msd-core/docs/how-to/execute-a-phase.md

How to execute a phase

Goal: Run a planned phase through wave-based parallel execution and land every plan as an atomic git commit.

Prerequisites: The phase has at least one PLAN.md file. If planning is not yet done, run /gsd-plan-phase N first — see Plan a phase.

---

Run the full phase

/gsd-execute-phase 1

GSD reads the phase's plan files, groups them into dependency waves, and spawns a fresh executor agent per plan. Each executor commits its work atomically before the next wave begins.

Before any agents are dispatched, GSD prints a wave table:

## Execution Plan

Phase 1: Core middleware — 3 plans across 2 wave(s)

| Wave | Plans          | What it builds            |
|------|----------------|---------------------------|
| 1    | 01-01, 01-02   | Core validation function  |
| 2    | 01-03          | Express middleware wrapper |

Wave 1 plans run in parallel (each in an isolated git worktree). Wave 2 waits until all Wave 1 commits are merged.

For the underlying agent coordination model, see Multi-agent orchestration.

---

Run a single wave

If you want to execute only one wave — for example, to inspect Wave 1 output before committing to Wave 2 — use --wave N:

/gsd-execute-phase 1 --wave 2

GSD executes only Wave 2 plans. It first checks that all earlier waves are complete; if any Wave 1 plan is still marked incomplete, it stops and tells you to finish earlier waves first.

---

Validate state before execution

If you suspect the .planning/ directory is out of sync with the filesystem — for example after a crash or an interrupted previous run — pass --validate:

/gsd-execute-phase 1 --validate

GSD runs a state consistency check before spawning any executors. Detected drift is reported and you can accept or correct it before proceeding.

---

Resume a stalled execution

If execution stops partway through — a quota error, a network drop, or a crashed session — the wave-level progress is preserved. GSD checks for a SUMMARY.md file for each plan; plans that have one are skipped automatically when you re-run:

/gsd-execute-phase 1

GSD will skip plans where SUMMARY.md already exists and pick up from the first incomplete plan.

If commits exist but SUMMARY.md is missing (the executor committed but did not write its summary before the session died), GSD surfaces a safe-resume gate and offers three options:

• close out manually — inspect the commits, write SUMMARY.md, then re-run.
• re-execute from scratch — revert or supersede the partial commits before dispatching a new executor.
• mark-and-skip — record the anomaly and move on, only with explicit confirmation.

For systematic failure diagnosis, see Debug a failed execution.

---

Where output lands

After all waves complete, the phase directory contains:

.planning/phases/01-<name>/
  01-01-SUMMARY.md    # What plan 01 built, key files, deviations
  01-02-SUMMARY.md
  01-03-SUMMARY.md
  VERIFICATION.md     # Requirement-by-requirement pass/fail status

STATE.md and ROADMAP.md are updated automatically once all waves are done. VERIFICATION.md is written only when the phase is fully complete.

Git history will show one commit per task (from each executor), followed by tracking commits from the orchestrator.

---

Cross-AI execution

To delegate execution to an external AI CLI (Codex, Gemini, etc.) configured in workflow.cross_ai_command:

/gsd-execute-phase 2 --cross-ai

To force local execution even when cross-AI is enabled in config:

/gsd-execute-phase 2 --no-cross-ai

---

Related

• Plan a phase
• Verify and ship
• Debug a failed execution
• Commands