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

中文版 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 GITHUB_TOKEN/GH_TOKEN or gh auth token when available; credentials are used only in request headers. GitHub requests respect HTTP_PROXY/HTTPS_PROXY/NO_PROXY when Node exposes the matching fetch dispatcher. CI, headless sessions, non-macOS hosts, sudo/root shells, offline downloads, or ROLL_SKIP_CAPTURE_INSTALL=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. ROLL_LANG=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):

• Delta Team (ordinary, host-guided) is the current host main session acting as the implicit Supervisor, plus host-native sub-agent sessions for the Designer, Builder, and Evaluator roles, driven through roll delta. The host requests and attests those sub-agents itself; Roll never spawns, resumes, or configures any session, including yours.
• Full Delta Team is an independently orchestrated multi-agent / multi-host topology that shares the same protocol but launches distinct role sessions through Roll's generic adapters.

Honest boundaries the protocol states and never overclaims:

• Terminal binding is Option C, handoff-only. A valid Evaluator report reaches only delta:terminal(handoff_ready) — not Done, a merge, an attest verdict, or a DeliveryRecord. The owner then manually runs the existing delivery/PR/attest procedure; Roll auto-binds nothing. Done still comes only from a PR merged into main.
• Host attestation is structural validation only — non-empty/unique opaque tokens that correspond across resolution/event/manifest. It never proves a fresh session, honored role/model, or actual model execution.
• Local preset (~/.roll/delta-team/presets.yaml) is host-local config, never project config.
• Host-guided cost is ? (host_unobservable) — never estimated, priced, or zeroed.

Every delegation has a Supervisor: a loop is a chain of cycles running inside a host session, so it has a main session and full sub-agent capability like any other delivery. There is one trigger axis value and no admission prohibition — any topology (solo / Delta Team / Full Delta Team) is available to a loop. See the roll-delta-team skill and guide/en/ai-agents.md for the full procedure.

Supervisor backlog-clearing standard

When the owner asks Roll to clear a backlog, Supervisor treats the scope as every live non-Hold FIX-*, US-*, and REFACTOR-* row unless the owner narrows it. Before scheduling another card it reconciles backlog status, open PRs, recent cycle endings, CI/evaluator gates, manual-merge PRs, and .roll meta state. Each card gets its own Builder and, when required by the execution profile, an independent Evaluator/Scorer selected from the current Agent roster. Repeated failure, zero TCR, missing PR/CI/evaluator evidence, parser failures, auth blocks, permission blocks, and [roll:manual-merge] PRs stop new scheduling and surface an owner action through roll supervisor status/next/why.

How work is driven

Roll has one way to drive delivery, over the same backlog, truth, route profile, execution profiles, evidence, Evaluator, and release gates:

• The session drives. The owner reads roll supervisor status/next/why and starts work in that session with roll loop go (optionally --epic <name> or --cards <id>). The agent session running it is the Supervisor. Nothing advances on its own — no timer, no resident process.

• Pause stops autonomous progress. roll loop pause stops cards from being picked; roll loop resume clears it. The correction circuit breaker also pauses automatically after repeated failures, so resume is the supported way back. An explicit one-shot (roll loop go --cards <id>) still runs while paused.

• Attest and evidence are story-scoped. A Story is accepted through its own Acceptance Review Page (latest/<id>-review.html), AC map, and screenshots/test artifacts. latest/<id>-report.html remains a legacy alias for one release cycle.

Agent bindings are declared in two files: ~/.roll/agents.yaml for Machine Scope and .roll/agents.yaml for Project Scope. A Project can inherit the machine pool and bind Story roles:

schema: roll-agents/v1
scope: project
inherits: machine
defaults:
  story:
    roles:
      execute:
        kind: select
        from: [kimi, codex, pi]
        require: [execute]
        strategy: first-available
      evaluate:
        kind: select
        from: [claude, codex, kimi, pi, agy, reasonix, cursor]
        require: [evaluate]
        strategy: health-aware

Runtime availability is explicit: if a candidate is not callable on the current machine because of auth, network, VPN, or account state, the current resolution records that limitation instead of rewriting the static pool. For open role casting, strategy: health-aware keeps the installed pool visible and ranks candidates by capability, recent health, successful deliveries, recent use, and cost band. Inspect a cast with roll supervisor route --role builder --story <id> [--json]; the trace lists every candidate, warnings, skipped facts, reasons, and the selected agent.

Onboarding Samples

Zero-start project

mkdir my-product && cd my-product
roll init
# In an interactive terminal, describe the requirement, point to a PRD,
# or let Roll write .roll/brief.md from detected notes.
roll next
roll design --from-file .roll/brief.md
roll loop go

Roll explains the next design step instead of inventing fake work. The Designer turns the requirement into Stories, the Supervisor chooses standard, verified, or designed execution, and the owner reviews story-scoped attest evidence.

Existing project

cd existing-codebase
roll init
roll next
roll init --apply        # after reviewing the generated onboard plan
roll loop go

Roll diagnoses the repository without destructive migration, writes or updates Roll metadata only after review, and then lets the Supervisor reason over existing backlog, docs, context, open PRs, and scoped role bindings. Current state is visible through CLI-first observability: roll status, roll loop watch, roll loop runs, roll loop cycle <id>, roll loop alert, and story reports.

Quick start for new projects

A new project needs a remote before the loop can push branches and open PRs:

cd your-project
roll init
# 1. Create a GitHub repository for the project and add it as `origin`
# 2. Push the current branch so the loop has somewhere to land work
git push -u origin main
# 3. Drive the backlog from this session
roll loop go

roll loop go will fail fast with an alert if the repository is missing or unreachable, so it never burns agent tokens against a broken push target. If you need to stop the loop, roll loop pause persists a pause marker; resume with roll loop resume when ready.

Commands

Command	Description
roll agent [migrate|list|cast]	Agent Scope, installed-agent inventory, and role casting
roll backlog [sync|block|defer|lint|…]	View, manage, lint, and sync pending tasks
roll config [lang|prices|tune|…]	Read/write configuration, model prices, and suggest-only tuning
roll design [--from-file <path>] [--agent <name>] [--verbose|--raw]	Launch $roll-design with bounded live progress, handoff, and an optional roll loop go --review auto continuation when new Todo cards are created
roll doctor [skills|tools|language|repair-protection]	Diagnose install health, skills, tools, permissions, language drift, and stale main-checkout write protection
roll help [--lang en|zh] [name]	View built-in Charter / guide docs; roll --help prints CLI usage
roll idea "<one-sentence description>"	Capture and classify a new backlog card
roll init	Diagnose this directory and route setup/onboarding
roll loop <on|off [--all]|go|watch|runs|cycles|cycle|alert|…>	Run, observe, stop, and maintain the autonomous executor
roll next	Continue init/onboard with one best next command
roll north [--json] [--no-color]	North-star terminal panel for autonomy, delivery rate, fix tax, and attribution errors
roll release [--dry-run|--showcase]	Release planning/flow plus golden-path showcase support
roll setup [-f|--force] [--reselect] [--no-capture-install] / roll setup skills|offboard	Install/sync conventions, repair Roll Capture.app readiness, or remove Roll-owned project artifacts
roll status [ci|pulse] [--json]	Project health, CI state, and delivery pulse
roll test [--where] [--reset]	Run tests through the isolation adapter
roll update	Upgrade the global Roll install and re-sync conventions
roll --version / roll -v	Print installed roll version

Retained support surfaces live under their owners: roll config prices, roll config tune, roll agent cast, roll doctor tools, roll status ci, roll status pulse, roll loop cycles, roll loop cycle, roll release showcase, and roll setup offboard. Historical top-level aliases for those capabilities now return the standard unknown-command response.

Observability Now

Roll's current observability is CLI-first. Persistent facts flow through one read path: anchors -> selectors -> adapter -> projections. roll status, roll loop watch, roll loop runs, roll loop cycle <id>, roll status pulse, and story-scoped attest reports are the current user-facing truth surfaces. Role and collaboration visibility are part of that same surface: roll loop cycle <id> --roles, roll loop cycle <id> --collab, roll loop cycle --legend, roll supervisor live --collab, and the Execution Cast report block expose selected/returned/accepted role outcomes. The archive rebuild is an on-demand archive and repair renderer for static HTML pages; it is not the active delivery truth surface.

• roll status starts with a compact North Star line. Read it as the same four roll north metrics in one row: autonomous runtime, delivery rate, fix tax, and attribution errors. A dot shows each metric's current state.
• roll north expands those readings into a 14-day panel. Targets are autonomous runtime >=72h, delivery rate >=60%, fix tax <1x, and attribution errors =0. The anti-gaming rules are part of the metric: an effective autonomous day needs at least 6 non-idle attempts, backlog-empty days pause the autonomy clock instead of counting against it, fix tax divides FIX work by US delivery only, and unknown attribution is not guessed. null means no usable data yet; the panel prints the reason.
• A backlog row is a claim; merge evidence on main and recorded acceptance evidence are truth. A premature ✅ Done claim is shown as drift.
• Failures are attributed as env, harness, card, or unknown. Repeated non-card root causes pause dispatch by root cause and write a diagnostic snapshot with a playbook. When you see dispatch paused, read the snapshot, repair the environment or Roll component named there, then resume. If a card was parked because old env/harness failures polluted skip accounting, use roll loop pardon-skip-list [--dry-run] [--include-unknown] to rebuild the skip list from runs and events.
• Builder cycles keep the main checkout physically read-only while the Builder runs. Dirty or ahead changes that leak into the main checkout are quarantined onto rescue/leaked-* refs with a manifest under .roll/loop/quarantine/. The manifest names the files and includes the restore command to claim the rescued work.
• Cycle history is read through the TerminalOutcome vocabulary, not legacy free-form summary text.
• Missing facts render as ?. A visible 0 means a known zero, not unknown.

Evidence gates are strict for merge. attest render failure, dangling ac-map.json paths, claimed AC statuses, and a non-exempt visual card with no captured screenshot can block merge. PR bodies carry a Roll-Evidence trailer so reviewers can jump to the story evidence. Run roll attest audit [--json] to find dangling evidence references and evidence_debt rows. See Acceptance evidence and Loop failure handling.

Visual evidence is best-effort: a visual AC is satisfied by either a Roll Capture · physical image or a target-bound Playwright · rendered receipt — a physical image is not the only thing that can satisfy it. Evidence health is one of four states: verified, degraded-infrastructure (capture machine broken — published, marked degraded, never rebuilt), invalid-target (blocks), or absent-contract (blocks). Receipts never include credentials, cookies, DOM, or network bodies, capture is window-scoped, and ROLL_NO_SCREENCAP bans only the runner's native path. Enable best-effort with the capability-gated, reversible roll capture migrate; repair a degraded record without reopening the build via roll capture repair <story-id>; and check readiness with roll doctor or roll capture status.

Behavior Roll cannot prove locally — a real npm i -g github:..., a published CLI's first run, a live OAuth callback — must declare an external-smoke or owner-attested verification path. The attest report shows an Outward verification banner: only a real smoke pass (or valid owner attestation) is green; verified-in-simulation (e.g. npm pack) and UNVERIFIED — external smoke not run are never green, so acceptance cannot overstate outward behavior. No real publish or account action ever runs without a declared authority. See Outward behavior verification.

roll supervisor live is the shipped CLI-first multi-role board. It prints a one-frame snapshot for scripts and quick inspection; roll supervisor live --watch keeps the same board open and redraws it in-place from the same event-backed view model. A browser/TUI Supervisor Live Console remains future work and must reuse that view model.

Repository layout

Dev side — a pnpm monorepo. Publish side — one npm package.

packages/      TypeScript engine (pnpm workspaces): spec · core · infra · cli · web
lib/           Runtime companions (prices snapshots, i18n catalog)
skills/        Git submodule → seanyao/roll-skills (the agent skill contracts)
conventions/   Conventions synced into AI clients by `roll setup`
template/      Project scaffolding installed by `roll init`

Build & test: pnpm install && pnpm -r test.

Published as a single npm package @seanyao/roll: dist/ (the CLI bundled to one self-contained ESM by esbuild) + lib/ + skills/ + conventions/ + template/.

Documentation

Start here	Getting started · Overview & architecture · Engineering methodology
Daily driving	The loop (autonomous executor) · Tools & policy · Browser operations (managed + interactive lanes; optional diagnostics are opt-in only) · Configuration · Pricing & cost · FAQ
Quality machinery	Acceptance evidence (roll attest) · Evidence lifecycle · Consistency & release gate · Cross-agent pairing · Peer review · Test isolation
Under the hood	Architecture: layers · domain · invariants · Verification system · Manifesto

Full guide index: guide/en/ — agents, peer review, feedback, backlog sync, adoption patterns, and more.

Contributing

See CONTRIBUTING.md for the development workflow, test setup, and PR conventions.

Security

See SECURITY.md. Please report vulnerabilities privately, not through public issues.

License

MIT