.planning/ directory at your project root.
/gsd-new-project
Initialize a new project with deep context gathering.
Syntax
| Artifact | Purpose |
|---|---|
.planning/PROJECT.md | Project context and goals |
.planning/config.json | Workflow preferences |
.planning/REQUIREMENTS.md | Scoped requirements |
.planning/ROADMAP.md | Phase structure |
.planning/STATE.md | Project memory |
.planning/research/ | Domain research (when research runs) |
Automatic mode. Skips interactive questioning and runs research → requirements → roadmap without further interaction. Pass your idea document via an
@ reference, for example --auto @brief.md./gsd-plan-phase 1 to begin the first phase.
/gsd-discuss-phase N
Gather phase context through adaptive questioning before planning.
Syntax
PROJECT.md, REQUIREMENTS.md, STATE.md, and any earlier CONTEXT.md files. Scouts the codebase for reusable assets, identifies unresolved gray areas, guides you through a deep-dive on any you choose to discuss, and writes a CONTEXT.md that gives the planner and researcher everything they need — so they never have to ask you the same question twice.
Produces
{phase_num}-CONTEXT.md — locked decisions and scope guidance for downstream agents.
Flags
Discuss all identified gray areas in one session rather than letting you pick a subset.
Auto-answer discussion questions using existing context. Useful in autonomous or CI pipelines where interactive input is not available.
Group related gray areas and address them together instead of one at a time.
Run a deeper analysis pass on the codebase before presenting gray areas.
Power mode. Runs an extended questioning protocol with richer probing — best for complex or ambiguous phases.
List the assumptions implicit in the current phase plan instead of opening a discussion session.
/gsd-ui-phase N
Generate a UI design contract for frontend phases.
Syntax
gsd-ui-researcher and a gsd-ui-checker to produce a UI-SPEC.md design contract for a frontend phase. Run this before /gsd-plan-phase on any phase that involves user-facing components so the planner has a verified UI specification to work from.
Produces
{phase_num}-UI-SPEC.md — design contract covering component structure, interaction patterns, and brand alignment.
/gsd-plan-phase N
Research, plan, and verify a phase — the core planning step.
Syntax
gsd-planner agent → gsd-plan-checker verification loop → plan approval. By default it auto-detects the next unplanned phase if you omit the phase number.
Produces
{phase_num}-PLAN.md files containing executable prompts for each task in the phase, plus RESEARCH.md when research runs.
Flags
Force-refresh research even when a
RESEARCH.md already exists for this phase.Skip research entirely and go straight to planning. Use when the implementation approach is already clear.
Research-only mode. Spawns the researcher for phase
N, writes RESEARCH.md, and exits before the planner runs. Useful for cross-phase research or iterating on research alone without replanning.Gap-closure mode. Reads
VERIFICATION.md and re-plans only to address verified gaps. Skips research.Path to a PRD or acceptance-criteria file. Parses requirements into
CONTEXT.md automatically, skipping the discuss phase entirely. Example: --prd docs/prd.md.Path or glob of ADR files to use instead of a discuss session. Parses locked decisions and scope fences into
CONTEXT.md. Example: --ingest docs/adr/*.md.Vertical MVP mode. Organizes tasks as feature slices (UI → API → DB) instead of horizontal layers. On Phase 1 of a new project, also emits a
SKELETON.md walking skeleton document. Persist this mode for a phase by adding **Mode:** mvp to ROADMAP.md.TDD mode. Instructs the planner to organize tasks around test-first RED-GREEN cycles.
Replan incorporating cross-AI feedback from a
REVIEWS.md file produced by /gsd-review.Skip the plan-checker verification loop and present the plan immediately after the planner completes.
/gsd-plan-review-convergence N
Run a cross-AI convergence loop until no HIGH-severity concerns remain.
Syntax
--reviews, then re-reviews. Stops when no HIGH concerns remain or the cycle cap is reached. Requires workflow.plan_review_convergence=true in your config.
Flags
Use Codex CLI as the reviewer. Default when no reviewer flag is specified.
Use Gemini CLI as the reviewer.
Use a separate Claude CLI session as the reviewer.
Use OpenCode as the reviewer.
Use a local Ollama server (OpenAI-compatible, default host
http://localhost:11434). Configure the model via review.models.ollama.Use a local LM Studio server (default host
http://localhost:1234). Configure the model via review.models.lm_studio.Use a local llama.cpp server (default host
http://localhost:8080). Configure the model via review.models.llama_cpp.Use every available CLI and running local model server.
Maximum number of replan → review cycles before escalating to you. Default:
3./gsd-execute-phase N
Execute all plans in a phase with wave-based parallelization.
Syntax
Execute only Wave
N of the phase. Use to pace execution, manage API usage limits, or perform a staged rollout.Execute only gap-closure plans — those with
gap_closure: true in their frontmatter. Run this after /gsd-verify-work creates fix plans.Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gap closures.
/gsd-verify-work N
Validate built features through conversational UAT with auto-diagnosis.
Syntax
UAT.md file, and when issues are found automatically diagnoses root causes, produces fix plans, and queues them for /gsd-execute-phase. If you omit the phase number it checks for an active session or prompts you.
Produces
{phase_num}-UAT.md — test results with pass/fail status. When issues are found: diagnosed gap descriptions and verified fix plans ready for re-execution.
/gsd-ship N
Create a pull request and prepare the phase for merge.
Syntax
Open the pull request as a draft instead of a ready-for-review PR. Use when you want the branch visible to your team but not yet requesting review.
/gsd-progress
Check where you are and what comes next.
Syntax
--next it advances automatically. With --do it maps natural language intent to the most appropriate GSD command, confirms the match, and hands off.
Flags
Automatically advance to the next logical workflow step. Scans all prior phases for incomplete work before routing. Add
--force to bypass safety gates.Like
--next, but after the determined step completes, re-invokes /gsd-progress --next --auto automatically to keep chaining steps. Enables hands-free plan → execute → verify progression until a blocking decision is required.Smart dispatcher. Matches freeform natural language to the best GSD command using routing rules, confirms the match, then hands off execution.
Append a 6-check integrity audit after the standard progress report.
/gsd-autonomous
Run all remaining phases without manual intervention.
Syntax
Start from phase
N instead of the first incomplete phase.Stop after phase
N completes instead of continuing to the end of the milestone.Execute only phase
N — single-phase mode.Run the discuss step inline so you can answer questions directly, then dispatch plan and execute as background agents. Keeps the main context lean while preserving your input on decisions.
Use plain-text numbered lists instead of interactive TUI menus. Required for
/rc remote sessions.