From 4e861f1f3e83bf5ddc559017625f5207f8654546 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 7 Sep 2026 17:14:21 +0000 Subject: [PATCH] docs: establish staged feature planning workflow --- AGENTS.md | 25 +++++++- README.md | 4 ++ docs/plans/template.md | 99 +++++++++++++++++++++++++------ docs/roadmap/features/template.md | 49 +++++++++++++++ 4 files changed, 155 insertions(+), 22 deletions(-) create mode 100644 docs/roadmap/features/template.md diff --git a/AGENTS.md b/AGENTS.md index caebb50..5e206ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/-.md` and + `docs/plans/-.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`. diff --git a/README.md b/README.md index 627355a..78692f2 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,11 @@ only workspace documentation, planning, and shared development utilities. development. - [`docs/roadmap/mvp.md`](docs/roadmap/mvp.md) records settled MVP decisions and open design work. +- [`docs/roadmap/features/`](docs/roadmap/features/) contains durable feature + roadmaps for selected units of work. - [`docs/status.md`](docs/status.md) records current cross-repository progress. +- [`docs/plans/template.md`](docs/plans/template.md) defines the staged format + used for out-of-band implementation. Run `./scripts/status` to see the branch and working-tree state of every repository in the workspace manifest. diff --git a/docs/plans/template.md b/docs/plans/template.md index 53c213d..629c690 100644 --- a/docs/plans/template.md +++ b/docs/plans/template.md @@ -1,37 +1,98 @@ -# Plan: +# Implementation Plan <ID>: <Title> Status: proposed -## Goal +Target executor: GPT-5.6-Terra -State the outcome this plan must achieve. +Feature roadmap: `docs/roadmap/features/<id>-<slug>.md` -## Non-goals +## Objective -List adjacent work that is intentionally outside this plan. +Summarize the implementation outcome. The feature roadmap remains authoritative +for scope, rationale, target end state, and acceptance criteria. -## Owning Repositories +## Execution Rules -List every repository this work may change and what each repository owns. +- Execute stages in numeric order. +- Number stages with consecutive integers beginning with `Stage 1`. Do not use + zero-based, decimal, nested, or nonsequential stage identifiers. +- Before each stage, confirm its preconditions and the working-tree state of + its owning repository. +- Preserve unrelated and pre-existing changes. +- Do not make unresolved product or architecture decisions during execution; + stop and report the decision required. +- Run every stage's validation before committing it. +- Commit each completed stage when it leaves the repository in a valid state, + using the commit intent specified by that stage. +- Do not begin a dependent stage after an earlier stage fails validation. -## Dependencies and Settled Decisions +## Starting State and Preconditions -Link applicable roadmap sections and decision records. Record prerequisites -that constrain implementation. +- List required branches, revisions, tools, dependencies, and prior features. +- Identify expected clean or intentionally dirty working trees. -## Acceptance Criteria +## Repository Scope -- Define observable conditions for completion. +- List every repository that may change and the changes it owns. +- List repositories that may be inspected but must remain unchanged. -## Implementation Sequence +## Stage 1: <Independently Verifiable Outcome> -1. Describe the first independently verifiable step. +### Objective -## Validation +State the single outcome delivered by this stage. -List the commands, tests, or inspections that demonstrate completion. +### Preconditions -## Progress +- List facts that must be true before editing begins. -Keep only concise current state and blockers here. Git history should preserve -obsolete execution detail. +### Owning Repository + +`<repository path>` + +### Required Changes + +1. Describe concrete behavior to implement, including relevant files or + components where known. +2. State invariants, compatibility requirements, and explicit exclusions. + +### Validation + +Run: + +```text +<exact validation command> +``` + +Expected result: describe the required observable outcome, not merely a zero +exit code. + +### Completion Criteria + +- List the evidence required before this stage is complete. + +### Commit + +Commit intent: `<type and concise purpose>` + +## Stage 2: <Next Independently Verifiable Outcome> + +Repeat the complete stage structure above. Add, remove, or split stages so +each is ordered by dependency, reviewable on its own, and small enough to +diagnose without repeating unrelated work. Continue with `Stage 3`, `Stage 4`, +and subsequent consecutive integers as needed. + +## Final Validation and Handoff + +- Run cross-stage and cross-repository validation required by the feature + roadmap. +- Confirm every changed repository is clean and identify all resulting commit + hashes. +- Summarize deviations from this plan, unresolved findings, and deferred work. +- Do not mark the feature `done`; implementation results require review first. + +## Progress Notes + +Keep only concise current state, completed stage references, and blockers here. +Git history and implementation commits should preserve detailed execution +evidence. diff --git a/docs/roadmap/features/template.md b/docs/roadmap/features/template.md new file mode 100644 index 0000000..12ecc40 --- /dev/null +++ b/docs/roadmap/features/template.md @@ -0,0 +1,49 @@ +# Feature <ID>: <Title> + +Status: proposed + +## Summary + +State the selected unit of work and the outcome it enables. + +## Problem or Opportunity + +Describe why this feature is needed and the current limitation it addresses. + +## Scope + +- List behavior and deliverables included in this feature. + +## Non-goals + +- List adjacent behavior intentionally excluded from this feature. + +## Target End State + +Describe the observable repository, deployment, and operator state after the +feature is complete. Keep this independent of the implementation sequence. + +## Repository Ownership + +Identify every repository involved and the durable responsibility each one +owns. Distinguish repositories that will change from read-only sources of +application contracts. + +## Constraints and Settled Decisions + +Link the MVP roadmap and applicable decision records. Record technical or +operational constraints that implementations must preserve. + +## Rationale and Alternatives + +Explain material tradeoffs and why the selected end state is preferred. Omit +this section when the choice is mechanical and needs no durable rationale. + +## Acceptance Criteria + +- Define observable, testable conditions required for feature completion. + +## Dependencies and Follow-up Work + +List prerequisites and explicitly deferred work without expanding this +feature's scope.