@seanyao/roll 2026.424.3 → 2026.503.7

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.424.3"
+VERSION="2026.503.7"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -64,6 +64,24 @@ lower_name() {
   echo "$1" | tr '[:upper:]' '[:lower:]'
 }
 
+# Check if an AI tool is actually installed.
+# Most tools create their own config dir; Trae on macOS uses Library/Application Support
+# and expects roll to manage ~/.trae/ — so we detect via the app directory instead.
+_is_ai_installed() {
+  local ai_dir="$1"
+  [[ -d "$ai_dir" ]] && return 0
+  local bn
+  bn="$(basename "$ai_dir" | sed 's/^\.//')"
+  case "$bn" in
+    trae)
+      [[ -d "$HOME/Library/Application Support/Trae" ]] ||
+      [[ -d "$HOME/.config/Trae" ]]
+      return
+      ;;
+  esac
+  return 1
+}
+
 # ─── Helper: read config value ───────────────────────────────────────────────
 config_get() {
   local key="$1"
@@ -87,6 +105,53 @@ _get_ai_tools() {
   done
 }
 
+# Add any ai_* keys from the default set that are missing from the user's config.
+# Non-destructive: never removes or modifies existing entries.
+_ensure_config_entries() {
+  [[ -f "$ROLL_CONFIG" ]] || return
+
+  local -a default_keys=(
+    "ai_claude:~/.claude|CLAUDE.md|CLAUDE.md"
+    "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"
+  )
+
+  local added=0
+  local tmp
+  tmp="$(mktemp)"
+  cp "$ROLL_CONFIG" "$tmp"
+
+  for entry in "${default_keys[@]}"; do
+    local key="${entry%%:*}"
+    local val="${entry#*:}"
+    if ! grep -qE "^${key}:" "$ROLL_CONFIG" 2>/dev/null; then
+      if grep -q "^# User preferences" "$tmp" 2>/dev/null; then
+        local new_tmp
+        new_tmp="$(mktemp)"
+        while IFS= read -r line; do
+          [[ "$line" == "# User preferences" ]] && echo "${key}: ${val}" >> "$new_tmp"
+          echo "$line" >> "$new_tmp"
+        done < "$tmp"
+        mv "$new_tmp" "$tmp"
+      else
+        echo "${key}: ${val}" >> "$tmp"
+      fi
+      added=$((added + 1))
+      warn "Added missing config entry: ${key}  已添加缺失配置项: ${key}"
+    fi
+  done
+
+  if [[ $added -gt 0 ]]; then
+    cp "$tmp" "$ROLL_CONFIG"
+    ok "Config updated with $added new entries  配置已更新，新增 $added 条目"
+  fi
+  rm -f "$tmp"
+}
+
 # Extract fields from a "<dir>|<config>|<src>" entry
 _ai_dir()    { echo "$1" | cut -d'|' -f1; }
 _ai_config() { echo "$1" | cut -d'|' -f2; }
@@ -246,6 +311,9 @@ YAML
     ok "Created: ~/.roll/config.yaml  已创建: ~/.roll/config.yaml"
   fi
 
+  # Ensure all expected ai_* keys exist (handles upgrades where new tools were added)
+  _ensure_config_entries
+
 }
 
 # ─── Internal: create or repair per-skill symlinks (non-destructive) ─────────
@@ -258,7 +326,8 @@ _link_skills() {
   while IFS= read -r entry; do
     local ai_dir
     ai_dir="$(_ai_dir "$entry")"
-    [[ -d "$ai_dir" ]] || continue
+    _is_ai_installed "$ai_dir" || continue
+    mkdir -p "$ai_dir"
 
     local ai_name ai_dir_real skills_dir
     ai_name="$(ai_tool_name "$ai_dir")"
@@ -355,8 +424,8 @@ _sync_convention_for_tool() {
   local dst_dir
   dst_dir="$(dirname "$main_dst")"
 
-  # Only proceed if the AI tool directory already exists (except Claude, always create)
-  if [[ "$dst_dir" != "$HOME/.claude" ]] && [[ ! -d "$dst_dir" ]]; then
+  # Only proceed if Claude (always) or the tool is installed
+  if [[ "$dst_dir" != "$HOME/.claude" ]] && ! _is_ai_installed "$dst_dir"; then
     return
   fi
   mkdir -p "$dst_dir"
@@ -467,6 +536,7 @@ cmd_sync() {
   info "Syncing from repo to AI tools...  正在从仓库同步到 AI 工具..."
   echo ""
   _pull_conventions "$force"
+  _ensure_config_entries
   echo ""
   _sync_conventions "$force"
   echo ""

package/conventions/global/CLAUDE.md

@@ -17,7 +17,7 @@
 
 ## Claude Code-Specific
 
-- When a project has Roll skills, use them (`$roll-design`, `$roll-story`, etc.).
+- When a project has Roll skills, use them (`$roll-design`, `$roll-build`, `$roll-fix`, etc.).
 - Use plan mode for complex multi-step tasks before executing.
 - Prefer Edit tool over Bash for file modifications.
 - Use Agent tool with worktree isolation for parallel independent subtasks.

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

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.424.3",
+  "version": "2026.503.7",
   "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-.qa/SKILL.md

@@ -208,4 +208,4 @@ If project lacks Playwright setup:
 
 - [Playwright Docs](https://playwright.dev/)
 - [Visual Regression Guide](https://playwright.dev/docs/test-snapshots)
-- Example implementation: `seanyao/kids-game/e2e/`
+- Example implementation: `<owner>/<repo>/e2e/`

package/skills/roll-notes/SKILL.md

@@ -54,6 +54,28 @@ $roll-notes 今天的 code review 给了很好的反馈
 ...
 ```
 
+## 写作风格（强制）
+
+**禁止干巴巴的 checklist。禁止只有结论没有过程。必须有人的声音。**
+
+### 叙事驱动
+以时间线和事件推进为主线，像讲故事一样记录。不是 `补了功能，pytest 绿`，而是 `"电池剩余电量在哪里看？"我一愣，US-PLAT-003 的 AC 明明写了...`
+
+### 技术细节嵌入叙事
+代码、数据、命令行是故事的一部分，自然插入，不是附录。
+
+### 对话与互动
+记录用户的反馈、提问、情绪。日记是对话记录，不是独白。
+
+### 诚实记录错误
+失败、困惑、教训比成功更值得记录。
+
+### 标题有画面感
+不是功能清单。如 `每秒 20 行的噪音`、`22 个文件挤在一个抽屉里`。
+
+### 结尾有收束
+最后一段回到人的状态。如 `"值了"。"睡了"。push。`
+
 ## Rules
 
 - **No planning**: Never write "明日待办" or "下一步"

package/skills/roll-release/SKILL.md

@@ -10,7 +10,7 @@ One-command publish flow for roll maintainers.
 
 ## When Not to Use
 
-- Non-maintainer users (this skill publishes `@seanyao/roll` to npm under seanyao)
+- Non-maintainer users (this skill publishes the package defined in `package.json` — confirm scope before running)
 - 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`)
@@ -92,8 +92,8 @@ After publish, show:
 ```
 ✅ Released v{version}
 🏷  Tag: v{version} pushed to origin
-📦 npm published: @seanyao/roll@{version}
-🔗 https://www.npmjs.com/package/@seanyao/roll
+📦 npm published: {package_name}@{version}   # package name read from package.json
+🔗 https://www.npmjs.com/package/{package_name}
 ```
 
 ## Abort Conditions