Skip to main content

​
Overview

The gsd:execute-phase command executes all plans in a phase using wave-based parallel execution. The orchestrator stays lean by discovering plans, analyzing dependencies, grouping into waves, spawning subagents, and collecting results.

​
Usage

/gsd:execute-phase <phase-number>

/gsd:execute-phase 3 --gaps-only

​
Parameters

​
phase-number
number
required
The phase number to execute (e.g., 1, 2, 3). Must exist in your ROADMAP.md and have a PLAN.md file.
​
--gaps-only
flag
Execute only gap closure plans (plans with gap_closure: true in frontmatter). Use after verify-work creates fix plans.

​
How It Works

The orchestrator follows an efficient workflow:
  1. Discover Plans - Finds all PLAN.md files for the phase
  2. Analyze Dependencies - Determines which plans depend on others
  3. Group into Waves - Creates parallel execution groups
  4. Spawn Subagents - Launches fresh agent per plan (100% context budget each)
  5. Collect Results - Gathers outcomes and updates state
Each subagent gets 100% fresh context budget. The orchestrator uses only ~15% of its budget for coordination.

​
Wave-Based Execution

Plans are executed in waves based on dependencies: Wave 1: All plans with no dependencies (can run in parallel) Wave 2: Plans that depend on Wave 1 completions Wave 3: Plans that depend on Wave 2 completions …and so on.

​
Example Wave Structure

Wave 1 (parallel):
  - 3.1-setup-database.md
  - 3.2-create-api-types.md
  - 3.3-setup-auth-middleware.md

Wave 2 (parallel, after Wave 1):
  - 3.4-implement-user-endpoints.md (depends on 3.1, 3.2)
  - 3.5-implement-auth-flow.md (depends on 3.3)

Wave 3 (after Wave 2):
  - 3.6-integration-tests.md (depends on 3.4, 3.5)
Within each wave, all plans execute in parallel for maximum efficiency.

​
Context Budget Management

The execution model is designed for efficiency:
  • Orchestrator: Uses ~15% context for coordination
  • Each Subagent: Gets 100% fresh context budget
  • Isolation: Each plan execution is independent

​
Gap Closure Mode

After running verify-work, you may have gaps to fix: 
/gsd:execute-phase 3 --gaps-only
This mode:
  • Executes only plans marked with gap_closure: true
  • Skips regular implementation plans
  • Used for targeted fixes after verification
Gap closure plans are created by the verify-work command when issues are found. Don’t use —gaps-only unless you’ve run verification first.

​
Files Created/Modified

​
.planning/STATE.md
file
Updated with execution progress, completion status, and checkpoints
​
source code
various
All source code, tests, and documentation specified in the plans

​
Checkpoint Handling

The system tracks execution state:
  • Wave Checkpoints - Progress saved after each wave completes
  • Plan Status - Individual plan success/failure tracking
  • Resume Capability - Can resume from last checkpoint on failure

​
Examples

​
Execute Full Phase

/gsd:execute-phase 2
Executes all plans in phase 2 using wave-based parallelization.

​
Execute Gap Fixes Only

/gsd:execute-phase 4 --gaps-only
After verification found issues in phase 4, execute only the fix plans.

​
Typical Flow

# 1. Plan the phase
/gsd:plan-phase 3

# 2. Execute the phase
/gsd:execute-phase 3

# 3. Verify the work
/gsd:verify-work 3

# 4. If gaps found, execute fixes
/gsd:execute-phase 3 --gaps-only

# 5. Verify again
/gsd:verify-work 3

​
Workflow Gates

All workflow gates are preserved:
  • Wave Execution - Dependency-based parallel execution
  • Checkpoint Handling - Progress tracking and resume capability
  • Verification - Post-execution validation
  • State Updates - Automatic STATE.md updates
  • Routing - Next-step suggestions

​
Error Handling

When a plan fails:
  1. Wave Continues - Other plans in the wave complete
  2. Dependent Waves Block - Plans depending on failed plan don’t execute
  3. State Updated - Failure recorded in STATE.md
  4. User Notified - Clear error message with context
You can fix failed plans and re-run execute-phase. The system will skip completed plans and resume from failures.

​
Next Steps

After executing a phase: Verify the work: 
/gsd:verify-work <phase>
This runs conversational UAT to confirm features work as expected. Move to next phase: 
/gsd:plan-phase <next-phase>

​
Allowed Tools

This command has access to:
  • Read - Read plan files and context
  • Write - Create new files
  • Edit - Modify existing files
  • Glob - Find files by pattern
  • Grep - Search file contents
  • Bash - Execute shell commands
  • Task - Spawn subagents for each plan
  • TodoWrite - Track execution progress
  • AskUserQuestion - Request clarification when needed