next phase
This commit is contained in:
1 parent
6387f4455b
commit
782e5dc440
14 files changed
+1280
-27
No files matched your search
+25
-7
@@ -11,15 +11,33 @@ Where other things live:
|
||||
| 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 [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>.md` (for example `plan/phase-5-alerting.md`).
|
||||
2. Fill in:
|
||||
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.
|
||||
- **Workstreams**: independent tracks with owned files, dependencies and done criteria, so they can run in parallel without merge conflicts.
|
||||
- **Open decisions**: questions that need a human call, each with options and a recommendation.
|
||||
- **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. Review and settle the open decisions in the plan file.
|
||||
4. 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).
|
||||
5. When the phase finishes, move the plan file (and any per-workstream notes) to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.
|
||||
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.
|
||||
Reference in new issue
Block a user