writing-plans

Writing Plans

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Save location

Save the plan to docs/plans/YYYY-MM-DD-<feature-name>.md.

Global Constraints

Every plan needs a Global Constraints section in its header, before the first task — the project-wide requirements every task inherits: version floors, dependency limits, naming conventions, commit-message style, anything a task shouldn't have to restate. One line per constraint, with the exact value, not a vague pointer:

## Global Constraints

- Node >= 20
- Zero new runtime dependencies
- Commit messages: single-line, commitlint style, English

A task's own requirements are on top of this, not instead of it — every task implicitly carries the Global Constraints too. That's why parallel-execution dispatch hands each implementer the global constraints alongside its task brief: they're plan-wide, not per-task, so nothing downstream has to look them up separately.

Destination, fog, and out-of-scope

Three more optional header sections, alongside ## Global Constraints, before the first task:

## Destination

The gate can answer "is this run landable" without an operator reading any prose.

## Not Yet Specified

- How should finish report a phase whose reviewers disagreed?
- Does the map's coupling data belong in the gate at all?

## Out of Scope

- Replacing `.teammates/` with a real datastore — swapping it invalidates every check that
  reads it, and the coordination store is not what this destination is about.

All three are optional. ## Out of Scope requires a ## Destination with prose under it in the same document — an empty ## Destination heading is treated exactly like an absent one, because "out of scope" means beyond the destination, and a heading with nothing under it leaves that unjudgeable. This is the format's rule, defined in scripts/plan-sections.mjs; it is refused at the moment a run is created once init-run wires that module in, which has not happened yet — see below.