---
name: forge:plan
description: Research-first multi-plan generation with wave-based execution ordering.
argument-hint: <phase-name> [--research] [--skip-research] [--gaps] [--skip-verify]
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Task
  - TaskCreate
  - TeamCreate
  - WebSearch
  - WebFetch
  - AskUserQuestion
---

Generate research-backed multi-plan breakdown for phase $ARGUMENTS. Each research finding that needs addressing becomes a separate plan file with 2-3 tasks. Plans are grouped into waves for parallel execution.

**Read first:** REQUIREMENTS.md, ROADMAP.md, .planning/phases/{phase}/CONTEXT.md (if exists), state/STATE.json

**Steps:**

1. **Parse arguments** — Extract phase name and flags from `$ARGUMENTS`:
   - `--research` — force re-run research even if RESEARCH.md exists
   - `--skip-research` — skip research step entirely
   - `--gaps` — generate gap closure plans only (used after verify)
   - `--skip-verify` — skip plan verification step

2. **Check for existing plans** — Look for `.planning/phases/{phase}/*-PLAN.md` files.
   - If plan files exist, use AskUserQuestion with options:
     a) "Add more plans" — continue numbering from highest existing plan number
     b) "Verify existing plans" — route to `/forge:verify {phase}`
     c) "Execute existing plans" — route to `/forge:execute {phase}`
     d) "Replan from scratch" — delete existing plan files, regenerate from research
   - If no plans exist, proceed to research.

3. **Research phase** (unless `--skip-research` or `--gaps`):
   - Check if `.planning/phases/{phase}/{phase}-RESEARCH.md` exists.
   - If exists and no `--research` flag, ask: use existing research or re-run?
   - If research needed, spawn a researcher agent via Task tool (subagent_type: "general-purpose"):
     - **Researcher reads:** CONTEXT.md to constrain research scope:
       - **Locked decisions** → research these deeply, find best practices, don't explore alternatives
       - **Claude's discretion** → research multiple options, recommend one with rationale
       - **Deferred ideas** → ignore completely, do not research
     - **Researcher uses:** WebSearch (include current year in queries), WebFetch (official docs), Grep/Glob (codebase patterns to follow)
     - **Researcher produces** `{phase}-RESEARCH.md` with sections:
       ```
       # {Phase} Research
       ## User Constraints (from CONTEXT.md)
       ## Summary
       ## Recommended Stack (specific versions)
       ## Architecture Patterns
       ## Don't Hand-Roll (use existing libraries)
       ## Common Pitfalls
       ## Code Examples
       ## Sources
       [Each with confidence: HIGH | MEDIUM | LOW]
       ```
     - Each major research finding becomes a candidate for a separate plan

4. **Generate multi-plan breakdown** — Spawn a planner agent via Task tool (subagent_type: "general-purpose"):
   - **Planner reads:** CONTEXT.md (locked decisions), RESEARCH.md, REQUIREMENTS.md, STATE.json, existing codebase patterns
   - **Planner decomposes** the phase into multiple plan files, each covering one coherent unit of work with 2-3 tasks
   - **Each plan file** gets YAML frontmatter:
     ```yaml
     ---
     phase: {phase-name}
     plan: 01
     wave: 1
     depends_on: []
     files_modified: [src/foo.ts, src/bar.ts]
     autonomous: true
     gap_closure: false
     ---
     ```
   - **Plan body** contains:
     - Objective (what this plan builds and why)
     - Context references (which CONTEXT.md decisions apply)
     - Tasks in XML format:
       ```xml
       <task name="descriptive-name" type="auto">
         <files>src/foo.ts, src/bar.ts</files>
         <action>What to implement, specifically</action>
         <verify>npm test, specific checks</verify>
         <done>Concrete completion criteria</done>
       </task>
       ```
     - Success criteria for the plan as a whole
   - **Write to:** `.planning/phases/{phase}/{phase}-01-PLAN.md`, `{phase}-02-PLAN.md`, etc.
   - **Build dependency graph and assign waves:**
     - Independent plans → same wave (can execute in parallel)
     - Plans that depend on others → higher wave number
     - `wave = max(waves[dep] for dep in depends_on) + 1`
     - Wave 1 plans have no dependencies

5. **Verify plans** (unless `--skip-verify`):
   - Check: requirements coverage across all plans, task completeness, dependency correctness, no circular deps, scope matches CONTEXT.md (no deferred ideas included)
   - If issues found, revision loop (max 3 iterations): targeted fixes, not full replan
   - If passes, proceed

6. **Present results:**
   ```
   Phase {X}: {Name} — {N} plan(s) in {M} wave(s)

   | Wave | Plans | What it builds |
   |------|-------|----------------|
   | 1    | 01, 02 | [objectives]  |
   | 2    | 03     | [objective]   |

   Research: {Completed | Used existing | Skipped}
   Verification: {Passed | Skipped}

   Next: /forge:execute {phase}
   ```

**Plan frontmatter reference:**
```yaml
---
phase: M2-planning-engine       # Phase identifier
plan: 01                        # Sequential plan number
wave: 1                         # Execution wave (parallel within wave)
depends_on: []                  # Plan numbers this depends on
files_modified: [src/foo.ts]    # Files this plan touches
autonomous: true                # false if has checkpoints needing user input
gap_closure: false              # true for gap remediation plans
---
```