@seanyao/roll 2026.421.4 → 2026.423.1

package/README.md

@@ -141,6 +141,7 @@ Research → Design → Build → Check → Fix → (loop)
 | Deep research (product / company / tech) | `$roll-research "subject"` |
 | Patrol production for regressions | `$roll-sentinel patrol` |
 | Debug a broken page | `$roll-debug <URL>` |
+| Record a dev moment / diary entry | `$roll-notes "just fixed that nasty bug"` |
 
 ### Full Skill List
 
@@ -160,6 +161,7 @@ Research → Design → Build → Check → Fix → (loop)
 | `$roll-.changelog` | Support | Auto-generate CHANGELOG from BACKLOG |
 | `$roll-.echo` | Support | Passive intent clarification |
 | `$roll-.clarify` | Support | Passive scope clarification for vague build requests |
+| `$roll-notes` | Support | Project diary — append dev moments to `notes/YYYY-MM-DD.md` |
 
 ---
 

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.4"
+VERSION="2026.423.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.421.4",
+  "version": "2026.423.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

@@ -0,0 +1,69 @@
+---
+name: roll-notes
+license: MIT
+description: "Project diary skill. Records development moments — successes, failures, discoveries — appended chronologically to a daily notes file."
+---
+
+# roll-notes
+
+> 项目日记技能。记录开发过程中的成功、失败、感受和任何值得记住的事情。
+> Append-only, timeline-driven, no fixed format.
+
+## Trigger
+
+- User says "记一下"、"写进日记"、"append 到日记"
+- User asks to record a feeling, finding, or moment
+- A project milestone is reached and worth capturing
+
+```
+$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
+2. **Get current time**: Use `Asia/Shanghai` timezone (`TZ=Asia/Shanghai date`)
+3. **Append**: Add new entry at end of file — never overwrite existing content
+4. **Create if missing**: If file doesn't exist, create with a `# YYYY-MM-DD — <one-line summary>` header
+5. **Free format**: Paragraph, list, code block — whatever fits the moment
+
+## File format
+
+```markdown
+# YYYY-MM-DD — 一句话概括今天
+
+> 时间：北京时间 HH:MM
+
+---
+
+## HH:MM — 事件标题
+
+发生了什么、怎么解决的、什么感受。
+
+---
+
+## HH:MM — 另一个事件
+
+...
+```
+
+## Rules
+
+- **No planning**: Never write "明日待办" or "下一步"
+- **No summaries**: Never write "今日收获" or "经验教训"
+- **Pure record**: What happened, as-is — honest, immediate, rough is fine
+- **Append freely**: Multiple entries per day is normal
+
+## File location
+
+```
+notes/
+  └── YYYY-MM-DD.md
+```

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