GSD Command Reference

Command syntax, flags, options, and examples for stable commands. For feature details, see Feature Reference. For workflow walkthroughs, see User Guide.

Command Syntax

• Claude Code / Gemini / Copilot: /gsd-command-name [args]
• OpenCode / Kilo: /gsd-command-name [args]
• Codex: $gsd-command-name [args]

Core Workflow Commands

/gsd-new-project

Initialize a new project with deep context gathering.

Prerequisites: No existing .planning/PROJECT.md Produces: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json, research/, CLAUDE.md

/gsd-new-project                    # Interactive mode
/gsd-new-project --auto @prd.md     # Auto-extract from PRD

/gsd-workspace

Manage GSD workspaces — create, list, or remove isolated workspace environments with repo copies and independent .planning/ directories.

Use cases:

• Multi-repo: work on a subset of repos with isolated GSD state
• Feature isolation: --repos . creates a worktree of the current repo

Produces: WORKSPACE.md, .planning/, repo copies (worktrees or clones)

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
/gsd-workspace --new --name feature-b --repos . --strategy worktree  # Same-repo isolation
/gsd-workspace --list
/gsd-workspace --remove feature-b

/gsd-discuss-phase

Gather phase context through adaptive questioning before planning.

Prerequisites: .planning/ROADMAP.md exists Produces: {phase}-CONTEXT.md, {phase}-DISCUSSION-LOG.md (audit trail)

/gsd-discuss-phase 1                # Interactive discussion for phase 1
/gsd-discuss-phase 1 --all          # Discuss all gray areas without selection step
/gsd-discuss-phase 3 --auto         # Auto-select defaults for phase 3
/gsd-discuss-phase --batch          # Batch mode for current phase
/gsd-discuss-phase 2 --analyze      # Discussion with trade-off analysis
/gsd-discuss-phase 1 --power        # Bulk answers from file

/gsd-ui-phase

Generate UI design contract for frontend phases.

Prerequisites: .planning/ROADMAP.md exists, phase has frontend/UI work Produces: {phase}-UI-SPEC.md

/gsd-ui-phase 2                     # Design contract for phase 2

/gsd-plan-phase

Research, plan, and verify a phase.

Prerequisites: .planning/ROADMAP.md exists Produces: {phase}-RESEARCH.md, {phase}-{N}-PLAN.md, {phase}-VALIDATION.md

Research-only mode (--research-phase <N>):

• No modifier: prompts update / view / skip if RESEARCH.md already exists.
• With --research: force-refresh — re-spawn researcher unconditionally, no prompt.
• With --view: print existing RESEARCH.md to stdout, no spawn. Errors if RESEARCH.md missing.

/gsd-plan-phase 1                              # Research + plan + verify phase 1
/gsd-plan-phase 3 --skip-research              # Plan without research (familiar domain)
/gsd-plan-phase --auto                         # Non-interactive planning
/gsd-plan-phase 2 --validate                   # Validate state before planning
/gsd-plan-phase 1 --bounce                     # Plan + external bounce validation
/gsd-plan-phase --research-phase 4             # Research only on phase 4 (prompts if RESEARCH.md exists)
/gsd-plan-phase --research-phase 4 --view      # Print existing RESEARCH.md, no spawn
/gsd-plan-phase --research-phase 4 --research  # Force-refresh research, no prompt

/gsd-plan-review-convergence

Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. Runs plan-phase → review → replan → re-review cycles (max 3 cycles by default). Spawns isolated agents for planning and review; orchestrator handles loop control, HIGH-concern counting, stall detection, and escalation.

Exit behavior: Loop exits when HIGH count hits zero. Stall detection warns when HIGH count is not decreasing across cycles. Escalation gate asks the user to proceed or review manually when --max-cycles is hit with HIGH concerns still open.

/gsd-plan-review-convergence 3                    # Default reviewers, 3 cycles
/gsd-plan-review-convergence 3 --codex            # Codex-only review
/gsd-plan-review-convergence 3 --all --max-cycles 5

/gsd-ultraplan-phase

[BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back. The plan drafts remotely so the terminal stays free; review inline comments in a browser, then import the finalized plan back into .planning/ via /gsd-import.

Isolation: Intentionally separate from /gsd-plan-phase so upstream ultraplan changes cannot affect the core planning pipeline.

/gsd-ultraplan-phase 4                  # Offload planning for phase 4

/gsd-execute-phase

Execute all plans in a phase with wave-based parallelization, or run a specific wave.

Prerequisites: Phase has PLAN.md files Produces: per-plan {phase}-{N}-SUMMARY.md, git commits, and {phase}-VERIFICATION.md when the phase is fully complete

/gsd-execute-phase 1                # Execute phase 1
/gsd-execute-phase 1 --wave 2       # Execute only Wave 2
/gsd-execute-phase 1 --validate     # Validate state before execution
/gsd-execute-phase 2 --cross-ai     # Delegate phase 2 to external AI CLI

/gsd-verify-work

User acceptance testing with auto-diagnosis.

Prerequisites: Phase has been executed Produces: {phase}-UAT.md, fix plans if issues found

/gsd-verify-work 1                  # UAT for phase 1

/gsd-ship

Create PR from completed phase work with auto-generated body.

Prerequisites: Phase verified (/gsd-verify-work passed), gh CLI installed and authenticated Produces: GitHub PR with rich body from planning artifacts, STATE.md updated

/gsd-ship 4                         # Ship phase 4
/gsd-ship 4 --draft                 # Ship as draft PR

PR body includes:

• Phase goal from ROADMAP.md
• Changes summary from SUMMARY.md files
• Requirements addressed (REQ-IDs)
• Verification status
• Key decisions

/gsd-ui-review

Retroactive 6-pillar visual audit of implemented frontend.

Prerequisites: Project has frontend code (works standalone, no GSD project needed) Produces: {phase}-UI-REVIEW.md, screenshots in .planning/ui-reviews/

/gsd-ui-review                      # Audit current phase
/gsd-ui-review 3                    # Audit phase 3

/gsd-audit-uat

Cross-phase audit of all outstanding UAT and verification items.

Prerequisites: At least one phase has been executed with UAT or verification Produces: Categorized audit report with human test plan

/gsd-audit-uat

/gsd-audit-milestone

Verify milestone met its definition of done.

Prerequisites: All phases executed Produces: Audit report with gap analysis

/gsd-audit-milestone

/gsd-complete-milestone

Archive milestone, tag release.

Prerequisites: Milestone audit complete (recommended) Produces: MILESTONES.md entry, git tag

/gsd-complete-milestone

/gsd-milestone-summary

Generate comprehensive project summary from milestone artifacts for team onboarding and review.

Prerequisites: At least one completed or in-progress milestone Produces: .planning/reports/MILESTONE_SUMMARY-v{version}.md

Summary includes:

• Overview, architecture decisions, phase-by-phase breakdown
• Key decisions and trade-offs
• Requirements coverage
• Tech debt and deferred items
• Getting started guide for new team members
• Interactive Q&A offered after generation

/gsd-milestone-summary                # Summarize current milestone
/gsd-milestone-summary v1.0           # Summarize specific milestone

/gsd-new-milestone

Start next version cycle.

Prerequisites: Previous milestone completed Produces: Updated PROJECT.md, new REQUIREMENTS.md, new ROADMAP.md

/gsd-new-milestone                  # Interactive
/gsd-new-milestone "v2.0 Mobile"    # Named milestone
/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile"  # Restart milestone numbering at 1

Phase Management Commands

/gsd-phase

CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases with a single consolidated command.

Prerequisites: .planning/ROADMAP.md exists Produces: Updated ROADMAP.md

/gsd-phase "Add authentication system"          # Append new phase with description
/gsd-phase --insert 3 "Fix auth race condition" # Insert between phase 3 and 4 → creates 3.1
/gsd-phase --remove 7               # Remove phase 7, renumber 8→7, 9→8, etc.
/gsd-phase --edit 5                 # Edit any field of phase 5
/gsd-phase --edit 5 --force         # Edit phase 5 even if in-progress or completed

/gsd-validate-phase

Retroactively audit and fill Nyquist validation gaps.

/gsd-validate-phase 2               # Audit test coverage for phase 2

Navigation Commands

/gsd-progress

Show status, next steps, and automatically advance to the next logical workflow step. Reads project state and determines the appropriate action.

Auto-routing behavior (absorbed from /gsd-next):

• No project → suggests /gsd-new-project
• Phase needs discussion → runs /gsd-discuss-phase
• Phase needs planning → runs /gsd-plan-phase
• Phase needs execution → runs /gsd-execute-phase
• Phase needs verification → runs /gsd-verify-work
• All phases complete → suggests /gsd-complete-milestone

/gsd-progress                       # "Where am I? What's next?" with auto-routing
/gsd-progress --next                # Advance to next step automatically
/gsd-progress --do "fix the auth bug"  # Dispatch freeform intent to best GSD command
/gsd-progress --forensic            # Standard report + integrity audit

/gsd-resume-work

Restore full context from last session.

/gsd-resume-work                    # After context reset or new session

/gsd-pause-work

Save context handoff when stopping mid-phase.

/gsd-pause-work                     # Creates continue-here.md

/gsd-manager

Interactive command center for managing multiple phases from one terminal.

Prerequisites: .planning/ROADMAP.md exists Behavior:

• Dashboard of all phases with visual status indicators
• Recommends optimal next actions based on dependencies and progress
• Dispatches work: discuss runs inline, plan/execute run as background agents
• Designed for power users parallelizing work across phases from one terminal
• Supports per-step passthrough flags via manager.flags config (see Configuration)

/gsd-manager                        # Open command center dashboard

Checkpoint Heartbeats (#2410):

Background execute-phase runs emit [checkpoint] markers at every wave and plan boundary so the Claude API SSE stream never idles long enough to trigger Stream idle timeout - partial response received on multi-plan phases. The format is:

[checkpoint] phase {N} wave {W}/{M} starting, {count} plan(s), {P}/{Q} plans done
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} starting ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} complete ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} complete, {P}/{Q} plans done ({ok}/{count} ok)

If a background phase fails partway through, grep the transcript for [checkpoint] to see the last confirmed boundary. The manager's background-completion handler uses these markers to report partial progress when an agent errors out.

Manager Passthrough Flags:

Configure per-step flags in .planning/config.json under manager.flags. These flags are appended to each dispatched command:

{
  "manager": {
    "flags": {
      "discuss": "--auto",
      "plan": "--skip-research",
      "execute": "--validate"
    }
  }
}

/gsd-help

Show all commands and usage guide.

/gsd-help                           # Quick reference

Utility Commands

/gsd-explore

Socratic ideation session — guide an idea through probing questions, optionally spawn research, then route output to the right GSD artifact (notes, todos, seeds, research questions, requirements, or a new phase).

/gsd-explore                        # Open-ended ideation session
/gsd-explore authentication strategy  # Explore a specific topic

/gsd-undo

Safe git revert — roll back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate.

Safety: Checks dependent phases/plans before reverting; always shows a confirmation gate.

/gsd-undo --last 5                  # Pick from the 5 most recent GSD commits
/gsd-undo --phase 03                # Revert all commits for phase 3
/gsd-undo --plan 03-02              # Revert commits for plan 02 of phase 3

/gsd-import

Ingest an external plan file into the GSD planning system with conflict detection against PROJECT.md decisions before writing anything.

Process: Detects conflicts → prompts for resolution → writes as GSD PLAN.md → validates via gsd-plan-checker

/gsd-import --from /tmp/team-plan.md  # Import and validate an external plan

/gsd-ingest-docs

Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo. Runs parallel classification (gsd-doc-classifier) plus synthesis with precedence rules and cycle detection (gsd-doc-synthesizer). Produces a three-bucket conflicts report (INGEST-CONFLICTS.md: auto-resolved, competing-variants, unresolved-blockers) and hard-blocks on LOCKED-vs-LOCKED ADR contradictions.

Limits: v1 caps at 50 docs per invocation. Extracts the shared conflict-detection contract into references/doc-conflict-engine.md, which /gsd-import also consumes.

/gsd-ingest-docs                            # Scan repo root, auto-detect mode
/gsd-ingest-docs docs/                      # Only ingest under docs/
/gsd-ingest-docs --manifest ingest.yaml     # Explicit precedence manifest

/gsd-quick

Execute ad-hoc task with GSD guarantees.

Granular flags are composable: --discuss --research --validate is equivalent to --full.

/gsd-quick                          # Basic quick task
/gsd-quick --discuss --research     # Discussion + research + planning
/gsd-quick --validate               # Plan-checking + verification only
/gsd-quick --full                   # Complete quality pipeline
/gsd-quick list                     # List all quick tasks
/gsd-quick status my-task-slug      # Show status of a quick task
/gsd-quick resume my-task-slug      # Resume a quick task

/gsd-autonomous

Run all remaining phases autonomously.

/gsd-autonomous                     # Run all remaining phases
/gsd-autonomous --from 3            # Start from phase 3
/gsd-autonomous --to 5              # Run up to and including phase 5
/gsd-autonomous --from 3 --to 5     # Run phases 3 through 5

/gsd-debug

Systematic debugging with persistent state.

Subcommands:

• /gsd-debug list — List all active debug sessions with status, hypothesis, and next action
• /gsd-debug status <slug> — Print full summary of a session (Evidence count, Eliminated count, Resolution, TDD checkpoint) without spawning an agent
• /gsd-debug continue <slug> — Resume a specific session by slug (surfaces Current Focus then spawns continuation agent)
• /gsd-debug [--diagnose] <description> — Start new debug session (existing behavior; --diagnose stops at root cause without applying fix)

TDD mode: When tdd_mode: true in .planning/config.json, debug sessions require a failing test to be written and verified before any fix is applied (red → green → done).

/gsd-debug "Login button not responding on mobile Safari"
/gsd-debug --diagnose "Intermittent 500 errors on /api/users"
/gsd-debug list
/gsd-debug status auth-token-null
/gsd-debug continue form-submit-500

/gsd-add-tests

Generate tests for a completed phase.

/gsd-add-tests 2                    # Generate tests for phase 2

/gsd-stats

Display project statistics.

/gsd-stats                          # Project metrics dashboard

/gsd-profile-user

Generate a developer behavioral profile from Claude Code session analysis across 8 dimensions (communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth). Produces artifacts that personalize Claude's responses.

Generated artifacts:

• USER-PROFILE.md — Full behavioral profile
• /gsd-dev-preferences command — Load preferences in any session
• CLAUDE.md profile section — Auto-discovered by Claude Code

/gsd-profile-user                   # Analyze sessions and build profile
/gsd-profile-user --questionnaire   # Interactive questionnaire fallback
/gsd-profile-user --refresh         # Re-generate from fresh analysis

/gsd-health

Validate .planning/ directory integrity.

/gsd-health                         # Check integrity
/gsd-health --repair                # Check and fix

/gsd-cleanup

Archive accumulated phase directories from completed milestones.

/gsd-cleanup

Spiking & Sketching Commands

/gsd-spike

Run 2–5 focused feasibility experiments before committing to an implementation approach. Each experiment uses Given/When/Then framing, produces executable code, and returns a VALIDATED / INVALIDATED / PARTIAL verdict.

Produces: .planning/spikes/NNN-experiment-name/ with code, results, and README; .planning/spikes/MANIFEST.md --wrap-up produces: .claude/skills/spike-findings-[project]/ skill file

/gsd-spike                              # Interactive intake
/gsd-spike "can we stream LLM tokens through SSE"
/gsd-spike --quick websocket-vs-polling
/gsd-spike --wrap-up                    # Package findings into a reusable skill

/gsd-sketch

Explore design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 variants per design question for direct browser comparison.

Produces: .planning/sketches/NNN-descriptive-name/index.html (2–3 interactive variants), README.md, shared themes/default.css; .planning/sketches/MANIFEST.md --wrap-up produces: .claude/skills/sketch-findings-[project]/ skill file

/gsd-sketch                             # Interactive mood intake
/gsd-sketch "dashboard layout"
/gsd-sketch --quick "sidebar navigation"
/gsd-sketch --text "onboarding flow"    # Non-Claude runtime
/gsd-sketch --wrap-up                   # Package winning sketch into a skill

Diagnostics Commands

/gsd-forensics

Post-mortem investigation for failed GSD workflows — diagnoses what went wrong.

Prerequisites: .planning/ directory exists Produces: .planning/forensics/report-{timestamp}.md

Investigation covers:

• Git history analysis (recent commits, stuck patterns, time gaps)
• Artifact integrity (expected files for completed phases)
• STATE.md anomalies and session history
• Uncommitted work, conflicts, abandoned changes
• At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption)
• GitHub issue creation offered if actionable findings exist

/gsd-forensics                              # Interactive — prompted for problem
/gsd-forensics "Phase 3 execution stalled"  # With problem description

/gsd-extract-learnings

Extract reusable patterns, anti-patterns, and architectural decisions from completed phase work.

Prerequisites: Phase has been executed (SUMMARY.md files exist) Produces: .planning/learnings/{phase}-LEARNINGS.md

Extracts:

• Architectural decisions and their rationale
• Patterns that worked well (reusable in future phases)
• Anti-patterns encountered and how they were resolved
• Technology-specific insights
• Performance and testing observations

/gsd-extract-learnings 3                    # Extract learnings from phase 3
/gsd-extract-learnings --all                # Extract from all completed phases

Workstream Management

/gsd-workstreams

Manage parallel workstreams for concurrent work on different milestone areas.

Subcommands:

Prerequisites: Active GSD project Produces: Workstream directories under .planning/, state tracking per workstream

/gsd-workstreams                    # List all workstreams
/gsd-workstreams create backend-api # Create new workstream
/gsd-workstreams switch backend-api # Set active workstream
/gsd-workstreams status backend-api # Detailed status
/gsd-workstreams progress           # Cross-workstream progress overview
/gsd-workstreams complete backend-api  # Archive completed workstream
/gsd-workstreams resume backend-api    # Resume work in workstream

Configuration Commands

/gsd-settings

Interactive configuration of workflow toggles and model profile. Questions are grouped into six visual sections:

• Planning — Research, Plan Checker, Pattern Mapper, Nyquist, UI Phase, UI Gate, AI Phase
• Execution — Verifier, TDD Mode, Code Review, Code Review Depth (conditional — only when Code Review is on), UI Review
• Docs & Output — Commit Docs, Skip Discuss, Worktrees
• Features — Intel, Graphify
• Model & Pipeline — Model Profile, Auto-Advance, Branching
• Misc — Context Warnings, Research Qs

All answers are merged via gsd-sdk query config-set into the resolved project config path (.planning/config.json for a standard install, or .planning/workstreams/<active>/config.json when a workstream is active), preserving unrelated keys. After confirmation, the user may save the full settings object to ~/.gsd/defaults.json so future /gsd-new-project runs start from the same baseline.

/gsd-settings                       # Interactive config

/gsd-config

Configure GSD settings interactively — workflow toggles, advanced knobs, integrations, and model profile — with a single consolidated command.

--advanced sections:

All answers merge via gsd-sdk query config-set, preserving unrelated keys. API keys are masked (****<last-4>) in all output.

/gsd-config                         # Common-case interactive config
/gsd-config --advanced              # Power-user knobs (six-section prompt)
/gsd-config --integrations          # API keys, review CLI routing, agent skills
/gsd-config --profile budget        # Switch to budget profile
/gsd-config --profile quality       # Switch to quality profile

See CONFIGURATION.md for the full schema and defaults.

Brownfield Commands

/gsd-map-codebase

Analyze existing codebase with parallel mapper agents. Use --fast for a quick single-agent scan, or --query to search existing intel.

Produces: .planning/codebase/ analysis documents (full mode); targeted document(s) in .planning/codebase/ (--fast); intel query results (--query)

/gsd-map-codebase                   # Full codebase analysis (4 parallel agents)
/gsd-map-codebase auth              # Focus on auth area
/gsd-map-codebase --fast            # Quick tech + arch overview (1 agent)
/gsd-map-codebase --fast --focus quality  # Quality and code health only
/gsd-map-codebase --query authentication  # Search intel for a term

/gsd-graphify

Build, query, and inspect the project knowledge graph stored in .planning/graphs/. Opt-in via graphify.enabled: true in config.json (see Configuration Reference); when disabled, the command prints an activation hint and stops.

Produces: .planning/graphs/ graph artifacts (nodes, edges, snapshots)

/gsd-graphify build                 # Build or rebuild the knowledge graph
/gsd-graphify query authentication  # Search the graph for a term
/gsd-graphify status                # Show freshness and statistics
/gsd-graphify diff                  # Show changes since last build

Programmatic access: node gsd-tools.cjs graphify <build|query|status|diff|snapshot> — see CLI Tools Reference.

AI Integration Commands

/gsd-ai-integration-phase

Generate an AI-SPEC.md design contract for phases that involve building AI systems. Presents an interactive decision matrix, surfaces domain-specific failure modes and eval criteria, and produces AI-SPEC.md with a framework recommendation, implementation guidance, and evaluation strategy.

Produces: {phase}-AI-SPEC.md in the phase directory

Spawns: 3 parallel specialist agents: domain-researcher, framework-selector, ai-researcher, and eval-planner

/gsd-ai-integration-phase              # Wizard for the current phase
/gsd-ai-integration-phase 3           # Wizard for a specific phase

/gsd-eval-review

Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan. Checks implementation against the AI-SPEC.md evaluation plan produced by /gsd-ai-integration-phase. Scores each eval dimension as COVERED/PARTIAL/MISSING.

Prerequisites: Phase has been executed and has an AI-SPEC.md Produces: {phase}-EVAL-REVIEW.md with findings, gaps, and remediation guidance

/gsd-eval-review                       # Audit current phase
/gsd-eval-review 3                     # Audit a specific phase

Update Commands

/gsd-update

Update GSD with changelog preview, and optionally sync skills or reapply local patches.

/gsd-update                         # Check for updates and install
/gsd-update --sync                  # Update and sync skills
/gsd-update --reapply               # Update and reapply local patches

Code Quality Commands

/gsd-code-review

Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems. Use --fix to auto-fix findings after review.

Prerequisites: Phase has been executed and has SUMMARY.md or git history Produces: {phase}-REVIEW.md with severity-classified findings; {phase}-REVIEW-FIX.md when --fix is used Spawns: gsd-code-reviewer agent; gsd-code-fixer agent (with --fix)

/gsd-code-review 3                          # Standard review for phase 3
/gsd-code-review 2 --depth=deep             # Deep cross-file review
/gsd-code-review 4 --files src/auth.ts,src/token.ts  # Explicit file list
/gsd-code-review 3 --fix                    # Review then fix Critical + Warning findings
/gsd-code-review 3 --fix --all             # Review then fix all findings including Info
/gsd-code-review 3 --fix --auto            # Review, fix, and re-review until clean (max 3 iterations)

/gsd-audit-fix

Autonomous audit-to-fix pipeline — runs an audit, classifies findings, fixes auto-fixable issues with test verification, and commits each fix atomically.

Prerequisites: At least one phase has been executed with UAT or verification Produces: Fix commits with test verification; classification report

/gsd-audit-fix                              # Run audit-uat, fix medium+ issues (max 5)
/gsd-audit-fix --severity high             # Only fix high-severity issues
/gsd-audit-fix --dry-run                   # Preview classification without fixing
/gsd-audit-fix --max 10 --severity all     # Fix up to 10 issues of any severity

Fast & Inline Commands

/gsd-fast

Execute a trivial task inline — no subagents, no planning overhead. For typo fixes, config changes, small refactors, forgotten commits.

Not a replacement for /gsd-quick — use /gsd-quick for anything needing research, multi-step planning, or verification.

/gsd-fast "fix typo in README"
/gsd-fast "add .env to gitignore"

/gsd-review

Cross-AI peer review of phase plans from external AI CLIs.

Produces: {phase}-REVIEWS.md — consumable by /gsd-plan-phase --reviews

/gsd-review --phase 3 --all
/gsd-review --phase 2 --gemini

/gsd-pr-branch

Create a clean PR branch by filtering out .planning/ commits.

Purpose: Reviewers see only code changes, not GSD planning artifacts.

/gsd-pr-branch                     # Filter against main
/gsd-pr-branch develop             # Filter against develop

/gsd-secure-phase

Retroactively verify threat mitigations for a completed phase.

Prerequisites: Phase must have been executed. Works with or without existing SECURITY.md. Produces: {phase}-SECURITY.md with threat verification results Spawns: gsd-security-auditor agent

Three operating modes:

1. SECURITY.md exists — audit and verify existing mitigations
2. No SECURITY.md but PLAN.md has threat model — generate from artifacts
3. Phase not executed — exits with guidance

/gsd-secure-phase                   # Audit last completed phase
/gsd-secure-phase 5                 # Audit specific phase

/gsd-docs-update

Generate or update project documentation verified against the codebase.

Produces: Up to 9 documentation files (README, architecture, API, getting started, development, testing, configuration, deployment, contributing) Spawns: gsd-doc-writer agents (one per doc type), then gsd-doc-verifier agents for factual verification

Each doc writer explores the codebase directly — no hallucinated paths or stale signatures. Doc verifier checks claims against the live filesystem.

/gsd-docs-update                    # Generate/update docs interactively
/gsd-docs-update --force            # Regenerate all docs
/gsd-docs-update --verify-only      # Verify existing docs only

Task Capture & Backlog Commands

/gsd-capture

Capture ideas, tasks, notes, and seeds to their appropriate destination. Default mode adds a structured todo; flags route to specialized capture workflows.

Backlog: 999.x numbering keeps items outside the active phase sequence; phase directories are created immediately so /gsd-discuss-phase and /gsd-plan-phase work on them. Seeds: Preserve full WHY, WHEN to surface, and breadcrumbs — consumed by /gsd-new-milestone.

Produces: .planning/todos/ (default), note files (--note), ROADMAP.md backlog section (--backlog), .planning/seeds/SEED-NNN-slug.md (--seed)

/gsd-capture "Consider adding dark mode support"   # Add todo
/gsd-capture --note "Caching strategy idea"        # Quick note
/gsd-capture --note list                           # List all notes
/gsd-capture --note promote 3                      # Promote note 3 to todo
/gsd-capture --backlog "GraphQL API layer"         # Add to backlog
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
/gsd-capture --list                                # Browse and act on todos

/gsd-review-backlog

Review and promote backlog items to active milestone.

Actions per item: Promote (move to active sequence), Keep (leave in backlog), Remove (delete).

/gsd-review-backlog

/gsd-thread

Manage persistent context threads for cross-session work.

Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than /gsd-pause-work.

/gsd-thread                         # List all threads
/gsd-thread list --open             # List only open/in-progress threads
/gsd-thread list --resolved         # List only resolved threads
/gsd-thread status fix-deploy-key   # Show thread status
/gsd-thread close fix-deploy-key    # Mark thread as resolved
/gsd-thread fix-deploy-key-auth     # Resume thread
/gsd-thread "Investigate TCP timeout in pasta service"  # Create new

State Management Commands

state validate

Detect drift between STATE.md and the actual filesystem.

Prerequisites: .planning/STATE.md exists Produces: Validation report showing any drift between STATE.md fields and filesystem reality

node gsd-tools.cjs state validate

state sync [--verify]

Reconstruct STATE.md from actual project state on disk.

Prerequisites: .planning/ directory exists Produces: Updated STATE.md reflecting filesystem reality

node gsd-tools.cjs state sync             # Reconstruct STATE.md from disk
node gsd-tools.cjs state sync --verify    # Dry-run: show changes without writing

state planned-phase

Record state transition after plan-phase completes (Planned/Ready to execute).

Prerequisites: Phase has been planned Produces: Updated STATE.md with post-planning state

node gsd-tools.cjs state planned-phase --phase 3 --plans 2

Community Commands

Community Hooks

Optional git and session hooks gated behind hooks.community: true in .planning/config.json. All are no-ops unless explicitly enabled.

Enable with:

{ "hooks": { "community": true } }

Community Invite

To join the GSD Discord community, visit the link in the GSD README or run /gsd-help and follow the Discord link shown there.

Contributing: Skill Description Standards

Skill descriptions (the description: field in each commands/gsd/*.md frontmatter) are injected into every session's system prompt. To keep per-session overhead low, descriptions must be ≤ 100 chars and must not duplicate flag documentation already in argument-hint:.

A lint gate enforces the budget:

npm run lint:descriptions

The check is also run as part of npm test via tests/enh-2789-description-budget.test.cjs.