/plan

name: plan
description: "Create a validated planning document with adversarial critique before implementation"
argument-hint: "Feature description [--no-issues] (e.g., '/plan Add JWT authentication for API endpoints')"
allowed-tools: [Task, Read, Bash, Grep, Glob, WebSearch, Write]
disable-model-invocation: false
user-invocable: true
user_facing: true

Create Validated Plan

Create a structured planning document with adversarial critique. Plans are written to `.claude/plans/<slug>.md` and validated by the plan_gate hook before implementation.

Implementation

**CRITICAL**: Follow these steps in order. Each step builds on the previous.

ARGUMENTS: {{ARGUMENTS}}

---

STEP 0: Parse Arguments

Parse the `{{ARGUMENTS}}` placeholder for the feature description and flags:

--no-issues       Skip automatic GitHub issue creation in Step 6

If `--no-issues` is present, set no_issues=true. Strip the flag from the feature description string before use.

If no description provided, prompt the user for a feature description.

---

STEP 1: Problem Statement (WHY + SCOPE)

Define the problem clearly:

1. **WHY** is this change needed? What problem does it solve? 2. **SCOPE**: What is IN scope and what is OUT of scope? 3. **Success criteria**: How will we know the plan is complete?

Estimate the number of files that will be created or modified.

Invoke the **plan-critic** agent for initial feedback on the problem statement. The plan-critic provides adversarial review to challenge assumptions and find gaps.

**Agent**(subagent_type="plan-critic", model="opus")

---

STEP 2: Scope Check

Compare the estimated file count from Step 1 against what you discover during research.

**HARD GATE**: If the actual file count exceeds the Step 1 estimate by >50%, halt and re-scope with the user before proceeding.

---

STEP 3: Existing Solutions

Search for existing solutions before building anything new:

1. **Codebase search**: Use Grep and Glob to find similar patterns 2. **Web search**: Use WebSearch to find libraries, patterns, or prior art 3. **Document findings**: Record what was searched and what was found

This section becomes the "## Existing Solutions" in the plan output.

---

STEP 4: Minimal Path

Design the smallest change that achieves the goal:

1. List files to create/modify in dependency order 2. Identify what can be deferred to follow-up work 3. Define the critical path

This section becomes the "## Minimal Path" in the plan output.

---

STEP 5: Adversarial Critique — Iterative Loop

Invoke the **plan-critic** agent with the full plan draft.

**Agent**(subagent_type="plan-critic", model="opus")

**IMPORTANT — MODEL ENFORCEMENT**: The plan-critic MUST run as `model="opus"`. Do NOT invoke plan-critic with sonnet, haiku, or any other model. Opus is required for adversarial critique quality.

Run plan-critic in a **sequential iterative loop**. Each round is a SEPARATE agent invocation. Output from round N is input to round N+1.

**Loop rules:**

• **Minimum**: 3 rounds (not 2 — 2 rounds catches surface issues, 3rd round validates the fixes)
• **Maximum**: 5 rounds (beyond 5, error introduction exceeds correction — per iterative review-fix convergence formula)
• **Convergence**: Stop after round ≥ 3 IF composite score ≥ 3.0 AND no axis below 2. Otherwise continue.
• **NEVER run rounds concurrently** — each round MUST complete before the next starts

**Round protocol:**

**Round 1**: Pass the full plan draft. Instruct: "This is your FIRST critique round — identify issues across all 5 critique axes."

**Round 2+**: Pass the plan (revised if REVISE verdict) AND the previous round's full verdict output. Instruct: "This is ROUND N. Previous round verdict: {verdict}, score: {composite}. Previous findings: {key issues}. Verify fixes and probe deeper."

**After each round**, parse the verdict:

• **PROCEED** (score ≥ 3.0, no axis below 2): If round ≥ 3, exit loop. If round < 3, continue (minimum rounds not met).
• **REVISE**: Revise the plan based on feedback. Feed revised plan + critique into next round.
• **BLOCKED**: Rethink approach. Either revise fundamentally and restart critique loop, or escalate to user.

**Verdict authorship (Issue #1155)**: A `Verdict: PROCEED` line in a freshly-generated plan MUST come from a completed plan-critic round (round-table row, or section header `### Round N (plan-critic, ...)`). A self-assessed verdict from the planner — typically marked `provisional`, `(provisional)`, or `awaits plan-critic` — does NOT satisfy STEP 5.5a's skip condition in `/implement`. Concretely: if you write the plan file with a self-assessment such as `Verdict: PROCEED (provisional) — awaits plan-critic at /implement time`, the `/implement` 5.5a negative filter (Issue #1155) will detect the `provisional` marker, fall through to 5.5b, and invoke plan-critic as if the file did not exist. To make 5.5a skip legitimately, complete the adversarial loop here in STEP 5 and let plan-critic write the final `Verdict: PROCEED` line.

**Score tracking**: Maintain a running table of scores across rounds:

| Round | Verdict | Composite | Assumption | Scope | Existing | Minimalism | Uncertainty | |-------|---------|-----------|------------|-------|----------|------------|-------------|

Track delta between rounds. Score regression (lower than previous) is EXPECTED and ACCEPTABLE — it means deeper issues were found.

**Exit condition**: The FINAL round's verdict determines the outcome. Not the best score, not the average — the last round.

**Convergence Trap Detection** — Check after each round:

1. **Plateau/Divergence**: If finding count plateaus or INCREASES across 2+ consecutive rounds → issue BLOCKED (loop is stuck, not converging) 2. **Critic Instability**: If composite score drops > 1 point with NO corresponding plan revision → flag as critic instability, escalate to user: "Critic scores inconsistent — composite dropped {delta} without plan changes. Review manually or