/execute — Parallel Subagent Orchestration

Read the orchestrator file, execute phases by spawning parallel subagents in waves, and run automatic final verification.

Instructions

1. You are a pure orchestrator.

You do NOT edit source files, write code, run tests, or implement anything. You read the plan, spawn subagents, collect results, and update status. If you find yourself about to edit a source file — stop. Spawn a subagent instead.

The only files you write to directly are:

• The orchestrator file (status updates)
• The TodoList (progress tracking)

All code work — implementation, tests, fixes, verification commands — is delegated to subagents via the Task tool.

2. Locate orchestrator.

If $ARGUMENTS is provided, use it as the path or task name to find the orchestrator file.

Otherwise, find the most recently modified *-ORCHESTRATOR.md file in .claude/plans/:

Glob pattern: .claude/plans/*-ORCHESTRATOR.md

Pick the most recently modified match. If none found, report an error and stop:

No orchestrator file found in .claude/plans/.
Run /parallelize first to generate one.

3. Parse orchestrator.

Read the orchestrator file and extract:

• Phases: All ### Phase N: ... sections
• Statuses: The Status: field of each phase (Not Started, In Progress, Complete, Failed)
• Dependencies: The Dependencies: field of each phase
• Wave assignments: The Wave: field of each phase
• Complexity tiers: The Complexity: field of each phase (simple, standard, complex)

Also locate the corresponding PLAN.md file (same task prefix) for reference sections that subagents will need.

4. Create TodoList for execution tracking.

Use TodoWrite to create a persistent checklist that survives compaction. Format:

- [ ] Wave 1: Phase 1 (Theme system) [standard/sonnet]
- [ ] Wave 2: Phase 2 (Toggle) [standard/sonnet] | Phase 3 (Migration) [standard/sonnet]
- [ ] Wave 3: Phase 4 (Integration) [simple/haiku]
- [ ] Final verification (project-wide)

Each entry includes the wave number, phase name(s), complexity tier, and model. Phases within the same wave are separated by | on a single line.

If a TodoList already exists from a prior partial execution, read it first with TodoRead and continue from the first unchecked item.

5. For each wave: execute phases in parallel.

Process waves sequentially (Wave 1, then Wave 2, etc.). Within each wave, execute all phases in parallel.

At the START of each wave, re-read the orchestrator file from disk. This is critical for compaction resilience — if compaction occurred between waves, the re-read restores full state.

For each wave:

5a. Identify phases in this wave that are still "Not Started". Skip any phase already marked "Complete" or "In Progress" (a prior run may have partially completed).

5b. Spawn a background Task per phase using the phase-executor subagent. Configure each task with:

• Model routing based on complexity tier:
  • simple → haiku
  • standard → sonnet
  • complex → sonnet (or override from .claude/plan-config.json if phaseComplex is set to opus)
• Task prompt includes:
  • The full phase instructions from the orchestrator (Implementation Steps, Context Files, Deliverables, Scoped Verification)
  • The relevant Plan Reference section from PLAN.md
  • The validation commands (scoped, not project-wide)
  • The explicit file ownership list ("You own these files: [list]. Only modify these.")
  • The concurrency reminder: "Other subagents are working concurrently. Ignore files that aren't yours. Run only scoped verification commands, not project-wide."

5c. Wait for ALL tasks in the wave to complete. Do not start the next wave until every phase in the current wave has reported back.

5d. Collect results from each completed task. Update the orchestrator file with completion status:

• Set Status: to Complete or Failed
• Set Completed by: to the model that executed it
• Only the parent orchestrator (you) writes to the orchestrator file — never subagents.

5e. Check off the wave in the TodoList using TodoWrite.

Parallel phase batching: If a wave has more parallel phases than maxParallelPhases (default: 5, configurable in .claude/plan-config.json), batch them: run up to maxParallelPhases at a time, wait for completion, then run the next batch within the same wave. This prevents overloading the Task tool while maintaining maximum parallelism.

6. After all phases: spawn verification subagent.

Once every phase is marked Complete (or Failed), spawn a final verification subagent (Sonnet) to run project-wide validation:

• Read the PLAN.md and verify each phase's deliverables are actually implemented
• Run full project-wide validation commands (test, lint, typecheck) from .claude/plan-config.json or auto-detected
• Report structured results: which checks passed, which failed, and what specifically failed

Check off "Final verification" in the TodoList.

7. Report results.

Present a summary of the entire execution:

═══ Execution Complete ═══

Wave 1: Phase 1 (Theme system) ✓
Wave 2: Phase 2 (Toggle) ✓ | Phase 3 (Migration) ✓
Wave 3: Phase 4 (Integration) ✓

Final Verification:
  Tests: ✓ (47 passed)
  Lint: ✓ (clean)
  Typecheck: ✓ (clean)

✅ All phases complete. Ready for your review and commit.

If any phase failed or verification found issues, report them clearly with specifics (which files, which tests, what errors). Do NOT attempt to fix issues inline — you are the orchestrator. Report the problems and let the user decide next steps.

If phases failed:

═══ Execution Complete (with issues) ═══

Wave 1: Phase 1 (Theme system) ✓
Wave 2: Phase 2 (Toggle) ✗ FAILED | Phase 3 (Migration) ✓

Phase 2 failure details:
  - useThemeToggle.test.ts: 2 tests failing (toggle persistence)
  - ESLint: 1 error in ThemeToggle.tsx (unused import)

Recommendation: Fix Phase 2 issues and re-run /execute to retry failed phases.

---

Compaction Resilience

State lives in the orchestrator file and the TodoList, not in memory. Each wave re-reads from disk before starting. Running /execute again on a partially-complete orchestrator picks up from the next unfinished wave automatically.

If compaction occurs mid-execution:

1. The PreCompact hook outputs active plan state to the post-compaction context.
2. After compaction, /execute can be re-invoked. It reads the orchestrator, sees which phases are Complete, and resumes from the next Not Started wave.
3. The TodoList provides a secondary checkpoint — TodoRead shows which waves were checked off.

This design means no execution progress is ever lost to compaction.