gsd:execute-phase

Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.

Context budget: ~15% orchestrator, 100% fresh per subagent.

<execution_context> @./.claude/get-shit-done/references/ui-brand.md @./.claude/get-shit-done/workflows/execute-phase.md </execution_context>

Flags:

• --gaps-only — Execute only gap closure plans (plans with gap_closure: true in frontmatter). Use after verify-work creates fix plans.

@.planning/ROADMAP.md @.planning/STATE.md

Read model profile for agent spawning:

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to "balanced" if not set.

Model lookup table:

Agent	quality	balanced	budget
gsd-executor	opus	sonnet	sonnet
gsd-verifier	sonnet	sonnet	haiku

Store resolved models for use in Task calls below.

1. Validate phase exists

   • Find phase directory matching argument
   • Count PLAN.md files
   • Error if no plans found

2. Discover plans

   • List all *-PLAN.md files in phase directory
   • Check which have *-SUMMARY.md (already complete)
   • If --gaps-only: filter to only plans with gap_closure: true
   • Build list of incomplete plans

3. Group by wave

   • Read wave from each plan's frontmatter
   • Group plans by wave number
   • Report wave structure to user

4. Execute waves For each wave in order:

   • Spawn gsd-executor for each plan in wave (parallel Task calls)
   • Wait for completion (Task blocks)
   • Verify SUMMARYs created and spot-check claims
   • Proceed to next wave

5. Aggregate results

   • Collect summaries from all plans
   • Report phase completion status

6. Commit any orchestrator corrections Check for uncommitted changes before verification:

   git status --porcelain
   

   If changes exist: Orchestrator made corrections between executor completions. Stage and commit them individually:

   # Stage each modified file individually (never use git add -u, git add ., or git add -A)
   git status --porcelain | grep '^ M' | cut -c4- | while read file; do
     git add "$file"
   done
   git commit -m "fix({phase}): orchestrator corrections"
   

   If clean: Continue to verification.

7. Verify phase goal Check config: WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")

   If workflow.verifier is false: Skip to step 8 (treat as passed).

   Otherwise:

   • Spawn gsd-verifier subagent with phase directory and goal
   • Verifier checks must_haves against actual codebase (not SUMMARY claims)
   • Creates VERIFICATION.md with detailed report
   • Route by status:
     • passed → continue to step 8
     • human_needed → present items, get approval or feedback
     • gaps_found → present gaps, offer /gsd:plan-phase {X} --gaps

8. Update roadmap and state

   • Update ROADMAP.md, STATE.md

9. Update requirements Mark phase requirements as Complete:

   • Read ROADMAP.md, find this phase's Requirements: line (e.g., "AUTH-01, AUTH-02")
   • Read REQUIREMENTS.md traceability table
   • For each REQ-ID in this phase: change Status from "Pending" to "Complete"
   • Write updated REQUIREMENTS.md
   • Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line

10. Commit phase completion Check COMMIT_PLANNING_DOCS from config.json (default: true). If false: Skip git operations for .planning/ files. If true: Bundle all phase metadata updates in one commit:

    • Stage: git add .planning/ROADMAP.md .planning/STATE.md
    • Stage REQUIREMENTS.md if updated: git add .planning/REQUIREMENTS.md
    • Commit: docs({phase}): complete {phase-name} phase