Land the shared peer contracts: types, error mapping, transport trait, fake transport and fixtures, registry/proxy/health skeletons, the AppState.peers and Config.peers seams, the ping and peers route stubs, and unit plus integration tests. No loops, no network, feature off by default.
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.
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-5-consolidator/) 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.