Wave Execution

Wave 1 (parallel)          Wave 2 (parallel)          Wave 3
┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐
│ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │ │ Plan 04 │ →  │ Plan 05 │
│         │ │         │    │         │ │         │    │         │
│ User    │ │ Product │    │ Orders  │ │ Cart    │    │ Checkout│
│ Model   │ │ Model   │    │ API     │ │ API     │    │ UI      │
└─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘
     │           │              ↑           ↑              ↑
     └───────────┴──────────────┴───────────┘              │
            Dependencies: Plan 03 needs Plan 01            │
                        Plan 04 needs Plan 02              │
                        Plan 05 needs Plans 03 + 04        │

---
phase: 03
plan: 03
wave: 2
depends_on:
  - 03-01
  - 03-02
---

1. Start with all plans at wave 0
2. For each plan:
   a. Find all dependencies (depends_on)
   b. Get max wave of dependencies
   c. Assign this plan to max_wave + 1
3. Repeat until no changes (handle transitive deps)
4. Group plans by wave number

Plan 01: User feature (model + API + UI)
Plan 02: Product feature (model + API + UI)
└─→ Both Wave 1, run in parallel

Plan 01: All models
Plan 02: All APIs (depends on Plan 01)
Plan 03: All UI (depends on Plan 02)
└─→ Wave 1, Wave 2, Wave 3 (sequential)

┌───────────────────────────────────────────────┐
│  /gsd:execute-phase 3                         │
├───────────────────────────────────────────────┤
│  1. Discover plans in phase                   │
│  2. Analyze dependencies, group into waves    │
│  3. Report execution plan to user             │
│  4. FOR EACH WAVE:                            │
│     a. Describe what's being built            │
│     b. Spawn executor agents (parallel)       │
│     c. WAIT for all agents in wave            │
│     d. Spot-check results (SUMMARY, commits)  │
│     e. Report wave completion                 │
│     f. Handle checkpoints (if any)            │
│     g. Proceed to next wave                   │
│  5. Spawn verifier (check goal achievement)   │
│  6. Update ROADMAP, commit                    │
│  7. Route to next action                      │
└───────────────────────────────────────────────┘

// Orchestrator stays lean (10-15% context)
Task(
  subagent_type="gsd-executor",
  prompt="
    <files_to_read>
    Read these files at execution start:
    - .planning/phases/03-auth/03-02-PLAN.md
    - .planning/STATE.md
    - .planning/config.json
    </files_to_read>
  "
)
// Executor loads files with fresh 200K context

{
  "parallelization": {
    "enabled": true
  }
}

03-01 (User model)
  ↓
03-03 (Login API)
  ↓
03-05 (Login UI)

03-02 (Password utils)
  ↓
03-04 (Registration API)

[Wave 1 Start]
  └─ Spawn executor for 03-01 (User model)
  └─ Spawn executor for 03-02 (Password utils)
  └─ WAIT (both running in parallel)
[Wave 1 Complete — 8 minutes elapsed]

[Wave 2 Start]
  └─ Spawn executor for 03-03 (Login API)
  └─ Spawn executor for 03-04 (Registration API)
  └─ WAIT (both running in parallel)
[Wave 2 Complete — 15 minutes elapsed]

[Wave 3 Start]
  └─ Spawn executor for 03-05 (Login UI)
  └─ WAIT
[Wave 3 Complete — 22 minutes elapsed]

[Verification]
  └─ Spawn verifier
  └─ Check: User can log in with email
  └─ Check: User can register new account
  └─ VERIFICATION.md: status = passed

---
phase: 04
plan: 02
autonomous: false  # Has checkpoints
wave: 2
---

<task type="checkpoint" checkpoint_type="human-verify">
  <name>Manual OAuth consent screen setup</name>
  <action>
    Instructions to configure Google OAuth consent screen.
  </action>
  <awaiting>
    User to complete OAuth setup and confirm.
  </awaiting>
</task>

[Wave 2 Start]
  └─ Spawn executor for 04-01 (autonomous)
  └─ Spawn executor for 04-02 (has checkpoint)
  └─ WAIT

[04-01 completes normally → SUMMARY.md]
[04-02 hits checkpoint → RETURNS EARLY]

[Orchestrator presents checkpoint to user]
  "Plan 04-02 paused at Task 2: Manual OAuth setup"
  "Awaiting: User to configure consent screen"
  "Enter 'done' when complete: ___"

[User responds: "done"]

[Orchestrator spawns continuation agent]
  └─ Continuation agent resumes from Task 2
  └─ Completes remaining tasks → SUMMARY.md

[Wave 2 Complete]

[Wave 2 Start]
  └─ Spawn executor for 03-03 (Login API)
  └─ Spawn executor for 03-04 (Registration API)
  └─ WAIT

[03-03 FAILS — missing dependency]
[03-04 completes normally]

[Orchestrator detects failure]
  "Plan 03-03 failed: Missing bcrypt library"
  "Plan 03-04 complete: Registration API"
  
  Options:
  1. Continue with Wave 3 (may cascade failures)
  2. Stop execution (investigate failure)
  3. Retry failed plan

[Wave 1: 03-01 FAILS (User model)]

[Wave 2: 03-03 depends on 03-01]
  → Orchestrator: "Wave 1 failure affects Wave 2 plans"
  → Options: Skip Wave 2, attempt anyway, stop execution

# Phase execution interrupted
# Some plans complete (have SUMMARY.md), others don't

# Re-run the command
/gsd:execute-phase 3

# Orchestrator:
# 1. Discovers all plans
# 2. Checks for SUMMARY.md (completion marker)
# 3. Filters to incomplete plans only
# 4. Recalculates waves from incomplete set
# 5. Continues execution

[All Waves Complete]
  └─ Spawn verifier
  └─ Load: ROADMAP (phase goal), REQUIREMENTS (must-haves)
  └─ Verify: Codebase delivers what phase promised
  └─ Create: VERIFICATION.md

Possible outcomes:
  - status: passed → Phase complete, update roadmap
  - status: human_needed → Manual testing required
  - status: gaps_found → Missing features, offer gap closure

Plan 01: All database models (User, Product, Order)
Plan 02: All API routes (depends on 01)
Plan 03: All UI components (depends on 02)
└─→ 3 waves, sequential only

Plan 01: User feature (model + API + UI)
Plan 02: Product feature (model + API + UI)
Plan 03: Order feature (model + API + UI)
└─→ 1 wave, all parallel