gsd:execute-phase

Execute all plans in a phase with wave-based parallelization

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