gsd-lite 0.3.7 → 0.3.9
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 +196 -92
- package/package.json +1 -1
- package/src/tools/orchestrator.js +1 -1
package/README.md
CHANGED
|
@@ -1,146 +1,250 @@
|
|
|
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
|
+
|
|
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
|
|
22
|
+
|
|
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
|
|
28
|
+
|
|
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
|
|
34
|
+
|
|
35
|
+
## Architecture
|
|
8
36
|
|
|
9
37
|
```
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
38
|
+
User → discuss + research (confirm requirements) → approve plan → auto-execute
|
|
39
|
+
↑ ↑ ↑
|
|
40
|
+
Interaction 1 Interaction 2 Autonomous execution
|
|
41
|
+
(code→review→verify→advance)
|
|
13
42
|
```
|
|
14
43
|
|
|
15
|
-
|
|
44
|
+
### 5 Commands
|
|
16
45
|
|
|
17
|
-
|
|
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 |
|
|
18
53
|
|
|
19
|
-
|
|
20
|
-
|------|-----|----------|
|
|
21
|
-
| 命令数 | 32 个 | **5 个** |
|
|
22
|
-
| Agent 数 | 12 个 | **4 个** |
|
|
23
|
-
| 源文件 | 100+ 个 | **~27 个** |
|
|
24
|
-
| 安装器 | 2465 行 | **~80 行** |
|
|
25
|
-
| 用户交互 | 6+ 次确认 | **常态 2 次** |
|
|
26
|
-
| TDD / 反合理化 / 质量纪律 | ❌ | ✅ |
|
|
54
|
+
### 4 Agents
|
|
27
55
|
|
|
28
|
-
|
|
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 |
|
|
29
62
|
|
|
30
|
-
|
|
31
|
-
|------|------|
|
|
32
|
-
| `/gsd:start` | 交互式启动：讨论→研究→计划→自动执行 |
|
|
33
|
-
| `/gsd:prd <需求>` | 从需求文档/描述快速启动 |
|
|
34
|
-
| `/gsd:resume` | 从断点恢复执行 |
|
|
35
|
-
| `/gsd:status` | 查看项目进度 |
|
|
36
|
-
| `/gsd:stop` | 保存状态并暂停 |
|
|
63
|
+
### MCP Server (10 Tools)
|
|
37
64
|
|
|
38
|
-
|
|
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 |
|
|
39
77
|
|
|
40
|
-
|
|
41
|
-
|-------|------|---------|
|
|
42
|
-
| **executor** | 执行单 task (TDD + 自审 + checkpoint) | 铁律 + 红旗 + 偏差规则 |
|
|
43
|
-
| **reviewer** | 双阶段审查 (规格→质量) | 独立验证 + HARD-GATE |
|
|
44
|
-
| **researcher** | 生态系统研究 (Context7→官方文档→WebSearch) | 置信度标注 |
|
|
45
|
-
| **debugger** | 4 阶段系统性根因分析 | 根因铁律 |
|
|
78
|
+
## Installation
|
|
46
79
|
|
|
47
|
-
|
|
80
|
+
### Method 1: Claude Code Plugin (Recommended)
|
|
48
81
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- **分层审查** — L0 自审 / L1 阶段批量 / L2 即时独立审查
|
|
53
|
-
- **TDD 铁律** — NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST (含合理例外)
|
|
54
|
-
- **反合理化** — 红旗列表内联到每个 Agent，封堵跳过流程的借口
|
|
55
|
-
- **返工失效传播** — contract_changed → 下游 task 自动 needs_revalidation
|
|
56
|
-
- **状态机恢复** — state.json 持久化，11 种 workflow_mode 精确恢复
|
|
82
|
+
```bash
|
|
83
|
+
claude /plugin install sdsrss/gsd-lite
|
|
84
|
+
```
|
|
57
85
|
|
|
58
|
-
|
|
86
|
+
Automatically registers all commands, agents, workflows, MCP server, and hooks.
|
|
59
87
|
|
|
60
|
-
|
|
61
|
-
# 方式一：Claude Code 插件市场 (推荐)
|
|
62
|
-
/plugin marketplace add sdsrss/gsd-lite
|
|
63
|
-
/plugin install gsd
|
|
88
|
+
### Method 2: npx
|
|
64
89
|
|
|
65
|
-
|
|
90
|
+
```bash
|
|
66
91
|
npx gsd-lite install
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Method 3: Manual
|
|
67
95
|
|
|
68
|
-
|
|
96
|
+
```bash
|
|
69
97
|
git clone https://github.com/sdsrss/gsd-lite.git
|
|
70
98
|
cd gsd-lite && npm install && node cli.js install
|
|
71
99
|
```
|
|
72
100
|
|
|
73
|
-
|
|
101
|
+
Methods 2 & 3 write components to `~/.claude/` and register the MCP server in `settings.json`.
|
|
74
102
|
|
|
75
|
-
|
|
103
|
+
Uninstall: `node cli.js uninstall` or `npx gsd-lite uninstall`
|
|
76
104
|
|
|
77
|
-
##
|
|
105
|
+
## Upgrade
|
|
78
106
|
|
|
79
107
|
```bash
|
|
80
|
-
#
|
|
81
|
-
/plugin update gsd
|
|
108
|
+
# Plugin
|
|
109
|
+
claude /plugin update gsd
|
|
82
110
|
|
|
83
|
-
#
|
|
84
|
-
git pull && npm install && node cli.js install
|
|
85
|
-
|
|
86
|
-
# npx 方式
|
|
111
|
+
# npx
|
|
87
112
|
npx gsd-lite install
|
|
113
|
+
|
|
114
|
+
# Manual
|
|
115
|
+
git pull && npm install && node cli.js install
|
|
88
116
|
```
|
|
89
117
|
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
118
|
+
- Installer is idempotent — no need to uninstall first
|
|
119
|
+
- Upgrades from older versions auto-clean legacy files
|
|
120
|
+
- Restart Claude Code after updating to load new MCP server / hooks
|
|
121
|
+
|
|
122
|
+
## Quick Start
|
|
93
123
|
|
|
94
|
-
|
|
124
|
+
### Interactive Start
|
|
95
125
|
|
|
96
126
|
```bash
|
|
97
|
-
# 交互式启动
|
|
98
127
|
/gsd:start
|
|
128
|
+
```
|
|
99
129
|
|
|
100
|
-
|
|
130
|
+
GSD-Lite will:
|
|
131
|
+
1. Analyze your codebase (tech stack, conventions, structure)
|
|
132
|
+
2. Ask what you want to build
|
|
133
|
+
3. Research the ecosystem (libraries, patterns, pitfalls)
|
|
134
|
+
4. Present a phased plan for your approval
|
|
135
|
+
5. Auto-execute all phases once approved
|
|
136
|
+
|
|
137
|
+
### From Requirements
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
# From a requirements document
|
|
101
141
|
/gsd:prd docs/requirements.md
|
|
102
142
|
|
|
103
|
-
#
|
|
104
|
-
/gsd:prd "
|
|
143
|
+
# From a description
|
|
144
|
+
/gsd:prd "Build a REST API with JWT auth, rate limiting, and PostgreSQL"
|
|
105
145
|
```
|
|
106
146
|
|
|
107
|
-
|
|
147
|
+
### Resume After Interruption
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
/gsd:resume
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Validates workspace consistency (git HEAD, file integrity), then resumes from the exact task and workflow mode where execution stopped.
|
|
154
|
+
|
|
155
|
+
### Monitor Progress
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
/gsd:status
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Shows phase completion, task lifecycle states, review status, and blockers — all derived from canonical state fields in real-time.
|
|
162
|
+
|
|
163
|
+
## How It Works
|
|
164
|
+
|
|
165
|
+
### Execution Loop
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
1. orchestrator-resume → determines next action
|
|
169
|
+
2. dispatch executor → runs task with TDD discipline
|
|
170
|
+
3. executor checkpoints → saves work + evidence
|
|
171
|
+
4. dispatch reviewer → independent spec + quality review
|
|
172
|
+
5. reviewer accepts → task done, schedule next
|
|
173
|
+
reviewer rejects → rework with specific feedback
|
|
174
|
+
6. all tasks done → phase handoff gate check
|
|
175
|
+
7. gate passes → advance to next phase
|
|
176
|
+
8. all phases done → project complete
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Failure Recovery
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
executor fails (attempt 1) → retry with context
|
|
183
|
+
executor fails (attempt 2) → retry with accumulated context
|
|
184
|
+
executor fails (attempt 3) → dispatch debugger
|
|
185
|
+
debugger analyzes → root cause + fix direction
|
|
186
|
+
executor retries → with debugger guidance injected
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### State Persistence
|
|
190
|
+
|
|
191
|
+
All state lives in `.gsd/state.json` — a single source of truth with:
|
|
192
|
+
- Canonical fields (whitelist-controlled, schema-validated)
|
|
193
|
+
- Lifecycle state machine (pending → running → checkpointed → accepted)
|
|
194
|
+
- Evidence references (command outputs, test results)
|
|
195
|
+
- Research artifacts and decision index
|
|
196
|
+
|
|
197
|
+
## Comparison with GSD
|
|
198
|
+
|
|
199
|
+
| Dimension | GSD | GSD-Lite |
|
|
200
|
+
|-----------|-----|----------|
|
|
201
|
+
| Commands | 32 | **5** |
|
|
202
|
+
| Agents | 12 | **4** |
|
|
203
|
+
| Source files | 100+ | **~35** |
|
|
204
|
+
| Installer | 2465 lines | **~80 lines** |
|
|
205
|
+
| User interactions | 6+ confirmations | **Typically 2** |
|
|
206
|
+
| TDD / Anti-rationalization | No | **Yes** |
|
|
207
|
+
| State machine recovery | Partial | **Full (11 modes)** |
|
|
208
|
+
| Evidence-based verification | No | **Yes** |
|
|
209
|
+
|
|
210
|
+
## Project Structure
|
|
108
211
|
|
|
109
212
|
```
|
|
110
213
|
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)
|
|
214
|
+
├── src/ # MCP Server + tools (~3300 lines)
|
|
215
|
+
│ ├── server.js # MCP Server entry (10 tools)
|
|
216
|
+
│ ├── schema.js # State schema + lifecycle validation
|
|
217
|
+
│ ├── utils.js # Shared utilities (atomic writes, git)
|
|
119
218
|
│ └── tools/
|
|
120
|
-
│ ├── state.js # State CRUD + evidence +
|
|
121
|
-
│
|
|
122
|
-
|
|
123
|
-
├──
|
|
124
|
-
├──
|
|
125
|
-
├──
|
|
126
|
-
├──
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
├── cli.js #
|
|
130
|
-
├──
|
|
131
|
-
|
|
132
|
-
└── uninstall.js # 卸载脚本
|
|
219
|
+
│ ├── state.js # State CRUD + evidence + propagation
|
|
220
|
+
│ ├── orchestrator.js # Orchestration logic + agent handlers
|
|
221
|
+
│ └── verify.js # lint/typecheck/test verification
|
|
222
|
+
├── commands/ # 5 slash commands
|
|
223
|
+
├── agents/ # 4 subagent prompts
|
|
224
|
+
├── workflows/ # 5 core workflows (TDD, review, debug, research, deviation)
|
|
225
|
+
├── references/ # 8 reference docs (execution loop, state diagram, evidence spec, ...)
|
|
226
|
+
├── hooks/ # Context monitoring (StatusLine + PostToolUse)
|
|
227
|
+
├── tests/ # 575 tests (506 unit + 69 E2E)
|
|
228
|
+
├── cli.js # Install/uninstall CLI entry
|
|
229
|
+
├── install.js # Installation script
|
|
230
|
+
└── uninstall.js # Uninstall script
|
|
133
231
|
```
|
|
134
232
|
|
|
135
|
-
|
|
233
|
+
## Testing
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
npm test # Run all 575 tests
|
|
237
|
+
npm run test:coverage # Tests + coverage report (94%+ lines, 81%+ branches)
|
|
238
|
+
npm run lint # Biome lint
|
|
239
|
+
node --test tests/file.js # Run a single test file
|
|
240
|
+
```
|
|
136
241
|
|
|
137
|
-
##
|
|
242
|
+
## Documentation
|
|
138
243
|
|
|
139
|
-
- [
|
|
140
|
-
- [
|
|
141
|
-
- [
|
|
244
|
+
- [Design Document v3.5](docs/gsd-lite-design.md) — Full architecture and protocol spec
|
|
245
|
+
- [Engineering Tasks](docs/gsd-lite-engineering-tasks.md) — 38 implementation tasks (5 phases, all complete)
|
|
246
|
+
- [Calibration Notes](docs/calibration-notes.md) — Context threshold and TTL calibration
|
|
142
247
|
|
|
143
248
|
## License
|
|
144
249
|
|
|
145
250
|
MIT
|
|
146
|
-
|
package/package.json
CHANGED
|
@@ -1013,7 +1013,7 @@ export async function handleReviewerResult({ result, basePath = process.cwd() }
|
|
|
1013
1013
|
phaseUpdates.phase_handoff = { required_reviews_passed: true };
|
|
1014
1014
|
}
|
|
1015
1015
|
|
|
1016
|
-
const workflowMode =
|
|
1016
|
+
const workflowMode = 'executing_task';
|
|
1017
1017
|
|
|
1018
1018
|
const persistError = await persist(basePath, {
|
|
1019
1019
|
workflow_mode: workflowMode,
|