155c08facf
* docs(#2197): drop --validate docs for /gsd-plan-phase and /gsd-execute-phase These two commands never parse --validate (silent no-op); the flag is real only for /gsd-quick. Remove the false flag-table rows and CLI examples across COMMANDS.md and the how-to guides (en + ja-JP/zh-CN/ ko-KR/pt-BR mirrors), and correct the manager.flags.execute example from --validate to --cross-ai (a flag execute-phase actually parses). /gsd-quick's real --validate docs are left untouched. Ref #2197 * docs(#2197): add changeset for --validate docs removal --------- Co-authored-by: CI Rebase Check <ci@gsd-redux>
3.5 KiB
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.
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, writeSUMMARY.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