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. </objective>

<execution_context> @{{PLATFORM_ROOT}}/get-shit-done/references/ui-brand.md @{{PLATFORM_ROOT}}/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 </context>

1. •

   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
2. •

   Group by wave

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

   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
   • •Proceed to next wave
4. •

   Aggregate results

   • •Collect summaries from all plans
   • •Report phase completion status
5. •

   Commit any orchestrator corrections Check for uncommitted changes before verification:

   bash

   git status --porcelain
   

   If changes exist: Orchestrator made corrections between executor completions. Commit them:

   bash

   git add -u && git commit -m "fix({phase}): orchestrator corrections"
   

   If clean: Continue to verification.

6. •

   Verify phase goal

   • •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 {{COMMAND_PREFIX}}plan-phase {X} --gaps
7. •

   Update roadmap and state

   • •Update ROADMAP.md, STATE.md
8. •

   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
9. •

   Commit phase completion 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
10. •

    Offer next steps

    • •Route to next action (see <offer_next>) </process>

<offer_next> Output this markdown directly (not as a code block). Route based on status:

Route A: Phase verified, more phases remain

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {Z} COMPLETE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase {Z}: {Name}

{Y} plans executed Goal verified ✓

───────────────────────────────────────────────────────────────

▶ Next Up

Phase {Z+1}: {Name} — {Goal from ROADMAP.md}

{{COMMAND_PREFIX}}discuss-phase {Z+1} — gather context and clarify approach

_{/clear first → fresh context window}

───────────────────────────────────────────────────────────────

Also available:

• •{{COMMAND_PREFIX}}plan-phase {Z+1} — skip discussion, plan directly
• •{{COMMAND_PREFIX}}verify-work {Z} — manual acceptance testing before continuing

───────────────────────────────────────────────────────────────

Route B: Phase verified, milestone complete

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► MILESTONE COMPLETE 🎉 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

v1.0

{N} phases completed All phase goals verified ✓

───────────────────────────────────────────────────────────────

▶ Next Up

Audit milestone — verify requirements, cross-phase integration, E2E flows

{{COMMAND_PREFIX}}audit-milestone

_{/clear first → fresh context window}

───────────────────────────────────────────────────────────────

Also available:

• •{{COMMAND_PREFIX}}verify-work — manual acceptance testing
• •{{COMMAND_PREFIX}}complete-milestone — skip audit, archive directly

───────────────────────────────────────────────────────────────

Route C: Gaps found — need additional planning

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {Z} GAPS FOUND ⚠ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase {Z}: {Name}

Score: {N}/{M} must-haves verified Report: .planning/phases/{phase_dir}/{phase}-VERIFICATION.md

What's Missing

{Extract gap summaries from VERIFICATION.md}

───────────────────────────────────────────────────────────────

▶ Next Up

Plan gap closure — create additional plans to complete the phase

{{COMMAND_PREFIX}}plan-phase {Z} --gaps

_{/clear first → fresh context window}

───────────────────────────────────────────────────────────────

Also available:

• •cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md — see full report
• •{{COMMAND_PREFIX}}verify-work {Z} — manual testing before planning

───────────────────────────────────────────────────────────────

After user runs {{COMMAND_PREFIX}}plan-phase {Z} --gaps:

1. •Planner reads VERIFICATION.md gaps
2. •Creates plans 04, 05, etc. to close gaps
3. •User runs {{COMMAND_PREFIX}}execute-phase {Z} again
4. •Execute-phase runs incomplete plans (04, 05...)
5. •Verifier runs again → loop until passed </offer_next>

<wave_execution> Parallel spawning:

Spawn all plans in a wave with a single message containing multiple Task calls:

Task(prompt="Execute plan at {plan_01_path}\n\nPlan: @{plan_01_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
Task(prompt="Execute plan at {plan_02_path}\n\nPlan: @{plan_02_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
Task(prompt="Execute plan at {plan_03_path}\n\nPlan: @{plan_03_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")

All three run in parallel. Task tool blocks until all complete.

No polling. No background agents. No TaskOutput loops. </wave_execution>

<checkpoint_handling> Plans with autonomous: false have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:

• •Subagent pauses at checkpoint, returns structured state
• •Orchestrator presents to user, collects response
• •Spawns fresh continuation agent (not resume)

See @{{PLATFORM_ROOT}}/get-shit-done/workflows/execute-phase.md step checkpoint_handling for complete details. </checkpoint_handling>

<deviation_rules> During execution, handle discoveries automatically:

1. •Auto-fix bugs - Fix immediately, document in Summary
2. •Auto-add critical - Security/correctness gaps, add and document
3. •Auto-fix blockers - Can't proceed without fix, do it and document
4. •Ask about architectural - Major structural changes, stop and ask user

Only rule 4 requires user intervention. </deviation_rules>

<commit_rules> Per-Task Commits:

After each task completes:

1. •Stage only files modified by that task
2. •Commit with format: {type}({phase}-{plan}): {task-name}
3. •Types: feat, fix, test, refactor, perf, chore
4. •Record commit hash for SUMMARY.md

Plan Metadata Commit:

After all tasks in a plan complete:

1. •Stage plan artifacts only: PLAN.md, SUMMARY.md
2. •Commit with format: docs({phase}-{plan}): complete [plan-name] plan
3. •NO code files (already committed per-task)

Phase Completion Commit:

After all plans in phase complete (step 7):

1. •Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
2. •Commit with format: docs({phase}): complete {phase-name} phase
3. •Bundles all phase-level state updates in one commit

NEVER use:

• •git add .
• •git add -A
• •git add src/ or any broad directory

Always stage files individually. </commit_rules>

<success_criteria>

• • All incomplete plans in phase executed
• • Each plan has SUMMARY.md
• • Phase goal verified (must_haves checked against codebase)
• • VERIFICATION.md created in phase directory
• • STATE.md reflects phase completion
• • ROADMAP.md updated
• • REQUIREMENTS.md updated (phase requirements marked Complete)
• • User informed of next steps </success_criteria>