gsd-lite

GSD-Lite

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 12-state workflow 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.

Features

Structured Execution Engine

• Phase-based project management — Break work into phases with ordered tasks, dependency tracking, and handoff gates
• 12-state workflow machine — planning → executing_task → reviewing_task → reviewing_phase → completed with precise 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 — crash protection via Stop hook auto-saves state markers

Quality Discipline (Built-in, Not Optional)

• 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 / phase review retry limit
• Contract change propagation — When an API contract changes, downstream tasks automatically invalidate

Intelligent Failure Recovery

• 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

Adaptive Review & Parallel Execution

• Confidence-based review adjustment — Executor self-assesses confidence (high/medium/low); orchestrator auto-adjusts review level with evidence cross-validation
• Impact analysis before review — Reviewer runs impact analysis on multi-file changes to catch missed downstream effects
• Parallel task scheduling — Independent tasks within the same phase are identified for concurrent dispatch
• Auto PR suggestion — Phase/project completion prompts PR creation with evidence summary

Context Protection & Monitoring

• Subagent isolation — Each task runs in its own agent context, preventing cross-contamination
• Real-time context health monitoring — StatusLine tracks context usage and project phase; composite StatusLine support coexists with other plugins
• Session lifecycle hooks — Stop hook writes crash marker; SessionStart injects project status into CLAUDE.md; resume detects non-graceful exits
• Evidence-based verification — Every claim backed by command output, not assertions
• Research with TTL — Research artifacts include volatility ratings and expiration dates

Auto-Update & Version Management

• Automatic update checks — Checks GitHub Releases every 24 hours with rate-limit backoff
• Version drift detection — Server startup compares running version against disk and plugin registry, warns on mismatch
• Smart cache management — Keeps latest 3 cached versions, auto-prunes old entries
• Idempotent installer — Reinstall anytime without uninstalling; legacy files auto-cleaned

Architecture

User → discuss + research (confirm requirements) → approve plan → auto-execute
        ↑                      ↑                        ↑
     Interaction 1          Interaction 2          Autonomous execution
                                              (code→review→verify→advance)

6 Commands

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 with workspace validation
/gsd:status	View project progress dashboard (derived from canonical state fields)
/gsd:stop	Save state and pause execution
/gsd:doctor	Diagnostic checks on GSD-Lite installation and project health

4 Agents

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

6 Workflows

Workflow	Purpose
tdd-cycle	RED-GREEN-REFACTOR TDD cycle enforcement
review-cycle	Two-level review gates and accept/rework decisions
debugging	4-phase root cause analysis process
research	Research with confidence scoring and TTL expiration
deviation-rules	Anti-rationalization guards and red-flag checklists
execution-flow	Complete task execution cycle from dispatch to checkpoint

MCP Server (11 Tools)

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
state-patch	Incrementally modify plan (add/remove/reorder tasks, update fields, add dependencies)
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

8 References

Reference	Content
execution-loop	9-step execution loop specification (single source of truth)
review-classification	Review level classification decision tree (L0/L1/L2)
evidence-spec	Evidence validation and citation rules
state-diagram	12-state lifecycle workflow machine diagram
testing-patterns	Test structure and patterns
anti-rationalization-full	Full red-flag checklist for agents
git-worktrees	Git worktree isolation strategy
questioning	Requirements clarification patterns

Installation

Method 1: Claude Code Plugin (Recommended)

# Step 1: Add the marketplace
/plugin marketplace add sdsrss/gsd-lite

# Step 2: Install the plugin
/plugin install gsd

Automatically registers all commands, agents, workflows, MCP server, hooks, and auto-update. Run these commands inside a Claude Code session.

Method 2: npx

npx gsd-lite install

Method 3: Manual

git clone https://github.com/sdsrss/gsd-lite.git
cd gsd-lite && npm install && node cli.js install

Methods 2 & 3 write components to ~/.claude/ and register the MCP server in settings.json.

The installer copies commands, agents, workflows, references, and hooks to ~/.claude/, and sets up the MCP server runtime in ~/.claude/gsd/.

Uninstall: node cli.js uninstall or npx gsd-lite uninstall

Upgrade

# Plugin (auto-update checks GitHub Releases every 24h)
/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
• Smart cache management keeps latest 3 versions, prunes old entries
• Restart Claude Code after updating to load new MCP server / hooks

Quick Start

Interactive Start

/gsd:start

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

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

Resume After Interruption

/gsd:resume

Validates workspace consistency (git HEAD, file integrity), then resumes from the exact task and workflow mode where execution stopped.

Monitor Progress

/gsd:status

Shows phase completion, task lifecycle states, review status, and blockers — all derived from canonical state fields in real-time.

How It Works

Execution Loop

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

Failure Recovery

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

State Persistence

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)
• Optimistic concurrency control (_version field with VERSION_CONFLICT detection)
• Evidence references (command outputs, test results)
• Research artifacts and decision index
• Incremental validation (simple field updates use fast path; phases use full validation)

Comparison with GSD

Dimension	GSD	GSD-Lite
Commands	32	6
Agents	12	4
Source files	100+	~15
Installer	2465 lines	~290 lines
User interactions	6+ confirmations	Typically 2
TDD / Anti-rationalization	No	Yes
State machine recovery	Partial	Full (12 modes)
Evidence-based verification	No	Yes
Auto-update	No	Yes
Context health monitoring	No	Yes

Project Structure

gsd-lite/
├── src/                    # MCP Server + tools (15 source files)
│   ├── server.js           # MCP Server entry (11 tools + version drift detection)
│   ├── schema.js           # State schema + lifecycle validation + incremental validation
│   ├── utils.js            # Shared utilities (atomic writes, git, file lock)
│   └── tools/
│       ├── state/          # State management (modular)
│       │   ├── constants.js  # Error codes, lock infrastructure
│       │   ├── crud.js       # CRUD operations + plan patching
│       │   ├── logic.js      # Task scheduling, propagation, research
│       │   └── index.js      # Re-exports
│       ├── orchestrator/   # Orchestration logic (modular)
│       │   ├── helpers.js    # Shared constants, preflight, dispatch
│       │   ├── resume.js     # Workflow resume state machine (12 modes)
│       │   ├── executor.js   # Executor result handler
│       │   ├── reviewer.js   # Reviewer result handler
│       │   ├── debugger.js   # Debugger result handler
│       │   ├── researcher.js # Researcher result handler
│       │   └── index.js      # Re-exports
│       └── verify.js       # lint/typecheck/test verification
├── commands/               # 6 slash commands (start, prd, resume, status, stop, doctor)
├── agents/                 # 4 subagent prompts (executor, reviewer, researcher, debugger)
├── workflows/              # 6 core workflows (TDD, review, debug, research, deviation, execution-flow)
├── references/             # 8 reference docs (execution-loop, state-diagram, evidence-spec, etc.)
├── hooks/                  # Session lifecycle hooks
│   ├── gsd-auto-update.cjs   # Auto-update from GitHub Releases (24h check interval)
│   ├── gsd-context-monitor.cjs # Real-time context health monitoring
│   ├── gsd-session-init.cjs   # Session initialization + CLAUDE.md status injection
│   ├── gsd-session-stop.cjs   # Graceful shutdown with crash markers
│   ├── gsd-statusline.cjs     # StatusLine display (composite-aware)
│   └── lib/                   # Shared hook utilities (gsd-finder, composite statusline, semver)
├── tests/                  # 972 tests (unit + simulation + E2E integration)
├── cli.js                  # Install/uninstall CLI entry
├── install.js              # Installation script (plugin-aware, idempotent)
└── uninstall.js            # Uninstall script

Testing

npm test                    # Run all 972 tests
npm run test:coverage       # Tests + coverage report (94%+ lines, 83%+ branches)
npm run lint                # Biome lint
node --test tests/file.js   # Run a single test file

Documentation

• 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

Requirements

• Node.js >= 20.0.0
• Claude Code

License

MIT