@seanyao/roll 0.5.0 → 2.602.1

package/conventions/config.yaml

@@ -7,9 +7,25 @@
 sync_claude: ~/.claude/CLAUDE.md
 sync_kimi: ~/.kimi/AGENTS.md
 sync_codex: ~/.codex/AGENTS.md
-sync_gemini: ~/.gemini/GEMINI.md
+sync_agy: ~/.gemini/GEMINI.md   # Antigravity (agy) reuses the legacy ~/.gemini/ path
 
 # User preferences
 default_language: zh
 default_project_type: fullstack
 editor: ${EDITOR:-vim}
+
+# --- Advanced ---
+# Cross-machine loop record sync (optional).
+# Set to a private git remote URL to share cycle history across machines.
+# Each machine writes its own events file — no merge conflicts.
+# Private repo strongly recommended: cycle records contain prompt text,
+# file paths, and other potentially sensitive information.
+#
+# roll_records_remote: "git@github.com:you/roll-loop-records.git"
+
+# Remote monitoring (optional) — US-OBS-014.
+# Local checkout of your roll-meta repo. When set, each loop cycle end
+# auto-pushes a status snapshot via ops/push-loop-status.sh so the
+# remote-watch prompt always sees fresh data (no manual cron needed).
+# Path supports ~ expansion; a missing path logs one WARNING and is skipped.
+# roll_meta_dir: ~/projects/roll-meta

package/conventions/global/AGENTS.md

@@ -1,100 +1,146 @@
-# Global Agent Conventions — Sean Yao
-
-> Master conventions file. All AI coding agents follow these principles.
-> Tool-specific files (CLAUDE.md, GEMINI.md, .cursor-rules) extend this document.
-
-## Communication
-
-- Respond in the language I write in. Chinese message → Chinese response. English → English.
-- Code, commit messages, variable names, comments: always English.
-- Error messages in API responses: English.
-- UI-facing text: Chinese (internal tool for Chinese-speaking team).
-- Be concise. Don't summarize what you just did — I can read the diff.
-- Don't ask for confirmation on routine actions. Just do it and show the result.
-- If something is ambiguous, make a reasonable judgment call. Only ask when the choice has real consequences.
-- Use plain language. No academic jargon or pretentious framing.
-- **Roll workflow milestones may be narrated.** It's fine to report high-level progress such as running baseline, sketching a design, completing an Action, passing a Verification Gate, or finishing TCR (Green/Commit or Red/Revert).
-- **Implementation details are invisible.** Do not include code diffs, file paths, line numbers, function names, variable names, test scripts, model parameters, or raw git output in conversational responses.
-- **Strategic reasoning is okay; tactical code-walking is not.** You may explain *why* a design choice was made at the product/business level. Do not narrate step-by-step code modifications or internal debugging monologues.
-- **Report in user-centric outcomes.** After making changes, summarize what improved for the user or product in 1–2 sentences.
-- **No code dumps unless explicitly asked.** Never paste code snippets, stack traces, or technical speculations into the chat.
-- **Business context over technical mechanics.** When explaining a bug or fix, lead with the user-visible effect. Root causes, if mentioned at all, belong in a single trailing sentence.
-
-## Code Style
-
-- TypeScript strict mode. No `any` unless absolutely unavoidable.
-- Functional components with hooks. No class components.
-- Prefer `const` over `let`. Never `var`.
-- Early returns over nested conditionals.
-- Name things clearly — no abbreviations except well-known ones (e.g., `id`, `url`, `api`).
-- Keep functions short and single-purpose. If it needs a comment to explain, it's too complex.
-- Don't add comments unless the logic is genuinely non-obvious.
-- Don't add docstrings, JSDoc, or type annotations to code you didn't change.
-
-## Git
-
-- Conventional commit format: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`
-- Write in English, concise, imperative mood.
-- Never force push to main.
-- Never skip hooks (`--no-verify`).
-- Never commit `.env`, credentials, or secrets.
-
-## Behavior
-
-- Do not refactor files unrelated to the current task.
-- Do not add features, refactoring, or "improvements" not requested.
-- Always ask before making structural changes (directory reorganization, architecture changes).
-- Don't wrap simple things in abstractions. Three similar lines > a premature helper.
-- Don't add error handling for impossible scenarios. Trust the framework.
-- Delete unused things completely — no `// removed` comments, no backward-compat shims.
-- Don't create README.md or documentation files unless asked.
-
-## Testing
-
-- All business logic must have unit tests (coverage >80%).
-- All API endpoints must have integration tests — no DB mocks.
-- Critical user flows must have E2E tests (Playwright).
-- New architecture introductions (State/Cache/EventBus) must have data flow integration tests.
-- Run existing tests before pushing to verify no regressions.
-
-## Engineering Common Sense
-
-Non-negotiable requirements for all code changes. Violating these is a bug:
-
-- **Idempotency**: Same operation N times = same result. Test by running 3 times.
-- **Cross-module contract**: Shared IDs, formats, algorithms must be identical across modules.
-- **Data flow integrity**: Producer → Storage → Consumer chain must be complete and tested.
-- **Atomicity**: Operations complete fully or not at all. Partial failure → rollback.
-- **Input validation**: All external input (API, user, file) must be validated.
-- **Graceful degradation**: Dependency fails → limited functionality, not crash.
-- **Observability**: User must see progress, state, and errors.
-- **Concurrency safety**: Shared resources under multi-thread/multi-process access must be safe.
-
-## Roll Workflow (When Project Has It)
-
-When a project has Roll workflow configured:
-
-### Workspace Structure
-
-- `BACKLOG.md` = index table, one-line summary per story only.
-- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
-- `docs/features/<feature>-plan.md` = architecture design doc (optional).
-- Never write project docs to `~/.kimi/` or any global config directory.
-
-### Development Discipline
-
-- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
-- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
-- **Verification Gate**: Before marking done, provide fresh evidence (test output, screenshot, curl). "I confirmed it works" is not evidence.
-- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
-
-### Skill Selection
-
-```
-Uncertain approach?        → $roll-design
-Want to ship something?    → $roll-build  (handles US-XXX, FIX-XXX, or vague ideas)
-Single bug fix?            → $roll-fix
-High-risk logic?           → $roll-spar
-Page/production issue?     → $roll-debug
-Initialize new project?    → roll init  (CLI command, not a skill)
-```
+# Agent Conventions
+
+> Baseline for AI-agent-friendly projects. Extend with project-specific rules.
+
+## 1. Communication
+- User's language. Code/Git/Comments: English. UI: Chinese.
+- Concise. No summaries/code-walking. Implementation invisible.
+- Strategy (Why) OK; Tactics (How) NO. Outcomes only.
+- **Ambiguity resolution**: When user says "explicit" in automation contexts,
+  interpret as "logged/observable with clear output", NOT "requiring manual
+  intervention". Confirm with one question if uncertain.
+- **Voice**: Natural, colleague-like tone — neither robotic ("Executing…") nor over-enthusiastic ("Great!"). "Done — here's what changed." instead of "Task completed successfully." Consistent warmth for success and failure alike.
+- **Bilingual output**: EN + ZH on separate lines, never inline.
+  ```
+  Processing...
+  处理中...
+  ```
+  Not: `Processing... 处理中...`
+
+## 2. Code
+- **TS**: Strict, no `any`. Functional hooks. Early returns.
+- **Git**: No force-push main. No `--no-verify`. No secrets in git.
+- **Identity**: When you need the user's name or email, read it dynamically — `git config user.name` / `git config user.email`. **Never hardcode personal data** (names, emails, machine paths, personal repo URLs) into files that get committed or shipped via npm. Author/repo metadata in `package.json` is the only allowed exception.
+- **Behavior**: No unrelated refactoring. No speculative abstractions.
+- **File ops**: Prefer targeted edits over full file rewrites. Verify file exists before modifying.
+
+## 3. Engineering
+- **Idempotency**: Same op N times = same result.
+- **Atomicity**: Complete fully or rollback. No partial state.
+- **Validation**: All external input validated. Fail fast on startup.
+- **Testing**: Unit >80%. E2E for flows. No DB mocks.
+
+## 4. Workflow
+- **Scope Gate**: Only implement what is explicitly listed in the AC. Nothing more.
+  - Requests made in conversation are NOT AC — capture with `roll-idea` first.
+  - Any new Story/Fix requires design doc + user confirmation before TCR starts.
+  - Do not commit without user approval unless explicitly told to auto-commit.
+- **Goal First**: Before any implementation, state verifiable success criteria.
+  Transform vague tasks: "add validation" → "write test for invalid input, then make it pass".
+  Multi-step work: list steps with verify checkpoints (step → verify: how to check).
+  Weak criteria ("make it work") require human clarification before starting.
+- **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.
+  - Before implementing: confirm exact files, test strategy, and commit message
+    draft with user. Do not write code until approved.
+  - Before claiming completion: verify in the target environment mentioned by
+    user (e.g., specific CLI tool, remote server, hardware platform).
+- **Workspace**: `.roll/backlog.md` index. `.roll/features/` for details.
+- **Backlog descriptions** (US, FIX, REFACTOR, IDEA, PROPOSAL): one sentence in plain language.
+  Say what changed and why it matters — not how it works internally.
+  No file paths, function names, parameter lists, or architecture jargon.
+  `depends-on:` and `manual-only:` functional tags are allowed; `Domain:` annotation tags are not.
+  Technical details and AC go in `.roll/features/`.
+  A well-written BACKLOG description can be used directly as a CHANGELOG entry.
+- **Convention layering**: project-level convention files extend the global SOT — see §9 below.
+- **Done**: Push + CI passes + deployed. Local-only is not done.
+- **Post-push verification** (universal — applies to any push to main, regardless of which
+  skill drove the work):
+  - After every push, wait for the triggered CI run and verify status (`gh run watch`
+    or equivalent). Do not move on, switch tasks, or claim completion until CI is green.
+  - Before pushing any new code commit, verify the **previous** code-changing push's CI
+    is green. Never stack new code commits on top of a red CI (this is the failure
+    mode FIX-026 / `_loop_precheck_ci` exists to prevent for the loop — humans need
+    the same discipline). Every commit now triggers CI (US-POS-006 removed the
+    `paths-ignore` allow-list), so doc-only commits run CI too; treat their result
+    the same way as any other push.
+  - If CI is red, the next action is **fix or revert**, not "queue something else".
+- **Commit message format**:
+  - Format: `<type>: <description>` (Git Hook may auto-prepend type prefix)
+  - Types: `Story N`, `Fix`, `Refactor`, `Docs`, `Chore`
+  - TCR micro-commits use `tcr:` prefix instead
+
+## 5. Refactoring & Renames
+
+Project-wide renames require systematic checking. Never assume find/replace
+is sufficient. Execute in order:
+
+1. **Code references** — imports, function names, string literals
+2. **Documentation** — README, methodology, API docs
+3. **Config files** — YAML frontmatter, package names, manifests
+4. **Symlinks** — verify all resolve after rename
+5. **Installer scripts** — update paths and references
+6. **Shell environment** — remind user to reload or restart sessions
+
+Confirm each phase clean before proceeding to the next.
+
+## 6. Configuration & External Services
+- **Config file editing** (YAML/TOML/JSON with schema):
+  1. Find official documentation or a verified working example first
+  2. Do not guess syntax
+  3. If no docs found after 2 searches, ask user for a reference config
+  4. Maximum 2 syntax attempts before escalating to research mode
+- **External services** (npm publishing, proxy, auth-dependent deploy):
+  - Stop after 2 failed attempts and ask user for preferred fallback
+  - Do not continue iterating on auth/proxy debugging without explicit direction
+  - If OIDC/token issues persist, immediately fallback to manual with explanation
+
+## 7. Frontend Default Stack
+- React + shadcn/ui + Tailwind CSS is the default.
+- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
+- `components/ui/` is shadcn-generated — never edit manually.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+- Icons: Lucide React.
+
+## 8. Where to Look
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records
+- When `.roll/domain/` or `.roll/features/` don't exist yet, run `$roll-doc` to bootstrap.
+
+## 9. Convention Architecture
+
+Roll conventions form a two-layer hierarchy. The **global** layer is the single
+source of truth for **cross-project rules** — rules that apply regardless of
+stack, language, or domain (e.g., BACKLOG row format, identity, TCR rhythm,
+commit message format, scope discipline). The **project** layer carries only
+**project-specific** rules — stack, structure, build commands, domain
+conventions, deploy targets.
+
+**The contract:**
+
+1. Every project-level convention file **must declare it extends the global
+   counterpart** via a one-line foundation note at the top (e.g., "Extends
+   `~/.<agent>/AGENTS.md`" or "Extends AGENTS.md in this directory").
+2. Project-level files **never duplicate or re-state** cross-project rules.
+   When you find yourself wanting to copy a rule down, add a pointer instead.
+3. Cross-project rules go in `conventions/global/`. Project-specific rules go
+   in `conventions/templates/<type>/`. Anything that applies regardless of
+   stack belongs upstairs.
+
+**Layered file pairs** — each global ↔ project pair must follow the contract:
+
+| Global SOT | Project layer | Audience |
+|---|---|---|
+| `conventions/global/AGENTS.md` | `conventions/templates/<type>/AGENTS.md` | All agents |
+| `conventions/global/CLAUDE.md` | `conventions/templates/<type>/CLAUDE.md` | Claude Code |
+| `conventions/global/GEMINI.md` | `conventions/templates/<type>/GEMINI.md` | Antigravity (agy) — reads `~/.gemini/GEMINI.md` natively |
+| `conventions/global/project_rules.md` | `conventions/templates/<type>/project_rules.md` | Trae IDE |
+
+The CLAUDE / GEMINI / project_rules global files themselves declare they
+extend this AGENTS.md, so this section's rules apply transitively to all
+four file families.
+
+**Why it matters**: copies drift, pointers don't. When a rule must change, it
+changes in one place and propagates; if it's duplicated, half the copies get
+updated and the others silently lag — which is the failure mode that produced
+this section in the first place.

package/conventions/global/CLAUDE.md

@@ -3,30 +3,10 @@
 > Extends [AGENTS.md](./AGENTS.md) — read that first for shared conventions.
 > This file adds Claude Code-specific configuration only.
 
-## Identity
-
-- Git: `Sean Yao <sean.dlut@gmail.com>`
-- Default branch: `main`
-
-## Commit Message Format
-
-- Format: `<type>: <description>` (遵循 Git Hook 自动生成的前缀)
-- TCR micro-commits: `tcr: <description>` (No prefix)
-- Types: Story N, Fix, Refactor, Docs, Chore
-- Example: `Story 7: Review assignment by org structure`
-
 ## Claude Code-Specific
 
-- When a project has Roll skills, use them (`$roll-design`, `$roll-story`, etc.).
+- When a project has Roll skills, use them (`$roll-design`, `$roll-build`, `$roll-fix`, etc.).
 - Use plan mode for complex multi-step tasks before executing.
 - Prefer Edit tool over Bash for file modifications.
 - Use Agent tool with worktree isolation for parallel independent subtasks.
 - When I say "帮我看下" or "处理下", go ahead and do it, not just analyze it.
-
-## Frontend Default Stack
-
-- React + shadcn/ui + Tailwind CSS is the default.
-- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
-- `components/ui/` is shadcn-generated — never edit manually.
-- Tailwind utility classes only. No inline styles, no CSS modules.
-- Icons: Lucide React.

package/conventions/global/GEMINI.md

@@ -1,28 +1,14 @@
-# Global Preferences — Gemini CLI
+# Global Preferences — Antigravity (agy)
 
 > Extends AGENTS.md in this directory — read that first for shared conventions.
-> This file adds Gemini CLI-specific configuration only.
+> This file adds Antigravity-specific configuration only.
+>
+> File is named `GEMINI.md` because agy reads `~/.gemini/GEMINI.md` natively
+> (it reuses the legacy Gemini CLI config dir). The filename is the canonical
+> agy-side filename; the content here is for agy.
 
-## Identity
-
-- Git: `Sean Yao <sean.dlut@gmail.com>`
-- Default branch: `main`
-
-## Commit Message Format
-
-- Format: `<type>: <description>` (遵循 Git Hook 自动生成的前缀)
-- TCR micro-commits: `tcr: <description>` (No prefix)
-- Types: Story N, Fix, Refactor, Docs, Chore
-
-## Gemini-Specific
+## Antigravity-Specific
 
 - When running shell commands, prefer the most specific tool available.
-- For file operations, verify the file exists before modifying.
 - When a project has Roll workflow, follow the AGENTS.md conventions and use Roll skills.
-- Prefer targeted edits over full file rewrites.
-
-## Frontend Default Stack
-
-- React + shadcn/ui + Tailwind CSS is the default.
-- Use shadcn/ui components first. Custom only when shadcn doesn't cover it.
-- Tailwind utility classes only. No inline styles, no CSS modules.
+- Invoke interactively with `agy -i "<prompt>"`; non-interactive with `agy -p "<prompt>"`.

package/conventions/global/project_rules.md

@@ -0,0 +1,9 @@
+# Global Preferences — Trae IDE
+
+> Extends AGENTS.md in this directory — read that first for shared conventions.
+> This file adds Trae IDE-specific configuration only.
+
+## Trae-Specific
+
+- When a project has Roll workflow, follow the AGENTS.md conventions and use Roll skills.
+- Use Solo mode for complex multi-step tasks.

package/conventions/templates/backend-service/AGENTS.md

@@ -1,88 +1,37 @@
 # Project Conventions — Backend Service
 
-> Project-type-specific conventions — reference material for skills.
-> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
-
-## API Design
-
-- RESTful API with consistent URL structure: `/api/{resource}/{id}`.
-- For internal microservices, gRPC is acceptable.
-- Structured error responses: `{ error: string, code: string, details?: object }`.
-- Health check endpoint: `GET /api/health` returning `{ status: "ok", version: string }`.
-- API versioning via URL prefix (`/api/v1/`) when breaking changes are needed.
-
-## Configuration
-
-- Environment config via `.env`. Never hardcode secrets.
-- Use `.env.example` as the template with all required variables documented.
-- Validate all env vars at startup — fail fast if missing.
-- Separate configs for development, staging, production.
-
-## Logging
-
-- Structured JSON logging (e.g., pino, winston with JSON transport).
-- Log levels: `error`, `warn`, `info`, `debug`. Default to `info` in production.
-- Include correlation IDs for request tracing.
-- Never log secrets, tokens, or PII.
-
-## Error Handling
-
-- Domain errors: typed error classes with error codes.
-- HTTP errors: map domain errors to appropriate status codes.
-- Unhandled errors: catch-all middleware, log full stack, return 500 with safe message.
-- Validation errors: 400 with detailed field-level error messages.
-
-## Project Structure
-
+> Reference for skills to infer backend project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
+
+## 1. Design
+- **API**: RESTful `/api/{res}/{id}`. Structured JSON errors.
+- **Config**: `.env` (validate at start). Flags > Env > File.
+- **Logging**: Structured JSON (pino/winston). No secrets/PII.
+
+## 2. Architecture
+- **DDD**: Organize by business domain, not tech layer.
+- **Clean**: Routes (thin) -> Services (logic) -> Models (data).
+- **Database**: Migrations mandatory. Transactions for multi-table.
+
+## 3. Structure
 ```
 src/
-├── routes/               # HTTP route handlers (thin — delegate to services)
-├── services/             # business logic (pure functions where possible)
-├── models/               # data models, ORM entities, schemas
-├── middleware/            # auth, logging, error handling, validation
-├── utils/                # shared utilities
-├── types/                # TypeScript type definitions
-├── config/               # environment config, constants
-└── index.ts              # entry point, server bootstrap
-
-tests/
-├── unit/                 # service/model unit tests
-├── integration/          # API endpoint tests (supertest)
-└── regression/           # Sentinel regression
+├── routes/       # thin handlers
+├── services/     # business logic
+├── models/       # schemas/entities
+└── middleware/   # auth/log/error
 ```
 
-## Database
-
-- Migrations managed via a migration tool (Prisma, Drizzle, Knex).
-- Never modify production data manually — always through migrations.
-- Index frequently queried columns. Monitor slow queries.
-- Use transactions for multi-table operations.
-
-## Security
-
-- Input validation on all endpoints (zod, joi, or similar).
-- Rate limiting on public endpoints.
-- CORS configured explicitly — no wildcard in production.
-- Authentication middleware applied at route level, not globally.
-- Secrets rotated periodically. Never in git history.
-
-## Architecture Constraints
-
-- **Domain Driven**: organize code by business domain, not technical layer. `src/services/` contains domain logic, not generic utilities.
-- **Clean Architecture**: routes (thin) → services (business logic) → models (data) ← infrastructure (DB/external APIs). Routes delegate; they don't contain business logic.
-- **Data Schema First**: define types/schemas before writing business logic.
-- **API Contract**: typed request/response schemas. API changes must bump version or be backward-compatible.
-
-## Development Discipline
-
-- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
-- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
-- **Verification Gate**: Before marking done, provide fresh evidence (test output, curl response). "I confirmed it works" is not evidence.
-- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
-
-## Workspace Structure
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Security**: Input validation (zod), Rate limiting, Secrets rotation.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
-- `BACKLOG.md` = index table, one-line summary per story only.
-- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
-- `docs/features/<feature>-plan.md` = architecture design doc (optional).
-- Never write project docs to `~/.kimi/` or any global config directory.
+## 5. Where to Look
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records

package/conventions/templates/backend-service/GEMINI.md

@@ -1,6 +1,6 @@
-# Project Preferences — Backend Service (Gemini CLI)
+# Project Preferences — Backend Service (Antigravity)
 
-> Extends global GEMINI.md + project AGENTS.md.
+> Extends global GEMINI.md (Antigravity) + project AGENTS.md.
 
 ## Stack
 
@@ -8,7 +8,7 @@
 - Database: Prisma or Drizzle ORM
 - Testing: Vitest + Supertest
 
-## Gemini Notes
+## Antigravity (agy) Notes
 
 - No frontend in this project. API-only service.
 - Write integration tests that hit real endpoints, not mocked handlers.

package/conventions/templates/backend-service/project_rules.md

@@ -0,0 +1,16 @@
+# Project Preferences — Backend Service (Trae IDE)
+
+> Extends global project_rules.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript / Express or Hono or Fastify
+- Database: Prisma or Drizzle ORM
+- Testing: Vitest + Supertest
+
+## Trae Notes
+
+- No frontend in this project. API-only service.
+- Write integration tests that hit real endpoints, not mocked handlers.
+- Run `npm run build && npm run test` before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/cli/AGENTS.md

@@ -1,66 +1,39 @@
 # Project Conventions — CLI Tool
 
-> Project-type-specific conventions — reference material for skills.
-> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
-
-## Design Principles
-
-- Lightweight. No server, no frontend, no heavy frameworks.
-- Clear command structure: `tool <command> [options] [args]`.
-- Helpful error messages with actionable suggestions.
-- Consistent exit codes: 0 = success, 1 = user error, 2 = system error.
-- Support `--help` and `--version` on every command.
-- Respect `NO_COLOR` env var for output formatting.
-
-## Architecture
-
-- Single entry point dispatching to command handlers.
-- Each command in its own file — easy to find, easy to test.
-- Config loading: CLI flags > environment variables > config file > defaults.
-- Use a CLI framework (commander, yargs, or citty) for argument parsing.
-
-## Output
-
-- Default to human-readable output. Support `--json` for machine-readable.
-- Progress indicators for long operations (ora, cli-progress).
-- Errors to stderr, results to stdout.
-- Quiet mode (`--quiet` or `-q`) suppresses non-essential output.
-
-## Project Structure
-
+> Reference for skills to infer CLI project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
+
+## 1. Principles
+- **Lightweight**: No server/frontend.
+- **Commands**: `tool <cmd> [opts]`. One file per cmd in `src/commands/`.
+- **Exit Codes**: 0 success, 1 user error, 2 system error.
+
+## 2. Architecture
+- **Entry**: `src/index.ts` bootstrap.
+- **Config**: Flags > Env > File > Defaults.
+- **Output**: Human-friendly default, `--json` support. Errors to stderr.
+
+## 3. Structure
 ```
 src/
-├── index.ts              # entry point, CLI bootstrap
-├── commands/             # one file per command
-│   ├── init.ts
-│   ├── build.ts
-│   └── ...
-├── utils/                # shared utilities
-├── types/                # type definitions
-└── config.ts             # config loading logic
-
+├── index.ts      # bootstrap
+├── commands/     # handlers
+└── config.ts     # logic
 tests/
-├── unit/                 # command logic tests
-└── integration/          # full CLI invocation tests (execa)
+├── unit/         # logic
+└── integration/  # execa
 ```
 
-## Distribution
-
-- Compile to single executable or publish to npm.
-- Include `bin` field in `package.json`.
-- Test installation flow: `npm install -g` should work cleanly.
-- Include a man page or `--help` output that covers all commands.
-
-## Development Discipline
-
-- **TCR mandatory**: All code changes follow Test → Green = Commit / Red = Revert. No WIP commits.
-- **Action granularity**: Each Action independently deployable, completable in 2–5 min. No placeholders (no TBD/TODO/pending).
-- **Verification Gate**: Before marking done, run the actual command and paste the output. "I confirmed it works" is not evidence.
-- **Complete delivery**: push to GitHub + CI passes + published/deployed. Local-only done is not done.
-
-## Workspace Structure
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Distribution**: `bin` in `package.json`, test `npm i -g`.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
-- `BACKLOG.md` = index table, one-line summary per story only.
-- `docs/features/<feature>.md` = US details (AC, Files, Dependencies).
-- `docs/features/<feature>-plan.md` = architecture design doc (optional).
-- Never write project docs to `~/.kimi/` or any global config directory.
+## 5. Where to Look
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records