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

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