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 / L3 immediate review plus a human sign-off gate that code enforces (see Review Levels) / 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 (StatusLine needs the npx gsd-lite install step — see Installation)
• 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/L3) | | 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

Registers the commands, agents, workflows, MCP server, session hooks, and update checks. Run these commands inside a Claude Code session, then restart it.

One thing the plugin system cannot do for us: statusLine is a top-level settings.json setting, and a plugin may not write there — so the progress StatusLine stays off on a plugin-only install. Add it with npx gsd-lite install, which is safe to run alongside the plugin: it detects the plugin and skips everything the plugin already serves, registering only the StatusLine and the hook scripts it needs.

To remove just the StatusLine afterwards, delete the statusLine key from ~/.claude/settings.json. Do not reach for npx gsd-lite uninstall for that — it removes everything GSD installed, the plugin cache, the marketplace entry and the enabledPlugins registration included, so you would be uninstalling the plugin as well.

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:

1. Analyze your codebase (tech stack, conventions, structure)
2. Ask what you want to build
3. Research the ecosystem (libraries, patterns, pitfalls)
4. Present a phased plan for your approval
5. 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.

Do not resume a checkout you don't trust.

.gsd/ is ordinary repository content. A clone, a fork, or a pull request branch carries whatever the author put there, and /gsd:resume turns that content into work: the plan's task descriptions become executor dispatches, which run commands and write files in your workspace. Resuming a project you didn't plan is running a task list you didn't write.

This starts before you type anything. The StatusLine hook reads .gsd/state.json on every render and SessionStart reads it when the session opens, each walking up from the working directory until it finds a .gsd/state.json — so merely opening Claude Code in an untrusted checkout is enough for GSD-Lite to read that repo's state file.

The read path itself is hardened: state reads go through an ownership-checked reader, so a symlink, a FIFO, or a directory left at one of those paths cannot hang the hook or quietly substitute another file. That makes the file safe to touch. It does not make the plan safe to run — no amount of read hardening can tell an attacker's task list from yours.

Treat .gsd/plan.md and .gsd/state.json the way you'd treat a Makefile or .vscode/tasks.json from a stranger: read them before you act on them. When in doubt, delete .gsd/ and plan the work yourself.

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

Review Levels

Every task carries a level that decides how its checkpoint is reviewed. Levels can be raised mid-flight (low executor confidence, a contract change, an explicit [LEVEL-UP]), never lowered once they reach L2 or L3.

| Level | Typical work | What happens after checkpoint | |-------|--------------|-------------------------------| | L0 | No runtime semantics (docs, config, style) | Accepted directly, no reviewer | | L1 | Ordinary coding (default) | Batch-reviewed at end of phase | | L2 | High risk — auth, payment, public API, DB migration | Immediate independent review | | L3 | Highest risk — security architecture, breaking changes | Immediate independent review and a human confirmation hold |

The L3 gate is enforced by the orchestrator, not by agent prompts. When a reviewer approves a task whose level is L3, the task is not accepted. It stays checkpointed, the workflow moves to awaiting_user, and current_review.stage becomes human_confirmation — so autonomous execution stops there and waits for you. Other tasks in the same review batch are accepted normally; only the L3 ones are withheld.

Resolve the hold through orchestrator-resume:

confirm_review: "confirm"   → the held task(s) become accepted, execution continues
confirm_review: "reject"    → the held task(s) go back for rework with your feedback

The gate fires on the task's level, not on a reviewer flag: a reviewer cannot opt out of it, and it covers phase-scoped reviews too. requires_human_confirmation and security_implications remain the reviewer's channel for attaching security context to the hold, which resume surfaces when it reports the pending confirmation.

This is the one point where "discuss thoroughly, execute automatically" deliberately stops being automatic. If you plan security or architecture work as L3, expect to be asked.

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)

state-init lays the directory out like this:

.gsd/
├── state.json              # canonical state — rewritten on nearly every tool call
├── state.json.bak          # last good state, kept when you re-init with force
├── plan.md                 # human-readable plan
├── phases/                 # per-phase notes
├── research/               # STACK.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md
├── .session-end            # session lifecycle marker (Stop hook)
├── .context-health         # context usage snapshot (StatusLine)
└── .research-commit-pending # marker: research landed but was never committed

Should you commit .gsd/?

Default: no — add .gsd/ to .gitignore. This repository does exactly that for its own working state. Three reasons:

• state.json is rewritten on nearly every tool call and carries a _version counter for optimistic concurrency. On a shared branch it conflicts on essentially every pull, and a hand-resolved merge of that file is a corrupted state machine, not a merged plan.
• The three dot-markers are per-machine, per-session facts. Committed, they describe someone else's session — .session-end in particular is how resume decides whether the last exit was graceful.
• A committed plan is an executable plan for anyone who clones the repo. See the warning under Resume After Interruption.

If you want the plan visible in review, commit only the prose artifacts and keep the machinery out:

.gsd/*
!.gsd/plan.md
!.gsd/phases/
!.gsd/research/

Those are written for humans and change at phase boundaries rather than per tool call. Everything else in .gsd/ is runtime state that belongs to one checkout on one machine.

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/                  # unit + simulation + E2E integration tests
├── cli.js                  # Install/uninstall CLI entry
├── install.js              # Installation script (plugin-aware, idempotent)
└── uninstall.js            # Uninstall script

Testing

npm test                    # Run the full test suite
npm run test:coverage       # Tests + coverage report (whole-package ~93% lines / ~86% branches; gate: 80% lines / 75% branches)
npm run lint                # Biome lint
node --test tests/file.js   # Run a single test file

Environment variables

| Variable | Effect | |----------|--------| | GSD_NO_CLAUDEMD_STATUS=1 | Opt out of the SessionStart hook injecting a <!-- GSD-STATUS-BEGIN -->…<!-- GSD-STATUS-END --> progress block into the project's CLAUDE.md. The block is idempotent (marker-delimited replace); set this if you'd rather GSD not touch CLAUDE.md. | | GSD_DEBUG=1 | Emit diagnostic output to stderr from hooks and the MCP server (tool dispatch + state read/write), for troubleshooting. |

Documentation

• references/ — the 8 reference docs listed above. They ship with the package, and agents read them at runtime.
• workflows/ — the 6 workflow specs listed above, same deal.

Design notes (architecture spec, engineering task breakdown, calibration notes) live in a gitignored docs/ directory: they are the author's working papers and are not part of a clone or the npm tarball.

Requirements

• Node.js >= 20.0.0
• Claude Code

License

MIT