plan-design — PRD to Execution Contract (Human Gate 2)

Produce docs/forge/plans/plan-NNN.md from docs/forge/prd/NNN-name.md. After approval this file is the FROZEN execution contract — run asks nothing.

Step 1 — Load inputs

• Read the target PRD docs/forge/prd/NNN-name.md (ask which N if ambiguous).
• If docs/forge/specs/spec-NNN.md exists (produced by spec-design), read it. Phases then follow its File Map and Interfaces, notes: cite the spec sections a phase implements, and the spec's Risks inform tagging — a phase touching a listed risk does not start junior/light.

• If NO spec exists and the PRD looks architecturally non-trivial (new interfaces, data models, multiple components that must agree), ASK the user ONCE before decomposing, as a lettered list (mark one Recommended with a concrete why) — never assume either way:

  No spec found, and this PRD looks architecturally non-trivial. Next: a) Run /forge-master:spec-design first — Recommended, new interfaces / data models / components that must agree b) Plan directly — you accept resolving design inline as phases are decomposed

  The user picks by replying with a letter. On (a), INVOKE forge-master:spec-design yourself via the Skill tool rather than asking the user to type it. For a clearly small task, proceed without asking — the spec is optional and subordinate to this plan.

• Read docs/context/lessons.md. Past escalation lessons ("P-type X tagged light escalated — tag heavy when <pattern>") MUST inform your tagging. This is the triage learning loop.
• Read templates/plan-template.md (from this plugin) as the output skeleton.

Step 2 — Decompose into phases

• Test harness first. Detect the repo's test runner (package.json test script, pytest/pyproject, go test, cargo, etc.). If there is none, the plan's first phase is ### P0: setup test harness (covers: -, depends_on: -, tier: junior, process: light, notes naming the runner you chose and why), and every phase without other dependencies gets depends_on: P0. P0 is written HERE so it passes gate 2 like every other phase; run never improvises one.
• Group the PRD's ACs into phases (P1, P2, ...). Each phase is an independently committable, independently verifiable unit of work.
• For each phase set:
  • covers: the AC IDs it satisfies.
  • depends_on: prerequisite P-ids. The graph MUST be acyclic. It defines what remains executable if a phase blocks.
  • tier: junior (cheap-model subagent, low effort) or senior (top model, high effort). Start optimistic — junior unless evidence (PRD constraints, a relevant lesson) demands senior.
  • process: light (inline implement -> write/run AC tests -> commit; no separate spec or review) or heavy (brief phase spec -> TDD red-green -> independent-subagent code review -> commit). Start light unless complexity/risk warrants heavy.
  • success: covered ACs green + full repo test suite still passes.
  • notes: risks, probable files, the reason for the tier/process choice (cite a lesson if one applied).

Step 3 — Total coverage proof (do this BEFORE presenting)

Build the coverage table: every PRD AC -> the single phase that covers it.

• Every AC appears in exactly one phase. An AC covered by zero phases (orphan) makes the plan INVALID — fix before presenting.
• An AC covered by two phases is also invalid — assign it to one.
• Verify the depends_on graph is acyclic.

Step 3.5 — Parallel groups (only if the user wants parallelism)

Identify sets of phases that are mutually independent (no depends_on path between any pair) AND file-disjoint (probable files in notes / cited File Map rows do not overlap). Declare them in the plan as ## Parallel Groups (e.g. group-1: P2, P3, P4). A phase in no group runs sequentially. When in doubt about file overlap, leave the phase out of any group — sequential is the safe default.

Step 4 — Run config

Fill Run Config: mode (default autonomous), branch: forge/NNN-<slug>, isolation: worktree (default — the run gets its own sibling worktree so the user's primary dir, editor, and any concurrent session stay untouched; only set in-place when the user confirms this is the sole session on the repo), K: 3, phase_budget / run_budget heuristics sized to the PRD, on_complete (default pr — push branch + open PR | merge | keep), and max_parallel: 1 (default — fully sequential) or N (max concurrent phases per batch). Only set > 1 when Parallel Groups exist.

Derive gates: from the repo's CI configuration (e.g. .github/workflows/*.yml) and its package/test scripts (package.json scripts, Makefile, pyproject): one bash command covering everything CI runs, e.g. npm test && npx tsc --noEmit. Show it on the Run Config card.

For a large or heavy plan, optionally hand off to the budget skill (/forge-master:budget) BEFORE gate 2 — it produces a per-phase token matrix and fills phase_budget / run_budget with principled numbers instead of heuristics, and flags any phase whose cost contradicts its tag. Optional; skip it for small plans.

Step 5 — Write the file

Write docs/forge/plans/plan-NNN.md (create docs/forge/plans/ if it does not exist) by filling templates/plan-template.md completely — no <...> placeholders left. Keep each field as a plain - key: value line (no bold, no nesting), and write "no dependencies" as -.

Step 5.5 — Lint (the coverage proof, executed)

Run node "${CLAUDE_PLUGIN_ROOT}/skills/forge-run/scripts/forge-state.mjs" lint docs/forge/plans/plan-NNN.md --prd docs/forge/prd/NNN-name.md. It checks by code what Step 3 checked by reading: required fields present, valid tier/process tags, every depends_on names a real phase, no dependency cycle, every PRD AC covered by exactly one phase, no covered AC missing from the PRD, Parallel Groups whose members are known and mutually independent, and max_parallel > 1 only with groups. File-disjointness stays your judgment (Step 3.5).

• ok: false → fix the plan and re-run until ok: true. A plan that fails lint is never presented at gate 2; run INIT would stop on it anyway.
• warnings don't block, but name each one in Block B. A phase that covers no AC (like P0) is expected. Parallel-group problems while max_parallel is 1 usually mean the template's example group line was left in: delete the ## Parallel Groups section unless you declared groups.

Step 6 — Human gate 2

Present TWO blocks, then gate.

Block A — Run Config card

Before presenting, run node "${CLAUDE_PLUGIN_ROOT}/skills/forge-run/scripts/forge-state.mjs" preflight docs/forge/plans/plan-NNN.md.

Render the frozen-candidate config with a health mark on each diagnosable line (✓ healthy · ⚠ advisory · ⛔ hard-block). Format phase_budget / run_budget with thousands separators for readability (e.g. 250,000, 1,200,000) — this is display only; the persisted plan ## Run Config keeps them as raw integers (no separators) so the loop's budget math stays unambiguous.

## Run Config — review before freeze
- **mode:** <autonomous|attended> · <one-line meaning>
- **branch:** forge/NNN-<slug>
- **isolation:** <worktree|in-place> · <primary dir untouched | shares the working dir>   <mark>
- **K:** <n> · max self-heal red iterations/phase before escalate
- **max_parallel:** <n> · <sequential | concurrent per group>      <mark>
- **phase_budget:** ~<n,nnn> · soft early-escalation signal        <mark>
- **run_budget:** ~<n,nnn> · global cap, clean-stop on exhaust     <mark>
- **on_complete:** <pr|merge|keep> · <one-line meaning>
- **gates (every phase):** <the derived gates: command>

Mark logic:

• isolation — ✓ if worktree · ⚠ shared-dir if in-place (the run will check out its branch in the working dir, colliding with any concurrent session or open editor).
• run_budget — ✓ if ≥ matrix TOTAL-high × headroom · ⚠ below est if under TOTAL-high · (heuristic — no matrix) if budget never ran.
• phase_budget — ✓ if ≥ a typical phase's estimated high · ⚠ below est if under · (heuristic — no matrix) if no matrix.
• K — ✓ at 2–5 · ⚠ low if <2 · ⚠ high if >6.
• on_complete — ✓ for keep, or pr/merge when preflight finds a remote · ⛔ no remote if pr/merge and preflight reports none (option a) withheld until the user adds a remote or picks keep).
• max_parallel — ✓ at 1 · ✓ groups file-disjoint if >1 WITH ## Parallel Groups · ⛔ no Parallel Groups if >1 WITHOUT.

Block B — the plan

Then present: the lint result (ok: true, plus any warnings), the phase list, each phase's tier/process tags WITH the reasoning (and any lesson that drove a non-default tag), the total-coverage table, and — when declared — the Parallel Groups with their file-disjointness reasoning (the human approves parallelism as part of the frozen contract).

The gate

Ask as a lettered list:

Review the config and plan above. Next: a) Approve & freeze — Recommended (omit this line whenever any card line is ⛔: approve option withheld) b) Change something — name the knob and the new value

On b), apply the matching pushback, then edit the plan's Run Config and re-present Block A once (back to a/b). Pushback is advisory — warn once, then honor for every knob EXCEPT the hard blocks (no ## Parallel Groups with max_parallel > 1; no remote with on_complete pr/merge):

• isolation set to in-place: "⚠ in-place checks out forge/NNN-<slug> in the working dir — any other session or your open editor gets yanked onto the run branch (the collision worktree mode exists to prevent). Safe only if this is the sole session on the repo. Keep in-place?"
• run_budget below matrix TOTAL-high: "⚠ run_budget ~X is below the matrix TOTAL-high (~Y). The loop stops cleanly mid-run with a report at the cap — you may not reach the finish action. Trade: ~Δ fewer tokens for a possible incomplete run. Keep ~X?"
• phase_budget below a typical phase's high: "⚠ phase_budget ~X is under several phases' estimated high — those phases early-escalate to you before finishing (more interruptions, not a kill). Intended?"
• K < 2: "⚠ K=X: self-heal gives up after X red iteration(s) then escalates. Lower K = faster failures, more human pings. Default 3 balances. Keep X?"
• K > 6: "⚠ K=X: a stuck phase burns budget on many red retries before escalating. Trades tokens for autonomy. Keep X?"
• budget tightened but no matrix exists — soft offer, lettered:

  I'm estimating from heuristics — no matrix was run, so I can't say how close ~X is to real cost. a) Run /forge-master:budget first — Recommended, grounds this in real numbers b) Keep ~X anyway — you accept the guess

• max_parallel > 1 with no ## Parallel Groups (⛔ HARD): "⛔ max_parallel=X but no Parallel Groups are declared. Concurrent phases run in worktrees with no file-disjointness proof — merge-back can corrupt overlapping files. Can't freeze. Either set max_parallel: 1, or declare Parallel Groups (I'll re-check file-disjointness)." Option a) stays unavailable until this clears.
• on_complete pr/merge with no remote (⛔ HARD, preflight reports none): "⛔ on_complete=X needs a git remote and none exists. Can't freeze. Add a remote, or set on_complete: keep." The approve option is withheld until then.

Advisory pushback fires ONCE per knob; if the user reconfirms, honor it and move on — no re-litigating. The change loop converges because every pass is user-driven.

On approval the plan is FROZEN. Then present the next step as a lettered list:

Plan approved and frozen. Next: a) Proceed to /forge-master:run — Recommended, executes the frozen contract now b) Hold — stop here; resume later by re-invoking /forge-master:run

The user chooses by replying with a letter. On (a), INVOKE forge-master:run yourself via the Skill tool — do NOT ask the user to type the command; once they approve, execution starts automatically. On (b), stop.