What it does
GSD is a context engineering layer for Claude Code (and a dozen other AI coding runtimes). It structures work into phases with explicit plans, spawns isolated subagents per task to keep context windows clean, and runs quality gates between steps. The pitch: describe what you want, let the system decompose it, and let Claude build it without drifting off-track as the conversation grows.
Why I starred it
Context rot is real. Past the 50k-token mark in a Claude Code session, you start getting hallucinated file paths, forgotten constraints, and repeated mistakes. Every serious Claude Code user hits this wall. GSD attacks it structurally — instead of one long session doing everything, it breaks work into phased plans, each executed by a fresh subagent with just the context it needs. The repo had ~48k stars when I found it, so clearly others have the same problem.
What made me stop and look closer: the system is almost entirely markdown. No complex runtime, no database, no daemon. Just structured .md files that Claude reads as instructions, plus a thin Node.js CLI (get-shit-done/bin/gsd-tools.cjs) that handles state management and file operations.
How it works
The architecture splits into three layers: workflows (orchestration), agents (execution), and a shared state machine.
Workflows live in get-shit-done/workflows/ — around 50 markdown files, each defining a single operation like execute-phase.md or plan-phase.md. These are essentially prompt templates with XML-structured steps. The execute-phase workflow is the most interesting. It parses plan dependencies, groups tasks into waves, and spawns subagents in parallel:
<step name="initialize" priority="first">
Load all context in one call:
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE_ARG}")
The orchestrator stays lean — it coordinates, never touches code directly. Each plan gets its own gsd-executor subagent with a fresh context window.
Agents in agents/ are markdown files with YAML frontmatter that declare tool access and behavioral constraints. The executor agent (agents/gsd-executor.md) enforces atomic commits per task, deviation handling, and mandatory SUMMARY.md generation. It even reads your project's CLAUDE.md and treats it as a hard constraint — if a plan task contradicts a project rule, the project rule wins.
State management runs through get-shit-done/bin/lib/state.cjs. The STATE.md file tracks current phase, blockers, and decisions. The state module parses both **Field:** bold and plain Field: formats, which tells you this evolved organically rather than being designed upfront:
function stateExtractField(content, fieldName) {
const escaped = escapeRegex(fieldName);
const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.+)`, 'i');
const boldMatch = content.match(boldPattern);
if (boldMatch) return boldMatch[1].trim();
const plainPattern = new RegExp(`^${escaped}:\\s*(.+)`, 'im');
const plainMatch = content.match(plainPattern);
return plainMatch ? plainMatch[1].trim() : null;
}The gate system (get-shit-done/references/gates.md) defines four canonical gate types: pre-flight (block before starting), revision (loop back with feedback, max 3 iterations), escalation (pause for human decision), and abort (stop to prevent damage). Every validation checkpoint in the system maps to one of these. The plan-checker agent runs revision gates on generated plans, looping up to three times before escalating to the developer. Stall detection kicks in if issue count doesn't decrease between iterations.
The core.cjs library (~120 lines I read) handles project root detection with a findProjectRoot() function that walks up the directory tree looking for .planning/ directories. It handles multi-repo workspaces by checking if a parent's config.json lists the current directory as a sub-repo. The logic is careful — it won't walk above $HOME and short-circuits if the current directory already owns a .planning/ folder.
Using it
npx get-shit-done-cc@latestThe installer prompts for runtime (Claude Code, Gemini CLI, Codex, Copilot, Cursor, Windsurf, and more) and location (global or local). It copies markdown files into the appropriate config directory — for Claude Code, that's ~/.claude/commands/gsd/ or the newer skills/gsd-*/SKILL.md format.
Once installed, the workflow starts with /gsd-new-project to scaffold a .planning/ directory, then /gsd-discuss-phase to gather context, /gsd-plan-phase to generate plans, and /gsd-execute-phase to run them. The /gsd-next command auto-routes to whatever the logical next step is.
Non-interactive installs work too, useful for Docker and CI:
npx get-shit-done-cc --claude --global # Claude Code, global
npx get-shit-done-cc --all --global # Every supported runtimeRough edges
The test suite is solid — 90+ test files in tests/ using Vitest, covering everything from frontmatter parsing to worktree merge protection. The 70% line coverage requirement in package.json is enforced via c8. That's better than most projects in this space.
The dependency footprint is minimal: just vitest, esbuild, and c8 as devDependencies. No runtime dependencies at all — the core is plain Node.js with fs, path, and child_process.
Where it gets rough: the system generates a lot of files. A single project accumulates STATE.md, ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, per-phase directories with PLAN.md and SUMMARY.md files, plus config.json. If you're already managing a complex project structure, the .planning/ directory adds cognitive overhead. There's a /gsd-cleanup command, but you'll need it.
The README leans heavy on marketing energy ("Trusted by engineers at Amazon, Google, Shopify, and Webflow") and links a $GSD Solana token on Dexscreener. That's... a choice. The engineering is legit, but the crypto angle will make some people close the tab before they get to the code.
The 12-runtime support matrix (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline) is impressive but means the installer in bin/install.js is a 100+ line runtime detection maze. Each runtime has different tool name mappings — the claudeToCopilotTools object maps Read to read, Write to edit, Bash to execute, and so on. Maintaining parity across all these targets is a long-term burden.
Bottom line
If you're using Claude Code for anything beyond quick one-off scripts and you've hit the context degradation wall, GSD is the most structured answer I've seen. The gate taxonomy alone is worth reading. Solo developers building complex projects will get the most out of it — teams with existing project management tooling probably won't need the overhead.