Step 1 — Discuss the phase
Before any planning begins, run/gsd-discuss-phase N to surface implementation decisions that would otherwise become hidden assumptions inside a plan. The command asks targeted questions about the phase, records your answers, and writes a structured context document for the planner to consume.
Flag reference
Flag reference
| Flag | Effect |
|---|---|
--all | Skip area selection and discuss every gray area interactively |
--auto | Auto-select recommended defaults for all questions; no user input required |
--batch | Group related questions together for faster batch intake |
--analyze | Adds trade-off analysis to each decision before recording the answer |
--power | Reads a pre-prepared answers file and applies answers in bulk |
--assumptions | Generates a list of Claude’s current assumptions about the phase without an interactive session |
{phase}-CONTEXT.md (structured implementation decisions), {phase}-DISCUSSION-LOG.md (full audit trail of the session)
Step 2 — Plan the phase
Run/gsd-plan-phase N to research the problem domain, decompose work into executable plans, and verify that each plan fits within a fresh 200k-token context window. The planner reads your ROADMAP, REQUIREMENTS, and CONTEXT documents and produces one PLAN.md per parallel execution wave.
Flag reference
Flag reference
| Flag | Effect |
|---|---|
--skip-research | Skip domain research (useful when the domain is well understood) |
--research | Force re-research even when RESEARCH.md already exists |
--gaps | Gap-closure mode — reads VERIFICATION.md to address open issues, skips research |
--prd <file> | Use a PRD file as phase context instead of the discuss-phase output |
--mvp | Planner organizes tasks as vertical feature slices (UI→API→DB) |
--tdd | Apply red-green-refactor sequencing to eligible behavior-adding tasks |
--granularity <coarse|standard|fine> | Override planning granularity for this invocation only |
--bounce | Run external plan validation script after planning |
--reviews | Feed REVIEWS.md cross-AI feedback back into replanning |
{phase}-RESEARCH.md, one or more {phase}-{N}-PLAN.md files, {phase}-VALIDATION.md
Set
workflow.research: false in config.json to permanently skip research for all phases. You can also skip it per-run with --skip-research without changing config.Step 3 — Execute the phase
Run/gsd-execute-phase N to execute all plans in the phase. GSD groups plans into dependency-ordered waves and runs each wave in parallel using git worktrees, so independent plans execute simultaneously without conflicting. Each executor agent starts with a clean context window and the full plan as its sole input.
Flag reference
Flag reference
| Flag | Effect |
|---|---|
--wave N | Execute only the specified wave; useful for resuming after an interruption |
--gaps-only | Execute only gap-closure plans (those created by verify-work to fix failing requirements) |
--interactive | Execute plans sequentially inline with user checkpoints between tasks; lower token usage, pair-programming style |
{phase}-{N}-SUMMARY.md files, git commits for all code changes, and {phase}-VERIFICATION.md when the phase finishes
Wave-based parallelization uses git worktrees by default. If your environment does not support worktrees, set
workflow.use_worktrees: false in config.json to fall back to sequential execution.Step 4 — Verify the work
Run/gsd-verify-work N to perform user acceptance testing against the phase goals. The verifier walks through what was built, checks each requirement from CONTEXT.md and REQUIREMENTS.md, and generates fix plans for anything that did not meet the acceptance criteria.
{phase}-UAT.md with acceptance status per requirement; fix plans for any failures that require remediation before shipping
Step 5 — Ship the phase
Run/gsd-ship N to create a GitHub pull request from the completed phase work. GSD generates a rich PR body from your planning artifacts — requirements addressed, key decisions, verification evidence — so reviewers have full context without reading the planning files directly.
gh CLI installed and authenticated, phase verified by /gsd-verify-work
Produces: GitHub PR with auto-generated body, STATE.md updated to mark the phase as shipped
Tracking progress
Use/gsd-progress at any point to see where you are in the lifecycle and what the recommended next step is.
--next
Reads STATE.md and automatically dispatches the next logical command — discuss, plan, execute, verify, or ship — without asking.
--do
Accepts a freeform description of what you want to do and routes it to the most appropriate GSD command.
--forensic
Appends a six-check integrity audit: STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking TODOs, and uncommitted code.
Complete lifecycle at a glance
Execute
/gsd-execute-phase N → runs plans in parallel waves → writes code commits and SUMMARY.md files