Files
skyg-linux-tracker/plan/README.md
T
2026-10-20 16:35:11 -04:00

44 lines
3.5 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. The Phase 5 plan is archived in [`../docs/workstreams/P5-consolidator/`](../docs/workstreams/P5-consolidator/README.md).
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-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 `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.