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
{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
{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
{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
1
Discuss
/gsd-discuss-phase N → captures decisions → writes CONTEXT.md2
Plan
/gsd-plan-phase N → researches domain → decomposes work → writes PLAN.md files3
Execute
/gsd-execute-phase N → runs plans in parallel waves → writes code commits and SUMMARY.md files4
Verify
/gsd-verify-work N → runs acceptance tests → writes UAT.md and any fix plans5
Ship
/gsd-ship N → creates GitHub PR → updates STATE.md