msd-core/get-shit-done/workflows/execute-phase.md

<purpose>
Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents.
</purpose>

<core_principle>
The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results.
</core_principle>

<process>

<step name="validate_phase">
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}"
</step>

<step name="discover_plans">
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:
- `depends_on: []` - Plan IDs this plan requires
- `files_modified: []` - Files this plan touches
- `autonomous: true/false` - Whether plan has checkpoints

Build plan inventory:
- Plan path
- Plan ID (e.g., "03-01")
- Dependencies
- Files modified
- Autonomous flag
- Completion status (SUMMARY exists = complete)

Skip completed plans. If all complete, report "Phase already executed" and exit.
</step>

<step name="analyze_dependencies">
Build dependency graph from frontmatter:

**Direct dependencies:**
- `depends_on: ["03-01"]` → this plan depends on 03-01

**File conflict dependencies:**
- If two plans modify same file, later plan (by number) depends on earlier

**Build graph:**
```
plan-01: {deps: [], files: [src/user.ts], autonomous: true}
plan-02: {deps: [], files: [src/product.ts], autonomous: true}
plan-03: {deps: ["plan-01"], files: [src/dashboard.tsx], autonomous: false}
plan-04: {deps: ["plan-02"], files: [src/cart.ts], autonomous: true}
plan-05: {deps: ["plan-03", "plan-04"], files: [src/checkout.ts], autonomous: true}
```
</step>

<step name="group_into_waves">
Group plans into execution waves based on dependencies:

**Wave assignment algorithm:**
1. Wave 1: All plans with no dependencies AND autonomous=true
2. Non-autonomous plans with no dependencies: execute after Wave 1, before Wave 2
3. Wave N: Plans whose dependencies are all in earlier waves

**Separate checkpoint plans:**
Plans with `autonomous: false` execute in main context (not parallel subagent) to handle user interaction.

**Example:**
```
Wave 1 (parallel): [plan-01, plan-02]
Checkpoint: [plan-03] - has human-verify, runs in main context
Wave 2 (parallel): [plan-04]
Wave 3: [plan-05]
```

Report wave structure to user:
```
Execution Plan:
  Wave 1 (parallel): 03-01, 03-02
  Checkpoint: 03-03 (requires user verification)
  Wave 2 (parallel): 03-04
  Wave 3: 03-05

Total: 5 plans in 3 waves + 1 checkpoint
```
</step>

<step name="execute_waves">
Execute each wave in sequence. Autonomous plans within a wave run in parallel.

**For each wave:**

1. **Spawn all autonomous agents in wave simultaneously:**

   Use Task tool with multiple parallel calls. Each agent gets prompt from subagent-task-prompt template:

   ```
   <objective>
   Execute plan {plan_number} of phase {phase_number}-{phase_name}.

   Commit each task atomically. Create SUMMARY.md. Update STATE.md.
   </objective>

   <execution_context>
   @~/.claude/get-shit-done/workflows/execute-plan.md
   @~/.claude/get-shit-done/templates/summary.md
   @~/.claude/get-shit-done/references/checkpoints.md
   @~/.claude/get-shit-done/references/tdd.md
   </execution_context>

   <context>
   Plan: @{plan_path}
   Project state: @.planning/STATE.md
   Config: @.planning/config.json (if exists)
   </context>

   <success_criteria>
   - [ ] All tasks executed
   - [ ] Each task committed individually
   - [ ] SUMMARY.md created in plan directory
   - [ ] STATE.md updated with position and decisions
   </success_criteria>
   ```

2. **Wait for all agents in wave to complete:**

   Task tool blocks until each agent finishes. All parallel agents return together.

3. **Collect results from wave:**

   For each completed agent:
   - Verify SUMMARY.md exists at expected path
   - Note any issues reported
   - Record completion

4. **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

5. **Execute checkpoint plans between waves:**

   See `<checkpoint_handling>` for details.

6. **Proceed to next wave**

</step>

<step name="checkpoint_handling">
Plans with `autonomous: false` require user interaction.

**Detection:** Check `autonomous` field in frontmatter.

**Execution flow for checkpoint plans:**

1. **Spawn agent for checkpoint plan:**
   ```
   Task(prompt="{subagent-task-prompt}", subagent_type="general-purpose")
   ```

2. **Agent runs until checkpoint:**
   - Executes auto tasks normally
   - Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`)
   - Agent returns with checkpoint details in its response

3. **Agent return includes:**
   - Checkpoint type (human-verify, decision, human-action)
   - Checkpoint details (what-built, options, instructions)
   - Agent ID for resumption
   - Progress so far (tasks completed)

4. **Orchestrator presents checkpoint to user:**
   ```
   ## Checkpoint: Visual Verification Required

   **Plan:** 03-03 Dashboard Layout
   **Progress:** 2/3 tasks complete

   **What was built:**
   Responsive dashboard with sidebar navigation

   **Please verify:**
   1. Run: npm run dev
   2. Visit: http://localhost:3000/dashboard
   3. Desktop (>1024px): Verify sidebar left, content right
   4. Mobile (375px): Verify single column layout

   Type "approved" to continue, or describe issues to fix.
   ```

5. **User responds:**
   - "approved" → resume agent
   - Description of issues → resume agent with feedback

6. **Resume agent:**
   ```
   Task(resume="{agent_id}", prompt="User response: {user_input}")
   ```

7. **Agent continues from checkpoint:**
   - If approved: proceed to next task
   - If issues: fix and re-present checkpoint, or ask for clarification

8. **Repeat until plan completes or user stops**

**Checkpoint in parallel context:**
If a plan in a parallel wave has a checkpoint:
- Spawn as normal
- Agent pauses at checkpoint and returns
- Other parallel agents may complete while waiting
- Handle checkpoint, resume agent
- Wait for all agents to finish before next wave
</step>

<step name="aggregate_results">
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"]
```
</step>

<step name="update_roadmap">
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"
```
</step>

<step name="offer_next">
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`
```
</step>

</process>

<context_efficiency>
**Why this works:**

Orchestrator context usage: ~10-15%
- Read plan frontmatter (small)
- Analyze dependencies (logic, no heavy reads)
- Fill template strings
- Spawn Task calls
- Collect results

Each subagent: Fresh 200k context
- Loads full execute-plan workflow
- Loads templates, references
- Executes plan with full capacity
- Creates SUMMARY, commits

**No polling.** Task tool blocks until completion. No TaskOutput loops.

**No context bleed.** Orchestrator never reads workflow internals. Just paths and results.
</context_efficiency>

<failure_handling>
**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
</failure_handling>

<resumption>
**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
</resumption>