@seanyao/roll 2026.519.3 → 2026.520.1

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.
Files changed (11) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +37 -86
  3. package/bin/roll +545 -97
  4. package/conventions/global/AGENTS.md +3 -2
  5. package/lib/roll-peer.py +242 -0
  6. package/lib/roll_render.py +21 -0
  7. package/package.json +1 -1
  8. package/skills/roll-loop/SKILL.md +16 -8
  9. package/lib/__pycache__/model_prices.cpython-314.pyc +0 -0
  10. package/lib/__pycache__/roll-loop-status.cpython-314.pyc +0 -0
  11. package/lib/__pycache__/roll_render.cpython-314.pyc +0 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## v2026.520.1
4
+
5
+ ### Added
6
+
7
+ - **`roll offboard`** — 一键清掉项目里的 Roll 痕迹，先 dry-run 预览、二次确认才动手；命名空间对不上直接拒绝，绝不跨项目误删 `[legacy-onboard]`
8
+ - **`roll init` 现在认得出非典型布局的老项目** — 微信小程序、Python 平铺、Terraform 仓不再被当成空项目静默跳过引导 `[legacy-onboard]`
9
+ - **onboard / offboard 用户指南** — 完整接入与退出流程文档上线，遗留项目页"怎么退出"段从手动 rm 改为指向新命令 `[docs]`
10
+
11
+ ### Improved
12
+
13
+ - **公开 README 重写为给使用者看的** — 中英文 README 去掉自我推销语言，围绕安装 + 使用展开，新增贡献指南与漏洞报告说明 `[docs]`
14
+ - **markdown 改动不再绕过 CI** — 文档量减下来之后，关键文档改动现在和代码一样要过 CI `[ci]`
15
+ - **onboard 留下回退清单** — onboard 完事会记下动过哪些文件、在 AGENTS.md 哪段合并、加了哪些 launchd 调度，作为 offboard 的精准回退依据 `[legacy-onboard]`
16
+
17
+ ### Fixed
18
+
19
+ - **loop 跑过 45 分钟预算时不再卡死** — watchdog 现在能稳定收掉超时的 claude，下一轮按时启动 `[loop]`
20
+ - **loop worktree 里能看到主仓最新 backlog** — 每轮启动会先把主仓 `.roll/` 同步进 worktree，不再因为 meta 滞后让 loop 拿到旧待办 `[loop]`
21
+
3
22
  ## v2026.519.3
4
23
 
5
24
  ### Major
package/README.md CHANGED
@@ -7,8 +7,6 @@
7
7
  ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚══════╝
8
8
  ```
9
9
 
10
- > _Agents, roll out._
11
-
12
10
  **[中文版 README](README_CN.md)**
13
11
 
14
12
  [![Website](https://img.shields.io/badge/Website-seanyao.github.io%2Froll-blue)](https://seanyao.github.io/roll/)
@@ -16,123 +14,76 @@
16
14
  [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
17
15
  [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
18
16
 
19
- ---
20
-
21
- ## What is Roll?
22
-
23
- 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.
24
-
25
- **Two core values:**
26
- 1. **Autonomous delivery** — `roll loop on` runs BACKLOG items hourly; Dream (nightly code-health scan) surfaces maintenance tasks; humans retain sole release authority
27
- 2. **Skill-driven execution** — 20+ skills encode TDD, TCR, and INVEST practices as reliable, repeatable workflows any agent can follow
28
-
29
- _Works with Claude, Cursor, Codex, or your own agent._
30
-
31
- ## What's New in 2.0 (May 2026)
32
-
33
- Roll 2.0 introduces a **process/product split** to keep open-source projects clean:
34
-
35
- - **`.roll/` directory convention** — all process artifacts (backlog, features, briefs, dream logs) move out of root into `.roll/`. User-facing `guide/` and `site/` move up to root. Old `docs/` directory disappears.
36
- - **`roll migrate`** — one-command migration for projects on pre-2.0 layout. `git mv` preserves history, single atomic commit, three-state idempotent.
37
- - **`$roll-onboard`** — interactive skill for adopting Roll on legacy codebases without rewrites. AI reads your code, asks 9 questions in ≤ 3 minutes, produces a plan; `roll init --apply` executes it.
38
- - **Three adoption patterns** — `seed` (new project), `graft` (legacy, non-invasive), `replant` (legacy, clean rebuild). See [guide/en/patterns/](guide/en/patterns/).
39
-
40
- ## Evolution
41
-
42
- Roll didn't start as a framework. It started as a question: *what if the AI didn't just write code, but actually shipped it?*
43
-
44
- Early versions just pushed engineering conventions to whichever AI tool you were running. Then came multi-agent support — Kimi, DeepSeek, Codex, Trae — and `roll-peer`, which let one AI challenge another's decisions before anything landed on `main`.
45
-
46
- The real shift was `roll loop`: stories running back-to-back without human prompting, `roll-.dream` filing its own refactor tickets after nightly scans, the system generating its own work queue. What followed was building enough trust to leave it running overnight — worktree isolation, CI + AI review double gates, real-time visibility into what the agent was actually doing.
17
+ Roll — a CLI that lets AI agents pick up backlog items and ship them through your normal git + CI workflow. Works with Claude, Cursor, Codex, Kimi, and others.
47
18
 
48
- The goal from here: full delivery, end to end — with humans on the loop, not in it.
49
-
50
- ---
51
-
52
- ## Quick Start (30 seconds)
19
+ ## Install
53
20
 
54
21
  ```bash
55
22
  npm install -g @seanyao/roll
56
- roll setup # distribute conventions to all AI clients
57
- cd my-project
58
- roll init # create AGENTS.md + .roll/backlog.md + .roll/features/
59
- roll loop on # optional: let the agent work unattended
23
+ roll setup
60
24
  ```
61
25
 
62
- **Requirements:** bash 4+, Node.js 16+
63
-
64
- ---
65
-
66
- ## Adoption Paths
67
-
68
- Three ways to bring Roll into a project. Not sure which fits? Just run `roll init` — it detects legacy code and routes you to `$roll-onboard` automatically.
69
-
70
- | Path | When to use | How to start |
71
- |------|-------------|--------------|
72
- | **Seed** | Brand-new project, starting from zero | `roll init` (the Quick Start path above) |
73
- | **Graft** | Existing codebase, keep current workflow intact | `roll init` → AI prompts `$roll-onboard` → 9 questions in ≤ 3 min → `roll init --apply` |
74
- | **Replant** | Existing codebase, ready to realign on Roll conventions | Same as Graft, choose "clean rebuild" during onboarding |
26
+ Requirements: bash 4+, Node.js 16+.
75
27
 
76
- Details: [seed](guide/en/patterns/seed-pattern.md) · [graft](guide/en/patterns/graft-pattern.md) · [replant](guide/en/patterns/replant-pattern.md)
28
+ ## Use
77
29
 
78
- ---
79
-
80
- ## Documentation Index
81
-
82
- | Topic | English | 中文 |
83
- |-------|---------|------|
84
- | Overview & architecture | [guide/en/overview.md](guide/en/overview.md) | [guide/zh/overview.md](guide/zh/overview.md) |
85
- | Engineering methodology | [guide/en/methodology.md](guide/en/methodology.md) | [guide/zh/methodology.md](guide/zh/methodology.md) |
86
- | Loop (autonomous executor) | [guide/en/loop.md](guide/en/loop.md) | [guide/zh/loop.md](guide/zh/loop.md) |
87
- | Dream (nightly health scan) | [guide/en/dream.md](guide/en/dream.md) | [guide/zh/dream.md](guide/zh/dream.md) |
88
- | Peer (cross-agent review) | [guide/en/peer.md](guide/en/peer.md) | [guide/zh/peer.md](guide/zh/peer.md) |
89
- | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
90
- | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
91
- | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
92
- | Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
93
- | Engineering common sense | [practices/engineering-common-sense.md](guide/en/practices/engineering-common-sense.md) | — |
30
+ ```bash
31
+ cd your-project
32
+ roll init # set up Roll here
33
+ roll loop on # let AI work through the backlog (optional)
34
+ ```
94
35
 
95
- ---
36
+ `roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
96
37
 
97
38
  ## Commands
98
39
 
99
40
  | Command | Description |
100
41
  |---------|-------------|
101
42
  | **Autonomy · daily use** | |
102
- | `roll loop <on\|off\|now\|status\|monitor>` | 🤖 Manage the autonomous BACKLOG executor |
103
- | `roll brief` | 🤖 Show latest owner brief |
104
- | `roll backlog [block\|defer\|…]` | View and manage pending tasks |
105
- | `roll peer` | 🤖 Cross-agent negotiation & review |
43
+ | `roll loop <on\|off\|now\|status\|monitor>` | Manage the autonomous BACKLOG executor |
44
+ | `roll brief` | Show latest owner brief |
45
+ | `roll backlog [block\|defer\|lint\|…]` | View and manage pending tasks |
46
+ | `roll peer` | Cross-agent negotiation & review |
106
47
  | `roll alert` | View / clear loop alerts |
107
48
  | **Project · per repo** | |
108
- | `roll init` | Create AGENTS.md + .roll/backlog.md + .roll/features/ |
49
+ | `roll init` | Set up Roll in this project |
109
50
  | `roll status` | Show current state and drift |
110
- | `roll agent [use <name>]` | Per-project agent selection (Claude / Cursor / Codex / Kimi / …) |
51
+ | `roll agent [use <name>]` | Per-project agent selection |
111
52
  | `roll ci [--wait]` | Show or wait for current commit's CI status |
112
- | `roll release` | 🤖 Run the release script (human-only) |
113
- | `roll review-pr <number>` | 🤖 AI-powered code review for a PR |
53
+ | `roll release` | Run the release script (human-only) |
54
+ | `roll review-pr <number>` | AI-powered code review for a PR |
114
55
  | **Machine · global** | |
115
56
  | `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
116
57
  | `roll update` | Upgrade to latest + re-sync |
117
58
  | `roll version` | Print installed roll version |
118
59
 
119
- ---
60
+ ## Documentation
61
+
62
+ | Topic | English | 中文 |
63
+ |-------|---------|------|
64
+ | Overview & architecture | [guide/en/overview.md](guide/en/overview.md) | [guide/zh/overview.md](guide/zh/overview.md) |
65
+ | Engineering methodology | [guide/en/methodology.md](guide/en/methodology.md) | [guide/zh/methodology.md](guide/zh/methodology.md) |
66
+ | Loop (autonomous executor) | [guide/en/loop.md](guide/en/loop.md) | [guide/zh/loop.md](guide/zh/loop.md) |
67
+ | Dream (nightly health scan) | [guide/en/dream.md](guide/en/dream.md) | [guide/zh/dream.md](guide/zh/dream.md) |
68
+ | Peer (cross-agent review) | [guide/en/peer.md](guide/en/peer.md) | [guide/zh/peer.md](guide/zh/peer.md) |
69
+ | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
70
+ | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
71
+ | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
72
+ | Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
120
73
 
121
74
  ## Contributing
122
75
 
123
- PRs welcome. Keep them focused on one thing. For larger changes, open an issue first.
76
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, test setup, and PR conventions.
124
77
 
125
- 1. `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
126
- 2. Make changes with bats tests (`tests/`)
127
- 3. Run `npm test` before pushing
78
+ ## Security
128
79
 
129
- ---
80
+ See [SECURITY.md](SECURITY.md). Please report vulnerabilities privately, not through public issues.
130
81
 
131
82
  ## Acknowledgments
132
83
 
133
84
  - **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — HV Analysis framework used by `$roll-research`, MIT License.
134
85
  - **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — composable skills library that inspired several Roll workflow patterns.
135
86
 
136
- ---
87
+ ## License
137
88
 
138
- MIT License
89
+ [MIT](LICENSE)