GSD (Get Shit Done) — User Guide

GSD is a meta-prompting, context-engineering, and spec-driven development system that runs inside your AI coding agent. Instead of typing one long prompt and hoping the model gets it right, you drive a structured pipeline — discuss → plan → execute → verify → ship — where each step writes durable Markdown artifacts that the next step reads. The result is repeatable, reviewable AI development with far less context rot and far fewer hallucinated implementations.

GSD installs as a set of slash commands (and agents, hooks, and skills) into Claude Code and 14 other AI coding runtimes. You invoke it with commands like /gsd-new-project and /gsd-plan-phase; GSD orchestrates specialized sub-agents behind the scenes and keeps all project state in a human-readable .planning/ directory.

Important

This repository has been archived. The version documented here (get-shit-done-cc v1.50.0-canary.0, commit bdcaab2) is the final state of gsd-build/get-shit-done. Active development has moved to GSD Core at github.com/open-gsd/gsd-core. This guide documents the code exactly as it exists at the archived commit; for current releases, install from the successor project. The install commands below reflect both the package name in this repository's package.json (get-shit-done-cc) and the redux package referenced throughout the bundled docs (@opengsd/get-shit-done-redux).

Table of Contents

1. What GSD Does
2. Quick Start
3. Installation
4. Core Concepts
5. The Phase Workflow (End-to-End)
6. Everyday Commands
7. Working Recipes
8. Quality Gates & Reviews
9. Exploration: Spike, Sketch, Explore
10. Capture, Backlog, Seeds & Threads
11. Multi-Stream & Multi-Repo Work
12. Tuning Cost & Speed
13. Security You Get for Free
14. Command Reference
15. Troubleshooting
16. Recovery Quick Reference
17. FAQ

What GSD Does

Modern AI coding agents are powerful but unstructured. Drop a big feature request into a single chat and quality degrades as the context window fills with conversation — a problem GSD calls context rot. GSD solves this with three ideas:

• Context engineering. Every task an agent performs is fed exactly the artifacts it needs (project vision, requirements, phase preferences, research) and nothing else.
• Multi-agent orchestration. Thin orchestrators spawn specialized agents — researchers, planners, executors, verifiers — each with a fresh context window, so no single agent drowns in accumulated history.
• Spec-driven development. Work flows through an explicit pipeline: requirements → research → plans → execution → verification. Each stage produces files you can read, edit, and commit to git.

You stay in control. GSD asks before it builds, verifies after it builds, and records every decision so you (or a teammate, or a fresh session tomorrow) can pick up exactly where you left off.

Note

GSD is a methodology layer, not a coding model. It runs on top of whatever AI agent you already use (Claude Code, Cursor, Codex, Gemini CLI, and more). It does not call models directly — your runtime does that.

Quick Start

The fastest path from zero to a built, verified phase:

# 1. Install GSD into your AI runtime (Claude Code shown)
npx get-shit-done-cc --claude --global

# 2. Open your AI agent in your project directory, then:
/gsd-new-project          # Answer questions, approve the roadmap
/clear                    # Start each major step with a clean context
/gsd-discuss-phase 1      # Lock in HOW phase 1 should be built
/gsd-plan-phase 1         # Research + atomic plans + plan-check
/gsd-execute-phase 1      # Parallel execution with atomic commits
/gsd-verify-work 1        # Walk through acceptance tests
/gsd-ship 1               # Open a PR from verified work

Tip

Run /clear (Claude Code) between major commands. GSD is designed around fresh contexts — every sub-agent already gets a clean window, and clearing the main session keeps your orchestration sharp.

Lost at any point? Run /gsd-progress — it reads all state and tells you exactly where you are and what to do next. Or run /gsd-progress --next to have GSD auto-advance to the correct step.

Installation

Requirements

Installing for your runtime

The installer writes GSD's commands, agents, hooks, and skills into your runtime's configuration directory and adapts file content per runtime automatically. Use --global (all projects) or --local (current project only).

Claude Code

npx get-shit-done-cc --claude --global

Cursor / Windsurf

npx get-shit-done-cc --cursor --global
npx get-shit-done-cc --windsurf --global

Codex

npx get-shit-done-cc --codex --global

Codex CLI minimum supported version: 0.130.0. Restart Codex after installing.

Gemini CLI

npx get-shit-done-cc --gemini --global

Gemini namespaces commands under gsd: — use the colon form (/gsd:new-project) instead of the hyphen form.

Other runtimes

# Pick your runtime flag:
--opencode  --kilo  --copilot  --antigravity  --augment
--trae  --qwen  --hermes  --codebuddy  --cline  --all

Note

Throughout the bundled documentation you will also see installs written as npx @opengsd/get-shit-done-redux --<runtime> --global. That is the package name used by the successor project. This repository's own package.json publishes the get-shit-done-cc bin, which is the form shown above. Both install the same system; pick whichever package your environment can resolve.

Slash-command spellings (hyphen vs colon vs $)

GSD ships the same commands to every runtime, but the invocation spelling differs:

The installer writes the correct form into each runtime's command directory — you don't choose. This guide uses the hyphen form; translate as needed for your runtime.

Installing for prerelease editions

Prerelease channels (Windsurf Next, Cursor Nightly, VS Code Insiders, etc.) read from a sibling config directory. Point the matching <RUNTIME>_CONFIG_DIR environment variable at it before installing:

WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx get-shit-done-cc --windsurf --global

Warning

Prerelease editions are best-effort and not separately tested in release CI. Installs work and paths resolve, but file an issue if anything other than the path mapping fails.

Updating

/gsd-update                # Check for updates, preview changelog, install
/gsd-update --sync         # Update and sync skills from the registry
/gsd-update --reapply      # Update and reapply your local modifications

Tip

Since v1.17 the installer backs up any locally modified GSD files to gsd-local-patches/. If an update overwrites your tweaks, run /gsd-update --reapply to merge them back.

Core Concepts

GSD organizes work into a small, consistent vocabulary. Understanding these terms makes every command obvious.

Project : The whole effort. Initialized by /gsd-new-project. Defined by PROJECT.md (vision), REQUIREMENTS.md (scoped requirements with IDs), and ROADMAP.md (the phase breakdown).

Milestone : A version cycle (e.g. v1.0, v2.0). A project completes a milestone, then optionally starts a new one with /gsd-new-milestone.

Phase : One unit of buildable work inside a milestone (e.g. "Phase 1 — Core middleware"). Phases are the heartbeat of GSD: you discuss, plan, execute, and verify them one at a time. Phases can be integers (1, 2, 3) or decimals for inserted urgent work (3.1).

Plan : An atomic, executable task file (XX-YY-PLAN.md) inside a phase. A phase typically has 2–3 plans. Each plan is small enough for a single agent to complete reliably in one context window.

The .planning/ directory : GSD's entire memory, stored as Markdown + JSON in your repo. It survives /clear, is inspectable by humans and agents, and can be committed for team visibility (or kept private — see Working on a private project).

Agents : Specialized sub-AIs GSD spawns for focused jobs — gsd-planner, gsd-executor, gsd-verifier, gsd-phase-researcher, and ~30 others. Each gets a fresh context window.

Workstream : An isolated .planning/ subtree that lets you work on multiple milestone areas concurrently without state collisions.

Note

Absent = enabled. GSD's workflow feature flags default to on when missing from config. You explicitly disable features you don't want; you never have to enable the defaults.

The Phase Workflow (End-to-End)

This is the canonical loop. Here it is applied to a small Node.js project — a webhook signature validator middleware for Express.

Step 1 — Create the project

/gsd-new-project

GSD asks about your idea, spawns parallel research agents, extracts requirements, and proposes a roadmap. Nothing is built until you approve the roadmap.

> What are you building?
  A webhook signature validator middleware for Express apps.

> Who's the user?
  Backend developers integrating third-party webhooks (Stripe, GitHub, Shopify).

[Research agents run in parallel...]
[Requirements extracted...]

Roadmap (1 phase):
  Phase 1 — Core middleware: HMAC-SHA256 signature validation,
            timing-safe compare, configurable tolerance window.

Approve? [y/n]

Creates: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json, research/, and a CLAUDE.md.

Step 2 — Discuss the phase

/gsd-discuss-phase 1

This is where you shape how GSD builds — not just what. GSD reads the phase goal and asks about your implementation preferences before any planning.

> How should invalid signatures be handled?
  Reject immediately with 401, log the raw header for debugging.

> Any library preferences for HMAC?
  Node built-in crypto only — no extra dependencies.

Creates: {phase}-CONTEXT.md (your locked-in decisions) and {phase}-DISCUSSION-LOG.md (audit trail).

Tip

Most plan-quality problems come from skipped discussion. If you ever think "the plan misunderstood me," the fix is almost always to run /gsd-discuss-phase first. Use --assumptions to have GSD read your codebase and show you what it intends to do, so you only correct what's wrong.

Step 3 — Plan the phase

/gsd-plan-phase 1

GSD spawns four parallel research agents (stack, features, architecture, pitfalls), synthesizes their findings, then a planner writes atomic task plans. A plan-checker verifies each plan achieves the phase goal before saving (looping up to 3 times if needed).

Creates: {phase}-RESEARCH.md, one or more {phase}-{N}-PLAN.md, and {phase}-VALIDATION.md (the test-coverage contract).

Wave 1 plan: 01-01-PLAN.md — Create validateSignature() core function
Wave 1 plan: 01-02-PLAN.md — Express middleware wrapper + error handling
[Plan checker] All plans achieve phase goal ✓

Step 4 — (Optional) Lock the UI design contract

For frontend phases, run this between discuss and plan:

/gsd-ui-phase 1

It generates a {phase}-UI-SPEC.md design contract (spacing, typography, color, copywriting, registry safety) so multiple components don't drift into five slightly different visual decisions.

Step 5 — Execute

/gsd-execute-phase 1

GSD groups plans into waves (parallel where independent, sequential where dependent), spawns a fresh executor per plan, and commits each task atomically.

Wave 1 (parallel):
  [Executor A] → 01-01-PLAN.md (core function)  ✓ committed
  [Executor B] → 01-02-PLAN.md (middleware)      ✓ committed

[Verifier] Checking codebase against phase goals...
  REQ-001 validateSignature() ✓   REQ-002 timing-safe compare ✓
  Status: PASS

Creates: per-plan {phase}-{N}-SUMMARY.md and {phase}-VERIFICATION.md; STATE.md is updated automatically.

Step 6 — Verify

/gsd-verify-work 1

GSD extracts testable deliverables from the phase goal and walks you through them one at a time. If something fails, it diagnoses the root cause and writes a fix plan.

[3/3] Does an invalid signature return 401 with { error: "invalid_signature" }?
> no — I'm getting a 500 instead

[Diagnosing...] Root cause: timingSafeEqual TypeError on different-length buffers.
Fix plan created: 01-03-PLAN.md. Run /gsd-execute-phase 1 to apply.

Creates: {phase}-UAT.md.

Step 7 — Ship

/gsd-ship 1            # Open a PR with an auto-generated body
/gsd-ship 1 --draft   # ...as a draft PR

The PR body always includes Summary, Changes, Requirements Addressed, Verification, and Key Decisions. (Requires the gh CLI, authenticated.)

Repeat, then close the milestone

/gsd-discuss-phase 2   # ...plan, execute, verify, ship phase 2, and so on
/gsd-progress --next   # Or let GSD auto-detect and run the next step

/gsd-audit-milestone     # Verify every requirement shipped
/gsd-complete-milestone  # Archive, tag the release

The full lifecycle at a glance

/gsd-new-project
      │
      ▼  (for each phase)
/gsd-discuss-phase → /gsd-ui-phase → /gsd-plan-phase
      → /gsd-execute-phase → /gsd-verify-work → /gsd-ship
      │
      ▼  (when all phases done)
/gsd-audit-milestone → /gsd-complete-milestone
      │
      ▼  (optional next cycle)
/gsd-new-milestone

Everyday Commands

These are the commands you'll reach for most often, grouped by what you're trying to do.

Knowing where you are

Pausing and resuming

Quick, ad-hoc work

Not every change deserves the full pipeline. GSD has two lighter lanes:

/gsd-fast "fix typo in README"        # Inline, no sub-agents, no planning — trivial edits
/gsd-quick                            # Ad-hoc task WITH GSD guarantees (plan + execute)
/gsd-quick --full                     # Quick task + the complete quality pipeline

Note

/gsd-fast is for typos, config tweaks, and forgotten commits. /gsd-quick is for anything that needs research, multi-step planning, or verification. When in doubt, use /gsd-quick.

Adjusting scope mid-flight

/gsd-phase "Add rate limiting"     # Append a new phase to the roadmap
/gsd-phase --insert 3 "Hotfix"     # Insert urgent work → creates phase 3.1
/gsd-phase --remove 7              # Descope phase 7 and renumber
/gsd-phase --edit 4                # Edit any field of phase 4 in place

Working Recipes

Brand-new greenfield project

/gsd-new-project
/clear
/gsd-discuss-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1

Starting from a PRD or design doc

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

Adding to an existing codebase (brownfield)

/gsd-map-codebase    # Parallel agents map stack, architecture, conventions, concerns
/gsd-new-project     # Questions now focus on what you're ADDING
# ...normal phase workflow from here

/gsd-map-codebase writes .planning/codebase/ analysis docs. For a faster, single-agent scan use /gsd-map-codebase --fast. To make your codebase queryable, enable the intel index (intel.enabled: true) and run /gsd-map-codebase --query refresh, then /gsd-map-codebase --query auth.

Importing an existing plan or migrating from GSD-2

/gsd-import --from /tmp/team-plan.md   # Ingest an external plan, with conflict detection
/gsd-import --from-gsd2                # Reverse-migrate a GSD-2 (.gsd/) project to v1 (.planning/)
/gsd-ingest-docs docs/                 # Bootstrap .planning/ from existing ADRs/PRDs/specs

Running everything autonomously

/gsd-autonomous              # Run all remaining phases end-to-end
/gsd-autonomous --from 3 --to 5   # Run only phases 3 through 5

Caution

Autonomous mode runs many phases without stopping. Pair it with the yolo preset only when your PROJECT.md and conventions are comprehensive enough that no discussion is needed (workflow.skip_discuss: true). Otherwise you may build a lot of the wrong thing before you notice.

Working on a private project

Keep planning artifacts out of git entirely:

1. Set planning.commit_docs: false (via /gsd-settings).
2. Add .planning/ to your .gitignore.
3. If already tracked: git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs".

GSD auto-detects a gitignored .planning/ and disables doc commits regardless of config, preventing git errors.

Quality Gates & Reviews

GSD bakes review into the loop rather than bolting it on at the end.

Code review

/gsd-code-review 3                 # Review all changed files in phase 3
/gsd-code-review 3 --depth=deep    # Cross-file review (import graphs, call chains)
/gsd-code-review 3 --fix           # Fix Critical + Warning findings atomically
/gsd-code-review 3 --fix --auto    # Fix and re-review until clean (max 3 iterations)

Findings are classified Critical / Warning / Info in {phase}-REVIEW.md. The reviewer slots in after execution, before UAT:

/gsd-execute-phase N → /gsd-code-review N → /gsd-code-review N --fix → /gsd-verify-work N

Autonomous audit-to-fix

/gsd-audit-fix                # Audit, classify, and fix medium+ issues (max 5)
/gsd-audit-fix --dry-run      # Preview the classification without fixing

Cross-AI peer review

Have a different AI critique your plans before you build:

/gsd-review --phase 2 --gemini       # One reviewer
/gsd-review --phase 2 --all          # Every detected reviewer (Gemini, Codex, Cursor, local servers…)
/gsd-plan-phase 2 --reviews          # Replan using the review feedback

Security and validation audits

/gsd-secure-phase 5          # Retroactively verify threat mitigations for phase 5
/gsd-validate-phase 2        # Fill automated-test-coverage (Nyquist) gaps
/gsd-add-tests 2             # Generate tests for a completed phase
/gsd-eval-review 3           # Audit an AI phase's evaluation coverage

Exploration: Spike, Sketch, Explore

Before committing a phase to one approach, de-risk it.

Spike — validate technical feasibility

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

Each spike runs 2–5 experiments. Every experiment has a Given/When/Then hypothesis, working code (not pseudocode), and a VALIDATED / INVALIDATED / PARTIAL verdict. Results land in .planning/spikes/.

Sketch — explore visual direction

/gsd-sketch "dashboard layout"
/gsd-sketch --text "onboarding flow"   # Text mode for non-Claude runtimes
/gsd-sketch --wrap-up

Each sketch answers one design question with 2–3 variants in a single browser-openable index.html — no build step. Results land in .planning/sketches/.

Explore — think it through first

/gsd-explore "caching strategy"

A Socratic ideation session that routes its output to the right artifact: a note, todo, seed, research question, requirements update, or a new phase.

Tip

The natural flow is spike → sketch → discuss → plan. Validate the approach, explore the design, then lock preferences and plan with confidence.

Capture, Backlog, Seeds & Threads

Ideas arrive at inconvenient times. GSD gives each kind a home.

Backlog items get full phase directories, so you can /gsd-discuss-phase 999.1 to explore one further. Review and promote with /gsd-review-backlog.

Seeds preserve the full why and when to surface — /gsd-new-milestone scans them and presents matches automatically.

Threads are lightweight cross-session knowledge stores (Goal, Context, References, Next Steps) for work that doesn't belong to any phase.

Multi-Stream & Multi-Repo Work

Workstreams — concurrent areas, one repo

/gsd-workstreams create backend-api   # Isolated .planning/ state
/gsd-workstreams switch backend-api   # Active context follows you
/gsd-workstreams list
/gsd-workstreams complete backend-api

Each workstream keeps its own .planning/ subtree so switching between "backend API" and "frontend dashboard" never clobbers progress. Active context is session-scoped, so one terminal can't repoint another's STATE.md.

Workspaces — separate repos or worktrees

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI   # Multi-repo workspace
/gsd-workspace --new --name feature-b --repos .                # Worktree of current repo
/gsd-workspace --list
/gsd-workspace --remove feature-b

Each workspace gets its own fully-independent .planning/, git worktrees (default) or clones, and a WORKSPACE.md manifest.

Note

Workstreams share one codebase and git history but isolate planning. Workspaces create separate worktrees/clones. Use workstreams for parallel concerns in one repo; use workspaces for parallel features needing real isolation.

Tuning Cost & Speed

GSD lets you trade thoroughness for speed and cost. Pick a preset, or tune individual levers.

Presets

Switch profiles fast:

/gsd-config --profile budget     # Cheapest models
/gsd-config --profile quality    # Best models
/gsd-config --profile inherit    # Use your current session model (OpenRouter/local providers)

Per-phase-type models

Apply "Opus for planning, Sonnet for the rest" without learning the agent taxonomy:

{
  "model_profile": "balanced",
  "models": {
    "planning": "opus",
    "research": "sonnet",
    "execution": "opus",
    "verification": "sonnet"
  }
}

The six slots are planning, discuss, research, execution, verification, completion, accepting opus / sonnet / haiku / inherit. Need a single exception? Add model_overrides (it wins over models).

The biggest lever GSD doesn't own: MCP servers

Every enabled MCP server injects its tool schema into every turn — browser/playwright tools can cost 20k+ tokens each. Before tuning model profiles, audit .claude/settings.json:

{
  "enabledMcpjsonServers": ["context7"],
  "disabledMcpjsonServers": ["playwright", "mac-tools"]
}

Tip

Trimming MCP servers compounds with model-profile tuning. Disable browser tools on a phase with no UI work, and platform-specific tools you aren't using right now.

Security You Get for Free

GSD generates Markdown that becomes LLM system prompts, so it treats all user-controlled text as a potential injection vector — and it guards your supply chain.

Prompt-injection defense

• gsd-prompt-guard.js scans .planning/ writes for injection patterns (role overrides, instruction bypasses, fake system tags). Always active; cannot be disabled.
• gsd-read-injection-scanner.js scans content read from untrusted sources for injected instructions.
• All user-supplied file paths (--prd, --text-file) are validated to resolve inside the project directory.

Package-legitimacy gate (anti-slopsquatting)

AI agents sometimes hallucinate package names; attackers pre-register those names with malicious install scripts. GSD runs slopcheck on every recommended package during research:

Packages discovered via WebSearch are always tagged [ASSUMED] and gated the same way. If slopcheck can't be installed, every package gets a human checkpoint — the safest fallback.

Important

If a package install fails during execution, GSD stops and asks rather than silently trying a similarly-named alternative — silent substitution is exactly how slopsquatting spreads.

Command Reference

The full roster is 67 slash commands. Below are the ones you'll use, grouped by purpose. Run /gsd-help for an on-screen tour, /gsd-help --full for every flag, or /gsd-help <topic> to jump to one section.

Core workflow

Milestones & phases

Navigation & sessions

Quality, debugging & docs

Utility & capture

Configuration

Note

The roster also includes six namespace meta-skills (/gsd-workflow, /gsd-project, /gsd-quality, /gsd-context, /gsd-manage, /gsd-ideate). You almost never type these — they're a routing layer that lets the model discover the right command cheaply. If you know the concrete command, call it directly.

Troubleshooting

GSD's troubleshooting format: the symptom, the cause, and the exact fix.

Error: Project already exists (.planning/PROJECT.md found)

Cause: /gsd-new-project found an existing .planning/PROJECT.md — a safety check. Solution: Start over by deleting the .planning/ directory first, or work in a fresh directory. Prevention: Run /gsd-new-project only in a clean project root.

Error: Permission to use Bash has been denied

Cause: Claude Code's default settings only allow read-only git commands, but executors need to commit and run build tools. Solution: Add the patterns your stack needs to ~/.claude/settings.json (or .claude/settings.local.json for one project). All stacks need the git + gh block:

"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:*)"
  ]
}

Then add your stack's tools, e.g. Node: "Bash(npm:*)", "Bash(npx:*)", "Bash(node:*)"; Python: "Bash(uv:*)", "Bash(pytest:*)", "Bash(ruff:*)"; Rails: "Bash(bin/rails:*)", "Bash(bundle:*)"; Rust: "Bash(cargo:*)". Prevention: When blocked mid-phase, the executor prints the exact pattern you need — add it and re-run /gsd-execute-phase.

STATE.md is out of sync

Cause: STATE.md drifted from the actual filesystem. Solution:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate       # Detect drift
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify  # Preview the fix
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync           # Reconstruct from disk

Plans seem wrong or misaligned

Cause: The planner made assumptions a discussion would have prevented. Solution: Run /gsd-discuss-phase [N] (or /gsd-discuss-phase --assumptions [N] to preview intent), then re-plan. Prevention: Always discuss before planning a non-trivial phase.

Quality drops during a long session

Cause: Context degradation in the main session. Solution: /clear between major commands, then /gsd-resume-work or /gsd-progress to restore state. Sub-agents already get fresh windows; the main session benefits from the same hygiene.

Execution produces stubs or fails

Cause: Plans too ambitious — tasks exceeding a single context window. Solution: Keep plans to 2–3 tasks. Re-plan with smaller scope.

Parallel execution causes build-lock errors

Cause: Multiple agents triggering build tools simultaneously (e.g. cargo lock contention). Solution: GSD handles this since v1.26 (--no-verify commits, hooks run once per wave). On older versions, update — or disable parallelism via /gsd-settings → parallelization.enabled: false.

A sub-agent "failed" but the work is there

Cause: A known Claude Code classification quirk. Solution: Check git log — the commits may have succeeded. GSD's orchestrators spot-check output before reporting failure.

Windows: installer crashes with EPERM ... scandir

Cause: OS-protected directories (e.g. browser profiles). Solution: Fixed since v1.24 — update. Workaround: temporarily rename the offending directory before installing.

A workflow is corrupted in a non-obvious way

Solution: Run /gsd-forensics — it checks git anomalies, artifact integrity, and state inconsistencies, and writes a diagnostic report to .planning/forensics/.

Other SDK / CLI errors you may see

Recovery Quick Reference

FAQ

Q: Do I need an API key or a special model? No. GSD runs inside your existing AI coding agent and uses whatever model your runtime provides. The optional search-API keys (brave_search, firecrawl, exa_search) only enhance research and are auto-detected.

Q: Which AI tools does GSD support? Fifteen runtimes: Claude Code, OpenCode, Kilo, Gemini CLI, Codex, GitHub Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, Hermes, CodeBuddy, and Cline.

Q: Where does GSD store everything? In a .planning/ directory in your repo — all human-readable Markdown and JSON. No database, no server, no external service.

Q: Can my team see the planning artifacts? Yes — commit .planning/ to git (the default). Or keep it private with planning.commit_docs: false and a .gitignore entry.

Q: What's the difference between /gsd-fast and /gsd-quick? /gsd-fast does a trivial change inline with no planning. /gsd-quick runs a real (but lightweight) plan-execute cycle for anything needing research, multiple steps, or verification.

Q: Do I have to run every command in order? No. Run /gsd-progress --next and GSD figures out the correct next step from your project state. The manual order just makes the pipeline explicit.

Q: How do I keep token costs down? Switch to the budget profile, disable research/plan-check when the domain is familiar, set per-phase-type models, and — biggest of all — disable MCP servers you aren't using in .claude/settings.json.

Q: My runtime uses a different model provider (OpenRouter, local). Will GSD still work? Yes. Use /gsd-config --profile inherit so all agents use your current session model instead of specific Anthropic model IDs. Non-Claude runtimes are auto-configured with resolve_model_ids: "omit".

Q: Is this repository still maintained? No — it's archived. Development continues as GSD Core at github.com/open-gsd/gsd-core. This guide documents the archived snapshot faithfully; for current features, follow the successor project.

Q: Where can I see the full architecture and configuration internals? See the companion Admin Guide, which covers the orchestration model, the full config.json schema, the installer, hooks, and security internals.