get-shit-done/docs/USER-GUIDE.md

GSD User Guide

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

---

Table of Contents

• Workflow Diagrams
• UI Design Contract
• Backlog & Threads
• Security
• 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: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  │
               └──────────────────────┘

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.

---

UI Design Contract

Why

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.

Commands

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

Workflow: /gsd:ui-phase

When to run: After /gsd:discuss-phase, before /gsd:plan-phase — for phases with frontend/UI work.

Flow:

1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
4. Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety)
5. Writes {phase}-UI-SPEC.md to phase directory
6. Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety)
7. Revision loop if BLOCKED (max 2 iterations)

Output: {padded_phase}-UI-SPEC.md in .planning/phases/{phase-dir}/

Workflow: /gsd:ui-review

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

1. Copywriting — CTA labels, empty states, error states
2. Visuals — focal points, visual hierarchy, icon accessibility
3. Color — accent usage discipline, 60/30/10 compliance
4. Typography — font size/weight constraint adherence
5. Spacing — grid alignment, token consistency
6. Experience Design — loading/error/empty state coverage

Output: {padded_phase}-UI-REVIEW.md in phase directory with scores and top 3 priority fixes.

Configuration

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.

shadcn Initialization

For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no components.json is found. The flow:

1. Visit ui.shadcn.com/create and configure your preset
2. Copy the preset string
3. Run npx shadcn init --preset {paste}
4. 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.

Registry Safety Gate

Third-party shadcn registries can inject arbitrary code. The safety gate requires:

• npx shadcn view {component} — inspect before installing
• npx shadcn diff {component} — compare against official

Controlled by workflow.ui_safety_gate config toggle.

Screenshot Storage

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

---

Backlog & Threads

Backlog Parking Lot

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

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

Persistent Context Threads

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

---

Security

Defense-in-Depth (v1.27)

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 via hooks.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.

---

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

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

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

Code Quality & Review

Command	Purpose	When to Use
/gsd:review --phase N	Cross-AI peer review from external CLIs	Before executing, to validate plans
/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

Backlog & Threads

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

---

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,
    "ui_phase": true,
    "ui_safety_gate": true,
    "research_before_questions": false
  },
  "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
  }
}

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, inherit	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
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

Hook Settings

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.

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
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}"
}

Model Profiles (Per-Agent Breakdown)

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 /model), or required when using non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs.

---

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

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

Multi-Project Workspaces

Work 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-b

Each workspace gets:

• Its own .planning/ directory (fully independent from source repos)
• Git worktrees (default) or clones of specified repos
• A WORKSPACE.md manifest tracking member repos

---

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

Using Non-Anthropic Models (OpenRouter, Local)

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.

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.

Parallel Execution Causes Build Lock Errors

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.

Windows: Installation Crashes on Protected Directories

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.

---

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

---

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