# Plan It

> Turn a fuzzy idea, brain-dump, or transcription into a COMPLETE spec set + agile delivery package for /build-it. /plan-it plans it, build-it builds it: pre-grounds the codebase, fans out parallel Claude teams, authors design docs in order, runs one up-front anamnesis questionnaire (access, fences, naming, topology, live-probes, known decisions), pauses at ONE batched human-decision gate, then freezes a shared CONTRACT so squads write PRDs + epics — each ending in a BINDING Test Contract the build must pass 100% before "done". Picks a topology (solo · orchestrator+squads · headless) and renders an HTML twin of each doc. Use when the user says "/plan-it", "plan this", "spec this out", "create the PRDs/epics", "scope this project/feature", or pastes a vision expecting a buildable plan. Built for humans and conductor agents. Inverse of /build-it; predecessor to /next-session-prompt. Deterministic core: an explicit statechart (machine.json), a resumable state file, gate-check.mjs exit codes gate advancement.

- Skill: `devotts/plan-it` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add devotts/plan-it`
- Raw SKILL.md: https://api.skillmd.com/api/skills/devotts/plan-it/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: devotts (https://skillmd.com/u/devotts)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/devotts/plan-it

---


# plan-it

**Take a fuzzy demand → ship a buildable delivery package.** This is the planning
conductor: the disciplined front-half of the lifecycle that ends exactly where
`/build-it` begins. It does *discovery* (research the ground truth), *spec*
(author the design docs), and *agile split* (PRDs, epics, tests, the shared
contract) — then hands off.

```
  /plan-it  ─────────────►  docs/ + delivery/  ─────────────►  /build-it
  (discovery → spec → plan)   (the buildable package)            (builds it)
```

Usable by a human directly, and by any orchestrating **conductor** agent that receives a new
demand and must turn it into a delivery package before dispatching workers.

---

## The five non-negotiable rules (enforce these — don't just suggest them)

These are the load-bearing rules reverse-engineered from every successful run.
If you violate one, the build downstream drifts or silently fails.

1. **Freeze a shared CONTRACT before any parallel planning.** The CONTRACT is the
   law: canonical entities, schema, API/interface, enums, repo/branch map, and the
   definition of "shipped." Squads write *to* it; any cross-cutting discovery folds
   *back* into it as a dated amendment (v1.0 → v1.1 …). No frozen contract → no
   parallel squads.

2. **Batch every human-only decision into ONE gate.** Do not pre-decide anything
   irreversible (repo topology, hosting, product name, architectural mode, build-vs-buy).
   Surface them together, each with a *recommendation attached*, and let the human
   answer numbered. This gate is where the human injects **vision**, not just picks
   options — leave room for them to add a concept you didn't propose. Lock each
   answer with **owner + date**.

3. **Verify every agent's output on disk — "idle ≠ delivered."** A team going idle
   does NOT mean it wrote files. After any fan-out, check the actual paths exist and
   are non-empty before proceeding. If a team held its output as a message, direct
   it to `Write` to the exact absolute path. Never trust a "done."

4. **Ground the plan against the LIVE system, not the repo — before you freeze.**
   For any plan touching a running system, the repo is a *hypothesis*; the deployed
   reality is the truth, and they drift. Before freezing the CONTRACT, verify against
   the actual system and write the *observations* in (not repo-derived guesses).
   Battle-tested: in one program EVERY mid-flight correction traced to a repo-inferred
   assumption reality contradicted — wrong canonical identifiers (manifests had drifted
   from the deployed catalog), a config value that was present-but-pointing-at-a-dead-host,
   "to-be-built" components that were already deployed, and a found credential that was
   the *wrong* one. See Phase 3's live-grounding gate for the concrete checks.

5. **Run the machine, not the prose.** The pipeline's control flow lives in
   `machine.json` (the explicit statechart), not in this document — this prose
   *explains* the machine. On invocation, read or initialize `.plan-it/state.json`
   (in the target project) and resume from its `state`; write it on **every**
   transition. At every guarded transition, run the guard's mapped subcommand
   (`node scripts/gate-check.mjs <check> …`) and **never advance on a non-zero
   exit** — fix, re-run, then transition. If Node is unavailable, perform the same
   checks manually and record them in the state file (degrade, never break). Full
   protocol: `references/machine.md`.

---

## The deterministic core (v2) — why a machine

Control flow written as prose ("do step 1, never skip the gate") is what the
determinism literature calls **prose control flow**: it relies on the model's
discipline across a long, summarization-prone context, and sometimes the model
won't follow it. v2 inverts that at the right altitude — *non-determinism at the
edges, determinism at the core*:

- **`machine.json`** — XState v5-compatible statechart of the pipeline: 25 states
  (17 baseline + 8 new in v4), the human gates across both modes (`meta.gate` +
  `meta.human`: G0–G4), guarded transitions, and an
  `AMENDMENT` self-loop on `parallelPlanning`. Paste into stately.ai/viz to see it.
- **`.plan-it/state.json`** — the persisted run: current state, gate approvals
  (owner + date), contract version, verified-artifact registry, history. This is
  what makes a run survive a crash or a fresh session.
- **`scripts/gate-check.mjs`** — the guards as exit codes: `verify` (Rule 3,
  idle ≠ delivered), `freeze` (Rule 1, no contract → no squads), `handoff` (the
  mechanizable half of playbooks §F), `state` (Rule 2, gates recorded),
  `adversary` (Rule 6 / D4 — failure-mode depth: a modelled machine must cover-or-
  waive the five cascade classes; N/A for linear workflows). The `LINT_CLEAN` and
  `ADVERSARY_CLEAN` transitions (verify → adversaryGate → handoff) gate on the
  last two.

The fuzzy phases — discovery, synthesis, spec authoring, judgment — stay
LLM-at-the-node (tagged `llmAtTheNode` in the machine). Do not formalize them;
modeling is not ceremony only when it replaces confusion. Details, state-file
schema, and the resume protocol: `references/machine.md`.

**Hard enforcement (v2.1, plugin installs on Claude Code only):** a `PreToolUse`
hook (`scripts/hooks/planit-guard.mjs`) *denies* Write/Edit calls on PRD/epic
deliverables while the run's contract is unfrozen — Rule 1 stops being an
instruction and becomes something the harness refuses. Fail-open: it never
touches non-plan-it work. Skill-only installs rely on Rule 5 discipline instead.

---

## The Test Contract — the quality differentiator (make this non-negotiable)

The single thing that most raises delivered code quality: **every PRD/epic ends by
generating its own test contract — up to ~20 concrete use-cases/scenarios that
stress the implementation — and the feature is NOT "done" until 100% of them pass.**
The build agent cannot just deliver the feature; it must satisfy the contract, and
`/iterate` until green.

This is a named, proven discipline: **Specification by Example** (Gojko Adzic) +
**ATDD/BDD** for code (concrete examples become executable acceptance tests and
living documentation), and **Eval-Driven Development** for skills/LLM features
(register goldens with expected outputs, iterate until they pass). Authoring the
cases *at planning time* is the whole point — they become a binding contract, not
an afterthought.

Rules of the Test Contract:
1. **Authored at planning time** — the LAST step of writing each epic/PRD is its
   test contract. Expected outputs are **registered now** ("designed first; expected
   outputs registered"), not discovered mid-build.
2. **Up to ~20 high-quality cases** per feature — enough to stress real behavior +
   edges; *not* thousands of shallow ones (quality > quantity — auto-bulk = "slop",
   per the eval literature). Draw cases from real/likely failure modes.
   **Per-shape count rule:** large Shape-1 multi-squad programs hold a **≥10
   cases-per-epic floor** (each epic is a big feature); small shapes (single
   skill/feature, S/M) author **~20 cases total across the package** (a handful per
   epic). Never both at once — pick by shape so a reviewer doesn't flag a correct
   small package as under-tested.
3. **Binding** — DoD (Definition of Done) = **100% of the contract passes**; until then, `/iterate`. No
   partial ship; no VERIFIED-on-a-mock (a `[REAL]` case whose target is unreachable
   → IMPLEMENTED-NOT-VERIFIED, never a fake green).
4. **Pick the test types by implementation** (one or more of unit / e2e / use-cases
   / stress):

| Implementation | Test types | How |
|----|----|----|
| CRUD / REST API | use-cases (happy+edge) + e2e | run every scenario **via API** *and* **via UI with Chrome CDP** (`chrome-cdp-control`); unit-test the logic |
| Skill / prompt / LLM function | use-cases w/ **expected output** | run it, **compare real vs expected** — exact match for closed outputs, rubric / LLM-as-judge for open ones (`make-eval`, promptfoo, DeepEval G-Eval) |
| Agent / stateful / multi-step | **stress** scenarios + use-cases | six axes: async, fan-out, escalation, human-gate, recursion, cycle-guard (Setup/Expected/Pass) |
| Pure logic / library | unit + **property-based** | enumerated cases + invariants |
| Data pipeline / migration | golden-value + e2e | hand-computed expected values; idempotency/rollback |
| Anything with load/abuse surface | **stress / adversarial** | concurrency, rate, malformed input, red-team |

5. **Execution path:** `/full-qa` runs the contract, `/iterate` loops it to 100%,
   `chrome-cdp-control` drives UI scenarios. **The contract is the bridge from
   plan-it → build-it: `/build-it`'s Definition of Done = this contract.**

Grammars and the contract header format: `references/formats.md` (the Test Contract
block + §4–5).

---

## Autonomy posture — guided mode

Run research and authoring autonomously at high effort, but **stop at three gates**:

| Gate | Machine state | When | What you ask |
|------|---------------|------|--------------|
| **G1 — Scope** | `scopeGate` | after intake (Phase 2) | confirm the sizing (feature vs program) + the numbered DoD before burning effort |
| **G2 — Decisions** | `decisionGate` | after specs drafted (Phase 7) | the batched "decisions only you can make," each with a recommendation |
| **G3 — Delivery** | `freezeGate` | before the agile split (Phase 8) | "specs look aligned — proceed to PRDs/epics?" |

`scopeGate`, `decisionGate` and `freezeGate` are the exact `machine.json` state
names for these three gates (CONTRACT §3.1) — never renamed. Everything between
gates runs unattended. Recommend `/effort xhigh` at the start (you cannot set
it yourself — tell the user to run `/effort xhigh` if they haven't).

## Autonomy posture — autonomous-draft mode

The default mode (ruling R1). Fewer stops — one up-front questionnaire, one
review-and-contradict round at the end — with every irreversible-but-guessable
call applied as a marked, contradictable default in between:

| Gate | When | What you ask |
|------|------|--------------|
| **G0 — Anamnesis** | at intake, before Phase 1 | the one up-front questionnaire: access & credentials the run may probe, fences, naming conventions, topology preference, live-probe authorization, decisions already known |
| **G1 — Scope** | after intake (Phase 2) | confirm the sizing + numbered DoD — same as guided mode |
| **G4 — Plan review** | after `adversaryGate`/`render` | the single PLAN-REVIEW round: every `[default — contradict if wrong]` decision plus the frozen backbone, reviewed together — replaces guided mode's separate G2 + G3 stops |

`anamnesis`, `scopeGate` and `planReview` are the exact `machine.json` state
names (CONTRACT §3.1) — never renamed. A contradiction at G4 that changes the
CONTRACT re-enters `parallelPlanning` as an `AMENDMENT` and runs the
verify → adversaryGate → render → planReview loop again.

---

## Output discipline for humans

**First-use rule (G-8):** every acronym or per-run ID this run mints or reuses
is expanded on first use in any human-facing surface — a decision-round table,
a KICKOFF doc, a launch prompt. Every package carries `GLOSSARY.md`; an ID used
in a package but absent from its glossary row fails `gate-check handoff`.

**Legend line:** wherever three or more per-run ID prefixes (governance rules,
test cases, waves, defaults, rulings) appear together in one artifact, carry
this line verbatim so a reader never has to guess which grammar an ID belongs
to:

```
Legend: G-n governance rule · T-<EID>-NN test case · Wn wave · Rn default · Dn ruling — see GLOSSARY.md
```

This is a legend line, never a renamed ID grammar — the fix for a `G1`-vs-`G-1`
or `W0`-vs-`W1` collision is one line of disambiguation, not a format change.

---

## Phase 0 — Intake

**Machine first (Rule 5):** if `.plan-it/state.json` exists in the target project,
run `node scripts/gate-check.mjs state .plan-it/state.json` and **resume from the
printed state** — do not restart phases already in `history`. If it doesn't exist,
create it now in state `intake` (schema in `references/machine.md`) and keep it
updated on every transition for the rest of the run.

Accept the demand in whatever form it arrives: a brain-dump, a pasted
transcription, a list of wants, or a one-liner. **Expect pointers, not content** —
session names (`/read-chat "<name>"`), repo paths, doc folders. Your job is to go
fetch the ground truth, not to be handed it.

Capture up front:
- **The raw vision** in the user's own words (you'll quote it back in `02 §1`).
- **Pointers** to prior sessions / repos / docs to research.
- **Use-case** (auto-detect — this drives the packaging shape at Gate G1):
  - new single app, greenfield · feature on a large existing repo ·
    from-scratch multi-subsystem program · multi-app platform (many PRDs) ·
    refactor / migration / debt · research spike (no build yet) · PM/board
    automation · document/audit an already-built system.
- **Research method**: default to parallel Claude teams at xhigh.

If the demand is genuinely one fuzzy paragraph with no pointers and an existing
repo, that's fine — pre-grounding (Phase 3) will find the targets.

### Anamnesis — gate G0

Immediately after capturing the raw vision above, and before Phase 1's DoD
lock, run the one batched **anamnesis** questionnaire — everything the run
needs from the human up front, asked once instead of dribbled out gate by
gate:

1. **Access & credentials** the run may probe (repos, live systems, secrets vaults).
2. **Fences** — what's out of bounds (files, systems, decisions not to touch).
3. **Naming conventions** — repo/branch/doc naming the run should follow.
4. **Topology preference** — `solo` · `orchestrator+squads` · `headless` (or "recommend one" and get a yes).
5. **Live-probe authorization** — is the run allowed to hit live systems/credentials (Rule 4), or stay read-only/repo-only.
6. **Decisions already known** — anything the human has already decided, so the run doesn't re-litigate it at a later gate.

Record the answers as `gates.G0` in `.plan-it/state.json` (the `G0_ANSWERED`
transition is guarded by `gateRecorded`) and machine-transition into state
**`anamnesis`** (CONTRACT §3.1 — this is the exact state name; do not invent
another). The answers seed Phase 1's Assumptions list and, where topology
warrants it, `DECISIONS.md`'s Ruled table directly — this is intake
enrichment, not a new decision round.

---

## Phase 1 — DoD lock

Restructure the fuzzy prose into a **numbered, individually-verifiable Definition
of Done** + a short list of stated assumptions. This is your contract with the
user for the planning job itself. Example shape:

```
DoD for this planning run:
  1. Ground-truth findings doc (every claim → path:line or table)
  2. Vision + architecture doc that solves each finding/contradiction
  3. Data/interface contract
  4. … (auto-sized — see Phase 2)
  N. Handoff: contract frozen, PRDs+epics with ≥10 tests each, kickoff prompt
Assumptions: <list>
```

---

## Phase 2 — Scope & shape governor  ⏸ GATE G1

Pick **size** (how much), **shape** (what form), *and* **topology** (how it's
run) before spending effort. Confirm all three with the user.

**Size** scales the artifact count:

| Signal | Size |
|--------|------|
| Single feature, 1 subsystem | **S** |
| Multi-feature / new subsystem, 1–2 repos | **M** |
| From-scratch program / many subsystems | **L** |

**Shape** is chosen by use-case (full definitions + the use-case→shape table in
`references/templates.md` PART D):

1. **Multi-doc + `delivery/`** (baseline) — from-scratch program, parallel squads.
2. **Single-file PRD-as-everything** — greenfield single app; CONTRACT inlined as G-rules.
3. **Research → locked-architecture → master+phase PRDs** — feature on a large existing repo.
4. **`implementation/<name>/` with numbered PRD-NN** — multi-app platform, many PRDs.
5. **Refactor/debt workstream catalog** — brownfield in-place.
   (+ research-spike, executable-board, and reverse-doc modes — see PART D.)

**Topology** decides how the run is executed, independent of size/shape
(CONTRACT §1; ruling D4 — the human picks, plan-it's recommendation shown):

| Signal | Topology | Recommendation |
|--------|----------|-----------------|
| Small/solo feature; one agent can hold the whole plan in context | **solo** | run single-threaded, no fan-out |
| Program-sized work with disjoint repo/file lanes, parallel squads needed | **orchestrator+squads** | one orchestrator + a worktree per squad (G-10 worktrees-only) |
| No human present to answer a chat gate — scheduled or unattended | **headless** | autonomous-draft mode; `--open` suppressed; decisions default-applied and reviewed at G4 |

Same phases regardless — only the artifact count and form change. **Don't give a
feature a 4-squad org; don't give a brownfield refactor a greenfield vision doc.**
Present the **SCOPE-BRIEF** (what each size/shape/topology produces, costs, and
is wrong for — skeleton in `references/templates.md`), then the chosen size +
shape + topology + the numbered DoD and get a yes before proceeding. On yes,
record `G1 = {approved, owner, date}` plus the chosen size/shape/topology in
`.plan-it/state.json` — the `G1_APPROVED` transition is guarded by `gateRecorded`.

---

## Phase 3 — Pre-ground

Before any fan-out, locate exact targets so agents get precise paths, not vague
instructions:
- Resolve pointer sessions with a session-reading skill (`/read-chat` or similar)
  if one is installed; otherwise ask for the relevant transcript or summary.
- `ls`/`grep` the named repos; find the `docs/`, schema files, entry points.
- Read the wiki hot-cache/index if the repo is vault-wired (per its `CLAUDE.md`).

Output: a list of `{subsystem → exact paths to read}` that seeds the research teams.

### Live-grounding gate (rule 4) — when the plan touches a RUNNING system

The repo tells you what *should* be true; the live system tells you what *is*. Do this
before Phase 8 freeze, and write the findings into the CONTRACT as observed facts:

- **Config reachability, not presence.** For every env/config lever the plan depends on
  (base URLs, API hosts, feature flags), *hit it* — don't just confirm it's set. A value
  can be set to a dead host and pass a "does it exist" check while silently breaking prod.
- **Live registry / canonical identifiers.** Dump the actual slugs / IDs / enum values the
  running system uses (integration slugs, catalog rows, schema). Repo manifests drift from
  the deployed catalog — bind the CONTRACT's canon to the LIVE value, not the manifest.
- **Deployed vs installed vs in-use.** Inventory what's already running, what's registered,
  and what's actually used by a tenant/user. "Build & deploy X" is often "redeploy X," and
  a component that's deployed-but-uninstalled cannot be live-verified per-item — which
  changes both verification depth and priority. Tag each target.
- **Credential validity, not existence.** A found key/token ≠ a correct one. If a plan
  relies on a credential, verify it actually works (a live call), and confirm ownership —
  a leftover token from another account will pass structural checks and fail at runtime.
- **Derive dependency sets from ACTUAL usage, cross-checked live.** Build the integration/
  dependency list from `code-grep ∪ every component's declared requirements`, intersected
  with the live registry — then list the *gaps* as explicit work. A list derived from a
  subset or from repo manifests will miss things the running system actually needs.
- **Separate "our code change" from "external connection/config/data seeding."** The code
  change is usually the easy, ownable part; the real blocker is often an external OAuth
  connection, a seeded secret VALUE, or an ops action — and it belongs on the critical path
  with an owner, not buried as a footnote.

Two build-time corollaries worth encoding in the CONTRACT/epics so the builder inherits them:
map a caller/consumer surface **before** planning any auth-guard or interface change (a
guard that breaks N callers is worse than no guard); and any repo *import* must be a
full-tree secret-scan + runtime-only subset, never a history mirror.

---

## Phase 4 — Discovery (autonomous burst)

Pick a **discovery mode** by use-case (full playbook in `references/playbooks.md` §A):
- **Solo read** — small feature, one subsystem.
- **Parallel research streams** — research-heavy: N agents, one *concern* each, each
  writes a cited `research/stream-<X>.md`.
- **Team-of-N codebase slices** — large codebase: N agents, one *non-overlapping
  slice* each, with explicit teammate-boundary notes.
- **Verify-then-extend** — brownfield/refactor: confirm every claimed gap against
  live code **with file:line** before it enters the spec, then sweep for new issues
  (see playbooks §B).

Shared mechanics for any fan-out:
- **Pre-ground first** — find the chokepoint/exact paths so agents don't work blind.
- **Shared-context contract** — write `research/SHARED-CONTEXT.md`, the one file
  every agent reads before working (Guardrail 1 for research).
- **Fixed report skeleton** + **skeptic posture** ("be criterious, cite path:line").
- **Stage findings to disk immediately** (`_research/NN-<slice>.md`) so nothing is
  lost to summarization.
- **Tell each agent: "you MUST run the tools and return findings; do not stop early."**
- **Apply Rule 3 — pull idle teammates.** After fan-out, run
  `node scripts/gate-check.mjs verify <every expected output path>` — the
  `FANOUT_COMPLETE` transition is guarded by it. On failure, `SendMessage` any
  silent agent to deliver; **re-dispatch any team that did 0 work** (this happens —
  caught and recovered live during the skill's own build-out). Record each passing
  artifact in `.plan-it/state.json` → `artifacts`.
- **Adversarial reconciliation** — when agents contradict, adjudicate in synthesis;
  don't average.
- **Independently verify the centerpiece** yourself rather than trust the team blind.

Use the `Agent` tool (`Explore`/`general-purpose`), or `/build-it`'s team machinery
for larger runs. Keep all *synthesis* single-threaded in the main thread.

---

## Phase 5 — Synthesis + memory

Merge the team reports into `docs/01-current-state-and-findings.md` (every claim
traceable to `path:line` or a table). Capture a project memory file so the thread
survives context loss (per the memory rules in your environment).

---

## Phase 6 — Spec authoring (autonomous burst)

Author the design docs **in dependency order** (skeletons in
`references/templates.md`). For size L the canonical arc:

1. `01` Current state & findings — diagnosis (contradictions/tensions, evidence)
2. `02` Vision & architecture — principles that solve each contradiction + the shape
3. `03` Data model & contract — canonical entities, schema, interface, migration
4. `04` [domain] organization — the durable/human layer (if there is one) *(optional)*
5. `05` [components] — deep-dive each major component: verdict, keep/discard/build, cost
6. `07` [organizing pattern] — the composability metaphor + "add a node" playbook *(optional)*
7. `06` Roadmap & open questions — phased plan, first vertical slice, risks, the decision list

Methodology to honor while authoring:
- **Model the confusing parts — including the failure half** — when discovery
  surfaced a workflow that is multi-step, approval-gated, agentic, concurrent, or
  retry/escalation-laden, the spec MUST include an explicit model of it (statechart,
  state-transition table, or equivalent — a given/when/then transition list is
  enough), and the epics that build it reference the model. The CONTRACT carries
  these under "Core-logic models." Only the confusing parts — modeling is not
  ceremony when it replaces confusion, and only then. **A model is not just the
  happy path**: name at least one failure state and one recovery/compensation
  transition out of it, or the downstream Test Contract has no depth to reach for.
  `gate-check adversary` (D4) enforces this at the `adversaryGate` state — the five
  cascade classes (partial-failure, rollback/compensation, failed-recovery→
  escalation, recovery/resume, adversarial-verify) must each be covered-or-waived.
  A genuinely linear workflow declares no machine and the gate is N/A (no over-reach).
- **Never greenfield when code exists** — every doc shows what's already built and
  how to *promote* it (mapping tables), not just what's new.
- **Contradiction-driven** — start from pain (01), derive principles (02),
  operationalize them everywhere after.
- **Evidence-based** — cite code, not intuition.
- **Risk-honest** — name rate limits, fidelity gaps, failure modes explicitly.
- **User-voiced** — restate the wants in the user's own language; map architecture
  back to each want.

Route per the repo's `CLAUDE.md`: code-adjacent docs → repo `docs/`; project
decisions/sessions → the vault.

---

## Phase 7 — Decision round  ⏸ GATE G2 (guided mode)

Collect every genuine judgment call into a single **"Decisions only you can make"**
section — written to **`DECISIONS.md`** (skeleton in `references/templates.md`),
not only inline in the roadmap doc `06 §4`. For each: state it, attach a
**recommendation**, but **do not pre-decide** the irreversible ones. Present them
numbered. The user answers numbered.

Then:
- **Lock** each answer into `DECISIONS.md`'s Ruled table, marked "locked," with
  **owner + date** — and record `G2 = {approved, owner, date}` in
  `.plan-it/state.json` (`G2_ANSWERED` is guarded by `gateRecorded`).
- If the user introduced a *new concept* (they often do here), thread it through —
  add/rewrite the affected doc (e.g. a new `07`) and **run a coherence pass**
  (grep for now-stale terms the new decision invalidated; fix them).

**Autonomous-draft mode:** this phase's chat stop is skipped — see "Phases 7 + 8
collapse into PLAN-REVIEW" at the end of Phase 8.

---

## Phase 8 — Backbone freeze  ⏸ GATE G3 (guided mode)

Ask "specs are aligned — proceed to the delivery package?" On yes, write the
backbone **first**, because squads build their PRDs against it:

1. `delivery/CONTRACT.md` (frozen v1.0) — vocabulary, schema, verbs/interface,
   primitive interface, enums/literals, repo ownership + branch rules, definition
   of "shipped," changelog.
2. `delivery/00-program-plan.md` — squads, epic backlog, waves, test standard,
   branching, the build-it runbook, the board pointer.
3. `delivery/STATUS.md` — the live board, all epics in backlog.

(For size S/M, fold these into fewer files — a contract section + a single plan.)

Record `G3 = {approved, owner, date}` on the user's yes. Then, before any squad
fan-out, run `node scripts/gate-check.mjs freeze delivery/CONTRACT.md` (or the
file carrying the inlined contract section) — the `CONTRACT_FROZEN` transition is
guarded by it, and Rule 1 is now an exit code, not a plea. Record the contract
version + path in `.plan-it/state.json` → `contract`.

### Autonomous-draft mode — Phases 7 + 8 collapse into PLAN-REVIEW

`specAuthoring` transitions straight to `defaultsApplied`
(`SPECS_DRAFTED_AUTONOMOUS`): every decision from Phase 7's list gets plan-it's
own recommendation applied and written into `DECISIONS.md`, each marked
`[default — contradict if wrong]` inline — **no chat stop**. `coherencePass`
still runs the same coherence check as guided mode, and `COHERENT_AUTONOMOUS`
transitions straight to `backboneFreeze`, which freezes the CONTRACT as a
**draft** (`freeze --draft`, ruling R1) instead of stopping for G3. Both rounds
are reviewed together, once, at gate **G4** — Phase 10's `planReview` — where
any default can still be contradicted before the CONTRACT becomes final.

---

## Phase 9 — Parallel planning (autonomous burst)

Fan out **one squad team per repo lane** (disjoint files — no co-editing). Each
writes its `prds/prd-N-*.md` + `epics/epics-N-*.md` **against the frozen CONTRACT**.
When topology = `orchestrator+squads`, record each squad's session name in SESSIONS.md as it's dispatched —
the orchestrator's only way to find and message a squad again is by that name (G-10).

- **PRD** per squad: summary, problem & goals, users & jobs, solution design
  (numbered decisions D1–DN, citing `file:line`), epics table, acceptance criteria,
  risks, repo/branch plan.
- **Epics** per squad: per epic — branch (`epic/<EID>-<slug>`), deps, scope, task
  checklist (file:line scoped), then **— as the LAST and load-bearing step — the
  Test Contract**: up to ~20 type-selected use-cases/scenarios with expected
  outputs registered (see "The Test Contract" above and `formats.md`). DoD = 100%
  of the contract passes. This is the heart of the epic, not a footnote.

**Amendment loop:** squads grounding in real code will surface cross-cutting
integration issues *before any code is written* — fold each back into `CONTRACT.md`
centrally (v1.0 → v1.1 …) so squads can't drift. This is the contract doing its job.

**Scaling the fan-out** (when there are *many* PRDs, not 4 fixed squads): use the
**parallel-batch generator** (playbooks §C) — a `features.json` work-breakdown
(one row per PRD), subagents spawned in review-gated batches, the same
template+glossary *injected into every subagent* for coherence, and a
cross-PRD consistency lint after the fan-out. PRD numbering `PRD-NN` where NN =
dependency order.

**Optional executable split** (playbooks §D): instead of (or beside) `epics/*.md`,
emit the breakdown onto a live GitHub Projects board via a `ghp.sh` helper
(epic = parent issue, tasks = native sub-issues, status single-select; GitHub is
source of truth, `tracker.md` a cache). Offer this when the user wants a live board.

Apply Rule 3 after the fan-out — `node scripts/gate-check.mjs verify prds/ epics/`
(the `SQUADS_COMPLETE` transition is guarded by it). Each `AMENDMENT` bumps the
contract version in `.plan-it/state.json` (v1.0 → v1.1 …) and stays in
`parallelPlanning` — the machine's self-loop.

---

## Phase 10 — Verify + handoff

- **Enforce the Test Contract gate:** every epic carries its contract (up to ~20
  type-selected cases, expected outputs registered); tally the totals; flag `[REAL]`
  cases (those needing a live target). DoD = 100% pass via `/full-qa` + `/iterate`.
  No `[REAL]` case may be marked VERIFIED on a mock — unreachable target →
  IMPLEMENTED-NOT-VERIFIED, never a fake green.
- **Run the mechanizable lint first:** `node scripts/gate-check.mjs handoff delivery/`
  — the `LINT_CLEAN` transition is guarded by it. It checks ID grammar, declared-vs-
  counted case totals, `[REAL]` tallies, per-epic Test Contract presence, and token
  lint. The judgment half below still needs you.
- **Then run the adversarial-depth gate:** `node scripts/gate-check.mjs adversary delivery/`
  — the `ADVERSARY_CLEAN` transition (verify → adversaryGate → handoff) is guarded by
  it (D4). When the CONTRACT declares a state machine, it enforces failure-mode depth:
  the machine models failures + recovery, every declared failure state is an asserted
  case, and the five cascade classes are covered-or-waived. Linear workflows: N/A, passes.
- **Run the pre-handoff consistency gate** (`references/playbooks.md` §F) — the lint
  that makes a package build *unattended*: counts add up (count tags, don't hand-type);
  every goal & governance rule has a test; the CONTRACT verb/API surface reconciles
  with what's "kept" and what's tested; **if the tool parses its own artifacts, round-trip
  the grammar over the generated sample**; every diff/sync verb declares live-vs-cached
  reads; every "never X" invariant has an inverse-op test; IDs/dep-graph coherent across
  files; token lint. Fix and re-lint until clean. (These are the exact defect classes a
  dry-run shipped — don't hand off without it.)
- **Assemble:** `delivery/README.md` (index) + `delivery/KICKOFF.md` (orientation:
  one-liner, first slice, repo map, locked decisions, gotchas, handoff state).
  When topology warrants it, add `SESSIONS.md` (squad session names), `GATE.md`
  (the answered decision/authorization/owner-action log) and `GLOSSARY.md` (the
  static seed plus every ID this run minted) to the file list. KICKOFF is
  *generated*, never copied stale: it MUST open with the "0. Pinning"
  block (absolute repo path @ full git SHA, `.plan-it/state.json` path, CONTRACT
  SHA-256) and make "re-derive tally + reconcile from disk, stop-and-report on
  mismatch" the builder's first numbered step (`references/templates.md`
  KICKOFF block, PRD §D4–D5).
- **Every twin is local, not a published artifact:** each md file's `<NAME>.html`
  twin is rendered and created locally by default, and is never published as a
  claude.ai artifact; it is opened (`--open`) only at human gates, and that
  opening is suppressed entirely in headless runs (G-7 prose).
- **Residual-disposition pass** (before filling the board): for every epic whose
  Test Contract is not 100% passing, tag each non-green case one of
  `backlog-with-reason` · `owner-gated` · `IMPLEMENTED-NOT-VERIFIED`, and record
  it in `STATUS.md`'s Disposition column. A binding contract case may never move
  to `backlog-with-reason` — it stays `IMPLEMENTED-NOT-VERIFIED` with a reason
  instead; only work beyond the case set may go to backlog (G-9).
- **Fill the board:** `STATUS.md` rows reflect Wave-0 in-progress, rest backlog.
- **Hand off** (the terminal phase — the build runs in a *fresh* session):
  - Wire the repo to your knowledge base (`/sync-obsidian` or equivalent), if your
    environment has one.
  - Capture a session debrief (`/session-debrief` or equivalent) — session note,
    reusable patterns, memory.
  - Produce the launch handoff (`/next-session-prompt`, or author it directly) —
    the KICKOFF doc **and** the exact copy-paste launch
    prompt (this is the `sample-prompt-prd.txt`-style artifact that `/build-it`
    consumes). Done.
- **Optional handoff enrichments** (playbooks §E): a `README.md` consolidation hub
  (reading-order table + decisions-in-one-screen + GATING items); a `KICKOFFS.md`
  archiving the launch prompt per PRD/phase; a `DELIVERY-LOG.md` truth board; and
  for large PRDs, an initial slice + a later `-CONCLUDE` run to close deferred
  IMPLEMENTED-NOT-VERIFIED items.

Final report to the user: per-doc + per-epic status, total test count, the
locked decisions, and the launch prompt.

---

## Composes with

- **[`/build-it`](https://github.com/DevOtts/build-it)** — the build engine `plan-it` feeds. The handoff prompt targets it.
- **`/read-chat`** (optional) — resolve pointer sessions in pre-grounding.
- **`/sync-obsidian`, `/session-debrief`, `/next-session-prompt`** (optional) — the
  handoff trio; degrade to inline equivalents when absent.
- **Agent / Claude teams** — the research (Phase 4) and squad (Phase 9) fan-outs.

## References (read the one you need before authoring)

- **`references/machine.md`** — the deterministic core: `machine.json` explained,
  the `.plan-it/state.json` schema + resume protocol, `gate-check` usage, the
  degrade-gracefully rule, and the "model the confusing parts" output discipline.
  Read at Phase 0 (resume) and before every guarded transition.
- **`references/templates.md`** — doc + delivery skeletons (PARTS A–C) **and the 5
  packaging shapes + use-case→shape map (PART D)**. Read PART D at Gate G1 to pick
  the shape; read A–C before authoring.
- **`references/formats.md`** — the composable atomic formats (lego bricks): decision
  log, blocking-questions table, governance/invariant block, the 4 test-case
  grammars, test-tier matrix + coverage-map self-audit, typed task grammar + dep-graph
  DAG, the DoD ladder, the honest run-report / DELIVERY-LOG.
- **`references/playbooks.md`** — advanced moves: discovery modes (incl.
  verify-then-extend), brownfield/refactor templates (verdict tables, blast-radius,
  naming-first, schema-vs-data-migration), scale-out batch PRD generation, the
  executable GitHub-board split, and handoff enrichments.

---
_Authored by [DevOtts](https://github.com/DevOtts)._