@seanyao/roll 0.5.0

package/README.md

@@ -0,0 +1,201 @@
+```
+ ██████╗  ██████╗ ██╗     ██╗     
+ ██╔══██╗██╔═══██╗██║     ██║     
+ ██████╔╝██║   ██║██║     ██║     
+ ██╔══██╗██║   ██║██║     ██║     
+ ██║  ██║╚██████╔╝███████╗███████╗
+ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝
+```
+
+> Roll out features with AI agents — _Move fast, no sprints._
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/roll.svg)](https://www.npmjs.com/package/roll)
+
+---
+
+## 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](docs/methodology-en.md)** · **[中文](docs/methodology.md)**
+
+---
+
+## Installation
+
+```bash
+npm install -g @seanyao/roll
+roll setup
+```
+
+**Requirements:** bash 4+, Node.js 16+
+
+To update:
+
+```bash
+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 |
+| `roll clean` | Remove legacy `~/.wukong/` or `~/.cybernetix/` remnants |
+
+### Typical Flow
+
+```bash
+# 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>` |
+
+### 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-.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 |
+
+---
+
+## 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](https://github.com/KKKKhazix/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](https://github.com/obra/superpowers)** by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.
+
+---
+
+## License
+
+MIT