Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents. The orchestrator's job is coordination, not execution. Orchestrator discovers plans, groups into waves, spawns `gsd-executor` agents, handles checkpoints, collects results. **Subagent:** `gsd-executor` — dedicated plan execution agent with all execution logic baked in. Read STATE.md before any operation to load project context. Before any operation, read project state: ```bash cat .planning/STATE.md 2>/dev/null ``` **If file exists:** Parse and internalize: - Current position (phase, plan, status) - Accumulated decisions (constraints on this execution) - Blockers/concerns (things to watch for) **If file missing but .planning/ exists:** ``` STATE.md missing but planning artifacts exist. Options: 1. Reconstruct from existing artifacts 2. Continue without project state (may lose accumulated context) ``` **If .planning/ doesn't exist:** Error - project not initialized. Confirm phase exists and has plans: ```bash PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1) if [ -z "$PHASE_DIR" ]; then echo "ERROR: No phase directory matching '${PHASE_ARG}'" exit 1 fi PLAN_COUNT=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ') if [ "$PLAN_COUNT" -eq 0 ]; then echo "ERROR: No plans found in $PHASE_DIR" exit 1 fi ``` Report: "Found {N} plans in {phase_dir}" List all plans and extract metadata: ```bash # Get all plans ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | sort # Get completed plans (have SUMMARY.md) ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | sort ``` For each plan, read frontmatter to extract: - `wave: N` - Execution wave (pre-computed) - `autonomous: true/false` - Whether plan has checkpoints Build plan inventory: - Plan path - Plan ID (e.g., "03-01") - Wave number - Autonomous flag - Completion status (SUMMARY exists = complete) Skip completed plans. If all complete, report "Phase already executed" and exit. Read `wave` from each plan's frontmatter and group by wave number: ```bash # For each plan, extract wave from frontmatter for plan in $PHASE_DIR/*-PLAN.md; do wave=$(grep "^wave:" "$plan" | cut -d: -f2 | tr -d ' ') autonomous=$(grep "^autonomous:" "$plan" | cut -d: -f2 | tr -d ' ') echo "$plan:$wave:$autonomous" done ``` **Group plans:** ``` waves = { 1: [plan-01, plan-02], 2: [plan-03, plan-04], 3: [plan-05] } ``` **No dependency analysis needed.** Wave numbers are pre-computed during `/gsd:plan-phase`. Report wave structure with context: ``` ## Execution Plan **Phase {X}: {Name}** — {total_plans} plans across {wave_count} waves | Wave | Plans | What it builds | |------|-------|----------------| | 1 | 01-01, 01-02 | {from plan objectives} | | 2 | 01-03 | {from plan objectives} | | 3 | 01-04 [checkpoint] | {from plan objectives} | ``` The "What it builds" column comes from skimming plan names/objectives. Keep it brief (3-8 words). Execute each wave in sequence. Autonomous plans within a wave run in parallel. **For each wave:** 1. **Describe what's being built (BEFORE spawning):** Read each plan's `` section. Extract what's being built and why it matters. **Output:** ``` --- ## Wave {N} **{Plan ID}: {Plan Name}** {2-3 sentences: what this builds, key technical approach, why it matters in context} **{Plan ID}: {Plan Name}** (if parallel) {same format} Spawning {count} agent(s)... --- ``` **Examples:** - Bad: "Executing terrain generation plan" - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground." 2. **Spawn all agents in wave simultaneously using gsd-executor:** Use Task tool with multiple parallel calls. Each agent is `gsd-executor` with minimal prompt: ``` Task( prompt="Execute plan at {plan_path} Plan: @{plan_path} Project state: @.planning/STATE.md Config: @.planning/config.json (if exists)", subagent_type="gsd-executor", description="Execute {phase}-{plan}" ) ``` The `gsd-executor` subagent has all execution logic baked in: - Deviation rules - Checkpoint protocols - Commit formatting - Summary creation - State updates No template filling needed. Just pass the plan path. Task tool blocks until each agent finishes. All parallel agents return together. 4. **Report completion and what was built:** For each completed agent: - Verify SUMMARY.md exists at expected path - Read SUMMARY.md to extract what was built - Note any issues or deviations **Output:** ``` --- ## Wave {N} Complete **{Plan ID}: {Plan Name}** {What was built — from SUMMARY.md deliverables} {Notable deviations or discoveries, if any} **{Plan ID}: {Plan Name}** (if parallel) {same format} {If more waves: brief note on what this enables for next wave} --- ``` **Examples:** - Bad: "Wave 2 complete. Proceeding to Wave 3." - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces." 5. **Handle failures:** If any agent in wave fails: - Report which plan failed and why - Ask user: "Continue with remaining waves?" or "Stop execution?" - If continue: proceed to next wave (dependent plans may also fail) - If stop: exit with partial completion report 6. **Execute checkpoint plans between waves:** See `` for details. 7. **Proceed to next wave** Plans with `autonomous: false` require user interaction. **Detection:** Check `autonomous` field in frontmatter. **Execution flow for checkpoint plans:** 1. **Spawn gsd-executor for checkpoint plan:** ``` Task( prompt="Execute plan at {plan_path} Plan: @{plan_path} Project state: @.planning/STATE.md", subagent_type="gsd-executor", description="Execute {phase}-{plan}" ) ``` 2. **Agent runs until checkpoint:** - Executes auto tasks normally - Reaches checkpoint task or auth gate - Agent returns with structured checkpoint (format baked into gsd-executor) 3. **Agent return includes (structured format):** - Completed Tasks table with commit hashes and files - Current task name and blocker - Checkpoint type and details for user - What's awaited from user 4. **Orchestrator presents checkpoint to user:** Extract and display the "Checkpoint Details" and "Awaiting" sections from agent return: ``` ## Checkpoint: [Type] **Plan:** 03-03 Dashboard Layout **Progress:** 2/3 tasks complete [Checkpoint Details section from agent return] [Awaiting section from agent return] ``` 5. **User responds:** - "approved" / "done" → spawn continuation agent - Description of issues → spawn continuation agent with feedback - Decision selection → spawn continuation agent with choice 6. **Spawn continuation agent (NOT resume):** Spawn fresh `gsd-executor` with continuation context: ``` Task( prompt="Continue executing plan at {plan_path} {completed_tasks_table from checkpoint return} Resume from: Task {N} - {task_name} User response: {user_response} {resume_instructions based on checkpoint type} Plan: @{plan_path} Project state: @.planning/STATE.md", subagent_type="gsd-executor", description="Continue {phase}-{plan}" ) ``` The `gsd-executor` has continuation handling baked in — it will verify previous commits and resume correctly. 7. **Continuation agent executes:** - Verifies previous commits exist - Continues from resume point - May hit another checkpoint (repeat from step 4) - Or completes plan 8. **Repeat until plan completes or user stops** **Why fresh agent instead of resume:** Resume relies on Claude Code's internal serialization which breaks with parallel tool calls. Fresh agents with explicit state are more reliable and maintain full context. **Checkpoint in parallel context:** If a plan in a parallel wave has a checkpoint: - Spawn as normal - Agent pauses at checkpoint and returns with structured state - Other parallel agents may complete while waiting - Present checkpoint to user - Spawn continuation agent with user response - Wait for all agents to finish before next wave After all waves complete, aggregate results: ```markdown ## Phase {X}: {Name} Execution Complete **Waves executed:** {N} **Plans completed:** {M} of {total} ### Wave Summary | Wave | Plans | Status | |------|-------|--------| | 1 | plan-01, plan-02 | ✓ Complete | | CP | plan-03 | ✓ Verified | | 2 | plan-04 | ✓ Complete | | 3 | plan-05 | ✓ Complete | ### Plan Details 1. **03-01**: [one-liner from SUMMARY.md] 2. **03-02**: [one-liner from SUMMARY.md] ... ### Issues Encountered [Aggregate from all SUMMARYs, or "None"] ``` **Verify the phase GOAL was achieved, not just that tasks completed.** This step catches the common failure: tasks done but goal not met (stubs, placeholders, unwired code). **1. Spawn gsd-verifier subagent:** ``` Task( prompt="Verify phase {phase_number} goal achievement Phase: {phase_number} - {phase_name} Phase goal: {phase_goal_from_roadmap} Phase directory: @.planning/phases/{phase_dir}/ Project context: @.planning/ROADMAP.md @.planning/REQUIREMENTS.md (if exists)", subagent_type="gsd-verifier", description="Verify phase {phase_number}" ) ``` The `gsd-verifier` subagent has all verification logic baked in: - Establishes must-haves (from frontmatter or derived) - Verifies observable truths against codebase - Checks artifacts exist and are substantive (not stubs) - Traces key links (wiring between components) - Scans for anti-patterns - Creates VERIFICATION.md report - Returns status to orchestrator **2. Verification subagent returns** with status and report path. **3. Handle verification result:** **If status = "passed":** ``` ## ✓ Phase Verification Passed All {N} must-haves verified: - {truth 1} ✓ - {truth 2} ✓ - {truth 3} ✓ Phase goal achieved. Proceeding to update roadmap. ``` Continue to update_roadmap step. **If status = "gaps_found":** ``` ## ⚠️ Phase Verification Found Gaps {M} of {N} must-haves incomplete: | Must-Have | Status | Issue | |-----------|--------|-------| | {truth 1} | ✓ VERIFIED | - | | {truth 2} | ✗ FAILED | API route returns placeholder | | {truth 3} | ✗ FAILED | Component not wired to API | ### Recommended Fix Plans 1. **{phase}-{next}-PLAN.md**: {description} 2. **{phase}-{next+1}-PLAN.md**: {description} Creating fix plans and executing... ``` Then: 1. Generate fix PLAN.md files from recommendations 2. Execute fix plans (loop back to execute_waves) 3. Re-verify (loop back to verify_phase_goal) 4. Repeat until all must-haves pass **If status = "human_needed":** ``` ## 👤 Human Verification Required Automated checks passed. These items need manual testing: ### 1. {Test Name} **Test:** {what to do} **Expected:** {what should happen} ### 2. {Test Name} **Test:** {what to do} **Expected:** {what should happen} After testing, type "verified" or describe issues found. ``` Wait for user response: - "verified" / "pass" / "ok" → Continue to update_roadmap - Description of issues → Generate fix plans, execute, re-verify **4. Fix plan generation:** When gaps are found, generate fix plans: ```bash # Create fix plan from verification recommendations NEXT_PLAN_NUM=$(ls "$PHASE_DIR"/*-PLAN.md | wc -l) NEXT_PLAN_NUM=$((NEXT_PLAN_NUM + 1)) ``` Fix plans: - Use standard PLAN.md template - Include must_haves (same as original, for re-verification) - Tasks target specific gaps (not entire feature) - Wave 99 (runs after all original plans) **5. Re-verification loop:** After fix plans execute: 1. Spawn verification subagent again 2. Check same must-haves 3. If still gaps → more fix plans 4. If passed → continue Limit: 3 fix cycles. If still failing after 3 rounds, present to user: ``` ## ⚠️ Verification Still Failing After 3 Fix Attempts Remaining gaps: - {gap 1} - {gap 2} Options: 1. Continue anyway (manual fixes later) 2. Stop and investigate ``` **Why this matters:** Without verification: - Phase 3 "complete" but chat doesn't work - Phase 4 builds on broken foundation - Phase 8: "nothing works, start over" With verification: - Phase 3 verified before moving on - Gaps caught and fixed immediately - Each phase delivers real value Update ROADMAP.md to reflect phase completion: ```bash # Mark phase complete # Update completion date # Update status ``` Commit roadmap update: ```bash git add .planning/ROADMAP.md git commit -m "docs(phase-{X}): complete phase execution" ``` Present next steps based on milestone status: **If more phases remain:** ``` ## Next Up **Phase {X+1}: {Name}** — {Goal} `/gsd:plan-phase {X+1}` <sub>`/clear` first for fresh context</sub> ``` **If milestone complete:** ``` MILESTONE COMPLETE! All {N} phases executed. `/gsd:complete-milestone` ``` **Why this works:** Orchestrator context usage: ~10-15% - Read plan frontmatter (small) - Group by wave (logic, no heavy reads) - Spawn Task calls with minimal prompts - Collect results Each `gsd-executor` subagent: Fresh 200k context - Execution logic baked into subagent prompt (cached) - Only plan-specific context varies - Executes plan with full capacity - Creates SUMMARY, commits **Prompt caching benefit:** The `gsd-executor` subagent prompt is stable across all invocations. Only the plan path varies. 90% cost reduction on cached portion. **No polling.** Task tool blocks until completion. No TaskOutput loops. **No context bleed.** Orchestrator never reads execution internals. Just paths and results. **Subagent fails mid-plan:** - SUMMARY.md won't exist - Orchestrator detects missing SUMMARY - Reports failure, asks user how to proceed **Dependency chain breaks:** - Wave 1 plan fails - Wave 2 plans depending on it will likely fail - Orchestrator can still attempt them (user choice) - Or skip dependent plans entirely **All agents in wave fail:** - Something systemic (git issues, permissions, etc.) - Stop execution - Report for manual investigation **Checkpoint fails to resolve:** - User can't approve or provides repeated issues - Ask: "Skip this plan?" or "Abort phase execution?" - Record partial progress in STATE.md **Resuming interrupted execution:** If phase execution was interrupted (context limit, user exit, error): 1. Run `/gsd:execute-phase {phase}` again 2. discover_plans finds completed SUMMARYs 3. Skips completed plans 4. Resumes from first incomplete plan 5. Continues wave-based execution **STATE.md tracks:** - Last completed plan - Current wave - Any pending checkpoints