@seanyao/roll 2026.421.5 → 2026.424.1

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.421.5"
+VERSION="2026.424.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -235,6 +235,7 @@ ai_gemini: ~/.gemini|GEMINI.md|GEMINI.md
 ai_kimi: ~/.kimi|AGENTS.md|AGENTS.md
 ai_codex: ~/.codex|AGENTS.md|AGENTS.md
 ai_cursor: ~/.cursor|.cursor-rules|.cursor-rules
+ai_trae: ~/.trae|user_rules.md|project_rules.md
 ai_openclaw: ~/.openclaw/workspace|AGENTS.md|AGENTS.md
 
 # User preferences
@@ -881,56 +882,6 @@ detect_project_type() {
   fi
 }
 
-# ─── Helper: detect AI tools from existing convention files ──────────────────
-detect_tools() {
-  local dir="$1"
-  local tools=""
-  [[ -f "$dir/.claude/CLAUDE.md" ]] && tools+="claude,"
-  [[ -f "$dir/GEMINI.md" ]] && tools+="gemini,"
-  [[ -f "$dir/.cursor-rules" ]] && tools+="cursor,"
-  echo "${tools%,}"
-}
-
-# ─── Helper: refresh a single project ────────────────────────────────────────
-refresh_project() {
-  local project_dir="$1"
-  local project_name
-  project_name="$(basename "$project_dir")"
-
-  local ptype
-  ptype="$(detect_project_type "$project_dir")"
-
-  if [[ "$ptype" == "unknown" ]]; then
-    warn "  ${BOLD}$project_name${NC}: cannot detect project type — skipping  无法检测项目类型 — 已跳过"
-    return 1
-  fi
-
-  local tools
-  tools="$(detect_tools "$project_dir")"
-
-  local tpl_dir="$ROLL_TEMPLATES/$ptype"
-  if [[ ! -d "$tpl_dir" ]]; then
-    warn "  ${BOLD}$project_name${NC}: template '$ptype' not found — skipping  模板 '$ptype' 未找到 — 已跳过"
-    return 1
-  fi
-
-  info "  ${BOLD}$project_name${NC} ($ptype | ${tools:-AGENTS.md only})  正在处理: ${BOLD}$project_name${NC}"
-
-  merge_convention "AGENTS.md" "$tpl_dir" "$project_dir" "  AGENTS.md"
-
-  if echo "$tools" | grep -q "claude"; then
-    mkdir -p "$project_dir/.claude"
-    merge_convention "CLAUDE.md" "$tpl_dir" "$project_dir/.claude" "  .claude/CLAUDE.md"
-  fi
-  if echo "$tools" | grep -q "gemini"; then
-    merge_convention "GEMINI.md" "$tpl_dir" "$project_dir" "  GEMINI.md"
-  fi
-  if echo "$tools" | grep -q "cursor"; then
-    merge_convention ".cursor-rules" "$tpl_dir" "$project_dir" "  .cursor-rules"
-  fi
-
-  return 0
-}
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: hooks <subcommand>
@@ -1043,7 +994,7 @@ cmd_status() {
 
   echo ""
   echo -e "${BOLD}Global conventions:  全局约定${NC}"
-  for f in AGENTS.md CLAUDE.md GEMINI.md .cursor-rules; do
+  for f in AGENTS.md CLAUDE.md GEMINI.md .cursor-rules project_rules.md; do
     if [[ -f "$ROLL_GLOBAL/$f" ]]; then
       echo -e "  ${GREEN}+${NC} $f"
     else

package/conventions/global/project_rules.md

@@ -0,0 +1,28 @@
+# Global Preferences — Trae IDE
+
+> Extends AGENTS.md in this directory — read that first for shared conventions.
+> This file adds Trae IDE-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
+
+## 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.
+- Prefer targeted edits over full file rewrites.
+- For file operations, verify the file exists before modifying.
+
+## 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.

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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.421.5",
+  "version": "2026.424.1",
   "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/skills/roll-.changelog/SKILL.md

@@ -1,6 +1,7 @@
 ---
 hidden: true
 name: roll-.changelog
+license: MIT
 description: After build completion, extracts completed Stories from BACKLOG.md to generate CHANGELOG.md. Auto-triggered after successful deploy, keeping the external changelog in sync with the internal backlog.
 ---
 
@@ -10,9 +11,15 @@ After successful Build & Deploy, extracts completed Stories from BACKLOG.md to g
 
 ## When Triggered
 
-- **Auto-triggered**: After successful deploy of `$roll-story` or `$roll-fix`
+- **Auto-triggered**: After successful deploy of `$roll-build` or `$roll-fix`
 - **Manual trigger**: When user requests "update changelog" or "generate release notes"
 
+## When Not to Use
+
+- Generating commit messages or PR descriptions — this skill only runs post-deploy
+- Recording dev diary / moments (use `$roll-notes`)
+- Bumping package version (use `$roll-release`)
+
 ## Workflow
 
 ### 1. Read BACKLOG.md
@@ -71,7 +78,7 @@ git push
 
 ## Integration
 
-After successful deploy in `$roll-story` / `$roll-fix` / `$roll-fly`:
+After successful deploy in `$roll-build` / `$roll-fix`:
 
 ```markdown
 **Post-Deploy:**

package/skills/roll-.clarify/SKILL.md

@@ -1,6 +1,7 @@
 ---
 hidden: true
 name: roll-.clarify
+license: MIT
 description: |
   Passive scope-clarification skill. Auto-triggers when roll-build receives vague or under-specified input in Fly mode. Summarizes intent and asks 3–5 targeted questions to establish boundaries before planning or coding.
   This is a passive skill. Never announce "I'm using roll-.clarify." Just do it naturally: summarize, ask, wait.
@@ -18,11 +19,13 @@ Auto-invoked by `roll-build` (Fly mode) when the user input is:
 - Contains ambiguous terms like "优化一下", "改一下", "加个东西"
 - Could be interpreted in multiple ways
 
-**Do NOT activate when:**
+## When Not to Use
+
 - Intent is already clear and actionable
 - User gives a specific command with a skill trigger (e.g. `$roll-jot ...`)
 - User is answering a clarification question you just asked
 - The task is simple enough that misinterpretation risk is negligible
+- User messy thoughts need restatement rather than questioning (use `$roll-.echo`)
 
 ## Behavior
 

package/skills/roll-.echo/SKILL.md

@@ -1,6 +1,7 @@
 ---
 hidden: true
 name: roll-.echo
+license: MIT
 description: |
   Passive intent clarification skill. Automatically activates when user input is vague, rambling, contradictory, or unclear. Restates the user's intent in structured, concise form and confirms before proceeding. Does NOT activate when intent is already clear — in that case, just execute directly.
   This is a passive skill. Never announce "I'm using roll-.echo." Just do it naturally: restate, confirm, proceed.
@@ -22,11 +23,13 @@ This skill fires **automatically** when the AI detects unclear intent. It should
 - Vague scope: "make it better", "fix this area", "do something about"
 - The intent could reasonably be interpreted in 2+ very different ways
 
-**Do NOT activate when**:
+## When Not to Use
+
 - Intent is already clear and actionable ("add a login button to the header")
-- User gives a specific command with a skill trigger ("$roll-story US-001")
+- User gives a specific command with a skill trigger ("$roll-build US-001")
 - User is answering a question you asked (they're clarifying, not initiating)
 - The task is simple enough that misinterpretation risk is negligible
+- User needs targeted Q&A to fill specific gaps (use `$roll-.clarify`)
 
 **When in doubt**: If you're 80%+ confident you understand correctly, just execute. Echo is for the 50/50 situations where getting it wrong would waste real effort.
 

package/skills/roll-.qa/SKILL.md

@@ -1,17 +1,24 @@
 ---
 hidden: true
-name: roll-.qa-cover
+name: roll-.qa
+license: MIT
 description: QA coverage reference for build skills. Defines test pyramid (unit/E2E/visual/smoke), coverage requirements, and CI gates. Ensures quality assurance across all testing layers.
 ---
 
 # QA Cover
 
-This is a **reference skill** used by `roll-story`, `roll-fix`, and `roll-fly` for quality assurance and test coverage.
+This is a **reference skill** used by `roll-build` and `roll-fix` for quality assurance and test coverage.
 
 ## When to Apply
 
 Any product with a user interface (Web, Desktop, Mobile) must follow these testing standards.
 
+## When Not to Use
+
+- Non-UI backends (APIs, CLI tools, data pipelines) — use project-specific test frameworks
+- Spike code or throwaway prototypes that won't ship
+- Per-commit self-review of diffs (use `$roll-.review`)
+
 ## Required Testing Levels
 
 ### 1. Unit Tests (Logic)

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

@@ -1,6 +1,7 @@
 ---
 hidden: true
-name: roll-.code-review
+name: roll-.review
+license: MIT
 description: Self code review step in the TCR workflow. Runs after each micro-step is completed and before commit, checking code quality, security, and design issues.
 ---
 
@@ -21,9 +22,15 @@ TCR Loop:
 
 ## When Triggered
 
-- **Auto-triggered**: After each TCR micro-step in `$roll-story` / `$roll-fix` / `$roll-fly`
+- **Auto-triggered**: After each TCR micro-step in `$roll-build` / `$roll-fix`
 - **Manual trigger**: When the user wants to review current changes
 
+## When Not to Use
+
+- Docs-only changes (README, CHANGELOG) with no code diff
+- Test pyramid / coverage standards check (use `$roll-.qa`)
+- Post-deploy production sampling (use `$roll-sentinel`)
+
 ## Review Scope
 
 ```bash

package/skills/roll-build/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-build
+license: MIT
 description: "Universal delivery skill. Handles any input: a US-XXX ID executes from BACKLOG via TCR; a FIX-XXX redirects to roll-fix; any other text auto-clarifies, designs, and ships as a new Story."
 ---
 

package/skills/roll-debug/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-debug
+license: MIT
 description: Universal web debugger. Collects diagnostics (console/network/DOM) via Playwright, analyzes root causes, and suggests fixes. Works with or without Black Box (BB) integration.
 ---
 
@@ -21,6 +22,12 @@ Two collection modes:
 - "Analyze BB data", "look at the diagnostic file"
 - Any scenario requiring web page diagnosis
 
+## When Not to Use
+
+- Non-web environments (CLI tools, backend-only services) — outside this skill's scope
+- Scheduled production sampling / acceptance checks (use `$roll-sentinel`)
+- Pure source-reading without runtime reproduction
+
 ## Quick Start
 
 ```bash
@@ -424,5 +431,5 @@ After `$roll-debug` finds issues:
 
 # For a complex multi-step fix
 # → Create US-XXX in backlog
-# → $roll-story US-XXX
+# → $roll-build US-XXX
 ```

package/skills/roll-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-design
+license: MIT
 description: Unified entry for discussion, design and planning. Explores options when uncertain, designs solutions, splits into INVEST-compliant user stories, and writes to BACKLOG.md. Use when user wants to discuss approaches, design solutions, plan features, or create stories.
 ---
 
@@ -24,6 +25,12 @@ Discuss approaches, design architecture, plan requirements, and write to `BACKLO
 - Splitting into Stories
 - Creating US / FIX entries
 
+## When Not to Use
+
+- One-liner capture of ideas or bugs (use `$roll-jot`)
+- Executing an already-split US-XXX (use `$roll-build`)
+- Fixing a well-defined FIX-XXX (use `$roll-fix`)
+
 ## Quick Start
 
 ```bash
@@ -124,7 +131,7 @@ User: "Help me design the user system" / "What approach should we use for search
               ▼
     "Confirm and execute?"
     │
-    ├── Yes ──→ $roll-story US-XXX
+    ├── Yes ──→ $roll-build US-XXX
     │
     └── No  ──→ Wait for user confirmation
 ```
@@ -221,16 +228,16 @@ FEATURE_FILE="docs/features/${FEATURE}.md"
 
 ## Integration
 
-### With story-build
+### With roll-build
 
 ```
 $roll-design "login feature" → Create US-AUTH-001
 User: "Execute US-AUTH-001"
     ↓
-$roll-story US-AUTH-001 → TCR → CI/CD → Deploy
+$roll-build US-AUTH-001 → TCR → CI/CD → Deploy
 ```
 
-### With fix-build
+### With roll-fix
 
 ```
 $roll-debug discovers issue → Suggest creating FIX

package/skills/roll-fix/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: roll-fix
-description: Execute bugfix/hotfix from backlog. Reads FIX/BUG from BACKLOG.md, delivers via TCR workflow. Lighter than story-build, focused on single-issue fixes.
+license: MIT
+description: Execute bugfix/hotfix from backlog. Reads FIX/BUG from BACKLOG.md, delivers via TCR workflow. Lighter than roll-build, focused on single-issue fixes.
 ---
 
 # Fix Ship (TCR Edition)
@@ -30,7 +31,7 @@ Do not use for:
 - Requirements that need planning and splitting first
 - Roadmap work that should be tracked as Stories
 
-If the issue expands beyond a single bounded change, switch to `roll-story`.
+If the issue expands beyond a single bounded change, switch to `roll-build`.
 
 ## Project Context Rule
 

package/skills/roll-jot/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-jot
+license: MIT
 description: "Fast backlog capture. Analyzes a short description, classifies it as bug or idea, and appends it to BACKLOG.md with an auto-incremented ID."
 ---
 
@@ -17,6 +18,12 @@ $roll-jot 手机端星星指标一行一个从上往下排
 $roll-jot 给 HOD 加一个批量导出 PDF 的功能
 ```
 
+## When Not to Use
+
+- Requirement needs discussion or splitting into Stories (use `$roll-design`)
+- A US-XXX / FIX-XXX is ready to execute (use `$roll-build` / `$roll-fix`)
+- Recording a development moment or feeling (use `$roll-notes`)
+
 ## Behavior
 
 1. **Read** `BACKLOG.md` from the project root.

package/skills/roll-notes/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-notes
+license: MIT
 description: "Project diary skill. Records development moments — successes, failures, discoveries — appended chronologically to a daily notes file."
 ---
 
@@ -19,6 +20,12 @@ $roll-notes 终于搞定了那个 WebSocket 断线重连的 bug
 $roll-notes 今天的 code review 给了很好的反馈
 ```
 
+## When Not to Use
+
+- Capturing a bug or feature idea into BACKLOG (use `$roll-jot`)
+- Generating user-facing release notes (use `$roll-.changelog`)
+- Writing design documents or AC (use `$roll-design`)
+
 ## Behavior
 
 1. **Determine file path**: `notes/YYYY-MM-DD.md` relative to project root

package/skills/roll-release/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-release
+license: MIT
 description: "Release skill for roll maintainers. Calculates next version (YYYY.MMDD.N format, auto-increments N from today's git tags), updates VERSION in bin/roll and package.json, commits, tags, and pushes to trigger npm auto-publish via GitHub Actions. Trigger: release, publish, 发版, 发布新版本."
 ---
 
@@ -7,6 +8,13 @@ description: "Release skill for roll maintainers. Calculates next version (YYYY.
 
 One-command publish flow for roll maintainers.
 
+## When Not to Use
+
+- Non-maintainer users (this skill publishes `@seanyao/roll` to npm under seanyao)
+- Internal project releases — only for the `roll` CLI package itself
+- Hotfixing code without a version bump (use `$roll-fix`)
+- Generating user-facing release notes (use `$roll-.changelog`)
+
 ## Version Format
 
 `YYYY.MMDD.N` — e.g. `2026.419.1`

package/skills/roll-research/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-research
+license: MIT
 description: |
   HV (Horizontal-Vertical) Analysis deep research skill for products, companies, concepts, technologies, or people. Dual-axis: vertical traces full lifecycle narrative from origin to present; horizontal compares against competitors at current time; cross-axis produces new insights. Output: professionally formatted PDF report.
   Trigger: "deep research", "research this", "competitive analysis", "help me understand", "what's the deal with", "deep dive", "HV analysis", or any request implying systematic research (not a simple lookup).

package/skills/roll-sentinel/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: roll-sentinel
+license: MIT
 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 +8,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
 
 ```
@@ -341,7 +349,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,6 @@
 ---
 name: roll-spar
+license: MIT
 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 +110,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 +206,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 +224,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 +233,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