superpowers-zh 1.3.0 → 1.6.0

package/skills/brainstorming/scripts/start-server.sh

@@ -11,6 +11,9 @@
 #   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
 #                         Use 0.0.0.0 in remote/containerized environments.
 #   --url-host <host>     Hostname shown in returned URL JSON.
+#   --idle-timeout-minutes <n>  Shut down after n minutes idle (default 240 = 4h).
+#   --open                Auto-open the browser on the first screen (use only
+#                         after the user approves the visual companion).
 #   --foreground          Run server in the current terminal (no backgrounding).
 #   --background          Force background mode (overrides Codex auto-foreground).
 
@@ -22,6 +25,7 @@ FOREGROUND="false"
 FORCE_BACKGROUND="false"
 BIND_HOST="127.0.0.1"
 URL_HOST=""
+IDLE_TIMEOUT_MINUTES=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --project-dir)
@@ -36,6 +40,14 @@ while [[ $# -gt 0 ]]; do
       URL_HOST="$2"
       shift 2
       ;;
+    --idle-timeout-minutes)
+      IDLE_TIMEOUT_MINUTES="$2"
+      shift 2
+      ;;
+    --open)
+      export BRAINSTORM_OPEN=1
+      shift
+      ;;
     --foreground|--no-daemon)
       FOREGROUND="true"
       shift
@@ -59,6 +71,29 @@ if [[ -z "$URL_HOST" ]]; then
   fi
 fi
 
+if [[ -n "$IDLE_TIMEOUT_MINUTES" ]]; then
+  if ! [[ "$IDLE_TIMEOUT_MINUTES" =~ ^[0-9]+$ ]] || [[ "$IDLE_TIMEOUT_MINUTES" -lt 1 ]]; then
+    echo "{\"error\": \"--idle-timeout-minutes must be a positive integer\"}"
+    exit 1
+  fi
+  export BRAINSTORM_IDLE_TIMEOUT_MS=$(( IDLE_TIMEOUT_MINUTES * 60 * 1000 ))
+fi
+
+is_windows_like_shell() {
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) return 0 ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    return 0
+  fi
+  local uname_s
+  uname_s="$(uname -s 2>/dev/null || true)"
+  case "$uname_s" in
+    MSYS*|MINGW*|CYGWIN*) return 0 ;;
+  esac
+  return 1
+}
+
 # Some environments reap detached/background processes. Auto-foreground when detected.
 if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
   FOREGROUND="true"
@@ -66,28 +101,45 @@ fi
 
 # Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
 if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
-  case "${OSTYPE:-}" in
-    msys*|cygwin*|mingw*) FOREGROUND="true" ;;
-  esac
-  if [[ -n "${MSYSTEM:-}" ]]; then
+  if is_windows_like_shell; then
     FOREGROUND="true"
   fi
 fi
 
+# Session files (server.log, server-info, .last-token) embed the session key —
+# keep everything this script and the server create owner-only.
+umask 077
+
 # Generate unique session directory
 SESSION_ID="$$-$(date +%s)"
 
 if [[ -n "$PROJECT_DIR" ]]; then
-  SCREEN_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  # Persist the bound port and key per project so a restart reuses them and an
+  # already-open browser tab reconnects to the same URL with a valid cookie.
+  export BRAINSTORM_PORT_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-port"
+  export BRAINSTORM_TOKEN_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-token"
 else
-  SCREEN_DIR="/tmp/brainstorm-${SESSION_ID}"
+  SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
 fi
 
-PID_FILE="${SCREEN_DIR}/.server.pid"
-LOG_FILE="${SCREEN_DIR}/.server.log"
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+LOG_FILE="${STATE_DIR}/server.log"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
 
-# Create fresh session directory
-mkdir -p "$SCREEN_DIR"
+# Create fresh session directory with content and state peers
+mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
+
+SERVER_ID=""
+if [[ -r /dev/urandom ]]; then
+  SERVER_ID="$(od -An -N24 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || true)"
+fi
+if ! [[ "$SERVER_ID" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
+  SERVER_ID="$(printf '%08x%08x%08x%08x' "$$" "$(date +%s)" "${RANDOM:-0}" "${RANDOM:-0}")"
+fi
+printf '%s\n' "$SERVER_ID" > "$SERVER_ID_FILE"
+chmod 600 "$SERVER_ID_FILE" 2>/dev/null || true
 
 # Kill any existing server
 if [[ -f "$PID_FILE" ]]; then
@@ -96,7 +148,7 @@ if [[ -f "$PID_FILE" ]]; then
   rm -f "$PID_FILE"
 fi
 
-cd "$SCRIPT_DIR"
+cd "$SCRIPT_DIR" || exit 1
 
 # Resolve the harness PID (grandparent of this script).
 # $PPID is the ephemeral shell the harness spawned to run us — it dies
@@ -106,28 +158,32 @@ if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
   OWNER_PID="$PPID"
 fi
 
-# On Windows/MSYS2, the MSYS2 PID namespace is invisible to Node.js.
-# Skip owner-PID monitoring — the 30-minute idle timeout prevents orphans.
-case "${OSTYPE:-}" in
-  msys*|cygwin*|mingw*) OWNER_PID="" ;;
-esac
+# Windows/MSYS2: Node.js cannot see POSIX PIDs from the MSYS2 namespace.
+# Passing a PID node cannot verify causes server to log owner-pid-invalid
+# and self-terminate at the 60-second lifecycle check. Clear it so the
+# watchdog is disabled and the idle timeout becomes the only shutdown trigger.
+if is_windows_like_shell; then
+  OWNER_PID=""
+fi
 
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
-  echo "$$" > "$PID_FILE"
-  env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs
+  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" &
+  SERVER_PID=$!
+  echo "$SERVER_PID" > "$PID_FILE"
+  wait "$SERVER_PID"
   exit $?
 fi
 
 # Start server, capturing output to log file
 # Use nohup to survive shell exit; disown to remove from job table
-nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs > "$LOG_FILE" 2>&1 &
+nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"
 
 # Wait for server-started message (check log file)
-for i in {1..50}; do
+for _ in {1..50}; do
   if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
     # Verify server is still alive after a short window (catches process reapers)
     alive="true"

package/skills/brainstorming/scripts/stop-server.sh

@@ -1,28 +1,92 @@
 #!/usr/bin/env bash
 # Stop the brainstorm server and clean up
-# Usage: stop-server.sh <screen_dir>
+# Usage: stop-server.sh <session_dir>
 #
 # Kills the server process. Only deletes session directory if it's
 # under /tmp (ephemeral). Persistent directories (.superpowers/) are
 # kept so mockups can be reviewed later.
 
-SCREEN_DIR="$1"
+SESSION_DIR="$1"
 
-if [[ -z "$SCREEN_DIR" ]]; then
-  echo '{"error": "Usage: stop-server.sh <screen_dir>"}'
+if [[ -z "$SESSION_DIR" ]]; then
+  echo '{"error": "Usage: stop-server.sh <session_dir>"}'
   exit 1
 fi
 
-PID_FILE="${SCREEN_DIR}/.server.pid"
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+mark_stopped() {
+  local reason="$1"
+  rm -f "${STATE_DIR}/server-info"
+  printf '{"reason":"%s","timestamp":%s}\n' "$reason" "$(date +%s)" > "${STATE_DIR}/server-stopped"
+}
+
+read_expected_server_id() {
+  [[ -f "$SERVER_ID_FILE" ]] || return 1
+  local id
+  id="$(tr -d '\r\n' < "$SERVER_ID_FILE" 2>/dev/null || true)"
+  [[ "$id" =~ ^[A-Za-z0-9_-]{32,64}$ ]] || return 1
+  printf '%s\n' "$id"
+}
+
+command_line_for_pid() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null || true
+    return 0
+  fi
+  ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true
+}
+
+command_has_server_id() {
+  local pid="$1"
+  local expected="$2"
+  local expected_arg="--brainstorm-server-id=$expected"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    local arg
+    while IFS= read -r -d '' arg || [[ -n "$arg" ]]; do
+      [[ "$arg" == "$expected_arg" ]] && return 0
+    done < "/proc/$pid/cmdline"
+    return 1
+  fi
+  local command_line
+  command_line="$(command_line_for_pid "$pid")"
+  [[ -n "$command_line" ]] || return 1
+  case " $command_line " in
+    *" $expected_arg "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Confirm a PID has this session's per-start instance id, not just a familiar
+# process name. Ambiguous or legacy metadata fails closed as stale_pid.
+is_brainstorm_server() {
+  kill -0 "$1" 2>/dev/null || return 1
+  local expected_id
+  expected_id="$(read_expected_server_id)" || return 1
+  command_has_server_id "$1" "$expected_id" || return 1
+  return 0
+}
 
 if [[ -f "$PID_FILE" ]]; then
   pid=$(cat "$PID_FILE")
 
+  # Refuse to signal a PID we can't prove is our server. A stale pid file may
+  # point at an unrelated process after a reboot/PID wraparound.
+  if ! is_brainstorm_server "$pid"; then
+    rm -f "$PID_FILE" "$SERVER_ID_FILE"
+    mark_stopped "stale_pid"
+    echo '{"status": "stale_pid"}'
+    exit 0
+  fi
+
   # Try to stop gracefully, fallback to force if still alive
   kill "$pid" 2>/dev/null || true
 
   # Wait for graceful shutdown (up to ~2s)
-  for i in {1..20}; do
+  for _ in {1..20}; do
     if ! kill -0 "$pid" 2>/dev/null; then
       break
     fi
@@ -42,11 +106,12 @@ if [[ -f "$PID_FILE" ]]; then
     exit 1
   fi
 
-  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
+  rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
+  mark_stopped "stop-server.sh"
 
   # Only delete ephemeral /tmp directories
-  if [[ "$SCREEN_DIR" == /tmp/* ]]; then
-    rm -rf "$SCREEN_DIR"
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
   fi
 
   echo '{"status": "stopped"}'

package/skills/chinese-code-review/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: chinese-code-review
 description: 中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [code-review, chinese]
 ---
 
 # 中文代码审查规范

package/skills/chinese-commit-conventions/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: chinese-commit-conventions
 description: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [git, chinese]
 ---
 
 # 中文 Git 提交规范

package/skills/chinese-documentation/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: chinese-documentation
 description: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [documentation, chinese]
 ---
 
 # 中文技术文档写作规范

package/skills/chinese-git-workflow/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: chinese-git-workflow
 description: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [git, chinese]
 ---
 
 # 国内 Git 工作流规范

package/skills/dispatching-parallel-agents/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: dispatching-parallel-agents
 description: 当面对 2 个以上可以独立进行、无共享状态或顺序依赖的任务时使用
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [agents, parallel]
 ---
 
 # 并行分派智能体

package/skills/executing-plans/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: executing-plans
 description: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [execution, planning]
 ---
 
 # 执行计划
@@ -80,8 +85,8 @@ $ git commit -m "feat: 添加用户输入验证（任务 2/5）"
 --- 任务 2/5 完成 ---
 ```
 
-**批量审查检查点：**
-- 每完成 3 个任务后，暂停回顾：整体方向还对吗？有没有偏离计划？
+**持续自查：**
+- 执行过程中持续留意：整体方向还对吗？有没有偏离计划？
 - 如果发现前面的实现有问题，先修复再继续，不要带着问题往下走
 
 ### 步骤 3：处理常见异常

package/skills/finishing-a-development-branch/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: finishing-a-development-branch
 description: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [git, workflow]
 ---
 
 # 完成开发分支
@@ -9,7 +14,7 @@ description: 当实现完成、所有测试通过、需要决定如何集成工
 
 通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。
 
-**核心原则：** 验证测试 → 展示选项 → 执行选择 → 清理。
+**核心原则：** 验证测试 → 检测环境 → 展示选项 → 执行选择 → 清理。
 
 **开始时宣布：** "我正在使用 finishing-a-development-branch 技能来完成这项工作。"
 
@@ -25,6 +30,7 @@ npm test / cargo test / pytest / go test ./...
 ```
 
 **如果测试失败：**
+
 ```
 测试失败（<N> 个失败）。必须先修复才能继续：
 
@@ -37,7 +43,24 @@ npm test / cargo test / pytest / go test ./...
 
 **如果测试通过：** 继续步骤 2。
 
-### 步骤 2：确定基础分支
+### 步骤 2：检测环境
+
+**在展示选项之前，先确定工作区状态：**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+这决定了展示哪种菜单、以及清理方式：
+
+| 状态 | 菜单 | 清理 |
+|------|------|------|
+| `GIT_DIR == GIT_COMMON`（普通仓库） | 标准 4 个选项 | 无 worktree 可清理 |
+| `GIT_DIR != GIT_COMMON`，命名分支 | 标准 4 个选项 | 按来源判断（见步骤 6） |
+| `GIT_DIR != GIT_COMMON`，分离 HEAD | 收敛 3 个选项（无合并） | 无清理（由外部管理） |
+
+### 步骤 3：确定基础分支
 
 ```bash
 # 尝试常见的基础分支
@@ -46,9 +69,9 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 
 或者询问："这个分支是从 main 分出来的——对吗？"
 
-### 步骤 3：展示选项
+### 步骤 4：展示选项
 
-展示以下 4 个选项：
+**普通仓库和命名分支 worktree —— 准确展示以下 4 个选项：**
 
 ```
 实现已完成。你想怎么做？
@@ -61,30 +84,45 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 选哪个？
 ```
 
-**不要添加解释** - 保持选项简洁。
+**分离 HEAD —— 准确展示以下 3 个选项：**
+
+```
+实现已完成。你在分离 HEAD 上（由外部管理的工作区）。
+
+1. 作为新分支推送并创建 Pull Request
+2. 保持现状（我稍后处理）
+3. 丢弃这项工作
+
+选哪个？
+```
+
+**不要添加解释** —— 保持选项简洁。
 
-### 步骤 4：执行选择
+### 步骤 5：执行选择
 
 #### 选项 1：本地合并
 
 ```bash
-# 切换到基础分支
-git checkout <base-branch>
+# 切到主仓库根目录，保证 CWD 安全
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
 
-# 拉取最新代码
+# 先合并 —— 在删除任何东西之前先验证合并成功
+git checkout <base-branch>
 git pull
-
-# 合并功能分支
 git merge <feature-branch>
 
 # 在合并结果上验证测试
 <test command>
 
-# 如果测试通过
-git branch -d <feature-branch>
+# 合并成功之后再：清理 worktree（步骤 6），然后删除分支
 ```
 
-然后：清理工作树（步骤 5）
+然后：清理 worktree（步骤 6），再删除分支：
+
+```bash
+git branch -d <feature-branch>
+```
 
 #### 选项 2：推送并创建 PR
 
@@ -103,7 +141,7 @@ EOF
 )"
 ```
 
-然后：清理工作树（步骤 5）
+**不要清理 worktree** —— 用户在 PR 反馈迭代时还需要它存活。
 
 #### 选项 3：保持现状
 
@@ -114,6 +152,7 @@ EOF
 #### 选项 4：丢弃
 
 **先确认：**
+
 ```
 这将永久删除：
 - 分支 <name>
@@ -126,28 +165,40 @@ EOF
 等待精确的确认。
 
 确认后：
+
 ```bash
-git checkout <base-branch>
-git branch -D <feature-branch>
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
 ```
 
-然后：清理工作树（步骤 5）
+然后：清理 worktree（步骤 6），再强制删除分支：
+
+```bash
+git branch -D <feature-branch>
+```
 
-### 步骤 5：清理工作树
+### 步骤 6：清理工作区
 
-**对于选项 1、2、4：**
+**只对选项 1 和 4 执行。** 选项 2 和 3 始终保留 worktree。
 
-检查是否在工作树中：
 ```bash
-git worktree list | grep $(git branch --show-current)
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 
-如果是：
+**如果 `GIT_DIR == GIT_COMMON`：** 普通仓库，无 worktree 可清理。结束。
+
+**如果 worktree 路径在 `.worktrees/` 或 `worktrees/` 之下：** 这是 Superpowers 创建的 worktree —— 我们负责清理。
+
 ```bash
-git worktree remove <worktree-path>
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # 自愈：清理任何过期的注册记录
 ```
 
-**对于选项 3：** 保留工作树。
+**否则：** 这个工作区由宿主环境（harness）管理。**不要**移除它。如果你的平台提供了工作区退出工具，用它。否则原样保留工作区。
 
 ## 快速参考
 
@@ -161,40 +212,69 @@ git worktree remove <worktree-path>
 ## 常见错误
 
 **跳过测试验证**
+
 - **问题：** 合并损坏的代码、创建失败的 PR
 - **修复：** 在提供选项前始终验证测试
 
 **开放式问题**
+
 - **问题：** "接下来该做什么？" → 含糊不清
-- **修复：** 准确展示 4 个结构化选项
+- **修复：** 准确展示 4 个结构化选项（分离 HEAD 时是 3 个）
+
+**为选项 2 清理 worktree**
 
-**自动清理工作树**
-- **问题：** 在可能还需要工作树时就删除了（选项 2、3）
+- **问题：** 删掉用户 PR 迭代还需要的 worktree
 - **修复：** 只在选项 1 和 4 时清理
 
+**先删分支再删 worktree**
+
+- **问题：** `git branch -d` 失败，因为 worktree 还引用着该分支
+- **修复：** 先合并，再删 worktree，最后删分支
+
+**在 worktree 内部跑 `git worktree remove`**
+
+- **问题：** 当 CWD 在被删除的 worktree 内时，命令静默失败
+- **修复：** 跑 `git worktree remove` 前先 `cd` 到主仓库根目录
+
+**清理 harness 拥有的 worktree**
+
+- **问题：** 移除 harness 创建的 worktree 会造成幻影状态
+- **修复：** 只清理 `.worktrees/` 或 `worktrees/` 下的 worktree
+
 **丢弃时不确认**
+
 - **问题：** 意外删除工作成果
-- **修复：** 要求输入 "discard" 确认
+- **修复：** 要求输入 'discard' 确认
 
 ## 红线
 
 **绝不：**
+
 - 在测试失败时继续
-- 合并前不验证测试结果
+- 合并前不验证合并结果上的测试
 - 不确认就删除工作成果
 - 未经明确请求就强制推送
+- 在确认合并成功之前移除 worktree
+- 清理不是你创建的 worktree（按来源判断）
+- 在 worktree 内部跑 `git worktree remove`
 
 **始终：**
+
 - 在提供选项前验证测试
-- 准确展示 4 个选项
+- 展示菜单前检测环境
+- 准确展示 4 个选项（分离 HEAD 时是 3 个）
 - 选项 4 要求输入确认
-- 只在选项 1 和 4 时清理工作树
+- 只在选项 1 和 4 时清理 worktree
+- 移除 worktree 前 `cd` 到主仓库根目录
+- 移除后跑 `git worktree prune`
 
 ## 集成
 
 **被以下技能调用：**
+
 - **subagent-driven-development**（步骤 7）- 所有任务完成后
 - **executing-plans**（步骤 5）- 所有批次完成后
 
 **配合使用：**
+
 - **using-git-worktrees** - 清理由该技能创建的工作树

package/skills/mcp-builder/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: mcp-builder
 description: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [mcp, development]
 ---
 
 # MCP 服务器构建

package/skills/receiving-code-review/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: receiving-code-review
 description: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [code-review]
 ---
 
 # 接收代码审查