@seanyao/roll 2026.503.7 → 2026.505.1

package/README.md

@@ -48,7 +48,8 @@ roll setup
 To update:
 
 ```bash
-roll update
+npm install -g @seanyao/roll@latest
+roll setup
 ```
 
 > **For contributors** (working on roll itself): `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
@@ -63,26 +64,24 @@ Unified behavioral conventions for Claude Code / Gemini CLI / Cursor / Codex —
 
 | Command | Description |
 |---------|-------------|
-| `roll setup` | First-time install: create `~/.roll/` + sync to all AI tools |
-| `roll update` | Update roll to latest version + re-sync |
-| `roll sync` | Re-sync conventions and skill symlinks to all AI tools |
+| `roll setup` | First-time install on this machine, or re-sync after editing `~/.roll/config.yaml` (use `--force` to overwrite local cache) |
 | `roll init` | New project: create `AGENTS.md` + `BACKLOG.md` + `docs/features/` |
-| `roll hook install` | Optional: global git hook for AI client auto-detection |
-| `roll reset` | Force-rebuild local cache from repo source, then re-sync |
+| `roll hook install` | Optional: global git hook that tags commits with the active AI client |
 | `roll status` | Show sync state, skill links, and detected AI tools |
 
 ### Typical Flow
 
 ```bash
-# 1. Install
-./install.sh
+# 1. Install on this machine
+npm install -g @seanyao/roll
+roll setup
 
 # 2. Initialize a project (run from project root)
 cd my-app
 roll init
 
-# 3. Re-sync after editing ~/.roll/config.yaml
-roll sync
+# 3. Re-sync after editing ~/.roll/config.yaml or after upgrading
+roll setup
 
 # 4. Optional: tag commits with AI client name
 roll hook install
@@ -120,7 +119,7 @@ Global conventions are additive and never overwrite existing files. Project conv
 
 ## Skill System
 
-Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in `~/.roll/skills/` and are symlinked into each AI client's skill directory on `roll sync`.
+Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in `~/.roll/skills/` and are symlinked into each AI client's skill directory on `roll setup`.
 
 ### Workflow
 

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.503.7"
+VERSION="2026.505.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -196,6 +196,27 @@ safe_copy() {
   ok "Wrote: ${dst/#$HOME/~}  已写入: ${dst/#$HOME/~}"
 }
 
+# ─── Internal: prune files in $1 that no longer exist in $2 ──────────────────
+# Used to clean up stale files left behind when a previous version had them
+# but the current package no longer ships them.
+_prune_dir() {
+  local installed_dir="$1"
+  local source_dir="$2"
+  local label="${3:-file}"
+  [[ -d "$installed_dir" ]] || return 0
+
+  local installed_f installed_fname
+  for installed_f in "$installed_dir"/* "$installed_dir"/.*; do
+    [[ -f "$installed_f" ]] || continue
+    installed_fname="$(basename "$installed_f")"
+    [[ "$installed_fname" == "." || "$installed_fname" == ".." ]] && continue
+    if [[ ! -f "$source_dir/$installed_fname" ]]; then
+      rm -f "$installed_f"
+      info "Removed stale $label: ${installed_dir##*/}/$installed_fname  已删除过时$label: ${installed_dir##*/}/$installed_fname"
+    fi
+  done
+}
+
 # ─── Internal: pull skills from repo → ~/.roll/skills ──────────────────────
 _pull_skills() {
   if [[ ! -d "$ROLL_PKG_DIR/skills" ]]; then
@@ -214,6 +235,8 @@ _pull_skills() {
       for f in "$skill_dir"*; do
         [[ -f "$f" ]] && cp "$f" "$ROLL_HOME/skills/$skill_name/$(basename "$f")"
       done
+      # File-level prune (dir-level prune below catches whole-skill removals)
+      _prune_dir "$ROLL_HOME/skills/$skill_name" "$skill_dir" "skill file"
     fi
   done
 
@@ -250,6 +273,8 @@ _pull_conventions() {
     [[ -f "$f" ]] && [[ "$(basename "$f")" != "." ]] && [[ "$(basename "$f")" != ".." ]] && \
       safe_copy "$f" "$ROLL_GLOBAL/$(basename "$f")" "$force"
   done
+  # Prune stale files in ~/.roll/conventions/global/
+  _prune_dir "$ROLL_GLOBAL" "$ROLL_PKG_CONVENTIONS/global" "convention"
 
   info "Copying project templates...  正在复制项目模板..."
   for tpl_dir in "$ROLL_PKG_CONVENTIONS"/templates/*/; do
@@ -262,6 +287,8 @@ _pull_conventions() {
       [[ -f "$f" ]] && [[ "$(basename "$f")" != "." ]] && [[ "$(basename "$f")" != ".." ]] && \
         safe_copy "$f" "$ROLL_TEMPLATES/$tpl_name/$(basename "$f")" "$force"
     done
+    # Prune stale files in this template dir
+    _prune_dir "$ROLL_TEMPLATES/$tpl_name" "$tpl_dir" "template file"
   done
 }
 
@@ -291,7 +318,7 @@ _install_local() {
     info "Creating default config...  正在创建默认配置..."
     cat > "$ROLL_CONFIG" << 'YAML'
 # Roll Configuration
-# Edit this file, then run `roll sync` to apply.
+# Edit this file, then run `roll setup` to apply.
 
 # AI tools — each entry controls both convention sync and skill linking
 # Format: <name>: <dir>|<config_file>|<convention_src>
@@ -514,37 +541,6 @@ cmd_setup() {
   info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
 }
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# COMMAND: sync [--force]
-# Full pipeline: repo → ~/.roll/ → AI tool config paths
-# Pulls latest conventions from repo, then distributes to all AI tools.
-# ═══════════════════════════════════════════════════════════════════════════════
-cmd_sync() {
-  if [[ ! -d "$ROLL_HOME" ]]; then
-    err "~/.roll/ not found. Run 'roll setup' first.  ~/.roll/ 不存在，请先运行 'roll setup'。"
-    exit 1
-  fi
-
-  local force=false
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --force|-f) force=true; shift ;;
-      *) err "Unknown sync argument: $1  未知同步参数: $1"; exit 1 ;;
-    esac
-  done
-
-  info "Syncing from repo to AI tools...  正在从仓库同步到 AI 工具..."
-  echo ""
-  _pull_conventions "$force"
-  _ensure_config_entries
-  echo ""
-  _sync_conventions "$force"
-  echo ""
-  _sync_skills "$force"
-  echo ""
-  ok "Sync complete.  同步完成。"
-}
-
 # ─── Helper: merge global AGENTS.md into project (no type prompt) ────────────
 # Fresh project: copies global AGENTS.md.
 # Existing AGENTS.md: appends any ## sections missing from global.
@@ -1007,46 +1003,6 @@ cmd_hook() {
   esac
 }
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# COMMAND: reset
-# Re-copy conventions and skills from repo source, force-sync everything
-# ═══════════════════════════════════════════════════════════════════════════════
-cmd_reset() {
-  warn "This will overwrite ~/.roll/conventions/ and skills with repo defaults.  此操作将用仓库默认值覆盖 ~/.roll/conventions/ 和技能。"
-  echo -n "  Continue? [y/N] "
-  read -r answer
-  [[ "$answer" =~ ^[Yy]$ ]] || { info "Aborted.  已取消。"; return; }
-
-  echo ""
-  info "Resetting and force-syncing...  正在重置并强制同步..."
-  cmd_setup --force
-}
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# COMMAND: update
-# Update roll to latest version (npm update or git pull), then re-sync
-# ═══════════════════════════════════════════════════════════════════════════════
-_is_git_install() {
-  [[ -d "$ROLL_PKG_DIR/.git" ]]
-}
-
-cmd_update() {
-  info "Current version: roll v${VERSION}  当前版本: roll v${VERSION}"
-  echo ""
-
-  if _is_git_install; then
-    info "Git install detected — pulling latest...  检测到 Git 安装，正在拉取最新代码..."
-    git -C "$ROLL_PKG_DIR" pull
-  else
-    info "npm install detected — updating package...  检测到 npm 安装，正在更新包..."
-    npm update -g @seanyao/roll
-  fi
-
-  echo ""
-  info "Re-syncing to AI tools...  正在重新同步到 AI 工具..."
-  cmd_sync
-}
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: status
 # Show current state of conventions
@@ -1222,17 +1178,13 @@ usage() {
   echo "用法:  roll <command> [options]"
   echo ""
   echo "Commands:"
-  echo "  setup [-f]             [Machine] First-time install: init ~/.roll/ + sync   首次安装：初始化 ~/.roll/ 并同步"
-  echo "  update                 [Upgrade] Update roll to latest + re-sync           更新 roll 到最新版本并重新同步"
-  echo "  sync [-f]              [Everyday] package → ~/.roll/ → AI tools            日常同步：从包同步到所有工具"
+  echo "  setup [-f]             [Machine] First-time install or re-sync             首次安装或重新同步"
   echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
   echo "  hook [install|remove]  [Optional] Manage global git hook                  管理全局 git hook"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
-  echo "  reset                  [Recovery] Force-rebuild from package source        强制从包源重建"
   echo ""
   echo "Examples / 示例:"
-  echo "  roll setup                    # New machine: first-time install             新机器：首次安装"
-  echo "  roll update                   # Get latest version + sync to AI tools      更新到最新版本并同步"
+  echo "  roll setup                    # New machine, or re-sync after npm update    新机器或更新后重新同步"
   echo "  roll init                     # New or re-merge project (run in project)   新建或重新合并（项目目录）"
   echo "  roll hook install             # Optional: tag commits with AI client       可选：提交时标记 AI 工具"
 }
@@ -1243,11 +1195,8 @@ main() {
 
   case "$cmd" in
     setup)         cmd_setup "$@" ;;
-    sync)          cmd_sync "$@" ;;
     init)          cmd_init "$@" ;;
-    hook)         cmd_hook "$@" ;;
-    update)        cmd_update "$@" ;;
-    reset)         cmd_reset "$@" ;;
+    hook)          cmd_hook "$@" ;;
     status)        cmd_status "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h|"") usage ;;
@@ -1284,7 +1233,7 @@ _notify_update() {
   local latest; latest=$(awk '{print $2}' "$cache" 2>/dev/null || true)
   [[ -z "$latest" || "$latest" == "$VERSION" ]] && return
   echo ""
-  warn "v${latest} available — run 'roll update' to upgrade  有新版本 v${latest} — 运行 'roll update' 升级"
+  warn "v${latest} available — run 'npm install -g @seanyao/roll@latest && roll setup' to upgrade  有新版本 v${latest} — 运行 'npm install -g @seanyao/roll@latest && roll setup' 升级"
 }
 
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then

package/conventions/global/AGENTS.md

@@ -6,11 +6,22 @@
 - User's language. Code/Git/Comments: English. UI: Chinese.
 - Concise. No summaries/code-walking. Implementation invisible.
 - Strategy (Why) OK; Tactics (How) NO. Outcomes only.
+- **Ambiguity resolution**: When user says "explicit" in automation contexts,
+  interpret as "logged/observable with clear output", NOT "requiring manual
+  intervention". Confirm with one question if uncertain.
+- **Bilingual output**: EN + ZH on separate lines, never inline.
+  ```
+  Processing...
+  处理中...
+  ```
+  Not: `Processing... 处理中...`
 
 ## 2. Code
 - **TS**: Strict, no `any`. Functional hooks. Early returns.
 - **Git**: No force-push main. No `--no-verify`. No secrets in git.
+- **Identity**: When you need the user's name or email, read it dynamically — `git config user.name` / `git config user.email`. **Never hardcode personal data** (names, emails, machine paths, personal repo URLs) into files that get committed or shipped via npm. Author/repo metadata in `package.json` is the only allowed exception.
 - **Behavior**: No unrelated refactoring. No speculative abstractions.
+- **File ops**: Prefer targeted edits over full file rewrites. Verify file exists before modifying.
 
 ## 3. Engineering
 - **Idempotency**: Same op N times = same result.
@@ -20,5 +31,45 @@
 
 ## 4. Workflow
 - **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.
+  - Before implementing: confirm exact files, test strategy, and commit message
+    draft with user. Do not write code until approved.
+  - Before claiming completion: verify in the target environment mentioned by
+    user (e.g., specific CLI tool, remote server, hardware platform).
 - **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
+- **Commit message format**:
+  - Format: `<type>: <description>` (Git Hook may auto-prepend type prefix)
+  - Types: `Story N`, `Fix`, `Refactor`, `Docs`, `Chore`
+  - TCR micro-commits use `tcr:` prefix instead
+
+## 5. Refactoring & Renames
+
+Project-wide renames require systematic checking. Never assume find/replace
+is sufficient. Execute in order:
+
+1. **Code references** — imports, function names, string literals
+2. **Documentation** — README, methodology, API docs
+3. **Config files** — YAML frontmatter, package names, manifests
+4. **Symlinks** — verify all resolve after rename
+5. **Installer scripts** — update paths and references
+6. **Shell environment** — remind user to reload or restart sessions
+
+Confirm each phase clean before proceeding to the next.
+
+## 6. Configuration & External Services
+- **Config file editing** (YAML/TOML/JSON with schema):
+  1. Find official documentation or a verified working example first
+  2. Do not guess syntax
+  3. If no docs found after 2 searches, ask user for a reference config
+  4. Maximum 2 syntax attempts before escalating to research mode
+- **External services** (npm publishing, proxy, auth-dependent deploy):
+  - Stop after 2 failed attempts and ask user for preferred fallback
+  - Do not continue iterating on auth/proxy debugging without explicit direction
+  - If OIDC/token issues persist, immediately fallback to manual with explanation
+
+## 7. Frontend Default Stack
+- React + shadcn/ui + Tailwind CSS is the default.
+- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
+- `components/ui/` is shadcn-generated — never edit manually.
+- Tailwind utility classes only. No inline styles, no CSS modules.
+- Icons: Lucide React.

package/conventions/global/CLAUDE.md

@@ -3,18 +3,6 @@
 > Extends [AGENTS.md](./AGENTS.md) — read that first for shared conventions.
 > This file adds Claude Code-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
-- Example: `Story 7: Review assignment by org structure`
-
 ## Claude Code-Specific
 
 - When a project has Roll skills, use them (`$roll-design`, `$roll-build`, `$roll-fix`, etc.).
@@ -22,11 +10,3 @@
 - Prefer Edit tool over Bash for file modifications.
 - Use Agent tool with worktree isolation for parallel independent subtasks.
 - When I say "帮我看下" or "处理下", go ahead and do it, not just analyze it.
-
-## Frontend Default Stack
-
-- React + shadcn/ui + Tailwind CSS is the default.
-- Use shadcn/ui components first. Custom components only when shadcn doesn't cover it.
-- `components/ui/` is shadcn-generated — never edit manually.
-- Tailwind utility classes only. No inline styles, no CSS modules.
-- Icons: Lucide React.

package/conventions/global/GEMINI.md

@@ -3,26 +3,7 @@
 > Extends AGENTS.md in this directory — read that first for shared conventions.
 > This file adds Gemini CLI-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
-
 ## Gemini-Specific
 
 - When running shell commands, prefer the most specific tool available.
-- For file operations, verify the file exists before modifying.
 - When a project has Roll workflow, follow the AGENTS.md conventions and use Roll skills.
-- Prefer targeted edits over full file rewrites.
-
-## 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/global/project_rules.md

@@ -3,26 +3,7 @@
 > 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.503.7",
+  "version": "2026.505.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"
@@ -21,7 +21,7 @@
     "roll": "bin/roll"
   },
   "license": "MIT",
-  "author": "Sean Yao <seanyao@gmail.com>",
+  "author": "Sean Yao <sean.dlut@gmail.com>",
   "files": [
     "bin/",
     "conventions/",

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

@@ -2,6 +2,8 @@
 hidden: true
 name: roll-.changelog
 license: MIT
+model: haiku
+allowed-tools: "Read, Edit, Write, Bash(git:*)"
 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.
 ---
 

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

@@ -2,6 +2,7 @@
 hidden: true
 name: roll-.qa
 license: MIT
+allowed-tools: "Read"
 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.
 ---
 

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

@@ -2,6 +2,8 @@
 hidden: true
 name: roll-.review
 license: MIT
+model: sonnet
+allowed-tools: "Read, Bash(git:*)"
 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.
 ---