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) |