seanyao/roll

 ██████╗  ██████╗ ██╗     ██╗     
 ██╔══██╗██╔═══██╗██║     ██║     
 ██████╔╝██║   ██║██║     ██║     
 ██╔══██╗██║   ██║██║     ██║     
 ██║  ██║╚██████╔╝███████╗███████╗
 ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝

中文版 README

Roll — a Supervisor-led CLI harness that routes AI agents through story-scoped planning, building, evaluation, git, CI, and acceptance evidence. Works with Claude, Cursor, Codex, Kimi, Pi, Reasonix, and other local rigs when they are available.

Install

curl -fsSL https://seanyao.github.io/roll/install | bash

npm install -g @seanyao/roll

Requirements: Node.js ≥ 22. Roll is a self-contained TypeScript CLI — no runtime engine beyond node. On macOS, npm installation also tries to install Roll Capture.app from the latest seanyao/roll-capture GitHub Release into ~/Applications so physical screenshots can run. If the release is private, the installer first tries anonymous GitHub access, then retries with GITHUBTOKEN/GHTOKEN or gh auth token when available; credentials are used only in request headers. GitHub requests respect HTTPPROXY/HTTPSPROXY/NOPROXY when Node exposes the matching fetch dispatcher. CI, headless sessions, non-macOS hosts, sudo/root shells, offline downloads, or ROLLSKIPCAPTUREINSTALL=1 skip this step without failing install; when skipped under sudo/root, re-run roll setup as a regular user so the app installs into that user's ~/Applications. roll setup and roll doctor tools report the same readiness and repair path.

Use

cd your-project
roll init           # set up Roll here (interactive confirmation)
roll next           # continue with design, apply, repair, migrate, loop, or status
roll loop go        # let AI work through the backlog in this session

roll init first diagnoses the current directory. Complete Roll projects get Already initialized and Next: roll status; partial Roll projects get roll init --repair, while pre-2.0 layouts get migration guidance without writing files. Existing codebases route to $roll-onboard. PRD/docs-only workspaces are treated as new projects: Roll writes .roll/brief.md from the detected document and points to roll design --from-file <detected-doc. Empty directories ask what you are building in an interactive terminal; in scripts and CI, plain roll init is read-only and roll init --auto writes a placeholder brief before pointing to roll design. For existing-codebase grafts, roll init --apply validates the generated artifacts, prints a review checkpoint with every planned file operation, and waits for owner confirmation before writing. Automation must use roll init --apply --auto after that review. After any init path, roll next is the continuation button: it reads the same brief, onboard plan, backlog, and Roll markers, then prints one best next command instead of a menu. When roll init writes Roll-owned meta files inside a git worktree, it also adds, commits, and pushes those files to origin when possible, then prints the commit/push result. Product files you created yourself are not included in that finalization commit. First time through? Start with Getting started.

Language Surfaces

Roll renders one visible language per user surface. ROLLLANG=en|zh pins the current process, roll config lang en|zh persists a preference, and roll config lang --reset returns to locale detection. roll help --lang en|zh is available for one-off guide/help reads, and roll doctor language audits docs, conventions, skills, and generated surfaces for mixed-language drift.

Agent contracts, code comments, git metadata, and TypeScript identifiers stay in English as the harness contract layer. Owner conversation follows the owner's language. User docs live in separate locale files under guide/en/ and guide/zh/; contributors should update the matching locale file or i18n catalog instead of placing translation pairs in the same rendered surface. Snapshot coverage for the current language controls lives in packages/cli/test/cli-language-surface.test.ts, packages/cli/test/snapshots/cli-language-surface.test.ts.snap, and packages/cli/test/doctor-language.test.ts.

V4 Supervisor Execution

Roll V4 separates project coordination from story delivery:

• Supervisor coordinates at project level: backlog order, cross-Story context, route advice, repeated failures, release readiness, budget, and owner escalation. It observes and advises; it does not implement a Story or override evidence gates.
• Delta Unit delivers one Story through scoped roles: design produces the Designer contract when the profile needs it, execute performs the Builder work, evaluate reviews/scores evidence, and supervise coordinates above the Story boundary.
• supervise / design / execute / evaluate roles are stable contracts. The concrete agent and optional model are resolved through the Agent Scope model: Scope - Role - Binding - Agent - Model.
• Skills remain the capability layer. Roles invoke $roll-design, $roll-build, $roll-fix, $roll-peer, $roll-.qa, and related skills instead of rewriting those contracts into TypeScript.
• Fallback is fail-loud. If a requested agent or rig is unavailable, Roll records that unavailability and pauses or asks for owner action; it does not silently pretend another agent was used.

Delta Team & Full Delta Team

Two named delivery topologies, distinct from each other and from the health-remediation delivery team (the FIX-routing target):