Execute Phase Plans

Run plans in parallel waves with atomic commits and fresh context

Overview

The /gsd:execute-phase command runs all plans for a phase using wave-based parallelization. Each plan executes in a fresh 200k token context window, eliminating context rot.

What It Does

1. Discover Plans

   Finds all PLAN.md files for the phase.

2. Analyze Dependencies

   Builds dependency graph from plan frontmatter.

3. Group Into Waves

   Independent plans → same wave (parallel) Dependent plans → later waves (sequential)

4. Execute Each Wave

   Spawns executor agents for each plan in the wave. Each agent gets fresh 200k context.

5. Commit Per Plan

   Atomic git commit after each plan completes.

6. Verify Phase

   Checks if phase goals and requirements were achieved.

Command Usage

/gsd:execute-phase <phase-number> [flags]

Execute All Plans

/gsd:execute-phase 2

Runs all plans for phase 2 in optimal wave order.

Execute Gap Fixes Only

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

Runs only plans marked with gap_closure: true in frontmatter.

Use after /gsd:verify-work creates fix plans for failures.

Wave-Based Execution

Plans are grouped into waves based on dependencies:

Wave Execution Example

┌─────────────────────────────────────────────────────────────────────┐
│  PHASE 2 EXECUTION: User Authentication                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3       │
│  ┌─────────┐ ┌─────────┐    ┌─────────┐               ┌─────────┐  │
│  │ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │            →  │ Plan 04 │  │
│  │         │ │         │    │         │               │         │  │
│  │Register │ │  Login  │    │  Rate   │               │  Tests  │  │
│  │ API     │ │  API    │    │Limiting │               │         │  │
│  └─────────┘ └─────────┘    └─────────┘               └─────────┘  │
│       │           │              ↑                         ↑        │
│       └───────────┴──────────────┘                         │        │
│              Plan 03 depends on 01 + 02                    │        │
│              Plan 04 depends on all previous               │        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Why Waves Matter

• Independent plans → Same wave → Run simultaneously → Faster completion
• Dependent plans → Later wave → Wait for dependencies → Correct order
• File conflicts → Detected and serialized automatically

Design phases with vertical slices (feature end-to-end) rather than horizontal layers (all models, then all APIs). Vertical slices parallelize better.

Fresh Context Per Plan

Each executor agent starts with:

• 200k tokens available - Full context budget
• Zero accumulated garbage - No prior conversation history
• Focused context - Only loads what’s needed for this plan

Context loaded per agent:

• PROJECT.md - Project vision
• {phase_num}-CONTEXT.md - Implementation preferences
• {phase_num}-RESEARCH.md - Domain knowledge
• {phase_num}-{N}-PLAN.md - The specific plan to execute
• STATE.md - Current decisions and blockers

This is why quality stays high. No context rot, no “I’ll be more concise”, no degradation.

Atomic Git Commits

Each plan gets its own commit immediately after completion:

Example Git History

$ git log --oneline

abc123f docs(02-03): complete rate limiting plan
def456g feat(02-03): add rate limiting middleware
hij789k feat(02-02): implement login endpoint
lmn012o feat(02-02): add session management
pqr345s feat(02-01): create registration endpoint
stu678v feat(02-01): add password validation

Commit format: type(phase-plan): description

• feat - New functionality
• fix - Bug fix
• docs - Documentation or completion
• refactor - Code restructuring
• test - Test addition/update

Benefits

• Git bisect finds exact failing task
• Selective revert - Each task independently revertable
• Clear history - Future Claude sessions understand what happened
• Better observability - Track progress at task granularity

Atomic commits are invaluable for debugging. If something breaks, git bisect pinpoints the exact task that caused it.

Execution Flow

1. Pre-flight Checks

   📋 Phase 2: User Authentication
   
   Plans found:
   - 02-01-PLAN.md: User Registration Endpoint (4 tasks)
   - 02-02-PLAN.md: Login and Session Management (5 tasks)
   - 02-03-PLAN.md: Rate Limiting Middleware (2 tasks)
   
   Analyzing dependencies...
   Building wave structure...
   
2. Wave 1 Execution

   🌊 Wave 1: 2 plans (parallel)
   
   Spawning executor agents:
   - Agent 1: Plan 02-01 (Registration)
   - Agent 2: Plan 02-02 (Login)
   
   [Agent 1] ✓ Task 1: Create registration API route
   [Agent 1] ✓ Task 2: Add email validation
   [Agent 2] ✓ Task 1: Create login API route
   [Agent 1] ✓ Task 3: Add password validation
   [Agent 2] ✓ Task 2: Implement session creation
   [Agent 1] ✓ Task 4: Write registration tests
   [Agent 2] ✓ Task 3: Add session middleware
   [Agent 2] ✓ Task 4: Handle token refresh
   [Agent 2] ✓ Task 5: Write login tests
   
   ✓ Wave 1 complete
   Commits:
   - abc123f feat(02-01): complete user registration endpoint
   - def456g feat(02-02): complete login and session management
   
3. Wave 2 Execution

   🌊 Wave 2: 1 plan
   
   Spawning executor agent:
   - Agent 3: Plan 02-03 (Rate Limiting)
   
   [Agent 3] ✓ Task 1: Create rate limit middleware
   [Agent 3] ✓ Task 2: Apply to auth endpoints
   
   ✓ Wave 2 complete
   Commits:
   - hij789k feat(02-03): complete rate limiting middleware
   
4. Phase Verification

   ✓ Phase 2 execution complete
   
   Verifying phase goals...
   
   ✓ Users can register with email/password
   ✓ Users can log in securely
   ✓ Sessions persist across requests
   ✓ Rate limiting prevents abuse
   
   ✓ All requirements met:
   - REQ-004: User registration
   - REQ-005: Rate limiting
   - REQ-006: Secure sessions
   
   Created: 02-VERIFICATION.md
   
5. Next Steps

   Next steps:
   - /gsd:verify-work 2 - Manual testing of features
   - /gsd:discuss-phase 3 - Start next phase
   - /gsd:progress - Check overall status
   

Checkpoint Handling

If execution is interrupted (crash, timeout, user cancellation):

⚠ Execution interrupted during Wave 2

Completed:
- Wave 1: 02-01 ✓, 02-02 ✓

Incomplete:
- Wave 2: 02-03 (in progress)
- Wave 3: 02-04 (not started)

Checkpoint saved. Resume with:
/gsd:execute-phase 2

Re-running the command resumes from the last checkpoint:

• Completed plans are skipped
• In-progress plan restarts from beginning
• Uncommitted work is preserved

If a plan partially completes, the executor will restart it. Ensure tasks are idempotent or use git to inspect changes before re-running.

Parallel Execution Configuration

Control parallelization via config:

{
  "parallelization": {
    "enabled": true  // Set false to run plans sequentially
  }
}

Disable parallel execution if:

• Working on a slow machine
• Debugging execution issues
• File conflicts occur frequently

Model Selection

Executor agents use models based on your profile:

Profile	Execution Model	Characteristics
quality	Opus	Best code quality, highest cost
balanced	Sonnet	Good quality, reasonable cost (default)
budget	Sonnet	Faster execution, lower cost

Set profile with /gsd:set-profile or configure in /gsd:settings.

Plan Summaries

After each plan completes, a SUMMARY.md is created:

Example: 02-01-SUMMARY.md

# Plan 01 Summary: User Registration Endpoint

## Completed Tasks

### Task 1: Create registration API route
- Created: `src/app/api/auth/register/route.ts`
- Validates email and password
- Hashes password with bcrypt (12 rounds)
- Returns 201 on success, 400/409 on errors

### Task 2: Add email validation
- Created: `src/lib/validation.ts` (email validation)
- Rejects invalid formats
- Exported `isValidEmail` function

### Task 3: Add password validation
- Updated: `src/lib/validation.ts`
- Min 8 chars, uppercase, number, special char
- Exported `isValidPassword` function

### Task 4: Write registration tests
- Created: `tests/api/auth/register.test.ts`
- Tests: success, duplicate email, validation errors
- All tests passing

## Files Changed
- src/app/api/auth/register/route.ts (new)
- src/lib/validation.ts (new)
- tests/api/auth/register.test.ts (new)

## Git Commits
- abc123f feat(02-01): complete user registration endpoint

## Verification
✓ POST /api/auth/register with valid data returns 201
✓ POST with duplicate email returns 409
✓ POST with weak password returns 400
✓ Password hashed in database (not plain text)
✓ All tests pass

## Notes
- Used bcrypt instead of argon2 (better Node.js support)
- Email validation does not check MX records (marked as nice-to-have)
- Rate limiting deferred to Plan 03

Summaries provide:

• Audit trail of what was built
• Context for future phases
• Debugging starting point if issues arise

Phase Verification

After all plans complete, automatic verification checks:

1. Requirements Coverage

   Were all phase requirements delivered?

2. Goal Achievement

   Does the codebase match the phase goal?

3. Integration Points

   Do new components integrate with existing code?

4. Must-Have Validation

   Are critical features present and functional?

Results saved to {phase_num}-VERIFICATION.md.

If verification fails:

❌ Phase verification found gaps:

- REQ-005: Rate limiting not applied to all endpoints
- Integration: Login endpoint not connected to dashboard

Recommendation:
Run /gsd:verify-work 2 to test manually, or
Run /gsd:plan-phase 2 --gaps to create fix plans

Automatic verification catches obvious issues. Manual verification with /gsd:verify-work tests actual user workflows.

Files Created

After execution, your .planning/ directory has:

.planning/
├── 02-01-PLAN.md
├── 02-01-SUMMARY.md       # New
├── 02-02-PLAN.md
├── 02-02-SUMMARY.md       # New
├── 02-03-PLAN.md
├── 02-03-SUMMARY.md       # New
└── 02-VERIFICATION.md     # New

Git Branching

If you’ve configured git branching strategy:

None (Default)

All commits go to current branch.

git log --oneline
abc123f feat(02-03): rate limiting
def456g feat(02-02): login endpoint
hij789k feat(02-01): registration endpoint

Phase Branching

Creates a branch per phase:

# Execution creates and switches to branch
git checkout -b gsd/phase-02-user-authentication

# All commits go to this branch
git log --oneline
abc123f feat(02-03): rate limiting
def456g feat(02-02): login endpoint
hij789k feat(02-01): registration endpoint

# After phase completes, offers merge
git checkout main
git merge --squash gsd/phase-02-user-authentication
git commit -m "feat: add user authentication (phase 02)"

Milestone Branching

Creates one branch for entire milestone:

# First phase creates branch
git checkout -b gsd/v1.0-mvp

# All phases commit to this branch
# At milestone completion, merge to main

Configure branching in /gsd:settings or .planning/config.json.

Next Steps

After execution completes:

Verify Work

Manually test features through conversational UAT

Next Phase

Start discussing the next phase

Tips

Don’t interrupt execution. Let waves complete. Checkpoints work but restarting wastes tokens.

Monitor the first wave. If plans fail immediately, pause and check for missing dependencies or unclear instructions.

Review summaries. They tell you exactly what was built and reveal if the executor misunderstood something.

If multiple plans modify the same file, they’ll be serialized automatically. This can slow execution - consider splitting files or merging plans.