@seanyao/roll 0.5.0 → 2.602.1

package/conventions/templates/cli/CLAUDE.md

@@ -4,10 +4,9 @@
 
 ## Stack
 
-- Node.js / TypeScript
-- CLI framework: commander or citty
-- Testing: Vitest + execa (CLI integration tests)
-- Distribution: npm package with bin entry
+- Runtime / Language: {e.g. Node.js / TypeScript, Go, Python, Bash}
+- Test framework: {e.g. Vitest, pytest, bats}
+- Distribution: {e.g. npm, Homebrew, binary release}
 
 ## Claude Code Notes
 
@@ -15,4 +14,3 @@
 - Test commands by running them in Bash, not just unit tests.
 - Use `$roll-design` to plan command structure and options before implementation.
 - Verify `--help` output is clear and complete for each command.
-- Run `npm run build && node dist/index.js --help` before pushing.

package/conventions/templates/cli/GEMINI.md

@@ -1,6 +1,6 @@
-# Project Preferences — CLI Tool (Gemini CLI)
+# Project Preferences — CLI Tool (Antigravity)
 
-> Extends global GEMINI.md + project AGENTS.md.
+> Extends global GEMINI.md (Antigravity) + project AGENTS.md.
 
 ## Stack
 
@@ -8,7 +8,7 @@
 - CLI framework: commander or citty
 - Testing: Vitest
 
-## Gemini Notes
+## Antigravity (agy) Notes
 
 - No server, no frontend. CLI tool only.
 - Test commands by running them, not just unit tests.

package/conventions/templates/cli/project_rules.md

@@ -0,0 +1,16 @@
+# Project Preferences — CLI Tool (Trae IDE)
+
+> Extends global project_rules.md + project AGENTS.md.
+
+## Stack
+
+- Node.js / TypeScript
+- CLI framework: commander or citty
+- Testing: Vitest
+
+## Trae Notes
+
+- No server, no frontend. CLI tool only.
+- Test commands by running them, not just unit tests.
+- Run `npm run build && node dist/index.js --help` before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

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

@@ -1,71 +1,36 @@
 # 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.
-
-## Frontend
-
-- 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
-
+> Reference for skills to infer frontend 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. 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.
+
+## 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
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Testing**: Unit (hooks/logic) >80%, E2E (Playwright).
+- **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/frontend-only/GEMINI.md

@@ -1,13 +1,13 @@
-# Project Preferences — Frontend Only (Gemini CLI)
+# Project Preferences — Frontend Only (Antigravity)
 
-> Extends global GEMINI.md + project AGENTS.md.
+> Extends global GEMINI.md (Antigravity) + project AGENTS.md.
 
 ## Stack
 
 - React + shadcn/ui + Tailwind CSS + Vite
 - Testing: Vitest + Playwright
 
-## Gemini Notes
+## Antigravity (agy) Notes
 
 - No backend in this project. All data via external API consumption.
 - Run `npm run build` to verify production bundle compiles before pushing.

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

@@ -0,0 +1,14 @@
+# Project Preferences — Frontend Only (Trae IDE)
+
+> Extends global project_rules.md + project AGENTS.md.
+
+## Stack
+
+- React + shadcn/ui + Tailwind CSS + Vite
+- Testing: Vitest + Playwright
+
+## Trae Notes
+
+- No backend in this project. All data via external API consumption.
+- Run `npm run build` to verify production bundle compiles before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/conventions/templates/fullstack/AGENTS.md

@@ -1,87 +1,39 @@
 # 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.
-
-## Frontend
-
-- 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
-
+> Reference for skills to infer fullstack 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. Stack
+- **Frontend**: React 18+ / TS / Vite / Tailwind / shadcn/ui.
+- **Backend**: Node.js REST API.
+- **Structure**: `src/domains/{domain}/` for DDD. `api/` for backend.
+
+## 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
+## 4. Discipline
+- **TCR**: Mandatory.
+- **Testing**: Unit >80%, E2E for critical flows.
+- **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/fullstack/CLAUDE.md

@@ -13,5 +13,5 @@
 
 - Use `$roll-design` to plan features that span frontend and backend.
 - When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
-- Use worktree isolation for parallel frontend/backend Actions in `$roll-story-build`.
+- Use worktree isolation for parallel frontend/backend Actions in `$roll-build`.
 - Run `npm run build` to verify both frontend and backend compile before pushing.

package/conventions/templates/fullstack/GEMINI.md

@@ -1,6 +1,6 @@
-# Project Preferences — Fullstack Web (Gemini CLI)
+# Project Preferences — Fullstack Web (Antigravity)
 
-> Extends global GEMINI.md + project AGENTS.md.
+> Extends global GEMINI.md (Antigravity) + project AGENTS.md.
 
 ## Stack
 
@@ -8,7 +8,7 @@
 - Backend: Node.js API (Express/Hono/Fastify)
 - Testing: Vitest (unit) + Playwright (E2E)
 
-## Gemini Notes
+## Antigravity (agy) Notes
 
 - When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
 - Run `npm run build` to verify both frontend and backend compile before pushing.

package/conventions/templates/fullstack/project_rules.md

@@ -0,0 +1,15 @@
+# Project Preferences — Fullstack Web (Trae IDE)
+
+> Extends global project_rules.md + project AGENTS.md.
+
+## Stack
+
+- Frontend: React + shadcn/ui + Tailwind CSS + Vite
+- Backend: Node.js API (Express/Hono/Fastify)
+- Testing: Vitest (unit) + Playwright (E2E)
+
+## Trae Notes
+
+- When modifying API contracts, update both `api/types.ts` and `src/shared/types/` in the same commit.
+- Run `npm run build` to verify both frontend and backend compile before pushing.
+- Follow the project AGENTS.md for architecture constraints and Roll workflow.

package/lib/README.md

@@ -0,0 +1,42 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/ — Python helpers and i18n runtime
+
+Python scripts and shell libraries that `bin/roll` delegates to for rendering-heavy or data-processing tasks.
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `roll-loop-status.py` | Renders the `roll loop status` health dashboard — reads cycle event NDJSON, computes per-cycle rows, daily rollups, and phase-tracing breakdown |
+| `roll-loop-story.py` | Per-story rollup: aggregates cycles, tokens, cost, and PR outcomes for `roll loop story <ID>` |
+| `roll-status.py` | Renders the `roll status` one-screen sync health view |
+| `roll-init.py` | Init-flow helpers called by `roll init` |
+| `roll-setup.py` | Setup-flow helpers (convention sync, tool config write) |
+| `roll-brief.py` | Brief generation: reads cycle records and produces the feature brief |
+| `roll-backlog.py` | Backlog read/write helpers |
+| `roll-peer.py` | Peer review coordination helpers |
+| `roll-help.py` | Renders `roll --help` output |
+| `roll-plan-validate.py` | Validates plan files before story execution |
+| `model_prices.py` | List-price table for AI model API pricing (per MTok, native currency) |
+| `prices_fetcher.py` | Fetches fresh price snapshots from vendor APIs |
+| `roll_render.py` | Shared rendering utilities (tables, color, formatting) |
+| `loop-fmt.py` | Loop log formatter (ANSI-strip, timestamp alignment) |
+| `loop_unstick.py` | Diagnostic: detects and unsticks hung loop state |
+| `backfill-pi-usage.py` | Backfills pi/deepseek token and cost data into existing cycle records |
+| `changelog_audit.py` | Audits CHANGELOG.md against backlog entries |
+| `i18n.sh` | Shell wrapper that delegates i18n string lookups to `lib/i18n/` |
+| `slides-render.py` | Renders `.deck.md` → HTML slides |
+| `slides-validate.py` | Validates deck file syntax and asset references |
+
+## Sub-directories
+
+- `agent_usage/` — token-usage capture and cost attribution per agent invocation
+- `i18n/` — localized string tables for all CLI output (EN + ZH)
+- `prices/` — price snapshot JSON files (per-vendor, dated)
+- `slides/` — slide component library for `roll deck`
+
+## Dependencies
+
+Imported by `bin/roll` via subprocess calls (`python3 lib/<script>.py`).
+No third-party pip dependencies — standard library only (json, sys, os, re, datetime).

package/lib/agent_usage/README.md

@@ -0,0 +1,49 @@
+# Adding a New Agent Usage Plugin
+
+5-step checklist for adding token/cost extraction for a new agent.
+
+## 1. Create plugin file
+
+```bash
+cp lib/agent_usage/pi.py lib/agent_usage/<agent>.py
+```
+
+Implement `extract(stdin_lines: list[str]) -> dict | None`.
+
+## 2. Register in `__init__.py`
+
+In `lib/agent_usage/__init__.py`, add one entry to `_PLUGINS`:
+
+```python
+_PLUGINS = {
+    "pi": ".pi",
+    "<agent>": ".<agent>",  # ← add this line
+}
+```
+
+The key must match `ROLL_LOOP_AGENT` env var (e.g. `kimi`, `deepseek`).
+
+## 3. Capture sample output
+
+Run a real cycle with the agent and save the stdout to a fixture:
+
+```bash
+roll loop test 2>&1 | tee tests/fixtures/<agent>_output_sample.txt
+```
+
+Or capture from a real cycle log.
+
+## 4. Write unit tests
+
+See `tests/unit/agent_usage_pi.bats` for reference. Test:
+- Happy path: fixture produces valid dict (all required fields non-None)
+- Edge case: empty lines, missing cost, unmatchable format → returns None
+- Round-trip: known token counts match fixture
+
+## 5. Run tests
+
+```bash
+npm test
+```
+
+That's it — no changes to `loop-fmt.py` or any other file.

package/lib/agent_usage/__init__.py

@@ -0,0 +1,108 @@
+"""
+agent_usage — plugin registry for extracting token/cost usage from
+non-claude agent stdout.
+
+Contract
+--------
+Each plugin module exports a single function:
+
+    def extract(stdin_lines: list[str]) -> dict | None:
+        '''Parse agent stdout lines and return structured usage data.
+
+        Returns None if the format wasn't recognized (caller falls back
+        to null payload — fully backward-compatible with US-LOOP-010).
+
+        Return dict shape:
+            {
+                "model": str,           # e.g. "deepseek-v4-pro"
+                "input_tokens": int,    # never None
+                "output_tokens": int,   # never None
+                "cost_list_usd": float, # never None
+                "duration_ms": int | None,
+            }
+        '''
+
+Adding a new agent
+------------------
+1. Create ``lib/agent_usage/<agent>.py`` implementing ``extract()``
+2. Register it here by adding one entry to ``REGISTRY``
+3. Add a fixture file under ``tests/fixtures/<agent>_output_sample.txt``
+4. Add unit tests in ``tests/unit/agent_usage_<agent>.bats``
+5. Run ``npm test`` to verify no regressions
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Callable, Dict, Optional
+
+_log = logging.getLogger(__name__)
+
+# Registry: agent name → extract function
+# Agent names match ROLL_LOOP_AGENT env var values (e.g. "pi", "deepseek", "kimi").
+REGISTRY: Dict[str, Callable] = {}
+
+
+def _lazy_import(module_name: str) -> Optional[Callable]:
+    """Import a plugin module and return its extract function, or None on failure."""
+    try:
+        mod = importlib.import_module(module_name)
+        extract = getattr(mod, "extract", None)
+        if extract is None:
+            _log.warning("agent_usage plugin %s has no extract() function", module_name)
+            return None
+        if not callable(extract):
+            _log.warning("agent_usage plugin %s.extract is not callable", module_name)
+            return None
+        return extract
+    except Exception:
+        _log.warning("agent_usage plugin %s failed to load", module_name, exc_info=True)
+        return None
+
+
+# Populate REGISTRY from known plugins
+_PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
+_PLUGINS = {
+    # agent name → python module name (relative to this package)
+    "pi": ".pi",
+    "openai": ".openai",
+    "gemini": ".gemini",
+    "kimi": ".kimi",
+    "qwen": ".qwen",
+}
+
+for _agent, _mod_suffix in _PLUGINS.items():
+    _extract = _lazy_import(__package__ + _mod_suffix)
+    if _extract is not None:
+        REGISTRY[_agent] = _extract
+
+
+def extract_usage(agent: str, stdin_lines: list[str]) -> Optional[dict]:
+    """Look up agent in REGISTRY and call its extract().
+
+    Returns None if agent not registered, plugin not loadable, or
+    extract() returns None / raises an exception.  The caller falls
+    back to the null-payload passthrough path (US-LOOP-010 compatible).
+    """
+    extract_fn = REGISTRY.get(agent)
+    if extract_fn is None:
+        return None
+    try:
+        result = extract_fn(stdin_lines)
+        if result is None:
+            return None
+        # Validate required fields
+        for key in ("model", "input_tokens", "output_tokens", "cost_list_usd"):
+            if result.get(key) is None:
+                _log.warning(
+                    "agent_usage plugin %s returned None for required field %r",
+                    agent, key,
+                )
+                return None
+        return result
+    except Exception:
+        _log.warning(
+            "agent_usage plugin %s raised during extract()", agent, exc_info=True,
+        )
+        return None