A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the README.
- Workflow Diagrams
- UI Design Contract
- Spiking & Sketching
- Backlog & Threads
- Workstreams
- Security
- Command Reference
- Configuration Reference
- Usage Examples
- Troubleshooting
- Recovery Quick Reference
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
│ Questions -> Research -> Requirements -> Roadmap│
└─────────────────────────┬────────────────────────┘
│
┌──────────────▼─────────────┐
│ FOR EACH PHASE: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd-discuss-phase │ │ <- Lock in preferences
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ui-phase │ │ <- Design contract (frontend)
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-plan-phase │ │ <- Research + Plan + Verify
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-execute-phase │ │ <- Parallel execution
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-verify-work │ │ <- Manual UAT
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ship │ │ <- Create PR (optional)
│ └──────────┬─────────┘ │
│ │ │
│ Next Phase?────────────┘
│ │ No
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd-audit-milestone │
│ /gsd-complete-milestone │
└───────────────┬──────────────┘
│
Another milestone?
│ │
Yes No -> Done!
│
┌───────▼──────────────┐
│ /gsd-new-milestone │
└──────────────────────┘
/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
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.
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.
By default, /gsd-discuss-phase asks open-ended questions about your implementation preferences. Assumptions mode inverts this: GSD reads your codebase first, surfaces structured assumptions about how it would build the phase, and asks only for corrections.
Enable: Set workflow.discuss_mode to 'assumptions' via /gsd-settings.
How it works:
- Reads PROJECT.md, codebase mapping, and existing conventions
- Generates a structured list of assumptions (tech choices, patterns, file locations)
- Presents assumptions for you to confirm, correct, or expand
- Writes CONTEXT.md from confirmed assumptions
When to use:
- Experienced developers who already know their codebase well
- Rapid iteration where open-ended questions slow you down
- Projects where patterns are well-established and predictable
See docs/workflow-discuss-mode.md for the full discuss-mode reference.
AI-generated frontends are visually inconsistent not because Claude Code is bad at UI but because no design contract existed before execution. Five components built without a shared spacing scale, color contract, or copywriting standard produce five slightly different visual decisions.
/gsd-ui-phase locks the design contract before planning. /gsd-ui-review audits the result after execution.
| Command | Description |
|---|---|
/gsd-ui-phase [N] |
Generate UI-SPEC.md design contract for a frontend phase |
/gsd-ui-review [N] |
Retroactive 6-pillar visual audit of implemented UI |
When to run: After /gsd-discuss-phase, before /gsd-plan-phase — for phases with frontend/UI work.
Flow:
- Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
- Detects design system state (shadcn components.json, Tailwind config, existing tokens)
- shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
- Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety)
- Writes
{phase}-UI-SPEC.mdto phase directory - Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety)
- Revision loop if BLOCKED (max 2 iterations)
Output: {padded_phase}-UI-SPEC.md in .planning/phases/{phase-dir}/
When to run: After /gsd-execute-phase or /gsd-verify-work — for any project with frontend code.
Standalone: Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
6 Pillars (scored 1-4 each):
- Copywriting — CTA labels, empty states, error states
- Visuals — focal points, visual hierarchy, icon accessibility
- Color — accent usage discipline, 60/30/10 compliance
- Typography — font size/weight constraint adherence
- Spacing — grid alignment, token consistency
- Experience Design — loading/error/empty state coverage
Output: {padded_phase}-UI-REVIEW.md in phase directory with scores and top 3 priority fixes.
| Setting | Default | Description |
|---|---|---|
workflow.ui_phase |
true |
Generate UI design contracts for frontend phases |
workflow.ui_safety_gate |
true |
plan-phase prompts to run /gsd-ui-phase for frontend phases |
Both follow the absent=enabled pattern. Disable via /gsd-settings.
For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no components.json is found. The flow:
- Visit
ui.shadcn.com/createand configure your preset - Copy the preset string
- Run
npx shadcn init --preset {paste} - Preset encodes the entire design system — colors, border radius, fonts
The preset string becomes a first-class GSD planning artifact, reproducible across phases and milestones.
Third-party shadcn registries can inject arbitrary code. The safety gate requires:
npx shadcn view {component}— inspect before installingnpx shadcn diff {component}— compare against official
Controlled by workflow.ui_safety_gate config toggle.
/gsd-ui-review captures screenshots via Playwright CLI to .planning/ui-reviews/. A .gitignore is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during /gsd-complete-milestone.
Use /gsd-spike to validate technical feasibility before planning, and /gsd-sketch to explore visual direction before designing. Both store artifacts in .planning/ and integrate with the project-skills system via their wrap-up companions.
Spike when you're uncertain whether a technical approach is feasible or want to compare two implementations before committing a phase to one of them.
/gsd-spike # Interactive intake — describes the question, you confirm
/gsd-spike "can we stream LLM tokens through SSE"
/gsd-spike --quick "websocket vs SSE latency"
Each spike runs 2–5 experiments. Every experiment has:
- A Given / When / Then hypothesis written before any code
- Working code (not pseudocode)
- A VALIDATED / INVALIDATED / PARTIAL verdict with evidence
Results land in .planning/spikes/NNN-name/README.md and are indexed in .planning/spikes/MANIFEST.md.
Once you have signal, run /gsd-spike-wrap-up to package the findings into .claude/skills/spike-findings-[project]/ — future sessions will load them automatically via project-skills discovery.
Sketch when you need to compare layout structures, interaction models, or visual treatments before writing any real component code.
/gsd-sketch # Mood intake — explores feel, references, core action
/gsd-sketch "dashboard layout"
/gsd-sketch --quick "sidebar navigation"
/gsd-sketch --text "onboarding flow" # For non-Claude runtimes (Codex, Gemini, etc.)
Each sketch answers one design question with 2–3 variants in a single index.html you open directly in a browser — no build step. Variants use tab navigation and shared CSS variables from themes/default.css. All interactive elements (hover, click, transitions) are functional.
After picking a winner, run /gsd-sketch-wrap-up to capture the visual decisions into .claude/skills/sketch-findings-[project]/.
/gsd-spike "SSE vs WebSocket" # Validate the approach
/gsd-spike-wrap-up # Package learnings
/gsd-sketch "real-time feed UI" # Explore the design
/gsd-sketch-wrap-up # Package decisions
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/gsd-plan-phase N # Plan with confidence
Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
Backlog items get full phase directories, so you can use /gsd-discuss-phase 999.1 to explore an idea further or /gsd-plan-phase 999.1 when it's ready.
Review and promote with /gsd-review-backlog — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
/gsd-plant-seed "Add real-time collab when WebSocket infra is in place"
Seeds preserve the full WHY and WHEN to surface. /gsd-new-milestone scans all seeds and presents matches.
Storage: .planning/seeds/SEED-NNN-slug.md
Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
/gsd-thread # List all threads
/gsd-thread fix-deploy-key-auth # Resume existing thread
/gsd-thread "Investigate TCP timeout" # Create new thread
Threads are lighter weight than /gsd-pause-work — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
Threads can be promoted to phases (/gsd-add-phase) or backlog items (/gsd-add-backlog) when they mature.
Storage: .planning/threads/{slug}.md
Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated .planning/ state, so switching between them doesn't clobber progress.
When to use: You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed.
| Command | Purpose |
|---|---|
/gsd-workstreams create <name> |
Create a new workstream with isolated planning state |
/gsd-workstreams switch <name> |
Switch active context to a different workstream |
/gsd-workstreams list |
Show all workstreams and which is active |
/gsd-workstreams complete <name> |
Mark a workstream as done and archive its state |
Each workstream maintains its own .planning/ directory subtree. When you switch workstreams, GSD swaps the active planning context so that /gsd-progress, /gsd-discuss-phase, /gsd-plan-phase, and other commands operate on that workstream's state. Active context is session-scoped when the runtime exposes a stable session identifier, which prevents one terminal or AI instance from repointing another instance's STATE.md.
This is lighter weight than /gsd-new-workspace (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts.
GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
Path Traversal Prevention:
All user-supplied file paths (--text-file, --prd) are validated to resolve within the project directory. macOS /var → /private/var symlink resolution is handled.
Prompt Injection Detection:
The security.cjs module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
Runtime Hooks:
gsd-prompt-guard.js— Scans Write/Edit calls to.planning/for injection patterns (always active, advisory-only)gsd-workflow-guard.js— Warns on file edits outside GSD workflow context (opt-in viahooks.workflow_guard)
CI Scanner:
prompt-injection-scan.test.cjs scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
/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
├── Test quality audit (disabled tests, circular patterns, assertion strength)
│
├── PASS -> VERIFICATION.md (success)
└── FAIL -> Issues logged for /gsd-verify-work
/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
└──────────────────┘
After executing a phase, run a structured code review before UAT:
/gsd-code-review 3 # Review all changed files in phase 3
/gsd-code-review 3 --depth=deep # Deep cross-file review (import graphs, call chains)The reviewer scopes files automatically using SUMMARY.md (preferred) or git diff fallback. Findings are classified as Critical, Warning, or Info in {phase}-REVIEW.md.
/gsd-code-review-fix 3 # Fix Critical + Warning findings atomically
/gsd-code-review-fix 3 --auto # Fix and re-review until clean (max 3 iterations)To run an audit and fix all auto-fixable issues in one pass:
/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
/gsd-audit-fix --dry-run # Preview classification without fixingThe review step slots in after execution and before UAT:
/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review-fix N -> /gsd-verify-work N
Before committing to a new phase or plan, use /gsd-explore to think through the idea:
/gsd-explore # Open-ended ideation
/gsd-explore "caching strategy" # Explore a specific topicThe exploration session guides you through probing questions, optionally spawns a research agent, and routes output to the appropriate GSD artifact: note, todo, seed, research question, requirements update, or new phase.
For queryable codebase insights without reading the entire codebase, enable the intel system:
{ "intel": { "enabled": true } }Then build the index:
/gsd-intel refresh # Analyze codebase and write .planning/intel/ files
/gsd-intel query auth # Search for a term across all intel files
/gsd-intel status # Check freshness of intel files
/gsd-intel diff # See what changed since last snapshotIntel files cover stack, API surface, dependency graph, file roles, and architecture decisions.
For a focused assessment without full /gsd-map-codebase overhead:
/gsd-scan # Quick tech + arch overview
/gsd-scan --focus quality # Quality and code health only
/gsd-scan --focus concerns # Risk areas and concerns| 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-ui-phase [N] |
Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) |
/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-ship [N] |
Create PR from verified work | After verification passes |
/gsd-fast <text> |
Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors |
/gsd-next |
Auto-detect state and run next step | Anytime — "what should I do next?" |
/gsd-ui-review [N] |
Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
/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 |
| 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 structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
/gsd-session-report |
Generate session summary with work and outcomes | End of session, stakeholder sharing |
/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 |
| 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-analyze-dependencies |
Detect phase dependencies for ROADMAP.md | Before /gsd-manager when phases have empty Depends on |
/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 |
| Command | Purpose | When to Use |
|---|---|---|
/gsd-map-codebase |
Analyze existing codebase (4 parallel agents) | Before /gsd-new-project on existing code |
/gsd-scan [--focus area] |
Rapid single-focus codebase scan (1 agent) | Quick assessment of a specific area |
/gsd-intel [query|status|diff|refresh] |
Query codebase intelligence index | Look up APIs, deps, or architecture decisions |
/gsd-explore [topic] |
Socratic ideation — think through an idea before committing | Exploring unfamiliar solution space |
/gsd-quick |
Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes |
/gsd-autonomous |
Run remaining phases autonomously (--from N, --to N) |
Hands-free multi-phase execution |
/gsd-undo --last N|--phase NN|--plan NN-MM |
Safe git revert using phase manifest | Roll back a bad execution |
/gsd-import --from <file> |
Ingest external plan with conflict detection | Import plans from teammates or other tools |
/gsd-debug [desc] |
Systematic debugging with persistent state (--diagnose for no-fix mode) |
When something breaks |
/gsd-forensics |
Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted |
/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 |
| Command | Purpose | When to Use |
|---|---|---|
/gsd-review --phase N |
Cross-AI peer review from external CLIs | Before executing, to validate plans |
/gsd-code-review <N> |
Review source files changed in a phase for bugs and security issues | After execution, before verification |
/gsd-code-review-fix <N> |
Auto-fix issues found by /gsd-code-review |
After code review produces REVIEW.md |
/gsd-audit-fix |
Autonomous audit-to-fix pipeline with classification and atomic commits | After UAT surfaces fixable issues |
/gsd-pr-branch |
Clean PR branch filtering .planning/ commits |
Before creating PR with planning-free diff |
/gsd-audit-uat |
Audit verification debt across all phases | Before milestone completion |
| Command | Purpose | When to Use |
|---|---|---|
/gsd-add-backlog <desc> |
Add idea to backlog parking lot (999.x) | Ideas not ready for active planning |
/gsd-review-backlog |
Promote/keep/remove backlog items | Before new milestone, to prioritize |
/gsd-plant-seed <idea> |
Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone |
/gsd-thread [name] |
Persistent context threads | Cross-session work outside the phase structure |
GSD stores project settings in .planning/config.json. Configure during /gsd-new-project or update later with /gsd-settings.
{
"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,
"ui_phase": true,
"ui_safety_gate": true,
"research_before_questions": false,
"discuss_mode": "standard",
"skip_discuss": false
},
"resolve_model_ids": "anthropic",
"hooks": {
"context_warnings": true,
"workflow_guard": false
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"quick_branch_template": null
}
}| 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, inherit |
balanced |
Model tier for each agent (see table below) |
| 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_docsis automaticallyfalseregardless of the config value.
| 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 |
workflow.ui_phase |
true, false |
true |
Generate UI design contracts for frontend phases |
workflow.ui_safety_gate |
true, false |
true |
plan-phase prompts to run /gsd-ui-phase for frontend phases |
workflow.research_before_questions |
true, false |
false |
Run research before discussion questions instead of after |
workflow.discuss_mode |
standard, assumptions |
standard |
Discussion style: open-ended questions vs. codebase-driven assumptions |
workflow.skip_discuss |
true, false |
false |
Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal |
response_language |
language code | (none) | Agent response language for cross-phase consistency (e.g., "pt", "ko", "ja") |
| Setting | Options | Default | What it Controls |
|---|---|---|---|
hooks.context_warnings |
true, false |
true |
Context window usage warnings |
hooks.workflow_guard |
true, false |
false |
Warn on file edits outside GSD workflow context |
Disable workflow toggles to speed up phases in familiar domains or when conserving tokens.
| 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 |
git.quick_branch_template |
Template string or null |
null |
Optional branch name for /gsd-quick tasks |
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"), {num} / {quick} = quick task ID (e.g., "260317-abc").
Example quick-task branching:
"git": {
"quick_branch_template": "gsd/quick-{num}-{slug}"
}| Agent | quality |
balanced |
budget |
inherit |
|---|---|---|---|---|
| gsd-planner | Opus | Opus | Sonnet | Inherit |
| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
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.
- inherit -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode or Kilo
/model), or when using Claude Code with non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs. For non-Claude runtimes (Codex, OpenCode, Gemini CLI, Kilo), the installer setsresolve_model_ids: "omit"automatically -- see Non-Claude Runtimes.
claude --dangerously-skip-permissions
/gsd-new-project # Answer questions, configure, approve roadmap
/clear
/gsd-discuss-phase 1 # Lock in your preferences
/gsd-ui-phase 1 # Design contract (frontend phases)
/gsd-plan-phase 1 # Research + plan + verify
/gsd-execute-phase 1 # Parallel execution
/gsd-verify-work 1 # Manual UAT
/gsd-ship 1 # Create PR from verified work
/gsd-ui-review 1 # Visual audit (frontend phases)
/clear
/gsd-next # Auto-detect and run next step
...
/gsd-audit-milestone # Check everything shipped
/gsd-complete-milestone # Archive, tag, done
/gsd-session-report # Generate session summary/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/clear
/gsd-discuss-phase 1 # Normal flow from here/gsd-map-codebase # Analyze what exists (parallel agents)
/gsd-new-project # Questions focus on what you're ADDING
# (normal phase workflow from here)/gsd-quick
> "Fix the login button not responding on mobile Safari"/gsd-progress # See where you left off and what's next
# or
/gsd-resume-work # Full context restoration from last session/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| 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 |
Skipping discuss-phase in autonomous mode: When running in yolo mode with well-established preferences already captured in PROJECT.md, set workflow.skip_discuss: true via /gsd-settings. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
/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 renumberWork on multiple repos or features in parallel with isolated GSD state.
# Create a workspace with repos from your monorepo
/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI
# Feature branch isolation — worktree of current repo with its own .planning/
/gsd-new-workspace --name feature-b --repos .
# Then cd into the workspace and initialize GSD
cd ~/gsd-workspaces/feature-b
/gsd-new-project
# List and manage workspaces
/gsd-list-workspaces
/gsd-remove-workspace feature-bEach workspace gets:
- Its own
.planning/directory (fully independent from source repos) - Git worktrees (default) or clones of specified repos
- A
WORKSPACE.mdmanifest tracking member repos
For automation and copy-paste from docs, prefer gsd-sdk query with a registered subcommand (see CLI-TOOLS.md and QUERY-HANDLERS.md). The legacy node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs CLI remains supported for dual-mode operation.
Not yet on gsd-sdk query (use CJS): state validate, state sync, audit-open, graphify, from-gsd2, and any subcommand not listed in the registry.
If STATE.md shows incorrect phase status or position, use the state consistency commands (CJS-only until ported to the query layer):
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift between STATE.md and filesystem
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview what sync would change
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md from diskThese commands are new in v1.32 and replace manual STATE.md editing.
Some non-Claude runtimes (Cline, Augment Code) may enter an infinite retry loop when an agent attempts to edit a file it hasn't read. The gsd-read-before-edit.js hook (v1.32) detects this pattern and advises reading the file first. If your runtime doesn't support PreToolUse hooks, add this to your project's CLAUDE.md:
## Edit Safety Rule
Always read a file before editing it. Never call Edit or Write on a file you haven't read in this session.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.
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.
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.
/gsd-discuss-phase adapts its language based on your USER-PROFILE.md. If the profile indicates a non-technical owner — learning_style: guided, jargon listed as a frustration trigger, or explanation_depth: high-level — gray area questions are automatically reframed in product-outcome language instead of implementation terminology.
To enable this: run /gsd-profile-user to generate your profile. The profile is stored at ~/.claude/get-shit-done/USER-PROFILE.md and is read automatically on every /gsd-discuss-phase invocation. No other configuration is required.
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.
Run /gsd-progress. It reads all state files and tells you exactly where you are and what to do next.
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.
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).
If you installed GSD for a non-Claude runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets resolve_model_ids: "omit" in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
To assign different models to different agents on a non-Claude runtime, add model_overrides to .planning/config.json with fully-qualified model IDs that your runtime recognizes:
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
}
}The installer auto-configures resolve_model_ids: "omit" for Gemini CLI, OpenCode, Kilo, and Codex. If you're manually setting up a non-Claude runtime, add it to .planning/config.json yourself.
See the Configuration Reference for the full explanation.
Cline uses a rules-based integration — GSD installs as .clinerules rather than slash commands.
# Global install (applies to all projects)
npx get-shit-done-cc --cline --global
# Local install (this project only)
npx get-shit-done-cc --cline --localGlobal installs write to ~/.cline/. Local installs write to ./.cline/. No custom slash commands are registered — GSD rules are loaded automatically by Cline from the rules file.
CodeBuddy uses a skills-based integration.
npx get-shit-done-cc --codebuddy --globalSkills are installed to ~/.codebuddy/skills/gsd-*/SKILL.md.
Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
npx get-shit-done-cc --qwen --globalSkills are installed to ~/.qwen/skills/gsd-*/SKILL.md. Use the QWEN_CONFIG_DIR environment variable to override the default install path.
If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the inherit profile: /gsd-set-profile inherit. This makes all agents use your current session model instead of specific Anthropic models. See also /gsd-settings → Model Profile → Inherit.
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.
Since v1.17, the installer backs up locally modified files to gsd-local-patches/. Run /gsd-reapply-patches to merge your changes back.
If npx get-shit-done-cc fails due to npm outages or network restrictions, see docs/manual-update.md for a step-by-step manual update procedure that works without npm access.
When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run /gsd-forensics to generate a diagnostic report.
What it checks:
- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
- Artifact integrity (missing or malformed planning files, broken cross-references)
- State inconsistencies (ROADMAP status vs. actual file presence, config drift)
Output: A diagnostic report written to .planning/forensics/ with findings and suggested remediation steps.
GSD's gsd-executor subagents need write-capable Bash access to a project's standard tooling — git commit, bin/rails, bundle exec, npm run, uv run, and similar commands. Claude Code's default ~/.claude/settings.json only allows a narrow set of read-only git commands, so a fresh install will hit "Permission to use Bash has been denied" the first time an executor tries to make a commit or run a build tool.
Fix: add the required patterns to ~/.claude/settings.json.
The patterns you need depend on your stack. Copy the block for your stack and add it to the permissions.allow array.
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git worktree:*)",
"Bash(git rebase:*)",
"Bash(git reset:*)",
"Bash(git checkout:*)",
"Bash(git switch:*)",
"Bash(git restore:*)",
"Bash(git stash:*)",
"Bash(git rm:*)",
"Bash(git mv:*)",
"Bash(git fetch:*)",
"Bash(git cherry-pick:*)",
"Bash(git apply:*)",
"Bash(gh:*)""Bash(bin/rails:*)",
"Bash(bin/brakeman:*)",
"Bash(bin/bundler-audit:*)",
"Bash(bin/importmap:*)",
"Bash(bundle:*)",
"Bash(rubocop:*)",
"Bash(erb_lint:*)""Bash(uv:*)",
"Bash(python:*)",
"Bash(pytest:*)",
"Bash(ruff:*)",
"Bash(mypy:*)""Bash(npm:*)",
"Bash(npx:*)",
"Bash(pnpm:*)",
"Bash(bun:*)",
"Bash(node:*)""Bash(cargo:*)"Example ~/.claude/settings.json snippet (Rails project):
{
"permissions": {
"allow": [
"Write",
"Edit",
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git worktree:*)",
"Bash(git rebase:*)",
"Bash(git reset:*)",
"Bash(git checkout:*)",
"Bash(git switch:*)",
"Bash(git restore:*)",
"Bash(git stash:*)",
"Bash(git rm:*)",
"Bash(git mv:*)",
"Bash(git fetch:*)",
"Bash(git cherry-pick:*)",
"Bash(git apply:*)",
"Bash(gh:*)",
"Bash(bin/rails:*)",
"Bash(bin/brakeman:*)",
"Bash(bin/bundler-audit:*)",
"Bash(bundle:*)",
"Bash(rubocop:*)"
]
}
}Per-project permissions (scoped to one repo): If you prefer to allow these patterns for a single project rather than globally, add the same permissions.allow block to .claude/settings.local.json in your project root instead of ~/.claude/settings.json. Claude Code checks project-local settings first.
Interactive guidance: When an executor is blocked mid-phase, it will identify the exact pattern needed (e.g. "Bash(bin/rails:*)") so you can add it and re-run /gsd-execute-phase.
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.
If you see pre-commit hook failures, cargo lock contention, or 30+ minute execution times during parallel wave execution, this is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26 — parallel agents use --no-verify on commits and the orchestrator runs hooks once after each wave. If you're on an older version, add this to your project's CLAUDE.md:
## Git Commit Rules for Agents
All subagent/executor commits MUST use `--no-verify`.To disable parallel execution entirely: /gsd-settings → set parallelization.enabled to false.
If the installer crashes with EPERM: operation not permitted, scandir on Windows, this is caused by OS-protected directories (e.g., Chromium browser profiles). Fixed since v1.24 — update to the latest version. As a workaround, temporarily rename the problematic directory before running the installer.
| 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" (add --diagnose for analysis without fixes) |
| STATE.md out of sync | state validate then state sync |
| Workflow state seems corrupted | /gsd-forensics |
| 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 |
| Want session summary for stakeholder | /gsd-session-report |
| Don't know what step is next | /gsd-next |
| Parallel execution build errors | Update GSD or set parallelization.enabled: false |
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
HANDOFF.json # Structured session handoff (from /gsd-pause-work)
research/ # Domain research from /gsd-new-project
reports/ # Session reports (from /gsd-session-report)
todos/
pending/ # Captured ideas awaiting work
done/ # Completed todos
debug/ # Active debug sessions
resolved/ # Archived debug sessions
spikes/ # Feasibility experiments (from /gsd-spike)
NNN-name/ # Experiment code + README with verdict
MANIFEST.md # Index of all spikes
sketches/ # HTML mockups (from /gsd-sketch)
NNN-name/ # index.html (2-3 variants) + README
themes/
default.css # Shared CSS variables for all sketches
MANIFEST.md # Index of all sketches with winners
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
XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)