GSD User Guide

A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the README.

Workflow Diagrams
Command Reference
Configuration Reference
Usage Examples
Troubleshooting
Recovery Quick Reference

Workflow Diagrams

Full Project Lifecycle

  ┌──────────────────────────────────────────────────┐
  │                   NEW PROJECT                    │
  │  /gsd:new-project                                │
  │  Questions -> Research -> Requirements -> Roadmap│
  └─────────────────────────┬────────────────────────┘
                            │
             ┌──────────────▼─────────────┐
             │      FOR EACH PHASE:       │
             │                            │
             │  ┌────────────────────┐    │
             │  │ /gsd:discuss-phase │    │  <- Lock in preferences
             │  └──────────┬─────────┘    │
             │             │              │
             │  ┌──────────▼─────────┐    │
             │  │ /gsd:plan-phase    │    │  <- Research + Plan + Verify
             │  └──────────┬─────────┘    │
             │             │              │
             │  ┌──────────▼─────────┐    │
             │  │ /gsd:execute-phase │    │  <- Parallel execution
             │  └──────────┬─────────┘    │
             │             │              │
             │  ┌──────────▼─────────┐    │
             │  │ /gsd:verify-work   │    │  <- Manual UAT
             │  └──────────┬─────────┘    │
             │             │              │
             │     Next Phase?────────────┘
             │             │ No
             └─────────────┼──────────────┘
                            │
            ┌───────────────▼──────────────┐
            │  /gsd:audit-milestone        │
            │  /gsd:complete-milestone     │
            └───────────────┬──────────────┘
                            │
                   Another milestone?
                       │          │
                      Yes         No -> Done!
                       │
               ┌───────▼──────────────┐
               │  /gsd:new-milestone  │
               └──────────────────────┘

Planning Agent Coordination

  /gsd:plan-phase N
         │
         ├── Phase Researcher (x4 parallel)
         │     ├── Stack researcher
         │     ├── Features researcher
         │     ├── Architecture researcher
         │     └── Pitfalls researcher
         │           │
         │     ┌──────▼──────┐
         │     │ RESEARCH.md │
         │     └──────┬──────┘
         │            │
         │     ┌──────▼──────┐
         │     │   Planner   │  <- Reads PROJECT.md, REQUIREMENTS.md,
         │     │             │     CONTEXT.md, RESEARCH.md
         │     └──────┬──────┘
         │            │
         │     ┌──────▼───────────┐     ┌────────┐
         │     │   Plan Checker   │────>│ PASS?  │
         │     └──────────────────┘     └───┬────┘
         │                                  │
         │                             Yes  │  No
         │                              │   │   │
         │                              │   └───┘  (loop, up to 3x)
         │                              │
         │                        ┌─────▼──────┐
         │                        │ PLAN files │
         │                        └────────────┘
         └── Done

Validation Architecture (Nyquist Layer)

During plan-phase research, GSD now maps automated test coverage to each phase requirement before any code is written. This ensures that when Claude's executor commits a task, a feedback mechanism already exists to verify it within seconds.

The researcher detects your existing test infrastructure, maps each requirement to a specific test command, and identifies any test scaffolding that must be created before implementation begins (Wave 0 tasks).

The plan-checker enforces this as an 8th verification dimension: plans where tasks lack automated verify commands will not be approved.

Output: {phase}-VALIDATION.md -- the feedback contract for the phase.

Disable: Set workflow.nyquist_validation: false in /gsd:settings for rapid prototyping phases where test infrastructure isn't the focus.

Retroactive Validation (`/gsd:validate-phase`)

For phases executed before Nyquist validation existed, or for existing codebases with only traditional test suites, retroactively audit and fill coverage gaps:

  /gsd:validate-phase N
         |
         +-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
         |
         +-- Discover: scan implementation, map requirements to tests
         |
         +-- Analyze gaps: which requirements lack automated verification?
         |
         +-- Present gap plan for approval
         |
         +-- Spawn auditor: generate tests, run, debug (max 3 attempts)
         |
         +-- Update VALIDATION.md
               |
               +-- COMPLIANT -> all requirements have automated checks
               +-- PARTIAL -> some gaps escalated to manual-only

The auditor never modifies implementation code — only test files and VALIDATION.md. If a test reveals an implementation bug, it's flagged as an escalation for you to address.

When to use: After executing phases that were planned before Nyquist was enabled, or after /gsd:audit-milestone surfaces Nyquist compliance gaps.

Execution Wave Coordination

  /gsd:execute-phase N
         │
         ├── Analyze plan dependencies
         │
         ├── Wave 1 (independent plans):
         │     ├── Executor A (fresh 200K context) -> commit
         │     └── Executor B (fresh 200K context) -> commit
         │
         ├── Wave 2 (depends on Wave 1):
         │     └── Executor C (fresh 200K context) -> commit
         │
         └── Verifier
               └── Check codebase against phase goals
                     │
                     ├── PASS -> VERIFICATION.md (success)
                     └── FAIL -> Issues logged for /gsd:verify-work

Brownfield Workflow (Existing Codebase)

  /gsd:map-codebase
         │
         ├── Stack Mapper     -> codebase/STACK.md
         ├── Arch Mapper      -> codebase/ARCHITECTURE.md
         ├── Convention Mapper -> codebase/CONVENTIONS.md
         └── Concern Mapper   -> codebase/CONCERNS.md
                │
        ┌───────▼──────────┐
        │ /gsd:new-project │  <- Questions focus on what you're ADDING
        └──────────────────┘

Command Reference

Core Workflow

Command	Purpose	When to Use
`/gsd:new-project`	Full project init: questions, research, requirements, roadmap	Start of a new project
`/gsd:new-project --auto @idea.md`	Automated init from document	Have a PRD or idea doc ready
`/gsd:discuss-phase [N]`	Capture implementation decisions	Before planning, to shape how it gets built
`/gsd:plan-phase [N]`	Research + plan + verify	Before executing a phase
`/gsd:execute-phase <N>`	Execute all plans in parallel waves	After planning is complete
`/gsd:verify-work [N]`	Manual UAT with auto-diagnosis	After execution completes
`/gsd:audit-milestone`	Verify milestone met its definition of done	Before completing milestone
`/gsd:complete-milestone`	Archive milestone, tag release	All phases verified
`/gsd:new-milestone [name]`	Start next version cycle	After completing a milestone

Navigation

Command	Purpose	When to Use
`/gsd:progress`	Show status and next steps	Anytime -- "where am I?"
`/gsd:resume-work`	Restore full context from last session	Starting a new session
`/gsd:pause-work`	Save context handoff	Stopping mid-phase
`/gsd:help`	Show all commands	Quick reference
`/gsd:update`	Update GSD with changelog preview	Check for new versions
`/gsd:join-discord`	Open Discord community invite	Questions or community

Phase Management

Command	Purpose	When to Use
`/gsd:add-phase`	Append new phase to roadmap	Scope grows after initial planning
`/gsd:insert-phase [N]`	Insert urgent work (decimal numbering)	Urgent fix mid-milestone
`/gsd:remove-phase [N]`	Remove future phase and renumber	Descoping a feature
`/gsd:list-phase-assumptions [N]`	Preview Claude's intended approach	Before planning, to validate direction
`/gsd:plan-milestone-gaps`	Create phases for audit gaps	After audit finds missing items
`/gsd:research-phase [N]`	Deep ecosystem research only	Complex or unfamiliar domain

Brownfield & Utilities

Command	Purpose	When to Use
`/gsd:map-codebase`	Analyze existing codebase	Before `/gsd:new-project` on existing code
`/gsd:quick`	Ad-hoc task with GSD guarantees	Bug fixes, small features, config changes
`/gsd:debug [desc]`	Systematic debugging with persistent state	When something breaks
`/gsd:add-todo [desc]`	Capture an idea for later	Think of something during a session
`/gsd:check-todos`	List pending todos	Review captured ideas
`/gsd:settings`	Configure workflow toggles and model profile	Change model, toggle agents
`/gsd:set-profile <profile>`	Quick profile switch	Change cost/quality tradeoff
`/gsd:reapply-patches`	Restore local modifications after update	After `/gsd:update` if you had local edits

Configuration Reference

GSD stores project settings in .planning/config.json. Configure during /gsd:new-project or update later with /gsd:settings.

Full config.json Schema

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  }
}

Core Settings

Setting	Options	Default	What it Controls
`mode`	`interactive`, `yolo`	`interactive`	`yolo` auto-approves decisions; `interactive` confirms at each step
`granularity`	`coarse`, `standard`, `fine`	`standard`	Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases)
`model_profile`	`quality`, `balanced`, `budget`	`balanced`	Model tier for each agent (see table below)

Planning Settings

Setting	Options	Default	What it Controls
`planning.commit_docs`	`true`, `false`	`true`	Whether `.planning/` files are committed to git
`planning.search_gitignored`	`true`, `false`	`false`	Add `--no-ignore` to broad searches to include `.planning/`

Note: If .planning/ is in .gitignore, commit_docs is automatically false regardless of the config value.

Workflow Toggles

Setting	Options	Default	What it Controls
`workflow.research`	`true`, `false`	`true`	Domain investigation before planning
`workflow.plan_check`	`true`, `false`	`true`	Plan verification loop (up to 3 iterations)
`workflow.verifier`	`true`, `false`	`true`	Post-execution verification against phase goals
`workflow.nyquist_validation`	`true`, `false`	`true`	Validation architecture research during plan-phase; 8th plan-check dimension

Disable these to speed up phases in familiar domains or when conserving tokens.

Git Branching

Setting	Options	Default	What it Controls
`git.branching_strategy`	`none`, `phase`, `milestone`	`none`	When and how branches are created
`git.phase_branch_template`	Template string	`gsd/phase-{phase}-{slug}`	Branch name for phase strategy
`git.milestone_branch_template`	Template string	`gsd/{milestone}-{slug}`	Branch name for milestone strategy

Branching strategies explained:

Strategy	Creates Branch	Scope	Best For
`none`	Never	N/A	Solo development, simple projects
`phase`	At each `execute-phase`	One phase per branch	Code review per phase, granular rollback
`milestone`	At first `execute-phase`	All phases share one branch	Release branches, PR per version

Template variables: {phase} = zero-padded number (e.g., "03"), {slug} = lowercase hyphenated name, {milestone} = version (e.g., "v1.0").

Model Profiles (Per-Agent Breakdown)

Agent	`quality`	`balanced`	`budget`
gsd-planner	Opus	Opus	Sonnet
gsd-roadmapper	Opus	Sonnet	Sonnet
gsd-executor	Opus	Sonnet	Sonnet
gsd-phase-researcher	Opus	Sonnet	Haiku
gsd-project-researcher	Opus	Sonnet	Haiku
gsd-research-synthesizer	Sonnet	Sonnet	Haiku
gsd-debugger	Opus	Sonnet	Sonnet
gsd-codebase-mapper	Sonnet	Haiku	Haiku
gsd-verifier	Sonnet	Sonnet	Haiku
gsd-plan-checker	Sonnet	Sonnet	Haiku
gsd-integration-checker	Sonnet	Sonnet	Haiku

Profile philosophy:

quality -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical.
balanced -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
budget -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases.

Usage Examples

New Project (Full Cycle)

claude --dangerously-skip-permissions
/gsd:new-project            # Answer questions, configure, approve roadmap
/clear
/gsd:discuss-phase 1        # Lock in your preferences
/gsd:plan-phase 1           # Research + plan + verify
/gsd:execute-phase 1        # Parallel execution
/gsd:verify-work 1          # Manual UAT
/clear
/gsd:discuss-phase 2        # Repeat for each phase
...
/gsd:audit-milestone        # Check everything shipped
/gsd:complete-milestone     # Archive, tag, done

New Project from Existing Document

/gsd:new-project --auto @prd.md   # Auto-runs research/requirements/roadmap from your doc
/clear
/gsd:discuss-phase 1               # Normal flow from here

Existing Codebase

/gsd:map-codebase           # Analyze what exists (parallel agents)
/gsd:new-project            # Questions focus on what you're ADDING
# (normal phase workflow from here)

Quick Bug Fix

/gsd:quick
> "Fix the login button not responding on mobile Safari"

Resuming After a Break

/gsd:progress               # See where you left off and what's next
# or
/gsd:resume-work            # Full context restoration from last session

Preparing for Release

/gsd:audit-milestone        # Check requirements coverage, detect stubs
/gsd:plan-milestone-gaps    # If audit found gaps, create phases to close them
/gsd:complete-milestone     # Archive, tag, done

Speed vs Quality Presets

Scenario	Mode	Granularity	Profile	Research	Plan Check	Verifier
Prototyping	`yolo`	`coarse`	`budget`	off	off	off
Normal dev	`interactive`	`standard`	`balanced`	on	on	on
Production	`interactive`	`fine`	`quality`	on	on	on

Mid-Milestone Scope Changes

/gsd:add-phase              # Append a new phase to the roadmap
# or
/gsd:insert-phase 3         # Insert urgent work between phases 3 and 4
# or
/gsd:remove-phase 7         # Descope phase 7 and renumber

Troubleshooting

"Project already initialized"

You ran /gsd:new-project but .planning/PROJECT.md already exists. This is a safety check. If you want to start over, delete the .planning/ directory first.

Context Degradation During Long Sessions

Clear your context window between major commands: /clear in Claude Code. GSD is designed around fresh contexts -- every subagent gets a clean 200K window. If quality is dropping in the main session, clear and use /gsd:resume-work or /gsd:progress to restore state.

Plans Seem Wrong or Misaligned

Run /gsd:discuss-phase [N] before planning. Most plan quality issues come from Claude making assumptions that CONTEXT.md would have prevented. You can also run /gsd:list-phase-assumptions [N] to see what Claude intends to do before committing to a plan.

Execution Fails or Produces Stubs

Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.

Lost Track of Where You Are

Run /gsd:progress. It reads all state files and tells you exactly where you are and what to do next.

Need to Change Something After Execution

Do not re-run /gsd:execute-phase. Use /gsd:quick for targeted fixes, or /gsd:verify-work to systematically identify and fix issues through UAT.

Model Costs Too High

Switch to budget profile: /gsd:set-profile budget. Disable research and plan-check agents via /gsd:settings if the domain is familiar to you (or to Claude).

Working on a Sensitive/Private Project

Set commit_docs: false during /gsd:new-project or via /gsd:settings. Add .planning/ to your .gitignore. Planning artifacts stay local and never touch git.

GSD Update Overwrote My Local Changes

Since v1.17, the installer backs up locally modified files to gsd-local-patches/. Run /gsd:reapply-patches to merge your changes back.

Subagent Appears to Fail but Work Was Done

A known workaround exists for a Claude Code classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check git log -- the work may have succeeded.

Recovery Quick Reference

Problem	Solution
Lost context / new session	`/gsd:resume-work` or `/gsd:progress`
Phase went wrong	`git revert` the phase commits, then re-plan
Need to change scope	`/gsd:add-phase`, `/gsd:insert-phase`, or `/gsd:remove-phase`
Milestone audit found gaps	`/gsd:plan-milestone-gaps`
Something broke	`/gsd:debug "description"`
Quick targeted fix	`/gsd:quick`
Plan doesn't match your vision	`/gsd:discuss-phase [N]` then re-plan
Costs running high	`/gsd:set-profile budget` and `/gsd:settings` to toggle agents off
Update broke local changes	`/gsd:reapply-patches`

Project File Structure

For reference, here is what GSD creates in your project:

.planning/
  PROJECT.md              # Project vision and context (always loaded)
  REQUIREMENTS.md         # Scoped v1/v2 requirements with IDs
  ROADMAP.md              # Phase breakdown with status tracking
  STATE.md                # Decisions, blockers, session memory
  config.json             # Workflow configuration
  MILESTONES.md           # Completed milestone archive
  research/               # Domain research from /gsd:new-project
  todos/
    pending/              # Captured ideas awaiting work
    done/                 # Completed todos
  debug/                  # Active debug sessions
    resolved/             # Archived debug sessions
  codebase/               # Brownfield codebase mapping (from /gsd:map-codebase)
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Atomic execution plans
      XX-YY-SUMMARY.md    # Execution outcomes and decisions
      CONTEXT.md          # Your implementation preferences
      RESEARCH.md         # Ecosystem research findings
      VERIFICATION.md     # Post-execution verification results

Uh oh!

FilesExpand file tree

USER-GUIDE.md

Latest commit

History