Files
get-shit-done/docs/COMMANDS.md
Tom Boucher df0ab0c0c9 fix(#2410): emit wave + plan checkpoint heartbeats to prevent stream idle timeout (#2626)
/gsd:manager's background execute-phase Task fails with
"Stream idle timeout - partial response received" on multi-plan phases
(Claude Code + Opus 4.7 at ~200K+ cache_read) because the long subagent
never emits tokens fast enough between large tool_results — the SSE layer
times out mid-assistant-turn and the harness retries hit the same TTFT
wall after prompt cache TTL expires.

Root cause: no orchestrator-level activity at wave/plan boundaries.

Fix (maintainer-approved A+B):
- A (wave boundary): execute-phase.md now emits a `[checkpoint]`
  heartbeat before each wave spawns and after each wave completes.
- B (plan boundary): also emit `[checkpoint]` before each Task()
  dispatch and after each executor returns (complete/failed/checkpoint).
  Heartbeats are literal assistant-text lines (no tool call) with a
  monotonic `{P}/{Q} plans done` counter so partial-transcript recovery
  tools can grep progress even when a run dies mid-phase.

Docs: COMMANDS.md /gsd-manager section documents the marker format.
Tests: tests/bug-2410-stream-checkpoint-heartbeats.test.cjs (12 cases)
asserts the heartbeats exist at every boundary and in the right workflow
step. Full suite: 5422 node:test cases pass. Pre-existing vitest
failures on main are unrelated to this change.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 11:54:11 -04:00

53 KiB
Raw Blame History

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.

Flag Description
--auto @file.md Auto-extract from document, skip interactive questions

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-new-workspace

Create an isolated workspace with repo copies and independent .planning/ directory.

Flag Description
--name <name> Workspace name (required)
--repos repo1,repo2 Comma-separated repo paths or names
--path /target Target directory (default: ~/gsd-workspaces/<name>)
--strategy worktree|clone Copy strategy (default: worktree)
--branch <name> Branch to checkout (default: workspace/<name>)
--auto Skip interactive questions

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-new-workspace --name feature-b --repos hr-ui,ZeymoAPI
/gsd-new-workspace --name feature-b --repos . --strategy worktree  # Same-repo isolation
/gsd-new-workspace --name spike --repos api,web --strategy clone   # Full clones

/gsd-list-workspaces

List active GSD workspaces and their status.

Scans: ~/gsd-workspaces/ for WORKSPACE.md manifests Shows: Name, repo count, strategy, GSD project status

/gsd-list-workspaces

/gsd-remove-workspace

Remove a workspace and clean up git worktrees.

Argument Required Description
<name> Yes Workspace name to remove

Safety: Refuses removal if any repo has uncommitted changes. Requires name confirmation.

/gsd-remove-workspace feature-b

/gsd-discuss-phase

Capture implementation decisions before planning.

Argument Required Description
N No Phase number (defaults to current phase)
Flag Description
--all Skip area selection — discuss all gray areas interactively (no auto-advance)
--auto Auto-select recommended defaults for all questions
--batch Group questions for batch intake instead of one-by-one
--analyze Add trade-off analysis during discussion
--power File-based bulk question answering from a prepared answers file

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.

Argument Required Description
N No Phase number (defaults to current phase)

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.

Argument Required Description
N No Phase number (defaults to next unplanned phase)
Flag Description
--auto Skip interactive confirmations
--research Force re-research even if RESEARCH.md exists
--skip-research Skip domain research step
--gaps Gap closure mode (reads VERIFICATION.md, skips research)
--skip-verify Skip plan checker verification loop
--prd <file> Use a PRD file instead of discuss-phase for context
--reviews Replan with cross-AI review feedback from REVIEWS.md
--validate Run state validation before planning begins
--bounce Run external plan bounce validation after planning (uses workflow.plan_bounce_script)
--skip-bounce Skip plan bounce even if enabled in config

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

/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-review-convergence

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

Argument / Flag Required Description
N Yes Phase number to plan and review
--codex / --gemini / --claude / --opencode No Single-reviewer selection
--all No Run every configured reviewer in parallel
--max-cycles N No Override cycle cap (default 3)

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 — Claude Code only.] Offload plan-phase work to Claude Code's ultraplan cloud. 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.

Flag Required Description
N Yes Phase number to plan remotely

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.

Argument Required Description
N Yes Phase number to execute
--wave N No Execute only Wave N in the phase
--validate No Run state validation before execution begins
--cross-ai No Delegate execution to an external AI CLI (uses workflow.cross_ai_command)
--no-cross-ai No Force local execution even if cross-AI is enabled in config

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.

Argument Required Description
N No Phase number (defaults to last executed phase)

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

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

/gsd-next

Automatically advance to the next logical workflow step. Reads project state and runs the appropriate command.

Prerequisites: .planning/ directory exists Behavior:

  • 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-next                           # Auto-detect and run next step

/gsd-session-report

Generate a session report with work summary, outcomes, and estimated resource usage.

Prerequisites: Active project with recent work Produces: .planning/reports/SESSION_REPORT.md

/gsd-session-report                 # Generate post-session summary

Report includes:

  • Work performed (commits, plans executed, phases progressed)
  • Outcomes and deliverables
  • Blockers and decisions made
  • Estimated token/cost usage
  • Next steps recommendation

/gsd-ship

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

Argument Required Description
N No Phase number or milestone version (e.g., 4 or v1.0)
--draft No Create as draft PR

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.

Argument Required Description
N No Phase number (defaults to last executed phase)

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.

Argument Required Description
version No Milestone version (defaults to current/latest milestone)

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.

Argument Required Description
name No Milestone name
--reset-phase-numbers No Restart the new milestone at Phase 1 and archive old phase dirs before roadmapping

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-add-phase

Append new phase to roadmap.

/gsd-add-phase                      # Interactive — describe the phase

/gsd-insert-phase

Insert urgent work between phases using decimal numbering.

Argument Required Description
N No Insert after this phase number
/gsd-insert-phase 3                 # Insert between phase 3 and 4 → creates 3.1

/gsd-remove-phase

Remove future phase and renumber subsequent phases.

Argument Required Description
N No Phase number to remove
/gsd-remove-phase 7                 # Remove phase 7, renumber 8→7, 9→8, etc.

/gsd-list-phase-assumptions

Preview Claude's intended approach before planning.

Argument Required Description
N No Phase number
/gsd-list-phase-assumptions 2       # See assumptions for phase 2

/gsd-analyze-dependencies

Analyze phase dependencies and suggest Depends on entries for ROADMAP.md before running /gsd-manager.

Prerequisites: .planning/ROADMAP.md exists Produces: Dependency suggestion table; optionally updates Depends on fields in ROADMAP.md with confirmation

Run this before /gsd-manager when phases have empty Depends on fields and you want to avoid merge conflicts from unordered parallel execution.

/gsd-analyze-dependencies           # Analyze all phases and suggest dependencies

Detection methods:

  • File overlap — phases touching the same files/domains must be ordered
  • Semantic dependencies — a phase that consumes an API or schema built by another phase
  • Data flow — a phase that reads output produced by another phase

/gsd-plan-milestone-gaps

Create phases to close gaps from milestone audit.

/gsd-plan-milestone-gaps             # Creates phases for each audit gap

/gsd-research-phase

Deep ecosystem research only (standalone — usually use /gsd-plan-phase instead).

Argument Required Description
N No Phase number
/gsd-research-phase 4               # Research phase 4 domain

/gsd-validate-phase

Retroactively audit and fill Nyquist validation gaps.

Argument Required Description
N No Phase number
/gsd-validate-phase 2               # Audit test coverage for phase 2

Navigation Commands

/gsd-progress

Show status and next steps.

Flag Description
--forensic Append a 6-check integrity audit after the standard report (STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking todos, uncommitted code)
/gsd-progress                       # "Where am I? What's next?"
/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).

Argument Required Description
topic No Topic to explore (e.g., /gsd-explore authentication strategy)
/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.

Flag Required Description
--last N (one of three required) Show recent GSD commits for interactive selection
--phase NN (one of three required) Revert all commits for a phase
--plan NN-MM (one of three required) Revert all commits for a specific plan

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.

Flag Required Description
--from <filepath> Yes Path to the external plan file to import

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

Scan a repo containing mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full .planning/ setup from them in a single pass. 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.

Argument / Flag Required Description
path No Target directory to scan (defaults to repo root)
--mode new|merge No Override auto-detect (defaults: new if .planning/ absent, merge if present)
--manifest <file> No YAML file listing {path, type, precedence?} per doc; overrides heuristic classification
--resolve auto No Conflict resolution mode (v1: only auto; interactive is reserved)

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-from-gsd2

Reverse migration from GSD-2 format (.gsd/ with Milestone→Slice→Task hierarchy) back to v1 .planning/ format.

Flag Required Description
--dry-run No Preview what would be migrated without writing anything
--force No Overwrite existing .planning/ directory
--path <dir> No Specify GSD-2 root directory (defaults to current directory)

Flattening: Milestone→Slice hierarchy is flattened to sequential phase numbers (M001/S01→phase 01, M001/S02→phase 02, M002/S01→phase 03, etc.).

Produces: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, and sequential phase directories in .planning/.

Safety: Guards against overwriting an existing .planning/ directory without --force.

/gsd-from-gsd2                          # Migrate .gsd/ in current directory
/gsd-from-gsd2 --dry-run                # Preview migration without writing
/gsd-from-gsd2 --force                  # Overwrite existing .planning/
/gsd-from-gsd2 --path /path/to/gsd2-project  # Specify GSD-2 root

/gsd-quick

Execute ad-hoc task with GSD guarantees.

Flag Description
--full Enable the complete quality pipeline — discussion + research + plan-checking + verification
--validate Plan-checking (max 2 iterations) + post-execution verification only; no discussion or research
--discuss Lightweight pre-planning discussion
--research Spawn focused researcher before planning

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

Subcommand Description
list List all quick tasks with status
status <slug> Show status of a specific quick task
resume <slug> Resume a specific quick task by slug
/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.

Flag Description
--from N Start from a specific phase number
--to N Stop after completing a specific phase number
--interactive Lean context with user input
/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-do

Route freeform text to the right GSD command.

/gsd-do                             # Then describe what you want

/gsd-note

Zero-friction idea capture — append, list, or promote notes to todos.

Argument Required Description
text No Note text to capture (default: append mode)
list No List all notes from project and global scopes
promote N No Convert note N into a structured todo
Flag Description
--global Use global scope for note operations
/gsd-note "Consider caching strategy for API responses"
/gsd-note list
/gsd-note promote 3

/gsd-debug

Systematic debugging with persistent state.

Argument Required Description
description No Description of the bug
Flag Description
--diagnose Diagnosis-only mode — investigate without attempting fixes

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-todo

Capture idea or task for later.

Argument Required Description
description No Todo description
/gsd-add-todo "Consider adding dark mode support"

/gsd-check-todos

List pending todos and select one to work on.

/gsd-check-todos

/gsd-add-tests

Generate tests for a completed phase.

Argument Required Description
N No Phase number
/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.

Flag Description
--questionnaire Use interactive questionnaire instead of session analysis
--refresh Re-analyze sessions and regenerate profile

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.

Flag Description
--repair Auto-fix recoverable issues
/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 25 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.

Argument Required Description
idea No The technical question or approach to investigate
--quick No Skip intake conversation; use idea text directly

Produces: .planning/spikes/NNN-experiment-name/ with code, results, and README; .planning/spikes/MANIFEST.md

/gsd-spike                              # Interactive intake
/gsd-spike "can we stream LLM tokens through SSE"
/gsd-spike --quick websocket-vs-polling

/gsd-spike-wrap-up

Package completed spike findings into a reusable project-local skill so future sessions can reference the conclusions.

Prerequisites: .planning/spikes/ exists with at least one completed spike Produces: .claude/skills/spike-findings-[project]/ skill file

/gsd-spike-wrap-up

/gsd-sketch

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

Argument Required Description
idea No The UI design question or direction to explore
--quick No Skip mood intake; use idea text directly
--text No Text-mode fallback — replace interactive prompts with numbered lists (for non-Claude runtimes)

Produces: .planning/sketches/NNN-descriptive-name/index.html (23 interactive variants), README.md, shared themes/default.css; .planning/sketches/MANIFEST.md

/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 decisions into a reusable project-local skill so future sessions inherit the visual direction.

Prerequisites: .planning/sketches/ exists with at least one completed sketch (winner marked) Produces: .claude/skills/sketch-findings-[project]/ skill file

/gsd-sketch-wrap-up

Diagnostics Commands

/gsd-forensics

Post-mortem investigation of failed or stuck GSD workflows.

Argument Required Description
description No Problem description (prompted if omitted)

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.

Argument Required Description
N Yes Phase number to extract learnings from
Flag Description
--all Extract learnings from all completed phases
--format Output format: markdown (default), json

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:

Subcommand Description
list List all workstreams with status (default if no subcommand)
create <name> Create a new workstream
status <name> Detailed status for one workstream
switch <name> Set active workstream
progress Progress summary across all workstreams
complete <name> Archive a completed workstream
resume <name> Resume work in a workstream

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-settings-advanced

Interactive configuration of power-user knobs — plan bounce, subagent timeouts, branch templates, cross-AI delegation, context window, and runtime output. Use after /gsd-settings once the common-case toggles are dialed in.

Six sections, each a focused prompt batch:

Section Keys
Planning Tuning workflow.plan_bounce, workflow.plan_bounce_passes, workflow.plan_bounce_script, workflow.subagent_timeout, workflow.inline_plan_threshold
Execution Tuning workflow.node_repair, workflow.node_repair_budget, workflow.auto_prune_state
Discussion Tuning workflow.max_discuss_passes
Cross-AI Execution workflow.cross_ai_execution, workflow.cross_ai_command, workflow.cross_ai_timeout
Git Customization git.base_branch, git.phase_branch_template, git.milestone_branch_template
Runtime / Output response_language, context_window, search_gitignored, graphify.build_timeout

Current values are pre-selected; an empty input keeps the existing value. Numeric fields reject non-numeric input and re-prompt. Null-allowed fields (plan_bounce_script, cross_ai_command, response_language) accept an empty input as a clear. Writes route through gsd-sdk query config-set, which preserves every unrelated key.

/gsd-settings-advanced              # Six-section interactive config

See CONFIGURATION.md for the full schema and defaults.

/gsd-settings-integrations

Interactive configuration of third-party integrations and cross-tool routing. Distinct from /gsd-settings (workflow toggles) — this command handles connectivity: API keys, reviewer CLI routing, and agent-skill injection.

Covers:

  • Search integrations: brave_search, firecrawl, exa_search API keys, and the search_gitignored toggle.
  • Code-review CLI routing: review.models.{claude,codex,gemini,opencode} — a shell command per reviewer flavor.
  • Agent-skill injection: agent_skills.<agent-type> — skill names injected into an agent's spawn frontmatter. Agent-type slugs are validated against [a-zA-Z0-9_-]+ so path separators and shell metacharacters are rejected.

API keys are stored plaintext in .planning/config.json but displayed masked (****<last-4>) in every interactive output, confirmation table, and config-set stdout/stderr line. Plaintext is never echoed, never logged, and never written to any file outside config.json by this workflow.

/gsd-settings-integrations           # Interactive config (three sections)

See docs/CONFIGURATION.md for the per-field reference and docs/CLI-TOOLS.md for the reviewer-CLI routing contract.

/gsd-set-profile

Quick profile switch.

Argument Required Description
profile Yes quality, balanced, budget, or inherit
/gsd-set-profile budget             # Switch to budget profile
/gsd-set-profile quality            # Switch to quality profile

Brownfield Commands

/gsd-map-codebase

Analyze existing codebase with parallel mapper agents.

Argument Required Description
area No Scope mapping to a specific area
/gsd-map-codebase                   # Full codebase analysis
/gsd-map-codebase auth              # Focus on auth area

/gsd-scan

Rapid single-focus codebase assessment — lightweight alternative to /gsd-map-codebase that spawns one mapper agent instead of four parallel ones.

Flag Description
--focus tech|arch|quality|concerns|tech+arch Focus area (default: tech+arch)

Produces: Targeted document(s) in .planning/codebase/

/gsd-scan                           # Quick tech + arch overview
/gsd-scan --focus quality           # Quality and code health only
/gsd-scan --focus concerns          # Surface concerns and risk areas

/gsd-intel

Query, inspect, or refresh queryable codebase intelligence files stored in .planning/intel/. Requires intel.enabled: true in config.json.

Argument Description
query <term> Search intel files for a term
status Show intel file freshness (FRESH/STALE)
diff Show changes since last snapshot
refresh Rebuild all intel files from codebase analysis

Produces: .planning/intel/ JSON files (stack, api-map, dependency-graph, file-roles, arch-decisions)

/gsd-intel status                   # Check freshness of intel files
/gsd-intel query authentication     # Search intel for a term
/gsd-intel diff                     # What changed since last snapshot
/gsd-intel refresh                  # Rebuild intel index

/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.

Subcommand Description
build Build or rebuild the knowledge graph (spawns the graphify-builder agent)
query <term> Search the graph for a term
status Show graph freshness and statistics
diff Show changes since the last build

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

AI framework selection wizard for integrating AI/LLM capabilities into a project phase. 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

Retroactive audit of an implemented AI phase's evaluation coverage. 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.

/gsd-update                         # Check for updates and install

/gsd-reapply-patches

Restore local modifications after a GSD update.

/gsd-reapply-patches                # Merge back local changes

Code Quality Commands

/gsd-code-review

Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems.

Argument Required Description
N Yes Phase number whose changes to review (e.g., 2 or 02)
--depth=quick|standard|deep No Review depth level (overrides workflow.code_review_depth config). quick: pattern-matching only (~2 min). standard: per-file analysis with language-specific checks (~515 min, default). deep: cross-file analysis including import graphs and call chains (~1530 min)
--files file1,file2,... No Explicit comma-separated file list; skips SUMMARY/git scoping entirely

Prerequisites: Phase has been executed and has SUMMARY.md or git history Produces: {phase}-REVIEW.md in phase directory with severity-classified findings Spawns: gsd-code-reviewer agent

/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-fix

Auto-fix issues found by /gsd-code-review. Reads REVIEW.md, spawns a fixer agent, commits each fix atomically, and produces a REVIEW-FIX.md summary.

Argument Required Description
N Yes Phase number whose REVIEW.md to fix
--all No Include Info findings in fix scope (default: Critical + Warning only)
--auto No Enable fix + re-review iteration loop, capped at 3 iterations

Prerequisites: Phase has a {phase}-REVIEW.md file (run /gsd-code-review first) Produces: {phase}-REVIEW-FIX.md with applied fixes summary Spawns: gsd-code-fixer agent

/gsd-code-review-fix 3                      # Fix Critical + Warning findings for phase 3
/gsd-code-review-fix 3 --all               # Include Info findings
/gsd-code-review-fix 3 --auto              # 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.

Flag Description
--source <audit> Which audit to run (default: audit-uat)
--severity high|medium|all Minimum severity to process (default: medium)
--max N Maximum findings to fix (default: 5)
--dry-run Classify findings without fixing (shows classification table)

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.

Argument Required Description
task description No What to do (prompted if omitted)

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.

Argument Required Description
--phase N Yes Phase number to review
Flag Description
--gemini Include Gemini CLI review
--claude Include Claude CLI review (separate session)
--codex Include Codex CLI review
--coderabbit Include CodeRabbit review
--opencode Include OpenCode review (via GitHub Copilot)
--qwen Include Qwen Code review (Alibaba Qwen models)
--cursor Include Cursor agent review
--all Include all available 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.

Argument Required Description
target branch No Base branch (default: main)

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

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

/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-secure-phase

Retroactively verify threat mitigations for a completed phase.

Argument Required Description
phase number No Phase to audit (default: last 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.

Argument Required Description
--force No Skip preservation prompts, regenerate all docs
--verify-only No Check existing docs for accuracy, no generation

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

Backlog & Thread Commands

/gsd-add-backlog

Add an idea to the backlog parking lot using 999.x numbering.

Argument Required Description
description Yes Backlog item description

999.x numbering keeps backlog items outside the active phase sequence. Phase directories are created immediately so /gsd-discuss-phase and /gsd-plan-phase work on them.

/gsd-add-backlog "GraphQL API layer"
/gsd-add-backlog "Mobile responsive redesign"

/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-plant-seed

Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone.

Argument Required Description
idea summary No Seed description (prompted if omitted)

Seeds solve context rot: instead of a one-liner in Deferred that nobody reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details.

Produces: .planning/seeds/SEED-NNN-slug.md Consumed by: /gsd-new-milestone (scans seeds and presents matches)

/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place"

/gsd-thread

Manage persistent context threads for cross-session work.

Argument Required Description
(none) / list List all threads
list --open List threads with status open or in_progress only
list --resolved List threads with status resolved only
status <slug> Show status of a specific thread
close <slug> Mark a thread as resolved
name Resume existing thread by name
description Create new thread

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.

Flag Description
--verify Dry-run mode — show proposed changes without writing

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).

Flag Description
--phase N Phase number that was planned
--plans N Number of plans generated

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.

Hook Purpose
gsd-validate-commit.sh Enforce Conventional Commits format on git commit messages
gsd-session-state.sh Track session state transitions
gsd-phase-boundary.sh Enforce phase boundary checks

Enable with:

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

/gsd-join-discord

Open Discord community invite.

/gsd-join-discord