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

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:

Convention CLI — a single source of engineering conventions distributed to every AI client on the machine (~/.claude/, ~/.cursor/, ~/.gemini/, etc.)
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.

Fork the repo and create a branch from main
Make your changes with tests where applicable (tests/)
Ensure ./bin/roll --help output is correct
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