superpowers-zh 1.3.0 → 1.5.0

package/skills/brainstorming/scripts/server.cjs

@@ -76,8 +76,10 @@ function decodeFrame(buffer) {
 const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
 const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
 const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
-const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
-const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
+const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
+const CONTENT_DIR = path.join(SESSION_DIR, 'content');
+const STATE_DIR = path.join(SESSION_DIR, 'state');
+let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
 
 const MIME_TYPES = {
   '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
@@ -112,10 +114,10 @@ function wrapInFrame(content) {
 }
 
 function getNewestScreen() {
-  const files = fs.readdirSync(SCREEN_DIR)
+  const files = fs.readdirSync(CONTENT_DIR)
     .filter(f => f.endsWith('.html'))
     .map(f => {
-      const fp = path.join(SCREEN_DIR, f);
+      const fp = path.join(CONTENT_DIR, f);
       return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
     })
     .sort((a, b) => b.mtime - a.mtime);
@@ -142,7 +144,7 @@ function handleRequest(req, res) {
     res.end(html);
   } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
     const fileName = req.url.slice(7);
-    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    const filePath = path.join(CONTENT_DIR, path.basename(fileName));
     if (!fs.existsSync(filePath)) {
       res.writeHead(404);
       res.end('Not found');
@@ -230,7 +232,7 @@ function handleMessage(text) {
   touchActivity();
   console.log(JSON.stringify({ source: 'user-event', ...event }));
   if (event.choice) {
-    const eventsFile = path.join(SCREEN_DIR, '.events');
+    const eventsFile = path.join(STATE_DIR, 'events');
     fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
   }
 }
@@ -258,32 +260,33 @@ const debounceTimers = new Map();
 // ========== Server Startup ==========
 
 function startServer() {
-  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+  if (!fs.existsSync(CONTENT_DIR)) fs.mkdirSync(CONTENT_DIR, { recursive: true });
+  if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
 
   // Track known files to distinguish new screens from updates.
   // macOS fs.watch reports 'rename' for both new files and overwrites,
   // so we can't rely on eventType alone.
   const knownFiles = new Set(
-    fs.readdirSync(SCREEN_DIR).filter(f => f.endsWith('.html'))
+    fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html'))
   );
 
   const server = http.createServer(handleRequest);
   server.on('upgrade', handleUpgrade);
 
-  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
+  const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => {
     if (!filename || !filename.endsWith('.html')) return;
 
     if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
     debounceTimers.set(filename, setTimeout(() => {
       debounceTimers.delete(filename);
-      const filePath = path.join(SCREEN_DIR, filename);
+      const filePath = path.join(CONTENT_DIR, filename);
 
       if (!fs.existsSync(filePath)) return; // file was deleted
       touchActivity();
 
       if (!knownFiles.has(filename)) {
         knownFiles.add(filename);
-        const eventsFile = path.join(SCREEN_DIR, '.events');
+        const eventsFile = path.join(STATE_DIR, 'events');
         if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
         console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
       } else {
@@ -297,10 +300,10 @@ function startServer() {
 
   function shutdown(reason) {
     console.log(JSON.stringify({ type: 'server-stopped', reason }));
-    const infoFile = path.join(SCREEN_DIR, '.server-info');
+    const infoFile = path.join(STATE_DIR, 'server-info');
     if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
     fs.writeFileSync(
-      path.join(SCREEN_DIR, '.server-stopped'),
+      path.join(STATE_DIR, 'server-stopped'),
       JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
     );
     watcher.close();
@@ -309,8 +312,8 @@ function startServer() {
   }
 
   function ownerAlive() {
-    if (!OWNER_PID) return true;
-    try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
+    if (!ownerPid) return true;
+    try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
   }
 
   // Check every 60s: exit if owner process died or idle for 30 minutes
@@ -320,14 +323,27 @@ function startServer() {
   }, 60 * 1000);
   lifecycleCheck.unref();
 
+  // Validate owner PID at startup. If it's already dead, the PID resolution
+  // was wrong (common on WSL, Tailscale SSH, and cross-user scenarios).
+  // Disable monitoring and rely on the idle timeout instead.
+  if (ownerPid) {
+    try { process.kill(ownerPid, 0); }
+    catch (e) {
+      if (e.code !== 'EPERM') {
+        console.log(JSON.stringify({ type: 'owner-pid-invalid', pid: ownerPid, reason: 'dead at startup' }));
+        ownerPid = null;
+      }
+    }
+  }
+
   server.listen(PORT, HOST, () => {
     const info = JSON.stringify({
       type: 'server-started', port: Number(PORT), host: HOST,
       url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
-      screen_dir: SCREEN_DIR
+      screen_dir: CONTENT_DIR, state_dir: STATE_DIR
     });
     console.log(info);
-    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n');
   });
 }
 

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

@@ -78,16 +78,17 @@ fi
 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}"
 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"
 
-# Create fresh session directory
-mkdir -p "$SCREEN_DIR"
+# Create fresh session directory with content and state peers
+mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
 
 # Kill any existing server
 if [[ -f "$PID_FILE" ]]; then
@@ -106,22 +107,16 @@ 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
-
 # 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
   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 > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"

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

@@ -1,19 +1,20 @@
 #!/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"
 
 if [[ -f "$PID_FILE" ]]; then
   pid=$(cat "$PID_FILE")
@@ -42,11 +43,11 @@ if [[ -f "$PID_FILE" ]]; then
     exit 1
   fi
 
-  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
+  rm -f "$PID_FILE" "${STATE_DIR}/server.log"
 
   # 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/finishing-a-development-branch/SKILL.md

@@ -9,7 +9,7 @@ description: 当实现完成、所有测试通过、需要决定如何集成工
 
 通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。
 
-**核心原则：** 验证测试 → 展示选项 → 执行选择 → 清理。
+**核心原则：** 验证测试 → 检测环境 → 展示选项 → 执行选择 → 清理。
 
 **开始时宣布：** "我正在使用 finishing-a-development-branch 技能来完成这项工作。"
 
@@ -25,6 +25,7 @@ npm test / cargo test / pytest / go test ./...
 ```
 
 **如果测试失败：**
+
 ```
 测试失败（<N> 个失败）。必须先修复才能继续：
 
@@ -37,7 +38,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 +64,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 +79,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 +136,7 @@ EOF
 )"
 ```
 
-然后：清理工作树（步骤 5）
+**不要清理 worktree** —— 用户在 PR 反馈迭代时还需要它存活。
 
 #### 选项 3：保持现状
 
@@ -114,6 +147,7 @@ EOF
 #### 选项 4：丢弃
 
 **先确认：**
+
 ```
 这将永久删除：
 - 分支 <name>
@@ -126,28 +160,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/` 或 `~/.config/superpowers/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 +207,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/` 或 `~/.config/superpowers/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/requesting-code-review/SKILL.md

@@ -5,7 +5,7 @@ description: 完成任务、实现重要功能或合并前使用，用于验证
 
 # 请求代码审查
 
-派遣 superpowers:code-reviewer 子代理来在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。这样可以让审查者专注于工作成果而非你的思考过程，同时保留你自己的上下文以便继续工作。
+派遣代码审查子代理，在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。这样可以让审查者专注于工作成果而非你的思考过程，同时保留你自己的上下文以便继续工作。
 
 **核心原则：** 早审查，勤审查。
 
@@ -29,16 +29,15 @@ BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. 派遣 code-reviewer 子代理：**
+**2. 派遣代码审查子代理：**
 
-使用 Task 工具，指定 superpowers:code-reviewer 类型，填写 `code-reviewer.md` 中的模板
+使用 Task 工具，指定 `general-purpose` 类型，填写 `code-reviewer.md` 中的模板
 
 **占位符说明：**
-- `{WHAT_WAS_IMPLEMENTED}` - 你刚完成的内容
+- `{DESCRIPTION}` - 你刚完成的内容简要说明
 - `{PLAN_OR_REQUIREMENTS}` - 预期功能
 - `{BASE_SHA}` - 起始提交
 - `{HEAD_SHA}` - 结束提交
-- `{DESCRIPTION}` - 简要说明
 
 **3. 处理反馈：**
 - Critical 问题立即修复
@@ -56,12 +55,11 @@ HEAD_SHA=$(git rev-parse HEAD)
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[派遣 superpowers:code-reviewer 子代理]
-  WHAT_WAS_IMPLEMENTED: 会话索引的验证和修复功能
+[派遣代码审查子代理]
+  DESCRIPTION: 添加了 verifyIndex() 和 repairIndex()，支持 4 种问题类型
   PLAN_OR_REQUIREMENTS: docs/superpowers/plans/deployment-plan.md 中的任务 2
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
-  DESCRIPTION: 添加了 verifyIndex() 和 repairIndex()，支持 4 种问题类型
 
 [子代理返回]:
   优点：架构清晰，测试真实
@@ -82,8 +80,8 @@ HEAD_SHA=$(git rev-parse HEAD)
 - 修复后再进入下一个任务
 
 **执行计划：**
-- 每批（3 个任务）后审查
-- 获取反馈，修复，继续
+- 每个任务完成后或在自然 checkpoint 审查
+- 获取反馈，应用，继续
 
 **临时开发：**
 - 合并前审查