44 lines
3.4 KiB
Markdown
44 lines
3.4 KiB
Markdown
# 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/<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 `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/<short-name>/` (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.
|