# 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`](../TODO.md) (tick boxes only there) | | Current design and decisions | [`../ARCHITECTURE.md`](../ARCHITECTURE.md) | | Long-form docs | [`../docs/`](../docs/README.md) | | Records of finished workstreams | [`../docs/workstreams/`](../docs/workstreams/) | ## Phase folder layout Each phase is a folder `plan//` (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--.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 `Owner` field (name or agent id) and committing that change before starting; set `Status` as 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 1. Copy the folder layout from [`TEMPLATE.md`](TEMPLATE.md) to `plan//` (for example `plan/phase-5-alerting/`). 2. 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). 3. Write `contracts.md` for anything two streams share, and `decisions.md` for 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). 4. Review and settle the open decisions in `decisions.md`. 5. When the plan is accepted, move the work into [`../TODO.md`](../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`](../ARCHITECTURE.md). 6. When the phase finishes, move the whole phase folder to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.