@seanyao/roll 2026.424.2 → 2026.424.3

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.424.2"
+VERSION="2026.424.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"

package/conventions/global/AGENTS.md

@@ -1,100 +1,24 @@
-# 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.
+
+## 2. Code
+- **TS**: Strict, no `any`. Functional hooks. Early returns.
+- **Git**: No force-push main. No `--no-verify`. No secrets in git.
+- **Behavior**: No unrelated refactoring. No speculative abstractions.
+
+## 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
+- **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.
+- **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
+- **Done**: Push + CI passes + deployed. Local-only is not done.

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

@@ -1,88 +1,27 @@
 # 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.
+> Reference for skills to infer backend project conventions.
 
-## API Design
+## 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.
 
-- 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
+## 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
-
-- `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.
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Security**: Input validation (zod), Rate limiting, Secrets rotation.
+- **Workspace**: `BACKLOG.md` + `docs/features/`.

package/conventions/templates/cli/AGENTS.md

@@ -1,66 +1,29 @@
 # 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.
+> Reference for skills to infer CLI project conventions.
 
-## Design Principles
+## 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.
 
-- 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
+## 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
-
-- `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.
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Distribution**: `bin` in `package.json`, test `npm i -g`.
+- **Workspace**: `BACKLOG.md` + `docs/features/`.

package/conventions/templates/frontend-only/AGENTS.md

@@ -1,71 +1,26 @@
 # Project Conventions — Frontend Only
 
-> Project-type-specific conventions — reference material for skills.
-> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+> Reference for skills to infer frontend project conventions.
 
-## Frontend
+## 1. Stack
+- **Core**: React 18+ / TS / Vite / Tailwind / shadcn/ui.
+- **State**: React state (simple), Zustand/Jotai (complex), TanStack Query (server).
+- **Structure**: `src/domains/{domain}/` for DDD.
 
-- Stack: React 18+ / TypeScript / Vite / Tailwind CSS / shadcn/ui / Lucide React
-- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
-- `src/components/ui/` is shadcn-generated — never edit manually.
-- `src/components/[feature]/` for custom feature components.
-- Tailwind utility classes only. No inline styles, no CSS modules.
-- Organize by domain: `src/domains/{domain}/components/`, `hooks/`, `services/`, `types.ts`
-- Shared utilities in `src/shared/` (api/, types/, utils/, hooks/).
-
-## Architecture
-
-- **Domain Driven Design**: organize code by business domain, not technical layer.
-- **Clean Architecture**: UI → Application (hooks) → Domain (services) → Infrastructure (API client).
-- **Decoupling**: UI renders only, logic lives in hooks. API calls wrapped in services.
-- **Data Schema First**: define types/schemas before writing business logic.
-- No backend code in this project. API consumption only.
-
-## State Management
-
-- Prefer React built-in state (useState, useReducer, useContext) for simple cases.
-- Use a state library (Zustand, Jotai) only when shared state gets complex.
-- Server state via TanStack Query (React Query) for API data fetching and caching.
-
-## Project Structure
+## 2. Architecture
+- **DDD**: Logic in hooks/services, not components.
+- **Decoupling**: UI renders only, logic in hooks.
+- **Data**: Define schemas before logic.
 
+## 3. Structure
 ```
 src/
-├── components/ui/        # shadcn/ui (generated, don't edit)
-├── domains/              # DDD by business domain
-│   └── {domain}/
-│       ├── components/   # domain-specific UI
-│       ├── hooks/        # domain logic + state
-│       ├── services/     # API client calls
-│       └── types.ts      # domain types
-├── shared/
-│   ├── api/              # HTTP client, interceptors
-│   ├── types/            # shared type definitions
-│   └── utils/            # utility functions
-├── App.tsx
-└── main.tsx
-
-tests/
-├── unit/                 # Vitest + Testing Library
-└── e2e/                  # Playwright
+├── components/ui/   # shadcn (don't edit)
+├── domains/         # DDD components/hooks/services
+└── shared/          # api/types/utils
 ```
 
-## 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). "I confirmed it works" is not evidence.
-- **Complete delivery**: push to GitHub + CI passes + deployed online. Local-only done is not done.
-
-## Testing Requirements
-
-- All hooks and domain logic must have unit tests (Vitest + Testing Library, coverage >80%).
-- Critical user flows must have E2E tests (Playwright).
-- Run existing tests before pushing to verify no regressions.
-
-## 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.
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Testing**: Unit (hooks/logic) >80%, E2E (Playwright).
+- **Workspace**: `BACKLOG.md` + `docs/features/`.

package/conventions/templates/fullstack/AGENTS.md

@@ -1,87 +1,29 @@
 # Project Conventions — Fullstack Web
 
-> Project-type-specific conventions — reference material for skills.
-> **Note: Reference Template** — used by skills to infer project conventions. Not selected by users.
+> Reference for skills to infer fullstack project conventions.
 
-## Frontend
+## 1. Stack
+- **Frontend**: React 18+ / TS / Vite / Tailwind / shadcn/ui.
+- **Backend**: Node.js REST API.
+- **Structure**: `src/domains/{domain}/` for DDD. `api/` for backend.
 
-- Stack: React 18+ / TypeScript / Vite / Tailwind CSS / shadcn/ui / Lucide React
-- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
-- `src/components/ui/` is shadcn-generated — never edit manually.
-- `src/components/[feature]/` for custom feature components.
-- Tailwind utility classes only. No inline styles, no CSS modules.
-- Organize by domain: `src/domains/{domain}/components/`, `hooks/`, `services/`, `types.ts`
-- Shared utilities in `src/shared/` (api/, types/, utils/, hooks/).
-
-## Backend
-
-- RESTful API conventions. Consistent URL structure: `/api/{resource}/{id}`.
-- Structured error responses: `{ error: string, code: string, details?: object }`.
-- Environment-based config via `.env`. Never hardcode secrets.
-- Folder structure:
-  - `src/routes/` or `api/routes/` — route handlers
-  - `src/services/` or `api/services/` — business logic
-  - `src/models/` or `api/models/` — data models and schemas
-- Health check endpoint: `GET /api/health`
-- Authentication: JWT in httpOnly cookies.
-
-## Architecture
-
-- **Domain Driven Design**: organize code by business domain, not technical layer.
-- **Clean Architecture**: UI → Application (hooks) → Domain (services) → Infrastructure (API/DB).
-- **Decoupling**: UI renders only, logic lives in hooks. API calls wrapped in services.
-- **Data Schema First**: define types/schemas before writing business logic.
-- **Frontend-Backend Contract**: API changes must sync `shared/types/`. Errors use unified format.
-
-## Project Structure
+## 2. Architecture
+- **DDD**: Logic in hooks/services, not components.
+- **Contract**: API changes must sync `shared/types/`.
+- **Data**: Define schemas before logic.
 
+## 3. Structure
 ```
 src/
-├── components/ui/        # shadcn/ui (generated, don't edit)
-├── domains/              # DDD by business domain
-│   └── {domain}/
-│       ├── components/   # domain-specific UI
-│       ├── hooks/        # domain logic
-│       ├── services/     # API calls
-│       └── types.ts      # domain types
-├── shared/
-│   ├── api/              # HTTP client, interceptors
-│   ├── types/            # shared type definitions
-│   └── utils/            # utility functions
-├── App.tsx
-└── main.tsx
-
+├── components/ui/   # shadcn (don't edit)
+├── domains/         # DDD components/hooks/services
+└── shared/          # api/types/utils
 api/
-├── routes/               # RESTful route handlers
-├── services/             # business logic
-├── models/               # data models
-└── types.ts              # API contract types
-
-schema/                   # data contract definitions
-tests/
-├── unit/                 # Vitest
-├── e2e/                  # Playwright
-└── regression/           # Sentinel regression
+├── routes/          # thin handlers
+└── services/        # business logic
 ```
 
-## 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.
-
-## Testing Requirements
-
-- All business logic must have unit tests (coverage >80%).
-- All API endpoints must have integration tests — no DB mocks, use real database.
-- Critical user flows must have E2E tests (Playwright).
-- New architecture introductions (State/Cache/EventBus) must have data flow integration tests.
-- Sentinel will periodically regression-test completed Stories.
-
-## 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.
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Testing**: Unit >80%, E2E for critical flows.
+- **Workspace**: `BACKLOG.md` + `docs/features/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.424.2",
+  "version": "2026.424.3",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

package/template/AGENTS.md

@@ -1,80 +1,26 @@
-# Project Agents Configuration
+# Agent Conventions
 
-## Workspace Configuration
+> Project template. Customize section 5 with project-specific rules.
 
-### Plan Documents Location
-**All Plan documents must be stored under the project directory. Writing to the `.kimi/` directory is prohibited.**
+## 1. Communication
+- User's language. Code/Git/Comments: English. UI: Chinese.
+- Concise. No summaries/code-walking. Outcomes only.
 
-```yaml
-# Plan file storage configuration
-plans:
-  base_dir: docs/plans/          # Relative to the project root
-  auto_create: true              # Auto-create directory if it doesn't exist
-  naming_convention: "{topic}.md" # Naming convention
-```
+## 2. Standards
+- **TS**: Strict, no `any`. Functional hooks.
+- **Test**: Unit >80%, E2E for flows. No WIP commits.
+- **Done**: Push + CI passes + deployed. Local-only is not done.
 
-**Rules:**
-1. **Preferred location**: `{project_root}/docs/plans/`
-2. **Auto-create**: If `docs/plans/` doesn't exist, create the directory automatically
-3. **Prohibited location**: Absolutely no writing to `~/.kimi/` or any global config directory
-4. **Non-project Plans**: Only allowed to use a temporary location when there is no project context
+## 3. Roll Workflow
+- **Design**: `$roll-design` -> Stories -> `BACKLOG.md`
+- **Build**: `$roll-build` / `$roll-fix` -> TCR (Green=Commit, Red=Revert)
+- **Patrol**: `$roll-sentinel` periodic + `$roll-debug` on failure
+- **Workspace**: `BACKLOG.md` index. `docs/features/<feat>.md` for details.
 
-**Examples:**
-- ✅ `my-project/docs/plans/auth-system.md`
-- ✅ `my-project/docs/plans/api-redesign.md`
-- ❌ `~/.kimi/skills/some-plan.md`
-- ❌ Any global location outside the project
+## 4. Architecture
+- **Schema First**: Define types before logic.
+- **Domain Driven**: Organize by business domain, not tech layer.
+- **Decoupling**: UI renders only. Logic in hooks/services.
 
-## Workflow
-
-### Design → $roll-design
-- Solution exploration, architecture design
-- Split into Stories
-- Write to BACKLOG.md
-
-### Build → $roll-build / $roll-fix
-- Read BACKLOG and execute
-- TCR development (independent Actions auto-parallelized + Worktree isolation)
-- CI/CD deployment
-
-### Check → $roll-sentinel / $roll-debug
-- Sentinel: Scheduled patrol
-- $roll-debug: Deep diagnosis
-
-### Fix → $roll-fix / $roll-design
-- Fix issues
-- Or re-plan
-
-## Architecture Constraints
-
-### Agent First
-- System designed for AI Agents
-- Agent is the primary user
-- UI is only a supplementary interface
-
-### Data Schema
-- Clear data structure definitions
-- Type/Schema is the contract between humans and Agents
-- Define Schema first, then write business logic
-
-### Domain Driven
-- Model by business domain
-- Not database table design
-- Help Agents understand the business
-
-### Decoupling Rules
-- UI layer only handles rendering; logic lives in Hooks
-- API calls encapsulated in services/
-- Shared types placed in shared/types/
-
-### Testing Requirements
-- All business logic must have unit tests
-- APIs have integration tests
-- Critical flows have E2E tests
-- Sentinel runs periodic regression tests
-
-## Conventions
-
-- All work tracked in BACKLOG.md
-- Sentinel patrols every 6 hours
-- TCR required for all changes
+## 5. Project Specifics
+<!-- Add project-specific stack, structure, and constraints. -->