@seanyao/roll 0.5.0 → 2.602.1

package/skills/roll-propose/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: roll-propose
+license: MIT
+allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
+description: |
+  Human-triggered product proposal generator. Reads project context (BACKLOG,
+  recent commits, existing skills) and generates 1–3 structured US drafts from
+  a user-facing perspective. Writes to .roll/proposals.md for human review — never
+  directly to BACKLOG. Distinct from roll-.dream (which surfaces technical debt
+  from execution experience); roll-propose thinks in user scenarios and feature
+  gaps.
+---
+
+# roll-propose
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+Human-triggered skill for product-level feature ideation. Generates structured
+User Story drafts from a product/user perspective and queues them in
+.roll/proposals.md for human approval before entering BACKLOG.
+
+## Distinct from roll-.dream
+
+| | roll-propose | roll-.dream |
+|---|---|---|
+| Triggered by | Human explicitly | Nightly schedule |
+| Perspective | User-facing / product scenarios | Code health / technical debt |
+| Output | .roll/proposals.md (pending approval) | BACKLOG (REFACTOR-XXX) |
+| Thinking style | "What would users want next?" | "What is the code telling us?" |
+
+## When to Use
+
+```
+$roll-propose                   # generate proposals from full context
+$roll-propose 用户反馈里提到了XX  # provide a focus hint
+```
+
+## When Not to Use
+
+- Describing a known defect or broken behavior (use `$roll-idea`)
+- A story is already well-defined and ready to build (use `$roll-build`)
+- Exploring technical architecture or design (use `$roll-design`)
+- Surfacing code-level technical debt (use `$roll-.dream`)
+
+## Behavior
+
+### Step 1 — Gather Context
+
+Read in parallel:
+
+1. `.roll/backlog.md` — all existing US-XXX, FIX-XXX, REFACTOR-XXX, IDEA-XXX entries (both Todo and Done) to avoid proposing duplicates
+2. `.roll/proposals.md` (if exists) — already-proposed items (avoid re-proposing rejected or pending ones)
+3. Recent 20 commits via `git log --oneline -20` — what has recently shipped
+4. `skills/` directory listing — what capabilities roll already has
+5. Optional: any focus hint passed by the user
+
+### Step 2 — Think from User Perspective
+
+Frame proposals from the **product engineer / end user** point of view:
+
+- What recurring friction do users of roll face that no current skill addresses?
+- What workflow is partially covered but has visible gaps?
+- What would make the autonomous loop more legible, controllable, or trustworthy to its human owner?
+
+Avoid technical-debt reasoning (that is roll-.dream's domain). Focus on:
+- New user-visible commands or behaviors
+- Improvements to existing UX (output clarity, discoverability, onboarding)
+- Integrations that extend reach (new AI tools, editor support, CI patterns)
+
+### Step 3 — Draft 1–3 Proposals
+
+Generate between 1 and 3 proposals. For each:
+
+```
+## PROPOSAL: {Short title}
+```
+
+`{Short title}` 写法：用户看得懂的一句话，说清楚"加什么"或"解决什么问题"。不用技术术语，不提内部实现。这句话批准后会直接成为 BACKLOG 里的描述。
+
+```
+**Motivation (why):**
+One to two sentences from the user's perspective explaining the pain or opportunity.
+
+**Target scenario:**
+Concrete usage example — what the user does, what they see, what they gain.
+
+**Acceptance Criteria (draft):**
+- [ ] AC 1
+- [ ] AC 2
+- [ ] AC 3
+
+**Suggested ID:** US-{EPIC}-{NNN}  (best-guess prefix; human assigns final ID)
+**Suggested Epic / Feature:** {name}
+**Estimated complexity:** {S | M | L}
+```
+
+Complexity guide: S = one skill file or small bin/roll change, M = skill + bin/roll + tests, L = multi-file + new infrastructure.
+
+### Step 4 — Write to .roll/proposals.md
+
+Append to `.roll/proposals.md` in the project root (create if absent):
+
+```markdown
+---
+proposed: {YYYY-MM-DD HH:MM}
+status: pending
+---
+
+{proposals from Step 3}
+```
+
+Use `---` as separator between proposal batches. Never overwrite existing content.
+
+### Step 5 — Report
+
+```
+✅ roll-propose: {N} proposal(s) written to .roll/proposals.md
+
+To approve: move the entry to .roll/backlog.md and assign a US-XXX ID.
+To reject:  annotate with "Rejected: {reason}" to suppress future re-proposals.
+```
+
+## Output Rules
+
+- Write proposals in the same language as the project's primary documentation (Chinese for this project).
+- Never write directly to .roll/backlog.md — .roll/proposals.md is the staging area.
+- If a similar proposal already exists in .roll/proposals.md (pending or rejected), note similarity and skip or merge rather than creating a duplicate.
+- Aim for 2 proposals by default; generate 1 if context is thin, 3 if focus hint suggests a rich area.
+
+## .roll/proposals.md Format
+
+```markdown
+# Roll Proposals
+
+> 待审批提案。批准后手工移入 .roll/backlog.md 并分配 US-XXX 编号。
+> 拒绝时在条目末尾注明拒绝原因，防止 Agent 重复提出相似提案。
+
+---
+proposed: 2026-05-11 11:30
+status: pending
+---
+
+## PROPOSAL: ...
+
+...
+
+---
+proposed: 2026-05-08 09:00
+status: rejected
+rejected_reason: 与现有 roll-design 功能重叠，不需要单独技能
+---
+
+## PROPOSAL: ...
+
+...
+```

package/skills/roll-review-pr/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: roll-review-pr
+license: MIT
+allowed-tools: "Read"
+description: "Agent-agnostic PR review skill. Reviews a pull request diff and emits a structured 3-state verdict (APPROVE / REQUEST_CHANGES / UNCERTAIN). Used by `roll review-pr` and `_loop_pr_review_external`."
+---
+
+# PR Review
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+You are reviewing a pull request. Your job is to assess code quality,
+correctness, and adherence to project conventions.
+
+## Context
+
+**PR Title:** {{PR_TITLE}}
+
+**PR Body:**
+{{PR_BODY}}
+
+## Diff
+
+```diff
+{{PR_DIFF}}
+```
+
+## Review Instructions
+
+1. Read the diff carefully. Focus on:
+   - Correctness: logic errors, off-by-one, unhandled edge cases
+   - Security: injection, secrets exposure, unsafe operations
+   - Conventions: naming, structure, test coverage (as described in AGENTS.md)
+   - Scope: changes should match what the PR title/body claims
+
+2. Write your analysis in free text (2-10 sentences). Be specific — cite file
+   names and line numbers when pointing out issues.
+
+3. End your response with exactly ONE verdict footer on its own line:
+
+   - If the code is acceptable:
+     `<!--VERDICT:APPROVE-->`
+
+   - If changes are needed (cite the most important issue):
+     `<!--VERDICT:REQUEST_CHANGES:one-line reason-->`
+
+   - If you cannot confidently judge (e.g., missing context, domain-specific logic):
+     `<!--VERDICT:UNCERTAIN:one-line reason-->`
+
+## Rules
+
+- The verdict footer MUST appear on the last non-empty line of your response.
+- Choose exactly one verdict. Do not combine them.
+- REQUEST_CHANGES is for real issues — not style nitpicks or personal preferences.
+- When in doubt between APPROVE and UNCERTAIN, prefer UNCERTAIN.
+- If the PR body contains `[skip-ai-review]`, immediately output
+  `<!--VERDICT:APPROVE-->` with no analysis.

package/skills/roll-sentinel/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: roll-sentinel
+license: MIT
+allowed-tools: "Read, Edit, Write, Bash, WebFetch"
 description: Smart patrol inspector for production systems. Scheduled randomized sampling checks based on BACKLOG requirements. Cost-controlled AI validation with intelligent spot-checking logic.
 ---
 
@@ -7,6 +9,13 @@ description: Smart patrol inspector for production systems. Scheduled randomized
 
 **Smart Patrol Inspector** - Scheduled, randomized, cost-controlled patrol and acceptance checks for production systems.
 
+## When Not to Use
+
+- One-off debugging of a reported bug (use `$roll-debug`)
+- Full-coverage regression testing (sentinel samples, does not cover)
+- Dev/staging environment checks (use CI tests instead)
+- Pre-commit self-review of diffs (use `$roll-.review`)
+
 ## Core Principle
 
 ```
@@ -309,7 +318,7 @@ async function batchCheck(stories) {
 │     └── Decision: create FIX-AUDIO-015                      │
 │                                                             │
 │  5. Create Backlog Item                                     │
-│     └── Add FIX-AUDIO-015 to BACKLOG.md                     │
+│     └── Add FIX-AUDIO-015 to .roll/backlog.md                     │
 │     └── Status: 📋 Todo                                     │
 │     └── Awaiting human fix                                  │
 │                                                             │
@@ -341,7 +350,7 @@ async function batchCheck(stories) {
 │  $roll-debug               On-demand deep diagnosis (aux) │
 │  (When Sentinel finds an issue, manually trigger deep dive) │
 │                                                             │
-│  $roll-story            Post-fix regression verify     │
+│  $roll-build            Post-fix regression verify     │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```

package/skills/roll-spar/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: roll-spar
+license: MIT
+allowed-tools: "Read, Edit, Write, Bash, Agent, Skill"
 description: Adversarial TDD mode with Attacker/Defender agents. Attacker writes tests to break the system, Defender writes minimal code to pass. Use for high-risk logic like auth, payments, data integrity, or complex state machines.
 ---
 
@@ -109,7 +111,7 @@ User: "$roll-spar implement transfer logic" or agent auto-triggers
 │    - Defender summarizes defense    │
 │      strategy                       │
 │    - Merged report                  │
-│    - Continue normal story-build    │
+│    - Continue normal roll-build     │
 │      flow                           │
 │      (push → CI → deploy → verify)  │
 └─────────────────────────────────────┘
@@ -205,12 +207,12 @@ Report to the user after each round:
 4. **Attack intent must be explained** — cannot just write tests without explaining "why this scenario matters"
 5. **Maximum round limit** — default 5 rounds, prevents infinite loops
 
-## Integration with story-build
+## Integration with roll-build
 
-Spar replaces steps 4-5 in story-build (Test Design + TCR Implementation):
+Spar replaces steps 4-5 in roll-build (Test Design + TCR Implementation):
 
 ```
-story-build normal flow:
+roll-build normal flow:
   1. Clarify Story
   2. Split Actions
   3. Define verification
@@ -223,7 +225,7 @@ story-build normal flow:
   ...
 ```
 
-**Auto-switching from story-build to Spar:**
+**Auto-switching from roll-build to Spar:**
 
 When the agent assesses an Action as high-risk at step 3:
 ```
@@ -232,7 +234,7 @@ When the agent assesses an Action as high-risk at step 3:
    Recommend enabling Spar mode — confirm? [Y/n]
 ```
 
-After user confirms, enter Spar. Once complete, return to story-build step 6 to continue.
+After user confirms, enter Spar. Once complete, return to roll-build step 6 to continue.
 
 ## Example
 

package/template/.github/workflows/ci.yml

@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           cache: 'npm'
       
       - name: Install dependencies
@@ -30,3 +30,6 @@ jobs:
       
       - name: Test
         run: npm run test -- --run
+
+      - name: E2E Tests
+        run: npm run test:e2e --if-present

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 -> `.roll/backlog.md`
+- **Build**: `$roll-build` / `$roll-fix` -> TCR (Green=Commit, Red=Revert)
+- **Patrol**: `$roll-sentinel` periodic + `$roll-debug` on failure
+- **Workspace**: `.roll/backlog.md` index. `.roll/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. -->