3.5 KiB
3.5 KiB
Planning the next phase
plan/ is only for planning the next big piece of work, before it starts. It is empty of plans while the current board is clean. The Phase 5 plan is archived in ../docs/workstreams/P5-consolidator/.
Where other things live:
| What | Where |
|---|---|
| Work tracking and checkboxes | ../TODO.md (tick boxes only there) |
| Current design and decisions | ../ARCHITECTURE.md |
| Long-form docs | ../docs/ |
| Records of finished workstreams | ../docs/workstreams/ |
Phase folder layout
Each phase is a folder plan/<short-name>/ (for example plan/phase-6-example/) so workstreams can be worked in parallel by separate agents or people:
| File | Purpose |
|---|---|
README.md |
Phase overview: goal, scope, grounding in code, workstream index (ID, file, owner, depends on, can start when, owned files), dependency graph, parallel lanes, risks, verification, exit criteria |
contracts.md |
Shared interfaces (types, traits, fakes, REST/MCP/OTel shapes, config surface) that let streams start against fakes before their dependency lands |
decisions.md |
Open-decisions table and decision records |
ws-<x>-<name>.md |
One file per workstream: header table, goal, tasks, inputs, done when, handoff, log |
Rules:
- Do not touch: a workstream edits only the files in its "Owned files" row. Other streams' files are in its "Do not touch" row. For the few shared files (for example
src/state.rs,src/api/mod.rs,flake.nix) the header names the integration seam and which stream edits it first; prefer one stream wiring the seam up front so the rest only fill their own files. - Contracts change only through
contracts.md: edit it first, then add a dated note to the Log of every affected workstream file. - Claim a workstream by setting its
Ownerfield (name or agent id) and committing that change before starting; setStatusas you go. Do not start a stream whose "Can start when" is not met unless you work against the contracts and fakes. - Log progress, discoveries and handoffs in the workstream's own
Log(dated), not in other files.
Proposing a phase plan
- Copy the folder layout from
TEMPLATE.mdtoplan/<short-name>/(for exampleplan/phase-5-alerting/). - Fill in the phase
README.md:- Goal: what changes for users or operators, in a few sentences.
- Scope: what is in, and explicitly what is out.
- Workstream index and parallel lanes: independent tracks with owned files, dependencies and what can run from day one, so they run in parallel without merge conflicts.
- Exit criteria: how you will know the phase is done (commands to run, behaviour to demonstrate).
- Write
contracts.mdfor anything two streams share, anddecisions.mdfor questions that need a human call, each with options and a recommendation. If a stream would block on another, add a small first task that lands the shared stubs (for example a fake). - Review and settle the open decisions in
decisions.md. - When the plan is accepted, move the work into
../TODO.md: add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of../ARCHITECTURE.md. - When the phase finishes, move the whole phase folder to
docs/workstreams/as an archived record and collapse its tasks inTODO.mdinto the Completed table.