{"id":49901103,"url":"https://github.com/seanyao/roll","last_synced_at":"2026-06-12T05:00:52.042Z","repository":{"id":351922888,"uuid":"1199782310","full_name":"seanyao/roll","owner":"seanyao","description":"Autonomous software delivery with AI agents — your BACKLOG runs itself, guided by encoded engineering discipline. No sprints, no hand-holding.","archived":false,"fork":false,"pushed_at":"2026-06-10T14:46:31.000Z","size":9379,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T15:24:08.546Z","etag":null,"topics":["ai","ai-agents","ai-coding","claude-code","claudecode","cli","codex-cli","conventions","developer-tools","engineering-workflow","kimi-cli","pi-cli","skills"],"latest_commit_sha":null,"homepage":"https://seanyao.github.io/roll/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seanyao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-02T17:48:01.000Z","updated_at":"2026-06-10T14:51:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/seanyao/roll","commit_stats":null,"previous_names":["seanyao/roll"],"tags_count":159,"template":false,"template_full_name":null,"purl":"pkg:github/seanyao/roll","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanyao%2Froll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanyao%2Froll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanyao%2Froll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanyao%2Froll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seanyao","download_url":"https://codeload.github.com/seanyao/roll/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seanyao%2Froll/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-coding","claude-code","claudecode","cli","codex-cli","conventions","developer-tools","engineering-workflow","kimi-cli","pi-cli","skills"],"created_at":"2026-05-16T06:24:39.818Z","updated_at":"2026-06-12T05:00:52.025Z","avatar_url":"https://github.com/seanyao.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n ██████╗  ██████╗ ██╗     ██╗     \n ██╔══██╗██╔═══██╗██║     ██║     \n ██████╔╝██║   ██║██║     ██║     \n ██╔══██╗██║   ██║██║     ██║     \n ██║  ██║╚██████╔╝███████╗███████╗\n ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝\n```\n\n**[中文版 README](README_CN.md)**\n\n[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2Froll-blue)](https://seanyao.github.io/roll/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)\n[![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)\n\nRoll — 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.\n\n## Install\n\n```bash\ncurl -fsSL https://seanyao.github.io/roll/install | bash\n```\n\n```bash\nnpm install -g @seanyao/roll\n```\n\nRequirements: Node.js ≥ 22. Roll is a self-contained TypeScript CLI — no runtime engine beyond node.\n\n## Use\n\n```bash\ncd your-project\nroll init           # set up Roll here\nroll loop on        # let AI work through the backlog (optional)\n```\n\n`roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.\nFirst time through? Start with [Getting started](guide/en/getting-started.md).\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| **Autonomy · daily use** | |\n| `roll loop \u003con\\|off\\|now\\|status\\|runs\\|log\\|story\\|events\\|eval\\|signals\\|alert\\|fmt\\|pr-inbox\\|mute\\|unmute\\|pause\\|resume\\|reset\\|gc\u003e` | Manage the autonomous BACKLOG executor (incl. per-cycle result scoring) |\n| `roll loop go [--epic \u003ce\u003e\\|--cards \u003cids\u003e] [--budget \u003cusd\u003e] [--for \u003cduration\u003e] [--review \u003cauto\\|hetero\\|self\\|off\u003e]` | Run goal mode manually until the scoped work completes, pauses, or hits a budget/usage/timebox guardrail; it can run while the scheduler is off, and a paused loop should be resumed first; final review defaults to `auto` |\n| `roll loop goal` | Show persisted goal scope, review mode, usage, limits, safety gate, and last decision |\n| `roll brief` | Show latest owner brief |\n| `roll backlog [sync\\|block\\|defer\\|lint\\|…]` | View, manage, and sync (from GitHub Issues) pending tasks |\n| `roll loop alert [list\\|ack\\|resolve\\|log]` | View / clear loop alerts |\n| `roll status` | Show current state and drift |\n| `roll doctor [skills]` | Environment + install diagnosis (agents, skill catalog, plists, launchd lanes) |\n| `roll tune [reset]` | Suggest-only self-tuning from loop trends — read-only, never auto-applies |\n| **Cards \u0026 evidence** | |\n| `roll idea \"\u003cone-sentence description\u003e\"` | Capture a card: auto-classify, number, lint, infer epic, mint the full story folder — the one user entry for adding cards |\n| `roll story new \u003cID\u003e --title \u003ct\u003e [--epic \u003ce\u003e] [--no-index]` | The one minting entry agents/skills use: card folder + backlog row + index refresh (`--no-index` for batches) |\n| **Project · per repo** | |\n| `roll init` | Set up Roll in this project (agent-driven onboarding for legacy code) |\n| `roll offboard` | Remove Roll from this project |\n| `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |\n| `roll ci [--wait]` | Show or wait for current commit's CI status |\n| `roll release [ship\\|waiver\\|changelog\\|consistency]` | Release guidance · changelog · consistency gate · gated tag push (`ship`) · recorded drift waiver (`waiver`) |\n| `roll release changelog generate [--write]` | Sync CHANGELOG from merged work |\n| `roll release consistency \u003ccheck\\|audit\u003e` | Five-dimension gap check · US-TRUTH shadow drift audit (read-only, exit 0) |\n| `roll pair [init\\|status]` | Cross-agent pairing: heterogeneous peer re-checks during builds |\n| `roll peer [--reviewer \u003cagent\u003e] (--prompt \u003ctext\u003e\\|--file \u003cpath\u003e)` | One-shot structured external-provider review; records `.roll/peer/runs.jsonl` |\n| **Config \u0026 machine** | |\n| `roll config [lang \u003czh\\|en\\|--reset\u003e\\|…]` | Read/write roll config (language, loop window, dream time) |\n| `roll agent [set \u003cslot\u003e \u003cagent\u003e\\|use \u003cname\u003e\\|list]` | Per-machine complexity-slot routing (easy/default/hard/fallback) |\n| `roll prices [refresh]` | Model price table (cost accounting source) |\n| `roll setup [skills\\|-f]` | First-time install, skill catalog generation, or re-sync conventions to all AI clients |\n| `roll update` | Upgrade to latest + re-sync |\n| `roll --version` / `roll -v` | Print installed roll version |\n\n## Truth Model In The UI\n\nThe Delivery Dossier is a truth projection, not a backlog mirror. Persistent\nfacts flow through one read path: anchors -\u003e selectors -\u003e adapter -\u003e\nprojections. `roll index` renders the front truth board from three aggregates:\nStory, Cycle, and Release.\n\n- A backlog row is a claim; merge evidence on `main` and recorded acceptance\n  evidence are truth. A premature `✅ Done` claim is shown as drift.\n- Cycle history is read through the TerminalOutcome vocabulary, not legacy\n  free-form summary text.\n- Missing facts render as `?`. A visible `0` means a known zero, not unknown.\n\n## Repository layout\n\nDev side — a pnpm monorepo. Publish side — one npm package.\n\n```\npackages/      TypeScript engine (pnpm workspaces): spec · core · infra · cli · web\nlib/           Runtime companions (prices snapshots, i18n catalog)\nskills/        Git submodule → seanyao/roll-skills (the agent skill contracts)\nconventions/   Conventions synced into AI clients by `roll setup`\ntemplate/      Project scaffolding installed by `roll init`\n```\n\nBuild \u0026 test: `pnpm install \u0026\u0026 pnpm -r test`.\n\nPublished as a single npm package `@seanyao/roll`: `dist/` (the CLI bundled to one self-contained ESM by esbuild) + `lib/` + `skills/` + `conventions/` + `template/`.\n\n## Documentation\n\n| | |\n|---|---|\n| **Start here** | [Getting started](guide/en/getting-started.md) · [Overview \u0026 architecture](guide/en/overview.md) · [Engineering methodology](guide/en/methodology.md) |\n| **Daily driving** | [The loop (autonomous executor)](guide/en/loop.md) · [Configuration](guide/en/configuration.md) · [Pricing \u0026 cost](guide/en/pricing.md) · [FAQ](guide/en/faq.md) |\n| **Quality machinery** | [Acceptance evidence (`roll attest`)](guide/en/acceptance-evidence.md) · [Evidence lifecycle](guide/en/acceptance-evidence.md#lifecycle-in-three-stages) · [Consistency \u0026 release gate](guide/en/consistency.md) · [Cross-agent pairing](guide/en/pairing.md) · [Peer review](guide/en/peer.md) · [Test isolation](guide/en/test-isolation.md) |\n| **Under the hood** | [Architecture: layers · domain · invariants](docs/architecture.md) · [Verification system](docs/verification.md) · [Manifesto](docs/manifesto.md) |\n\nFull guide index: [guide/en/](guide/en/) — agents, peer review, feedback, backlog sync, adoption patterns, and more.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, test setup, and PR conventions.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Please report vulnerabilities privately, not through public issues.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanyao%2Froll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseanyao%2Froll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseanyao%2Froll/lists"}