gsd-lite 0.3.8 → 0.3.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +200 -92
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,146 +1,254 @@
|
|
|
1
1
|
# GSD-Lite
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Get Shit Done — AI orchestration for Claude Code
|
|
4
4
|
|
|
5
|
-
GSD-Lite
|
|
5
|
+
GSD-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 state machine that keeps multi-phase projects on track.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**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.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
### Structured Execution Engine
|
|
12
|
+
- **Phase-based project management** — Break work into phases with ordered tasks, dependency tracking, and handoff gates
|
|
13
|
+
- **State machine orchestration** — 11 workflow modes with precise state transitions, persistent to `state.json`
|
|
14
|
+
- **Automatic task scheduling** — Gate-aware dependency resolution determines what runs next
|
|
15
|
+
- **Session resilience** — Stop anytime, resume exactly where you left off — even across Claude Code restarts
|
|
16
|
+
|
|
17
|
+
### Quality Discipline (Built-in, Not Optional)
|
|
18
|
+
- **TDD enforcement** — "No production code without a failing test first" baked into every executor dispatch
|
|
19
|
+
- **Anti-rationalization guards** — Red-flag checklists inline in every agent prompt, blocking common excuses to skip process
|
|
20
|
+
- **Multi-level code review** — L0 self-review / L1 phase-batch review / L2 immediate independent review
|
|
21
|
+
- **Contract change propagation** — When an API contract changes, downstream tasks automatically invalidate
|
|
14
22
|
|
|
15
|
-
|
|
23
|
+
### Intelligent Failure Recovery
|
|
24
|
+
- **3-strike retry with debugger escalation** — Failed tasks retry up to 3 times, then auto-dispatch a debugger agent
|
|
25
|
+
- **Systematic root cause analysis** — Debugger tests hypotheses, finds root cause, feeds fix guidance back to executor
|
|
26
|
+
- **Blocked task handling** — Blocked tasks are parked; execution continues with remaining tasks
|
|
27
|
+
- **Rework propagation** — Critical review issues cascade invalidation to dependent tasks
|
|
16
28
|
|
|
17
|
-
|
|
29
|
+
### Context Protection
|
|
30
|
+
- **Subagent isolation** — Each task runs in its own agent context, preventing cross-contamination
|
|
31
|
+
- **StatusLine monitoring** — Real-time context health tracking via Claude Code StatusLine
|
|
32
|
+
- **Evidence-based verification** — Every claim backed by command output, not assertions
|
|
33
|
+
- **Research with TTL** — Research artifacts include volatility ratings and expiration dates
|
|
18
34
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
35
|
+
## Architecture
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
User → discuss + research (confirm requirements) → approve plan → auto-execute
|
|
39
|
+
↑ ↑ ↑
|
|
40
|
+
Interaction 1 Interaction 2 Autonomous execution
|
|
41
|
+
(code→review→verify→advance)
|
|
42
|
+
```
|
|
27
43
|
|
|
28
|
-
|
|
44
|
+
### 5 Commands
|
|
29
45
|
|
|
30
|
-
|
|
|
31
|
-
|
|
32
|
-
| `/gsd:start` |
|
|
33
|
-
| `/gsd:prd
|
|
34
|
-
| `/gsd:resume` |
|
|
35
|
-
| `/gsd:status` |
|
|
36
|
-
| `/gsd:stop` |
|
|
46
|
+
| Command | Purpose |
|
|
47
|
+
|---------|---------|
|
|
48
|
+
| `/gsd:start` | Interactive start — discuss requirements, research, plan, then auto-execute |
|
|
49
|
+
| `/gsd:prd <input>` | Start from a requirements doc or description text |
|
|
50
|
+
| `/gsd:resume` | Resume execution from saved state |
|
|
51
|
+
| `/gsd:status` | View project progress dashboard |
|
|
52
|
+
| `/gsd:stop` | Save state and pause execution |
|
|
37
53
|
|
|
38
|
-
|
|
54
|
+
### 4 Agents
|
|
39
55
|
|
|
40
|
-
| Agent |
|
|
41
|
-
|
|
42
|
-
| **executor** |
|
|
43
|
-
| **reviewer** |
|
|
44
|
-
| **researcher** |
|
|
45
|
-
| **debugger** | 4
|
|
56
|
+
| Agent | Role | Built-in Discipline |
|
|
57
|
+
|-------|------|---------------------|
|
|
58
|
+
| **executor** | Execute a single task (TDD + self-review + checkpoint) | Iron Law + Red Flags + Deviation Rules |
|
|
59
|
+
| **reviewer** | Two-stage review (spec check → quality check) | Independent verification + Hard Gates |
|
|
60
|
+
| **researcher** | Ecosystem research (Context7 → official docs → web) | Confidence scoring + TTL |
|
|
61
|
+
| **debugger** | 4-phase systematic root cause analysis | Root Cause Iron Law |
|
|
46
62
|
|
|
47
|
-
|
|
63
|
+
### MCP Server (10 Tools)
|
|
48
64
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
65
|
+
| Tool | Purpose |
|
|
66
|
+
|------|---------|
|
|
67
|
+
| `health` | Server status and state existence check |
|
|
68
|
+
| `state-init` | Initialize `.gsd/` directory with project structure |
|
|
69
|
+
| `state-read` | Read state with optional field filtering |
|
|
70
|
+
| `state-update` | Update canonical fields with lifecycle validation |
|
|
71
|
+
| `phase-complete` | Complete a phase after verifying handoff gates |
|
|
72
|
+
| `orchestrator-resume` | Resume orchestration from current state |
|
|
73
|
+
| `orchestrator-handle-executor-result` | Process executor output, advance lifecycle |
|
|
74
|
+
| `orchestrator-handle-reviewer-result` | Process review, trigger accept/rework |
|
|
75
|
+
| `orchestrator-handle-researcher-result` | Store research artifacts and decisions |
|
|
76
|
+
| `orchestrator-handle-debugger-result` | Process root cause analysis, re-dispatch executor |
|
|
57
77
|
|
|
58
|
-
##
|
|
78
|
+
## Installation
|
|
79
|
+
|
|
80
|
+
### Method 1: Claude Code Plugin (Recommended)
|
|
59
81
|
|
|
60
82
|
```bash
|
|
61
|
-
#
|
|
83
|
+
# Step 1: Add the marketplace
|
|
62
84
|
/plugin marketplace add sdsrss/gsd-lite
|
|
63
|
-
/plugin install gsd
|
|
64
85
|
|
|
65
|
-
#
|
|
86
|
+
# Step 2: Install the plugin
|
|
87
|
+
/plugin install gsd@sdsrss-gsd-lite
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Automatically registers all commands, agents, workflows, MCP server, and hooks. Run these commands inside a Claude Code session.
|
|
91
|
+
|
|
92
|
+
### Method 2: npx
|
|
93
|
+
|
|
94
|
+
```bash
|
|
66
95
|
npx gsd-lite install
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Method 3: Manual
|
|
67
99
|
|
|
68
|
-
|
|
100
|
+
```bash
|
|
69
101
|
git clone https://github.com/sdsrss/gsd-lite.git
|
|
70
102
|
cd gsd-lite && npm install && node cli.js install
|
|
71
103
|
```
|
|
72
104
|
|
|
73
|
-
|
|
105
|
+
Methods 2 & 3 write components to `~/.claude/` and register the MCP server in `settings.json`.
|
|
74
106
|
|
|
75
|
-
|
|
107
|
+
Uninstall: `node cli.js uninstall` or `npx gsd-lite uninstall`
|
|
76
108
|
|
|
77
|
-
##
|
|
109
|
+
## Upgrade
|
|
78
110
|
|
|
79
111
|
```bash
|
|
80
|
-
#
|
|
81
|
-
/plugin update gsd
|
|
112
|
+
# Plugin
|
|
113
|
+
/plugin update gsd@sdsrss-gsd-lite
|
|
82
114
|
|
|
83
|
-
#
|
|
84
|
-
git pull && npm install && node cli.js install
|
|
85
|
-
|
|
86
|
-
# npx 方式
|
|
115
|
+
# npx
|
|
87
116
|
npx gsd-lite install
|
|
117
|
+
|
|
118
|
+
# Manual
|
|
119
|
+
git pull && npm install && node cli.js install
|
|
88
120
|
```
|
|
89
121
|
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
122
|
+
- Installer is idempotent — no need to uninstall first
|
|
123
|
+
- Upgrades from older versions auto-clean legacy files
|
|
124
|
+
- Restart Claude Code after updating to load new MCP server / hooks
|
|
93
125
|
|
|
94
|
-
##
|
|
126
|
+
## Quick Start
|
|
127
|
+
|
|
128
|
+
### Interactive Start
|
|
95
129
|
|
|
96
130
|
```bash
|
|
97
|
-
# 交互式启动
|
|
98
131
|
/gsd:start
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
GSD-Lite will:
|
|
135
|
+
1. Analyze your codebase (tech stack, conventions, structure)
|
|
136
|
+
2. Ask what you want to build
|
|
137
|
+
3. Research the ecosystem (libraries, patterns, pitfalls)
|
|
138
|
+
4. Present a phased plan for your approval
|
|
139
|
+
5. Auto-execute all phases once approved
|
|
99
140
|
|
|
100
|
-
|
|
141
|
+
### From Requirements
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
# From a requirements document
|
|
101
145
|
/gsd:prd docs/requirements.md
|
|
102
146
|
|
|
103
|
-
#
|
|
104
|
-
/gsd:prd "
|
|
147
|
+
# From a description
|
|
148
|
+
/gsd:prd "Build a REST API with JWT auth, rate limiting, and PostgreSQL"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Resume After Interruption
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
/gsd:resume
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Validates workspace consistency (git HEAD, file integrity), then resumes from the exact task and workflow mode where execution stopped.
|
|
158
|
+
|
|
159
|
+
### Monitor Progress
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
/gsd:status
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Shows phase completion, task lifecycle states, review status, and blockers — all derived from canonical state fields in real-time.
|
|
166
|
+
|
|
167
|
+
## How It Works
|
|
168
|
+
|
|
169
|
+
### Execution Loop
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
1. orchestrator-resume → determines next action
|
|
173
|
+
2. dispatch executor → runs task with TDD discipline
|
|
174
|
+
3. executor checkpoints → saves work + evidence
|
|
175
|
+
4. dispatch reviewer → independent spec + quality review
|
|
176
|
+
5. reviewer accepts → task done, schedule next
|
|
177
|
+
reviewer rejects → rework with specific feedback
|
|
178
|
+
6. all tasks done → phase handoff gate check
|
|
179
|
+
7. gate passes → advance to next phase
|
|
180
|
+
8. all phases done → project complete
|
|
105
181
|
```
|
|
106
182
|
|
|
107
|
-
|
|
183
|
+
### Failure Recovery
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
executor fails (attempt 1) → retry with context
|
|
187
|
+
executor fails (attempt 2) → retry with accumulated context
|
|
188
|
+
executor fails (attempt 3) → dispatch debugger
|
|
189
|
+
debugger analyzes → root cause + fix direction
|
|
190
|
+
executor retries → with debugger guidance injected
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### State Persistence
|
|
194
|
+
|
|
195
|
+
All state lives in `.gsd/state.json` — a single source of truth with:
|
|
196
|
+
- Canonical fields (whitelist-controlled, schema-validated)
|
|
197
|
+
- Lifecycle state machine (pending → running → checkpointed → accepted)
|
|
198
|
+
- Evidence references (command outputs, test results)
|
|
199
|
+
- Research artifacts and decision index
|
|
200
|
+
|
|
201
|
+
## Comparison with GSD
|
|
202
|
+
|
|
203
|
+
| Dimension | GSD | GSD-Lite |
|
|
204
|
+
|-----------|-----|----------|
|
|
205
|
+
| Commands | 32 | **5** |
|
|
206
|
+
| Agents | 12 | **4** |
|
|
207
|
+
| Source files | 100+ | **~35** |
|
|
208
|
+
| Installer | 2465 lines | **~80 lines** |
|
|
209
|
+
| User interactions | 6+ confirmations | **Typically 2** |
|
|
210
|
+
| TDD / Anti-rationalization | No | **Yes** |
|
|
211
|
+
| State machine recovery | Partial | **Full (11 modes)** |
|
|
212
|
+
| Evidence-based verification | No | **Yes** |
|
|
213
|
+
|
|
214
|
+
## Project Structure
|
|
108
215
|
|
|
109
216
|
```
|
|
110
217
|
gsd-lite/
|
|
111
|
-
├──
|
|
112
|
-
│ ├──
|
|
113
|
-
│
|
|
114
|
-
├── .
|
|
115
|
-
├── src/ # MCP Server + 工具层 (~1100行)
|
|
116
|
-
│ ├── server.js # MCP Server (4 tools 注册)
|
|
117
|
-
│ ├── schema.js # State schema + lifecycle 校验
|
|
118
|
-
│ ├── utils.js # 共享工具 (原子写入, 路径, git)
|
|
218
|
+
├── src/ # MCP Server + tools (~3300 lines)
|
|
219
|
+
│ ├── server.js # MCP Server entry (10 tools)
|
|
220
|
+
│ ├── schema.js # State schema + lifecycle validation
|
|
221
|
+
│ ├── utils.js # Shared utilities (atomic writes, git)
|
|
119
222
|
│ └── tools/
|
|
120
|
-
│ ├── state.js # State CRUD + evidence +
|
|
121
|
-
│
|
|
122
|
-
|
|
123
|
-
├──
|
|
124
|
-
├──
|
|
125
|
-
├──
|
|
126
|
-
├──
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
├── cli.js #
|
|
130
|
-
├──
|
|
131
|
-
|
|
132
|
-
└── uninstall.js # 卸载脚本
|
|
223
|
+
│ ├── state.js # State CRUD + evidence + propagation
|
|
224
|
+
│ ├── orchestrator.js # Orchestration logic + agent handlers
|
|
225
|
+
│ └── verify.js # lint/typecheck/test verification
|
|
226
|
+
├── commands/ # 5 slash commands
|
|
227
|
+
├── agents/ # 4 subagent prompts
|
|
228
|
+
├── workflows/ # 5 core workflows (TDD, review, debug, research, deviation)
|
|
229
|
+
├── references/ # 8 reference docs (execution loop, state diagram, evidence spec, ...)
|
|
230
|
+
├── hooks/ # Context monitoring (StatusLine + PostToolUse)
|
|
231
|
+
├── tests/ # 575 tests (506 unit + 69 E2E)
|
|
232
|
+
├── cli.js # Install/uninstall CLI entry
|
|
233
|
+
├── install.js # Installation script
|
|
234
|
+
└── uninstall.js # Uninstall script
|
|
133
235
|
```
|
|
134
236
|
|
|
135
|
-
|
|
237
|
+
## Testing
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
npm test # Run all 575 tests
|
|
241
|
+
npm run test:coverage # Tests + coverage report (94%+ lines, 81%+ branches)
|
|
242
|
+
npm run lint # Biome lint
|
|
243
|
+
node --test tests/file.js # Run a single test file
|
|
244
|
+
```
|
|
136
245
|
|
|
137
|
-
##
|
|
246
|
+
## Documentation
|
|
138
247
|
|
|
139
|
-
- [
|
|
140
|
-
- [
|
|
141
|
-
- [
|
|
248
|
+
- [Design Document v3.5](docs/gsd-lite-design.md) — Full architecture and protocol spec
|
|
249
|
+
- [Engineering Tasks](docs/gsd-lite-engineering-tasks.md) — 38 implementation tasks (5 phases, all complete)
|
|
250
|
+
- [Calibration Notes](docs/calibration-notes.md) — Context threshold and TTL calibration
|
|
142
251
|
|
|
143
252
|
## License
|
|
144
253
|
|
|
145
254
|
MIT
|
|
146
|
-
|