Code Quality
19 documents
Architecture
Use MVVM with [CommunityToolkit.Mvvm](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/) — source-gener...
Completeness: finish the work, don't defer by default
Deliver the full agreed scope. Don't silently mark work out of scope, declare done prematurely, or invoke YAGNI to skip required work.
Dependency Injection
Constructor injection via `Microsoft.Extensions.DependencyInjection`. Use interface types for dependencies, not concr...
File paths
Use `pathlib.Path`, not `os.path`. All path manipulation should go through `pathlib`.
Hilt dependency injection for Android
Use Hilt with KSP and constructor injection for Android DI; scope bindings to the correct Hilt component and reserve @Singleton for app-scoped state.
Linting before the first PR
All projects MUST have linting configured and passing before the first pull request.
Naming
- `PascalCase` for types, methods, properties, public fields, constants, namespaces
No external dependencies in core libraries
`roadmap_lib` uses the standard library only. Do not add PyYAML, requests, or other third-party packages to core libr...
Nullable Reference Types
Enable `<Nullable>enable</Nullable>` in all projects. Treat warnings as design signals — `string` means non-null, `st...
Scope discipline
Only modify what was requested. State the goal before starting. Note but do not fix adjacent issues.
Shell scripts
Shell script `main()` functions must only call other functions — no inline logic. Keep scripts composable and testable.
Small, atomic commits
One logical change per commit. A change may touch multiple files if they are part of the same concept. Commits should...
Type hints
Type hints are welcome but not required. Maintain Python 3.9 compatibility — use `from __future__ import annotations`...
TypeScript strictness configuration
Set strict: true on every new TypeScript project and adopt the stricter index/module flags incrementally.
Use roadmap_lib
Use functions from `roadmap_lib` for all roadmap operations (reading state, parsing frontmatter, finding steps, etc.)...
Value objects over primitive obsession
Wrap domain primitives that carry invariants in small immutable value objects so validation lives in one place and invalid instances cannot be constructed.
Verification harnesses as agent guardrails
Give every agent a runnable pass/fail check it can run on itself, and enforce correctness through deterministic gates rather than prompt text.
Writing code for the AI reader
Favor explicit, greppable, locally-readable code so AI agents can find and modify behavior on the first pass — without sacrificing human readability.
YAML frontmatter
Parse YAML frontmatter with the built-in frontmatter parser in `roadmap_lib`. Do not add a PyYAML dependency. The par...