---
name: plan
description: Turn a development task into one work file in .work/ — goal, decisions, lanes with exact files and verification, done-criteria. Use for M and L tasks before writing code, and whenever a task needs a design decision, touches a persisted schema, an exit code, the extension contract or the collector, or will be split across subagents.
argument-hint: "[issue #N | task description]"
---
# Plan — one file, spec and plan together

Task: $ARGUMENTS

Write `.work/<yyyy-mm-dd>-<slug>.md` (git ignores `.work/`) from `.claude/skills/plan/TEMPLATE.md`.
One file replaces the
spec, the plan, the task briefs and the progress ledger. Target: under 150 lines. English.

## Before you write

1. **Find out, cheaply.** Send `scout` for "where does X live / who calls Y"; read yourself only
   what the design turns on. Check open issues, milestones, `docs/product-status.md` and
   `.work/` — the work may already be planned.
2. **Ask only what is the user's to decide** (product behaviour, what a user's CI will see, what
   is paid). Everything the code or the docs can answer, answer yourself. Put open questions at
   the top of the file and keep working on what does not depend on them.
   For an issue, fill the template's Issue section as `/work` § From an issue says: owner,
   milestone, linked PRs, release impact, and every acceptance criterion as a checkbox.
3. **Name the blast radius.** Which of these does the change touch? Each one adds a done-criterion:
   - a persisted document (run manifest, report envelope, baseline, lock file, profile, pack
     manifest, `schemas/`) → `schema_version` moves, a migration exists, the round-trip test
     covers the new field;
   - an exit code → `docs/exit-codes.md` and the design table say the same thing;
   - a CLI command or flag → its `docs/usage-*.md`, `docs/index.md`, `FEATURES.md`;
   - the extension contract (`Rule` / `Evaluator` / `Target`, an entry-point group, the pack
     manifest, the trace format) → every isolated example suite, run with `--no-cache`;
   - the collector → tenancy and authorization stated per route, PostgreSQL tests that refuse
     to skip in CI, the envelope still versioned;
   - a rule, evaluator or target → the `add-a-rule` checklist, `docs/generated/` regenerated;
   - a count or a capability claim in prose → generated by a script or cited with a source;
   - a script → a module docstring saying what it reads, writes and needs;
   - reader-facing wording → its own lane, reviewed as text.

## Design — only for a new capability or an L task

Before lanes, put two or three real alternatives in "Decisions", one line of trade-off each, and
pick one against the product principles in `CLAUDE.md`. When the design carries risk (a schema,
a contract, the collector, a milestone exit criterion), spawn `reviewer` on the WORK FILE as a
challenger — "what breaks, what is missing, is this the simplest thing that works, where could
it report clean about something it never examined" — and answer its findings in the file before
any code. A design nobody tried to break is a draft.

## Lanes

Split only where files are disjoint. A lane is sized for one `coder` run: a behaviour, its files,
its tests, its verification command. For each lane give: **files** (exact paths, with anchors
where it helps), **change** (behaviour, not implementation diary), **tests** (what proves it —
including the negative case), **verify** (the scoped command), **owner** (`main` for
cross-cutting or subtle work, `coder` otherwise), **depends on**. Order lanes so the suite is
green after each one.

Wording a reader sees is never a coding lane: give it its own lane, say which page or prompt
receives it, and review it as text.

## Done-criteria (copy into the file, delete what does not apply)

- full gate green, verdict lines read: `scripts/ci_local.sh --quiet`
- the documented command run against a real or faked target, its artifact read
- reviewed (`/review`), findings fixed or answered
- the five documentation places answered in the same change (`/docs`)
- every acceptance box of the issue ticked with its evidence, or the issue left open
- work file deleted in the shipping commit; leftovers opened as issues

Show the user the goal, the decisions and the lane list in a few lines, then continue unless a
decision is genuinely theirs.