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

中文版 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 on        # let AI work through the backlog (optional)

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.

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.

Operating modes

Roll has two product modes over the same backlog, truth, route profile, execution profiles, evidence, Evaluator, and release gates:

• guided — the owner drives through roll supervisor status/next/why and starts work explicitly with commands such as roll loop go --cards <id>. Guided mode never silently starts long-running Story execution. When the scheduler is off, roll loop go runs a manual goal; when the loop is paused, use roll loop resume before scheduled work can continue.
• autonomous — roll loop on installs the scheduler; eligible Stories may be picked within the existing pause, budget, route, evidence, Evaluator, and release gates. roll loop pause / roll loop off return control to guided operation; roll loop off --all is the machine-wide emergency stop for every local com.roll.* LaunchAgent; roll loop resume / roll loop on switch back explicitly. If macOS launchd bootstrap fails, roll loop on exits unarmed and offers roll loop fallback start --confirm as an owner-confirmed, non-persistent fallback; repair launchd first when possible.
• 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 on

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 on

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. Start the autonomous loop
roll loop on

The loop 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.

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