@seanyao/roll 2026.512.6 → 2026.512.8
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/CHANGELOG.md +17 -0
- package/README.md +39 -225
- package/bin/roll +312 -36
- package/package.json +2 -2
- package/skills/roll-.changelog/SKILL.md +24 -2
- package/skills/roll-.dream/SKILL.md +127 -4
- package/skills/roll-brief/SKILL.md +9 -0
- package/skills/roll-build/SKILL.md +10 -6
- package/skills/roll-doc/SKILL.md +184 -0
- package/skills/roll-loop/SKILL.md +38 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v2026.512.8
|
|
4
|
+
- **Added**: `$roll-doc` — legacy 项目文档自动化技能：四阶段扫描（索引 + 缺口分析 + 草稿补全 + 报告），支持 `--dry-run` / `--force`，适用任何项目
|
|
5
|
+
- **Added**: `roll-.dream` Scan 6 — 文档新鲜度检测（滞后文档 / 未记录 ENV 变量 / 架构文档缺失），依赖 roll-doc，发现写入 REFACTOR 条目
|
|
6
|
+
- **Fixed**: loop CI gate 在 SSH config 改写 github.com 为 IP 的环境下失灵 — `gh` 自动识别失败被静默吞掉，loop 把 "gh 出错" 误判为 "gh 未装"，在 CI 红的情况下继续把 story 标 ✅ Done；现从 git remote 推导 `owner/repo` 强制传 `-R`，gh 调用失败 = ALERT，loop 起跑前先验 HEAD CI 红绿，红则拒绝 build
|
|
7
|
+
|
|
8
|
+
## v2026.512.7
|
|
9
|
+
- **Added**: `roll alert` — 查看、确认、清除 loop 告警，不用再去翻 loop status
|
|
10
|
+
- **Added**: macOS 系统通知 — story 完成或告警写入时自动弹通知，静音模式下不打扰
|
|
11
|
+
- **Added**: `roll ci [--wait]` — 查看当前提交的 CI 状态，或等待 CI 跑完再继续
|
|
12
|
+
- **Fixed**: loop 现在会等 CI 通过后才标记故事完成，CI 失败则保持进行中并发出提醒
|
|
13
|
+
- **Fixed**: changelog 更新不再产生独立 commit，并入故事完成提交，git log 更干净
|
|
14
|
+
- **Added**: `docs/domain/` — Roll 架构的 DDD 领域模型文档（5 个 Bounded Context + 自治操作 Aggregate 设计）
|
|
15
|
+
- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
|
|
16
|
+
- **Added**: 文档目录重组 — methodology、skill 选择指南、loop 验证记录迁移至 `docs/guide/` 和 `docs/practices/`，根目录不再有散落文件
|
|
17
|
+
- **Added**: README 大幅精简并新增文档导航索引 — 首页更清晰，所有指南一表可查
|
|
18
|
+
- **Added**: dream 每晚自动检测文档缺口，brief 新增文档覆盖率数字
|
|
19
|
+
|
|
3
20
|
## v2026.512.6
|
|
4
21
|
- **Added**: peer review 现在也会自动弹出终端窗口，实时观察跨 AI 协商过程（mute 关闭同一开关）
|
|
5
22
|
- **Added**: `docs/guide/en/` — loop/dream/peer 英文用户指南上线，覆盖所有子命令和使用场景
|
package/README.md
CHANGED
|
@@ -19,262 +19,76 @@
|
|
|
19
19
|
|
|
20
20
|
## What is Roll?
|
|
21
21
|
|
|
22
|
-
Roll
|
|
22
|
+
Roll is an autonomous delivery system for software teams — AI agents pick stories from your BACKLOG, execute them with encoded engineering discipline, and ship continuously while you stay focused on what to build next.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
**Two core values:**
|
|
25
|
+
1. **Autonomous delivery** — `roll loop on` runs BACKLOG items hourly; Dream (nightly code-health scan) surfaces maintenance tasks; humans retain sole release authority
|
|
26
|
+
2. **Skill-driven execution** — 20+ skills encode TDD, TCR, and INVEST practices as reliable, repeatable workflows any agent can follow
|
|
25
27
|
|
|
26
|
-
|
|
27
|
-
2. **Skill System** — 20 proven engineering practices (TDD, TCR, SRE, INVEST, DDD) encoded as instructions that any AI agent can follow
|
|
28
|
-
3. **Autonomous Evolution** — an optional layer that lets the agent work unattended: `roll-loop` executes BACKLOG items hourly, `roll-.dream` scans code health nightly, and `roll-brief` briefs the human each morning. The human retains sole authority over releases.
|
|
29
|
-
|
|
30
|
-
The result: any agent, any client, same constraints — and optionally, continuous autonomous delivery.
|
|
28
|
+
_Works with Claude, Cursor, Codex, or your own agent._
|
|
31
29
|
|
|
32
30
|
---
|
|
33
31
|
|
|
34
|
-
## Start
|
|
35
|
-
|
|
36
|
-
Before commands and skills, read the Engineering Methodology — it explains the three-loop architecture (Research → Build → Observe), the autonomous evolution layer, why each skill exists, and how they connect into a complete delivery system.
|
|
37
|
-
|
|
38
|
-
**[English](docs/methodology-en.md)** · **[中文](docs/methodology.md)**
|
|
39
|
-
|
|
40
|
-
---
|
|
41
|
-
|
|
42
|
-
## Installation
|
|
32
|
+
## Quick Start (30 seconds)
|
|
43
33
|
|
|
44
34
|
```bash
|
|
45
35
|
npm install -g @seanyao/roll
|
|
46
|
-
roll setup
|
|
36
|
+
roll setup # distribute conventions to all AI clients
|
|
37
|
+
cd my-project
|
|
38
|
+
roll init # create AGENTS.md + BACKLOG.md + docs/features/
|
|
39
|
+
roll loop on # optional: let the agent work unattended
|
|
47
40
|
```
|
|
48
41
|
|
|
49
42
|
**Requirements:** bash 4+, Node.js 16+
|
|
50
43
|
|
|
51
|
-
To update:
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
roll update
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
> **For contributors** (working on roll itself): `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
|
|
58
|
-
|
|
59
44
|
---
|
|
60
45
|
|
|
61
|
-
##
|
|
46
|
+
## Documentation Index
|
|
62
47
|
|
|
63
|
-
|
|
48
|
+
| Topic | English | 中文 |
|
|
49
|
+
|-------|---------|------|
|
|
50
|
+
| Overview & architecture | [guide/en/overview.md](docs/guide/en/overview.md) | [guide/zh/overview.md](docs/guide/zh/overview.md) |
|
|
51
|
+
| Engineering methodology | [guide/en/methodology.md](docs/guide/en/methodology.md) | [guide/zh/methodology.md](docs/guide/zh/methodology.md) |
|
|
52
|
+
| Loop (autonomous executor) | [guide/en/loop.md](docs/guide/en/loop.md) | [guide/zh/loop.md](docs/guide/zh/loop.md) |
|
|
53
|
+
| Dream (nightly health scan) | [guide/en/dream.md](docs/guide/en/dream.md) | [guide/zh/dream.md](docs/guide/zh/dream.md) |
|
|
54
|
+
| Peer (cross-agent review) | [guide/en/peer.md](docs/guide/en/peer.md) | [guide/zh/peer.md](docs/guide/zh/peer.md) |
|
|
55
|
+
| Skill selection guide | [guide/en/skills.md](docs/guide/en/skills.md) | [guide/zh/skills.md](docs/guide/zh/skills.md) |
|
|
56
|
+
| Domain model (DDD) | [domain/context-map.md](docs/domain/context-map.md) | — |
|
|
57
|
+
| Engineering common sense | [practices/engineering-common-sense.md](docs/practices/engineering-common-sense.md) | — |
|
|
64
58
|
|
|
65
|
-
|
|
59
|
+
---
|
|
66
60
|
|
|
67
|
-
Commands
|
|
61
|
+
## Commands
|
|
68
62
|
|
|
69
63
|
| Command | Description |
|
|
70
64
|
|---------|-------------|
|
|
71
|
-
| `roll setup [-f]` | First-time install
|
|
72
|
-
| `roll update` |
|
|
73
|
-
| `roll init` |
|
|
74
|
-
| `roll status` | Show sync state, skill links,
|
|
75
|
-
| `roll backlog` | Show
|
|
76
|
-
| `roll
|
|
77
|
-
| `roll
|
|
78
|
-
| `roll
|
|
79
|
-
| `roll
|
|
80
|
-
| `roll release` | 🤖 Sync changelog + version bump + tag + npm publish + GitHub Release |
|
|
81
|
-
| `roll` _(no args, in project dir)_ | Dashboard: loop status, pending count, latest brief summary |
|
|
82
|
-
|
|
83
|
-
### Typical Flow
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
# 1. Install on this machine
|
|
87
|
-
npm install -g @seanyao/roll
|
|
88
|
-
roll setup
|
|
89
|
-
|
|
90
|
-
# 2. Initialize a project (run from project root)
|
|
91
|
-
cd my-app
|
|
92
|
-
roll init
|
|
93
|
-
|
|
94
|
-
# 3. Upgrade to a new release
|
|
95
|
-
roll update
|
|
96
|
-
|
|
97
|
-
# 4. Enable autonomous evolution (optional)
|
|
98
|
-
roll loop on # three services: loop (hourly) + dream (nightly) + brief (daily)
|
|
99
|
-
roll loop monitor # real-time top-like dashboard
|
|
100
|
-
roll brief # read the latest digest
|
|
101
|
-
|
|
102
|
-
# 5. Switch agent per project
|
|
103
|
-
roll agent use kimi # all 🤖 commands now use kimi for this project
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
### How Convention Layering Works
|
|
107
|
-
|
|
108
|
-
```
|
|
109
|
-
Global ~/.claude/CLAUDE.md ← user-owned; roll setup appends @roll.md
|
|
110
|
-
~/.claude/roll.md ← Roll conventions (written by roll setup/sync)
|
|
111
|
-
↓ auto-stacked
|
|
112
|
-
Project <project>/AGENTS.md ← generated by roll init
|
|
113
|
-
<project>/.claude/CLAUDE.md
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
Global conventions are additive and never overwrite existing files. Project conventions are injected per project via `roll init`.
|
|
117
|
-
|
|
118
|
-
### Directory Layout
|
|
119
|
-
|
|
120
|
-
```
|
|
121
|
-
~/.roll/
|
|
122
|
-
├── config.yaml # sync path configuration
|
|
123
|
-
└── conventions/
|
|
124
|
-
├── global/ # single source of truth
|
|
125
|
-
│ ├── AGENTS.md
|
|
126
|
-
│ ├── CLAUDE.md / GEMINI.md / .cursor-rules
|
|
127
|
-
└── templates/ # project type templates
|
|
128
|
-
├── fullstack/
|
|
129
|
-
├── frontend-only/
|
|
130
|
-
├── backend-service/
|
|
131
|
-
└── cli/
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
---
|
|
135
|
-
|
|
136
|
-
## Skill System
|
|
137
|
-
|
|
138
|
-
Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in `~/.roll/skills/` and are symlinked into each AI client's skill directory on `roll setup`.
|
|
139
|
-
|
|
140
|
-
### Workflow
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
Research → Design → Build → Check → Fix → (loop)
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
### Quick Reference
|
|
147
|
-
|
|
148
|
-
| Scenario | Skill |
|
|
149
|
-
|----------|-------|
|
|
150
|
-
| Uncertain approach, need to think it through | `$roll-design "topic"` |
|
|
151
|
-
| Execute a planned Story | `$roll-build US-001` |
|
|
152
|
-
| Free-form feature request | `$roll-build "add search to admin"` |
|
|
153
|
-
| Bug fix | `$roll-fix FIX-001` |
|
|
154
|
-
| Fast backlog capture (bug / idea) | `$roll-idea "description"` |
|
|
155
|
-
| High-risk logic (payments, auth, state machines) | `$roll-spar "feature"` |
|
|
156
|
-
| Deep research (product / company / tech) | `$roll-research "subject"` |
|
|
157
|
-
| Cross-agent code review | `$roll-peer` |
|
|
158
|
-
| Patrol production for regressions | `$roll-sentinel patrol` |
|
|
159
|
-
| Debug a broken page | `$roll-debug <URL>` |
|
|
160
|
-
| Record a dev moment / diary entry | `$roll-notes "just fixed that nasty bug"` |
|
|
161
|
-
| Let the agent work overnight | `roll loop on` |
|
|
162
|
-
|
|
163
|
-
### Full Skill List
|
|
164
|
-
|
|
165
|
-
**Loop A — Research & Design**
|
|
166
|
-
|
|
167
|
-
| Skill | Description |
|
|
168
|
-
|-------|-------------|
|
|
169
|
-
| `$roll-research` | HV Analysis (Horizontal-Vertical) deep research framework, outputs PDF report |
|
|
170
|
-
| `$roll-design` | Multi-turn discuss → [peer review] → DDD model → solution design → [peer review] → write Stories to BACKLOG |
|
|
171
|
-
|
|
172
|
-
**Loop B — Implementation & Iteration**
|
|
173
|
-
|
|
174
|
-
| Skill | Description |
|
|
175
|
-
|-------|-------------|
|
|
176
|
-
| `$roll-build` | Universal entry: Story ID, fix ID, or free-text fly mode. TCR-driven micro-commits |
|
|
177
|
-
| `$roll-spar` | Adversarial TDD — Attacker writes tests, Defender writes code |
|
|
178
|
-
| `$roll-fix` | Bug fix / hotfix from BACKLOG |
|
|
179
|
-
| `$roll-release` | One-command publish: auto version (YYYY.MMDD.N) → tag → npm publish → GitHub Release |
|
|
180
|
-
| `$roll-peer` | Cross-agent code review — Claude / Kimi / DeepSeek / Codex bilateral negotiation |
|
|
181
|
-
|
|
182
|
-
**Loop C — Observability & Maintenance**
|
|
183
|
-
|
|
184
|
-
| Skill | Description |
|
|
185
|
-
|-------|-------------|
|
|
186
|
-
| `$roll-sentinel` | Randomized production patrol with adaptive hot-spot weighting |
|
|
187
|
-
| `$roll-debug` | Deep page diagnostics + root cause analysis (Black Box probe) |
|
|
188
|
-
|
|
189
|
-
**Autonomous Evolution (optional, via `roll loop on`)**
|
|
190
|
-
|
|
191
|
-
| Skill | Description |
|
|
192
|
-
|-------|-------------|
|
|
193
|
-
| `$roll-loop` | Hourly BACKLOG executor — routes US/FIX/REFACTOR to the right skill, enforces TCR |
|
|
194
|
-
| `$roll-.dream` | Nightly code health scan — dead code, architectural drift → REFACTOR entries |
|
|
195
|
-
| `$roll-brief` | Owner-facing digest — what's done, what's pending, release readiness verdict |
|
|
196
|
-
|
|
197
|
-
**Passive Support**
|
|
198
|
-
|
|
199
|
-
| Skill | Description |
|
|
200
|
-
|-------|-------------|
|
|
201
|
-
| `$roll-.review` | Pre-commit multi-dimensional self code review |
|
|
202
|
-
| `$roll-.qa` | Test pyramid and coverage standards reference |
|
|
203
|
-
| `$roll-.changelog` | Auto-generate CHANGELOG from BACKLOG |
|
|
204
|
-
| `$roll-.echo` | Passive intent clarification |
|
|
205
|
-
| `$roll-.clarify` | Passive scope clarification for vague build requests |
|
|
206
|
-
| `$roll-idea` | Fast capture a bug or idea into BACKLOG.md |
|
|
207
|
-
| `$roll-notes` | Project diary — append dev moments to `notes/YYYY-MM-DD.md` |
|
|
208
|
-
| `$roll-doctor` | One-command dev toolchain health check |
|
|
209
|
-
|
|
210
|
-
---
|
|
211
|
-
|
|
212
|
-
## Autonomous Evolution
|
|
213
|
-
|
|
214
|
-
Off by default. Enable with `roll loop on` to let the agent work unattended on your project.
|
|
215
|
-
|
|
216
|
-
```
|
|
217
|
-
┌─────────────────────────────────────────────────────────┐
|
|
218
|
-
│ Base layer (always active) │
|
|
219
|
-
│ $roll-design → $roll-build → $roll-fix → $roll-spar │
|
|
220
|
-
│ Human drives every action │
|
|
221
|
-
├─────────────────────────────────────────────────────────┤
|
|
222
|
-
│ Autonomous layer (opt-in: roll loop on) │
|
|
223
|
-
│ roll-loop — hourly BACKLOG executor │
|
|
224
|
-
│ roll-.dream — nightly code health scan │
|
|
225
|
-
│ roll-brief — daily morning digest + release readiness │
|
|
226
|
-
│ Human reviews briefs; retains sole release authority │
|
|
227
|
-
└─────────────────────────────────────────────────────────┘
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
Three services are scheduled via macOS launchd (Linux: crontab) and managed as a unit:
|
|
231
|
-
|
|
232
|
-
- **roll-loop** runs hourly, picks up `📋 Todo` items from BACKLOG, routes them (`US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`), and enforces TCR discipline — if a story completes with zero `tcr:` micro-commits, it reverts to Todo with an ALERT.
|
|
233
|
-
- **roll-.dream** runs nightly, scanning for dead code, architectural drift, and refactoring opportunities. Outputs `REFACTOR-XXX` entries to BACKLOG.
|
|
234
|
-
- **roll-brief** runs each morning (or on-demand via `roll brief`), producing an owner-facing digest with a release-readiness verdict.
|
|
235
|
-
|
|
236
|
-
The autonomous layer **never** invokes `roll-release`. Production deployment is always a human decision.
|
|
237
|
-
|
|
238
|
-
Use `roll loop monitor` for a real-time `top`-like view of all three services: launchd status, current execution state, pending queue, alerts, and live log tail.
|
|
239
|
-
|
|
240
|
-
Per-project agent configuration: `roll agent use <name>` writes `.roll.yaml` so each project can use a different AI client (claude / kimi / deepseek / pi / codex / opencode). Lookup order: `.roll.yaml` → `~/.roll/config.yaml` → `claude` (default).
|
|
241
|
-
|
|
242
|
-
---
|
|
243
|
-
|
|
244
|
-
## Project Structure (`roll init`)
|
|
245
|
-
|
|
246
|
-
```
|
|
247
|
-
my-project/
|
|
248
|
-
├── AGENTS.md # Project constraints & skill routing
|
|
249
|
-
├── BACKLOG.md # Story and bug index
|
|
250
|
-
├── docs/features/ # Story details and specs
|
|
251
|
-
└── ... your project files
|
|
252
|
-
```
|
|
65
|
+
| `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
|
|
66
|
+
| `roll update` | Upgrade to latest version |
|
|
67
|
+
| `roll init` | Initialize project: AGENTS.md + BACKLOG.md + docs/features/ |
|
|
68
|
+
| `roll status` | Show sync state, skill links, detected AI tools |
|
|
69
|
+
| `roll backlog` | Show pending tasks from BACKLOG.md |
|
|
70
|
+
| `roll loop <on\|off\|now\|status\|monitor>` | 🤖 Manage autonomous executor |
|
|
71
|
+
| `roll brief` | 🤖 Show latest owner digest |
|
|
72
|
+
| `roll peer` | 🤖 Cross-agent code review |
|
|
73
|
+
| `roll release` | 🤖 Version + tag + npm publish + GitHub Release |
|
|
253
74
|
|
|
254
75
|
---
|
|
255
76
|
|
|
256
77
|
## Contributing
|
|
257
78
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
1. Fork the repo and create a branch from `main`
|
|
261
|
-
2. Make your changes with tests where applicable (`tests/`)
|
|
262
|
-
3. Ensure `./bin/roll --help` output is correct
|
|
263
|
-
4. Open a pull request with a clear description
|
|
79
|
+
PRs welcome. Keep them focused on one thing. For larger changes, open an issue first.
|
|
264
80
|
|
|
265
|
-
|
|
81
|
+
1. `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
|
|
82
|
+
2. Make changes with bats tests (`tests/`)
|
|
83
|
+
3. Run `npm test` before pushing
|
|
266
84
|
|
|
267
85
|
---
|
|
268
86
|
|
|
269
87
|
## Acknowledgments
|
|
270
88
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework and schema used by `$roll-research` are derived from this project, used under the MIT License. Copyright (c) 2026 数字生命卡兹克.
|
|
274
|
-
- **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.
|
|
89
|
+
- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — HV Analysis framework used by `$roll-research`, MIT License.
|
|
90
|
+
- **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — composable skills library that inspired several Roll workflow patterns.
|
|
275
91
|
|
|
276
92
|
---
|
|
277
93
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
MIT
|
|
94
|
+
MIT License
|