{"id":47036661,"url":"https://github.com/sdsrss/gsd-lite","last_synced_at":"2026-05-23T19:01:16.758Z","repository":{"id":343433623,"uuid":"1177317224","full_name":"sdsrss/gsd-lite","owner":"sdsrss","description":"AI orchestration tool for Claude Code with MCP state management, review workflows, and plugin auto-update","archived":false,"fork":false,"pushed_at":"2026-04-20T16:04:51.000Z","size":1002,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T18:12:59.075Z","etag":null,"topics":["ai-agent","automation","claude-code","claude-plugin","mcp","nodejs","orchestration","task-management"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sdsrss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T23:05:22.000Z","updated_at":"2026-04-20T16:04:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sdsrss/gsd-lite","commit_stats":null,"previous_names":["sdsrss/gsd-lite"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/sdsrss/gsd-lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fgsd-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fgsd-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fgsd-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fgsd-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdsrss","download_url":"https://codeload.github.com/sdsrss/gsd-lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fgsd-lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","claude-code","claude-plugin","mcp","nodejs","orchestration","task-management"],"created_at":"2026-03-12T01:38:35.888Z","updated_at":"2026-05-23T19:01:16.736Z","avatar_url":"https://github.com/sdsrss.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GSD-Lite\n\n\u003e Get Shit Done — AI orchestration for Claude Code\n\nGSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.com/en/docs/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.\n\n**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.\n\n## Features\n\n### Structured Execution Engine\n- **Phase-based project management** — Break work into phases with ordered tasks, dependency tracking, and handoff gates\n- **12-state workflow machine** — `planning → executing_task → reviewing_task → reviewing_phase → completed` with precise transitions, persistent to `state.json`\n- **Automatic task scheduling** — Gate-aware dependency resolution determines what runs next\n- **Session resilience** — Stop anytime, resume exactly where you left off — crash protection via Stop hook auto-saves state markers\n\n### Quality Discipline (Built-in, Not Optional)\n- **TDD enforcement** — \"No production code without a failing test first\" baked into every executor dispatch\n- **Anti-rationalization guards** — Red-flag checklists inline in every agent prompt, blocking common excuses to skip process\n- **Multi-level code review** — L0 self-review / L1 phase-batch review / L2 immediate independent review / phase review retry limit\n- **Contract change propagation** — When an API contract changes, downstream tasks automatically invalidate\n\n### Intelligent Failure Recovery\n- **3-strike retry with debugger escalation** — Failed tasks retry up to 3 times, then auto-dispatch a debugger agent\n- **Systematic root cause analysis** — Debugger tests hypotheses, finds root cause, feeds fix guidance back to executor\n- **Blocked task handling** — Blocked tasks are parked; execution continues with remaining tasks\n- **Rework propagation** — Critical review issues cascade invalidation to dependent tasks\n\n### Adaptive Review \u0026 Parallel Execution\n- **Confidence-based review adjustment** — Executor self-assesses confidence (high/medium/low); orchestrator auto-adjusts review level with evidence cross-validation\n- **Impact analysis before review** — Reviewer runs impact analysis on multi-file changes to catch missed downstream effects\n- **Parallel task scheduling** — Independent tasks within the same phase are identified for concurrent dispatch\n- **Auto PR suggestion** — Phase/project completion prompts PR creation with evidence summary\n\n### Context Protection \u0026 Monitoring\n- **Subagent isolation** — Each task runs in its own agent context, preventing cross-contamination\n- **Real-time context health monitoring** — StatusLine tracks context usage and project phase; composite StatusLine support coexists with other plugins\n- **Session lifecycle hooks** — Stop hook writes crash marker; SessionStart injects project status into CLAUDE.md; resume detects non-graceful exits\n- **Evidence-based verification** — Every claim backed by command output, not assertions\n- **Research with TTL** — Research artifacts include volatility ratings and expiration dates\n\n### Auto-Update \u0026 Version Management\n- **Automatic update checks** — Checks GitHub Releases every 24 hours with rate-limit backoff\n- **Version drift detection** — Server startup compares running version against disk and plugin registry, warns on mismatch\n- **Smart cache management** — Keeps latest 3 cached versions, auto-prunes old entries\n- **Idempotent installer** — Reinstall anytime without uninstalling; legacy files auto-cleaned\n\n## Architecture\n\n```\nUser → discuss + research (confirm requirements) → approve plan → auto-execute\n        ↑                      ↑                        ↑\n     Interaction 1          Interaction 2          Autonomous execution\n                                              (code→review→verify→advance)\n```\n\n### 6 Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/gsd:start` | Interactive start — discuss requirements, research, plan, then auto-execute |\n| `/gsd:prd \u003cinput\u003e` | Start from a requirements doc or description text |\n| `/gsd:resume` | Resume execution from saved state with workspace validation |\n| `/gsd:status` | View project progress dashboard (derived from canonical state fields) |\n| `/gsd:stop` | Save state and pause execution |\n| `/gsd:doctor` | Diagnostic checks on GSD-Lite installation and project health |\n\n### 4 Agents\n\n| Agent | Role | Built-in Discipline |\n|-------|------|---------------------|\n| **executor** | Execute a single task (TDD + self-review + checkpoint) | Iron Law + Red Flags + Deviation Rules |\n| **reviewer** | Two-stage review (spec check → quality check) | Independent verification + Hard Gates |\n| **researcher** | Ecosystem research (Context7 → official docs → web) | Confidence scoring + TTL |\n| **debugger** | 4-phase systematic root cause analysis | Root Cause Iron Law |\n\n### 6 Workflows\n\n| Workflow | Purpose |\n|----------|---------|\n| `tdd-cycle` | RED-GREEN-REFACTOR TDD cycle enforcement |\n| `review-cycle` | Two-level review gates and accept/rework decisions |\n| `debugging` | 4-phase root cause analysis process |\n| `research` | Research with confidence scoring and TTL expiration |\n| `deviation-rules` | Anti-rationalization guards and red-flag checklists |\n| `execution-flow` | Complete task execution cycle from dispatch to checkpoint |\n\n### MCP Server (11 Tools)\n\n| Tool | Purpose |\n|------|---------|\n| `health` | Server status and state existence check |\n| `state-init` | Initialize `.gsd/` directory with project structure |\n| `state-read` | Read state with optional field filtering |\n| `state-update` | Update canonical fields with lifecycle validation |\n| `state-patch` | Incrementally modify plan (add/remove/reorder tasks, update fields, add dependencies) |\n| `phase-complete` | Complete a phase after verifying handoff gates |\n| `orchestrator-resume` | Resume orchestration from current state |\n| `orchestrator-handle-executor-result` | Process executor output, advance lifecycle |\n| `orchestrator-handle-reviewer-result` | Process review, trigger accept/rework |\n| `orchestrator-handle-researcher-result` | Store research artifacts and decisions |\n| `orchestrator-handle-debugger-result` | Process root cause analysis, re-dispatch executor |\n\n### 8 References\n\n| Reference | Content |\n|-----------|---------|\n| `execution-loop` | 9-step execution loop specification (single source of truth) |\n| `review-classification` | Review level classification decision tree (L0/L1/L2) |\n| `evidence-spec` | Evidence validation and citation rules |\n| `state-diagram` | 12-state lifecycle workflow machine diagram |\n| `testing-patterns` | Test structure and patterns |\n| `anti-rationalization-full` | Full red-flag checklist for agents |\n| `git-worktrees` | Git worktree isolation strategy |\n| `questioning` | Requirements clarification patterns |\n\n## Installation\n\n### Method 1: Claude Code Plugin (Recommended)\n\n```bash\n# Step 1: Add the marketplace\n/plugin marketplace add sdsrss/gsd-lite\n\n# Step 2: Install the plugin\n/plugin install gsd\n```\n\nAutomatically registers all commands, agents, workflows, MCP server, hooks, and auto-update. Run these commands inside a Claude Code session.\n\n### Method 2: npx\n\n```bash\nnpx gsd-lite install\n```\n\n### Method 3: Manual\n\n```bash\ngit clone https://github.com/sdsrss/gsd-lite.git\ncd gsd-lite \u0026\u0026 npm install \u0026\u0026 node cli.js install\n```\n\nMethods 2 \u0026 3 write components to `~/.claude/` and register the MCP server in `settings.json`.\n\nThe installer copies commands, agents, workflows, references, and hooks to `~/.claude/`, and sets up the MCP server runtime in `~/.claude/gsd/`.\n\nUninstall: `node cli.js uninstall` or `npx gsd-lite uninstall`\n\n## Upgrade\n\n```bash\n# Plugin (auto-update checks GitHub Releases every 24h)\n/plugin update gsd\n\n# npx\nnpx gsd-lite install\n\n# Manual\ngit pull \u0026\u0026 npm install \u0026\u0026 node cli.js install\n```\n\n- Installer is idempotent — no need to uninstall first\n- Upgrades from older versions auto-clean legacy files\n- Smart cache management keeps latest 3 versions, prunes old entries\n- Restart Claude Code after updating to load new MCP server / hooks\n\n## Quick Start\n\n### Interactive Start\n\n```bash\n/gsd:start\n```\n\nGSD-Lite will:\n1. Analyze your codebase (tech stack, conventions, structure)\n2. Ask what you want to build\n3. Research the ecosystem (libraries, patterns, pitfalls)\n4. Present a phased plan for your approval\n5. Auto-execute all phases once approved\n\n### From Requirements\n\n```bash\n# From a requirements document\n/gsd:prd docs/requirements.md\n\n# From a description\n/gsd:prd \"Build a REST API with JWT auth, rate limiting, and PostgreSQL\"\n```\n\n### Resume After Interruption\n\n```bash\n/gsd:resume\n```\n\nValidates workspace consistency (git HEAD, file integrity), then resumes from the exact task and workflow mode where execution stopped.\n\n### Monitor Progress\n\n```bash\n/gsd:status\n```\n\nShows phase completion, task lifecycle states, review status, and blockers — all derived from canonical state fields in real-time.\n\n## How It Works\n\n### Execution Loop\n\n```\n1. orchestrator-resume → determines next action\n2. dispatch executor → runs task with TDD discipline\n3. executor checkpoints → saves work + evidence\n4. dispatch reviewer → independent spec + quality review\n5. reviewer accepts → task done, schedule next\n   reviewer rejects → rework with specific feedback\n6. all tasks done → phase handoff gate check\n7. gate passes → advance to next phase\n8. all phases done → project complete\n```\n\n### Failure Recovery\n\n```\nexecutor fails (attempt 1) → retry with context\nexecutor fails (attempt 2) → retry with accumulated context\nexecutor fails (attempt 3) → dispatch debugger\ndebugger analyzes → root cause + fix direction\nexecutor retries → with debugger guidance injected\n```\n\n### State Persistence\n\nAll state lives in `.gsd/state.json` — a single source of truth with:\n- Canonical fields (whitelist-controlled, schema-validated)\n- Lifecycle state machine (pending → running → checkpointed → accepted)\n- Optimistic concurrency control (`_version` field with `VERSION_CONFLICT` detection)\n- Evidence references (command outputs, test results)\n- Research artifacts and decision index\n- Incremental validation (simple field updates use fast path; phases use full validation)\n\n## Comparison with GSD\n\n| Dimension | GSD | GSD-Lite |\n|-----------|-----|----------|\n| Commands | 32 | **6** |\n| Agents | 12 | **4** |\n| Source files | 100+ | **~15** |\n| Installer | 2465 lines | **~290 lines** |\n| User interactions | 6+ confirmations | **Typically 2** |\n| TDD / Anti-rationalization | No | **Yes** |\n| State machine recovery | Partial | **Full (12 modes)** |\n| Evidence-based verification | No | **Yes** |\n| Auto-update | No | **Yes** |\n| Context health monitoring | No | **Yes** |\n\n## Project Structure\n\n```\ngsd-lite/\n├── src/                    # MCP Server + tools (15 source files)\n│   ├── server.js           # MCP Server entry (11 tools + version drift detection)\n│   ├── schema.js           # State schema + lifecycle validation + incremental validation\n│   ├── utils.js            # Shared utilities (atomic writes, git, file lock)\n│   └── tools/\n│       ├── state/          # State management (modular)\n│       │   ├── constants.js  # Error codes, lock infrastructure\n│       │   ├── crud.js       # CRUD operations + plan patching\n│       │   ├── logic.js      # Task scheduling, propagation, research\n│       │   └── index.js      # Re-exports\n│       ├── orchestrator/   # Orchestration logic (modular)\n│       │   ├── helpers.js    # Shared constants, preflight, dispatch\n│       │   ├── resume.js     # Workflow resume state machine (12 modes)\n│       │   ├── executor.js   # Executor result handler\n│       │   ├── reviewer.js   # Reviewer result handler\n│       │   ├── debugger.js   # Debugger result handler\n│       │   ├── researcher.js # Researcher result handler\n│       │   └── index.js      # Re-exports\n│       └── verify.js       # lint/typecheck/test verification\n├── commands/               # 6 slash commands (start, prd, resume, status, stop, doctor)\n├── agents/                 # 4 subagent prompts (executor, reviewer, researcher, debugger)\n├── workflows/              # 6 core workflows (TDD, review, debug, research, deviation, execution-flow)\n├── references/             # 8 reference docs (execution-loop, state-diagram, evidence-spec, etc.)\n├── hooks/                  # Session lifecycle hooks\n│   ├── gsd-auto-update.cjs   # Auto-update from GitHub Releases (24h check interval)\n│   ├── gsd-context-monitor.cjs # Real-time context health monitoring\n│   ├── gsd-session-init.cjs   # Session initialization + CLAUDE.md status injection\n│   ├── gsd-session-stop.cjs   # Graceful shutdown with crash markers\n│   ├── gsd-statusline.cjs     # StatusLine display (composite-aware)\n│   └── lib/                   # Shared hook utilities (gsd-finder, composite statusline, semver)\n├── tests/                  # 972 tests (unit + simulation + E2E integration)\n├── cli.js                  # Install/uninstall CLI entry\n├── install.js              # Installation script (plugin-aware, idempotent)\n└── uninstall.js            # Uninstall script\n```\n\n## Testing\n\n```bash\nnpm test                    # Run all 972 tests\nnpm run test:coverage       # Tests + coverage report (94%+ lines, 83%+ branches)\nnpm run lint                # Biome lint\nnode --test tests/file.js   # Run a single test file\n```\n\n## Documentation\n\n- [Design Document v3.5](docs/gsd-lite-design.md) — Full architecture and protocol spec\n- [Engineering Tasks](docs/gsd-lite-engineering-tasks.md) — 38 implementation tasks (5 phases, all complete)\n- [Calibration Notes](docs/calibration-notes.md) — Context threshold and TTL calibration\n\n## Requirements\n\n- Node.js \u003e= 20.0.0\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fgsd-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdsrss%2Fgsd-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fgsd-lite/lists"}