Draft Plan

---
name: draft-plan
description: "Produce a versioned plan under `.claude/plans/<slug>/v<N>.md` from the active spec for that slug, pinned to a specific spec version and presented for review (accept / edit / reject) before it is written to disk. Use when the user types /draft-plan or asks to plan out the implementation of a specced feature. Mode A only — never auto-fires."
---

# draft-plan

Run the `plan` flow — turn an active spec (or a degraded `--task` description) into a versioned, stepped implementation plan. Upstream of `/execute`; downstream of `/spec`. Plans pin to the exact spec version they were drafted against.

## When to run

- User types `/draft-plan`, `/draft-plan <slug>`, or `/draft-plan <slug> --task "<text>"`.
- User asks to "plan out", "break into steps", "draft an implementation plan" for a specced feature.
- After `/spec` lands, before `/execute`.

Do **not** auto-fire. For a one-sentence change, the triviality check (step 7) will short-circuit and tell the user to just do it.

## Forms

- `/draft-plan` (no slug) — resolve in this order: (1) if `default` is active in `.claude/specs/INDEX.md`, use it; (2) else if exactly one named slug is active, use it; (3) else list active slugs and ask.
- `/draft-plan <slug>` — read `.claude/specs/<slug>/` active version, write `.claude/plans/<slug>/v<N>.md`.
- `/draft-plan <slug> --task "<text>"` — degraded mode: no spec required, the text is the input. Slug still required for the output path. Use `default` for the no-decision case.
- `--quiet` — terse review gate: one accept/edit/reject prompt instead of an inline or outline walkthrough (step 9). Combinable with any form above.
- `--executor cheap` — **strict drafting mode.** Draft the plan for an executor that does not share this conversation and reasons less capably: every step self-contained, every judgment call closed at draft time (step 8b). Default is `--executor main` (this context executes; today's behaviour). Combinable with any form above.

## Procedure

1. **Locate the trees.** `$CLAUDE_PROJECT_DIR/.claude/specs/` and `.claude/plans/` (cwd fallback if env var unset). Lazy mkdir.

2. **Resolve the slug.**
   - Slug given → use it.
   - No slug, `default` is active in `.claude/specs/INDEX.md` → use `default`.
   - No slug, no `default` but exactly one other active spec → use it.
   - No slug, multiple active → list active slugs and ask which.
   - No slug, no specs → only valid with `--task` (which itself requires an explicit slug); otherwise stop with: *"No specs and no task description. Run `/spec` first or pass `<slug> --task`."*
   - **Stale INDEX** — INDEX.md names an active version whose file is missing on disk → stop with: *"INDEX.md points at `<path>` but the file is missing. Reconcile by re-running `/spec <slug>`, or pass an explicit path."*

3. **Resolve the input.**
   - Default: read the active version file (`.claude/specs/<slug>/v<M>.md` where M = active version per INDEX).
   - With `--task`: use the task text. Warn: *"No spec — running in degraded mode. For non-trivial work, run `/spec <slug>` first."*

   **Done-criteria gate** (default mode only — skipped with `--task` since no spec exists):
   - If the spec's frontmatter `done_criteria_provisional: true`, refuse to plan:

     > Spec `<slug>` v<M> has provisional done-criteria. Plans cannot be drafted against an under-specified spec — re-run `/spec <slug>` to firm up the done-criteria probe, then re-run `/draft-plan <slug>`.

   - If the spec's frontmatter has no `done_criteria` field at all (a legacy spec predating done-criteria), warn once and continue:

     > Spec `<slug>` v<M> predates the done-criteria field. Continuing in legacy mode — the plan will not echo or verify done-criteria. Recommended: re-run `/spec <slug>` to add criteria; the next plan version will pick them up.

   - Capture the `done_criteria` list (or empty list in legacy mode) for use in steps 8, 9, and the final synthesis step.

4. **Resolve the output version.** Look at `.claude/plans/<slug>/`:
   - If empty / does not exist → write `v1.md`.
   - Else → write `v<N+1>.md` where N is the highest existing version, and supersede the previous active plan per step 11.

   No `--evolve` / `--new` distinction for plans. Plans are cheaper than specs and always evolve as a new version against the same slug. If the user wants a fresh plan tree under a new slug, that's a `/spec <new-slug> --new` operation upstream.

5. **Prep.** Invoke `skills/prep/SKILL.md` with the spec topic / task text. Architectural rules must be loaded before steps are drafted.

   **Autonomy-contract check** (optional): if no autonomy contract is set for this work (no `active.md`, no kickoff from `/spec`), optionally ask one question — *"How autonomous should the execute run be — push to all criteria or MVP-and-stop, interrupt every step or only on forks?"* — and call [autonomize](../autonomize/SKILL.md) to record it, so `/execute` reads a calibrated cadence/stopping instead of the bare default. Skip when the spec already set a contract, the user gave a terse preference, or the default obviously fits. One optional question, never a gate — the explicit `/autonomize` command stays available.

6. **Discover.**

   ```
   {
     task_keywords: [<derived from spec / task>],
     scopes: [<detected language>, <detected domain>, "global", "project-<name>"],
     kind: ["architectural-rule", "decision", "lesson", "project", "codemap"],
     top_n: 20,
     render_bodies: true,
     include_recaps: false
   }
   ```

   Use codemap to resolve concrete paths. Do not guess paths — Glob / Grep / Read the repo if codemap doesn't cover the area.

7. **Triviality check.** One-paragraph spec + one-step change + no architectural risk → ask:

   > This looks small enough to skip plan/execute. Anthropic's rule: if you can describe the diff in one sentence, just do it. Want to proceed anyway? (y/N)

   Stop unless the user confirms.

8. **Draft steps.** Each step has:
   - Concrete goal (one line).
   - Files (concrete paths — flag unknowns in Notes and stop).
   - Outcome (what is true after this step).
   - Verification (specific command, test, or check).
   - **Serves criteria:** list of done-criteria index numbers from the spec this step contributes to (e.g. `[1, 3]`). At least one criterion per step. A step that traces to no criterion is a planning smell — flag and ask the user:

     > Step N doesn't trace to any done-criterion. Either the criterion is missing from the spec (re-run `/spec <slug>`) or the step is unnecessary (drop it). Resolve before continuing.

   - Optional tags: `[research]`, `[delegate]`.

   **Skip the "Serves criteria" field in legacy mode** (spec had no `done_criteria`) — there's nothing to map to.

   **Self-containment for delegated steps.** When a step is tagged `[delegate]` (or otherwise destined for a fresh subagent — see execute §3b), the executing agent does **not** share this conversation's context and cannot re-derive it. Such a step needs two extra fields so it stands alone:

   - **Current state:** the relevant *before* excerpt of what the step modifies — the actual code/config lines being changed (a few lines, cited `file:line`), not a paraphrase. For a new-file step, state "new file" and the directory it lands in.
   - **Exemplar:** a concrete path in the repo to follow as the convention anchor (e.g. *"mirror the structure of `src/services/auth-service.ts`"*). The subagent reads it to match local idiom instead of inventing one.

   Populate both only for `[delegate]`-tagged steps — they are noise on a step that runs in this context, where the conversation already carries that state. If a step is `[delegate]` but you cannot supply a concrete Current-state excerpt or an Exemplar path, that is a signal the step is under-specified for delegation: either Read the repo to fill them in, or drop the `[delegate]` tag and run it in-context. Do not delegate a step the plan can't make self-contained.

   The closing done-criteria assessment is **not** a plan step — it's post-loop infrastructure inside `/execute`, run after the last real step's verification passes. The plan declares what done means; execute checks it.

8b. **Strict drafting mode (`--executor cheap` only).** A cheap-tier executor is functionally a fresh subagent with weaker inference: it does not share this conversation, cannot re-derive intent, and will not notice that a step left something open. Strictness is therefore a function of *who executes*, and in this mode it applies to **every** step, not just `[delegate]`-tagged ones:

   - **Self-containment everywhere.** Every step carries the **Current state** excerpt and **Exemplar** path that step 8 requires only of delegated steps. The same failure test applies, now plan-wide: if you cannot supply a concrete before-excerpt and an exemplar path for a step, the step is under-specified for this mode — Read the repo and fill them in, or draft the plan for `main` instead.
   - **Judgment calls closed at draft time.** Anything the main context would have decided *while executing* — a name, a file location, which of two shapes to follow, whether an edge case is in scope — is decided **now** and written into the step as a statement, not a choice. "Pick a sensible name for the helper" becomes the name. A step whose text still contains a choice is not ready for a cheap executor.
   - **Commands spelled out.** Verification and any setup commands appear verbatim, not described ("run the test suite" → the exact command). The executor should never have to infer an invocation.

   State the cost honestly at the review gate: strict drafting reads more of the repo, produces a longer plan, and goes stale faster (excerpts pin file state at draft time). It pays off on mechanical-heavy plans — migrations, scaffolding, rename sweeps, test authoring — and loses on small or judgment-heavy ones. When the user passes `--executor cheap` on a plan that looks judgment-heavy, say so once and let them decide.

8c. **Classify each step: `[mechanical]` or `[judgment]`.** In strict mode every step carries exactly one of these tags; in `main` mode they are optional and purely informational. The tag is what `/execute` reads to decide where a step runs, so classify by what the step *needs*, never by its size:

   - **`[mechanical]`** — the step is fully determined by the plan text plus its exemplar. Renames, scaffolding from a pattern, config edits, boilerplate, porting an existing shape to a new file. Two readers following the step would produce the same diff.
   - **`[judgment]`** — the step contains something the plan could not close: a design decision, an ambiguous requirement, an unknown that must be discovered while working. Always runs in the main context.

   **The verification-shape gate (hard rule).** A step may carry `[mechanical]` **only if its Verification is command-shaped**, or artifact-shaped with the exact check written out (the literal Grep/Read, not "confirm the function exists"). User-attested verification never qualifies.

   The reason is worth stating, because it is the whole basis for routing work to a weaker executor: strict prose does not constrain a model, a failing command does. Everything else in strict mode raises the odds of a correct execution; only the verification catches an incorrect one. A step whose correctness cannot be checked mechanically must not be handed to an executor that is likelier to get it wrong.

   When a step is genuinely mechanical but its verification is user-attested, do not downgrade the verification to make the tag fit — tag it `[judgment]` and leave the verification honest.

   The drafted plan is held **in-conversation** at this point — nothing is written to disk yet. The review gate (step 9) decides whether it lands.

9. **Review gate — present the plan and confirm before writing.** The plan is the last cheap checkpoint before `/execute` ("plan changes are cheap, implementation changes are not"). Do **not** write the file silently; present the drafted plan and ask the user how to proceed. For a non-trivial plan, offer a [human-view](../human-view/SKILL.md) projection alongside — *"want the plain-prose approval view? (/human-view)"* — so approval reads the decisions, not the artefact format. Pick the presentation mode by plan size:

   - **Inline (default, small plans ≤ 6 steps).** Render the full plan body — Context, the Done-criteria echo, and every numbered step (goal / files / outcome / verification / serves-criteria) — in the conversation. Then ask: *accept / edit / reject*.
   - **Outline-first (large plans > 6 steps).** Render a compact outline — one line per step (`Step N: <goal>  → serves [criteria]`) — then ask: *"Show the full plan inline, write it to disk for you to open, or edit a step? (accept / show / write / edit / reject)"*. Pull the full body inline only if the user asks for it.
   - **Ask-only (terse preference — `--quiet` flag, or a stored `preferences/`-tier verbosity preference).** A single prompt: *"Plan drafted: K steps, pinned to spec v<M>. Review inline, or write and open? (review / write / reject)"*. Honour the stated preference for minimal conversation while still **asking** rather than silently writing.

   Resolve the user's choice:

   - **accept** (or "write") → proceed to step 10 and write the file exactly as specified. The confirmed plan is what lands.
   - **edit** → the user describes changes in prose ("drop step 3", "swap 4 and 5", "step 2 should also touch `foo.ts`"). Apply them to the in-conversation draft, re-present per the same mode, and loop until accept or reject.
   - **reject** → discard the draft. Write nothing. Acknowledge (*"Plan discarded — nothing written."*) and stop.

   This is a gate on the **in-conversation draft**, not a second file. No `v<N>-draft.md` scratch file is created — only the confirmed plan becomes `v<N>.md`. The gate fires identically in degraded `--task` mode (arguably more important there, since there is no spec to fall back on). It mirrors the propose-confirm-commit flow recap / capture / rules / memory-audit already use.

10. **Write the plan file.** Path: `.claude/plans/<slug>/v<N>.md`. Reached only on **accept** in step 9.

   Frontmatter:

   ```yaml
   ---
   slug: <slug>
   version: <N>
   status: active
   spec: ../../specs/<slug>/v<M>.md   # pin to the spec version this plan is built against
   supersedes: v<N-1>.md              # omit on v1
   executor: main                     # or `cheap` — see step 8b; omit on main for brevity
   created: YYYY-MM-DD
   description: <one-line — what this plan accomplishes>
   ---
   ```

   **`--task` plans (no spec):** write `spec: none — task description in Context` and put the task description in the plan's Context section. A plan whose `spec:` is `none` is exempt from the stale-pin check and the done-criteria echo — there is no pinned version to go stale and no criteria list to read.

   Body:

   ```markdown
   # Plan — <slug> (v<N>)
   Spec: <relative path to pinned spec version, or "no spec — task description below">
   Generated: YYYY-MM-DD

   ## Context
   <1–3 paragraphs from the spec or task text.>

   ## Done-criteria (from spec)
   <Echo the spec's done_criteria list verbatim, numbered. Each criterion gets a stable index that step "Serves criteria" lines reference. Skip this section entirely in legacy mode.>

   1. <criterion 1 verbatim>
   2. <criterion 2 verbatim>

   ## Step 1: <goal>
   - Files: <concrete paths>
   - Outcome: <what is true after this step>
   - Verification: <command or specific check>
   - Serves criteria: [<list of criterion indices, e.g. 1, 3>]   ← skipped in legacy mode
   - Tags: [research] [delegate] [mechanical|judgment]   ← optional on main; [mechanical]/[judgment] mandatory in strict mode
   - Current state: <before-excerpt, file:line>   ← [delegate] steps; every step in strict mode ("new file" for new-file steps)
   - Exemplar: <path to follow as convention anchor>   ← [delegate] steps; every step in strict mode

   ## Step 2: <goal>
   ...

   ## Notes
   - Architectural rules loaded: <names only>
   - Open risks: <list, or "none">
   ```

11. **Update previous active plan** (when N > 1). Versioning follows spec's canonical contract ([spec SKILL.md § Versioning contract](../spec/SKILL.md)): mark the previous version superseded with a `superseded_by` pointer and regenerate the INDEX.

12. **Update plans INDEX.** Path: `.claude/plans/INDEX.md`. Same shape as specs INDEX:

    ```markdown
    # Plans index

    | Slug | Current | Status | Spec | Created | Description |
    |------|---------|--------|------|---------|-------------|
    | <slug> | v<N> | active | v<M> | YYYY-MM-DD | <one-line> |
    ```

    Regenerated from frontmatter every invocation. Lazy create.

13. **Close.**

    > Wrote `.claude/plans/<slug>/v<N>.md` with K steps, pinned to spec v<M> (reviewed and accepted). Run `/execute <slug>` when ready.

    Optionally offer the blueprint step — user-confirmed, never automatic:

    > Want a concrete blueprint (intent + the mature shape — classes, interfaces, deps, build order) before coding? Run `/blueprint <slug>`.

    Offer it once, in the close only. Do not push it; `/blueprint` is a deliberate choice, and small plans rarely need it.

    **Offer a changelog decision line — significant changes only.** A *new* plan for a slug (v1) is a significant planning-artifact change worth recording: offer *"Drafted the &lt;slug&gt; plan — log a decision line to CHANGELOG? (y/N)"*. On `y`, invoke [`update-changelog`](../update-changelog/SKILL.md) (it composes a `◆` decision line behind its own accept/edit/reject gate). **Do not offer on a routine plan re-draft (v→v+1)** — that is authoring churn, already tracked by the plan version chain + INDEX (changelog-contract §5). draft-plan is a *doorway*, not the writer.

## Spec pinning

A plan's `spec:` frontmatter pins the exact spec version it was drafted against. If the spec evolves to a higher version after the plan is written, the plan does NOT silently update — it stays pinned. This is deliberate: a plan reflects decisions made against a specific spec snapshot. To rebuild the plan against a newer spec, run `/draft-plan <slug>` again, which produces a new plan version pinned to the new spec version.

## What /draft-plan does not do

- Does not implement anything.
- Does not run `/execute`.
- Does not modify spec files.
- Does not silently overwrite an existing plan version. Every write creates a new `v<N>.md`.
- Does not write the plan without confirmation. The review gate (step 9) presents the drafted plan and waits for *accept* before anything lands on disk — no silent write, no draft scratch file.

See also: [`docs/plan-execute-workflow.md`](../../docs/plan-execute-workflow.md).