> ## 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. # 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 Finds all PLAN.md files for the phase. Builds dependency graph from plan frontmatter. Independent plans → same wave (parallel) Dependent plans → later waves (sequential) Spawns executor agents for each plan in the wave. Each agent gets fresh 200k context. Atomic git commit after each plan completes. Checks if phase goals and requirements were achieved. ## Command Usage ```bash theme={null} /gsd:execute-phase [flags] ``` ```bash theme={null} /gsd:execute-phase 2 ``` Runs all plans for phase 2 in optimal wave order. ```bash theme={null} /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: ```markdown Wave Execution Example theme={null} ┌─────────────────────────────────────────────────────────────────────┐ │ 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: ```bash Example Git History theme={null} $ 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 ```markdown theme={null} 📋 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... ``` ```markdown theme={null} 🌊 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 ``` ```markdown theme={null} 🌊 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 ``` ```markdown theme={null} ✓ 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 ``` ```markdown theme={null} 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): ```markdown theme={null} ⚠ 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: ```json theme={null} { "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: ```markdown Example: 02-01-SUMMARY.md theme={null} # 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: Were all phase requirements delivered? Does the codebase match the phase goal? Do new components integrate with existing code? Are critical features present and functional? Results saved to `{phase_num}-VERIFICATION.md`. If verification fails: ```markdown theme={null} ❌ 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: All commits go to current branch. ```bash theme={null} git log --oneline abc123f feat(02-03): rate limiting def456g feat(02-02): login endpoint hij789k feat(02-01): registration endpoint ``` Creates a branch per phase: ```bash theme={null} # 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)" ``` Creates one branch for entire milestone: ```bash theme={null} # 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: Manually test features through conversational UAT 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.