docs: establish staged feature planning workflow

This commit is contained in:
2026-09-07 17:14:21 +00:00
parent 0349682eb9
commit 4e861f1f3e
4 changed files with 155 additions and 22 deletions

View File

@@ -33,6 +33,8 @@ remotes.
## Sources of Truth
- `docs/roadmap/mvp.md`: settled MVP scope, architecture, and open design work.
- `docs/roadmap/features/`: durable scope and target state for selected units
of work.
- `docs/status.md`: current cross-repository progress and next work.
- `docs/decisions/`: durable rationale for significant architectural choices.
- `docs/plans/`: temporary implementation plans for substantial work.
@@ -68,10 +70,27 @@ link and a concise deployment consequence are sufficient.
- Update `docs/roadmap/mvp.md` when a design question becomes a settled scope
or architecture decision.
- Discuss and select the next unit of work before planning implementation.
- Give each selected feature a four-digit identifier and matching documents at
`docs/roadmap/features/<id>-<slug>.md` and
`docs/plans/<id>-<slug>.md`. Add the same identifier to `docs/status.md`.
- Write and agree on the feature roadmap before writing its implementation
plan. The roadmap owns scope, target end state, rationale, constraints, and
acceptance criteria.
- Write implementation plans as dependency-ordered stages suitable for
GPT-5.6-Terra to execute sequentially. Number stages with consecutive
integers beginning with `Stage 1`; do not skip numbers or use nested stage
numbering. Each stage must identify its repository, preconditions, required
behavior, validation, completion criteria, and expected commit.
- Resolve architectural choices during roadmap and plan review. Do not leave
unresolved design judgment to the implementation agent.
- Update `docs/status.md` when cross-repository work starts, becomes blocked,
or is completed. Completed items must point to concrete evidence.
- Create a file in `docs/plans/` only for work spanning multiple meaningful
steps or repositories. Remove or archive stale execution detail after the
work is complete; durable rationale belongs in `docs/decisions/`.
- Out-of-band implementation should commit each completed stage when that
stage leaves its owning repository valid. Review the implementation and its
validation evidence before marking the feature complete.
- Retain feature roadmaps as durable records. Remove or archive obsolete
implementation detail after completion; durable architectural rationale
belongs in `docs/decisions/`.
- Use the status values `proposed`, `ready`, `in_progress`, `blocked`, `done`,
and `deferred`.