# 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`](https://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](#what-gsd-does)
2. [Quick Start](#quick-start)
3. [Installation](#installation)
4. [Core Concepts](#core-concepts)
5. [The Phase Workflow (End-to-End)](#the-phase-workflow-end-to-end)
6. [Everyday Commands](#everyday-commands)
7. [Working Recipes](#working-recipes)
8. [Quality Gates & Reviews](#quality-gates--reviews)
9. [Exploration: Spike, Sketch, Explore](#exploration-spike-sketch-explore)
10. [Capture, Backlog, Seeds & Threads](#capture-backlog-seeds--threads)
11. [Multi-Stream & Multi-Repo Work](#multi-stream--multi-repo-work)
12. [Tuning Cost & Speed](#tuning-cost--speed)
13. [Security You Get for Free](#security-you-get-for-free)
14. [Command Reference](#command-reference)
15. [Troubleshooting](#troubleshooting)
16. [Recovery Quick Reference](#recovery-quick-reference)
17. [FAQ](#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:

```bash
# 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

| Requirement | Detail |
|-------------|--------|
| **Node.js** | `>= 22.0.0` (declared in `package.json` `engines`) |
| **An AI coding runtime** | Claude Code, OpenCode, Kilo, Gemini CLI, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, Hermes, CodeBuddy, or Cline |
| **`gh` CLI** (optional) | Required only for `/gsd-ship` (PR creation), authenticated |
| **`slopcheck`** (optional) | Python tool auto-installed at research time for the package-legitimacy gate |

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

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

=== "Cursor / Windsurf"

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

=== "Codex"

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

    > Codex CLI minimum supported version: **`0.130.0`**. Restart Codex after installing.

=== "Gemini CLI"

    ```bash
    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"

    ```bash
    # 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:

| Runtimes | Spelling | Example |
|----------|----------|---------|
| Claude Code, Copilot, OpenCode, Kilo, Cursor, Windsurf, Augment, Antigravity, Trae | Hyphen form | `/gsd-plan-phase 1` |
| Gemini CLI | Colon form (namespaced) | `/gsd:plan-phase 1` |
| Codex | `$` prefix (skills) | `$gsd-plan-phase 1` |

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:

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

```bash
/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](#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

```bash
/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.**

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

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

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

```bash
/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).

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

```bash
/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

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

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

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

```text
[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

```bash
/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

```bash
/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

```text
/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

| Command | What it does |
|---------|--------------|
| `/gsd-progress` | "Where am I? What's next?" — reads all state and auto-routes |
| `/gsd-progress --next` | Advance to the next logical step automatically |
| `/gsd-progress --do "fix the auth bug"` | Dispatch freeform intent to the best GSD command |
| `/gsd-resume-work` | Full context restoration after a `/clear` or new session |
| `/gsd-stats` | Project metrics dashboard |
| `/gsd-manager` | Interactive command center for driving multiple phases from one terminal |

### Pausing and resuming

| Command | What it does |
|---------|--------------|
| `/gsd-pause-work` | Save a context handoff when stopping mid-phase |
| `/gsd-pause-work --report` | ...plus a stakeholder-ready session summary in `.planning/reports/` |
| `/gsd-resume-work` | Restore everything from the last session |

### Quick, ad-hoc work

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

```bash
/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

```bash
/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

```bash
/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

```bash
/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)

```bash
/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

```bash
/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

```bash
/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

```bash
/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**:

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

### Autonomous audit-to-fix

```bash
/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:

```bash
/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

```bash
/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

```bash
/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

```bash
/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

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

| You have… | Command | Where it goes |
|-----------|---------|---------------|
| A task for later | `/gsd-capture "Add dark mode"` | `.planning/todos/pending/` |
| A quick note | `/gsd-capture --note "Caching idea"` | Note files |
| An idea not ready to plan | `/gsd-capture --backlog "GraphQL layer"` | Backlog (999.x numbering) |
| A future idea with a trigger | `/gsd-capture --seed "Realtime collab when WS infra lands"` | `.planning/seeds/` |
| Cross-session investigation | `/gsd-thread "Investigate TCP timeout"` | `.planning/threads/` |

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

```bash
/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

```bash
/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

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

Switch profiles fast:

```bash
/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:

```json
{
  "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`:

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

| Verdict | Meaning | GSD action |
|---------|---------|------------|
| `[OK]` | Passes all checks | Proceeds — no checkpoint |
| `[SUS]` | Suspicious (new, low downloads, no source repo) | Flagged; a human-verify checkpoint is added before install |
| `[SLOP]` | High-confidence hallucination / attacker-registered | **Removed** from research entirely — never reaches the planner |

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

| Command | Purpose | Key flags |
|---------|---------|-----------|
| `/gsd-new-project` | Initialize a project | `--auto @file.md` |
| `/gsd-discuss-phase [N]` | Gather phase preferences | `--all`, `--auto`, `--assumptions`, `--analyze`, `--power`, `--batch` |
| `/gsd-ui-phase [N]` | UI design contract | — |
| `/gsd-plan-phase [N]` | Research + plan + verify | `--skip-research`, `--research-phase N`, `--gaps`, `--reviews`, `--bounce`, `--prd`, `--ingest` |
| `/gsd-execute-phase N` | Wave-based execution | `--wave N`, `--validate`, `--cross-ai` |
| `/gsd-verify-work [N]` | UAT with auto-diagnosis | — |
| `/gsd-ship [N]` | Open a PR | `--draft` |
| `/gsd-ui-review [N]` | 6-pillar visual audit | — |

### Milestones & phases

| Command | Purpose |
|---------|---------|
| `/gsd-audit-milestone` | Verify the milestone's definition of done |
| `/gsd-complete-milestone` | Archive + tag the release |
| `/gsd-new-milestone [name]` | Start the next version cycle (`--reset-phase-numbers`) |
| `/gsd-milestone-summary [version]` | Comprehensive onboarding summary |
| `/gsd-phase` | Add / `--insert` / `--remove` / `--edit` phases |
| `/gsd-validate-phase [N]` | Fill Nyquist test-coverage gaps |

### Navigation & sessions

| Command | Purpose |
|---------|---------|
| `/gsd-progress` | Status + next step (`--next`, `--do`, `--forensic`) |
| `/gsd-resume-work` | Restore context |
| `/gsd-pause-work` | Save handoff (`--report`) |
| `/gsd-manager` | Multi-phase command center |
| `/gsd-help` | Command help (`--brief`, `--full`, `<topic>`) |

### Quality, debugging & docs

| Command | Purpose |
|---------|---------|
| `/gsd-code-review N` | Review changed files (`--depth=`, `--fix`, `--files`) |
| `/gsd-audit-fix` | Autonomous audit-to-fix (`--dry-run`, `--severity`, `--max`) |
| `/gsd-review --phase N` | Cross-AI plan review (per-CLI flags, `--all`) |
| `/gsd-debug [desc]` | Persistent debug session (`--diagnose`, `list`, `continue`) |
| `/gsd-secure-phase [N]` | Threat-mitigation audit |
| `/gsd-forensics [desc]` | Post-mortem for failed workflows |
| `/gsd-docs-update` | Generate/verify project docs (`--force`, `--verify-only`) |
| `/gsd-extract-learnings N` | Extract reusable patterns (`--all`) |

### Utility & capture

| Command | Purpose |
|---------|---------|
| `/gsd-quick` | Ad-hoc task with guarantees (`--full`, `--validate`, `--discuss`, `--research`) |
| `/gsd-fast "task"` | Trivial inline change |
| `/gsd-explore [topic]` | Socratic ideation |
| `/gsd-spike [idea]` | Feasibility experiments (`--quick`, `--wrap-up`) |
| `/gsd-sketch [idea]` | HTML design mockups (`--quick`, `--text`, `--wrap-up`) |
| `/gsd-capture` | Todos/notes/backlog/seeds (`--note`, `--backlog`, `--seed`, `--list`) |
| `/gsd-thread` | Persistent context threads |
| `/gsd-undo` | Safe git revert of GSD commits (`--last`, `--phase`, `--plan`) |
| `/gsd-cleanup` | Archive old phase directories |
| `/gsd-health` | Check `.planning/` integrity (`--repair`, `--context`) |

### Configuration

| Command | Purpose |
|---------|---------|
| `/gsd-settings` | Interactive workflow toggles + model profile |
| `/gsd-config` | Config (`--advanced`, `--integrations`, `--profile`) |
| `/gsd-surface` | Toggle which skills are surfaced (`list`, `profile`, `disable`, `enable`, `reset`) |
| `/gsd-update` | Update GSD (`--sync`, `--reapply`) |
| `/gsd-map-codebase` | Brownfield mapping (`--fast`, `--query`, `--focus`) |
| `/gsd-graphify` | Knowledge graph (`build`, `query`, `status`, `diff`) |
| `/gsd-workstreams`, `/gsd-workspace` | Parallel work management |

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

```json
"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:**

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

| Error message | Meaning |
|---------------|---------|
| `Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots` | Bad `/gsd-workstreams` name |
| `Failed to parse config at <path>` / `Config ... must be a JSON object` | `.planning/config.json` is malformed — fix the JSON |
| `gsd-tools timed out after <ms>` | A CLI subcommand exceeded its timeout — re-run or raise `workflow.subagent_timeout` |
| `Cannot read input file` | A `--prd` / `--ingest` path doesn't resolve — check the path |

---

## Recovery Quick Reference

| Problem | Solution |
|---------|----------|
| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
| Phase went wrong | `git revert` the phase commits (or `/gsd-undo --phase NN`), then re-plan |
| Need to change scope | `/gsd-phase` / `--insert` / `--remove` |
| Something broke | `/gsd-debug "description"` (add `--diagnose`) |
| STATE.md out of sync | `state validate` then `state sync` |
| Workflow seems corrupted | `/gsd-forensics` |
| Quick targeted fix | `/gsd-quick` |
| Plan doesn't match vision | `/gsd-discuss-phase [N]` then re-plan |
| Costs running high | `/gsd-config --profile budget`, toggle agents off |
| Update broke local changes | `/gsd-update --reapply` |
| Don't know what's next | `/gsd-progress --next` |

---

## 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`](https://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.

---

_Generated June 2026 from gsd-build/get-shit-done at bdcaab2. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._