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

Roll out features with AI agents — Move fast, no sprints.

What is Roll?

Roll solves a specific problem: when developers on the same team use different AI clients (Claude Code, Cursor, Gemini CLI, Codex), each agent operates under different engineering constraints. One developer's Claude runs tests another's Cursor never even considers.

Roll fixes this through two mechanisms:

1. Convention CLI — a single source of engineering conventions distributed to every AI client on the machine (~/.claude/, ~/.cursor/, ~/.gemini/, etc.)
2. Skill System — proven engineering practices (TDD, TCR, SRE, INVEST) encoded as instructions that any AI agent can follow

The result: any agent, any client, same constraints.

Start Here

Before commands and skills, read the Engineering Methodology — it explains the three-loop architecture (Research → Build → Observe), why each skill exists, and how they connect into a complete delivery system.

English · 中文

Installation

npm install -g @seanyao/roll
roll setup

Requirements: bash 4+, Node.js 16+

To update:

roll update

For contributors (working on roll itself): git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh

Convention Management

Unified behavioral conventions for Claude Code / Gemini CLI / Cursor / Codex — all from one source.

Commands

| Command | Description | |---------|-------------| | roll setup | First-time install: create ~/.roll/ + sync to all AI tools | | roll update | Update roll to latest version + re-sync | | roll sync | Re-sync conventions and skill symlinks to all AI tools | | roll init | New project: create AGENTS.md + BACKLOG.md + docs/features/ | | roll hook install | Optional: global git hook for AI client auto-detection | | roll reset | Force-rebuild local cache from repo source, then re-sync | | roll status | Show sync state, skill links, and detected AI tools |

Typical Flow

# 1. Install
./install.sh

# 2. Initialize a project (run from project root)
cd my-app
roll init

# 3. Re-sync after editing ~/.roll/config.yaml
roll sync

# 4. Optional: tag commits with AI client name
roll hook install

How Convention Layering Works

Global  ~/.claude/CLAUDE.md         ← user-owned; roll setup appends @roll.md
        ~/.claude/roll.md            ← Roll conventions (written by roll setup/sync)
  ↓  auto-stacked
Project <project>/AGENTS.md         ← generated by roll init
        <project>/.claude/CLAUDE.md

Global conventions are additive and never overwrite existing files. Project conventions are injected per project via roll init.

Directory Layout

~/.roll/
├── config.yaml                  # sync path configuration
└── conventions/
    ├── global/                  # single source of truth
    │   ├── AGENTS.md
    │   ├── CLAUDE.md / GEMINI.md / .cursor-rules
    └── templates/               # project type templates
        ├── fullstack/
        ├── frontend-only/
        ├── backend-service/
        └── cli/

Skill System

Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in ~/.roll/skills/ and are symlinked into each AI client's skill directory on roll sync.

Workflow

Research → Design → Build → Check → Fix → (loop)

Quick Reference

| Scenario | Skill | |----------|-------| | Uncertain approach, need to think it through | $roll-design "topic" | | Execute a planned Story | $roll-build US-001 | | Free-form feature request | $roll-build "add search to admin" | | Bug fix | $roll-fix FIX-001 | | Fast backlog capture (bug / idea) | $roll-jot "description" | | High-risk logic (payments, auth, state machines) | $roll-spar "feature" | | Deep research (product / company / tech) | $roll-research "subject" | | Patrol production for regressions | $roll-sentinel patrol | | Debug a broken page | $roll-debug <URL> | | Record a dev moment / diary entry | $roll-notes "just fixed that nasty bug" |

Full Skill List

| Skill | Phase | Description | |-------|-------|-------------| | $roll-build | DESIGN+BUILD | Universal entry: Story ID, fix ID, or free-text fly mode | | $roll-design | DESIGN | Explore approaches → design solution → write Stories to BACKLOG | | $roll-fix | FIX | Bug fix / hotfix from BACKLOG | | $roll-jot | Support | Fast capture a bug or idea into BACKLOG.md | | $roll-spar | BUILD | Adversarial TDD — Attacker writes tests, Defender writes code | | $roll-sentinel | CHECK | Scheduled production patrol | | $roll-debug | CHECK | Deep page diagnostics + root cause analysis | | $roll-research | RESEARCH | HV Analysis framework, outputs PDF report | | $roll-release | RELEASE | One-command publish: auto version (YYYY.MMDD.N) → tag → npm publish | | $roll-.review | Support | Pre-commit self code review | | $roll-.qa | Support | Test pyramid and coverage standards reference | | $roll-.changelog | Support | Auto-generate CHANGELOG from BACKLOG | | $roll-.echo | Support | Passive intent clarification | | $roll-.clarify | Support | Passive scope clarification for vague build requests | | $roll-notes | Support | Project diary — append dev moments to notes/YYYY-MM-DD.md |

Project Structure (roll init)

my-project/
├── AGENTS.md            # Project constraints & skill routing
├── BACKLOG.md           # Story and bug index
├── docs/features/       # Story details and specs
└── ... your project files

Contributing

Contributions are welcome. Roll is a small focused tool — keep PRs focused on one thing.

1. Fork the repo and create a branch from main
2. Make your changes with tests where applicable (tests/)
3. Ensure ./bin/roll --help output is correct
4. Open a pull request with a clear description

For larger changes, open an issue first to discuss the approach.

Acknowledgments

Roll builds on ideas and inspiration from the open-source community:

• khazix-skills by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework that powers $roll-research was adapted from this project.
• superpowers by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.

License

MIT