Files
skyg-linux-tracker/plan
ariandClaude Sonnet 5.5 6be774e98b H: mark merged
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 16:32:08 -04:00
..
2026-10-20 15:54:03 -04:00
2026-10-19 16:43:35 -04:00
2026-10-19 16:43:35 -04:00
2026-10-20 15:59:48 -04:00
2026-10-20 16:32:08 -04:00

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 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 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: add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of ../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.