> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
/gsd:execute-phase <phase-number>
```

```bash theme={null}
/gsd:execute-phase 3 --gaps-only
```

## Parameters

<ParamField path="phase-number" type="number" required>
  The phase number to execute (e.g., 1, 2, 3). Must exist in your ROADMAP.md and have a PLAN.md file.
</ParamField>

<ParamField path="--gaps-only" type="flag">
  Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
</ParamField>

## 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

<Info>
  Each subagent gets 100% fresh context budget. The orchestrator uses only \~15% of its budget for coordination.
</Info>

## 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)
```

<Note>
  Within each wave, all plans execute in parallel for maximum efficiency.
</Note>

## 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:

```bash theme={null}
/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

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

## Files Created/Modified

<ParamField path=".planning/STATE.md" type="file">
  Updated with execution progress, completion status, and checkpoints
</ParamField>

<ParamField path="source code" type="various">
  All source code, tests, and documentation specified in the plans
</ParamField>

## 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

```bash theme={null}
/gsd:execute-phase 2
```

Executes all plans in phase 2 using wave-based parallelization.

### Execute Gap Fixes Only

```bash theme={null}
/gsd:execute-phase 4 --gaps-only
```

After verification found issues in phase 4, execute only the fix plans.

### Typical Flow

```bash theme={null}
# 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

<Info>
  You can fix failed plans and re-run execute-phase. The system will skip completed plans and resume from failures.
</Info>

## Next Steps

After executing a phase:

**Verify the work**:

```bash theme={null}
/gsd:verify-work <phase>
```

This runs conversational UAT to confirm features work as expected.

**Move to next phase**:

```bash theme={null}
/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