Get Shit Done — AI orchestration for Claude Code
GSD-Lite is an AI orchestration tool for Claude Code. It combines structured project management with built-in quality discipline: TDD enforcement, anti-rationalization guards, multi-level code review, and automatic failure recovery — all driven by a state machine that keeps multi-phase projects on track.
Discuss thoroughly, execute automatically. Have as many rounds of requirement discussion as needed. Once the plan is approved, GSD-Lite auto-executes: coding, self-review, independent review, verification, and phase advancement — with minimal human intervention.
- Phase-based project management — Break work into phases with ordered tasks, dependency tracking, and handoff gates
- State machine orchestration — 11 workflow modes with precise state transitions, persistent to
state.json - Automatic task scheduling — Gate-aware dependency resolution determines what runs next
- Session resilience — Stop anytime, resume exactly where you left off — even across Claude Code restarts
- TDD enforcement — "No production code without a failing test first" baked into every executor dispatch
- Anti-rationalization guards — Red-flag checklists inline in every agent prompt, blocking common excuses to skip process
- Multi-level code review — L0 self-review / L1 phase-batch review / L2 immediate independent review
- Contract change propagation — When an API contract changes, downstream tasks automatically invalidate
- 3-strike retry with debugger escalation — Failed tasks retry up to 3 times, then auto-dispatch a debugger agent
- Systematic root cause analysis — Debugger tests hypotheses, finds root cause, feeds fix guidance back to executor
- Blocked task handling — Blocked tasks are parked; execution continues with remaining tasks
- Rework propagation — Critical review issues cascade invalidation to dependent tasks
- Subagent isolation — Each task runs in its own agent context, preventing cross-contamination
- StatusLine monitoring — Real-time context health tracking via Claude Code StatusLine
- Evidence-based verification — Every claim backed by command output, not assertions
- Research with TTL — Research artifacts include volatility ratings and expiration dates
User → discuss + research (confirm requirements) → approve plan → auto-execute
↑ ↑ ↑
Interaction 1 Interaction 2 Autonomous execution
(code→review→verify→advance)
| Command | Purpose |
|---|---|
/gsd:start |
Interactive start — discuss requirements, research, plan, then auto-execute |
/gsd:prd <input> |
Start from a requirements doc or description text |
/gsd:resume |
Resume execution from saved state |
/gsd:status |
View project progress dashboard |
/gsd:stop |
Save state and pause execution |
| Agent | Role | Built-in Discipline |
|---|---|---|
| executor | Execute a single task (TDD + self-review + checkpoint) | Iron Law + Red Flags + Deviation Rules |
| reviewer | Two-stage review (spec check → quality check) | Independent verification + Hard Gates |
| researcher | Ecosystem research (Context7 → official docs → web) | Confidence scoring + TTL |
| debugger | 4-phase systematic root cause analysis | Root Cause Iron Law |
| Tool | Purpose |
|---|---|
health |
Server status and state existence check |
state-init |
Initialize .gsd/ directory with project structure |
state-read |
Read state with optional field filtering |
state-update |
Update canonical fields with lifecycle validation |
phase-complete |
Complete a phase after verifying handoff gates |
orchestrator-resume |
Resume orchestration from current state |
orchestrator-handle-executor-result |
Process executor output, advance lifecycle |
orchestrator-handle-reviewer-result |
Process review, trigger accept/rework |
orchestrator-handle-researcher-result |
Store research artifacts and decisions |
orchestrator-handle-debugger-result |
Process root cause analysis, re-dispatch executor |
# Step 1: Add the marketplace
/plugin marketplace add sdsrss/gsd-lite
# Step 2: Install the plugin
/plugin install gsdAutomatically registers all commands, agents, workflows, MCP server, and hooks. Run these commands inside a Claude Code session.
npx gsd-lite installgit clone https://github.com/sdsrss/gsd-lite.git
cd gsd-lite && npm install && node cli.js installMethods 2 & 3 write components to ~/.claude/ and register the MCP server in settings.json.
Uninstall: node cli.js uninstall or npx gsd-lite uninstall
# Plugin
/plugin update gsd
# npx
npx gsd-lite install
# Manual
git pull && npm install && node cli.js install- Installer is idempotent — no need to uninstall first
- Upgrades from older versions auto-clean legacy files
- Restart Claude Code after updating to load new MCP server / hooks
/gsd:startGSD-Lite will:
- Analyze your codebase (tech stack, conventions, structure)
- Ask what you want to build
- Research the ecosystem (libraries, patterns, pitfalls)
- Present a phased plan for your approval
- Auto-execute all phases once approved
# From a requirements document
/gsd:prd docs/requirements.md
# From a description
/gsd:prd "Build a REST API with JWT auth, rate limiting, and PostgreSQL"/gsd:resumeValidates workspace consistency (git HEAD, file integrity), then resumes from the exact task and workflow mode where execution stopped.
/gsd:statusShows phase completion, task lifecycle states, review status, and blockers — all derived from canonical state fields in real-time.
1. orchestrator-resume → determines next action
2. dispatch executor → runs task with TDD discipline
3. executor checkpoints → saves work + evidence
4. dispatch reviewer → independent spec + quality review
5. reviewer accepts → task done, schedule next
reviewer rejects → rework with specific feedback
6. all tasks done → phase handoff gate check
7. gate passes → advance to next phase
8. all phases done → project complete
executor fails (attempt 1) → retry with context
executor fails (attempt 2) → retry with accumulated context
executor fails (attempt 3) → dispatch debugger
debugger analyzes → root cause + fix direction
executor retries → with debugger guidance injected
All state lives in .gsd/state.json — a single source of truth with:
- Canonical fields (whitelist-controlled, schema-validated)
- Lifecycle state machine (pending → running → checkpointed → accepted)
- Evidence references (command outputs, test results)
- Research artifacts and decision index
| Dimension | GSD | GSD-Lite |
|---|---|---|
| Commands | 32 | 5 |
| Agents | 12 | 4 |
| Source files | 100+ | ~35 |
| Installer | 2465 lines | ~80 lines |
| User interactions | 6+ confirmations | Typically 2 |
| TDD / Anti-rationalization | No | Yes |
| State machine recovery | Partial | Full (11 modes) |
| Evidence-based verification | No | Yes |
gsd-lite/
├── src/ # MCP Server + tools (~3300 lines)
│ ├── server.js # MCP Server entry (10 tools)
│ ├── schema.js # State schema + lifecycle validation
│ ├── utils.js # Shared utilities (atomic writes, git)
│ └── tools/
│ ├── state.js # State CRUD + evidence + propagation
│ ├── orchestrator.js # Orchestration logic + agent handlers
│ └── verify.js # lint/typecheck/test verification
├── commands/ # 5 slash commands
├── agents/ # 4 subagent prompts
├── workflows/ # 5 core workflows (TDD, review, debug, research, deviation)
├── references/ # 8 reference docs (execution loop, state diagram, evidence spec, ...)
├── hooks/ # Context monitoring (StatusLine + PostToolUse)
├── tests/ # 674 tests (unit + simulation + E2E)
├── cli.js # Install/uninstall CLI entry
├── install.js # Installation script
└── uninstall.js # Uninstall script
npm test # Run all 674 tests
npm run test:coverage # Tests + coverage report (94%+ lines, 81%+ branches)
npm run lint # Biome lint
node --test tests/file.js # Run a single test file- Design Document v3.5 — Full architecture and protocol spec
- Engineering Tasks — 38 implementation tasks (5 phases, all complete)
- Calibration Notes — Context threshold and TTL calibration
MIT