---
name: forge:execute
description: Execute all plans in a phase with wave-based parallelization.
argument-hint: <phase-name> [--gaps]
allowed-tools:
  - Read
  - Write
  - Bash
  - TaskList
  - TaskCreate
  - TaskUpdate
  - TaskGet
  - SendMessage
  - Task
---

Execute phase $ARGUMENTS by discovering all plan files, grouping by wave, and executing waves sequentially with plans within each wave in parallel.

**Flag support:** If `$ARGUMENTS` contains `--gaps`, only execute plans with `gap_closure: true` in their frontmatter. Parse the phase name by stripping `--gaps` from arguments.

**Read first:** All `.planning/phases/{phase}/*-PLAN.md` files, `.planning/phases/{phase}/CONTEXT.md`, state/STATE.json

**Steps:**

1. **Parse arguments and discover plans:**
   - Extract phase name, check for `--gaps` flag
   - Glob `.planning/phases/{phase}/*-PLAN.md` → parse YAML frontmatter of each
   - Extract from each: plan number, wave, depends_on, autonomous, files_modified, gap_closure
   - Skip plans that have a matching `*-SUMMARY.md` (already executed)
   - If `--gaps`: only include plans where `gap_closure: true`
   - If no plans found, error: suggest running `/forge:plan {phase}` first
   - Report: "Found {N} plans in {M} waves ({K} incomplete)"

2. **Ensure FORGE team AND teammates are running:**
   - Check `~/.claude/teams/forge/config.json` exists. If not, create team with TeamCreate.
   - Read `.planning/AgentTeam.md` to get the list of teammates that should be active.
   - Read `~/.claude/teams/forge/config.json` members list to see who is registered.
   - For each teammate defined in AgentTeam.md that is NOT in the team config (or if team was just created), spawn them using the Task tool with `team_name: "forge"` and `name: "{teammate-name}"` and their full prompt from AgentTeam.md.
   - This ensures teammates are always running when any FORGE command executes, even after session restarts.

3. **Create EXECUTION.md** — `.planning/phases/{phase}/EXECUTION.md` with wave/plan status table:
   ```markdown
   # {Phase} Execution Log
   **Started:** [timestamp]

   | Wave | Plan | Objective | Status | Commit |
   |------|------|-----------|--------|--------|
   | 1    | 01   | [from plan] | pending | — |
   | 1    | 02   | [from plan] | pending | — |
   | 2    | 03   | [from plan] | pending | — |
   ```

4. **Wave execution loop** (sequential between waves, parallel within):
   For each wave in order:
   - Describe what this wave builds (from plan objectives — substantive, not just plan numbers)
   - Spawn one executor agent per plan via Task tool (subagent_type: "general-purpose"). Each executor:
     - Reads their specific `{phase}-{NN}-PLAN.md`
     - Reads CONTEXT.md for locked decisions and RESEARCH.md for technical guidance
     - Executes tasks following the plan exactly
     - Atomic commit per task: `type(phase-plan): description`
     - Creates `{phase}-{NN}-SUMMARY.md` on completion with:
       ```markdown
       # Plan {NN} Summary
       **Completed:** [timestamp]
       ## What was built
       ## Files changed
       ## Commits
       ## Issues encountered (if any)
       ```
   - Wait for all wave agents to complete
   - Spot-check: verify SUMMARY.md exists for each plan, git commits present
   - Update EXECUTION.md after each plan completes
   - Report wave completion with what was built
   - Proceed to next wave automatically (do NOT ask user between waves)

5. **Cross-domain work:** If a plan touches another teammate's files, use REQUEST_CONTRACT event → provider publishes to contracts/ → both work against contract

6. **State:** Agents write events to state/events/, State Steward merges → STATE.json

7. **On completion:**
   - Aggregate all SUMMARY.md files into final EXECUTION.md status
   - Submit phase completion events
   - Offer `/forge:verify {phase}` to validate results

**Prefer existing teammates** over spawning new ones. Only spawn if the task domain is truly uncovered by current team members.