diff --git a/zh-CN/CHANGELOG.md b/zh-CN/CHANGELOG.md
new file mode 100644
index 0000000000..5f290069df
--- /dev/null
+++ b/zh-CN/CHANGELOG.md
@@ -0,0 +1,13 @@
+# 更新日志
+
+## \[5.0.5] - 2026-03-17
+
+### 修复
+
+* **Brainstorm 服务器 ESM 修复**：将 `server.js` 重命名为 `server.cjs`，以便 Brainstorm 服务器在 Node.js 22+ 上正确启动，因为在 Node.js 22+ 中，根目录的 `package.json` `"type": "module"` 会导致 `require()` 失败。([PR #784](https://github.com/obra/superpowers/pull/784) 由 @sarbojitrana 提交，修复了 [#774](https://github.com/obra/superpowers/issues/774), [#780](https://github.com/obra/superpowers/issues/780), [#783](https://github.com/obra/superpowers/issues/783))
+* **Brainstorm 在 Windows 上的所有者进程 PID**：在 Windows/MSYS2 上跳过 `BRAINSTORM_OWNER_PID` 生命周期监控，因为其 PID 命名空间对 Node.js 不可见。防止服务器在 60 秒后自行终止。30 分钟的空闲超时仍作为安全网保留。([#770](https://github.com/obra/superpowers/issues/770)，文档来自 [PR #768](https://github.com/obra/superpowers/pull/768) 由 @lucasyhzhu-debug 提交)
+* **stop-server.sh 可靠性**：在报告成功之前，验证服务器进程是否确实已终止。等待最多 2 秒以进行正常关闭，然后升级到 `SIGKILL`，如果进程仍然存活则报告失败。([#723](https://github.com/obra/superpowers/issues/723))
+
+### 变更
+
+* **执行交接**：恢复用户在计划编写后，在子代理驱动开发和执行计划之间的选择。子代理驱动是推荐的，但不再是强制性的。(撤销 `5e51c3e`)
diff --git a/zh-CN/CODE_OF_CONDUCT.md b/zh-CN/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000000..e24ac17dfa
--- /dev/null
+++ b/zh-CN/CODE_OF_CONDUCT.md
@@ -0,0 +1,84 @@
+# 贡献者公约行为准则
+
+## 我们的承诺
+
+我们作为成员、贡献者和领导者承诺，无论年龄、体型、可见或不可见的残疾、民族、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、个人外貌、种族、宗教信仰或性取向与性认同如何，都将使参与我们社区成为对所有人无骚扰的体验。
+
+我们承诺以促进开放、友善、多元、包容和健康社区的方式行事和互动。
+
+## 我们的标准
+
+有助于为我们社区创造积极环境的行为示例包括：
+
+* 对他人表现出同理心和善意
+* 尊重不同的意见、观点和经验
+* 给予并优雅地接受建设性反馈
+* 承担责任，向受我们错误影响的人道歉，并从经验中学习
+* 关注不仅对我们个人，而且对整个社区最有利的事情
+
+不可接受的行为示例包括：
+
+* 使用带有性暗示的语言或图像，以及任何形式的性关注或性挑逗
+* 挑衅、侮辱或贬损性评论，以及个人或政治攻击
+* 公开或私下的骚扰
+* 未经他人明确许可，发布他人的私人信息，例如物理地址或电子邮件地址
+* 其他在专业环境中可能被视为不当的行为
+
+## 执行责任
+
+社区领导者有责任澄清和执行我们的可接受行为标准，并将对他们认为不当、威胁、冒犯或有害的任何行为采取适当且公平的纠正措施。
+
+社区领导者有权且有责任删除、编辑或拒绝与行为准则不符的评论、提交、代码、维基编辑、问题和其他贡献，并将在适当时沟通审核决定的原因。
+
+## 适用范围
+
+本行为准则适用于所有社区空间，也适用于个人在公共空间正式代表社区的情况。代表我们社区的示例包括使用官方电子邮件地址、通过官方社交媒体账户发帖，或在线上或线下活动中担任指定代表。
+
+## 执行
+
+虐待、骚扰或其他不可接受行为的实例可以向负责执行的社区领导者报告，邮箱为 jesse@primeradiant.com。
+所有投诉都将得到及时和公平的审查和调查。
+
+所有社区领导者都有义务尊重任何事件报告者的隐私和安全。
+
+## 执行指南
+
+社区领导者将遵循以下社区影响指南，确定他们认为违反本行为准则的任何行为的后果：
+
+### 1. 纠正
+
+**社区影响**：使用不当语言或其他在社区中被视为不专业或不受欢迎的行为。
+
+**后果**：社区领导者发出私人的书面警告，明确说明违规性质，并解释为何该行为不当。可能会要求公开道歉。
+
+### 2. 警告
+
+**社区影响**：通过单个事件或一系列行为造成的违规。
+
+**后果**：带有持续行为后果的警告。在规定时间内，不得与相关人员互动，包括与行为准则执行者进行未经请求的互动。这包括避免在社区空间以及社交媒体等外部渠道的互动。违反这些条款可能导致暂时或永久封禁。
+
+### 3. 暂时封禁
+
+**社区影响**：严重违反社区标准，包括持续的不当行为。
+
+**后果**：在规定时间内，禁止与社区进行任何形式的互动或公开交流。在此期间，不允许与相关人员（包括行为准则执行者）进行公开或私下的互动。违反这些条款可能导致永久封禁。
+
+### 4. 永久封禁
+
+**社区影响**：表现出违反社区标准的模式，包括持续的不当行为、对个人的骚扰，或对某类人群的攻击或贬低。
+
+**后果**：永久禁止在社区内进行任何形式的公开互动。
+
+## 致谢
+
+本行为准则改编自 \[Contributor Covenant]\[homepage]，
+版本 2.0，可在
+https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html 获取。
+
+社区影响指南的灵感来自 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity)。
+
+[homepage]: https://www.contributor-covenant.org
+
+有关本行为准则常见问题的解答，请参阅常见问题解答页面：
+https://www.contributor-covenant.org/faq。翻译版本可在
+https://www.contributor-covenant.org/translations 获取。
diff --git a/zh-CN/GEMINI.md b/zh-CN/GEMINI.md
new file mode 100644
index 0000000000..0dd2f585ec
--- /dev/null
+++ b/zh-CN/GEMINI.md
@@ -0,0 +1,2 @@
+@./skills/using-superpowers/SKILL.md
+@./skills/using-superpowers/references/gemini-tools.md
diff --git a/zh-CN/README.md b/zh-CN/README.md
new file mode 100644
index 0000000000..ec6276c08d
--- /dev/null
+++ b/zh-CN/README.md
@@ -0,0 +1,189 @@
+# Superpowers
+
+Superpowers 是一个为您的编程智能体构建的完整软件开发工作流，它建立在一组可组合的“技能”和一些初始指令之上，确保您的智能体能够正确使用它们。
+
+## 工作原理
+
+它从您启动编程智能体的那一刻开始。一旦它发现您正在构建某些东西，它*不会*直接跳入尝试编写代码。相反，它会退一步，询问您真正想要实现的目标。
+
+一旦它从对话中梳理出需求规格，它会以足够简短、便于您实际阅读和消化的块状形式展示给您。
+
+在您确认设计之后，您的智能体会制定一个足够清晰的实施计划，即使是一个品味不佳、缺乏判断力、没有项目背景且厌恶测试的热心初级工程师也能遵循。它强调真正的红/绿测试驱动开发、YAGNI（您不会需要它）和 DRY 原则。
+
+接下来，一旦您说“开始”，它会启动一个*子智能体驱动开发*过程，让智能体们处理每个工程任务，检查和评审他们的工作，并持续推进。Claude 通常能够自主工作数小时而不偏离您制定的计划。
+
+其中还有更多内容，但这是系统的核心。由于技能会自动触发，您无需做任何特殊操作。您的编程智能体就拥有了 Superpowers。
+
+## 赞助
+
+如果 Superpowers 帮助您完成了能赚钱的事情，并且您有意愿，如果您能考虑[赞助我的开源工作](https://github.com/sponsors/obra)，我将不胜感激。
+
+谢谢！
+
+* Jesse
+
+## 安装
+
+**注意：** 安装方式因平台而异。Claude Code 或 Cursor 有内置的插件市场。Codex 和 OpenCode 需要手动设置。
+
+### Claude Code 官方市场
+
+Superpowers 可通过[官方 Claude 插件市场](https://claude.com/plugins/superpowers)获取
+
+从 Claude 市场安装插件：
+
+```bash
+/plugin install superpowers@claude-plugins-official
+```
+
+### Claude Code（通过插件市场）
+
+在 Claude Code 中，首先注册市场：
+
+```bash
+/plugin marketplace add obra/superpowers-marketplace
+```
+
+然后从此市场安装插件：
+
+```bash
+/plugin install superpowers@superpowers-marketplace
+```
+
+### Cursor（通过插件市场）
+
+在 Cursor Agent 聊天中，从市场安装：
+
+```text
+/add-plugin superpowers
+```
+
+或在插件市场中搜索“superpowers”。
+
+### Codex
+
+告诉 Codex：
+
+```
+从 https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md 获取并遵循说明。
+```
+
+**详细文档：** [docs/README.codex.md](docs/README.codex.md)
+
+### OpenCode
+
+告诉 OpenCode：
+
+```
+从 https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md 获取并遵循说明。
+```
+
+**详细文档：** [docs/README.opencode.md](docs/README.opencode.md)
+
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/obra/superpowers
+```
+
+要更新：
+
+```bash
+gemini extensions update superpowers
+```
+
+### 验证安装
+
+在您选择的平台中启动一个新会话，并询问一些应该触发技能的事情（例如，“帮我规划这个功能”或“我们来调试这个问题”）。智能体应该会自动调用相关的 superpowers 技能。
+
+## 基本工作流程
+
+1. **头脑风暴** - 在编写代码前激活。通过提问完善粗略想法，探索替代方案，分部分呈现设计以供验证。保存设计文档。
+
+2. **使用 Git 工作树** - 在设计批准后激活。在新分支上创建隔离的工作区，运行项目设置，验证干净的测试基线。
+
+3. **编写计划** - 在批准设计后激活。将工作分解成小块任务（每个 2-5 分钟）。每个任务都有确切的文件路径、完整代码、验证步骤。
+
+4. **子智能体驱动开发** 或 **执行计划** - 在计划制定后激活。为每个任务派遣新的子智能体，进行两阶段评审（规范符合性，然后是代码质量），或者分批执行并设置人工检查点。
+
+5. **测试驱动开发** - 在实施过程中激活。强制执行 RED-GREEN-REFACTOR 循环：编写失败测试，观察其失败，编写最小化代码，观察其通过，提交。删除在测试之前编写的代码。
+
+6. **请求代码审查** - 在任务之间激活。对照计划进行审查，按严重程度报告问题。关键问题会阻止进展。
+
+7. **完成开发分支** - 在任务完成时激活。验证测试，呈现选项（合并/PR/保留/丢弃），清理工作树。
+
+**智能体在任何任务前都会检查相关技能。** 这是强制性的工作流程，而非建议。
+
+## 包含内容
+
+### 技能库
+
+**测试**
+
+* **测试驱动开发** - RED-GREEN-REFACTOR 循环（包含测试反模式参考）
+
+**调试**
+
+* **系统化调试** - 4 阶段根本原因分析过程（包含根本原因追溯、深度防御、条件等待技术）
+* **完成前验证** - 确保问题真正解决
+
+**协作**
+
+* **头脑风暴** - 苏格拉底式设计完善
+* **编写计划** - 详细的实施计划
+* **执行计划** - 带检查点的批量执行
+* **派遣并行智能体** - 并发子智能体工作流
+* **请求代码审查** - 预审查清单
+* **接收代码审查** - 响应反馈
+* **使用 Git 工作树** - 并行开发分支
+* **完成开发分支** - 合并/PR 决策工作流
+* **子智能体驱动开发** - 带两阶段评审（规范符合性，然后是代码质量）的快速迭代
+
+**元技能**
+
+* **编写技能** - 遵循最佳实践创建新技能（包含测试方法）
+* **使用 superpowers** - 技能系统介绍
+
+## 理念
+
+* **测试驱动开发** - 始终先写测试
+* **系统化优于临时性** - 流程优于猜测
+* **降低复杂性** - 以简洁为主要目标
+* **证据优于断言** - 在宣布成功前进行验证
+
+阅读更多：[适用于 Claude Code 的 Superpowers](https://blog.fsck.com/2025/10/09/superpowers/)
+
+## 贡献
+
+技能直接存放在此代码库中。要贡献：
+
+1. 分叉此代码库
+2. 为您的技能创建一个分支
+3. 遵循 `writing-skills` 技能来创建和测试新技能
+4. 提交 PR
+
+查看 `skills/writing-skills/SKILL.md` 获取完整指南。
+
+## 更新
+
+当您更新插件时，技能会自动更新：
+
+```bash
+/plugin update superpowers
+```
+
+## 许可证
+
+MIT 许可证 - 详见 LICENSE 文件
+
+## 社区
+
+Superpowers 由 [Jesse Vincent](https://blog.fsck.com) 和 [Prime Radiant](https://primeradiant.com) 的其他成员共同构建。
+
+如需社区支持、问题咨询，或分享您使用 Superpowers 构建的项目，欢迎加入我们的 [Discord](https://discord.gg/Jd8Vphy9jq)。
+
+## 支持
+
+* **Discord**：[加入我们的 Discord](https://discord.gg/Jd8Vphy9jq)
+* **问题反馈**：https://github.com/obra/superpowers/issues
+* **市场**：https://github.com/obra/superpowers-marketplace
diff --git a/zh-CN/RELEASE-NOTES.md b/zh-CN/RELEASE-NOTES.md
new file mode 100644
index 0000000000..8456b3b1fc
--- /dev/null
+++ b/zh-CN/RELEASE-NOTES.md
@@ -0,0 +1,1102 @@
+# Superpowers 发布说明
+
+## v5.0.5 (2026-03-17)
+
+### 错误修复
+
+* **Brainstorm 服务器 ESM 修复** — 将 `server.js` 重命名为 `server.cjs`，使得 Brainstorming 服务器能在 Node.js 22+ 上正确启动，在这些版本中，根目录的 `package.json` `"type": "module"` 会导致 `require()` 失败。(PR #784 by @sarbojitrana，修复 #774, #780, #783)
+* **Brainstorm 在 Windows 上的所有者 PID** — 在 Windows/MSYS2 上跳过 PID 生命周期监控，因为 Node.js 无法看到其 PID 命名空间，从而防止服务器在 60 秒后自行终止。(#770，文档来自 PR #768 by @lucasyhzlu-debug)
+* **stop-server.sh 可靠性提升** — 在报告成功之前，验证服务器进程确实已终止。采用 SIGTERM + 等待 2 秒 + SIGKILL 备选方案。(#723)
+
+### 已更改
+
+* **执行移交** — 在计划编写后，恢复用户在子代理驱动执行和内联执行之间的选择。推荐使用子代理驱动，但不再是强制性的。
+
+## v5.0.4 (2026-03-16)
+
+### 审查循环优化
+
+通过消除不必要的审查轮次和收紧审查者关注点，显著减少了令牌使用量，并加速了规范和计划的审查。
+
+* **单次完整计划审查** — 计划审查者现在一次性审查完整计划，而不是分块审查。移除了所有与分块相关的概念（`## Chunk N:` 标题、1000 行分块限制、每块调度）。
+* **提高了阻塞问题的门槛** — 规范和计划审查者的提示现在都包含一个“校准”部分：仅标记那些会在实施过程中导致实际问题的项目。轻微的措辞、风格偏好和格式上的吹毛求疵不应阻止批准。
+* **减少了最大审查迭代次数** — 规范和计划审查循环都从 5 次减少到 3 次。如果审查者校准正确，3 轮就足够了。
+* **精简了审查者清单** — 规范审查者从 7 个类别精简到 5 个；计划审查者从 7 个精简到 4 个。移除了以格式为重点的检查（任务语法、分块大小），转而关注实质内容（可构建性、规范一致性）。
+
+### OpenCode
+
+* **单行插件安装** — OpenCode 插件现在通过一个 `config` 钩子自动注册技能目录。不再需要符号链接或 `skills.paths` 配置。安装只需在 `opencode.json` 中添加一行。(PR #753)
+* **添加了 `package.json`**，以便 OpenCode 可以从 git 安装 superpowers 作为 npm 包。
+
+### 错误修复
+
+* **验证服务器确实已停止** — `stop-server.sh` 现在会在报告成功之前确认进程已终止。采用 SIGTERM + 等待 2 秒 + SIGKILL 备选方案。如果进程存活，则报告失败。(PR #751)
+* **通用代理语言** — brainstorm 伴侣等待页面现在说“代理”而不是“Claude”。
+
+## v5.0.3 (2026-03-15)
+
+### Cursor 支持
+
+* **Cursor 钩子** — 添加了 `hooks/hooks-cursor.json`，采用 Cursor 的驼峰命名格式（`sessionStart`，`version: 1`），并更新了 `.cursor-plugin/plugin.json` 以引用它。修复了 `session-start` 中的平台检测，优先检查 `CURSOR_PLUGIN_ROOT`（Cursor 也可能设置 `CLAUDE_PLUGIN_ROOT`）。(基于 PR #709)
+
+### 错误修复
+
+* **停止在 `--resume` 时触发 SessionStart 钩子** — 启动钩子会在恢复的会话中重新注入上下文，而这些会话的对话历史中已经包含了上下文。该钩子现在仅在 `startup`、`clear` 和 `compact` 时触发。
+* **Bash 5.3+ 钩子挂起** — 在 `hooks/session-start` 中用 `printf` 替换了 heredoc（`cat <<EOF`）。修复了在 macOS 上使用 Homebrew bash 5.3+ 时，由于 bash 在处理 heredoc 中大变量扩展时的回归问题导致的无限期挂起。(#572, #571)
+* **POSIX 安全的钩子脚本** — 在 `hooks/session-start` 中用 `$0` 替换了 `${BASH_SOURCE[0]:-$0}`。修复了在 Ubuntu/Debian 上（其中 `/bin/sh` 是 dash）出现的“Bad substitution”错误。(#553)
+* **可移植的 shebang** — 在所有 shell 脚本中用 `#!/usr/bin/env bash` 替换了 `#!/bin/bash`。修复了在 NixOS、FreeBSD 和 macOS（使用 Homebrew bash）上，因 `/bin/bash` 过时或缺失而导致的执行问题。(#700)
+* **Brainstorm 服务器在 Windows 上** — 自动检测 Windows/Git Bash（`OSTYPE=msys*`，`MSYSTEM`）并切换到前台模式，修复了因 `nohup`/`disown` 进程回收导致的服务器静默失败问题。(#737)
+* **Codex 文档修复** — 在 Codex 文档中用 `multi_agent` 替换了已弃用的 `collab` 标志。(PR #749)
+
+## v5.0.2 (2026-03-11)
+
+### 零依赖头脑风暴服务器
+
+**移除所有打包的 node\_modules — server.js 现已完全自包含**
+
+* 用零依赖的 Node.js 服务器替换了 Express/Chokidar/WebSocket 依赖项，使用内置的 `http`、`fs` 和 `crypto` 模块
+* 移除了约 1,200 行打包的 `node_modules/`、`package.json` 和 `package-lock.json`
+* 自定义 WebSocket 协议实现（RFC 6455 帧处理、ping/pong、正确的关闭握手）
+* 原生的 `fs.watch()` 文件监视替换了 Chokidar
+* 完整的测试套件：HTTP 服务、WebSocket 协议、文件监视和集成测试
+
+### 头脑风暴服务器可靠性
+
+* **空闲 30 分钟后自动退出** — 当没有客户端连接时，服务器关闭，防止产生孤儿进程
+* **所有者进程追踪** — 服务器监控父进程的 PID，当所属会话终止时退出
+* **活跃性检查** — 技能在重用现有实例前验证服务器是否响应
+* **编码修复** — 在提供的 HTML 页面上使用正确的 `<meta charset="utf-8">`
+
+### 子代理上下文隔离
+
+* 所有委派技能（头脑风暴、并行代理调度、请求代码审查、子代理驱动开发、编写计划）现在都包含上下文隔离原则
+* 子代理仅接收它们所需的上下文，防止上下文窗口污染
+
+## v5.0.1 (2026-03-10)
+
+### Agentskills 合规性
+
+**Brainstorm-server 移至技能目录**
+
+* 根据 [agentskills.io](https://agentskills.io) 规范，将 `lib/brainstorm-server/` 移至 `skills/brainstorming/scripts/`
+* 所有 `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/` 引用替换为相对的 `scripts/` 路径
+* 技能现在完全跨平台可移植 — 无需平台特定的环境变量来定位脚本
+* 删除了 `lib/` 目录（这是最后剩余的内容）
+
+### 新功能
+
+**Gemini CLI 扩展**
+
+* 通过仓库根目录的 `gemini-extension.json` 和 `GEMINI.md` 实现原生的 Gemini CLI 扩展支持
+* `GEMINI.md` 在会话开始时 @imports `using-superpowers` 技能和工具映射表
+* Gemini CLI 工具映射参考（`skills/using-superpowers/references/gemini-tools.md`）— 将 Claude Code 工具名称（Read、Write、Edit、Bash 等）翻译为 Gemini CLI 等效项（read\_file、write\_file、replace 等）
+* 记录了 Gemini CLI 的限制：无子代理支持，技能回退到 `executing-plans`
+* 扩展根目录位于仓库根目录以实现跨平台兼容性（避免 Windows 符号链接问题）
+* 安装说明已添加到 README
+
+### 改进
+
+**多平台头脑风暴服务器启动**
+
+* visual-companion.md 中的每平台启动说明：Claude Code（默认模式）、Codex（通过 `CODEX_CI` 自动前台运行）、Gemini CLI（带有 `--foreground` 的 `is_background`）以及其他环境的回退方案
+* 服务器现在将启动 JSON 写入 `$SCREEN_DIR/.server-info`，以便代理即使在后台执行隐藏了 stdout 时也能找到 URL 和端口
+
+**头脑风暴服务器依赖项打包**
+
+* `node_modules` 已打包到仓库中，这样头脑风暴服务器在全新插件安装后无需运行时执行 `npm` 即可立即工作
+* 从打包的依赖项中移除了 `fsevents`（仅限 macOS 的原生二进制文件；chokidar 在缺少它时会优雅地回退）
+* 如果缺少 `node_modules`，则通过 `npm install` 进行回退自动安装
+
+**OpenCode 工具映射修复**
+
+* `TodoWrite` → `todowrite`（之前错误地映射到 `update_plan`）；已根据 OpenCode 源代码验证
+
+### 错误修复
+
+**Windows/Linux：单引号破坏 SessionStart 钩子** (#577, #529, #644, PR #585)
+
+* hooks.json 中 `${CLAUDE_PLUGIN_ROOT}` 周围的单引号在 Windows 上失败（cmd.exe 不将单引号识别为路径分隔符）以及在 Linux 上失败（单引号阻止变量扩展）
+* 修复：将单引号替换为转义的双引号 — 在 macOS bash、Windows cmd.exe、Windows Git Bash 和 Linux 上均可工作，无论路径中是否包含空格
+* 已在 Windows 11（NT 10.0.26200.0）上使用 Claude Code 2.1.72 和 Git for Windows 验证
+
+**头脑风暴规范审查循环被跳过** (#677)
+
+* 规范审查循环（调度 spec-document-reviewer 子代理，迭代直到批准）存在于散文“设计之后”部分，但在检查清单和流程图中缺失
+* 由于代理遵循图表和检查清单比散文更可靠，规范审查步骤被完全跳过
+* 已将步骤 7（规范审查循环）添加到检查清单，并将相应的节点添加到点图
+* 使用 `claude --plugin-dir` 和 `claude-session-driver` 测试：worker 现在能正确调度审查者
+
+**Cursor 安装命令** (PR #676)
+
+* 修复了 README 中的 Cursor 安装命令：`/plugin-add` → `/add-plugin`（通过 Cursor 2.5 发布公告确认）
+
+**头脑风暴中的用户审查关口** (#565)
+
+* 在规范完成和编写计划交接之间添加了明确的用户审查步骤
+* 用户必须在实施计划开始前批准规范
+* 检查清单、流程图和散文已更新，包含新的关口
+
+**会话启动钩子每个平台仅发出一次上下文**
+
+* 钩子现在检测它是在 Claude Code 还是其他平台中运行
+* 为 Claude Code 发出 `hookSpecificOutput`，为其他平台发出 `additional_context` — 防止双重上下文注入
+
+**令牌分析脚本中的代码风格修复**
+
+* `except:` → `except Exception:`，位于 `tests/claude-code/analyze-token-usage.py`
+
+### 维护
+
+**移除死代码**
+
+* 删除了 `lib/skills-core.js` 及其测试（`tests/opencode/test-skills-core.js`）— 自 2026 年 2 月起未使用
+* 从 `tests/opencode/test-plugin-loading.sh` 中移除了 skills-core 存在性检查
+
+### 社区
+
+* @karuturi — Claude Code 官方市场安装说明（PR #610）
+* @mvanhorn — 会话启动钩子双重发出修复，OpenCode 工具映射修复
+* @daniel-graham — 裸异常捕获的代码风格修复
+* PR #585 作者 — Windows/Linux 钩子引号修复
+
+***
+
+## v5.0.0 (2026-03-09)
+
+### 破坏性变更
+
+**规范和计划目录结构调整**
+
+* 规范（头脑风暴输出）现在保存到 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+* 计划（编写计划输出）现在保存到 `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+* 用户对规范/计划位置的偏好会覆盖这些默认值
+* 所有内部技能引用、测试文件和示例路径都已更新以匹配新结构
+* 迁移：如果需要，将现有文件从 `docs/plans/` 移动到新位置
+
+**在支持的子代理平台上强制使用子代理驱动开发**
+
+编写计划不再提供在子代理驱动和执行计划之间的选择。在具有子代理支持的平台（Claude Code、Codex）上，子代理驱动开发是必需的。执行计划保留给没有子代理能力的平台，并且现在会告知用户 Superpowers 在支持子代理的平台上效果更好。
+
+**执行计划不再分批执行**
+
+移除了“执行 3 个任务后停止审查”的模式。计划现在连续执行，仅在遇到阻塞时停止。
+
+**斜杠命令已弃用**
+
+`/brainstorm`、`/write-plan` 和 `/execute-plan` 现在显示弃用通知，引导用户使用相应的技能。命令将在下一个主要版本中移除。
+
+### 新功能
+
+**可视化头脑风暴伴侣**
+
+头脑风暴会话的可选浏览器伴侣。当主题受益于可视化时，头脑风暴技能会提供在浏览器窗口中显示与终端对话并行的线框图、图表、比较和其他内容。
+
+* `lib/brainstorm-server/` — 包含浏览器助手库、会话管理脚本和深色/浅色主题框架模板（“Superpowers Brainstorming” 带 GitHub 链接）的 WebSocket 服务器
+* `skills/brainstorming/visual-companion.md` — 服务器工作流程、屏幕创作和反馈收集的渐进式指南
+* 头脑风暴技能在其流程中添加了一个可视化伴侣决策点：在探索项目上下文后，技能评估即将到来的问题是否涉及可视化内容，并在其自己的消息中提供伴侣
+* 按问题决策：即使在接受后，每个问题都会评估浏览器还是终端更合适
+* `tests/brainstorm-server/` 中的集成测试
+
+**文档审查系统**
+
+使用子代理调度的规范和计划文档的自动化审查循环：
+
+* `skills/brainstorming/spec-document-reviewer-prompt.md` — 审查者检查完整性、一致性、架构和 YAGNI
+* `skills/writing-plans/plan-document-reviewer-prompt.md` — 审查者检查规范对齐、任务分解、文件结构和文件大小
+* 头脑风暴在编写设计文档后调度规范审查者
+* 编写计划在每个部分后包含基于块的计划审查循环
+* 审查循环重复直到批准或在 5 次迭代后升级
+* `tests/claude-code/test-document-review-system.sh` 中的端到端测试
+* `docs/superpowers/` 中的设计规范和实施计划
+
+**贯穿技能管道的架构指导**
+
+设计隔离和文件大小感知指导已添加到头脑风暴、编写计划和子代理驱动开发中：
+
+* **头脑风暴** — 新章节：“为隔离和清晰度而设计”（清晰的边界、定义良好的接口、独立可测试的单元）和“在现有代码库中工作”（遵循现有模式，仅进行有针对性的改进）
+* **编写计划** — 新的“文件结构”部分：在定义任务前规划文件和职责。新的“范围检查”后备机制：捕获应在头脑风暴期间分解的多子系统规范
+* **SDD 实施者** — 新的“代码组织”部分（遵循计划的文件结构，报告对文件增长的担忧）和“当您力不从心时”的升级指导
+* **SDD 代码质量审查者** — 现在检查架构、单元分解、计划符合性和文件增长
+* **规范/计划审查者** — 架构和文件大小已添加到审查标准中
+* **范围评估** — 头脑风暴现在评估项目是否对单个规范来说太大。多子系统请求会及早标记，并分解为子项目，每个子项目都有自己的规范 → 计划 → 实施周期
+
+**子代理驱动开发的改进**
+
+* **模型选择** — 按任务类型选择模型能力的指导：廉价模型用于机械实施，标准模型用于集成，能力强模型用于架构和审查
+* **实施者状态协议** — 子代理现在报告 DONE、DONE\_WITH\_CONCERNS、BLOCKED 或 NEEDS\_CONTEXT。控制器适当地处理每个状态：用更多上下文重新调度、升级模型能力、分解任务或升级给人类
+
+### 改进
+
+**指令优先级层次结构**
+
+向 using-superpowers 添加了明确的优先级排序：
+
+1. 用户的明确指令（CLAUDE.md、AGENTS.md、直接请求）— 最高优先级
+2. Superpowers 技能 — 覆盖默认系统行为
+3. 默认系统提示 — 最低优先级
+
+如果 CLAUDE.md 或 AGENTS.md 说“不要使用 TDD”而一个技能说“始终使用 TDD”，那么用户的指令胜出。
+
+**SUBAGENT-STOP 关口**
+
+向 using-superpowers 添加了 `<SUBAGENT-STOP>` 块。为特定任务调度的子代理现在跳过该技能，而不是激活 1% 规则并调用完整的技能工作流。
+
+**多平台改进**
+
+* Codex 工具映射移至渐进式参考文件（`references/codex-tools.md`）
+* 添加了平台适配指针，以便非 Claude-Code 平台可以找到工具等效项
+* 计划头部现在针对“代理工作者”而不是特定的“Claude”
+* 协作功能要求在 `docs/README.codex.md` 中记录
+
+**编写计划模板更新**
+
+* 计划步骤现在使用复选框语法（`- [ ] **Step N:**`）进行进度跟踪
+* 计划头部引用子代理驱动开发和执行计划，并具有平台感知的路由
+
+***
+
+## v4.3.1 (2026-02-21)
+
+### 新增
+
+**Cursor 支持**
+
+Superpowers 现在可与 Cursor 的插件系统协同工作。包含一个 `.cursor-plugin/plugin.json` 清单，以及 README 中的 Cursor 特定安装说明。SessionStart 钩子的输出现在包含一个 `additional_context` 字段，与现有的 `hookSpecificOutput.additionalContext` 并列，以实现 Cursor 钩子的兼容性。
+
+### 已修复
+
+**Windows：恢复了多语言包装器以确保钩子可靠执行 (#518, #504, #491, #487, #466, #440)**
+
+Claude Code 在 Windows 上的 `.sh` 自动检测功能，会在钩子命令前添加 `bash`，从而破坏执行。修复方法如下：
+
+* 将 `session-start.sh` 重命名为 `session-start`（无扩展名），这样自动检测就不会干扰
+* 恢复了 `run-hook.cmd` 多语言包装器，包含多位置 bash 发现（标准的 Git for Windows 路径，然后是 PATH 回退）
+* 如果未找到 bash，则静默退出，而不是报错
+* 在 Unix 上，包装器通过 `exec bash` 直接运行脚本
+* 使用符合 POSIX 标准的 `dirname "$0"` 路径解析（适用于 dash/sh，不仅仅是 bash）
+
+这修复了 Windows 上因路径包含空格、缺少 WSL、MSYS 上 `set -euo pipefail` 的脆弱性以及反斜杠处理错误导致的 SessionStart 失败。
+
+## v4.3.0 (2026-02-12)
+
+此修复应能显著提高 superpowers 技能合规性，并应降低 Claude 意外进入其原生计划模式的可能性。
+
+### 已更改
+
+**头脑风暴技能现在强制执行其工作流程，而非仅描述它**
+
+模型曾跳过设计阶段，直接跳转到实现技能（如前端设计），或将整个头脑风暴过程压缩到单个文本块中。该技能现在使用硬性关卡、强制检查清单和 graphviz 流程来确保合规：
+
+* `<HARD-GATE>`：在展示设计并获得用户批准之前，不得使用实现技能、编写代码或进行脚手架搭建
+* 明确的检查清单（6项），必须创建为任务并按顺序完成
+* 包含 `writing-plans` 作为唯一有效终止状态的 Graphviz 流程图
+* 对“这太简单了，不需要设计”这种反模式提出警告——这正是模型用来跳过流程的合理化说辞
+* 设计部分的大小基于部分复杂性，而非项目复杂性
+
+**使用-superpowers 工作流图拦截 EnterPlanMode**
+
+在技能流程图中添加了 `EnterPlanMode` 拦截。当模型即将进入 Claude 的原生计划模式时，它会检查是否已进行头脑风暴，并改为路由到头脑风暴技能。计划模式永远不会被进入。
+
+### 已修复
+
+**SessionStart 钩子现在同步运行**
+
+将 hooks.json 中的 `async: true` 更改为 `async: false`。异步运行时，钩子可能在模型的第一个回合之前无法完成，这意味着使用-superpowers 指令在第一条消息时未处于上下文中。
+
+## v4.2.0 (2026-02-05)
+
+### 破坏性变更
+
+**Codex：用原生技能发现替换了引导 CLI**
+
+移除了 `superpowers-codex` 引导 CLI、Windows `.cmd` 包装器以及相关的引导内容文件。Codex 现在通过 `~/.agents/skills/superpowers/` 符号链接使用原生技能发现，因此不再需要旧的 `use_skill`/`find_skills` CLI 工具。
+
+现在安装只需克隆 + 创建符号链接（在 INSTALL.md 中有记录）。不需要 Node.js 依赖。旧的 `~/.codex/skills/` 路径已被弃用。
+
+### 修复
+
+**Windows：修复了 Claude Code 2.1.x 的钩子执行 (#331)**
+
+Claude Code 2.1.x 更改了 Windows 上钩子的执行方式：现在它会自动检测命令中的 `.sh` 文件，并在前面添加 `bash`。这破坏了多语言包装器模式，因为 `bash "run-hook.cmd" session-start.sh` 试图将 `.cmd` 文件作为 bash 脚本执行。
+
+修复方法：hooks.json 现在直接调用 session-start.sh。Claude Code 2.1.x 会自动处理 bash 调用。同时添加了 .gitattributes 来为 shell 脚本强制执行 LF 行尾（修复了 Windows 检出时的 CRLF 问题）。
+
+**Windows：SessionStart 钩子异步运行以防止终端冻结 (#404, #413, #414, #419)**
+
+同步的 SessionStart 钩子在 Windows 上会阻止 TUI 进入原始模式，冻结所有键盘输入。异步运行钩子可以防止冻结，同时仍能注入 superpowers 上下文。
+
+**Windows：修复了 O(n^2) 的 `escape_for_json` 性能**
+
+使用 `${input:$i:1}` 的逐字符循环，由于子字符串复制开销，在 bash 中是 O(n^2) 复杂度。在 Windows Git Bash 上，这需要 60 多秒。已替换为 bash 参数替换（`${s//old/new}`），它将每个模式作为一次 C 语言级别的遍历运行——在 macOS 上快 7 倍，在 Windows 上显著加快。
+
+**Codex：修复了 Windows/PowerShell 调用 (#285, #243)**
+
+* Windows 不遵循 shebang，因此直接调用无扩展名的 `superpowers-codex` 脚本会触发“打开方式”对话框。所有调用现在都加上了 `node` 前缀。
+* 修复了 Windows 上的 `~/` 路径扩展问题——PowerShell 在将 `~` 作为参数传递给 `node` 时不会扩展它。已更改为 `$HOME`，它在 bash 和 PowerShell 中都能正确扩展。
+
+**Codex：修复了安装程序中的路径解析**
+
+使用 `fileURLToPath()` 替代手动 URL 路径名解析，以在所有平台上正确处理包含空格和特殊字符的路径。
+
+**Codex：修复了 writing-skills 中过时的技能路径**
+
+将 `~/.codex/skills/` 引用（已弃用）更新为 `~/.agents/skills/`，以支持原生发现。
+
+### 改进
+
+**在实现之前现在需要工作树隔离**
+
+为 `subagent-driven-development` 和 `executing-plans` 添加了 `using-git-worktrees` 作为必需技能。实现工作流现在明确要求在开始工作之前设置一个隔离的工作树，防止直接在 main 分支上意外工作。
+
+**Main 分支保护放宽为需要明确同意**
+
+技能不再完全禁止在 main 分支上工作，而是允许在获得用户明确同意后进行。这样更灵活，同时仍能确保用户了解其影响。
+
+**简化了安装验证**
+
+从验证步骤中移除了 `/help` 命令检查和特定的斜杠命令列表。技能主要通过描述你想要做的事情来调用，而不是通过运行特定命令。
+
+**Codex：在引导程序中澄清了子代理工具映射**
+
+改进了关于 Codex 工具如何映射到 Claude Code 等效工具以实现子代理工作流的文档。
+
+### 测试
+
+* 为 subagent-driven-development 添加了工作树要求测试
+* 添加了 main 分支危险警告测试
+* 修复了技能识别测试断言中的大小写敏感性
+
+***
+
+## v4.1.1 (2026-01-23)
+
+### 修复
+
+**OpenCode：根据官方文档标准化为 `plugins/` 目录 (#343)**
+
+OpenCode 的官方文档使用 `~/.config/opencode/plugins/`（复数形式）。我们的文档之前使用 `plugin/`（单数形式）。虽然 OpenCode 接受两种形式，但我们已经标准化为官方约定，以避免混淆。
+
+更改：
+
+* 在仓库结构中，将 `.opencode/plugin/` 重命名为 `.opencode/plugins/`
+* 更新了所有平台上的所有安装文档（INSTALL.md、README.opencode.md）
+* 更新了测试脚本以匹配
+
+**OpenCode：修复了符号链接说明 (#339, #342)**
+
+* 在 `ln -s` 之前添加了明确的 `rm`（修复重新安装时的“文件已存在”错误）
+* 添加了 INSTALL.md 中缺失的技能符号链接步骤
+* 更新了已弃用的 `use_skill`/`find_skills` 引用，改为原生的 `skill` 工具引用
+
+***
+
+## v4.1.0 (2026-01-23)
+
+### 破坏性变更
+
+**OpenCode：切换到原生技能系统**
+
+用于 OpenCode 的 Superpowers 现在使用 OpenCode 的原生 `skill` 工具，而不是自定义的 `use_skill`/`find_skills` 工具。这是一个更简洁的集成，可与 OpenCode 内置的技能发现协同工作。
+
+**需要迁移：** 技能必须符号链接到 `~/.config/opencode/skills/superpowers/`（请参阅更新的安装文档）。
+
+### 修复
+
+**OpenCode：修复了会话开始时的代理重置问题 (#226)**
+
+之前使用 `session.prompt({ noReply: true })` 的引导注入方法导致 OpenCode 在第一条消息时将所选代理重置为“build”。现在使用 `experimental.chat.system.transform` 钩子，它直接修改系统提示，没有副作用。
+
+**OpenCode：修复了 Windows 安装问题 (#232)**
+
+* 移除了对 `skills-core.js` 的依赖（消除了文件被复制而非符号链接时出现的损坏的相对导入问题）
+* 为 cmd.exe、PowerShell 和 Git Bash 添加了全面的 Windows 安装文档
+* 记录了每个平台正确的符号链接与连接点用法
+
+**Claude Code：修复了 Claude Code 2.1.x 在 Windows 上的钩子执行问题**
+
+Claude Code 2.1.x 更改了 Windows 上钩子的执行方式：现在它会自动检测命令中的 `.sh` 文件，并在前面添加 `bash `。这破坏了多语言包装器模式，因为 `bash "run-hook.cmd" session-start.sh` 试图将 .cmd 文件作为 bash 脚本执行。
+
+修复方法：hooks.json 现在直接调用 session-start.sh。Claude Code 2.1.x 会自动处理 bash 调用。同时添加了 .gitattributes 来为 shell 脚本强制执行 LF 行尾（修复了 Windows 检出时的 CRLF 问题）。
+
+***
+
+## v4.0.3 (2025-12-26)
+
+### 改进
+
+**增强了使用-superpowers 技能以应对明确的技能请求**
+
+解决了一个故障模式，即使用户明确按名称请求技能（例如，“请使用 subagent-driven-development”），Claude 也会跳过调用该技能。Claude 会认为“我知道那是什么意思”，然后直接开始工作，而不是加载技能。
+
+更改：
+
+* 更新了“规则”，将“检查技能”改为“调用相关或请求的技能”——强调主动调用而非被动检查
+* 添加了“在任何响应或行动之前”——原始措辞只提到了“响应”，但 Claude 有时会在不先响应的情况下采取行动
+* 添加了保证：调用错误的技能也没关系——减少犹豫
+* 添加了新的危险信号：“我知道那是什么意思”→ 知道概念 ≠ 使用技能
+
+**添加了明确的技能请求测试**
+
+在 `tests/explicit-skill-requests/` 中添加了新的测试套件，用于验证当用户按名称请求技能时，Claude 是否正确调用技能。包括单回合和多回合测试场景。
+
+## v4.0.2 (2025-12-23)
+
+### 修复
+
+**斜杠命令现在仅供用户使用**
+
+为所有三个斜杠命令（`/brainstorm`、`/execute-plan`、`/write-plan`）添加了 `disable-model-invocation: true`。Claude 不能再通过 Skill 工具调用这些命令——它们仅限于手动用户调用。
+
+底层技能（`superpowers:brainstorming`、`superpowers:executing-plans`、`superpowers:writing-plans`）仍然可供 Claude 自主调用。此更改防止了当 Claude 调用一个只是重定向到技能的指令时产生的混淆。
+
+## v4.0.1 (2025-12-23)
+
+### 修复
+
+**阐明了如何在 Claude Code 中访问技能**
+
+修复了一个令人困惑的模式：Claude 通过 Skill 工具调用技能后，会尝试单独读取技能文件。`using-superpowers` 技能现在明确指出，Skill 工具会直接加载技能内容——无需读取文件。
+
+* 向 `using-superpowers` 添加了“如何访问技能”部分
+* 在说明中将“读取技能”改为“调用技能”
+* 更新了斜杠命令以使用完全限定的技能名称（例如，`superpowers:brainstorming`）
+
+**向 receiving-code-review 添加了 GitHub 线程回复指南**（感谢 @ralphbean）
+
+添加了关于在原始线程中回复内联评论，而不是作为顶级 PR 评论的说明。
+
+**向 writing-skills 添加了自动化优于文档的指南**（感谢 @EthanJStark）
+
+添加了指南：机械性约束应自动化，而非文档化——将技能留给判断性决策。
+
+## v4.0.0 (2025-12-17)
+
+### 新功能
+
+**subagent-driven-development 中的两阶段代码审查**
+
+子代理工作流现在在每个任务后使用两个独立的审查阶段：
+
+1. **规范符合性审查** - 持怀疑态度的审查者验证实现是否完全符合规范。捕捉缺失的需求**和**过度构建。不信任实施者的报告——阅读实际代码。
+2. **代码质量审查** - 仅在规范符合性通过后运行。审查代码整洁度、测试覆盖率、可维护性。
+
+这捕捉了代码编写良好但与请求不符的常见失败模式。评审是循环而非单次操作：若评审者发现问题，实施者修复后，评审者会再次检查。
+
+其他子代理工作流改进：
+
+* 控制器向工作者提供完整任务文本（而非文件引用）
+* 工作者可在工作开始前及工作中提出澄清问题
+* 报告完成前进行自我评审检查清单
+* 计划仅在开始时读取一次，并提取到TodoWrite
+
+`skills/subagent-driven-development/`中的新提示模板：
+
+* `implementer-prompt.md` - 包含自我评审检查清单，鼓励提问
+* `spec-reviewer-prompt.md` - 针对需求进行怀疑性验证
+* `code-quality-reviewer-prompt.md` - 标准代码评审
+
+**调试技术与工具整合**
+
+`systematic-debugging`现已捆绑支持技术和工具：
+
+* `root-cause-tracing.md` - 通过调用栈反向追踪错误
+* `defense-in-depth.md` - 在多个层级添加验证
+* `condition-based-waiting.md` - 用条件轮询替代任意超时
+* `find-polluter.sh` - 二分查找脚本定位产生污染的测试
+* `condition-based-waiting-example.ts` - 来自实际调试会话的完整实现
+
+**测试反模式参考**
+
+`test-driven-development`现包含`testing-anti-patterns.md`，涵盖：
+
+* 测试模拟行为而非真实行为
+* 向生产类添加仅用于测试的方法
+* 在不理解依赖关系的情况下进行模拟
+* 隐藏结构假设的不完整模拟
+
+**技能测试基础设施**
+
+用于验证技能行为的三个新测试框架：
+
+`tests/skill-triggering/` - 验证技能能否通过朴素提示触发而无需显式命名。测试6项技能以确保仅凭描述即可触发。
+
+`tests/claude-code/` - 使用`claude -p`进行无头测试的集成测试。通过会话转录（JSONL）分析验证技能使用情况。包含用于成本跟踪的`analyze-token-usage.py`。
+
+`tests/subagent-driven-dev/` - 包含两个完整测试项目的端到端工作流验证：
+
+* `go-fractals/` - 包含Sierpinski/Mandelbrot的CLI工具（10项任务）
+* `svelte-todo/` - 包含localStorage和Playwright的CRUD应用（12项任务）
+
+### 主要变更
+
+**将DOT流程图作为可执行规范**
+
+使用DOT/GraphViz流程图作为权威流程定义重写了关键技能。文本内容变为辅助性材料。
+
+**描述陷阱**（记录于`writing-skills`）：发现当技能描述包含工作流摘要时，技能描述会覆盖流程图内容。Claude会遵循简短描述而非阅读详细的流程图。修复方法：描述必须仅为触发用途（"在X情况下使用"），不包含流程细节。
+
+**using-superpowers中的技能优先级**
+
+当多个技能适用时，流程技能（头脑风暴、调试）现在明确优先于实现技能。"构建X"会先触发头脑风暴，然后是领域技能。
+
+**头脑风暴触发机制强化**
+
+描述改为命令式："在进行任何创造性工作前——创建功能、构建组件、添加功能或修改行为时，你必须使用此技能。"
+
+### 破坏性变更
+
+**技能整合** - 六项独立技能已合并：
+
+* `root-cause-tracing`、`defense-in-depth`、`condition-based-waiting` → 捆绑于`systematic-debugging/`
+* `testing-skills-with-subagents` → 捆绑于`writing-skills/`
+* `testing-anti-patterns` → 捆绑于`test-driven-development/`
+* `sharing-skills`已移除（已过时）
+
+### 其他改进
+
+* **render-graphs.js** - 从技能中提取DOT图表并渲染为SVG的工具
+* **using-superpowers中的合理化表格** - 可扫描格式，包含新条目："我需要更多上下文"、"让我先探索"、"这感觉很有成效"
+* **docs/testing.md** - 使用Claude Code集成测试测试技能的指南
+
+***
+
+## v3.6.2 (2025-12-03)
+
+### 已修复
+
+* **Linux兼容性**：修复了多语言钩子包装器（`run-hook.cmd`）以使用符合POSIX标准的语法
+  * 第16行将bash特定的`${BASH_SOURCE[0]:-$0}`替换为标准`$0`
+  * 解决了在Ubuntu/Debian系统上（其中`/bin/sh`为dash）出现的"Bad substitution"错误
+  * 修复了#141
+
+***
+
+## v3.5.1 (2025-11-24)
+
+### 已更改
+
+* **OpenCode引导程序重构**：从`chat.message`钩子切换到`session.created`事件进行引导程序注入
+  * 引导程序现通过`session.prompt()`在会话创建时注入，使用`noReply: true`
+  * 明确告知模型using-superpowers已加载，防止冗余技能加载
+  * 将引导程序内容生成整合到共享的`getBootstrapContent()`辅助函数中
+  * 更简洁的单实现方法（移除了回退模式）
+
+***
+
+## v3.5.0 (2025-11-23)
+
+### 新增
+
+* **OpenCode支持**：OpenCode.ai的原生JavaScript插件
+  * 自定义工具：`use_skill`和`find_skills`
+  * 用于在上下文压缩后保持技能持久性的消息插入模式
+  * 通过chat.message钩子自动注入上下文
+  * 在session.compacted事件上自动重新注入
+  * 三层技能优先级：项目 > 个人 > superpowers
+  * 项目本地技能支持（`.opencode/skills/`）
+  * 用于与Codex代码重用的共享核心模块（`lib/skills-core.js`）
+  * 具有适当隔离的自动化测试套件（`tests/opencode/`）
+  * 平台特定文档（`docs/README.opencode.md`、`docs/README.codex.md`）
+
+### 已更改
+
+* **重构的Codex实现**：现在使用共享的`lib/skills-core.js` ES模块
+  * 消除了Codex和OpenCode之间的代码重复
+  * 技能发现和解析的单一真实来源
+  * Codex通过Node.js互操作成功加载ES模块
+
+* **改进的文档**：重写README以清晰解释问题/解决方案
+  * 移除了重复部分和冲突信息
+  * 添加了完整的工作流描述（头脑风暴 → 计划 → 执行 → 完成）
+  * 简化了平台安装说明
+  * 强调技能检查协议而非自动激活声明
+
+***
+
+## v3.4.1 (2025-10-31)
+
+### 改进
+
+* 优化了superpowers引导程序以消除冗余技能执行。`using-superpowers`技能内容现在直接在会话上下文中提供，并附有明确指导，仅将Skill工具用于其他技能。这减少了开销，并防止了代理尽管在会话开始时已获得内容但仍手动执行`using-superpowers`的混乱循环。
+
+## v3.4.0 (2025-10-30)
+
+### 改进
+
+* 简化了`brainstorming`技能，回归到原始的对话式愿景。移除了带有正式检查清单的重型6阶段流程，转而采用自然对话：一次提出一个问题，然后以200-300字的部分呈现设计并进行验证。保留了文档和实现交接功能。
+
+## v3.3.1 (2025-10-28)
+
+### 改进
+
+* 更新了`brainstorming`技能，要求在提问前进行自主侦察，鼓励基于推荐的决策，并防止代理将优先级决定权交还给人类。
+* 应用了写作清晰度改进至`brainstorming`技能，遵循Strunk的"Elements of Style"原则（省略不必要的词语，将否定形式转换为肯定形式，改进平行结构）。
+
+### 错误修复
+
+* 澄清了`writing-skills`指导，使其指向正确的代理特定个人技能目录（Claude Code的`~/.claude/skills`，Codex的`~/.codex/skills`）。
+
+## v3.3.0 (2025-10-28)
+
+### 新功能
+
+**实验性Codex支持**
+
+* 添加了统一的`superpowers-codex`脚本，包含引导程序/使用技能/查找技能命令
+* 跨平台Node.js实现（适用于Windows、macOS、Linux）
+* 命名空间技能：superpowers技能的`superpowers:skill-name`，个人技能的`skill-name`
+* 名称匹配时，个人技能覆盖superpowers技能
+* 清晰的技能显示：显示名称/描述，不含原始frontmatter
+* 有帮助的上下文：显示每项技能的支持文件目录
+* Codex的工具映射：TodoWrite→update\_plan、subagents→手动回退等
+* 与最小AGENTS.md集成的引导程序，用于自动启动
+* 特定于Codex的完整安装指南和引导程序说明
+
+**与Claude Code集成的关键区别：**
+
+* 单个统一脚本而非独立工具
+* 用于Codex特定等效工具的工具替换系统
+* 简化的子代理处理（手动工作而非委派）
+* 更新的术语："Superpowers技能"替代"核心技能"
+
+### 新增文件
+
+* `.codex/INSTALL.md` - Codex用户的安装指南
+* `.codex/superpowers-bootstrap.md` - 包含Codex适配的引导程序说明
+* `.codex/superpowers-codex` - 包含所有功能的统一Node.js可执行文件
+
+**注意：** Codex支持是实验性的。该集成提供了核心的superpowers功能，但可能需要根据用户反馈进行改进。
+
+## v3.2.3 (2025-10-23)
+
+### 改进
+
+**更新了using-superpowers技能以使用Skill工具而非Read工具**
+
+* 将技能调用说明从Read工具更改为Skill工具
+* 更新描述："使用Read工具" → "使用Skill工具"
+* 更新步骤3："使用Read工具" → "使用Skill工具读取并运行"
+* 更新合理化列表："读取当前版本" → "运行当前版本"
+
+Skill工具是Claude Code中调用技能的正确机制。此更新更正了引导程序说明，以指导代理使用正确的工具。
+
+### 变更的文件
+
+* 更新：`skills/using-superpowers/SKILL.md` - 将工具引用从Read更改为Skill
+
+## v3.2.2 (2025-10-21)
+
+### 改进
+
+**强化了using-superpowers技能以应对代理合理化行为**
+
+* 添加了包含绝对语言的EXTREMELY-IMPORTANT块，关于强制技能检查
+  * "即使只有1%的可能性适用技能，你也必须读取它"
+  * "你没有选择。你无法合理化地回避。"
+* 添加了MANDATORY FIRST RESPONSE PROTOCOL检查清单
+  * 代理在做出任何响应前必须完成的5步流程
+  * 明确的"未完成此步骤即响应 = 失败"后果
+* 添加了Common Rationalizations部分，包含8种特定的规避模式
+  * "这只是一个简单问题" → 错误
+  * "我可以快速检查文件" → 错误
+  * "让我先收集信息" → 错误
+  * 加上另外5种在代理行为中观察到的常见模式
+
+这些变更解决了观察到的代理行为，即尽管有明确指示，他们仍会合理化地绕过技能使用。强制的语言和先发制人的反驳旨在使不遵守行为更难发生。
+
+### 变更的文件
+
+* 更新：`skills/using-superpowers/SKILL.md` - 添加了三层强制措施以防止技能跳过合理化
+
+## v3.2.1 (2025-10-20)
+
+### 新功能
+
+**代码评审代理现已包含在插件中**
+
+* 将`superpowers:code-reviewer`代理添加到插件的`agents/`目录
+* 该代理提供针对计划和编码标准的系统性代码评审
+* 之前要求用户拥有个人代理配置
+* 所有技能引用已更新为使用命名空间的`superpowers:code-reviewer`
+* 修复了#55
+
+### 变更的文件
+
+* 新增：`agents/code-reviewer.md` - 包含评审检查清单和输出格式的代理定义
+* 更新：`skills/requesting-code-review/SKILL.md` - 对`superpowers:code-reviewer`的引用
+* 更新：`skills/subagent-driven-development/SKILL.md` - 对`superpowers:code-reviewer`的引用
+
+## v3.2.0 (2025-10-18)
+
+### 新功能
+
+**头脑风暴工作流中的设计文档**
+
+* 为头脑风暴技能添加了第4阶段：设计文档
+* 设计文档现在在实施前写入`docs/plans/YYYY-MM-DD-<topic>-design.md`
+* 恢复了原始头脑风暴命令在技能转换过程中丢失的功能
+* 在工作树设置和实施计划之前编写文档
+* 通过子代理在时间压力下测试以验证合规性
+
+### 破坏性变更
+
+**技能引用命名空间标准化**
+
+* 所有内部技能引用现在使用 `superpowers:` 命名空间前缀
+* 更新后的格式：`superpowers:test-driven-development`（之前仅为 `test-driven-development`）
+* 影响所有 REQUIRED SUB-SKILL、RECOMMENDED SUB-SKILL 和 REQUIRED BACKGROUND 引用
+* 与使用 Skill 工具调用技能的方式保持一致
+* 更新的文件：brainstorming、executing-plans、subagent-driven-development、systematic-debugging、testing-skills-with-subagents、writing-plans、writing-skills
+
+### 改进
+
+**设计文档与实现计划命名**
+
+* 设计文档使用 `-design.md` 后缀以防止文件名冲突
+* 实现计划继续使用现有的 `YYYY-MM-DD-<feature-name>.md` 格式
+* 两者都存储在 `docs/plans/` 目录中，具有清晰的命名区分
+
+## v3.1.1 (2025-10-17)
+
+### 错误修复
+
+* **修复了 README 中的命令语法** (#44) - 更新了所有命令引用以使用正确的命名空间语法（`/superpowers:brainstorm` 替代 `/brainstorm`）。插件提供的命令由 Claude Code 自动命名空间化，以避免插件之间的冲突。
+
+## v3.1.0 (2025-10-17)
+
+### 破坏性变更
+
+**技能名称标准化为小写**
+
+* 所有技能 frontmatter `name:` 字段现在使用小写 kebab-case，与目录名称匹配
+* 示例：`brainstorming`、`test-driven-development`、`using-git-worktrees`
+* 所有技能公告和交叉引用已更新为小写格式
+* 这确保了目录名称、frontmatter 和文档之间的命名一致性
+
+### 新功能
+
+**增强的 brainstorming 技能**
+
+* 添加了显示阶段、活动和工具使用的快速参考表
+* 添加了用于跟踪进度的可复制工作流程清单
+* 添加了用于决定何时重新访问早期阶段的决策流程图
+* 添加了包含具体示例的全面 AskUserQuestion 工具指南
+* 添加了“问题模式”部分，解释何时使用结构化问题与开放式问题
+* 将关键原则重构为可扫描的表格
+
+**Anthropic 最佳实践集成**
+
+* 添加了 `skills/writing-skills/anthropic-best-practices.md` - 官方 Anthropic 技能编写指南
+* 在 writing-skills SKILL.md 中引用以获取全面指导
+* 提供了渐进式披露、工作流程和评估的模式
+
+### 改进
+
+**技能交叉引用清晰度**
+
+* 所有技能引用现在使用明确的需求标记：
+  * `**REQUIRED BACKGROUND:**` - 你必须理解的先决条件
+  * `**REQUIRED SUB-SKILL:**` - 必须在工作流程中使用的技能
+  * `**Complementary skills:**` - 可选但有用的相关技能
+* 移除了旧的路径格式（`skills/collaboration/X` → 仅为 `X`）
+* 使用分类关系（必需与补充）更新了集成部分
+* 使用最佳实践更新了交叉引用文档
+
+**与 Anthropic 最佳实践保持一致**
+
+* 修复了描述语法和语态（完全第三人称）
+* 添加了用于扫描的快速参考表
+* 添加了 Claude 可以复制和跟踪的工作流程清单
+* 对非明显决策点适当使用流程图
+* 改进了可扫描的表格格式
+* 所有技能均符合 500 行建议
+
+### 错误修复
+
+* **重新添加了缺失的命令重定向** - 恢复了在 v3.0 迁移中意外删除的 `commands/brainstorm.md` 和 `commands/write-plan.md`
+* 修复了 `defense-in-depth` 名称不匹配问题（原为 `Defense-in-Depth-Validation`）
+* 修复了 `receiving-code-review` 名称不匹配问题（原为 `Code-Review-Reception`）
+* 修复了 `commands/brainstorm.md` 对正确技能名称的引用
+* 移除了对不存在相关技能的引用
+
+### 文档
+
+**writing-skills 改进**
+
+* 使用明确的需求标记更新了交叉引用指南
+* 添加了对 Anthropic 官方最佳实践的引用
+* 改进了显示正确技能引用格式的示例
+
+## v3.0.1 (2025-10-16)
+
+### 变更
+
+我们现在使用 Anthropic 的第一方技能系统！
+
+## v2.0.2 (2025-10-12)
+
+### 错误修复
+
+* **修复了当本地技能仓库领先于上游时的错误警告** - 初始化脚本在本地仓库提交领先于上游时错误地警告“上游有新的技能可用”。逻辑现在正确区分了三种 git 状态：本地落后（应更新）、本地领先（无警告）和分叉（应警告）。
+
+## v2.0.1 (2025-10-12)
+
+### 错误修复
+
+* **修复了插件上下文中的 session-start 钩子执行问题** (#8, PR #9) - 该钩子静默失败并显示“插件钩子错误”，阻止了技能上下文的加载。通过以下方式修复：
+  * 在 Claude Code 执行上下文中 BASH\_SOURCE 未绑定时使用 `${BASH_SOURCE[0]:-$0}` 回退
+  * 添加 `|| true` 以在过滤状态标志时优雅处理空的 grep 结果
+
+***
+
+# Superpowers v2.0.0 发布说明
+
+## 概述
+
+Superpowers v2.0 通过一次重大的架构转变，使技能更易访问、更易维护且更具社区驱动性。
+
+头条变更是**技能仓库分离**：所有技能、脚本和文档已从插件中移出，转移到一个专用仓库（[obra/superpowers-skills](https://github.com/obra/superpowers-skills)）。这将 superpowers 从一个单体插件转变为一个轻量级垫片，用于管理技能仓库的本地克隆。技能在会话开始时自动更新。用户通过标准的 git 工作流程进行分叉和贡献改进。技能库独立于插件进行版本控制。
+
+除了基础设施之外，此版本还添加了九个专注于问题解决、研究和架构的新技能。我们以命令式语调和更清晰的结构重写了核心的 **using-skills** 文档，使 Claude 更容易理解何时以及如何使用技能。**find-skills** 现在输出可以直接粘贴到 Read 工具中的路径，消除了技能发现工作流程中的摩擦。
+
+用户体验无缝操作：插件自动处理克隆、分叉和更新。贡献者发现新的架构使得改进和共享技能变得微不足道。此版本为技能作为社区资源快速发展奠定了基础。
+
+## 重大变更
+
+### 技能仓库分离
+
+**最大的变化：** 技能不再存在于插件中。它们已移至位于 [obra/superpowers-skills](https://github.com/obra/superpowers-skills) 的独立仓库。
+
+**这对您意味着：**
+
+* **首次安装：** 插件自动将技能克隆到 `~/.config/superpowers/skills/`
+* **分叉：** 在设置过程中，您将获得分叉技能仓库的选项（如果安装了 `gh`）
+* **更新：** 技能在会话开始时自动更新（尽可能快进）
+* **贡献：** 在分支上工作，本地提交，向上游提交 PR
+* **不再有影子系统：** 旧的两层系统（个人/核心）被单一仓库分支工作流程取代
+
+**迁移：**
+
+如果您有现有安装：
+
+1. 您旧的 `~/.config/superpowers/.git` 将备份到 `~/.config/superpowers/.git.bak`
+2. 旧技能将备份到 `~/.config/superpowers/skills.bak`
+3. 将在 `~/.config/superpowers/skills/` 处创建 obra/superpowers-skills 的新鲜克隆
+
+### 移除的功能
+
+* **个人 superpowers 覆盖系统** - 被 git 分支工作流程取代
+* **setup-personal-superpowers 钩子** - 被 initialize-skills.sh 取代
+
+## 新功能
+
+### 技能仓库基础设施
+
+**自动克隆与设置** (`lib/initialize-skills.sh`)
+
+* 首次运行时克隆 obra/superpowers-skills
+* 如果安装了 GitHub CLI，则提供分叉创建选项
+* 正确设置上游/源远程仓库
+* 处理从旧安装的迁移
+
+**自动更新**
+
+* 每次会话开始时从跟踪远程仓库获取
+* 尽可能快进自动合并
+* 需要手动同步时通知（分支分叉）
+* 使用 pulling-updates-from-skills-repository 技能进行手动同步
+
+### 新技能
+
+**问题解决技能** (`skills/problem-solving/`)
+
+* **collision-zone-thinking** - 强制无关概念碰撞以获得涌现的洞察
+* **inversion-exercise** - 翻转假设以揭示隐藏的约束
+* **meta-pattern-recognition** - 发现跨领域的通用原则
+* **scale-game** - 在极端情况下测试以暴露基本真理
+* **simplification-cascades** - 找到消除多个组件的洞察
+* **when-stuck** - 派遣到正确的问题解决技术
+
+**研究技能** (`skills/research/`)
+
+* **tracing-knowledge-lineages** - 理解想法如何随时间演变
+
+**架构技能** (`skills/architecture/`)
+
+* **preserving-productive-tensions** - 保持多种有效方法，而不是强制过早解决
+
+### 技能改进
+
+**using-skills（原 getting-started）**
+
+* 从 getting-started 重命名为 using-skills
+* 使用命令式语调完全重写 (v4.0.0)
+* 前置关键规则
+* 为所有工作流程添加了“为什么”解释
+* 引用中始终包含 /SKILL.md 后缀
+* 更清晰地区分严格规则和灵活模式
+
+**writing-skills**
+
+* 交叉引用指南从 using-skills 移出
+* 添加了令牌效率部分（字数目标）
+* 改进了 CSO（Claude 搜索优化）指南
+
+**sharing-skills**
+
+* 更新为新的分支和 PR 工作流程 (v2.0.0)
+* 移除了个人/核心分离引用
+
+**pulling-updates-from-skills-repository（新）**
+
+* 与上游同步的完整工作流程
+* 取代了旧的“updating-skills”技能
+
+### 工具改进
+
+**find-skills**
+
+* 现在输出带有 /SKILL.md 后缀的完整路径
+* 使路径可直接与 Read 工具一起使用
+* 更新了帮助文本
+
+**skill-run**
+
+* 从 scripts/ 移动到 skills/using-skills/
+* 改进了文档
+
+### 插件基础设施
+
+**会话开始钩子**
+
+* 现在从技能仓库位置加载
+* 在会话开始时显示完整的技能列表
+* 打印技能位置信息
+* 显示更新状态（成功更新 / 落后于上游）
+* 将“技能落后”警告移至输出末尾
+
+**环境变量**
+
+* `SUPERPOWERS_SKILLS_ROOT` 设置为 `~/.config/superpowers/skills`
+* 在所有路径中一致使用
+
+## 错误修复
+
+* 修复了分叉时重复添加上游远程仓库的问题
+* 修复了 find-skills 输出中双“skills/”前缀的问题
+* 从 session-start 中移除了过时的 setup-personal-superpowers 调用
+* 修复了整个钩子和命令中的路径引用
+
+## 文档
+
+### README
+
+* 更新为新的技能仓库架构
+* 显著链接到 superpowers-skills 仓库
+* 更新了自动更新描述
+* 修复了技能名称和引用
+* 更新了元技能列表
+
+### 测试文档
+
+* 添加了全面的测试清单 (`docs/TESTING-CHECKLIST.md`)
+* 为测试创建了本地市场配置
+* 记录了手动测试场景
+
+## 技术细节
+
+### 文件变更
+
+**添加：**
+
+* `lib/initialize-skills.sh` - 技能仓库初始化和自动更新
+* `docs/TESTING-CHECKLIST.md` - 手动测试场景
+* `.claude-plugin/marketplace.json` - 本地测试配置
+
+**移除：**
+
+* `skills/` 目录（82 个文件）- 现在位于 obra/superpowers-skills
+* `scripts/` 目录 - 现在位于 obra/superpowers-skills/skills/using-skills/
+* `hooks/setup-personal-superpowers.sh` - 已过时
+
+**修改：**
+
+* `hooks/session-start.sh` - 使用来自 ~/.config/superpowers/skills 的技能
+* `commands/brainstorm.md` - 更新路径至 SUPERPOWERS\_SKILLS\_ROOT
+* `commands/write-plan.md` - 更新路径至 SUPERPOWERS\_SKILLS\_ROOT
+* `commands/execute-plan.md` - 更新路径至 SUPERPOWERS\_SKILLS\_ROOT
+* `README.md` - 为新架构完全重写
+
+### 提交历史
+
+此版本包括：
+
+* 20+ 次提交用于技能仓库分离
+* PR #1：受放大器启发的问题解决和研究技能
+* PR #2：个人 superpowers 覆盖系统（后来被取代）
+* 多次技能细化和文档改进
+
+## 升级说明
+
+### 全新安装
+
+```bash
+# In Claude Code
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+
+插件自动处理一切。
+
+### 从 v1.x 升级
+
+1. **备份您的个人技能**（如果有的话）：
+   ```bash
+   cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup
+   ```
+
+2. **更新插件：**
+   ```bash
+   /plugin update superpowers
+   ```
+
+3. **在下一次会话开始时：**
+   * 旧安装将自动备份
+   * 将克隆全新的技能仓库
+   * 如果你有 GitHub CLI，系统将提供 fork 选项
+
+4. **迁移个人技能**（如果你有的话）：
+   * 在本地技能仓库中创建一个分支
+   * 从备份中复制你的个人技能
+   * 提交并推送到你的 fork
+   * 考虑通过 PR 回馈社区
+
+## 下一步
+
+### 对于用户
+
+* 探索新的问题解决技能
+* 尝试基于分支的工作流来改进技能
+* 将技能贡献回社区
+
+### 对于贡献者
+
+* 技能仓库现位于 https://github.com/obra/superpowers-skills
+* 采用 Fork → 分支 → PR 的工作流
+* 查看 skills/meta/writing-skills/SKILL.md 了解文档的 TDD 方法
+
+## 已知问题
+
+目前没有。
+
+## 致谢
+
+* 问题解决技能灵感来源于 Amplifier 模式
+* 社区贡献和反馈
+* 对技能有效性进行了广泛的测试和迭代
+
+***
+
+**完整更新日志：** https://github.com/obra/superpowers/compare/dd013f6...main
+**技能仓库：** https://github.com/obra/superpowers-skills
+**问题反馈：** https://github.com/obra/superpowers/issues
diff --git a/zh-CN/agents/code-reviewer.md b/zh-CN/agents/code-reviewer.md
new file mode 100644
index 0000000000..d068cb2033
--- /dev/null
+++ b/zh-CN/agents/code-reviewer.md
@@ -0,0 +1,47 @@
+---
+name: code-reviewer
+description: 当主要项目步骤已完成，需要对照原始计划和编码标准进行审查时，请使用此代理。示例：<example>上下文：用户正在创建一个代码审查代理，该代理应在编写完逻辑代码块后被调用。用户：“我已按照计划第3步完成了用户身份验证系统的实现” 助手：“干得好！现在让我使用代码审查代理来对照我们的计划和编码标准审查此实现” <commentary>由于主要项目步骤已完成，使用代码审查代理来验证工作是否符合计划并识别任何问题。</commentary></example> <example>上下文：用户已完成一个重要功能实现。用户：“任务管理系统的API端点现已完成——这涵盖了架构文档中的第2步” 助手：“太好了！让我请代码审查代理检查此实现，以确保其符合我们的计划并遵循最佳实践” <commentary>计划文档中的一个编号步骤已完成，因此应使用代码审查代理审查工作。</commentary></example>
+model: inherit
+---
+
+你是一位资深代码审查员，在软件架构、设计模式和最佳实践方面拥有专业知识。你的职责是根据原始计划审查已完成的项目步骤，并确保代码质量达标。
+
+在审查已完成的工作时，你将：
+
+1. **计划对齐分析**：
+   * 将实现与原始规划文档或步骤描述进行对比
+   * 识别与计划方法、架构或要求的任何偏差
+   * 评估偏差是合理的改进还是有问题的偏离
+   * 验证所有计划的功能是否已实现
+
+2. **代码质量评估**：
+   * 审查代码是否遵循既定模式和约定
+   * 检查是否正确处理错误、类型安全以及防御性编程
+   * 评估代码组织、命名约定和可维护性
+   * 评估测试覆盖率和测试实现的质量
+   * 寻找潜在的安全漏洞或性能问题
+
+3. **架构与设计审查**：
+   * 确保实现遵循 SOLID 原则和既定的架构模式
+   * 检查是否实现了适当的关注点分离和松耦合
+   * 验证代码与现有系统的集成是否良好
+   * 评估可扩展性和可扩展性方面的考量
+
+4. **文档与标准**：
+   * 验证代码是否包含适当的注释和文档
+   * 检查文件头、函数文档和内联注释是否存在且准确
+   * 确保遵守项目特定的编码标准和约定
+
+5. **问题识别与建议**：
+   * 将问题明确分类为：关键（必须修复）、重要（应该修复）或建议（最好有）
+   * 针对每个问题，提供具体示例和可操作的建议
+   * 当识别出计划偏差时，解释其是有问题的还是有益的
+   * 在必要时，提供包含代码示例的具体改进建议
+
+6. **沟通协议**：
+   * 如果发现与计划存在重大偏差，请要求编码代理审查并确认更改
+   * 如果发现原始计划本身存在问题，建议更新计划
+   * 对于实现问题，提供关于所需修复的明确指导
+   * 在强调问题之前，始终先肯定做得好的方面
+
+你的输出应具有结构性、可操作性，并专注于帮助维持高代码质量，同时确保项目目标达成。要做到彻底但简洁，始终提供建设性反馈，以帮助改进当前实现和未来的开发实践。
diff --git a/zh-CN/commands/brainstorm.md b/zh-CN/commands/brainstorm.md
new file mode 100644
index 0000000000..ab1b54110d
--- /dev/null
+++ b/zh-CN/commands/brainstorm.md
@@ -0,0 +1,5 @@
+---
+description: "已弃用 - 请改用 superpowers:头脑风暴技能"
+---
+
+告诉你的合作伙伴，这个命令已被弃用，并将在下一个主要版本中移除。他们应该要求你使用“superpowers 头脑风暴”技能代替。
diff --git a/zh-CN/commands/execute-plan.md b/zh-CN/commands/execute-plan.md
new file mode 100644
index 0000000000..d827d82f37
--- /dev/null
+++ b/zh-CN/commands/execute-plan.md
@@ -0,0 +1,5 @@
+---
+description: "已弃用 - 请改用 superpowers:executing-plans 技能"
+---
+
+告诉你的合作伙伴，这个命令已被弃用，并将在下一个主要版本中移除。他们应该要求你使用“superpowers executing-plans”技能来代替。
diff --git a/zh-CN/commands/write-plan.md b/zh-CN/commands/write-plan.md
new file mode 100644
index 0000000000..a1d81c49ba
--- /dev/null
+++ b/zh-CN/commands/write-plan.md
@@ -0,0 +1,5 @@
+---
+description: "已弃用 - 请改用 superpowers:writing-plans 技能"
+---
+
+告诉你的合作伙伴，这个命令已被弃用，并将在下一个主要版本中移除。他们应该要求你使用 "superpowers writing-plans" 技能。
diff --git a/zh-CN/docs/README.codex.md b/zh-CN/docs/README.codex.md
new file mode 100644
index 0000000000..a92a74ef47
--- /dev/null
+++ b/zh-CN/docs/README.codex.md
@@ -0,0 +1,128 @@
+# Superpowers for Codex
+
+使用原生技能发现功能，通过 OpenAI Codex 使用 Superpowers 的指南。
+
+## 快速安装
+
+告诉 Codex：
+
+```
+从 https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md 获取并遵循指令
+```
+
+## 手动安装
+
+### 先决条件
+
+* OpenAI Codex CLI
+* Git
+
+### 步骤
+
+1. 克隆仓库：
+   ```bash
+   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
+   ```
+
+2. 创建技能符号链接：
+   ```bash
+   mkdir -p ~/.agents/skills
+   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
+   ```
+
+3. 重启 Codex。
+
+4. **对于子代理技能**（可选）：诸如 `dispatching-parallel-agents` 和 `subagent-driven-development` 这类技能需要 Codex 的多代理功能。请将以下内容添加到你的 Codex 配置中：
+   ```toml
+   [features]
+   multi_agent = true
+   ```
+
+### Windows
+
+使用连接点代替符号链接（无需开发者模式）：
+
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
+```
+
+## 工作原理
+
+Codex 具有原生技能发现功能——它在启动时扫描 `~/.agents/skills/`，解析 SKILL.md 的前置元数据，并按需加载技能。Superpowers 技能通过单个符号链接变得可见：
+
+```
+~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
+```
+
+`using-superpowers` 技能会被自动发现，并强制执行技能使用规范——无需额外配置。
+
+## 使用
+
+技能会被自动发现。Codex 在以下情况下激活它们：
+
+* 你按名称提及一个技能（例如，“使用 brainstorming”）
+* 任务与某个技能的描述匹配
+* `using-superpowers` 技能指示 Codex 使用某个技能
+
+### 个人技能
+
+在 `~/.agents/skills/` 中创建你自己的技能：
+
+```bash
+mkdir -p ~/.agents/skills/my-skill
+```
+
+创建 `~/.agents/skills/my-skill/SKILL.md`：
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [what it does]
+---
+
+# 我的技能
+
+[你的技能内容在这里]
+```
+
+`description` 字段是 Codex 决定何时自动激活技能的依据——将其写成一个清晰的触发条件。
+
+## 更新
+
+```bash
+cd ~/.codex/superpowers && git pull
+```
+
+技能通过符号链接即时更新。
+
+## 卸载
+
+```bash
+rm ~/.agents/skills/superpowers
+```
+
+**Windows (PowerShell)：**
+
+```powershell
+Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
+```
+
+可选择删除克隆的仓库：`rm -rf ~/.codex/superpowers`（Windows：`Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`）。
+
+## 故障排除
+
+### 技能未显示
+
+1. 验证符号链接：`ls -la ~/.agents/skills/superpowers`
+2. 检查技能是否存在：`ls ~/.codex/superpowers/skills`
+3. 重启 Codex——技能在启动时被发现
+
+### Windows 连接点问题
+
+连接点通常无需特殊权限即可工作。如果创建失败，请尝试以管理员身份运行 PowerShell。
+
+## 获取帮助
+
+* 报告问题：https://github.com/obra/superpowers/issues
+* 主要文档：https://github.com/obra/superpowers
diff --git a/zh-CN/docs/README.opencode.md b/zh-CN/docs/README.opencode.md
new file mode 100644
index 0000000000..3e5cd75db2
--- /dev/null
+++ b/zh-CN/docs/README.opencode.md
@@ -0,0 +1,130 @@
+# OpenCode 的 Superpowers
+
+与 [OpenCode.ai](https://opencode.ai) 一起使用 Superpowers 的完整指南。
+
+## 安装
+
+将 superpowers 添加到你的 `opencode.json`（全局或项目级）中的 `plugin` 数组：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+重启 OpenCode。插件将通过 Bun 自动安装并自动注册所有技能。
+
+通过询问以下内容进行验证：“告诉我关于你的 superpowers”
+
+### 从旧的基于符号链接的安装迁移
+
+如果你之前使用 `git clone` 和符号链接安装了 superpowers，请移除旧设置：
+
+```bash
+# Remove old symlinks
+rm -f ~/.config/opencode/plugins/superpowers.js
+rm -rf ~/.config/opencode/skills/superpowers
+
+# Optionally remove the cloned repo
+rm -rf ~/.config/opencode/superpowers
+
+# Remove skills.paths from opencode.json if you added one for superpowers
+```
+
+然后按照上述安装步骤操作。
+
+## 使用
+
+### 查找技能
+
+使用 OpenCode 原生的 `skill` 工具列出所有可用技能：
+
+```
+使用技能工具来列出技能
+```
+
+### 加载技能
+
+```
+使用技能工具加载 superpowers/brainstorming
+```
+
+### 个人技能
+
+在 `~/.config/opencode/skills/` 中创建您自己的技能：
+
+```bash
+mkdir -p ~/.config/opencode/skills/my-skill
+```
+
+创建 `~/.config/opencode/skills/my-skill/SKILL.md`：
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [what it does]
+---
+
+# 我的技能
+
+[你的技能内容在此]
+```
+
+### 项目技能
+
+在你的项目中，于 `.opencode/skills/` 内创建项目特定技能。
+
+**技能优先级：** 项目技能 > 个人技能 > Superpowers 技能
+
+## 更新
+
+Superpowers 在你重启 OpenCode 时会自动更新。插件在每次启动时都会从 git 仓库重新安装。
+
+要固定特定版本，请使用分支或标签：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
+```
+
+## 工作原理
+
+该插件执行两项操作：
+
+1. **通过 `experimental.chat.system.transform` 钩子注入引导上下文**，为每次对话添加 superpowers 感知。
+2. **通过 `config` 钩子注册技能目录**，以便 OpenCode 无需符号链接或手动配置即可发现所有 superpowers 技能。
+
+### 工具映射
+
+为 Claude Code 编写的技能会自动适配到 OpenCode：
+
+* `TodoWrite` → `todowrite`
+* 带有子代理的 `Task` → OpenCode 的 `@mention` 系统
+* `Skill` 工具 → OpenCode 原生的 `skill` 工具
+* 文件操作 → 原生 OpenCode 工具
+
+## 故障排除
+
+### 插件未加载
+
+1. 检查 OpenCode 日志：`opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+2. 验证你的 `opencode.json` 中的插件行是否正确
+3. 确保你运行的是最新版本的 OpenCode
+
+### 技能未找到
+
+1. 使用 OpenCode 的 `skill` 工具列出可用技能
+2. 检查插件是否正在加载（见上文）
+3. 每个技能都需要一个带有有效 YAML 前置元数据的 `SKILL.md` 文件
+
+### 引导程序未出现
+
+1. 检查 OpenCode 版本是否支持 `experimental.chat.system.transform` 钩子
+2. 在配置更改后重启 OpenCode
+
+## 获取帮助
+
+* 报告问题：https://github.com/obra/superpowers/issues
+* 主要文档：https://github.com/obra/superpowers
+* OpenCode 文档：https://opencode.ai/docs/
diff --git a/zh-CN/docs/plans/2025-11-22-opencode-support-design.md b/zh-CN/docs/plans/2025-11-22-opencode-support-design.md
new file mode 100644
index 0000000000..c443c171ad
--- /dev/null
+++ b/zh-CN/docs/plans/2025-11-22-opencode-support-design.md
@@ -0,0 +1,294 @@
+# OpenCode 支持设计
+
+**日期：** 2025-11-22
+**作者：** Bot & Jesse
+**状态：** 设计完成，待实施
+
+## 概述
+
+通过使用与现有 Codex 实现共享核心功能的本机 OpenCode 插件架构，为 OpenCode.ai 添加完整的 superpowers 支持。
+
+## 背景
+
+OpenCode.ai 是一个类似于 Claude Code 和 Codex 的编码代理。之前将 superpowers 移植到 OpenCode 的尝试（PR #93, PR #116）使用了文件复制方法。本设计采用不同的方法：使用 OpenCode 的 JavaScript/TypeScript 插件系统构建一个本机 OpenCode 插件，同时与 Codex 实现共享代码。
+
+### 平台间的关键差异
+
+* **Claude Code**：本机 Anthropic 插件系统 + 基于文件的技能
+* **Codex**：无插件系统 → 引导式 markdown + CLI 脚本
+* **OpenCode**：具有事件钩子和自定义工具 API 的 JavaScript/TypeScript 插件
+
+### OpenCode 的代理系统
+
+* **主要代理**：构建（默认，完全访问）和计划（受限，只读）
+* **子代理**：通用（研究、搜索、多步骤任务）
+* **调用方式**：由主要代理自动分派 或 手动 `@mention` 语法
+* **配置**：在 `opencode.json` 或 `~/.config/opencode/agent/` 中配置自定义代理
+
+## 架构
+
+### 高层次结构
+
+1. **共享核心模块** (`lib/skills-core.js`)
+   * 通用的技能发现和解析逻辑
+   * 由 Codex 和 OpenCode 实现共同使用
+
+2. **平台特定包装器**
+   * Codex：CLI 脚本 (`.codex/superpowers-codex`)
+   * OpenCode：插件模块 (`.opencode/plugin/superpowers.js`)
+
+3. **技能目录**
+   * 核心：`~/.config/opencode/superpowers/skills/`（或安装位置）
+   * 个人：`~/.config/opencode/skills/`（覆盖核心技能）
+
+### 代码复用策略
+
+从 `.codex/superpowers-codex` 中提取通用功能到共享模块：
+
+```javascript
+// lib/skills-core.js
+module.exports = {
+  extractFrontmatter(filePath),      // Parse name + description from YAML
+  findSkillsInDir(dir, maxDepth),    // Recursive SKILL.md discovery
+  findAllSkills(dirs),                // Scan multiple directories
+  resolveSkillPath(skillName, dirs), // Handle shadowing (personal > core)
+  checkForUpdates(repoDir)           // Git fetch/status check
+};
+```
+
+### 技能 Frontmatter 格式
+
+当前格式（无 `when_to_use` 字段）：
+
+```yaml
+---
+name: skill-name
+description: Use when [condition] - [what it does]; [additional context]
+---
+```
+
+## OpenCode 插件实现
+
+### 自定义工具
+
+**工具 1：`use_skill`**
+
+将特定技能的内容加载到对话中（相当于 Claude 的 Skill 工具）。
+
+```javascript
+{
+  name: 'use_skill',
+  description: 'Load and read a specific skill to guide your work',
+  schema: z.object({
+    skill_name: z.string().describe('Name of skill (e.g., "superpowers:brainstorming")')
+  }),
+  execute: async ({ skill_name }) => {
+    const { skillPath, content, frontmatter } = resolveAndReadSkill(skill_name);
+    const skillDir = path.dirname(skillPath);
+
+    return `# ${frontmatter.name}
+# ${frontmatter.description}
+# Supporting tools and docs are in ${skillDir}
+# ============================================
+
+${content}`;
+  }
+}
+```
+
+**工具 2：`find_skills`**
+
+列出所有可用技能及其元数据。
+
+```javascript
+{
+  name: 'find_skills',
+  description: 'List all available skills',
+  schema: z.object({}),
+  execute: async () => {
+    const skills = discoverAllSkills();
+    return skills.map(s =>
+      `${s.namespace}:${s.name}
+  ${s.description}
+  Directory: ${s.directory}
+`).join('\n');
+  }
+}
+```
+
+### 会话启动钩子
+
+当新会话开始时（`session.started` 事件）：
+
+1. **注入 using-superpowers 内容**
+   * using-superpowers 技能的全部内容
+   * 建立强制性的工作流程
+
+2. **自动运行 find\_skills**
+   * 预先显示完整的可用技能列表
+   * 包含每个技能的目录
+
+3. **注入工具映射说明**
+   ```markdown
+   **OpenCode 工具映射：**
+   当技能引用你未拥有的工具时，请替换为：
+   - `TodoWrite` → `update_plan`
+   - 带有子代理的 `Task` → 使用 OpenCode 子代理系统（@提及）
+   - `Skill` 工具 → `use_skill` 自定义工具
+   - Read、Write、Edit、Bash → 你的本机等效工具
+
+   **技能目录包含：**
+   - 支持脚本（使用 bash 运行）
+   - 附加文档（使用 read 工具读取）
+   - 该技能特定的实用程序
+   ```
+
+4. **检查更新**（非阻塞）
+   * 带超时的快速 git fetch
+   * 如有可用更新则通知
+
+### 插件结构
+
+```javascript
+// .opencode/plugin/superpowers.js
+const skillsCore = require('../../lib/skills-core');
+const path = require('path');
+const fs = require('fs');
+const { z } = require('zod');
+
+export const SuperpowersPlugin = async ({ client, directory, $ }) => {
+  const superpowersDir = path.join(process.env.HOME, '.config/opencode/superpowers');
+  const personalDir = path.join(process.env.HOME, '.config/opencode/skills');
+
+  return {
+    'session.started': async () => {
+      const usingSuperpowers = await readSkill('using-superpowers');
+      const skillsList = await findAllSkills();
+      const toolMapping = getToolMappingInstructions();
+
+      return {
+        context: `${usingSuperpowers}\n\n${skillsList}\n\n${toolMapping}`
+      };
+    },
+
+    tools: [
+      {
+        name: 'use_skill',
+        description: 'Load and read a specific skill',
+        schema: z.object({
+          skill_name: z.string()
+        }),
+        execute: async ({ skill_name }) => {
+          // Implementation using skillsCore
+        }
+      },
+      {
+        name: 'find_skills',
+        description: 'List all available skills',
+        schema: z.object({}),
+        execute: async () => {
+          // Implementation using skillsCore
+        }
+      }
+    ]
+  };
+};
+```
+
+## 文件结构
+
+```
+superpowers/
+├── lib/
+│   └── skills-core.js           # 新增：共享技能逻辑
+├── .codex/
+│   ├── superpowers-codex        # 已更新：使用 skills-core
+│   ├── superpowers-bootstrap.md
+│   └── INSTALL.md
+├── .opencode/
+│   ├── plugin/
+│   │   └── superpowers.js       # 新增：OpenCode 插件
+│   └── INSTALL.md               # 新增：安装指南
+└── skills/                       # 未更改
+```
+
+## 实施计划
+
+### 阶段 1：重构共享核心
+
+1. 创建 `lib/skills-core.js`
+   * 从 `.codex/superpowers-codex` 中提取 frontmatter 解析逻辑
+   * 提取技能发现逻辑
+   * 提取路径解析逻辑（含覆盖机制）
+   * 更新为仅使用 `name` 和 `description`（不使用 `when_to_use`）
+
+2. 更新 `.codex/superpowers-codex` 以使用共享核心
+   * 从 `../lib/skills-core.js` 导入
+   * 移除重复代码
+   * 保留 CLI 包装器逻辑
+
+3. 测试 Codex 实现是否仍然有效
+   * 验证 bootstrap 命令
+   * 验证 use-skill 命令
+   * 验证 find-skills 命令
+
+### 阶段 2：构建 OpenCode 插件
+
+1. 创建 `.opencode/plugin/superpowers.js`
+   * 从 `../../lib/skills-core.js` 导入共享核心
+   * 实现插件函数
+   * 定义自定义工具（use\_skill, find\_skills）
+   * 实现 session.started 钩子
+
+2. 创建 `.opencode/INSTALL.md`
+   * 安装说明
+   * 目录设置
+   * 配置指南
+
+3. 测试 OpenCode 实现
+   * 验证会话启动引导
+   * 验证 use\_skill 工具工作正常
+   * 验证 find\_skills 工具工作正常
+   * 验证技能目录可访问
+
+### 阶段 3：文档与完善
+
+1. 更新 README，包含 OpenCode 支持
+2. 在主文档中添加 OpenCode 安装说明
+3. 更新 RELEASE-NOTES
+4. 测试 Codex 和 OpenCode 是否都能正常工作
+
+## 后续步骤
+
+1. **创建独立工作区**（使用 git worktrees）
+   * 分支：`feature/opencode-support`
+
+2. **在适用处遵循 TDD**
+   * 测试共享核心函数
+   * 测试技能发现和解析
+   * 两个平台的集成测试
+
+3. **增量实施**
+   * 阶段 1：重构共享核心 + 更新 Codex
+   * 继续之前验证 Codex 是否仍有效
+   * 阶段 2：构建 OpenCode 插件
+   * 阶段 3：文档与完善
+
+4. **测试策略**
+   * 使用真实的 OpenCode 安装进行手动测试
+   * 验证技能加载、目录、脚本正常工作
+   * 并排测试 Codex 和 OpenCode
+   * 验证工具映射正常工作
+
+5. **PR 与合并**
+   * 创建包含完整实现的 PR
+   * 在干净环境中测试
+   * 合并到主分支
+
+## 优势
+
+* **代码复用**：技能发现/解析的单一事实来源
+* **可维护性**：错误修复适用于两个平台
+* **可扩展性**：易于添加未来平台（Cursor、Windsurf 等）
+* **本机集成**：正确使用 OpenCode 的插件系统
+* **一致性**：在所有平台上获得相同的技能体验
diff --git a/zh-CN/docs/plans/2025-11-22-opencode-support-implementation.md b/zh-CN/docs/plans/2025-11-22-opencode-support-implementation.md
new file mode 100644
index 0000000000..c6d505fe42
--- /dev/null
+++ b/zh-CN/docs/plans/2025-11-22-opencode-support-implementation.md
@@ -0,0 +1,1119 @@
+# OpenCode 支持实施计划
+
+> **对于代理工作者：** 必需子技能：使用 superpowers:executing-plans 来逐任务实施此计划。
+
+**目标：** 为 OpenCode.ai 添加完整的 superpowers 支持，使用一个与现有 Codex 实现共享核心功能的原生 JavaScript 插件。
+
+**架构：** 将通用技能发现/解析逻辑提取到 `lib/skills-core.js` 中，重构 Codex 以使用它，然后使用其原生插件 API 以及自定义工具和会话钩子构建 OpenCode 插件。
+
+**技术栈：** Node.js, JavaScript, OpenCode 插件 API, Git worktrees
+
+***
+
+## 阶段 1：创建共享核心模块
+
+### 任务 1：提取 Frontmatter 解析
+
+**文件：**
+
+* 创建：`lib/skills-core.js`
+* 参考：`.codex/superpowers-codex` (第 40-74 行)
+
+**步骤 1：创建 lib/skills-core.js 并包含 extractFrontmatter 函数**
+
+```javascript
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract YAML frontmatter from a skill file.
+ * Current format:
+ * ---
+ * name: skill-name
+ * description: Use when [condition] - [what it does]
+ * ---
+ *
+ * @param {string} filePath - Path to SKILL.md file
+ * @returns {{name: string, description: string}}
+ */
+function extractFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n');
+
+        let inFrontmatter = false;
+        let name = '';
+        let description = '';
+
+        for (const line of lines) {
+            if (line.trim() === '---') {
+                if (inFrontmatter) break;
+                inFrontmatter = true;
+                continue;
+            }
+
+            if (inFrontmatter) {
+                const match = line.match(/^(\w+):\s*(.*)$/);
+                if (match) {
+                    const [, key, value] = match;
+                    switch (key) {
+                        case 'name':
+                            name = value.trim();
+                            break;
+                        case 'description':
+                            description = value.trim();
+                            break;
+                    }
+                }
+            }
+        }
+
+        return { name, description };
+    } catch (error) {
+        return { name: '', description: '' };
+    }
+}
+
+module.exports = {
+    extractFrontmatter
+};
+```
+
+**步骤 2：验证文件已创建**
+
+运行：`ls -l lib/skills-core.js`
+预期：文件存在
+
+**步骤 3：提交**
+
+```bash
+git add lib/skills-core.js
+git commit -m "feat: create shared skills core module with frontmatter parser"
+```
+
+***
+
+### 任务 2：提取技能发现逻辑
+
+**文件：**
+
+* 修改：`lib/skills-core.js`
+* 参考：`.codex/superpowers-codex` (第 97-136 行)
+
+**步骤 1：向 skills-core.js 添加 findSkillsInDir 函数**
+
+在 `module.exports` 之前添加：
+
+```javascript
+/**
+ * Find all SKILL.md files in a directory recursively.
+ *
+ * @param {string} dir - Directory to search
+ * @param {string} sourceType - 'personal' or 'superpowers' for namespacing
+ * @param {number} maxDepth - Maximum recursion depth (default: 3)
+ * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
+ */
+function findSkillsInDir(dir, sourceType, maxDepth = 3) {
+    const skills = [];
+
+    if (!fs.existsSync(dir)) return skills;
+
+    function recurse(currentDir, depth) {
+        if (depth > maxDepth) return;
+
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+
+            if (entry.isDirectory()) {
+                // Check for SKILL.md in this directory
+                const skillFile = path.join(fullPath, 'SKILL.md');
+                if (fs.existsSync(skillFile)) {
+                    const { name, description } = extractFrontmatter(skillFile);
+                    skills.push({
+                        path: fullPath,
+                        skillFile: skillFile,
+                        name: name || entry.name,
+                        description: description || '',
+                        sourceType: sourceType
+                    });
+                }
+
+                // Recurse into subdirectories
+                recurse(fullPath, depth + 1);
+            }
+        }
+    }
+
+    recurse(dir, 0);
+    return skills;
+}
+```
+
+**步骤 2：更新 module.exports**
+
+替换导出行为：
+
+```javascript
+module.exports = {
+    extractFrontmatter,
+    findSkillsInDir
+};
+```
+
+**步骤 3：验证语法**
+
+运行：`node -c lib/skills-core.js`
+预期：无输出（成功）
+
+**步骤 4：提交**
+
+```bash
+git add lib/skills-core.js
+git commit -m "feat: add skill discovery function to core module"
+```
+
+***
+
+### 任务 3：提取技能解析逻辑
+
+**文件：**
+
+* 修改：`lib/skills-core.js`
+* 参考：`.codex/superpowers-codex` (第 212-280 行)
+
+**步骤 1：添加 resolveSkillPath 函数**
+
+在 `module.exports` 之前添加：
+
+```javascript
+/**
+ * Resolve a skill name to its file path, handling shadowing
+ * (personal skills override superpowers skills).
+ *
+ * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill"
+ * @param {string} superpowersDir - Path to superpowers skills directory
+ * @param {string} personalDir - Path to personal skills directory
+ * @returns {{skillFile: string, sourceType: string, skillPath: string} | null}
+ */
+function resolveSkillPath(skillName, superpowersDir, personalDir) {
+    // Strip superpowers: prefix if present
+    const forceSuperpowers = skillName.startsWith('superpowers:');
+    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
+
+    // Try personal skills first (unless explicitly superpowers:)
+    if (!forceSuperpowers && personalDir) {
+        const personalPath = path.join(personalDir, actualSkillName);
+        const personalSkillFile = path.join(personalPath, 'SKILL.md');
+        if (fs.existsSync(personalSkillFile)) {
+            return {
+                skillFile: personalSkillFile,
+                sourceType: 'personal',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    // Try superpowers skills
+    if (superpowersDir) {
+        const superpowersPath = path.join(superpowersDir, actualSkillName);
+        const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
+        if (fs.existsSync(superpowersSkillFile)) {
+            return {
+                skillFile: superpowersSkillFile,
+                sourceType: 'superpowers',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    return null;
+}
+```
+
+**步骤 2：更新 module.exports**
+
+```javascript
+module.exports = {
+    extractFrontmatter,
+    findSkillsInDir,
+    resolveSkillPath
+};
+```
+
+**步骤 3：验证语法**
+
+运行：`node -c lib/skills-core.js`
+预期：无输出
+
+**步骤 4：提交**
+
+```bash
+git add lib/skills-core.js
+git commit -m "feat: add skill path resolution with shadowing support"
+```
+
+***
+
+### 任务 4：提取更新检查逻辑
+
+**文件：**
+
+* 修改：`lib/skills-core.js`
+* 参考：`.codex/superpowers-codex` (第 16-38 行)
+
+**步骤 1：添加 checkForUpdates 函数**
+
+在顶部 require 之后添加：
+
+```javascript
+const { execSync } = require('child_process');
+```
+
+在 `module.exports` 之前添加：
+
+```javascript
+/**
+ * Check if a git repository has updates available.
+ *
+ * @param {string} repoDir - Path to git repository
+ * @returns {boolean} - True if updates are available
+ */
+function checkForUpdates(repoDir) {
+    try {
+        // Quick check with 3 second timeout to avoid delays if network is down
+        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
+            cwd: repoDir,
+            timeout: 3000,
+            encoding: 'utf8',
+            stdio: 'pipe'
+        });
+
+        // Parse git status output to see if we're behind
+        const statusLines = output.split('\n');
+        for (const line of statusLines) {
+            if (line.startsWith('## ') && line.includes('[behind ')) {
+                return true; // We're behind remote
+            }
+        }
+        return false; // Up to date
+    } catch (error) {
+        // Network down, git error, timeout, etc. - don't block bootstrap
+        return false;
+    }
+}
+```
+
+**步骤 2：更新 module.exports**
+
+```javascript
+module.exports = {
+    extractFrontmatter,
+    findSkillsInDir,
+    resolveSkillPath,
+    checkForUpdates
+};
+```
+
+**步骤 3：验证语法**
+
+运行：`node -c lib/skills-core.js`
+预期：无输出
+
+**步骤 4：提交**
+
+```bash
+git add lib/skills-core.js
+git commit -m "feat: add git update checking to core module"
+```
+
+***
+
+## 阶段 2：重构 Codex 以使用共享核心
+
+### 任务 5：更新 Codex 以导入共享核心
+
+**文件：**
+
+* 修改：`.codex/superpowers-codex` (在顶部添加导入)
+
+**步骤 1：添加导入语句**
+
+在文件顶部现有的 require 之后（大约第 6 行），添加：
+
+```javascript
+const skillsCore = require('../lib/skills-core');
+```
+
+**步骤 2：验证语法**
+
+运行：`node -c .codex/superpowers-codex`
+预期：无输出
+
+**步骤 3：提交**
+
+```bash
+git add .codex/superpowers-codex
+git commit -m "refactor: import shared skills core in codex"
+```
+
+***
+
+### 任务 6：将 extractFrontmatter 替换为核心版本
+
+**文件：**
+
+* 修改：`.codex/superpowers-codex` (第 40-74 行)
+
+**步骤 1：移除本地的 extractFrontmatter 函数**
+
+删除第 40-74 行（整个 extractFrontmatter 函数定义）。
+
+**步骤 2：更新所有 extractFrontmatter 调用**
+
+查找并替换所有调用，从 `extractFrontmatter(` 到 `skillsCore.extractFrontmatter(`
+
+受影响的代码行大约在：90, 310
+
+**步骤 3：验证脚本仍然工作**
+
+运行：`.codex/superpowers-codex find-skills | head -20`
+预期：显示技能列表
+
+**步骤 4：提交**
+
+```bash
+git add .codex/superpowers-codex
+git commit -m "refactor: use shared extractFrontmatter in codex"
+```
+
+***
+
+### 任务 7：将 findSkillsInDir 替换为核心版本
+
+**文件：**
+
+* 修改：`.codex/superpowers-codex` (大约第 97-136 行)
+
+**步骤 1：移除本地的 findSkillsInDir 函数**
+
+删除整个 `findSkillsInDir` 函数定义（大约第 97-136 行）。
+
+**步骤 2：更新所有 findSkillsInDir 调用**
+
+将调用从 `findSkillsInDir(` 替换为 `skillsCore.findSkillsInDir(`
+
+**步骤 3：验证脚本仍然工作**
+
+运行：`.codex/superpowers-codex find-skills | head -20`
+预期：显示技能列表
+
+**步骤 4：提交**
+
+```bash
+git add .codex/superpowers-codex
+git commit -m "refactor: use shared findSkillsInDir in codex"
+```
+
+***
+
+### 任务 8：将 checkForUpdates 替换为核心版本
+
+**文件：**
+
+* 修改：`.codex/superpowers-codex` (大约第 16-38 行)
+
+**步骤 1：移除本地的 checkForUpdates 函数**
+
+删除整个 `checkForUpdates` 函数定义。
+
+**步骤 2：更新所有 checkForUpdates 调用**
+
+将调用从 `checkForUpdates(` 替换为 `skillsCore.checkForUpdates(`
+
+**步骤 3：验证脚本仍然工作**
+
+运行：`.codex/superpowers-codex bootstrap | head -50`
+预期：显示引导内容
+
+**步骤 4：提交**
+
+```bash
+git add .codex/superpowers-codex
+git commit -m "refactor: use shared checkForUpdates in codex"
+```
+
+***
+
+## 阶段 3：构建 OpenCode 插件
+
+### 任务 9：创建 OpenCode 插件目录结构
+
+**文件：**
+
+* 创建：`.opencode/plugin/superpowers.js`
+
+**步骤 1：创建目录**
+
+运行：`mkdir -p .opencode/plugin`
+
+**步骤 2：创建基础插件文件**
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * Superpowers plugin for OpenCode.ai
+ *
+ * Provides custom tools for loading and discovering skills,
+ * with automatic bootstrap on session start.
+ */
+
+const skillsCore = require('../../lib/skills-core');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const homeDir = os.homedir();
+const superpowersSkillsDir = path.join(homeDir, '.config/opencode/superpowers/skills');
+const personalSkillsDir = path.join(homeDir, '.config/opencode/skills');
+
+/**
+ * OpenCode plugin entry point
+ */
+export const SuperpowersPlugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    // Custom tools and hooks will go here
+  };
+};
+```
+
+**步骤 3：验证文件已创建**
+
+运行：`ls -l .opencode/plugin/superpowers.js`
+预期：文件存在
+
+**步骤 4：提交**
+
+```bash
+git add .opencode/plugin/superpowers.js
+git commit -m "feat: create opencode plugin scaffold"
+```
+
+***
+
+### 任务 10：实现 use\_skill 工具
+
+**文件：**
+
+* 修改：`.opencode/plugin/superpowers.js`
+
+**步骤 1：添加 use\_skill 工具实现**
+
+替换插件的返回语句为：
+
+```javascript
+export const SuperpowersPlugin = async ({ project, client, $, directory, worktree }) => {
+  // Import zod for schema validation
+  const { z } = await import('zod');
+
+  return {
+    tools: [
+      {
+        name: 'use_skill',
+        description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques.',
+        schema: z.object({
+          skill_name: z.string().describe('Name of the skill to load (e.g., "superpowers:brainstorming" or "my-custom-skill")')
+        }),
+        execute: async ({ skill_name }) => {
+          // Resolve skill path (handles shadowing: personal > superpowers)
+          const resolved = skillsCore.resolveSkillPath(
+            skill_name,
+            superpowersSkillsDir,
+            personalSkillsDir
+          );
+
+          if (!resolved) {
+            return `Error: Skill "${skill_name}" not found.\n\nRun find_skills to see available skills.`;
+          }
+
+          // Read skill content
+          const fullContent = fs.readFileSync(resolved.skillFile, 'utf8');
+          const { name, description } = skillsCore.extractFrontmatter(resolved.skillFile);
+
+          // Extract content after frontmatter
+          const lines = fullContent.split('\n');
+          let inFrontmatter = false;
+          let frontmatterEnded = false;
+          const contentLines = [];
+
+          for (const line of lines) {
+            if (line.trim() === '---') {
+              if (inFrontmatter) {
+                frontmatterEnded = true;
+                continue;
+              }
+              inFrontmatter = true;
+              continue;
+            }
+
+            if (frontmatterEnded || !inFrontmatter) {
+              contentLines.push(line);
+            }
+          }
+
+          const content = contentLines.join('\n').trim();
+          const skillDirectory = path.dirname(resolved.skillFile);
+
+          // Format output similar to Claude Code's Skill tool
+          return `# ${name || skill_name}
+# ${description || ''}
+# Supporting tools and docs are in ${skillDirectory}
+# ============================================
+
+${content}`;
+        }
+      }
+    ]
+  };
+};
+```
+
+**步骤 2：验证语法**
+
+运行：`node -c .opencode/plugin/superpowers.js`
+预期：无输出
+
+**步骤 3：提交**
+
+```bash
+git add .opencode/plugin/superpowers.js
+git commit -m "feat: implement use_skill tool for opencode"
+```
+
+***
+
+### 任务 11：实现 find\_skills 工具
+
+**文件：**
+
+* 修改：`.opencode/plugin/superpowers.js`
+
+**步骤 1：向工具数组添加 find\_skills 工具**
+
+在 use\_skill 工具定义之后，关闭工具数组之前添加：
+
+```javascript
+      {
+        name: 'find_skills',
+        description: 'List all available skills in the superpowers and personal skill libraries.',
+        schema: z.object({}),
+        execute: async () => {
+          // Find skills in both directories
+          const superpowersSkills = skillsCore.findSkillsInDir(
+            superpowersSkillsDir,
+            'superpowers',
+            3
+          );
+          const personalSkills = skillsCore.findSkillsInDir(
+            personalSkillsDir,
+            'personal',
+            3
+          );
+
+          // Combine and format skills list
+          const allSkills = [...personalSkills, ...superpowersSkills];
+
+          if (allSkills.length === 0) {
+            return 'No skills found. Install superpowers skills to ~/.config/opencode/superpowers/skills/';
+          }
+
+          let output = 'Available skills:\n\n';
+
+          for (const skill of allSkills) {
+            const namespace = skill.sourceType === 'personal' ? '' : 'superpowers:';
+            const skillName = skill.name || path.basename(skill.path);
+
+            output += `${namespace}${skillName}\n`;
+            if (skill.description) {
+              output += `  ${skill.description}\n`;
+            }
+            output += `  Directory: ${skill.path}\n\n`;
+          }
+
+          return output;
+        }
+      }
+```
+
+**步骤 2：验证语法**
+
+运行：`node -c .opencode/plugin/superpowers.js`
+预期：无输出
+
+**步骤 3：提交**
+
+```bash
+git add .opencode/plugin/superpowers.js
+git commit -m "feat: implement find_skills tool for opencode"
+```
+
+***
+
+### 任务 12：实现会话启动钩子
+
+**文件：**
+
+* 修改：`.opencode/plugin/superpowers.js`
+
+**步骤 1：添加 session.started 钩子**
+
+在工具数组之后添加：
+
+```javascript
+    'session.started': async () => {
+      // Read using-superpowers skill content
+      const usingSuperpowersPath = skillsCore.resolveSkillPath(
+        'using-superpowers',
+        superpowersSkillsDir,
+        personalSkillsDir
+      );
+
+      let usingSuperpowersContent = '';
+      if (usingSuperpowersPath) {
+        const fullContent = fs.readFileSync(usingSuperpowersPath.skillFile, 'utf8');
+        // Strip frontmatter
+        const lines = fullContent.split('\n');
+        let inFrontmatter = false;
+        let frontmatterEnded = false;
+        const contentLines = [];
+
+        for (const line of lines) {
+          if (line.trim() === '---') {
+            if (inFrontmatter) {
+              frontmatterEnded = true;
+              continue;
+            }
+            inFrontmatter = true;
+            continue;
+          }
+
+          if (frontmatterEnded || !inFrontmatter) {
+            contentLines.push(line);
+          }
+        }
+
+        usingSuperpowersContent = contentLines.join('\n').trim();
+      }
+
+      // Tool mapping instructions
+      const toolMapping = `
+**Tool Mapping for OpenCode:**
+When skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` → \`update_plan\` (your planning/task tracking tool)
+- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention syntax or automatic dispatch)
+- \`Skill\` tool → \`use_skill\` custom tool (already available)
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Use your native tools
+
+**Skill directories contain supporting files:**
+- Scripts you can run with bash tool
+- Additional documentation you can read
+- Utilities and helpers specific to that skill
+
+**Skills naming:**
+- Superpowers skills: \`superpowers:skill-name\` (from ~/.config/opencode/superpowers/skills/)
+- Personal skills: \`skill-name\` (from ~/.config/opencode/skills/)
+- Personal skills override superpowers skills when names match
+`;
+
+      // Check for updates (non-blocking)
+      const hasUpdates = skillsCore.checkForUpdates(
+        path.join(homeDir, '.config/opencode/superpowers')
+      );
+
+      const updateNotice = hasUpdates ?
+        '\n\n⚠️ **Updates available!** Run `cd ~/.config/opencode/superpowers && git pull` to update superpowers.' :
+        '';
+
+      // Return context to inject into session
+      return {
+        context: `<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'use_skill' tool:**
+
+${usingSuperpowersContent}
+
+${toolMapping}${updateNotice}
+</EXTREMELY_IMPORTANT>`
+      };
+    }
+```
+
+**步骤 2：验证语法**
+
+运行：`node -c .opencode/plugin/superpowers.js`
+预期：无输出
+
+**步骤 3：提交**
+
+```bash
+git add .opencode/plugin/superpowers.js
+git commit -m "feat: implement session.started hook for opencode"
+```
+
+***
+
+## 阶段 4：文档
+
+### 任务 13：创建 OpenCode 安装指南
+
+**文件：**
+
+* 创建：`.opencode/INSTALL.md`
+
+**步骤 1：创建安装指南**
+
+````markdown
+# 为 OpenCode 安装 Superpowers
+
+## 先决条件
+
+- 已安装 [OpenCode.ai](https://opencode.ai)
+- 已安装 Node.js
+- 已安装 Git
+
+## 安装步骤
+
+### 1. 安装 Superpowers 技能
+
+```bash
+# 将 superpowers 技能克隆到 OpenCode 配置目录
+mkdir -p ~/.config/opencode/superpowers
+git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+````
+
+### 2. 安装插件
+
+插件包含在你刚刚克隆的 superpowers 仓库中。
+
+OpenCode 会自动从以下位置发现它：
+
+* `~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
+
+或者，你可以将其链接到项目本地的插件目录：
+
+```bash
+# In your OpenCode project
+mkdir -p .opencode/plugin
+ln -s ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js
+```
+
+### 3. 重启 OpenCode
+
+重启 OpenCode 以加载插件。在下一次会话中，你应该会看到：
+
+```
+你有 superpowers。
+```
+
+## 使用方法
+
+### 查找技能
+
+使用 `find_skills` 工具列出所有可用技能：
+
+```
+使用 find_skills 工具
+```
+
+### 加载技能
+
+使用 `use_skill` 工具加载特定技能：
+
+```
+使用 use_skill 工具，技能名称："superpowers:brainstorming"
+```
+
+### 个人技能
+
+在 `~/.config/opencode/skills/` 中创建你自己的技能：
+
+```bash
+mkdir -p ~/.config/opencode/skills/my-skill
+```
+
+创建 `~/.config/opencode/skills/my-skill/SKILL.md`：
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [what it does]
+---
+
+# 我的技能
+
+[你的技能内容在这里]
+```
+
+个人技能会覆盖同名的 superpowers 技能。
+
+## 更新
+
+```bash
+cd ~/.config/opencode/superpowers
+git pull
+```
+
+## 故障排除
+
+### 插件未加载
+
+1. 检查插件文件是否存在：`ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
+2. 检查 OpenCode 日志以查找错误
+3. 验证 Node.js 是否已安装：`node --version`
+
+### 技能未找到
+
+1. 验证技能目录是否存在：`ls ~/.config/opencode/superpowers/skills`
+2. 使用 `find_skills` 工具查看发现了什么
+3. 检查文件结构：每个技能应有一个 `SKILL.md` 文件
+
+### 工具映射问题
+
+当技能引用了你没有的 Claude Code 工具时：
+
+* `TodoWrite` → 使用 `update_plan`
+* 带有子代理的 `Task` → 使用 `@mention` 语法来调用 OpenCode 子代理
+* `Skill` → 使用 `use_skill` 工具
+* 文件操作 → 使用你的原生工具
+
+## 获取帮助
+
+* 报告问题：https://github.com/obra/superpowers/issues
+* 文档：https://github.com/obra/superpowers
+
+````
+**Step 2: 验证文件已创建**
+
+运行: `ls -l .opencode/INSTALL.md`
+预期: 文件存在
+
+**Step 3: 提交**
+
+```bash
+git add .opencode/INSTALL.md
+git commit -m "docs: add opencode installation guide"
+
+````
+
+***
+
+### 任务 14：更新主 README
+
+**文件：**
+
+* 修改：`README.md`
+
+**步骤 1：添加 OpenCode 部分**
+
+查找关于支持平台的部分（在文件中搜索 "Codex"），并在其后添加：
+
+```markdown
+### OpenCode
+
+Superpowers 通过原生 JavaScript 插件与 [OpenCode.ai](https://opencode.ai) 协同工作。
+
+**安装：** 参见 [.opencode/INSTALL.md](.opencode/INSTALL.md)
+
+**功能特性：**
+- 自定义工具：`use_skill` 和 `find_skills`
+- 自动会话引导
+- 具备影射功能的个人技能
+- 支持文件和脚本访问
+```
+
+**步骤 2：验证格式**
+
+运行：`grep -A 10 "### OpenCode" README.md`
+预期：显示你添加的部分
+
+**步骤 3：提交**
+
+```bash
+git add README.md
+git commit -m "docs: add opencode support to readme"
+```
+
+***
+
+### 任务 15：更新发布说明
+
+**文件：**
+
+* 修改：`RELEASE-NOTES.md`
+
+**步骤 1：为 OpenCode 支持添加条目**
+
+在文件顶部（标题之后），添加：
+
+```markdown
+## [未发布]
+
+### 新增
+
+- **OpenCode 支持**：原生 JavaScript 插件，用于 OpenCode.ai
+  - 自定义工具：`use_skill` 和 `find_skills`
+  - 自动会话引导，附带工具映射说明
+  - 共享核心模块（`lib/skills-core.js`），用于代码复用
+  - 安装指南位于 `.opencode/INSTALL.md`
+
+### 变更
+
+- **重构了 Codex 实现**：现在使用共享的 `lib/skills-core.js` 模块
+  - 消除了 Codex 和 OpenCode 之间的代码重复
+  - 技能发现和解析的单一事实来源
+
+---
+```
+
+**步骤 2：验证格式**
+
+运行：`head -30 RELEASE-NOTES.md`
+预期：显示你的新部分
+
+**步骤 3：提交**
+
+```bash
+git add RELEASE-NOTES.md
+git commit -m "docs: add opencode support to release notes"
+```
+
+***
+
+## 阶段 5：最终验证
+
+### 任务 16：测试 Codex 是否仍然工作
+
+**文件：**
+
+* 测试：`.codex/superpowers-codex`
+
+**步骤 1：测试 find-skills 命令**
+
+运行：`.codex/superpowers-codex find-skills | head -20`
+预期：显示带有名称和描述的技能列表
+
+**步骤 2：测试 use-skill 命令**
+
+运行：`.codex/superpowers-codex use-skill superpowers:brainstorming | head -20`
+预期：显示头脑风暴技能内容
+
+**步骤 3：测试 bootstrap 命令**
+
+运行：`.codex/superpowers-codex bootstrap | head -30`
+预期：显示带有说明的引导内容
+
+**步骤 4：如果所有测试通过，记录成功**
+
+无需提交 - 这只是验证。
+
+***
+
+### 任务 17：验证文件结构
+
+**文件：**
+
+* 检查：所有新文件都存在
+
+**步骤 1：验证所有文件已创建**
+
+运行：
+
+```bash
+ls -l lib/skills-core.js
+ls -l .opencode/plugin/superpowers.js
+ls -l .opencode/INSTALL.md
+```
+
+预期：所有文件都存在
+
+**步骤 2：验证目录结构**
+
+运行：`tree -L 2 .opencode/` (如果 tree 命令不可用，则使用 `find .opencode -type f`)
+预期：
+
+```
+.opencode/
+├── INSTALL.md
+└── plugin/
+    └── superpowers.js
+```
+
+**步骤 3：如果结构正确，则继续**
+
+无需提交 - 这只是验证。
+
+***
+
+### 任务 18：最终提交与总结
+
+**文件：**
+
+* 检查：`git status`
+
+**步骤 1：检查 git 状态**
+
+运行：`git status`
+预期：工作树干净，所有更改已提交
+
+**步骤 2：查看提交日志**
+
+运行：`git log --oneline -20`
+预期：显示此实施过程中的所有提交
+
+**步骤 3：创建总结文档**
+
+创建一个完成总结，显示：
+
+* 总共进行的提交
+* 创建的文件：`lib/skills-core.js`, `.opencode/plugin/superpowers.js`, `.opencode/INSTALL.md`
+* 修改的文件：`.codex/superpowers-codex`, `README.md`, `RELEASE-NOTES.md`
+* 执行的测试：Codex 命令已验证
+* 准备就绪，可用于：使用实际的 OpenCode 安装进行测试
+
+**步骤 4：报告完成**
+
+向用户呈现总结并提供以下选项：
+
+1. 推送到远程仓库
+2. 创建拉取请求
+3. 使用真实的 OpenCode 安装进行测试（需要已安装 OpenCode）
+
+***
+
+## 测试指南（手动 - 需要 OpenCode）
+
+这些步骤需要安装 OpenCode，不属于自动化实施的一部分：
+
+1. **安装技能**：按照 `.opencode/INSTALL.md` 操作
+2. **启动 OpenCode 会话**：验证引导信息出现
+3. **测试 find\_skills**：应列出所有可用技能
+4. **测试 use\_skill**：加载一个技能并验证内容出现
+5. **测试支持文件**：验证技能目录路径可访问
+6. **测试个人技能**：创建一个个人技能并验证它覆盖了核心技能
+7. **测试工具映射**：验证 TodoWrite → update\_plan 映射有效
+
+## 成功标准
+
+* \[ ] `lib/skills-core.js` 已创建，包含所有核心功能
+* \[ ] `.codex/superpowers-codex` 已重构为使用共享核心
+* \[ ] Codex 命令仍然有效（find-skills, use-skill, bootstrap）
+* \[ ] `.opencode/plugin/superpowers.js` 已创建，包含工具和钩子
+* \[ ] 安装指南已创建
+* \[ ] README 和 RELEASE-NOTES 已更新
+* \[ ] 所有更改已提交
+* \[ ] 工作树干净
diff --git a/zh-CN/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md b/zh-CN/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md
new file mode 100644
index 0000000000..41a34a0515
--- /dev/null
+++ b/zh-CN/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md
@@ -0,0 +1,751 @@
+# 基于用户反馈的技能改进
+
+**日期：** 2025-11-28
+**状态：** 草案
+**来源：** 两个 Claude 实例在实际开发场景中使用 superpowers
+
+***
+
+## 执行摘要
+
+两个 Claude 实例提供了来自实际开发会话的详细反馈。他们的反馈揭示了当前技能中存在的**系统性缺陷**，这些缺陷导致可预防的 bug 在遵循技能的情况下仍然被发布。
+
+**关键洞察：** 这些都是问题报告，而不仅仅是解决方案提议。问题是真实存在的；解决方案需要仔细评估。
+
+**关键主题：**
+
+1. **验证缺口** - 我们验证操作成功，但不验证它们是否达到了预期结果
+2. **流程卫生** - 后台进程累积并在子代理之间产生干扰
+3. **上下文优化** - 子代理获取了太多无关信息
+4. **缺少自我反思** - 在移交前没有提示来批判自己的工作
+5. **模拟安全** - 模拟可能偏离接口而无法被检测到
+6. **技能激活** - 技能存在但未被阅读/使用
+
+***
+
+## 已识别的问题
+
+### 问题 1：配置变更验证缺口
+
+**发生了什么：**
+
+* 子代理测试了“OpenAI 集成”
+* 设置了 `OPENAI_API_KEY` 环境变量
+* 收到了状态 200 的响应
+* 报告“OpenAI 集成工作正常”
+* **但是** 响应包含 `"model": "claude-sonnet-4-20250514"` - 实际上使用的是 Anthropic
+
+**根本原因：**
+`verification-before-completion` 检查操作是否成功，但不检查结果是否反映了预期的配置变更。
+
+**影响：** 高 - 对集成测试产生虚假信心，bug 发布到生产环境
+
+**示例失败模式：**
+
+* 切换 LLM 提供商 → 验证状态 200 但不检查模型名称
+* 启用功能标志 → 验证无错误但不检查功能是否激活
+* 更改环境 → 验证部署成功但不检查环境变量
+
+***
+
+### 问题 2：后台进程累积
+
+**发生了什么：**
+
+* 会话期间分派了多个子代理
+* 每个子代理都启动了后台服务器进程
+* 进程累积（4 个以上服务器在运行）
+* 过时的进程仍然绑定到端口
+* 后来的端到端测试命中了配置错误的陈旧服务器
+* 导致混淆/不正确的测试结果
+
+**根本原因：**
+子代理是无状态的 - 不知道先前子代理的进程。没有清理协议。
+
+**影响：** 中-高 - 测试命中错误的服务器，虚假通过/失败，调试混淆
+
+***
+
+### 问题 3：子代理提示中的上下文膨胀
+
+**发生了什么：**
+
+* 标准方法：给子代理完整的计划文件阅读
+* 实验：只给任务 + 模式 + 文件 + 验证命令
+* 结果：更快、更专注、单次尝试完成更常见
+
+**根本原因：**
+子代理在无关的计划部分浪费了令牌和注意力。
+
+**影响：** 中 - 执行速度慢，更多失败尝试
+
+**有效的方法：**
+
+```
+你正在为 packnplay 的测试套件添加一个端到端测试。
+
+**你的任务：** 在 `pkg/runner/e2e_test.go` 中添加 `TestE2E_FeaturePrivilegedMode`
+
+**测试内容：** 一个在其元数据中请求了 `"privileged": true` 的本地 devcontainer 功能，应该导致容器以 `--privileged` 标志运行。
+
+**请严格按照 TestE2E_FeatureOptionValidation 的模式编写**（位于文件末尾）
+
+**编写完成后，运行：** `go test -v ./pkg/runner -run TestE2E_FeaturePrivilegedMode -timeout 5m`
+```
+
+***
+
+### 问题 4：移交前无自我反思
+
+**发生了什么：**
+
+* 添加了自我反思提示：“用新的眼光审视你的工作 - 哪些地方可以做得更好？”
+* 任务 5 的实施者识别出测试失败是由于实现 bug，而不是测试 bug
+* 追溯到第 99 行：`strings.Join(metadata.Entrypoint, " ")` 创建了无效的 Docker 语法
+* 如果没有自我反思，只会报告“测试失败”而不说明根本原因
+
+**根本原因：**
+实施者在报告完成前，不会自然地退一步批判自己的工作。
+
+**影响：** 中 - 实施者本可以发现的 bug 被移交给审查者
+
+***
+
+### 问题 5：模拟-接口漂移
+
+**发生了什么：**
+
+```typescript
+// Interface defines close()
+interface PlatformAdapter {
+  close(): Promise<void>;
+}
+
+// Code (BUGGY) calls cleanup()
+await adapter.cleanup();
+
+// Mock (MATCHES BUG) defines cleanup()
+vi.mock('web-adapter', () => ({
+  WebAdapter: vi.fn().mockImplementation(() => ({
+    cleanup: vi.fn().mockResolvedValue(undefined),  // Wrong!
+  })),
+}));
+```
+
+* 测试通过
+* 运行时崩溃：“adapter.cleanup is not a function”
+
+**根本原因：**
+模拟源自错误代码调用的内容，而非接口定义。TypeScript 无法捕获方法名错误的行内模拟。
+
+**影响：** 高 - 测试给出虚假信心，运行时崩溃
+
+**为什么测试反模式没有防止这种情况：**
+该技能涵盖了测试模拟行为和在不理解的情况下进行模拟，但没有涵盖“从接口而非实现派生模拟”的具体模式。
+
+***
+
+### 问题 6：代码审查者文件访问
+
+**发生了什么：**
+
+* 分派了代码审查子代理
+* 找不到测试文件：“该文件似乎不存在于仓库中”
+* 文件实际存在
+* 审查者不知道需要先显式读取它
+
+**根本原因：**
+审查者提示不包括显式的文件读取指令。
+
+**影响：** 低-中 - 审查失败或不完整
+
+***
+
+### 问题 7：修复工作流延迟
+
+**发生了什么：**
+
+* 实施者在自我反思期间识别出 bug
+* 实施者知道如何修复
+* 当前工作流：报告 → 我分派修复者 → 修复者修复 → 我验证
+* 额外的往返增加了延迟，但没有增加价值
+
+**根本原因：**
+当实施者已经诊断出问题时，实施者和修复者角色之间仍存在严格的分离。
+
+**影响：** 低 - 延迟，但无正确性问题
+
+***
+
+### 问题 8：技能未被阅读
+
+**发生了什么：**
+
+* `testing-anti-patterns` 技能存在
+* 无论是人类还是子代理在编写测试前都没有阅读它
+* 本可以防止一些问题（虽然不是全部 - 参见问题 5）
+
+**根本原因：**
+没有强制要求子代理阅读相关技能。没有提示包含技能阅读。
+
+**影响：** 中 - 如果不使用，技能投资就被浪费了
+
+***
+
+## 提议的改进
+
+### 1. verification-before-completion: 添加配置变更验证
+
+**添加新部分：**
+
+```markdown
+## 验证配置变更
+
+测试配置、提供商、功能开关或环境变更时：
+
+**不要仅验证操作成功。要验证输出反映了预期的变更。**
+
+### 常见失败模式
+
+操作成功是因为存在*某些*有效配置，但并非你打算测试的配置。
+
+### 示例
+
+| 变更 | 不充分的验证 | 必需的验证 |
+|--------|-------------|----------|
+| 切换LLM提供商 | 状态码200 | 响应包含预期的模型名称 |
+| 启用功能开关 | 无错误 | 功能行为实际已激活 |
+| 更改环境 | 部署成功 | 日志/变量引用新环境 |
+| 设置凭据 | 身份验证成功 | 已验证的用户/上下文正确 |
+
+### 门控函数
+```
+
+在声称配置变更有效之前：
+
+1. 识别：此变更后，什么应该**不同**？
+2. 定位：这种差异在哪里可以观察到？
+   * 响应字段（模型名称，用户 ID）
+   * 日志行（环境，提供商）
+   * 行为（功能激活/未激活）
+3. 运行：显示可观察差异的命令
+4. 验证：输出包含预期的差异
+5. 只有**在那之后**：声称配置变更有效
+
+危险信号：
+
+* “请求成功”但不检查内容
+  * 检查状态码但不检查响应体
+  * 验证无错误但不进行积极确认
+
+````
+**Why this works:**
+Forces verification of INTENT, not just operation success.
+
+---
+
+### 2. subagent-driven-development: Add Process Hygiene for E2E Tests
+
+**Add new section:**
+
+```markdown
+## Process Hygiene for E2E Tests
+
+When dispatching subagents that start services (servers, databases, message queues):
+
+### Problem
+
+Subagents are stateless - they don't know about processes started by previous subagents. Background processes persist and can interfere with later tests.
+
+### Solution
+
+**Before dispatching E2E test subagent, include cleanup in prompt:**
+
+````
+
+在启动任何服务之前：
+
+1. 终止现有进程：pkill -f "<service-pattern>" 2>/dev/null || true
+2. 等待清理：sleep 1
+3. 验证端口空闲：lsof -i :<port> && echo "ERROR: Port still in use" || echo "Port free"
+
+测试完成后：
+
+1. 终止你启动的进程
+2. 验证清理：pgrep -f "<service-pattern>" || echo "Cleanup successful"
+
+```
+### 示例
+```
+
+任务：运行 API 服务器的端到端测试
+
+提示包括：
+“在启动服务器之前：
+
+* 终止任何现有服务器：pkill -f 'node.\*server.js' 2>/dev/null || true
+* 验证端口 3001 空闲：lsof -i :3001 && exit 1 || echo 'Port available'
+
+测试之后：
+
+* 终止你启动的服务器
+* 验证：pgrep -f 'node.\*server.js' || echo 'Cleanup verified'”
+
+```
+### 为何这很重要
+
+- 过时的进程会使用错误的配置处理请求
+- 端口冲突导致静默失败
+- 进程累积拖慢系统
+- 造成混淆的测试结果（访问到错误的服务器）
+```
+
+**权衡分析：**
+
+* 给提示增加了样板代码
+* 但防止了非常令人困惑的调试
+* 对于端到端测试子代理来说是值得的
+
+***
+
+### 3. subagent-driven-development: 添加精简上下文选项
+
+**修改步骤 2：使用子代理执行任务**
+
+**之前：**
+
+```
+仔细阅读 [plan-file] 中的任务。
+```
+
+**之后：**
+
+```
+## 上下文处理方式
+
+**完整计划（默认）：**
+适用于任务复杂或存在依赖关系时：
+```
+
+仔细阅读 \[plan-file] 中的任务 N。
+
+```
+**Lean Context（适用于独立任务）：**
+当任务独立且基于模式时使用：
+```
+
+你正在实现：\[1-2 句任务描述]
+
+要修改的文件：\[确切路径]
+要遵循的模式：\[对现有函数/测试的引用]
+要实现的内容：\[具体要求]
+验证：\[要运行的精确命令]
+
+\[请勿包含完整的计划文件]
+
+```
+**在以下情况下使用精简上下文：**
+- 任务遵循现有模式（添加类似测试，实现类似功能）
+- 任务是自包含的（不需要其他任务的上下文）
+- 模式参考已足够（例如，"遵循 TestE2E_FeatureOptionValidation"）
+
+**在以下情况下使用完整计划：**
+- 任务依赖于其他任务
+- 需要理解整体架构
+- 需要上下文才能理解的复杂逻辑
+```
+
+**示例：**
+
+```
+Lean 上下文提示：
+
+"你正在为 devcontainer 功能添加特权模式测试。
+
+文件：pkg/runner/e2e_test.go
+模式：遵循 TestE2E_FeatureOptionValidation（在文件末尾）
+测试：元数据中带有 `"privileged": true` 的功能应产生 `--privileged` 标志
+验证：go test -v ./pkg/runner -run TestE2E_FeaturePrivilegedMode -timeout 5m
+
+报告：实现情况、测试结果、任何问题。"
+```
+
+**为什么这有效：**
+减少令牌使用，提高专注度，在适当时更快完成。
+
+***
+
+### 4. subagent-driven-development: 添加自我反思步骤
+
+**修改步骤 2：使用子代理执行任务**
+
+**添加到提示模板：**
+
+```
+当完成后，在汇报之前：
+
+退一步，用全新的视角审视你的工作。
+
+问自己：
+- 这真的解决了指定的任务吗？
+- 有没有我没有考虑到的边缘情况？
+- 我是否正确遵循了模式？
+- 如果测试失败，根本原因是什么（实现错误还是测试错误）？
+- 这个实现还有哪些可以改进的地方？
+
+如果在这次反思中发现了问题，现在就去修复它们。
+
+然后汇报：
+- 你实现了什么
+- 自我反思的发现（如果有的话）
+- 测试结果
+- 更改的文件
+```
+
+**为什么这有效：**
+在移交前捕获实施者自己能发现的 bug。有记录的案例：通过自我反思识别了入口点 bug。
+
+**权衡：**
+每个任务增加约 30 秒，但在审查前捕获问题。
+
+***
+
+### 5. requesting-code-review: 添加显式文件读取
+
+**修改代码审查者模板：**
+
+**在开头添加：**
+
+```markdown
+## 待审阅文件
+
+开始分析前，请先阅读以下文件：
+
+1. [列出差异中涉及的具体文件]
+2. [被变更引用但未修改的文件]
+
+使用 Read 工具加载每个文件。
+
+如果找不到文件：
+- 检查差异中提供的准确路径
+- 尝试其他可能的位置
+- 报告："无法定位 [路径] - 请确认文件是否存在"
+
+在未实际阅读代码前，请勿继续审阅。
+```
+
+**为什么这有效：**
+明确的指令防止“找不到文件”的问题。
+
+***
+
+### 6. testing-anti-patterns: 添加模拟-接口漂移反模式
+
+**添加新的反模式 6：**
+
+````markdown
+## 反模式 6：从实现细节派生的模拟
+
+**违规情况：**
+```typescript
+// 代码（有缺陷）调用了 cleanup()
+await adapter.cleanup();
+
+// 模拟（匹配缺陷）包含了 cleanup()
+const mock = {
+  cleanup: vi.fn().mockResolvedValue(undefined)
+};
+
+// 接口（正确）定义的是 close()
+interface PlatformAdapter {
+  close(): Promise<void>;
+}
+````
+
+**为什么这是错误的：**
+
+* 模拟将 bug 编码到测试中
+* TypeScript 无法捕获方法名错误的行内模拟
+* 测试通过是因为代码和模拟都是错误的
+* 使用真实对象时运行时崩溃
+
+**修复方法：**
+
+```typescript
+// ✅ GOOD: Derive mock from interface
+
+// Step 1: Open interface definition (PlatformAdapter)
+// Step 2: List methods defined there (close, initialize, etc.)
+// Step 3: Mock EXACTLY those methods
+
+const mock = {
+  initialize: vi.fn().mockResolvedValue(undefined),
+  close: vi.fn().mockResolvedValue(undefined),  // From interface!
+};
+
+// Now test FAILS because code calls cleanup() which doesn't exist
+// That failure reveals the bug BEFORE runtime
+```
+
+### 门控函数
+
+```
+在编写任何模拟之前：
+
+  1. 停止 - 请勿查看待测代码
+  2. 查找：依赖项的接口/类型定义
+  3. 阅读：接口文件
+  4. 列出：接口中定义的方法
+  5. 模拟：仅模拟那些方法，并使用完全相同的名称
+  6. 不要：查看你的代码调用了什么
+
+  如果你的测试因代码调用了模拟中不存在的内容而失败：
+    ✅ 很好 - 测试发现了你代码中的一个错误
+    修复代码以调用正确的接口方法
+    而不是修改模拟
+
+  危险信号：
+    - "我会模拟代码调用的内容"
+    - 从实现中复制方法名称
+    - 未阅读接口就编写模拟
+    - "测试失败了，所以我会在模拟中添加这个方法"
+```
+
+**检测：**
+
+当你看到运行时错误“X 不是一个函数”而测试通过时：
+
+1. 检查 X 是否被模拟
+2. 比较模拟方法与接口方法
+3. 寻找方法名不匹配
+
+````
+**Why this works:**
+直接针对反馈中的失败模式进行解决。
+
+---
+
+### 7. subagent-driven-development: 要求测试子代理具备技能阅读能力
+
+**当任务涉及测试时，添加到提示模板中：**
+
+```markdown
+BEFORE writing any tests:
+
+1. Read testing-anti-patterns skill:
+   Use Skill tool: superpowers:testing-anti-patterns
+
+2. Apply gate functions from that skill when:
+   - Writing mocks
+   - Adding methods to production classes
+   - Mocking dependencies
+
+This is NOT optional. Tests that violate anti-patterns will be rejected in review.
+
+````
+
+**为什么这有效：**
+确保技能实际被使用，而不仅仅是存在。
+
+**权衡：**
+每个任务增加时间，但防止了整类 bug。
+
+***
+
+### 8. subagent-driven-development: 允许实施者修复自我识别的问题
+
+**修改步骤 2：**
+
+**当前：**
+
+```
+Subagent 报告工作摘要。
+```
+
+**提议：**
+
+```
+Subagent 进行自我反思，然后：
+
+IF 自我反思识别出可修复的问题：
+  1. 修复问题
+  2. 重新运行验证
+  3. 报告："初始实现 + 自我反思修复"
+
+ELSE：
+  报告："实施完成"
+
+报告中包含：
+- 自我反思的发现
+- 是否应用了修复
+- 最终的验证结果
+```
+
+**为什么这有效：**
+当实施者已经知道修复方法时，减少延迟。有记录的案例：本可以为入口点 bug 节省一次往返。
+
+**权衡：**
+提示稍微复杂一些，但端到端速度更快。
+
+***
+
+## 实施计划
+
+### 第一阶段：高影响，低风险（优先实施）
+
+1. **verification-before-completion: 配置变更验证**
+   * 清晰的补充，不改变现有内容
+   * 解决高影响问题（测试中的虚假信心）
+   * 文件：`skills/verification-before-completion/SKILL.md`
+
+2. **testing-anti-patterns: 模拟-接口漂移**
+   * 添加新反模式，不修改现有内容
+   * 解决高影响问题（运行时崩溃）
+   * 文件：`skills/testing-anti-patterns/SKILL.md`
+
+3. **requesting-code-review: 显式文件读取**
+   * 对模板的简单补充
+   * 解决具体问题（审查者找不到文件）
+   * 文件：`skills/requesting-code-review/SKILL.md`
+
+### 第二阶段：中等变更（仔细测试）
+
+4. **subagent-driven-development: 流程卫生**
+   * 添加新部分，不改变工作流
+   * 解决中-高影响问题（测试可靠性）
+   * 文件：`skills/subagent-driven-development/SKILL.md`
+
+5. **subagent-driven-development: 自我反思**
+   * 更改提示模板（风险较高）
+   * 但有记录表明能捕获 bug
+   * 文件：`skills/subagent-driven-development/SKILL.md`
+
+6. **subagent-driven-development: 技能阅读要求**
+   * 增加提示开销
+   * 但确保技能实际被使用
+   * 文件：`skills/subagent-driven-development/SKILL.md`
+
+### 第三阶段：优化（先验证）
+
+7. **subagent-driven-development: 精简上下文选项**
+   * 增加复杂性（两种方法）
+   * 需要验证它不会引起混淆
+   * 文件：`skills/subagent-driven-development/SKILL.md`
+
+8. **subagent-driven-development: 允许实施者修复**
+   * 更改工作流（风险较高）
+   * 优化，而非 bug 修复
+   * 文件：`skills/subagent-driven-development/SKILL.md`
+
+***
+
+## 开放性问题
+
+1. **精简上下文方法：**
+   * 对于基于模式的任务，我们应该将其设为默认吗？
+   * 我们如何决定使用哪种方法？
+   * 过于精简而遗漏重要上下文的风险？
+
+2. **自我反思：**
+   * 这会显著减慢简单任务的速度吗？
+   * 是否只应应用于复杂任务？
+   * 如何防止其变得机械而导致的“反思疲劳”？
+
+3. **流程卫生：**
+   * 这应该放在 subagent-driven-development 中，还是一个单独的技能里？
+   * 它是否适用于端到端测试之外的其他工作流？
+   * 如何处理进程**应该**持续存在的情况（开发服务器）？
+
+4. **技能阅读强制要求：**
+   * 我们应该要求**所有**子代理阅读相关技能吗？
+   * 如何防止提示变得过长？
+   * 过度文档化而失去焦点的风险？
+
+***
+
+## 成功指标
+
+我们如何知道这些改进有效？
+
+1. **配置验证：**
+   * “测试通过但使用了错误配置”的实例为零
+   * Jesse 不会说“那实际上并没有测试你认为它在测试的东西”
+
+2. **流程卫生：**
+   * “测试命中错误服务器”的实例为零
+   * 端到端测试运行期间无端口冲突错误
+
+3. **模拟接口漂移：**
+   * 零出现“测试通过但运行时因缺少方法而崩溃”的情况
+   * 模拟对象与接口之间不存在方法名不匹配
+
+4. **自我反思：**
+   * 可衡量性：执行者报告是否包含自我反思的发现？
+   * 定性分析：进入代码审查阶段的缺陷是否减少？
+
+5. **技能解读：**
+   * 子代理报告引用技能门控函数
+   * 代码审查中反模式违规情况减少
+
+***
+
+## 风险与应对措施
+
+### 风险：提示膨胀
+
+**问题：** 添加所有这些要求会使提示变得过于冗长
+**应对措施：**
+
+* 分阶段实施（不要一次性添加所有内容）
+* 使部分附加要求成为条件性（端到端卫生仅适用于端到端测试）
+* 考虑为不同任务类型设置模板
+
+### 风险：分析瘫痪
+
+**问题：** 过多的反思/验证会拖慢执行速度
+**应对措施：**
+
+* 保持门控函数快速执行（秒级，而非分钟级）
+* 初始阶段将精简上下文设为可选功能
+* 监控任务完成时间
+
+### 风险：虚假安全感
+
+**问题：** 遵循检查清单并不能保证正确性
+**应对措施：**
+
+* 强调门控函数是最低要求，而非最高标准
+* 在技能描述中保留“运用判断力”的表述
+* 说明技能旨在发现常见错误，而非所有错误
+
+### 风险：技能分歧
+
+**问题：** 不同技能给出相互矛盾的建议
+**应对措施：**
+
+* 审查所有技能的变更以确保一致性
+* 记录技能间的协作方式（集成章节）
+* 部署前通过真实场景进行测试
+
+***
+
+## 实施建议
+
+**立即启动第一阶段：**
+
+* 完成前验证：配置变更验证
+* 测试反模式：模拟接口漂移检测
+* 发起代码审查：显式文件读取要求
+
+**与Jesse共同测试第二阶段后再定稿：**
+
+* 获取关于自我反思影响的反馈
+* 验证流程卫生方法的有效性
+* 确认技能解读要求值得其额外开销
+
+**暂缓实施第三阶段以待验证：**
+
+* 精简上下文需经实际场景测试
+* 执行者修复工作流变更需谨慎评估
+
+这些改进措施针对用户记录的实际问题，同时最大限度降低了技能质量下降的风险。
diff --git a/zh-CN/docs/plans/2026-01-17-visual-brainstorming.md b/zh-CN/docs/plans/2026-01-17-visual-brainstorming.md
new file mode 100644
index 0000000000..fe74222b64
--- /dev/null
+++ b/zh-CN/docs/plans/2026-01-17-visual-brainstorming.md
@@ -0,0 +1,579 @@
+# 视觉化头脑风暴伴侣实施计划
+
+> **对于智能体工作者：** 必需子技能：使用 superpowers:executing-plans 来按任务实施此计划。
+
+**目标：** 为 Claude 提供一个基于浏览器的视觉伴侣，用于头脑风暴会议——在终端对话旁展示线框图、原型和交互式选择。
+
+**架构：** Claude 将 HTML 写入一个临时文件。一个本地 Node.js 服务器监视该文件，并通过一个自动注入的辅助库来提供该文件。用户交互通过 WebSocket 流到服务器的标准输出，Claude 可以在后台任务输出中看到这些交互。
+
+**技术栈：** Node.js, Express, ws (WebSocket), chokidar (文件监视)
+
+***
+
+## 任务 1：创建服务器基础
+
+**文件：**
+
+* 创建：`lib/brainstorm-server/index.js`
+* 创建：`lib/brainstorm-server/package.json`
+
+**步骤 1：创建 package.json**
+
+```json
+{
+  "name": "brainstorm-server",
+  "version": "1.0.0",
+  "description": "Visual brainstorming companion server for Claude Code",
+  "main": "index.js",
+  "dependencies": {
+    "chokidar": "^3.5.3",
+    "express": "^4.18.2",
+    "ws": "^8.14.2"
+  }
+}
+```
+
+**步骤 2：创建可启动的最小服务器**
+
+```javascript
+const express = require('express');
+const http = require('http');
+const WebSocket = require('ws');
+const chokidar = require('chokidar');
+const fs = require('fs');
+const path = require('path');
+
+const PORT = process.env.BRAINSTORM_PORT || 3333;
+const SCREEN_FILE = process.env.BRAINSTORM_SCREEN || '/tmp/brainstorm/screen.html';
+const SCREEN_DIR = path.dirname(SCREEN_FILE);
+
+// Ensure screen directory exists
+if (!fs.existsSync(SCREEN_DIR)) {
+  fs.mkdirSync(SCREEN_DIR, { recursive: true });
+}
+
+// Create default screen if none exists
+if (!fs.existsSync(SCREEN_FILE)) {
+  fs.writeFileSync(SCREEN_FILE, `<!DOCTYPE html>
+<html>
+<head>
+  <title>Brainstorm Companion</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+    h1 { color: #333; }
+    p { color: #666; }
+  </style>
+</head>
+<body>
+  <h1>Brainstorm Companion</h1>
+  <p>Waiting for Claude to push a screen...</p>
+</body>
+</html>`);
+}
+
+const app = express();
+const server = http.createServer(app);
+const wss = new WebSocket.Server({ server });
+
+// Track connected browsers for reload notifications
+const clients = new Set();
+
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  ws.on('close', () => clients.delete(ws));
+
+  ws.on('message', (data) => {
+    // User interaction event - write to stdout for Claude
+    const event = JSON.parse(data.toString());
+    console.log(JSON.stringify({ type: 'user-event', ...event }));
+  });
+});
+
+// Serve current screen with helper.js injected
+app.get('/', (req, res) => {
+  let html = fs.readFileSync(SCREEN_FILE, 'utf-8');
+
+  // Inject helper script before </body>
+  const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+  const injection = `<script>\n${helperScript}\n</script>`;
+
+  if (html.includes('</body>')) {
+    html = html.replace('</body>', `${injection}\n</body>`);
+  } else {
+    html += injection;
+  }
+
+  res.type('html').send(html);
+});
+
+// Watch for screen file changes
+chokidar.watch(SCREEN_FILE).on('change', () => {
+  console.log(JSON.stringify({ type: 'screen-updated', file: SCREEN_FILE }));
+  // Notify all browsers to reload
+  clients.forEach(ws => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'reload' }));
+    }
+  });
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(JSON.stringify({ type: 'server-started', port: PORT, url: `http://localhost:${PORT}` }));
+});
+```
+
+**步骤 3：运行 npm install**
+
+运行：`cd lib/brainstorm-server && npm install`
+预期：依赖项已安装
+
+**步骤 4：测试服务器启动**
+
+运行：`cd lib/brainstorm-server && timeout 3 node index.js || true`
+预期：看到包含 `server-started` 和端口信息的 JSON
+
+**步骤 5：提交**
+
+```bash
+git add lib/brainstorm-server/
+git commit -m "feat: add brainstorm server foundation"
+```
+
+***
+
+## 任务 2：创建辅助库
+
+**文件：**
+
+* 创建：`lib/brainstorm-server/helper.js`
+
+**步骤 1：创建带有事件自动捕获功能的 helper.js**
+
+```javascript
+(function() {
+  const WS_URL = 'ws://' + window.location.host;
+  let ws = null;
+  let eventQueue = [];
+
+  function connect() {
+    ws = new WebSocket(WS_URL);
+
+    ws.onopen = () => {
+      // Send any queued events
+      eventQueue.forEach(e => ws.send(JSON.stringify(e)));
+      eventQueue = [];
+    };
+
+    ws.onmessage = (msg) => {
+      const data = JSON.parse(msg.data);
+      if (data.type === 'reload') {
+        window.location.reload();
+      }
+    };
+
+    ws.onclose = () => {
+      // Reconnect after 1 second
+      setTimeout(connect, 1000);
+    };
+  }
+
+  function send(event) {
+    event.timestamp = Date.now();
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(event));
+    } else {
+      eventQueue.push(event);
+    }
+  }
+
+  // Auto-capture clicks on interactive elements
+  document.addEventListener('click', (e) => {
+    const target = e.target.closest('button, a, [data-choice], [role="button"], input[type="submit"]');
+    if (!target) return;
+
+    // Don't capture regular link navigation
+    if (target.tagName === 'A' && !target.dataset.choice) return;
+
+    e.preventDefault();
+
+    send({
+      type: 'click',
+      text: target.textContent.trim(),
+      choice: target.dataset.choice || null,
+      id: target.id || null,
+      className: target.className || null
+    });
+  });
+
+  // Auto-capture form submissions
+  document.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const form = e.target;
+    const formData = new FormData(form);
+    const data = {};
+    formData.forEach((value, key) => { data[key] = value; });
+
+    send({
+      type: 'submit',
+      formId: form.id || null,
+      formName: form.name || null,
+      data: data
+    });
+  });
+
+  // Auto-capture input changes (debounced)
+  let inputTimeout = null;
+  document.addEventListener('input', (e) => {
+    const target = e.target;
+    if (!target.matches('input, textarea, select')) return;
+
+    clearTimeout(inputTimeout);
+    inputTimeout = setTimeout(() => {
+      send({
+        type: 'input',
+        name: target.name || null,
+        id: target.id || null,
+        value: target.value,
+        inputType: target.type || target.tagName.toLowerCase()
+      });
+    }, 500); // 500ms debounce
+  });
+
+  // Expose for explicit use if needed
+  window.brainstorm = {
+    send: send,
+    choice: (value, metadata = {}) => send({ type: 'choice', value, ...metadata })
+  };
+
+  connect();
+})();
+```
+
+**步骤 2：验证 helper.js 语法有效**
+
+运行：`node -c lib/brainstorm-server/helper.js`
+预期：无语法错误
+
+**步骤 3：提交**
+
+```bash
+git add lib/brainstorm-server/helper.js
+git commit -m "feat: add browser helper library for event capture"
+```
+
+***
+
+## 任务 3：为服务器编写测试
+
+**文件：**
+
+* 创建：`tests/brainstorm-server/server.test.js`
+* 创建：`tests/brainstorm-server/package.json`
+
+**步骤 1：创建测试 package.json**
+
+```json
+{
+  "name": "brainstorm-server-tests",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "node server.test.js"
+  }
+}
+```
+
+**步骤 2：编写服务器测试**
+
+```javascript
+const { spawn } = require('child_process');
+const http = require('http');
+const WebSocket = require('ws');
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+const SERVER_PATH = path.join(__dirname, '../../lib/brainstorm-server/index.js');
+const TEST_PORT = 3334;
+const TEST_SCREEN = '/tmp/brainstorm-test/screen.html';
+
+// Clean up test directory
+function cleanup() {
+  if (fs.existsSync(path.dirname(TEST_SCREEN))) {
+    fs.rmSync(path.dirname(TEST_SCREEN), { recursive: true });
+  }
+}
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function fetch(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    }).on('error', reject);
+  });
+}
+
+async function runTests() {
+  cleanup();
+
+  // Start server
+  const server = spawn('node', [SERVER_PATH], {
+    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_SCREEN: TEST_SCREEN }
+  });
+
+  let stdout = '';
+  server.stdout.on('data', (data) => { stdout += data.toString(); });
+  server.stderr.on('data', (data) => { console.error('Server stderr:', data.toString()); });
+
+  await sleep(1000); // Wait for server to start
+
+  try {
+    // Test 1: Server starts and outputs JSON
+    console.log('Test 1: Server startup message');
+    assert(stdout.includes('server-started'), 'Should output server-started');
+    assert(stdout.includes(TEST_PORT.toString()), 'Should include port');
+    console.log('  PASS');
+
+    // Test 2: GET / returns HTML with helper injected
+    console.log('Test 2: Serves HTML with helper injected');
+    const res = await fetch(`http://localhost:${TEST_PORT}/`);
+    assert.strictEqual(res.status, 200);
+    assert(res.body.includes('brainstorm'), 'Should include brainstorm content');
+    assert(res.body.includes('WebSocket'), 'Should have helper.js injected');
+    console.log('  PASS');
+
+    // Test 3: WebSocket connection and event relay
+    console.log('Test 3: WebSocket relays events to stdout');
+    stdout = ''; // Reset stdout capture
+    const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws.on('open', resolve));
+
+    ws.send(JSON.stringify({ type: 'click', text: 'Test Button' }));
+    await sleep(100);
+
+    assert(stdout.includes('user-event'), 'Should relay user events');
+    assert(stdout.includes('Test Button'), 'Should include event data');
+    ws.close();
+    console.log('  PASS');
+
+    // Test 4: File change triggers reload notification
+    console.log('Test 4: File change notifies browsers');
+    const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws2.on('open', resolve));
+
+    let gotReload = false;
+    ws2.on('message', (data) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.type === 'reload') gotReload = true;
+    });
+
+    // Modify the screen file
+    fs.writeFileSync(TEST_SCREEN, '<html><body>Updated</body></html>');
+    await sleep(500);
+
+    assert(gotReload, 'Should send reload message on file change');
+    ws2.close();
+    console.log('  PASS');
+
+    console.log('\nAll tests passed!');
+
+  } finally {
+    server.kill();
+    cleanup();
+  }
+}
+
+runTests().catch(err => {
+  console.error('Test failed:', err);
+  process.exit(1);
+});
+```
+
+**步骤 3：运行测试**
+
+运行：`cd tests/brainstorm-server && npm install ws && node server.test.js`
+预期：所有测试通过
+
+**步骤 4：提交**
+
+```bash
+git add tests/brainstorm-server/
+git commit -m "test: add brainstorm server integration tests"
+```
+
+***
+
+## 任务 4：将视觉伴侣添加到头脑风暴技能
+
+**文件：**
+
+* 修改：`skills/brainstorming/SKILL.md`
+* 创建：`skills/brainstorming/visual-companion.md` (支持文档)
+
+**步骤 1：创建支持文档**
+
+创建 `skills/brainstorming/visual-companion.md`：
+
+````markdown
+# Visual Companion 参考
+
+## 启动服务器
+
+以后台任务运行：
+
+```bash
+node ${PLUGIN_ROOT}/lib/brainstorm-server/index.js
+````
+
+告诉用户："我已经在 http://localhost:3333 启动了一个视觉伴侣——请在浏览器中打开它。"
+
+## 推送屏幕
+
+将 HTML 写入 `/tmp/brainstorm/screen.html`。服务器监视此文件并自动刷新浏览器。
+
+## 读取用户响应
+
+在后台任务输出中检查 JSON 事件：
+
+```json
+{"type":"user-event","type":"click","text":"Option A","choice":"optionA","timestamp":1234567890}
+{"type":"user-event","type":"submit","data":{"notes":"My feedback"},"timestamp":1234567891}
+```
+
+事件类型：
+
+* **click：** 用户点击了按钮或 `data-choice` 元素
+* **submit：** 用户提交了表单（包含所有表单数据）
+* **input：** 用户在字段中输入了内容（防抖 500 毫秒）
+
+## HTML 模式
+
+### 选择卡片
+
+```html
+<div class="options">
+  <button data-choice="optionA">
+    <h3>Option A</h3>
+    <p>Description</p>
+  </button>
+  <button data-choice="optionB">
+    <h3>Option B</h3>
+    <p>Description</p>
+  </button>
+</div>
+```
+
+### 交互式线框图
+
+```html
+<div class="mockup">
+  <header data-choice="header">App Header</header>
+  <nav data-choice="nav">Navigation</nav>
+  <main data-choice="main">Content</main>
+</div>
+```
+
+### 带备注的表单
+
+```html
+<form>
+  <label>Priority: <input type="range" name="priority" min="1" max="5"></label>
+  <textarea name="notes" placeholder="Additional thoughts..."></textarea>
+  <button type="submit">Submit</button>
+</form>
+```
+
+### 显式 JavaScript
+
+```html
+<button onclick="brainstorm.choice('custom', {extra: 'data'})">Custom</button>
+```
+
+````
+**第二步：为头脑风暴技能添加视觉伴侣部分**
+
+在 `skills/brainstorming/SKILL.md` 中的"核心原则"后添加：
+
+```markdown
+
+## 视觉伴侣（可选）
+
+当头脑风暴涉及视觉元素——UI 原型、线框图、交互式原型——时，使用基于浏览器的视觉伴侣。
+
+**何时使用：**
+- 展示受益于视觉比较的 UI/UX 方案
+- 展示线框图或布局选项
+- 收集结构化反馈（评分、表单）
+- 原型点击交互
+
+**工作原理：**
+1. 将服务器作为后台作业启动
+2. 告知用户打开 http://localhost:3333
+3. 将 HTML 写入 `/tmp/brainstorm/screen.html`（自动刷新）
+4. 检查后台任务输出以获取用户交互
+
+终端仍是主要的对话界面。浏览器是一个视觉辅助工具。
+
+**参考：** 查看此技能目录中的 `visual-companion.md` 以获取 HTML 模式和 API 详情。
+````
+
+**步骤 3：验证编辑**
+
+运行：`grep -A5 "Visual Companion" skills/brainstorming/SKILL.md`
+预期：显示新章节
+
+**步骤 4：提交**
+
+```bash
+git add skills/brainstorming/
+git commit -m "feat: add visual companion to brainstorming skill"
+```
+
+***
+
+## 任务 5：将服务器添加到插件忽略列表（可选清理）
+
+**文件：**
+
+* 检查 `.gitignore` 是否需要为 lib/brainstorm-server 排除 node\_modules
+
+**步骤 1：检查当前的 gitignore**
+
+运行：`cat .gitignore 2>/dev/null || echo "No .gitignore"`
+
+**步骤 2：如果需要，添加 node\_modules**
+
+如果尚未存在，添加：
+
+```
+lib/brainstorm-server/node_modules/
+```
+
+**步骤 3：如果更改则提交**
+
+```bash
+git add .gitignore
+git commit -m "chore: ignore brainstorm-server node_modules"
+```
+
+***
+
+## 总结
+
+完成所有任务后：
+
+1. **服务器**位于 `lib/brainstorm-server/` —— 监视 HTML 文件并中继事件的 Node.js 服务器
+2. **辅助库**自动注入 —— 捕获点击、表单、输入事件
+3. **测试**位于 `tests/brainstorm-server/` —— 验证服务器行为
+4. **头脑风暴技能**更新了视觉伴侣章节和 `visual-companion.md` 参考文档
+
+**使用方法：**
+
+1. 将服务器作为后台任务启动：`node lib/brainstorm-server/index.js &`
+2. 告诉用户打开 `http://localhost:3333`
+3. 将 HTML 写入 `/tmp/brainstorm/screen.html`
+4. 在任务输出中检查用户事件
diff --git a/zh-CN/docs/superpowers/plans/2026-01-22-document-review-system.md b/zh-CN/docs/superpowers/plans/2026-01-22-document-review-system.md
new file mode 100644
index 0000000000..bcea5e9018
--- /dev/null
+++ b/zh-CN/docs/superpowers/plans/2026-01-22-document-review-system.md
@@ -0,0 +1,310 @@
+# 文档评审系统实施计划
+
+> **对于智能体工作者：** 必需：使用 superpowers：子智能体驱动开发（如果子智能体可用）或 superpowers：执行计划来实现此计划。
+
+**目标：** 为头脑风暴和编写计划技能添加规范和计划文档评审循环。
+
+**架构：** 在每个技能目录中创建评审者提示模板。修改技能文件以在文档创建后添加评审循环。使用 Task 工具和通用子智能体进行评审者调度。
+
+**技术栈：** Markdown 技能文件，通过 Task 工具进行子智能体调度
+
+**规范：** docs/superpowers/specs/2026-01-22-document-review-system-design.md
+
+***
+
+## 模块 1：规范文档评审者
+
+此模块将规范文档评审者添加到头脑风暴技能中。
+
+### 任务 1：创建规范文档评审者提示模板
+
+**文件：**
+
+* 创建：`skills/brainstorming/spec-document-reviewer-prompt.md`
+
+* \[ ] **步骤 1：** 创建评审者提示模板文件
+
+```markdown
+# 规格文档审阅者提示模板
+
+在派发规格文档审阅者子代理时使用此模板。
+
+**目的：** 验证规格是否完整、一致，并已准备好进行实施规划。
+
+**派发时机：** 规格文档已写入 docs/superpowers/specs/
+```
+
+Task 工具（通用）：
+description: "评审规范文档"
+prompt: |
+您是一名规范文档评审者。请验证此规范是否完整并已准备好进行规划。
+
+```
+**Spec to review:** [SPEC_FILE_PATH]
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Coverage | Missing error handling, edge cases, integration points |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Ambiguous requirements |
+| YAGNI | Unrequested features, over-engineering |
+
+## CRITICAL
+
+Look especially hard for:
+- Any TODO markers or placeholder text
+- Sections saying "to be defined later" or "will spec when X is done"
+- Sections noticeably less detailed than others
+
+## Output Format
+
+## Spec Review
+
+**Status:** ✅ Approved | ❌ Issues Found
+
+**Issues (if any):**
+- [Section X]: [specific issue] - [why it matters]
+
+**Recommendations (advisory):**
+- [suggestions that don't block approval]
+```
+
+```
+**审阅者返回：** 状态，问题（如有），建议
+```
+
+* \[ ] **步骤 2：** 验证文件是否正确创建
+
+运行：`cat skills/brainstorming/spec-document-reviewer-prompt.md | head -20`
+预期：显示标题和目的部分
+
+* \[ ] **步骤 3：** 提交
+
+```bash
+git add skills/brainstorming/spec-document-reviewer-prompt.md
+git commit -m "feat: add spec document reviewer prompt template"
+```
+
+***
+
+### 任务 2：将评审循环添加到头脑风暴技能
+
+**文件：**
+
+* 修改：`skills/brainstorming/SKILL.md`
+
+* \[ ] **步骤 1：** 读取当前的头脑风暴技能
+
+运行：`cat skills/brainstorming/SKILL.md`
+
+* \[ ] **步骤 2：** 在“设计之后”部分后添加评审循环部分
+
+找到“设计之后”部分，并在文档之后、实施之前添加一个新的“规范评审循环”部分：
+
+```markdown
+**规范审查循环：**
+编写规范文档后：
+1. 派发规范文档审查子代理（参见 spec-document-reviewer-prompt.md）
+2. 若 ❌ 发现问题：
+   - 在规范文档中修复问题
+   - 重新派发审查员
+   - 重复直至 ✅ 获得批准
+3. 若 ✅ 获得批准：继续执行实施设置
+
+**审查循环指导原则：**
+- 由编写规范的同一代理进行修复（保持上下文一致）
+- 若循环超过5次迭代，则提请人工指导
+- 审查员仅提供建议——若您认为反馈有误，请解释分歧点
+```
+
+* \[ ] **步骤 3：** 验证更改
+
+运行：`grep -A 15 "Spec Review Loop" skills/brainstorming/SKILL.md`
+预期：显示新的评审循环部分
+
+* \[ ] **步骤 4：** 提交
+
+```bash
+git add skills/brainstorming/SKILL.md
+git commit -m "feat: add spec review loop to brainstorming skill"
+```
+
+***
+
+## 模块 2：计划文档评审者
+
+此模块将计划文档评审者添加到编写计划技能中。
+
+### 任务 3：创建计划文档评审者提示模板
+
+**文件：**
+
+* 创建：`skills/writing-plans/plan-document-reviewer-prompt.md`
+
+* \[ ] **步骤 1：** 创建评审者提示模板文件
+
+```markdown
+# 计划文档评审员提示模板
+
+在派遣计划文档评审员子代理时使用此模板。
+
+**目的：** 验证计划片段是否完整，是否符合规范，并具有适当的任务分解。
+
+**派遣时机：** 每个计划片段撰写完成后
+```
+
+Task 工具（通用）：
+description: "评审计划模块 N"
+prompt: |
+您是一名计划文档评审者。请验证此计划模块是否完整并已准备好实施。
+
+```
+**Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
+**Spec for reference:** [SPEC_FILE_PATH]
+
+## What to Check
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+| Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
+| Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
+| Task Syntax | Checkbox syntax (`- [ ]`) on tasks and steps |
+| Chunk Size | Each chunk under 1000 lines |
+
+## CRITICAL
+
+Look especially hard for:
+- Any TODO markers or placeholder text
+- Steps that say "similar to X" without actual content
+- Incomplete task definitions
+- Missing verification steps or expected outputs
+
+## Output Format
+
+## Plan Review - Chunk N
+
+**Status:** ✅ Approved | ❌ Issues Found
+
+**Issues (if any):**
+- [Task X, Step Y]: [specific issue] - [why it matters]
+
+**Recommendations (advisory):**
+- [suggestions that don't block approval]
+```
+
+```
+**审阅者返回：** 状态，问题（如有），建议
+```
+
+* \[ ] **步骤 2：** 验证文件已创建
+
+运行：`cat skills/writing-plans/plan-document-reviewer-prompt.md | head -20`
+预期：显示标题和目的部分
+
+* \[ ] **步骤 3：** 提交
+
+```bash
+git add skills/writing-plans/plan-document-reviewer-prompt.md
+git commit -m "feat: add plan document reviewer prompt template"
+```
+
+***
+
+### 任务 4：将评审循环添加到编写计划技能
+
+**文件：**
+
+* 修改：`skills/writing-plans/SKILL.md`
+
+* \[ ] **步骤 1：** 读取当前技能文件
+
+运行：`cat skills/writing-plans/SKILL.md`
+
+* \[ ] **步骤 2：** 添加逐模块评审部分
+
+在“执行交接”部分之前添加：
+
+```markdown
+## 计划审查循环
+
+完成每个计划区块后：
+
+1. 针对当前区块调度计划-文档-审查子代理
+   - 提供：区块内容、规范文档路径
+2. 如果 ❌ 发现问题：
+   - 在区块中修复问题
+   - 重新调度该区块的审查
+   - 重复直到 ✅ 通过批准
+3. 如果 ✅ 通过批准：继续下一个区块（或如果是最后一个区块，则移交执行）
+
+**区块边界：** 使用 `## Chunk N: <name>` 标题来划分区块。每个区块应 ≤1000 行且在逻辑上自成一体。
+```
+
+* \[ ] **步骤 3：** 更新任务语法示例以使用复选框
+
+更改“任务结构”部分以显示复选框语法：
+
+```markdown
+### 任务 N: [组件名称]
+
+- [ ] **步骤 1:** 编写失败的测试
+  - 文件: `tests/path/test.py`
+  ...
+```
+
+* \[ ] **步骤 4：** 验证评审循环部分已添加
+
+运行：`grep -A 15 "Plan Review Loop" skills/writing-plans/SKILL.md`
+预期：显示新的评审循环部分
+
+* \[ ] **步骤 5：** 验证任务语法示例已更新
+
+运行：`grep -A 5 "Task N:" skills/writing-plans/SKILL.md`
+预期：显示复选框语法 `### Task N:`
+
+* \[ ] **步骤 6：** 提交
+
+```bash
+git add skills/writing-plans/SKILL.md
+git commit -m "feat: add plan review loop and checkbox syntax to writing-plans skill"
+```
+
+***
+
+## 模块 3：更新计划文档标题
+
+此模块更新计划文档标题模板，以引用新的复选框语法要求。
+
+### 任务 5：在编写计划技能中更新计划标题模板
+
+**文件：**
+
+* 修改：`skills/writing-plans/SKILL.md`
+
+* \[ ] **步骤 1：** 读取当前计划标题模板
+
+运行：`grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md`
+
+* \[ ] **步骤 2：** 更新标题模板以引用复选框语法
+
+计划标题应注明任务和步骤使用复选框语法。更新标题注释：
+
+```markdown
+> **对于智能体工作者：** 必需：使用 superpowers:subagent-driven-development（如果子智能体可用）或 superpowers:executing-plans 来实施此计划。任务和步骤使用复选框（`- [ ]`）语法进行跟踪。
+```
+
+* \[ ] **步骤 3：** 验证更改
+
+运行：`grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md`
+预期：显示提及复选框语法的更新后标题
+
+* \[ ] **步骤 4：** 提交
+
+```bash
+git add skills/writing-plans/SKILL.md
+git commit -m "docs: update plan header to reference checkbox syntax"
+```
diff --git a/zh-CN/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md b/zh-CN/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
new file mode 100644
index 0000000000..e7bc2955ef
--- /dev/null
+++ b/zh-CN/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
@@ -0,0 +1,539 @@
+# 视觉化头脑风暴重构实施计划
+
+> **对于智能体工作者：** 必需：使用 superpowers:subagent-driven-development（如果子智能体可用）或 superpowers:executing-plans 来实施此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。
+
+**目标：** 将视觉化头脑风暴从阻塞式 TUI 反馈模型重构为非阻塞式“浏览器显示，终端命令”架构。
+
+**架构：** 浏览器成为交互式显示界面；终端保持为对话通道。服务器将用户事件写入一个每屏的 `.events` 文件，供 Claude 在其下一次轮次读取。消除 `wait-for-feedback.sh` 和所有 `TaskOutput` 阻塞。
+
+**技术栈：** Node.js (Express, ws, chokidar), 原生 HTML/CSS/JS
+
+**规范：** `docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md`
+
+***
+
+## 文件映射
+
+| 文件 | 操作 | 职责 |
+|------|--------|---------------|
+| `lib/brainstorm-server/index.js` | 修改 | 服务器：添加 `.events` 文件写入，在新屏幕时清除，替换 `wrapInFrame` |
+| `lib/brainstorm-server/frame-template.html` | 修改 | 模板：移除反馈页脚，添加内容占位符 + 选择指示器 |
+| `lib/brainstorm-server/helper.js` | 修改 | 客户端 JS：移除发送/反馈函数，精简为点击捕获 + 指示器更新 |
+| `lib/brainstorm-server/wait-for-feedback.sh` | 删除 | 不再需要 |
+| `skills/brainstorming/visual-companion.md` | 修改 | 技能说明：重写循环为非阻塞式流程 |
+| `tests/brainstorm-server/server.test.js` | 修改 | 测试：更新以适应新模板结构和 helper.js API |
+
+***
+
+## 块 1：服务器、模板、客户端、测试、技能
+
+### 任务 1：更新 `frame-template.html`
+
+**文件：**
+
+* 修改：`lib/brainstorm-server/frame-template.html`
+
+* \[ ] **步骤 1：移除反馈页脚 HTML**
+
+将 feedback-footer div（第 227-233 行）替换为选择指示器栏：
+
+```html
+  <div class="indicator-bar">
+    <span id="indicator-text">Click an option above, then return to the terminal</span>
+  </div>
+```
+
+同时将 `#claude-content` 内的默认内容（第 220-223 行）替换为内容占位符：
+
+```html
+    <div id="claude-content">
+      <!-- CONTENT -->
+    </div>
+```
+
+* \[ ] **步骤 2：将反馈页脚 CSS 替换为指示器栏 CSS**
+
+移除 `.feedback-footer`、`.feedback-footer label`、`.feedback-row` 以及 `.feedback-footer` 内的 textarea/button 样式（第 82-112 行）。
+
+添加指示器栏 CSS：
+
+```css
+    .indicator-bar {
+      background: var(--bg-secondary);
+      border-top: 1px solid var(--border);
+      padding: 0.5rem 1.5rem;
+      flex-shrink: 0;
+      text-align: center;
+    }
+    .indicator-bar span {
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+    }
+    .indicator-bar .selected-text {
+      color: var(--accent);
+      font-weight: 500;
+    }
+```
+
+* \[ ] **步骤 3：验证模板渲染**
+
+运行测试套件以检查模板是否仍能加载：
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：测试 1-5 应仍通过。测试 6-8 可能失败（预期如此——它们断言的是旧结构）。
+
+* \[ ] **步骤 4：提交**
+
+```bash
+git add lib/brainstorm-server/frame-template.html
+git commit -m "Replace feedback footer with selection indicator bar in brainstorm template"
+```
+
+***
+
+### 任务 2：更新 `index.js` — 内容注入和 `.events` 文件
+
+**文件：**
+
+* 修改：`lib/brainstorm-server/index.js`
+
+* \[ ] **步骤 1：为 `.events` 文件写入编写失败测试**
+
+在 `tests/brainstorm-server/server.test.js` 的测试 4 区域后添加——一个新的测试，发送带有 `choice` 字段的 WebSocket 事件，并验证 `.events` 文件被写入：
+
+```javascript
+    // Test: Choice events written to .events file
+    console.log('Test: Choice events written to .events file');
+    const ws3 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws3.on('open', resolve));
+
+    ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' }));
+    await sleep(300);
+
+    const eventsFile = path.join(TEST_DIR, '.events');
+    assert(fs.existsSync(eventsFile), '.events file should exist after choice click');
+    const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');
+    const event = JSON.parse(lines[lines.length - 1]);
+    assert.strictEqual(event.choice, 'a', 'Event should contain choice');
+    assert.strictEqual(event.text, 'Option A', 'Event should contain text');
+    ws3.close();
+    console.log('  PASS');
+```
+
+* \[ ] **步骤 2：运行测试以验证其失败**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：新测试失败——`.events` 文件尚不存在。
+
+* \[ ] **步骤 3：为 `.events` 文件在新屏幕时清除编写失败测试**
+
+添加另一个测试：
+
+```javascript
+    // Test: .events cleared on new screen
+    console.log('Test: .events cleared on new screen');
+    // .events file should still exist from previous test
+    assert(fs.existsSync(path.join(TEST_DIR, '.events')), '.events should exist before new screen');
+    fs.writeFileSync(path.join(TEST_DIR, 'new-screen.html'), '<h2>New screen</h2>');
+    await sleep(500);
+    assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen');
+    console.log('  PASS');
+```
+
+* \[ ] **步骤 4：运行测试以验证其失败**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：新测试失败——`.events` 在推送屏幕时未被清除。
+
+* \[ ] **步骤 5：在 `index.js` 中实现 `.events` 文件写入**
+
+在 WebSocket `message` 处理程序中（`index.js` 的第 74-77 行），`console.log` 之后，添加：
+
+```javascript
+    // Write user events to .events file for Claude to read
+    if (event.choice) {
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+    }
+```
+
+在 chokidar `add` 处理程序中（第 104-111 行），添加 `.events` 清除：
+
+```javascript
+    if (filePath.endsWith('.html')) {
+      // Clear events from previous screen
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      // ... existing reload broadcast
+    }
+```
+
+* \[ ] **步骤 6：用注释占位符注入替换 `wrapInFrame`**
+
+替换 `wrapInFrame` 函数（`index.js` 的第 27-32 行）：
+
+```javascript
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+```
+
+* \[ ] **步骤 7：运行所有测试**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：新的 `.events` 测试通过。现有测试可能仍有来自旧断言的失败（将在任务 4 中修复）。
+
+* \[ ] **步骤 8：提交**
+
+```bash
+git add lib/brainstorm-server/index.js tests/brainstorm-server/server.test.js
+git commit -m "Add .events file writing and comment-based content injection to brainstorm server"
+```
+
+***
+
+### 任务 3：简化 `helper.js`
+
+**文件：**
+
+* 修改：`lib/brainstorm-server/helper.js`
+
+* \[ ] **步骤 1：移除 `sendToClaude` 函数**
+
+删除 `sendToClaude` 函数（第 92-106 行）——函数体和页面接管 HTML。
+
+* \[ ] **步骤 2：移除 `window.send` 函数**
+
+删除 `window.send` 函数（第 120-129 行）——该函数与已移除的发送按钮绑定。
+
+* \[ ] **步骤 3：移除表单提交和输入变更处理程序**
+
+删除表单提交处理程序（第 57-71 行）和输入变更处理程序（第 73-89 行），包括 `inputTimeout` 变量。
+
+* \[ ] **步骤 4：移除 `pageshow` 事件监听器**
+
+删除我们之前添加的 `pageshow` 监听器（不再有需要清除的文本域）。
+
+* \[ ] **步骤 5：将点击处理程序精简为仅 `[data-choice]`**
+
+替换点击处理程序（第 36-55 行）为一个更精简的版本：
+
+```javascript
+  // Capture clicks on choice elements
+  document.addEventListener('click', (e) => {
+    const target = e.target.closest('[data-choice]');
+    if (!target) return;
+
+    sendEvent({
+      type: 'click',
+      text: target.textContent.trim(),
+      choice: target.dataset.choice,
+      id: target.id || null
+    });
+  });
+```
+
+* \[ ] **步骤 6：在选择点击时添加指示器栏更新**
+
+在点击处理程序中的 `sendEvent` 调用后，添加：
+
+```javascript
+    // Update indicator bar
+    const indicator = document.getElementById('indicator-text');
+    if (indicator) {
+      const label = target.querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || target.dataset.choice;
+      indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
+    }
+```
+
+* \[ ] **步骤 7：从 `window.brainstorm` API 中移除 `sendToClaude`**
+
+更新 `window.brainstorm` 对象（第 132-136 行）以移除 `sendToClaude`：
+
+```javascript
+  window.brainstorm = {
+    send: sendEvent,
+    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
+  };
+```
+
+* \[ ] **步骤 8：运行测试**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+* \[ ] **步骤 9：提交**
+
+```bash
+git add lib/brainstorm-server/helper.js
+git commit -m "Simplify helper.js: remove feedback functions, narrow to choice capture + indicator"
+```
+
+***
+
+### 任务 4：为新结构更新测试
+
+**文件：**
+
+* 修改：`tests/brainstorm-server/server.test.js`
+
+**注意：** 下面的行号引用来自*原始*文件。任务 2 在文件更早位置插入了新测试，因此实际行号会发生偏移。通过 `console.log` 标签（例如 "Test 5:"、"Test 6:"）查找测试。
+
+* \[ ] **步骤 1：更新测试 5（完整文档断言）**
+
+找到测试 5 的断言 `!fullRes.body.includes('feedback-footer')`。将其更改为：完整文档不应该有指示器栏（它们按原样提供）：
+
+```javascript
+    assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'),
+      'Should not wrap full documents in frame template');
+```
+
+* \[ ] **步骤 2：更新测试 6（片段包装）**
+
+第 125 行：将 `feedback-footer` 断言替换为指示器栏断言：
+
+```javascript
+    assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame');
+```
+
+同时验证内容占位符已被替换（片段内容出现，占位符注释不出现）：
+
+```javascript
+    assert(!fragRes.body.includes('<!-- CONTENT -->'), 'Content placeholder should be replaced');
+```
+
+* \[ ] **步骤 3：更新测试 7（helper.js API）**
+
+第 140-142 行：更新断言以反映新的 API 接口：
+
+```javascript
+    assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect');
+    assert(helperContent.includes('sendEvent'), 'helper.js should define sendEvent');
+    assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice');
+    assert(helperContent.includes('brainstorm'), 'helper.js should expose brainstorm API');
+    assert(!helperContent.includes('sendToClaude'), 'helper.js should not contain sendToClaude');
+```
+
+* \[ ] **步骤 4：将测试 8（sendToClaude 主题）替换为指示器栏测试**
+
+替换测试 8（第 145-149 行）——`sendToClaude` 不再存在。改为测试指示器栏：
+
+```javascript
+    // Test 8: Indicator bar uses CSS variables (theme support)
+    console.log('Test 8: Indicator bar uses CSS variables');
+    const templateContent = fs.readFileSync(
+      path.join(__dirname, '../../lib/brainstorm-server/frame-template.html'), 'utf-8'
+    );
+    assert(templateContent.includes('indicator-bar'), 'Template should have indicator bar');
+    assert(templateContent.includes('indicator-text'), 'Template should have indicator text element');
+    console.log('  PASS');
+```
+
+* \[ ] **步骤 5：运行完整测试套件**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：所有测试通过。
+
+* \[ ] **步骤 6：提交**
+
+```bash
+git add tests/brainstorm-server/server.test.js
+git commit -m "Update brainstorm server tests for new template structure and helper.js API"
+```
+
+***
+
+### 任务 5：删除 `wait-for-feedback.sh`
+
+**文件：**
+
+* 删除：`lib/brainstorm-server/wait-for-feedback.sh`
+
+* \[ ] **步骤 1：验证没有其他文件导入或引用 `wait-for-feedback.sh`**
+
+搜索代码库：
+
+```bash
+grep -r "wait-for-feedback" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.json"
+```
+
+预期引用：只有 `visual-companion.md`（将在任务 6 中重写）以及可能的发布说明（历史记录，保留原样）。
+
+* \[ ] **步骤 2：删除文件**
+
+```bash
+rm lib/brainstorm-server/wait-for-feedback.sh
+```
+
+* \[ ] **步骤 3：运行测试以确认没有破坏任何东西**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：所有测试通过（没有测试引用此文件）。
+
+* \[ ] **步骤 4：提交**
+
+```bash
+git add -u lib/brainstorm-server/wait-for-feedback.sh
+git commit -m "Delete wait-for-feedback.sh: replaced by .events file"
+```
+
+***
+
+### 任务 6：重写 `visual-companion.md`
+
+**文件：**
+
+* 修改：`skills/brainstorming/visual-companion.md`
+
+* \[ ] **步骤 1：更新“工作原理”描述（第 18 行）**
+
+将关于接收反馈“作为 JSON”的句子替换为：
+
+```markdown
+服务器监视一个目录中的 HTML 文件，并将最新的一个提供给浏览器。你编写 HTML 内容，用户在其浏览器中查看，并可以通过点击来选择选项。选择会被记录到一个 `.events` 文件中，供你在下一回合读取。
+```
+
+* \[ ] **步骤 2：更新片段描述（第 20 行）**
+
+从框架模板提供的描述中移除“反馈页脚”：
+
+```markdown
+**内容片段与完整文档：** 如果您的 HTML 文件以 `<!DOCTYPE` 或 `<html` 开头，服务器会直接提供它（仅注入辅助脚本）。否则，服务器会自动将您的内容包装在框架模板中——添加页眉、CSS 主题、选择指示器以及所有交互式基础结构。**默认情况下请编写内容片段。** 仅在需要完全控制页面时编写完整文档。
+```
+
+* \[ ] **步骤 3：重写“循环”部分（第 36-61 行）**
+
+替换整个“循环”部分为：
+
+```markdown
+## 循环流程
+
+1.  **编写 HTML** 到 `screen_dir` 中的一个新文件：
+    *   使用语义化的文件名：`platform.html`、`visual-style.html`、`layout.html`
+    *   **切勿重用文件名** — 每个屏幕都应使用一个全新的文件
+    *   使用 Write 工具 — **切勿使用 cat/heredoc**（这会将噪音输出到终端）
+    *   服务器会自动提供最新的文件
+
+2.  **告知用户预期结果并结束你的回合：**
+    *   提醒他们 URL（每一步都要提醒，不仅仅是第一步）
+    *   简要描述屏幕上的内容（例如，“为主页展示了 3 个布局选项”）
+    *   请他们在终端中回复：“查看一下并告诉我你的想法。如果你想选择某个选项，请点击它。”
+
+3.  **在你的下一个回合** — 在用户在终端中回复之后：
+    *   如果 `$SCREEN_DIR/.events` 存在，请读取它 — 它包含用户的浏览器交互（点击、选择）数据，以 JSON 行格式记录
+    *   将其与用户的终端文本合并，以获得完整的反馈信息
+    *   终端消息是主要的反馈来源；`.events` 提供结构化的交互数据
+
+4.  **迭代或推进** — 如果反馈改变了当前屏幕，则写入一个新文件（例如，`layout-v2.html`）。只有当当前步骤得到确认后，才进入下一个问题。
+
+5.  重复以上步骤，直到完成。
+```
+
+* \[ ] **步骤 4：替换“用户反馈格式”部分（第 165-174 行）**
+
+替换为：
+
+````markdown
+## 浏览器事件格式
+
+当用户在浏览器中点击选项时，其交互会被记录到 `$SCREEN_DIR/.events`（每行一个 JSON 对象）。当你推送新屏幕时，该文件会自动清空。
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+
+````
+
+完整的事件流显示了用户的探索路径——他们可能在确定之前点击了多个选项。最后一个 `choice` 事件通常是最终选择，但点击模式可能揭示值得询问的犹豫或偏好。
+
+如果 `.events` 不存在，则用户未与浏览器交互——仅使用其终端文本。
+
+````
+- [ ] **Step 5: Update "Writing Content Fragments" description (line 65)**
+
+移除 "feedback footer" 引用：
+
+```markdown
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+````
+
+* \[ ] **步骤 6：更新参考部分（第 200-203 行）**
+
+移除关于“JS API”的 helper.js 引用描述——API 现在是最小化的。保留路径引用：
+
+```markdown
+## 参考
+
+- 框架模板（CSS 参考）：`${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
+- 辅助脚本（客户端）：`${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/helper.js`
+```
+
+* \[ ] **步骤 7：提交**
+
+```bash
+git add skills/brainstorming/visual-companion.md
+git commit -m "Rewrite visual-companion.md for non-blocking browser-displays-terminal-commands flow"
+```
+
+***
+
+### 任务 7：最终验证
+
+* \[ ] **步骤 1：运行完整测试套件**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+预期：所有测试通过。
+
+* \[ ] **步骤 2：手动冒烟测试**
+
+手动启动服务器并验证端到端流程是否工作：
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && lib/brainstorm-server/start-server.sh --project-dir /tmp/brainstorm-smoke-test
+```
+
+写入一个测试片段，在浏览器中打开，点击一个选项，验证 `.events` 文件被写入，验证指示器栏更新。然后停止服务器：
+
+```bash
+lib/brainstorm-server/stop-server.sh <screen_dir from start output>
+```
+
+* \[ ] **步骤 3：验证没有残留的陈旧引用**
+
+```bash
+grep -r "wait-for-feedback\|sendToClaude\|feedback-footer\|send-to-claude\|TaskOutput.*block.*true" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.html" | grep -v node_modules | grep -v RELEASE-NOTES | grep -v "\.md:.*spec\|plan"
+```
+
+预期：除了发布说明和规范/计划文档（这些是历史记录）外，没有其他匹配项。
+
+* \[ ] **步骤 4：如果需要任何清理，进行最终提交**
+
+```bash
+git status
+# Review untracked/modified files, stage specific files as needed, commit if clean
+```
diff --git a/zh-CN/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md b/zh-CN/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
new file mode 100644
index 0000000000..dfe1547c2a
--- /dev/null
+++ b/zh-CN/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
@@ -0,0 +1,490 @@
+# 零依赖头脑风暴服务器实现计划
+
+> **针对智能体工作者：** 必需：使用 superpowers:子智能体驱动开发（如果子智能体可用）或 superpowers:执行计划 来实现此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。
+
+**目标：** 将头脑风暴服务器的第三方 node\_modules 替换为单个零依赖的 `server.js`，仅使用 Node 内置模块。
+
+**架构：** 单个文件，包含 WebSocket 协议（RFC 6455 文本帧）、HTTP 服务器（`http` 模块）和文件监视（`fs.watch`）。当作为模块被需要时，导出协议函数以供单元测试。
+
+**技术栈：** 仅使用 Node.js 内置模块：`http`, `crypto`, `fs`, `path`
+
+**规范：** `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`
+
+**现有测试：** `tests/brainstorm-server/ws-protocol.test.js`（单元测试），`tests/brainstorm-server/server.test.js`（集成测试）
+
+***
+
+## 文件映射
+
+* **创建：** `skills/brainstorming/scripts/server.js` — 零依赖替代文件
+* **修改：** `skills/brainstorming/scripts/start-server.sh:94,100` — 将 `index.js` 改为 `server.js`
+* **修改：** `.gitignore:6` — 移除 `!skills/brainstorming/scripts/node_modules/` 例外
+* **删除：** `skills/brainstorming/scripts/index.js`
+* **删除：** `skills/brainstorming/scripts/package.json`
+* **删除：** `skills/brainstorming/scripts/package-lock.json`
+* **删除：** `skills/brainstorming/scripts/node_modules/`（714 个文件）
+* **无更改：** `skills/brainstorming/scripts/helper.js`, `skills/brainstorming/scripts/frame-template.html`, `skills/brainstorming/scripts/stop-server.sh`
+
+***
+
+## 区块 1：WebSocket 协议层
+
+### 任务 1：实现 WebSocket 协议导出
+
+**文件：**
+
+* 创建：`skills/brainstorming/scripts/server.js`
+
+* 测试：`tests/brainstorm-server/ws-protocol.test.js`（已存在）
+
+* \[ ] **步骤 1：创建 server.js，包含 OPCODES 常量和 computeAcceptKey 函数**
+
+```js
+const crypto = require('crypto');
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+```
+
+* \[ ] **步骤 2：实现 encodeFrame 函数**
+
+服务器帧从不掩码。三种长度编码：
+
+* 载荷 < 126：2 字节头部（FIN+操作码，长度）
+* 126-65535：4 字节头部（FIN+操作码，126，16 位长度）
+* \> 65535：10 字节头部（FIN+操作码，127，64 位长度）
+
+```js
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+```
+
+* \[ ] **步骤 3：实现 decodeFrame 函数**
+
+客户端帧始终被掩码。返回 `{ opcode, payload, bytesConsumed }` 或 `null` 表示不完整。对未掩码的帧抛出错误。
+
+```js
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const firstByte = buffer[0];
+  const secondByte = buffer[1];
+  const opcode = firstByte & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+```
+
+* \[ ] **步骤 4：在文件底部添加模块导出**
+
+```js
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
+```
+
+* \[ ] **步骤 5：运行单元测试**
+
+运行：`cd tests/brainstorm-server && node ws-protocol.test.js`
+预期：所有测试通过（握手、编码、解码、边界情况、边缘情况）
+
+* \[ ] **步骤 6：提交**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add WebSocket protocol layer for zero-dep brainstorm server"
+```
+
+***
+
+## 区块 2：HTTP 服务器和应用逻辑
+
+### 任务 2：添加 HTTP 服务器、文件监视和 WebSocket 连接处理
+
+**文件：**
+
+* 修改：`skills/brainstorming/scripts/server.js`
+
+* 测试：`tests/brainstorm-server/server.test.js`（已存在）
+
+* \[ ] **步骤 1：在 server.js 顶部（require 之后）添加配置和常量**
+
+```js
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+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 MIME_TYPES = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
+};
+```
+
+* \[ ] **步骤 2：添加 WAITING\_PAGE、模板加载（模块作用域）和辅助函数**
+
+在模块作用域加载 `frameTemplate` 和 `helperInjection`，以便 `wrapInFrame` 和 `handleRequest` 可以访问。它们只从 `__dirname`（脚本目录）读取文件，无论模块是被 require 还是直接运行，这都是有效的。
+
+```js
+const WAITING_PAGE = `<!DOCTYPE html>
+<html>
+<head><title>Brainstorm Companion</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; }</style>
+</head>
+<body><h1>Brainstorm Companion</h1>
+<p>Waiting for Claude to push a screen...</p></body></html>`;
+
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = '<script>\n' + helperScript + '\n</script>';
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
+}
+
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+
+function getNewestScreen() {
+  const files = fs.readdirSync(SCREEN_DIR)
+    .filter(f => f.endsWith('.html'))
+    .map(f => {
+      const fp = path.join(SCREEN_DIR, f);
+      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].path : null;
+}
+```
+
+* \[ ] **步骤 3：添加 HTTP 请求处理器**
+
+```js
+function handleRequest(req, res) {
+  if (req.method === 'GET' && req.url === '/') {
+    const screenFile = getNewestScreen();
+    let html = screenFile
+      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
+      : WAITING_PAGE;
+
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', helperInjection + '\n</body>');
+    } else {
+      html += helperInjection;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
+    const fileName = req.url.slice(7); // strip '/files/'
+    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(fs.readFileSync(filePath));
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+```
+
+* \[ ] **步骤 4：添加 WebSocket 连接处理**
+
+```js
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          handleMessage(result.payload.toString());
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default:
+          // Unsupported opcode — close with 1003
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function handleMessage(text) {
+  let event;
+  try {
+    event = JSON.parse(text);
+  } catch (e) {
+    console.error('Failed to parse WebSocket message:', e.message);
+    return;
+  }
+  console.log(JSON.stringify({ source: 'user-event', ...event }));
+  if (event.choice) {
+    const eventsFile = path.join(SCREEN_DIR, '.events');
+    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+  }
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+```
+
+* \[ ] **步骤 5：添加防抖计时器映射**
+
+```js
+const debounceTimers = new Map();
+```
+
+文件监视逻辑内联在 `startServer`（步骤 6）中，以便将监视器生命周期与服务器生命周期保持在一起，并根据规范包含一个 `error` 处理器。
+
+* \[ ] **步骤 6：添加 startServer 函数和条件主逻辑**
+
+`frameTemplate` 和 `helperInjection` 已在模块作用域（步骤 2）。`startServer` 只是创建屏幕目录、启动 HTTP 服务器、监视器并记录启动信息。
+
+```js
+function startServer() {
+  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  const watcher = fs.watch(SCREEN_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);
+      if (eventType === 'rename' && fs.existsSync(filePath)) {
+        const eventsFile = path.join(SCREEN_DIR, '.events');
+        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      } else if (eventType === 'change') {
+        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
+      }
+      broadcast({ type: 'reload' });
+    }, 100));
+  });
+  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+
+  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
+    });
+    console.log(info);
+    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+  });
+}
+
+if (require.main === module) {
+  startServer();
+}
+```
+
+* \[ ] **步骤 7：运行集成测试**
+
+测试目录已有一个 `package.json`，依赖 `ws`。如果需要，请安装它，然后运行测试。
+
+运行：`cd tests/brainstorm-server && npm install && node server.test.js`
+预期：所有测试通过
+
+* \[ ] **步骤 8：提交**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add HTTP server, WebSocket handling, and file watching to server.js"
+```
+
+***
+
+## 区块 3：替换和清理
+
+### 任务 3：更新 start-server.sh 并删除旧文件
+
+**文件：**
+
+* 修改：`skills/brainstorming/scripts/start-server.sh:94,100`
+
+* 修改：`.gitignore:6`
+
+* 删除：`skills/brainstorming/scripts/index.js`
+
+* 删除：`skills/brainstorming/scripts/package.json`
+
+* 删除：`skills/brainstorming/scripts/package-lock.json`
+
+* 删除：`skills/brainstorming/scripts/node_modules/`（整个目录）
+
+* \[ ] **步骤 1：更新 start-server.sh — 将 `index.js` 改为 `server.js`**
+
+需要更改两行：
+
+第 94 行：`env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js`
+
+第 100 行：`nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js > "$LOG_FILE" 2>&1 &`
+
+* \[ ] **步骤 2：移除对 node\_modules 的 gitignore 例外**
+
+在 `.gitignore` 中，删除第 6 行：`!skills/brainstorming/scripts/node_modules/`
+
+* \[ ] **步骤 3：删除旧文件**
+
+```bash
+git rm skills/brainstorming/scripts/index.js
+git rm skills/brainstorming/scripts/package.json
+git rm skills/brainstorming/scripts/package-lock.json
+git rm -r skills/brainstorming/scripts/node_modules/
+```
+
+* \[ ] **步骤 4：运行两个测试套件**
+
+运行：`cd tests/brainstorm-server && node ws-protocol.test.js && node server.test.js`
+预期：所有测试通过
+
+* \[ ] **步骤 5：提交**
+
+```bash
+git add skills/brainstorming/scripts/ .gitignore
+git commit -m "Remove vendored node_modules, swap to zero-dep server.js"
+```
+
+### 任务 4：手动冒烟测试
+
+* \[ ] **步骤 1：手动启动服务器**
+
+```bash
+cd skills/brainstorming/scripts
+BRAINSTORM_DIR=/tmp/brainstorm-smoke BRAINSTORM_PORT=9876 node server.js
+```
+
+预期：打印 `server-started` JSON，端口为 9876
+
+* \[ ] **步骤 2：在浏览器中打开 http://localhost:9876**
+
+预期：显示等待页面，内容为"Waiting for Claude to push a screen..."
+
+* \[ ] **步骤 3：向屏幕目录写入一个 HTML 文件**
+
+```bash
+echo '<h2>Hello from smoke test</h2>' > /tmp/brainstorm-smoke/test.html
+```
+
+预期：浏览器刷新并显示"Hello from smoke test"，包裹在框架模板中
+
+* \[ ] **步骤 4：验证 WebSocket 是否正常工作 — 检查浏览器控制台**
+
+打开浏览器开发者工具。WebSocket 连接应显示为已连接（控制台无错误）。框架模板的状态指示器应显示"Connected"。
+
+* \[ ] **步骤 5：使用 Ctrl-C 停止服务器，清理**
+
+```bash
+rm -rf /tmp/brainstorm-smoke
+```
diff --git a/zh-CN/docs/superpowers/specs/2026-01-22-document-review-system-design.md b/zh-CN/docs/superpowers/specs/2026-01-22-document-review-system-design.md
new file mode 100644
index 0000000000..cdf2243b39
--- /dev/null
+++ b/zh-CN/docs/superpowers/specs/2026-01-22-document-review-system-design.md
@@ -0,0 +1,146 @@
+# 文档评审系统设计
+
+## 概述
+
+在 superpowers 工作流中新增两个评审阶段：
+
+1. **规格说明书评审** - 头脑风暴之后，编写计划之前
+2. **计划文档评审** - 编写计划之后，实施之前
+
+两者都遵循实施评审所使用的迭代循环模式。
+
+## 规格说明书评审员
+
+**目的：** 验证规格说明书是否完整、一致，并已准备好用于实施规划。
+
+**位置：** `skills/brainstorming/spec-document-reviewer-prompt.md`
+
+**检查内容：**
+
+| 类别 | 需要关注的点 |
+|------|--------------|
+| 完整性 | TODO项、占位符、"TBD"、不完整的章节 |
+| 覆盖度 | 缺失的错误处理、边界情况、集成点 |
+| 一致性 | 内部矛盾、冲突的需求 |
+| 清晰度 | 模糊不清的需求 |
+| YAGNI（你不需要它） | 未要求的功能、过度设计 |
+
+**输出格式：**
+
+```
+## 规格评审
+
+**状态：** 已批准 | 发现问题
+
+**问题（如有）：**
+- [章节 X]: [问题] - [原因说明]
+
+**建议（仅供参考）：**
+- [不影响批准的建议]
+```
+
+**评审循环：** 发现问题 -> 头脑风暴代理修复 -> 重新评审 -> 重复直至批准。
+
+**调度机制：** 使用任务工具 `subagent_type: general-purpose`。评审员提示模板提供了完整的提示。头脑风暴技能的控制器负责调度评审员。
+
+## 计划文档评审员
+
+**目的：** 验证计划是否完整、与规格说明书匹配，并且具有正确的任务分解。
+
+**位置：** `skills/writing-plans/plan-document-reviewer-prompt.md`
+
+**检查内容：**
+
+| 类别 | 需要关注的点 |
+|------|--------------|
+| 完整性 | TODO项、占位符、不完整的任务 |
+| 规格对齐 | 计划覆盖了规格需求，无范围蔓延 |
+| 任务分解 | 任务具有原子性，边界清晰 |
+| 任务语法 | 任务和步骤的复选框语法 |
+| 区块大小 | 每个区块少于 1000 行 |
+
+**区块定义：** 区块是计划文档内任务的逻辑分组，由 `## Chunk N: <name>` 标题分隔。编写计划技能根据逻辑阶段（例如"基础"、"核心功能"、"集成"）创建这些边界。每个区块应足够自包含，以便独立评审。
+
+**规格对齐验证：** 评审员接收以下两项：
+
+1. 计划文档（或当前区块）
+2. 用于参考的规格说明书路径
+
+评审员读取两者并比较需求覆盖情况。
+
+**输出格式：** 与规格说明书评审员相同，但范围限定在当前区块。
+
+**评审流程（逐区块）：**
+
+1. 编写计划创建区块 N
+2. 控制器调度计划文档评审员，附带区块 N 内容和规格说明书路径
+3. 评审员读取区块和规格说明书，返回裁决
+4. 如果发现问题：编写计划代理修复区块 N，转到步骤 2
+5. 如果批准：继续处理区块 N+1
+6. 重复直到所有区块获得批准
+
+**调度机制：** 与规格说明书评审员相同 - 使用任务工具 `subagent_type: general-purpose`。
+
+## 更新后的工作流
+
+```
+brainstorming -> spec -> SPEC REVIEW LOOP -> writing-plans -> plan -> PLAN REVIEW LOOP -> implementation
+```
+
+**规格评审循环：**
+
+1. 规格说明书完成
+2. 调度评审员
+3. 如果发现问题：修复 -> 转到 2
+4. 如果批准：继续
+
+**计划评审循环：**
+
+1. 区块 N 完成
+2. 为区块 N 调度评审员
+3. 如果发现问题：修复 -> 转到 2
+4. 如果批准：处理下一个区块或进入实施阶段
+
+## Markdown 任务语法
+
+任务和步骤使用复选框语法：
+
+```markdown
+- [ ] ### 任务 1：名称
+
+- [ ] **步骤 1：描述**
+  - 文件：路径
+  - 命令：cmd
+```
+
+## 错误处理
+
+**评审循环终止：**
+
+* 无硬性迭代限制 - 循环持续直到评审员批准
+* 如果循环超过 5 次迭代，控制器应将此情况呈现给人类以寻求指导
+* 人类可以选择：继续迭代、批准已知问题或中止
+
+**分歧处理：**
+
+* 评审员是建议性的 - 他们标记问题但不阻塞
+* 如果代理认为评审员的反馈不正确，应在修复中解释原因
+* 如果同一问题在 3 次迭代后仍存在分歧，则呈现给人类
+
+**评审员输出格式错误：**
+
+* 控制器应验证评审员输出是否具有必填字段（状态，以及适用时的"问题"）
+* 如果格式错误，重新调度评审员并附带关于预期格式的说明
+* 在 2 次格式错误的响应后，呈现给人类
+
+## 需要更改的文件
+
+**新增文件：**
+
+* `skills/brainstorming/spec-document-reviewer-prompt.md`
+* `skills/writing-plans/plan-document-reviewer-prompt.md`
+
+**修改文件：**
+
+* `skills/brainstorming/SKILL.md` - 在规格说明书编写后添加评审循环
+* `skills/writing-plans/SKILL.md` - 添加逐区块评审循环，更新任务语法示例
diff --git a/zh-CN/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md b/zh-CN/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md
new file mode 100644
index 0000000000..929e61f623
--- /dev/null
+++ b/zh-CN/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md
@@ -0,0 +1,174 @@
+# 可视化头脑风暴重构：浏览器显示与终端命令
+
+**日期：** 2026-02-19
+**状态：** 已批准
+**范围：** `lib/brainstorm-server/`, `skills/brainstorming/visual-companion.md`, `tests/brainstorm-server/`
+
+## 问题
+
+在可视化头脑风暴过程中，Claude 将 `wait-for-feedback.sh` 作为后台任务运行并阻塞在 `TaskOutput(block=true, timeout=600s)` 上。这会完全占用 TUI —— 在可视化头脑风暴运行时用户无法向 Claude 输入。浏览器成为唯一的输入通道。
+
+Claude Code 的执行模型是基于轮次的。Claude 无法在一个轮次内同时监听两个通道。阻塞式的 `TaskOutput` 模式是错误的原语 —— 它模拟了平台不支持的基于事件的行为。
+
+## 设计
+
+### 核心模型
+
+**浏览器 = 交互式显示。** 显示设计稿，让用户点击选择选项。选择结果记录在服务器端。
+
+**终端 = 对话通道。** 始终保持畅通，始终可用。用户在此与 Claude 对话。
+
+### 循环流程
+
+1. Claude 将 HTML 文件写入会话目录
+2. 服务器通过 chokidar 检测到该文件，通过 WebSocket 推送重新加载指令到浏览器（保持不变）
+3. Claude 结束其轮次 —— 告诉用户检查浏览器并在终端中回应
+4. 用户查看浏览器，可选地点击选择选项，然后在终端中输入反馈
+5. 在下一轮次中，Claude 读取 `$SCREEN_DIR/.events` 以获取浏览器交互流（点击、选择），并与终端文本合并
+6. 迭代或推进
+
+无后台任务。无 `TaskOutput` 阻塞。无轮询脚本。
+
+### 关键删除项：`wait-for-feedback.sh`
+
+完全删除。其目的是在“服务器将事件记录到标准输出”和“Claude 需要接收这些事件”之间建立桥梁。`.events` 文件取代了它 —— 服务器直接写入用户交互事件，而 Claude 使用平台提供的任何文件读取机制来读取它们。
+
+### 关键新增项：`.events` 文件（每屏幕事件流）
+
+服务器将所有用户交互事件写入 `$SCREEN_DIR/.events`，每行一个 JSON 对象。这为 Claude 提供了当前屏幕的完整交互流 —— 不仅仅是最终选择，还包括用户的探索路径（点击了 A，然后 B，最终选定 C）。
+
+用户探索选项后的示例内容：
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Preset-First Wizard","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Manual Config","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid Approach","timestamp":1706000115}
+```
+
+* 在单个屏幕内是追加写入。每个用户事件都作为新行追加。
+* 当 chokidar 检测到新的 HTML 文件（推送新屏幕）时，文件会被清除（删除），防止陈旧的事件延续。
+* 如果 Claude 读取时文件不存在，则表示没有发生浏览器交互 —— Claude 仅使用终端文本。
+* 该文件仅包含用户事件（`click` 等）—— 不包含服务器生命周期事件（`server-started`、`screen-added`）。这使其保持小巧且专注。
+* Claude 可以读取完整流来理解用户的探索模式，或者仅查看最后的 `choice` 事件以获取最终选择。
+
+## 按文件划分的变更
+
+### `index.js`（服务器）
+
+**A. 将用户事件写入 `.events` 文件。**
+
+在 WebSocket `message` 处理程序中，将事件记录到标准输出后：通过 `fs.appendFileSync` 将事件作为 JSON 行追加到 `$SCREEN_DIR/.events`。仅写入用户交互事件（那些带有 `source: 'user-event'` 的），不写入服务器生命周期事件。
+
+**B. 在新屏幕时清除 `.events`。**
+
+在 chokidar `add` 处理程序（检测到新的 `.html` 文件）中，如果 `$SCREEN_DIR/.events` 存在则删除它。这是明确的“新屏幕”信号 —— 比在每次重新加载都会触发的 GET `/` 时清除更好。
+
+**C. 替换 `wrapInFrame` 内容注入。**
+
+当前的正则表达式锚定在 `<div class="feedback-footer">`，而该内容正在被移除。替换为注释占位符：移除 `#claude-content` 内现有的默认内容（`<h2>Visual Brainstorming</h2>` 和副标题段落），并替换为单个 `<!-- CONTENT -->` 标记。内容注入变为 `frameTemplate.replace('<!-- CONTENT -->', content)`。更简单，并且如果模板格式更改也不会中断。
+
+### `frame-template.html`（UI 框架）
+
+**移除：**
+
+* `feedback-footer` div（文本区域、发送按钮、标签、`.feedback-row`）
+* 相关的 CSS（`.feedback-footer`、`.feedback-footer label`、`.feedback-row`、其中的文本区域和按钮样式）
+
+**添加：**
+
+* `<!-- CONTENT -->` 占位符在 `#claude-content` 内，替换默认文本
+* 一个选择指示条，位于原来页脚的位置，有两种状态：
+  * 默认：“点击上方选项，然后返回终端”
+  * 选择后：“已选择选项 B —— 返回终端以继续”
+* 指示条的 CSS（微妙，视觉重量与现有页眉相似）
+
+**保持不变：**
+
+* 带有“Brainstorm Companion”标题和连接状态的页眉栏
+* `.main` 包装器和 `#claude-content` 容器
+* 所有组件 CSS（`.options`、`.cards`、`.mockup`、`.split`、`.pros-cons`、占位符、模拟元素）
+* 深色/浅色主题变量和媒体查询
+
+### `helper.js`（客户端脚本）
+
+**移除：**
+
+* `sendToClaude()` 函数和“已发送给 Claude”页面接管
+* `window.send()` 函数（与已移除的发送按钮关联）
+* 表单提交处理程序 —— 没有反馈文本区域后无意义，增加日志噪音
+* 输入变更处理程序 —— 原因同上
+* `pageshow` 事件监听器（原为修复文本区域持久性而添加 —— 现在没有文本区域了）
+
+**保留：**
+
+* WebSocket 连接、重新连接逻辑、事件队列
+* 重新加载处理程序（服务器推送时的 `window.location.reload()`）
+* 用于选择高亮的 `window.toggleSelect()`
+* `window.selectedChoice` 跟踪
+* `window.brainstorm.send()` 和 `window.brainstorm.choice()` —— 这些与已移除的 `window.send()` 不同。它们调用 `sendEvent`，后者通过 WebSocket 记录到服务器。对自定义完整文档页面很有用。
+
+**收窄范围：**
+
+* 点击处理程序：仅捕获 `[data-choice]` 点击，而非所有按钮/链接。当浏览器是反馈通道时需要广泛捕获；现在仅用于选择跟踪。
+
+**添加：**
+
+* 在 `data-choice` 点击时，更新选择指示条文本以显示选择了哪个选项。
+
+**从 `window.brainstorm` API 中移除：**
+
+* `brainstorm.sendToClaude` —— 不再存在
+
+### `visual-companion.md`（技能说明）
+
+**重写“循环流程”部分**为上述非阻塞流程。移除所有对以下内容的引用：
+
+* `wait-for-feedback.sh`
+* `TaskOutput` 阻塞
+* 超时/重试逻辑（600 秒超时，30 分钟上限）
+* 描述 `send-to-claude` JSON 的“用户反馈格式”部分
+
+**替换为：**
+
+* 新循环（写入 HTML → 结束轮次 → 用户在终端回应 → 读取 `.events` → 迭代）
+* `.events` 文件格式文档
+* 指导说明：终端消息是主要反馈；`.events` 提供完整的浏览器交互流以获取额外上下文
+
+**保留：**
+
+* 服务器启动/关闭说明
+* 内容片段与完整文档的指导
+* CSS 类参考和可用组件
+* 设计技巧（根据问题调整保真度、每屏幕 2-4 个选项等）
+
+### `wait-for-feedback.sh`
+
+**完全删除。**
+
+### `tests/brainstorm-server/server.test.js`
+
+需要更新的测试：
+
+* 断言片段响应中存在 `feedback-footer` 的测试 —— 更新为断言选择指示条或 `<!-- CONTENT -->` 替换
+* 断言 `helper.js` 包含 `send` 的测试 —— 更新以反映收窄的 API
+* 断言 `sendToClaude` CSS 变量用法的测试 —— 移除（函数不再存在）
+
+## 平台兼容性
+
+服务器代码（`index.js`、`helper.js`、`frame-template.html`）完全与平台无关 —— 纯 Node.js 和浏览器 JavaScript。没有 Claude Code 特定引用。已通过后台终端交互在 Codex 上验证可行。
+
+技能说明（`visual-companion.md`）是平台适配层。每个平台的 Claude 使用其自己的工具来启动服务器、读取 `.events` 等。非阻塞模型自然适用于所有平台，因为它不依赖任何平台特定的阻塞原语。
+
+## 此项重构带来的能力
+
+* **TUI 在可视化头脑风暴期间始终保持响应**
+* **混合输入** —— 在浏览器中点击 + 在终端中键入，自然地合并
+* **优雅降级** —— 浏览器关闭或用户未打开？终端仍然可用
+* **更简单的架构** —— 无后台任务、无轮询脚本、无超时管理
+* **跨平台** —— 相同的服务器代码适用于 Claude Code、Codex 及任何未来平台
+
+## 此项重构舍弃的内容
+
+* **纯浏览器反馈工作流** —— 用户必须返回终端才能继续。选择指示条会引导他们，但与旧的点击-发送-等待流程相比，这多了一个步骤。
+* **来自浏览器的内联文本反馈** —— 文本区域已移除。所有文本反馈都通过终端进行。这是有意为之 —— 终端是比框架中的小文本区域更好的文本输入通道。
+* **浏览器发送后的即时响应** —— 旧系统在用户点击发送时 Claude 会立即响应。现在用户切换到终端时存在间隙。实际上这只有几秒钟，并且用户可以在其终端消息中添加上下文。
diff --git a/zh-CN/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md b/zh-CN/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md
new file mode 100644
index 0000000000..3eaeb56f02
--- /dev/null
+++ b/zh-CN/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md
@@ -0,0 +1,119 @@
+# 零依赖头脑风暴服务器
+
+将头脑风暴伴侣服务器中打包的 node\_modules（express、ws、chokidar —— 714 个跟踪文件）替换为仅使用 Node.js 内置模块的单个零依赖 `server.js`。
+
+## 动机
+
+将 node\_modules 打包到 git 仓库中会带来供应链风险：冻结的依赖项无法获得安全补丁，714 个未经审计的第三方代码文件被提交，且对打包代码的修改看起来像普通提交。虽然实际风险较低（仅限本地开发服务器），但消除它非常简单。
+
+## 架构
+
+使用 `http`、`crypto`、`fs` 和 `path` 的单个 `server.js` 文件（约 250-300 行）。该文件扮演两个角色：
+
+* **直接运行时**（`node server.js`）：启动 HTTP/WebSocket 服务器
+* **被引用时**（`require('./server.js')`）：导出用于单元测试的 WebSocket 协议函数
+
+### WebSocket 协议
+
+仅实现文本帧的 RFC 6455：
+
+**握手：** 使用 SHA-1 和 RFC 6455 魔法 GUID 从客户端的 `Sec-WebSocket-Key` 计算 `Sec-WebSocket-Accept`。返回 101 切换协议。
+
+**帧解码（客户端到服务器）：** 处理三种带掩码的长度编码：
+
+* 小型：有效负载 < 126 字节
+* 中型：126-65535 字节（16 位扩展）
+* 大型：> 65535 字节（64 位扩展）
+
+使用 4 字节掩码密钥对有效负载进行 XOR 解掩码。对于不完整的缓冲区，返回 `{ opcode, payload, bytesConsumed }` 或 `null`。拒绝未掩码的帧。
+
+**帧编码（服务器到客户端）：** 使用相同三种长度编码的未掩码帧。
+
+**处理的操作码：** TEXT (0x01)、CLOSE (0x08)、PING (0x09)、PONG (0x0A)。无法识别的操作码将收到状态为 1003（不支持的数据）的关闭帧。
+
+**有意跳过的功能：** 二进制帧、分片消息、扩展（permessage-deflate）、子协议。这些对于 localhost 客户端之间的小型 JSON 文本消息是不必要的。扩展和子协议在握手时协商 —— 通过不宣告它们，它们永远不会被激活。
+
+**缓冲区累积：** 每个连接维护一个缓冲区。在 `data` 时，追加并循环 `decodeFrame`，直到它返回 null 或缓冲区为空。
+
+### HTTP 服务器
+
+三个路由：
+
+1. **`GET /`** —— 按修改时间从屏幕目录提供最新的 `.html`。检测完整文档与片段，将片段包装在框架模板中，注入 helper.js。返回 `text/html`。当不存在 `.html` 文件时，提供一个硬编码的等待页面（"等待 Claude 推送屏幕..."）并注入 helper.js。
+2. **`GET /files/*`** —— 从屏幕目录提供静态文件，使用硬编码的扩展名映射（html、css、js、png、jpg、gif、svg、json）查找 MIME 类型。如果未找到则返回 404。
+3. **其他所有请求** —— 404。
+
+WebSocket 升级通过 HTTP 服务器上的 `'upgrade'` 事件处理，与请求处理器分开。
+
+### 配置
+
+环境变量（全部可选）：
+
+* `BRAINSTORM_PORT` —— 绑定的端口（默认：随机高端口 49152-65535）
+* `BRAINSTORM_HOST` —— 绑定的接口（默认：`127.0.0.1`）
+* `BRAINSTORM_URL_HOST` —— 启动 JSON 中 URL 的主机名（默认：当主机为 `127.0.0.1` 时为 `localhost`，否则与主机相同）
+* `BRAINSTORM_DIR` —— 屏幕目录路径（默认：`/tmp/brainstorm`）
+
+### 启动顺序
+
+1. 如果不存在则创建 `SCREEN_DIR`（`mkdirSync` 递归）
+2. 从 `__dirname` 加载框架模板和 helper.js
+3. 在配置的主机/端口上启动 HTTP 服务器
+4. 在 `SCREEN_DIR` 上启动 `fs.watch`
+5. 成功监听后，将 `server-started` JSON 记录到 stdout：`{ type, port, host, url_host, url, screen_dir }`
+6. 将相同的 JSON 写入 `SCREEN_DIR/.server-info`，以便在 stdout 被隐藏时（后台执行）代理可以找到连接详细信息
+
+### 应用层 WebSocket 消息
+
+当从客户端收到 TEXT 帧时：
+
+1. 解析为 JSON。如果解析失败，记录到 stderr 并继续。
+2. 记录到 stdout 为 `{ source: 'user-event', ...event }`。
+3. 如果事件包含 `choice` 属性，则将 JSON 追加到 `SCREEN_DIR/.events`（每个事件一行）。
+
+### 文件监视
+
+`fs.watch(SCREEN_DIR)` 替换 chokidar。在 HTML 文件事件上：
+
+* 新文件时（存在文件的 `rename` 事件）：如果存在则删除 `.events` 文件（`unlinkSync`），将 `screen-added` 记录到 stdout 为 JSON
+* 文件更改时（`change` 事件）：将 `screen-updated` 记录到 stdout 为 JSON（不 清除 `.events`）
+* 两个事件：将 `{ type: 'reload' }` 发送给所有连接的 WebSocket 客户端
+
+使用约 100 毫秒的超时按文件名进行防抖，以防止重复事件（在 macOS 和 Linux 上常见）。
+
+### 错误处理
+
+* WebSocket 客户端的格式错误 JSON：记录到 stderr，继续
+* 未处理的操作码：关闭并返回状态 1003
+* 客户端断开连接：从广播集合中移除
+* `fs.watch` 错误：记录到 stderr，继续
+* 没有优雅关闭逻辑 —— shell 脚本通过 SIGTERM 处理进程生命周期
+
+## 变更内容
+
+| 之前 | 之后 |
+|---|---|
+| `index.js` + `package.json` + `package-lock.json` + 714 个 `node_modules` 文件 | `server.js`（单个文件） |
+| express、ws、chokidar 依赖项 | 无 |
+| 无静态文件服务 | `/files/*` 从屏幕目录提供服务 |
+
+## 保持不变的内容
+
+* `helper.js` —— 无更改
+* `frame-template.html` —— 无更改
+* `start-server.sh` —— 单行更新：`index.js` 改为 `server.js`
+* `stop-server.sh` —— 无更改
+* `visual-companion.md` —— 无更改
+* 所有现有的服务器行为和外部契约
+
+## 平台兼容性
+
+* `server.js` 仅使用跨平台的 Node 内置模块
+* `fs.watch` 在 macOS、Linux 和 Windows 上对于单个扁平目录是可靠的
+* Shell 脚本需要 bash（Windows 上需要 Git Bash，这是 Claude Code 的要求）
+
+## 测试
+
+**单元测试**（`ws-protocol.test.js`）：通过引用 `server.js` 导出的函数，直接测试 WebSocket 帧编码/解码、握手计算和协议边缘情况。
+
+**集成测试**（`server.test.js`）：测试完整的服务器行为 —— HTTP 服务、WebSocket 通信、文件监视、头脑风暴工作流。使用 `ws` npm 包作为仅测试的客户端依赖项（不交付给最终用户）。
diff --git a/zh-CN/docs/testing.md b/zh-CN/docs/testing.md
new file mode 100644
index 0000000000..f543d9ce4e
--- /dev/null
+++ b/zh-CN/docs/testing.md
@@ -0,0 +1,307 @@
+# 测试 Superpowers 技能
+
+本文档描述了如何测试 Superpowers 技能，特别是针对像 `subagent-driven-development` 这样的复杂技能的集成测试。
+
+## 概述
+
+测试涉及子代理、工作流和复杂交互的技能，需要在无头模式下运行实际的 Claude Code 会话，并通过会话记录验证其行为。
+
+## 测试结构
+
+```
+tests/
+├── claude-code/
+│   ├── test-helpers.sh                    # 共享测试工具
+│   ├── test-subagent-driven-development-integration.sh
+│   ├── analyze-token-usage.py             # Token 分析工具
+│   └── run-skill-tests.sh                 # 测试运行器（如果存在）
+```
+
+## 运行测试
+
+### 集成测试
+
+集成测试使用实际技能执行真实的 Claude Code 会话：
+
+```bash
+# Run the subagent-driven-development integration test
+cd tests/claude-code
+./test-subagent-driven-development-integration.sh
+```
+
+**注意：** 集成测试可能需要 10-30 分钟，因为它们会执行包含多个子代理的真实实施计划。
+
+### 要求
+
+* 必须从 **superpowers 插件目录** 运行（不能从临时目录运行）
+* 必须安装 Claude Code 并且可以作为 `claude` 命令使用
+* 必须启用本地开发市场：在 `~/.claude/settings.json` 中设置 `"superpowers@superpowers-dev": true`
+
+## 集成测试：subagent-driven-development
+
+### 测试内容
+
+该集成测试验证 `subagent-driven-development` 技能是否正确：
+
+1. **计划加载**：在开始时读取一次计划
+2. **完整任务文本**：向子代理提供完整的任务描述（不让它们读取文件）
+3. **自我审查**：确保子代理在报告前进行自我审查
+4. **审查顺序**：在代码质量审查之前运行规范合规性审查
+5. **审查循环**：发现问题时使用审查循环
+6. **独立验证**：规范审查员独立阅读代码，不信任实施者的报告
+
+### 工作原理
+
+1. **设置**：创建一个包含最小实施计划的临时 Node.js 项目
+2. **执行**：在无头模式下使用该技能运行 Claude Code
+3. **验证**：解析会话记录（`.jsonl` 文件）以验证：
+   * 技能工具被调用
+   * 子代理被分派（任务工具）
+   * 使用了 TodoWrite 进行跟踪
+   * 创建了实现文件
+   * 测试通过
+   * Git 提交显示了正确的工作流程
+4. **令牌分析**：显示按子代理划分的令牌使用情况细分
+
+### 测试输出
+
+```
+========================================
+ 集成测试：subagent-driven-development
+========================================
+
+测试项目：/tmp/tmp.xyz123
+
+=== 验证测试 ===
+
+测试 1：技能工具被调用...
+  [通过] subagent-driven-development 技能被调用
+
+测试 2：子代理已分派...
+  [通过] 7 个子代理已分派
+
+测试 3：任务跟踪...
+  [通过] TodoWrite 被使用 5 次
+
+测试 6：实现验证...
+  [通过] src/math.js 已创建
+  [通过] add 函数存在
+  [通过] multiply 函数存在
+  [通过] test/math.test.js 已创建
+  [通过] 测试通过
+
+测试 7：Git 提交历史...
+  [通过] 创建了多次提交（总计 3 次）
+
+测试 8：未添加额外功能...
+  [通过] 未添加额外功能
+
+=========================================
+ 令牌使用分析
+=========================================
+
+使用情况明细：
+----------------------------------------------------------------------------------------------------
+代理           描述                         消息数     输入      输出      缓存      成本
+----------------------------------------------------------------------------------------------------
+main           主会话（协调器）             34         27      3,996  1,213,703 $   4.09
+3380c209       实现任务 1：创建 Add 函数     1          2        787     24,989 $   0.09
+34b00fde       实现任务 2：创建 Multiply 函数 1          4        644     25,114 $   0.09
+3801a732       审查实现是否匹配...   1          5        703     25,742 $   0.09
+4c142934       进行最终代码审查...                    1          6        854     25,319 $   0.09
+5f017a42       代码审查员。审查任务 2...               1          6        504     22,949 $   0.08
+a6b7fbe4       代码审查员。审查任务 1...               1          6        515     22,534 $   0.08
+f15837c0       审查实现是否匹配...   1          6        416     22,485 $   0.07
+----------------------------------------------------------------------------------------------------
+
+总计：
+  总消息数：         41
+  输入令牌数：           62
+  输出令牌数：          8,419
+  缓存创建令牌数：  132,742
+  缓存读取令牌数：      1,382,835
+
+  总输入（含缓存）： 1,515,639
+  总令牌数：             1,524,058
+
+  估算成本： $4.67
+  （按每百万令牌输入/输出 $3/$15 计算）
+
+========================================
+ 测试摘要
+========================================
+
+状态：通过
+```
+
+## 令牌分析工具
+
+### 用法
+
+分析任何 Claude Code 会话的令牌使用情况：
+
+```bash
+python3 tests/claude-code/analyze-token-usage.py ~/.claude/projects/<project-dir>/<session-id>.jsonl
+```
+
+### 查找会话文件
+
+会话记录存储在 `~/.claude/projects/` 中，工作目录路径被编码：
+
+```bash
+# Example for /Users/jesse/Documents/GitHub/superpowers/superpowers
+SESSION_DIR="$HOME/.claude/projects/-Users-jesse-Documents-GitHub-superpowers-superpowers"
+
+# Find recent sessions
+ls -lt "$SESSION_DIR"/*.jsonl | head -5
+```
+
+### 显示内容
+
+* **主会话使用情况**：协调器（你或主 Claude 实例）的令牌使用情况
+* **每个子代理的细分**：每次任务调用包含：
+  * 代理 ID
+  * 描述（从提示中提取）
+  * 消息数量
+  * 输入/输出令牌
+  * 缓存使用情况
+  * 估算成本
+* **总计**：总体令牌使用情况和成本估算
+
+### 理解输出
+
+* **缓存读取率高**：良好 - 意味着提示缓存正在工作
+* **主会话输入令牌高**：预期 - 协调器拥有完整上下文
+* **每个子代理成本相似**：预期 - 每个子代理的任务复杂度相似
+* **每项任务成本**：根据任务不同，每个子代理的典型范围是 $0.05-$0.15
+
+## 故障排除
+
+### 技能未加载
+
+**问题**：运行无头测试时找不到技能
+
+**解决方案**：
+
+1. 确保你从 superpowers 目录运行：`cd /path/to/superpowers && tests/...`
+2. 检查 `~/.claude/settings.json` 在 `enabledPlugins` 中是否有 `"superpowers@superpowers-dev": true`
+3. 验证技能存在于 `skills/` 目录中
+
+### 权限错误
+
+**问题**：Claude 被阻止写入文件或访问目录
+
+**解决方案**：
+
+1. 使用 `--permission-mode bypassPermissions` 标志
+2. 使用 `--add-dir /path/to/temp/dir` 授予对测试目录的访问权限
+3. 检查测试目录的文件权限
+
+### 测试超时
+
+**问题**：测试耗时过长并超时
+
+**解决方案**：
+
+1. 增加超时时间：`timeout 1800 claude ...`（30 分钟）
+2. 检查技能逻辑中是否存在无限循环
+3. 检查子代理任务的复杂性
+
+### 找不到会话文件
+
+**问题**：测试运行后找不到会话记录
+
+**解决方案**：
+
+1. 检查 `~/.claude/projects/` 中正确的项目目录
+2. 使用 `find ~/.claude/projects -name "*.jsonl" -mmin -60` 查找最近的会话
+3. 验证测试是否实际运行（检查测试输出中的错误）
+
+## 编写新的集成测试
+
+### 模板
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+# Create test project
+TEST_PROJECT=$(create_test_project)
+trap "cleanup_test_project $TEST_PROJECT" EXIT
+
+# Set up test files...
+cd "$TEST_PROJECT"
+
+# Run Claude with skill
+PROMPT="Your test prompt here"
+cd "$SCRIPT_DIR/../.." && timeout 1800 claude -p "$PROMPT" \
+  --allowed-tools=all \
+  --add-dir "$TEST_PROJECT" \
+  --permission-mode bypassPermissions \
+  2>&1 | tee output.txt
+
+# Find and analyze session
+WORKING_DIR_ESCAPED=$(echo "$SCRIPT_DIR/../.." | sed 's/\\//-/g' | sed 's/^-//')
+SESSION_DIR="$HOME/.claude/projects/$WORKING_DIR_ESCAPED"
+SESSION_FILE=$(find "$SESSION_DIR" -name "*.jsonl" -type f -mmin -60 | sort -r | head -1)
+
+# Verify behavior by parsing session transcript
+if grep -q '"name":"Skill".*"skill":"your-skill-name"' "$SESSION_FILE"; then
+    echo "[PASS] Skill was invoked"
+fi
+
+# Show token analysis
+python3 "$SCRIPT_DIR/analyze-token-usage.py" "$SESSION_FILE"
+```
+
+### 最佳实践
+
+1. **始终清理**：使用 trap 清理临时目录
+2. **解析记录**：不要 grep 面向用户的输出 - 解析 `.jsonl` 会话文件
+3. **授予权限**：使用 `--permission-mode bypassPermissions` 和 `--add-dir`
+4. **从插件目录运行**：只有从 superpowers 目录运行时才会加载技能
+5. **显示令牌使用情况**：始终包含令牌分析以了解成本
+6. **测试真实行为**：验证实际创建的文件、通过的测试、进行的提交
+
+## 会话记录格式
+
+会话记录是 JSONL（JSON Lines）文件，其中每一行都是一个代表消息或工具结果的 JSON 对象。
+
+### 关键字段
+
+```json
+{
+  "type": "assistant",
+  "message": {
+    "content": [...],
+    "usage": {
+      "input_tokens": 27,
+      "output_tokens": 3996,
+      "cache_read_input_tokens": 1213703
+    }
+  }
+}
+```
+
+### 工具结果
+
+```json
+{
+  "type": "user",
+  "toolUseResult": {
+    "agentId": "3380c209",
+    "usage": {
+      "input_tokens": 2,
+      "output_tokens": 787,
+      "cache_read_input_tokens": 24989
+    },
+    "prompt": "You are implementing Task 1...",
+    "content": [{"type": "text", "text": "..."}]
+  }
+}
+```
+
+`agentId` 字段链接到子代理会话，`usage` 字段包含该特定子代理调用的令牌使用情况。
diff --git a/zh-CN/docs/windows/polyglot-hooks.md b/zh-CN/docs/windows/polyglot-hooks.md
new file mode 100644
index 0000000000..82310a037f
--- /dev/null
+++ b/zh-CN/docs/windows/polyglot-hooks.md
@@ -0,0 +1,227 @@
+# Claude Code 的跨平台多语言钩子
+
+Claude Code 插件需要能在 Windows、macOS 和 Linux 上工作的钩子。本文档解释了实现这一点的多语言包装器技术。
+
+## 问题所在
+
+Claude Code 通过系统的默认 shell 运行钩子命令：
+
+* **Windows**: CMD.exe
+* **macOS/Linux**: bash 或 sh
+
+这带来了几个挑战：
+
+1. **脚本执行**：Windows CMD 无法直接执行 `.sh` 文件——它会尝试在文本编辑器中打开它们
+2. **路径格式**：Windows 使用反斜杠 (`C:\path`)，Unix 使用正斜杠 (`/path`)
+3. **环境变量**：`$VAR` 语法在 CMD 中无效
+4. **PATH 中没有 `bash`**：即使安装了 Git Bash，当 CMD 运行时，`bash` 也不在 PATH 中
+
+## 解决方案：多语言 `.cmd` 包装器
+
+多语言脚本是指同时是多种语言的有效语法。我们的包装器在 CMD 和 bash 中均有效：
+
+```cmd
+: << 'CMDBLOCK'
+@echo off
+"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+```
+
+### 工作原理
+
+#### 在 Windows 上 (CMD.exe)
+
+1. `: << 'CMDBLOCK'` - CMD 将 `:` 视为标签（类似 `:label`）并忽略 `<< 'CMDBLOCK'`
+2. `@echo off` - 抑制命令回显
+3. bash.exe 命令以如下方式运行：
+   * `-l`（登录 shell）以获取包含 Unix 工具的正确 PATH
+   * `cygpath -u` 将 Windows 路径转换为 Unix 格式 (`C:\foo` → `/c/foo`)
+4. `exit /b` - 退出批处理脚本，在此处停止 CMD
+5. `CMDBLOCK` 之后的所有内容 CMD 都不会执行到
+
+#### 在 Unix 上 (bash/sh)
+
+1. `: << 'CMDBLOCK'` - `:` 是无操作，`<< 'CMDBLOCK'` 开始一个 heredoc
+2. 直到 `CMDBLOCK` 的所有内容都被 heredoc 消耗（忽略）
+3. `# Unix shell runs from here` - 注释
+4. 脚本直接使用 Unix 路径运行
+
+## 文件结构
+
+```
+hooks/
+├── hooks.json           # 指向 .cmd 包装器
+├── session-start.cmd    # 多语言包装器（跨平台入口点）
+└── session-start.sh     # 实际钩子逻辑（bash 脚本）
+```
+
+### hooks.json
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+注意：路径必须用引号括起来，因为 `${CLAUDE_PLUGIN_ROOT}` 在 Windows 上可能包含空格（例如 `C:\Program Files\...`）。
+
+## 要求
+
+### Windows
+
+* 必须安装 **Git for Windows**（提供 `bash.exe` 和 `cygpath`）
+* 默认安装路径：`C:\Program Files\Git\bin\bash.exe`
+* 如果 Git 安装在其他位置，则需要修改包装器
+
+### Unix (macOS/Linux)
+
+* 标准的 bash 或 sh shell
+* `.cmd` 文件必须具有执行权限 (`chmod +x`)
+
+## 编写跨平台钩子脚本
+
+你的实际钩子逻辑放在 `.sh` 文件中。为确保它在 Windows 上（通过 Git Bash）工作：
+
+### 应该做：
+
+* 尽可能使用纯 bash 内置命令
+* 使用 `$(command)` 而不是反引号
+* 引用所有变量扩展：`"$VAR"`
+* 使用 `printf` 或 here-docs 进行输出
+
+### 应避免：
+
+* PATH 中可能没有的外部命令（sed、awk、grep）
+* 如果必须使用它们，它们在 Git Bash 中可用，但要确保 PATH 已设置（使用 `bash -l`）
+
+### 示例：不使用 sed/awk 的 JSON 转义
+
+替代方案：
+
+```bash
+escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+```
+
+使用纯 bash：
+
+```bash
+escape_for_json() {
+    local input="$1"
+    local output=""
+    local i char
+    for (( i=0; i<${#input}; i++ )); do
+        char="${input:$i:1}"
+        case "$char" in
+            $'\\') output+='\\' ;;
+            '"') output+='\"' ;;
+            $'\n') output+='\n' ;;
+            $'\r') output+='\r' ;;
+            $'\t') output+='\t' ;;
+            *) output+="$char" ;;
+        esac
+    done
+    printf '%s' "$output"
+}
+```
+
+## 可复用的包装器模式
+
+对于具有多个钩子的插件，可以创建一个通用包装器，将脚本名称作为参数：
+
+### run-hook.cmd
+
+```cmd
+: << 'CMDBLOCK'
+@echo off
+set "SCRIPT_DIR=%~dp0"
+set "SCRIPT_NAME=%~1"
+"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+```
+
+### 使用可复用包装器的 hooks.json
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 故障排除
+
+### "bash 无法识别"
+
+CMD 找不到 bash。包装器使用完整路径 `C:\Program Files\Git\bin\bash.exe`。如果 Git 安装在其他位置，请更新路径。
+
+### "cygpath: 命令未找到" 或 "dirname: 命令未找到"
+
+Bash 没有作为登录 shell 运行。确保使用了 `-l` 标志。
+
+### 路径中有奇怪的 `\/`
+
+`${CLAUDE_PLUGIN_ROOT}` 扩展为以反斜杠结尾的 Windows 路径，然后附加了 `/hooks/...`。使用 `cygpath` 转换整个路径。
+
+### 脚本在文本编辑器中打开而不是运行
+
+hooks.json 直接指向了 `.sh` 文件。应指向 `.cmd` 包装器。
+
+### 在终端中工作，但作为钩子不工作
+
+Claude Code 可能以不同方式运行钩子。通过模拟钩子环境进行测试：
+
+```powershell
+$env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
+cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
+```
+
+## 相关问题
+
+* [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - Windows 上 .sh 脚本在编辑器中打开
+* [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Windows 上钩子不工作
+* [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - 找不到 CLAUDE\_PROJECT\_DIR
diff --git a/zh-CN/skills/brainstorming/SKILL.md b/zh-CN/skills/brainstorming/SKILL.md
new file mode 100644
index 0000000000..bb99ea12de
--- /dev/null
+++ b/zh-CN/skills/brainstorming/SKILL.md
@@ -0,0 +1,165 @@
+---
+name: brainstorming
+description: "在进行任何创意工作之前，您必须使用此方法——无论是创建功能、构建组件、增加功能还是修改行为。在实施之前，探索用户意图、需求和设计。"
+---
+
+# 将构思转化为设计
+
+通过自然的协作对话，帮助将想法转化为完整的设计和规格说明。
+
+首先了解当前项目背景，然后逐一提问以完善想法。一旦明确要构建什么，便呈现设计并获得用户批准。
+
+<HARD-GATE>
+在展示设计并获得用户批准之前，切勿调用任何实现技能、编写任何代码、搭建任何项目或采取任何实现行动。无论项目看起来多么简单，这都适用于每一个项目。
+</HARD-GATE>
+
+## 反模式：“这太简单了，不需要设计”
+
+每个项目都会经历这个过程。待办事项列表、单功能工具、配置更改——所有这些都是如此。“简单”的项目正是未经验证的假设导致最多无用功的地方。设计可以简短（对于真正简单的项目，几句话即可），但你必须呈现它并获得批准。
+
+## 检查清单
+
+你必须为以下每一项创建任务，并按顺序完成：
+
+1. **探索项目背景** — 检查文件、文档、近期提交记录
+2. **提供视觉辅助**（如果主题涉及视觉问题）— 这是独立的消息，不与澄清问题合并。请参阅下方的视觉辅助部分。
+3. **提出澄清问题** — 一次一个，理解目的/约束/成功标准
+4. **提出2-3种方案** — 包括权衡利弊和你的建议
+5. **呈现设计** — 按复杂度分节呈现，每节后获取用户批准
+6. **撰写设计文档** — 保存至 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 并提交
+7. **规范评审循环** — 派遣规范文档评审子代理，附带精确构建的评审上下文（切勿使用你的会话历史）；修复问题并重新派遣直至批准（最多3次迭代，然后提交给人工处理）
+8. **用户评审书面规范** — 请用户在继续前评审规范文件
+9. **过渡到实施阶段** — 调用写作计划技能以创建实施计划
+
+## 流程
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message, no other content)" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec review loop" [shape=box];
+    "Spec review passed?" [shape=diamond];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Visual questions ahead?";
+    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
+    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
+    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec review loop";
+    "Spec review loop" -> "Spec review passed?";
+    "Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
+    "Spec review passed?" -> "User reviews spec?" [label="approved"];
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
+}
+```
+
+**终端状态是调用 writing-plans。** 在头脑风暴之后，请勿调用 frontend-design、mcp-builder 或任何其他实施技能。头脑风暴后调用的唯一技能是 writing-plans。
+
+## 流程详解
+
+**理解想法：**
+
+* 首先查看当前项目状态（文件、文档、最近的提交记录）
+* 在提出详细问题之前，评估范围：如果请求描述了多个独立的子系统（例如，“构建一个包含聊天、文件存储、计费和数据分析的平台”），请立即指出这一点。不要花费问题去细化一个需要首先分解的项目细节。
+* 如果项目对于单个规格来说太大，帮助用户分解为子项目：哪些是独立的部分，它们如何关联，应该按什么顺序构建？然后通过正常的设计流程对第一个子项目进行头脑风暴。每个子项目都有自己的规格 → 计划 → 实施周期。
+* 对于范围合适的项目，逐一提问以完善想法
+* 可能的情况下，优先使用多项选择题，但开放式问题也可以
+* 每条消息只提一个问题 - 如果一个主题需要更多探索，将其分解为多个问题
+* 专注于理解：目的、约束、成功标准
+
+**探索方案：**
+
+* 提出 2-3 种不同的方案，附带权衡分析
+* 以对话方式呈现选项，并给出你的建议和理由
+* 首先介绍你推荐的选项并解释原因
+
+**呈现设计：**
+
+* 一旦确信理解了要构建什么，便呈现设计
+* 根据复杂性调整每个章节：如果直接明了，几句话即可；如果复杂，最多 200-300 字
+* 在每个章节后询问是否看起来正确
+* 涵盖：架构、组件、数据流、错误处理、测试
+* 准备好返回澄清任何不清楚的地方
+
+**为隔离性和清晰性而设计：**
+
+* 将系统分解为更小的单元，每个单元都有一个明确的目的，通过定义良好的接口进行通信，并且可以独立理解和测试
+* 对于每个单元，你应该能够回答：它做什么，如何使用它，以及它依赖什么？
+* 是否有人无需阅读其内部实现就能理解一个单元的功能？是否可以在不破坏消费者的情况下更改其内部实现？如果不能，那么边界需要改进。
+* 更小、边界清晰的单元也更容易让你处理——你能更好地推理那些可以一次性把握上下文的代码，并且当文件聚焦时，你的编辑更可靠。当一个文件变得庞大时，这通常是它承担过多职责的信号。
+
+**在现有代码库中工作：**
+
+* 在提出更改之前，探索当前结构。遵循现有模式。
+* 如果现有代码存在影响当前工作的问题（例如，文件变得过于庞大、边界不清晰、职责纠缠），将有针对性的改进作为设计的一部分——就像优秀的开发人员会改进他们正在工作的代码一样。
+* 不要提出无关的重构。专注于服务于当前目标的内容。
+
+## 设计之后
+
+**文档：**
+
+* 将验证过的设计（规格）写入 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  * （用户对规格文件位置的偏好会覆盖此默认设置）
+* 如果可用，使用 elements-of-style:writing-clearly-and-concisely 技能
+* 将设计文档提交到 git
+
+**规格审查循环：**
+编写规格文档后：
+
+1. 派遣规范文档评审子代理（参见 spec-document-reviewer-prompt.md）
+2. 如果发现问题：修复、重新派遣、重复直至批准
+3. 如果循环超过3次迭代，提交给人工指导
+
+**用户审查关卡：**
+在规格审查循环通过后，请用户在继续之前审查书面规格：
+
+> “规格已编写并提交到 `<path>`。请在开始编写实施计划之前审查它，并告知是否需要进行任何更改。”
+
+等待用户的回应。如果他们要求更改，进行更改并重新运行规格审查循环。只有在用户批准后才继续。
+
+**实施：**
+
+* 调用 writing-plans 技能来创建详细的实施计划
+* 请勿调用任何其他技能。writing-plans 是下一步。
+
+## 关键原则
+
+* **一次一个问题** —— 不要用多个问题压倒对方
+* **优先多项选择** —— 可能的情况下，比开放式问题更容易回答
+* **无情地应用 YAGNI** —— 从所有设计中移除不必要的功能
+* **探索替代方案** —— 在确定方案前，始终提出 2-3 种方法
+* **增量验证** —— 呈现设计，获得批准后再继续
+* **保持灵活** —— 当某些内容不清楚时，返回澄清
+
+## 视觉辅助工具
+
+一个基于浏览器的辅助工具，用于在头脑风暴期间展示线框图、图表和视觉选项。作为工具提供——而非模式。接受辅助工具意味着它可用于那些受益于视觉处理的问题；这并不意味着每个问题都要通过浏览器处理。
+
+**提供辅助工具：** 当你预期即将到来的问题会涉及视觉内容（线框图、布局、图表）时，为征求同意提供一次：
+
+> “我们正在处理的一些内容，如果能通过网页浏览器向你展示，可能会更容易解释。我可以随时准备线框图、图表、比较和其他视觉效果。这个功能还比较新，可能会消耗较多 token。想试试吗？（需要打开本地 URL）”
+
+**此提议必须是独立的消息。** 不要将其与澄清问题、背景摘要或任何其他内容合并。消息应仅包含上述提议，别无其他。在继续之前等待用户的回应。如果他们拒绝，则继续进行纯文本头脑风暴。
+
+**按问题决定：** 即使用户接受了，也要为每个问题决定是使用浏览器还是终端。判断标准是：**用户通过看到它比通过阅读它更能理解吗？**
+
+* **使用浏览器** 处理**是**视觉的内容 —— 线框图、布局比较、架构图、并排视觉设计
+* **使用终端** 处理文本内容 —— 需求问题、概念选择、权衡列表、A/B/C/D 文本选项、范围决策
+
+关于 UI 主题的问题不自动成为视觉问题。“在这种情况下，‘个性’意味着什么？”是一个概念问题——使用终端。“哪个向导布局效果更好？”是一个视觉问题——使用浏览器。
+
+如果他们同意使用辅助工具，请在继续之前阅读详细指南：
+`skills/brainstorming/visual-companion.md`
diff --git a/zh-CN/skills/brainstorming/spec-document-reviewer-prompt.md b/zh-CN/skills/brainstorming/spec-document-reviewer-prompt.md
new file mode 100644
index 0000000000..7aa8c1b84c
--- /dev/null
+++ b/zh-CN/skills/brainstorming/spec-document-reviewer-prompt.md
@@ -0,0 +1,47 @@
+# 规范文档评审提示模板
+
+在调度规范文档评审子代理时使用此模板。
+
+**目的：** 验证规范是否完整、一致，并准备好进行实施规划。
+
+**调度时机：** 规范文档已编写至 docs/superpowers/specs/
+
+```
+任务工具（通用）：
+  描述："审查规范文档"
+  提示：|
+    你是一名规范文档审查员。请验证此规范是否完整并已准备好进行规划。
+
+    **待审查规范：** [SPEC_FILE_PATH]
+
+    ## 检查内容
+
+    | 类别 | 检查要点 |
+    |----------|------------------|
+    | 完整性 | TODOs、占位符、"TBD"、不完整的部分 |
+    | 一致性 | 内部矛盾、冲突的需求 |
+    | 清晰度 | 可能导致构建错误产物的模糊需求 |
+    | 范围 | 是否足够专注于单一计划——未涵盖多个独立的子系统 |
+    | YAGNI | 未请求的功能、过度设计 |
+
+    ## 校准标准
+
+    **仅标记在实施规划过程中会导致实际问题的问题。**
+    缺失的部分、矛盾之处，或可能被两种不同方式解释的模糊需求——这些是问题。次要的措辞改进、风格偏好以及"部分细节不如其他部分详细"则不视为问题。
+
+    除非存在会导致计划缺陷的严重空白，否则予以批准。
+
+    ## 输出格式
+
+    ## 规范审查
+
+    **状态：** 已批准 | 发现问题
+
+    **问题（如有）：**
+    - [部分 X]：[具体问题] - [为何对规划重要]
+
+    **建议（咨询性质，不阻止批准）：**
+    - [改进建议]
+```
+
+**评审员返回：** 状态、问题（如有）、建议
diff --git a/zh-CN/skills/brainstorming/visual-companion.md b/zh-CN/skills/brainstorming/visual-companion.md
new file mode 100644
index 0000000000..5cf2c83de8
--- /dev/null
+++ b/zh-CN/skills/brainstorming/visual-companion.md
@@ -0,0 +1,291 @@
+# 视觉伴侣指南
+
+基于浏览器的可视化头脑风暴伴侣，用于展示原型图、图表和选项。
+
+## 何时使用
+
+按问题决定，而非按会话决定。判断标准是：**用户通过观看是否比阅读能更好地理解此内容？**
+
+**使用浏览器** 当内容本身是视觉化的：
+
+* **UI 原型图** — 线框图、布局、导航结构、组件设计
+* **架构图** — 系统组件、数据流、关系图
+* **并排视觉比较** — 比较两种布局、两种配色方案、两种设计方向
+* **设计精修** — 当问题涉及外观、间距、视觉层次时
+* **空间关系** — 状态机、流程图、以图表形式呈现的实体关系
+
+**使用终端** 当内容是文本或表格时：
+
+* **需求和范围问题** — “X 是什么意思？”、“哪些功能在范围内？”
+* **概念性 A/B/C 选择** — 在文字描述的方法之间进行选择
+* **权衡列表** — 利弊、比较表
+* **技术决策** — API 设计、数据建模、架构方法选择
+* **澄清性问题** — 任何答案是文字而非视觉偏好的情况
+
+一个 *关于* UI 主题的问题并不自动成为视觉问题。“你想要哪种向导？”是概念性的——使用终端。“这些向导布局中哪个感觉合适？”是视觉性的——使用浏览器。
+
+## 工作原理
+
+服务器监视一个目录中的 HTML 文件，并将最新的文件提供给浏览器。您编写 HTML 内容，用户在浏览器中查看并可以点击选择选项。选择记录到 `.events` 文件中，您在下一轮可以读取。
+
+**内容片段与完整文档：** 如果您的 HTML 文件以 `<!DOCTYPE` 或 `<html` 开头，服务器会按原样提供（仅注入辅助脚本）。否则，服务器会自动将您的内容包装在框架模板中——添加页眉、CSS 主题、选择指示器以及所有交互式基础设施。**默认编写内容片段。** 仅在需要完全控制页面时才编写完整文档。
+
+## 启动会话
+
+```bash
+# Start server with persistence (mockups saved to project)
+scripts/start-server.sh --project-dir /path/to/project
+
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000"}
+```
+
+从响应中保存 `screen_dir`。告诉用户打开 URL。
+
+**查找连接信息：** 服务器将其启动 JSON 写入 `$SCREEN_DIR/.server-info`。如果您在后台启动了服务器且未捕获 stdout，请读取该文件以获取 URL 和端口。使用 `--project-dir` 时，检查 `<project>/.superpowers/brainstorm/` 以获取会话目录。
+
+**注意：** 将项目根目录作为 `--project-dir` 传递，以便原型图持久保存在 `.superpowers/brainstorm/` 中并在服务器重启后保留。没有它，文件会进入 `/tmp` 并被清理。如果 `.superpowers/` 尚未存在，请提醒用户将其添加到 `.gitignore`。
+
+**按平台启动服务器：**
+
+**Claude Code (macOS / Linux):**
+
+```bash
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Claude Code (Windows):**
+
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+通过 Bash 工具调用时，请设置 `run_in_background: true`。然后在下一轮读取 `$SCREEN_DIR/.server-info` 以获取 URL 和端口。
+
+**Codex：**
+
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI：**
+
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**其他环境：** 服务器必须在对话轮次之间持续在后台运行。如果您的环境回收分离的进程，请使用 `--foreground` 并使用您平台的背景执行机制启动命令。
+
+如果 URL 无法从您的浏览器访问（在远程/容器化设置中常见），请绑定非环回主机：
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+使用 `--url-host` 来控制返回的 URL JSON 中打印的主机名。
+
+## 循环流程
+
+1. **检查服务器是否存活**，然后**将 HTML 写入** `screen_dir` 中的新文件：
+   * 每次写入前，检查 `$SCREEN_DIR/.server-info` 是否存在。如果不存在（或 `.server-stopped` 存在），则服务器已关闭——在继续之前使用 `start-server.sh` 重新启动它。服务器在 30 分钟不活动后自动退出。
+   * 使用语义化文件名：`platform.html`、`visual-style.html`、`layout.html`
+   * **切勿重复使用文件名**——每个屏幕使用一个新文件
+   * 使用 Write 工具——**切勿使用 cat/heredoc**（会在终端中产生噪音）
+   * 服务器自动提供最新的文件
+
+2. **告诉用户预期结果并结束您的回合：**
+   * 提醒他们 URL（每一步都要提醒，不仅仅是第一步）
+   * 简要总结屏幕上的内容（例如，“显示首页的 3 种布局选项”）
+   * 要求他们在终端中回复：“看一下，告诉我你的想法。如果愿意，请点击选择一个选项。”
+
+3. **在您的下一回合**——用户在终端中回复后：
+   * 如果存在，读取 `$SCREEN_DIR/.events`——这包含用户的浏览器交互（点击、选择）作为 JSON 行
+   * 与用户的终端文本合并，以获得完整情况
+   * 终端消息是主要反馈；`.events` 提供结构化的交互数据
+
+4. **迭代或推进**——如果反馈改变了当前屏幕，则写入一个新文件（例如 `layout-v2.html`）。仅当当前步骤得到验证后才进入下一个问题。
+
+5. **返回终端时卸载**——当下一步不需要浏览器时（例如，澄清性问题、权衡讨论），推送一个等待屏幕以清除陈旧内容：
+
+   ```html
+   <!-- filename: waiting.html (或 waiting-2.html 等) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">继续在终端中...</p>
+   </div>
+   ```
+
+   这可以防止用户在对话已继续进行时盯着已解决的选项。当下一个视觉问题出现时，照常推送新的内容文件。
+
+6. 重复直到完成。
+
+## 编写内容片段
+
+仅编写页面内部的内容。服务器会自动将其包装在框架模板中（页眉、主题 CSS、选择指示器以及所有交互式基础设施）。
+
+**最小示例：**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+就这样。不需要 `<html>`、CSS 或 `<script>` 标签。服务器提供所有这些。
+
+## 可用的 CSS 类
+
+框架模板为您的内容提供以下 CSS 类：
+
+### 选项（A/B/C 选择）
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**多选：** 向容器添加 `data-multiselect` 以允许用户选择多个选项。每次点击切换项目。指示条显示计数。
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### 卡片（视觉设计）
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### 原型图容器
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### 分屏视图（并排）
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### 利弊分析
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### 模拟元素（线框图构建块）
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### 排版和版块
+
+* `h2` — 页面标题
+* `h3` — 版块标题
+* `.subtitle` — 标题下方的辅助文本
+* `.section` — 带底部边距的内容块
+* `.label` — 小型大写标签文本
+
+## 浏览器事件格式
+
+当用户在浏览器中点击选项时，他们的交互记录到 `$SCREEN_DIR/.events`（每行一个 JSON 对象）。当您推送新屏幕时，该文件会自动清除。
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+完整的事件流显示了用户的探索路径——他们可能在确定前点击了多个选项。最后的 `choice` 事件通常是最终选择，但点击模式可能揭示值得询问的犹豫或偏好。
+
+如果 `.events` 不存在，则用户没有与浏览器交互——仅使用他们的终端文本。
+
+## 设计技巧
+
+* **根据问题调整保真度**——布局用线框图，精修问题用精修设计
+* **在每个页面上解释问题**——“哪种布局感觉更专业？”而不仅仅是“选一个”
+* **在推进前迭代**——如果反馈改变了当前屏幕，则编写新版本
+* **每屏最多 2-4 个选项**
+* **在重要时使用真实内容**——对于摄影作品集，使用实际图像（Unsplash）。占位符内容会掩盖设计问题。
+* **保持原型图简洁**——专注于布局和结构，而非像素级完美的设计
+
+## 文件命名
+
+* 使用语义化名称：`platform.html`、`visual-style.html`、`layout.html`
+* 切勿重复使用文件名——每个屏幕必须是新文件
+* 对于迭代：附加版本后缀，如 `layout-v2.html`、`layout-v3.html`
+* 服务器按修改时间提供最新文件
+
+## 清理
+
+```bash
+scripts/stop-server.sh $SCREEN_DIR
+```
+
+如果会话使用了 `--project-dir`，原型图文件将持久保存在 `.superpowers/brainstorm/` 中以供日后参考。只有 `/tmp` 会话会在停止时被删除。
+
+## 参考
+
+* 框架模板（CSS 参考）：`scripts/frame-template.html`
+* 辅助脚本（客户端）：`scripts/helper.js`
diff --git a/zh-CN/skills/dispatching-parallel-agents/SKILL.md b/zh-CN/skills/dispatching-parallel-agents/SKILL.md
new file mode 100644
index 0000000000..0c0657155e
--- /dev/null
+++ b/zh-CN/skills/dispatching-parallel-agents/SKILL.md
@@ -0,0 +1,193 @@
+---
+name: dispatching-parallel-agents
+description: 当面对两个或更多独立任务，且这些任务可以在没有共享状态或顺序依赖的情况下工作时使用
+---
+
+# 调度并行智能体
+
+## 概述
+
+您将任务委派给具有隔离上下文的专业智能体。通过精心设计它们的指令和上下文，确保它们保持专注并成功完成任务。它们绝不应继承您会话的上下文或历史记录——您精确地构建它们所需的一切。这也有助于保留您自己的上下文以进行协调工作。
+
+当您遇到多个不相关的故障（不同的测试文件、不同的子系统、不同的错误）时，按顺序调查它们会浪费时间。每项调查都是独立的，可以并行进行。
+
+**核心原则：** 为每个独立的问题领域调度一个智能体。让它们并发工作。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**在以下情况使用：**
+
+* 3个以上测试文件因不同的根本原因而失败
+* 多个子系统独立损坏
+* 每个问题无需其他问题的上下文即可理解
+* 调查之间没有共享状态
+
+**不要在以下情况使用：**
+
+* 故障是相关的（修复一个可能修复其他）
+* 需要理解完整的系统状态
+* 智能体会相互干扰
+
+## 模式
+
+### 1. 识别独立领域
+
+按损坏内容对故障进行分组：
+
+* 文件 A 测试：工具审批流程
+* 文件 B 测试：批处理完成行为
+* 文件 C 测试：中止功能
+
+每个领域都是独立的——修复工具审批不会影响中止测试。
+
+### 2. 创建专注的智能体任务
+
+每个智能体获得：
+
+* **特定范围：** 一个测试文件或子系统
+* **明确目标：** 使这些测试通过
+* **约束：** 不要更改其他代码
+* **预期输出：** 发现和修复的内容摘要
+
+### 3. 并行调度
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. 审查与集成
+
+当智能体返回时：
+
+* 阅读每个摘要
+* 验证修复没有冲突
+* 运行完整的测试套件
+* 集成所有更改
+
+## 智能体提示结构
+
+好的智能体提示是：
+
+1. **专注的** - 一个明确的问题领域
+2. **自包含的** - 理解问题所需的所有上下文
+3. **输出具体** - 智能体应返回什么？
+
+```markdown
+修复 `src/agents/agent-tool-abort.test.ts` 中 3 个失败的测试：
+
+1. **"should abort tool with partial output capture"** - 预期消息中包含 'interrupted at'
+2. **"should handle mixed completed and aborted tools"** - 快速工具被中止而非完成
+3. **"should properly track pendingToolCount"** - 预期 3 个结果但得到 0
+
+这些是时序/竞态条件问题。你的任务：
+
+1. 阅读测试文件并理解每个测试的验证内容
+2. 识别根本原因 - 是时序问题还是实际错误？
+3. 通过以下方式修复：
+   - 将任意超时替换为基于事件的等待
+   - 如果发现错误，修复中止实现中的问题
+   - 如果测试行为改变，调整测试预期
+
+不要仅仅增加超时时间 - 找出真正的问题。
+
+返回：总结你发现的问题以及修复的内容。
+```
+
+## 常见错误
+
+**❌ 范围太广：** "修复所有测试" - 智能体迷失方向
+**✅ 具体明确：** "修复 agent-tool-abort.test.ts" - 专注的范围
+
+**❌ 没有上下文：** "修复竞态条件" - 智能体不知道在哪里
+**✅ 提供上下文：** 粘贴错误消息和测试名称
+
+**❌ 没有约束：** 智能体可能会重构所有内容
+**✅ 设置约束：** "请勿更改生产代码" 或 "仅修复测试"
+
+**❌ 输出模糊：** "修复它" - 您不知道改变了什么
+**✅ 具体输出：** "返回根本原因和更改的摘要"
+
+## 何时不应使用
+
+**相关故障：** 修复一个可能修复其他——先一起调查
+**需要完整上下文：** 理解需要查看整个系统
+**探索性调试：** 您还不知道哪里坏了
+**共享状态：** 智能体会相互干扰（编辑相同文件，使用相同资源）
+
+## 会话中的真实示例
+
+**场景：** 重大重构后，3个文件出现6个测试失败
+
+**故障：**
+
+* agent-tool-abort.test.ts：3个故障（时序问题）
+* batch-completion-behavior.test.ts：2个故障（工具未执行）
+* tool-approval-race-conditions.test.ts：1个故障（执行计数 = 0）
+
+**决策：** 独立领域——中止逻辑独立于批处理完成，批处理完成独立于竞态条件
+
+**调度：**
+
+```
+Agent 1 → 修复 agent-tool-abort.test.ts
+Agent 2 → 修复 batch-completion-behavior.test.ts
+Agent 3 → 修复 tool-approval-race-conditions.test.ts
+```
+
+**结果：**
+
+* 智能体 1：用基于事件的等待替换了超时
+* 智能体 2：修复了事件结构错误（threadId 位置错误）
+* 智能体 3：添加了等待异步工具执行完成的逻辑
+
+**集成：** 所有修复都是独立的，没有冲突，完整套件通过
+
+**节省的时间：** 并行解决3个问题 vs 顺序解决
+
+## 主要优势
+
+1. **并行化** - 多项调查同时进行
+2. **专注** - 每个智能体范围狭窄，需要跟踪的上下文更少
+3. **独立性** - 智能体互不干扰
+4. **速度** - 解决3个问题的时间相当于解决1个问题
+
+## 验证
+
+智能体返回后：
+
+1. **审查每个摘要** - 了解更改了什么
+2. **检查冲突** - 智能体是否编辑了相同的代码？
+3. **运行完整套件** - 验证所有修复协同工作
+4. **抽查** - 智能体可能会犯系统性错误
+
+## 实际影响
+
+来自调试会话（2025-10-03）：
+
+* 3个文件出现6个故障
+* 并行调度了3个智能体
+* 所有调查并发完成
+* 所有修复成功集成
+* 智能体更改之间零冲突
diff --git a/zh-CN/skills/executing-plans/SKILL.md b/zh-CN/skills/executing-plans/SKILL.md
new file mode 100644
index 0000000000..60e6cedb4c
--- /dev/null
+++ b/zh-CN/skills/executing-plans/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: executing-plans
+description: 当您有一个书面实施计划，需要在单独的会话中执行并设置审查检查点时使用。
+---
+
+# 执行计划
+
+## 概述
+
+加载计划，进行审阅，执行所有任务，完成后报告。
+
+**开始时宣布：** "我正在使用执行计划技能来实施这个计划。"
+
+**注意：** 告诉您的人类伙伴，Superpowers 在有子代理访问权限的情况下效果会好得多。如果在支持子代理的平台上运行（例如 Claude Code 或 Codex），其工作质量将显著提高。如果子代理可用，请使用 superpowers:subagent-driven-development 而不是此技能。
+
+## 流程
+
+### 步骤 1：加载并审阅计划
+
+1. 读取计划文件
+2. 审阅计划 - 识别计划中的任何疑问或问题
+3. 如果有问题：在开始前向您的人类伙伴提出
+4. 如果没有问题：创建 TodoWrite 并继续
+
+### 步骤 2：执行任务
+
+对于每个任务：
+
+1. 标记为 in\_progress
+2. 严格按照每个步骤执行（计划包含易于执行的小步骤）
+3. 按照指定运行验证
+4. 标记为 completed
+
+### 步骤 3：完成开发
+
+所有任务完成并验证后：
+
+* 宣布："我正在使用完成开发分支技能来完成这项工作。"
+* **必需的子技能：** 使用 superpowers:finishing-a-development-branch
+* 遵循该技能来验证测试、呈现选项、执行选择
+
+## 何时停止并寻求帮助
+
+**遇到以下情况立即停止执行：**
+
+* 遇到阻碍（缺少依赖项、测试失败、指令不明确）
+* 计划存在关键缺陷，无法开始
+* 不理解某个指令
+* 验证反复失败
+
+**请求澄清，而不是猜测。**
+
+## 何时重新审视前面的步骤
+
+**遇到以下情况返回审阅（步骤 1）：**
+
+* 伙伴根据您的反馈更新了计划
+* 基本方法需要重新思考
+
+**不要强行突破阻碍** - 停止并询问。
+
+## 记住
+
+* 首先审阅计划
+* 严格按照计划步骤执行
+* 不要跳过验证
+* 当计划说明时，引用相关技能
+* 遇到阻碍时停止，不要猜测
+* 未经用户明确同意，切勿在 main/master 分支上开始实施
+
+## 集成
+
+**必需的工作流技能：**
+
+* **superpowers:using-git-worktrees** - 必需：在开始前设置隔离的工作空间
+* **superpowers:writing-plans** - 创建此技能执行的计划
+* **superpowers:finishing-a-development-branch** - 所有任务完成后完成开发
diff --git a/zh-CN/skills/finishing-a-development-branch/SKILL.md b/zh-CN/skills/finishing-a-development-branch/SKILL.md
new file mode 100644
index 0000000000..6e3fc4e50f
--- /dev/null
+++ b/zh-CN/skills/finishing-a-development-branch/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: finishing-a-development-branch
+description: 当实现完成、所有测试通过且需要决定如何集成工作时使用 - 通过提供合并、拉取请求或清理的结构化选项，指导开发工作的完成
+---
+
+# 完成开发分支
+
+## 概述
+
+通过呈现清晰选项并处理所选工作流，指导完成开发工作。
+
+**核心原则：** 验证测试 → 呈现选项 → 执行选择 → 清理。
+
+**开始时声明：** "我正在使用完成开发分支技能来完成这项工作。"
+
+## 流程
+
+### 步骤 1：验证测试
+
+**在呈现选项之前，验证测试通过：**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**如果测试失败：**
+
+```
+测试失败（<N> 个失败项）。完成前必须修复：
+
+[显示失败详情]
+
+测试通过前无法进行合并/拉取请求操作。
+```
+
+停止。不要继续到步骤 2。
+
+**如果测试通过：** 继续到步骤 2。
+
+### 步骤 2：确定基础分支
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+或询问："此分支是从 main 分支分出来的 - 是否正确？"
+
+### 步骤 3：呈现选项
+
+准确呈现这 4 个选项：
+
+```
+实施完成。您想做什么？
+
+1. 在本地合并回 <base-branch>
+2. 推送并创建 Pull Request
+3. 保持分支原样（我稍后处理）
+4. 丢弃此项工作
+
+请选择哪个选项？
+```
+
+**不要添加解释** - 保持选项简洁。
+
+### 步骤 4：执行选择
+
+#### 选项 1：本地合并
+
+```bash
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 2：推送并创建 PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+然后：清理工作树（步骤 5）
+
+#### 选项 3：保持原样
+
+报告："保持分支 <名称>。工作树保留在 <路径>。"
+
+**不要清理工作树。**
+
+#### 选项 4：丢弃
+
+**首先确认：**
+
+```
+这将永久删除：
+- 分支 <name>
+- 所有提交：<commit-list>
+- 位于 <path> 的工作树
+
+输入 'discard' 以确认。
+```
+
+等待确切的确认。
+
+如果确认：
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+然后：清理工作树（步骤 5）
+
+### 步骤 5：清理工作树
+
+**对于选项 1, 2, 4：**
+
+检查是否在工作树中：
+
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+如果是：
+
+```bash
+git worktree remove <worktree-path>
+```
+
+**对于选项 3：** 保留工作树。
+
+## 快速参考
+
+| 选项 | 合并 | 推送 | 保留工作树 | 清理分支 |
+|--------|-------|------|---------------|----------------|
+| 1. 本地合并 | ✓ | - | - | ✓ |
+| 2. 创建 PR | - | ✓ | ✓ | - |
+| 3. 保持原样 | - | - | ✓ | - |
+| 4. 丢弃 | - | - | - | ✓ (强制) |
+
+## 常见错误
+
+**跳过测试验证**
+
+* **问题：** 合并损坏的代码，创建失败的 PR
+* **修复：** 在提供选项之前始终验证测试
+
+**开放式问题**
+
+* **问题：** "接下来我该做什么？" → 模糊不清
+* **修复：** 准确呈现 4 个结构化选项
+
+**自动工作树清理**
+
+* **问题：** 在可能还需要时移除工作树（选项 2, 3）
+* **修复：** 仅清理选项 1 和 4 的情况
+
+**丢弃时无确认**
+
+* **问题：** 意外删除工作
+* **修复：** 要求输入 "discard" 确认
+
+## 危险信号
+
+**切勿：**
+
+* 在测试失败的情况下继续
+* 未验证结果测试就进行合并
+* 未经确认就删除工作
+* 未经明确请求就强制推送
+
+**始终：**
+
+* 在提供选项之前验证测试
+* 准确呈现 4 个选项
+* 获取选项 4 的输入确认
+* 仅清理选项 1 和 4 的工作树
+
+## 集成
+
+**由以下调用：**
+
+* **subagent-driven-development** (步骤 7) - 所有任务完成后
+* **executing-plans** (步骤 5) - 所有批次完成后
+
+**与以下配对：**
+
+* **using-git-worktrees** - 清理由该技能创建的工作树
diff --git a/zh-CN/skills/receiving-code-review/SKILL.md b/zh-CN/skills/receiving-code-review/SKILL.md
new file mode 100644
index 0000000000..6f8efbfacd
--- /dev/null
+++ b/zh-CN/skills/receiving-code-review/SKILL.md
@@ -0,0 +1,226 @@
+---
+name: receiving-code-review
+description: 在收到代码审查反馈时使用，特别是在反馈看起来不清楚或技术上存在疑问的情况下——这需要技术上的严谨性和验证，而不是形式上的同意或盲目执行
+---
+
+# 代码审查接待指南
+
+## 概述
+
+代码审查需要技术评估，而非情感表演。
+
+**核心原则：** 先验证，后实施。先询问，后假设。技术正确性高于社交舒适度。
+
+## 回应模式
+
+```
+收到代码审查反馈时：
+
+1. **阅读**：完整阅读反馈内容，不要立即回应
+2. **理解**：用自己的话复述要求（或询问澄清）
+3. **验证**：对照代码库实际情况检查
+4. **评估**：建议是否适合当前代码库的技术方案？
+5. **回应**：给出技术性确认或有理有据的反对意见
+6. **实施**：逐项修改，每项完成后进行测试
+```
+
+## 禁止的回应
+
+**绝对不要：**
+
+* “你说得完全对！”（明确违反 CLAUDE.md）
+* “好观点！” / “出色的反馈！”（表演性回应）
+* “我现在就来实现它”（未经验证前）
+
+**应该：**
+
+* 重述技术需求
+* 提出澄清性问题
+* 如果错误，用技术推理进行反驳
+* 直接开始工作（行动胜于言辞）
+
+## 处理不明确的反馈
+
+```
+如果任何项目不清楚：
+  停止 - 先不要实施任何操作
+  询问不清楚的项目
+
+原因：项目之间可能相互关联。部分理解会导致错误实施。
+```
+
+**示例：**
+
+```
+你的合作伙伴："修复1-6"
+你理解了1、2、3、6。不清楚4和5。
+
+❌ 错误做法：现在实施1、2、3、6，稍后再询问4、5
+✅ 正确做法："我理解了第1、2、3、6项。在继续之前需要澄清第4和第5项。"
+```
+
+## 按来源处理
+
+### 来自你的合作伙伴（人类）
+
+* **信任** - 理解后实施
+* **如果范围不明确，仍需询问**
+* **不要进行表演性同意**
+* **直接行动**或进行技术确认
+
+### 来自外部审查者
+
+```
+实施前：
+  1. 检查：对此代码库在技术上是否正确？
+  2. 检查：是否会破坏现有功能？
+  3. 检查：当前实现的原因是什么？
+  4. 检查：是否适用于所有平台/版本？
+  5. 检查：审查者是否理解完整上下文？
+
+如果建议看似错误：
+  基于技术理由提出异议
+
+如果无法轻易验证：
+  如实说明："我无法在没有 [X] 的情况下验证这一点。我应该 [调查/询问/继续] 吗？"
+
+如果与您人类伙伴先前的决定冲突：
+  暂停并首先与您的人类伙伴讨论
+```
+
+**你的合作伙伴的规则：** “外部反馈——保持怀疑，但仔细检查”
+
+## 对“专业”功能的 YAGNI 检查
+
+```
+如果审阅者建议“正确实现”：
+  在代码库中搜索实际使用情况
+
+  如果未使用：“这个端点未被调用。是否删除它（YAGNI原则）？”
+  如果已使用：则正确实现它
+```
+
+**你的合作伙伴的规则：** “你和审查者都向我汇报。如果我们不需要这个功能，就不要添加它。”
+
+## 实施顺序
+
+```
+对于多项反馈：
+  1. 首先澄清任何不明确之处
+  2. 然后按此顺序实施：
+     - 阻塞性问题（中断、安全）
+     - 简单修复（拼写错误、导入）
+     - 复杂修复（重构、逻辑）
+  3. 单独测试每个修复
+  4. 验证无回归问题
+```
+
+## 何时进行反驳
+
+在以下情况下进行反驳：
+
+* 建议会破坏现有功能
+* 审查者缺乏完整上下文
+* 违反 YAGNI（未使用的功能）
+* 在当前技术栈中技术上不正确
+* 存在遗留/兼容性原因
+* 与你的合作伙伴的架构决策相冲突
+
+**如何反驳：**
+
+* 使用技术推理，而非防御性态度
+* 提出具体问题
+* 引用有效的测试/代码
+* 如果涉及架构，请让你的合作伙伴参与
+
+**如果因公开反驳感到不适，请发出信号：** “Circle K 那边有点不对劲”
+
+## 确认正确的反馈
+
+当反馈**确实**正确时：
+
+```
+✅ "已修复。[简要描述更改内容]"
+✅ "好发现 - [具体问题]。已在[位置]修复。"
+✅ [直接修复并在代码中展示]
+
+❌ "您说得完全正确！"
+❌ "很好的观点！"
+❌ "感谢您发现这个问题！"
+❌ "感谢您[任何内容]"
+❌ 任何感谢表达
+```
+
+**为何不道谢：** 行动胜于言表。直接修复它。代码本身就表明你听到了反馈。
+
+**如果你发现自己正要写“谢谢”：** 删除它。改为陈述修复内容。
+
+## 优雅地纠正你的反驳
+
+如果你反驳了，但你是错的：
+
+```
+✅ "你说得对——我检查了 [X]，它确实 [Y]。正在实施。"
+✅ "验证过了，你是对的。我最初的理解有误，因为 [原因]。正在修复。"
+
+❌ 冗长的道歉
+❌ 辩解为何提出异议
+❌ 过度解释
+```
+
+客观地陈述更正并继续。
+
+## 常见错误
+
+| 错误 | 修正方法 |
+|---------|-----|
+| 表演性同意 | 陈述需求或直接行动 |
+| 盲目实施 | 先对照代码库验证 |
+| 批量处理而不测试 | 一次一个，逐个测试 |
+| 假设审查者是对的 | 检查是否会破坏东西 |
+| 避免反驳 | 技术正确性 > 舒适度 |
+| 部分实施 | 先澄清所有事项 |
+| 无法验证，仍继续 | 说明局限性，请求指示 |
+
+## 真实示例
+
+**表演性同意（错误）：**
+
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**技术验证（正确）：**
+
+```
+Reviewer: "移除旧版代码"
+✅ "正在检查...构建目标为10.15+，此API需要13+。需要旧版代码以保持向后兼容。当前实现使用了错误的bundle ID - 修复它还是放弃对13以下版本的支持？"
+```
+
+**YAGNI（正确）：**
+
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "已搜索代码库 - 没有调用此端点。删除它（YAGNI）？还是我遗漏了使用情况？"
+```
+
+**不明确的项目（正确）：**
+
+```
+你的合作者："修复第1到第6项"
+你理解第1、2、3、6项。对第4、5项不清楚。
+✅ "理解第1、2、3、6项。在实施前需要澄清第4和第5项。"
+```
+
+## GitHub 线程回复
+
+当回复 GitHub 上的行内审查评论时，请在评论线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而不是作为 PR 的顶级评论。
+
+## 底线
+
+**外部反馈 = 需要评估的建议，而非必须遵循的命令。**
+
+验证。质疑。然后实施。
+
+不要表演性同意。始终保持技术严谨性。
diff --git a/zh-CN/skills/requesting-code-review/SKILL.md b/zh-CN/skills/requesting-code-review/SKILL.md
new file mode 100644
index 0000000000..10acc5f2d5
--- /dev/null
+++ b/zh-CN/skills/requesting-code-review/SKILL.md
@@ -0,0 +1,115 @@
+---
+name: requesting-code-review
+description: 用于完成任务、实现主要功能或合并前验证工作是否符合要求时使用
+---
+
+# 请求代码审查
+
+调度 superpowers:code-reviewer 子代理以在问题蔓延前将其捕获。审查者会获得精心构建的评估上下文——绝不会是你会话的历史记录。这能让审查者专注于工作成果，而非你的思考过程，并为你自己的后续工作保留上下文。
+
+**核心原则：** 早审查，常审查。
+
+## 何时请求审查
+
+**强制情况：**
+
+* 在子代理驱动开发的每项任务之后
+* 完成主要功能后
+* 合并到主分支前
+
+**可选但很有价值：**
+
+* 遇到瓶颈时（获取新视角）
+* 重构之前（基线检查）
+* 修复复杂错误后
+
+## 如何请求
+
+**1. 获取 git SHA：**
+
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. 调度 code-reviewer 子代理：**
+
+使用 Task 工具，类型为 superpowers:code-reviewer，填写位于 `code-reviewer.md` 的模板
+
+**占位符说明：**
+
+* `{WHAT_WAS_IMPLEMENTED}` - 你刚刚构建了什么
+* `{PLAN_OR_REQUIREMENTS}` - 它应该做什么
+* `{BASE_SHA}` - 起始提交
+* `{HEAD_SHA}` - 结束提交
+* `{DESCRIPTION}` - 简要总结
+
+**3. 处理反馈：**
+
+* 立即修复 关键 问题
+* 在继续之前修复 重要 问题
+* 记录 次要 问题稍后处理
+* 如果审查者有误，请提出反驳（并附上理由）
+
+## 示例
+
+```
+[已完成任务 2：添加验证功能]
+
+你：让我在继续之前请求代码审查。
+
+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: 对话索引的验证和修复功能
+  PLAN_OR_REQUIREMENTS: 来自 docs/superpowers/plans/deployment-plan.md 的任务 2
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: 添加了包含 4 种问题类型的 verifyIndex() 和 repairIndex()
+
+[子代理返回]：
+  优点：架构清晰，包含真实测试
+  问题：
+    重要：缺少进度指示器
+    次要：报告间隔使用魔数 (100)
+  评估：可以继续
+
+你：[修复进度指示器]
+[继续任务 3]
+```
+
+## 与工作流的集成
+
+**子代理驱动开发：**
+
+* 在 每项 任务后审查
+* 在问题累积前将其捕获
+* 在进入下一任务前修复
+
+**执行计划时：**
+
+* 每批（3项任务）后审查
+* 获取反馈，应用，继续
+
+**临时开发：**
+
+* 合并前审查
+* 遇到瓶颈时审查
+
+## 危险信号
+
+**切勿：**
+
+* 因为“很简单”而跳过审查
+* 忽视 关键 问题
+* 带着未修复的 重要 问题继续
+* 与有效的技术反馈争论
+
+**如果审查者有误：**
+
+* 用技术推理提出反驳
+* 展示证明其有效的代码/测试
+* 请求澄清
+
+模板见：requesting-code-review/code-reviewer.md
diff --git a/zh-CN/skills/requesting-code-review/code-reviewer.md b/zh-CN/skills/requesting-code-review/code-reviewer.md
new file mode 100644
index 0000000000..fd7724ba06
--- /dev/null
+++ b/zh-CN/skills/requesting-code-review/code-reviewer.md
@@ -0,0 +1,160 @@
+# 代码审查代理
+
+您正在审查代码变更的生产就绪性。
+
+**您的任务：**
+
+1. 审查 {WHAT\_WAS\_IMPLEMENTED}
+2. 与 {PLAN\_OR\_REQUIREMENTS} 进行对比
+3. 检查代码质量、架构、测试
+4. 按严重性对问题进行归类
+5. 评估生产就绪性
+
+## 已实现内容
+
+{DESCRIPTION}
+
+## 需求/计划
+
+{PLAN\_REFERENCE}
+
+## 待审查的 Git 范围
+
+**基准：** {BASE\_SHA}
+**头部：** {HEAD\_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## 审查清单
+
+**代码质量：**
+
+* 关注点分离是否清晰？
+* 错误处理是否恰当？
+* 类型安全（如适用）？
+* 是否遵循 DRY 原则？
+* 边界情况是否已处理？
+
+**架构：**
+
+* 设计决策是否合理？
+* 是否考虑了可扩展性？
+* 对性能有何影响？
+* 是否存在安全隐患？
+
+**测试：**
+
+* 测试是否真正测试了逻辑（而非模拟对象）？
+* 是否覆盖了边界情况？
+* 在需要的地方是否有集成测试？
+* 所有测试是否通过？
+
+**需求：**
+
+* 是否满足所有计划需求？
+* 实现是否符合规范？
+* 是否存在范围蔓延？
+* 破坏性变更是否已记录？
+
+**生产就绪性：**
+
+* 迁移策略（如果存在模式变更）？
+* 是否考虑了向后兼容性？
+* 文档是否完整？
+* 是否存在明显的错误？
+
+## 输出格式
+
+### 优点
+
+\[哪些地方做得好？请具体说明。]
+
+### 问题
+
+#### 关键问题（必须修复）
+
+\[错误、安全问题、数据丢失风险、功能损坏]
+
+#### 重要问题（应该修复）
+
+\[架构问题、功能缺失、错误处理不当、测试缺口]
+
+#### 次要问题（最好有）
+
+\[代码风格、优化机会、文档改进]
+
+**针对每个问题：**
+
+* 文件:行号引用
+* 问题是什么
+* 为什么重要
+* 如何修复（如果不明显）
+
+### 建议
+
+\[针对代码质量、架构或流程的改进建议]
+
+### 评估
+
+**是否可合并？** \[是/否/需修复后]
+
+**理由：** \[1-2句话的技术评估]
+
+## 关键规则
+
+**务必：**
+
+* 按实际严重性分类（并非所有问题都是关键问题）
+* 具体说明（文件:行号，而非模糊描述）
+* 解释问题为何重要
+* 肯定优点
+* 给出明确的结论
+
+**切勿：**
+
+* 未经检查就说"看起来不错"
+* 将吹毛求疵的问题标记为关键问题
+* 对未审查的代码提供反馈
+* 含糊不清（如"改进错误处理"）
+* 避免给出明确结论
+
+## 示例输出
+
+```
+### 优势
+- 清晰的数据库结构，配备了恰当的迁移脚本 (db.ts:15-42)
+- 全面的测试覆盖 (18个测试，覆盖所有边界情况)
+- 良好的错误处理与回退机制 (summarizer.ts:85-92)
+
+### 问题
+
+#### 重要
+1. **CLI包装器中缺少帮助文本**
+   - 文件: index-conversations:1-31
+   - 问题: 没有 `--help` 标志，用户无法发现 `--concurrency` 参数
+   - 修复: 添加 `--help` 选项并附带使用示例
+
+2. **缺少日期验证**
+   - 文件: search.ts:25-27
+   - 问题: 无效日期会静默返回无结果
+   - 修复: 验证ISO格式，抛出错误并附带示例
+
+#### 次要
+1. **进度指示器**
+   - 文件: indexer.ts:130
+   - 问题: 长时间操作没有 "X of Y" 计数器
+   - 影响: 用户不知道需要等待多久
+
+### 建议
+- 添加进度报告以提升用户体验
+- 考虑使用配置文件来管理排除的项目（以提高可移植性）
+
+### 评估
+
+**准备合并状态：需要修复后**
+
+**理由：** 核心实现稳固，架构良好且测试完善。重要问题（帮助文本、日期验证）易于修复，且不影响核心功能。
+```
diff --git a/zh-CN/skills/subagent-driven-development/SKILL.md b/zh-CN/skills/subagent-driven-development/SKILL.md
new file mode 100644
index 0000000000..5864cce2e7
--- /dev/null
+++ b/zh-CN/skills/subagent-driven-development/SKILL.md
@@ -0,0 +1,292 @@
+---
+name: subagent-driven-development
+description: 在当前会话中执行具有独立任务的实施计划时使用
+---
+
+# 子代理驱动开发
+
+通过为每个任务派遣新的子代理来执行计划，每个任务后进行两阶段评审：先进行规范符合性评审，再进行代码质量评审。
+
+**为何使用子代理：** 你将任务委托给具有独立上下文的专业代理。通过精确设计其指令和上下文，确保他们保持专注并成功完成任务。他们绝不应继承你会话的上下文或历史记录——你只构建他们所需的确切内容。这也为你自己的协调工作保留了上下文。
+
+**核心原则：** 每个任务使用新的子代理 + 两阶段评审（先规范后质量）= 高质量、快速迭代
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "Have implementation plan?" [shape=diamond];
+    "Tasks mostly independent?" [shape=diamond];
+    "Stay in this session?" [shape=diamond];
+    "subagent-driven-development" [shape=box];
+    "executing-plans" [shape=box];
+    "Manual execution or brainstorm first" [shape=box];
+
+    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
+    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
+    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
+    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
+    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
+    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
+}
+```
+
+**对比执行计划（并行会话）：**
+
+* 同一会话（无需切换上下文）
+* 每个任务使用新的子代理（无上下文污染）
+* 每个任务后进行两阶段评审：先进行规范符合性评审，再进行代码质量评审
+* 迭代更快（任务之间无需人工介入）
+
+## 流程
+
+```dot
+digraph process {
+    rankdir=TB;
+
+    subgraph cluster_per_task {
+        label="Per Task";
+        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
+        "Implementer subagent asks questions?" [shape=diamond];
+        "Answer questions, provide context" [shape=box];
+        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
+        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
+        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
+        "Implementer subagent fixes spec gaps" [shape=box];
+        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
+        "Code quality reviewer subagent approves?" [shape=diamond];
+        "Implementer subagent fixes quality issues" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
+    }
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+    "More tasks remain?" [shape=diamond];
+    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
+    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
+    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
+    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
+    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
+    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
+    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
+    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
+    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
+    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+}
+```
+
+## 模型选择
+
+使用能够胜任每个角色的最小能力模型，以节约成本并提高速度。
+
+**机械性实现任务**（独立的函数、明确的规范、1-2个文件）：使用快速、廉价的模型。当计划制定明确时，大多数实现任务都是机械性的。
+
+**集成和判断任务**（多文件协调、模式匹配、调试）：使用标准模型。
+
+**架构、设计和评审任务**：使用可用的最强大模型。
+
+**任务复杂性信号：**
+
+* 涉及1-2个文件且有完整规范 → 廉价模型
+* 涉及多个文件且有集成问题 → 标准模型
+* 需要设计判断或广泛的代码库理解 → 最强大模型
+
+## 处理实现者状态
+
+实现者子代理报告四种状态之一。请适当处理每种状态：
+
+**完成：** 继续进行规范符合性评审。
+
+**完成但有顾虑：** 实现者完成了工作，但标记了疑虑。在继续之前阅读这些顾虑。如果顾虑涉及正确性或范围，请在评审前解决它们。如果它们是观察性意见（例如，“这个文件变得很大”），记下它们并继续进行评审。
+
+**需要上下文：** 实现者需要未提供的信息。提供缺失的上下文并重新派遣。
+
+**受阻：** 实现者无法完成任务。评估阻碍因素：
+
+1. 如果是上下文问题，提供更多上下文并用同一模型重新派遣
+2. 如果任务需要更多推理，用更强大的模型重新派遣
+3. 如果任务太大，将其分解为更小的部分
+4. 如果计划本身有误，上报给人类
+
+**切勿** 忽略上报或在不做任何更改的情况下强制同一模型重试。如果实现者表示受阻，则必须做出某些改变。
+
+## 提示词模板
+
+* `./implementer-prompt.md` - 派遣实现者子代理
+* `./spec-reviewer-prompt.md` - 派遣规范符合性评审者子代理
+* `./code-quality-reviewer-prompt.md` - 派遣代码质量评审者子代理
+
+## 示例工作流
+
+```
+You: 我正在使用 Subagent-Driven Development 来执行这个计划。
+
+[读取计划文件一次：docs/superpowers/plans/feature-plan.md]
+[提取全部 5 个任务及其完整文本和上下文]
+[使用所有任务创建 TodoWrite]
+
+任务 1: 钩子安装脚本
+
+[获取任务 1 的文本和上下文（已提取）]
+[派遣实现子代理，附带完整任务文本和上下文]
+
+实现者："在我开始之前 - 钩子应该安装在用户级别还是系统级别？"
+
+You: "用户级别 (~/.config/superpowers/hooks/)"
+
+实现者："明白了。现在开始实现..."
+[稍后] 实现者:
+  - 实现了 install-hook 命令
+  - 添加了测试，5/5 通过
+  - 自审：发现我遗漏了 --force 标志，已添加
+  - 已提交
+
+[派遣规范合规审查员]
+规范审查员：✅ 符合规范 - 所有要求均已满足，无额外添加
+
+[获取 git SHAs，派遣代码质量审查员]
+代码审查员：优点：测试覆盖良好，代码简洁。问题：无。批准。
+
+[标记任务 1 完成]
+
+任务 2: 恢复模式
+
+[获取任务 2 的文本和上下文（已提取）]
+[派遣实现子代理，附带完整任务文本和上下文]
+
+实现者：[没有问题，继续]
+实现者：
+  - 添加了 verify/repair 模式
+  - 8/8 测试通过
+  - 自审：一切良好
+  - 已提交
+
+[派遣规范合规审查员]
+规范审查员：❌ 问题：
+  - 缺失：进度报告（规范要求"每 100 个项目报告一次"）
+  - 额外：添加了 --json 标志（未要求）
+
+[实现者修复问题]
+实现者：移除了 --json 标志，添加了进度报告
+
+[规范审查员再次审查]
+规范审查员：✅ 现在符合规范
+
+[派遣代码质量审查员]
+代码审查员：优点：扎实。问题（重要）：魔法数字 (100)
+
+[实现者修复]
+实现者：提取了 PROGRESS_INTERVAL 常量
+
+[代码审查员再次审查]
+代码审查员：✅ 批准
+
+[标记任务 2 完成]
+
+...
+
+[所有任务完成后]
+[派遣最终代码审查员]
+最终审查员：所有要求均已满足，准备合并
+
+完成！
+```
+
+## 优势
+
+**对比手动执行：**
+
+* 子代理自然遵循测试驱动开发
+* 每个任务都有新的上下文（无混淆）
+* 支持并行安全（子代理互不干扰）
+* 子代理可以提问（在工作开始前和工作期间）
+
+**对比执行计划：**
+
+* 同一会话（无需交接）
+* 持续进展（无需等待）
+* 评审检查点自动进行
+
+**效率提升：**
+
+* 无文件读取开销（控制器提供完整文本）
+* 控制器精心策划所需的确切上下文
+* 子代理一开始就获得完整信息
+* 问题在工作开始前就浮出水面（而非之后）
+
+**质量关卡：**
+
+* 自评审在交接前发现问题
+* 两阶段评审：规范符合性，然后代码质量
+* 评审循环确保修复实际有效
+* 规范符合性防止过度构建或构建不足
+* 代码质量确保实现构建良好
+
+**成本：**
+
+* 更多的子代理调用（每个任务：实现者 + 2名评审者）
+* 控制器做更多准备工作（提前提取所有任务）
+* 评审循环增加了迭代次数
+* 但能及早发现问题（比后期调试更便宜）
+
+## 危险信号
+
+**切勿：**
+
+* 未经用户明确同意就在主分支上开始实现
+* 跳过评审（规范符合性或代码质量）
+* 带着未修复的问题继续
+* 并行派遣多个实现子代理（冲突）
+* 让子代理读取计划文件（应提供完整文本）
+* 跳过场景设定上下文（子代理需要理解任务所处位置）
+* 忽略子代理的问题（在让他们继续之前回答）
+* 在规范符合性上接受“差不多就行”（规范评审者发现问题 = 未完成）
+* 跳过评审循环（评审者发现问题 = 实现者修复 = 再次评审）
+* 让实现者自评审取代实际评审（两者都需要）
+* **在规范符合性评审通过前开始代码质量评审**（顺序错误）
+* 在任一评审仍有未解决问题时转向下一个任务
+
+**如果子代理提问：**
+
+* 清晰完整地回答
+* 必要时提供额外上下文
+* 不要催促他们进入实现阶段
+
+**如果评审者发现问题：**
+
+* 由实现者（同一子代理）修复它们
+* 评审者再次评审
+* 重复直至批准
+* 不要跳过重新评审
+
+**如果子代理任务失败：**
+
+* 派遣修复子代理并给出具体指令
+* 不要尝试手动修复（上下文污染）
+
+## 集成
+
+**必需的工作流技能：**
+
+* **superpowers:using-git-worktrees** - **必需**：在开始前设置独立的工作空间
+* **superpowers:writing-plans** - 创建此技能执行的计划
+* **superpowers:requesting-code-review** - 用于评审者子代理的代码评审模板
+* **superpowers:finishing-a-development-branch** - 在所有任务完成后完成开发
+
+**子代理应使用：**
+
+* **superpowers:test-driven-development** - 子代理为每个任务遵循测试驱动开发
+
+**替代工作流：**
+
+* **superpowers:executing-plans** - 用于并行会话而非同一会话执行
diff --git a/zh-CN/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/zh-CN/skills/subagent-driven-development/code-quality-reviewer-prompt.md
new file mode 100644
index 0000000000..46d3ac9c55
--- /dev/null
+++ b/zh-CN/skills/subagent-driven-development/code-quality-reviewer-prompt.md
@@ -0,0 +1,27 @@
+# 代码质量审查员提示模板
+
+在分派代码质量审查员子代理时使用此模板。
+
+**目的：** 验证实现是否构建良好（整洁、经过测试、可维护）
+
+**仅在规范合规性审查通过后分派。**
+
+```
+Task tool (superpowers:code-reviewer):
+  使用 requesting-code-review/code-reviewer.md 中的模板
+
+  WHAT_WAS_IMPLEMENTED: [来自实施者的报告]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [任务前的提交]
+  HEAD_SHA: [当前提交]
+  DESCRIPTION: [任务摘要]
+```
+
+**除了标准的代码质量问题外，审查员还应检查：**
+
+* 每个文件是否具有一个明确的职责和定义良好的接口？
+* 单元是否被分解，以便能够独立理解和测试？
+* 实现是否遵循计划中的文件结构？
+* 此实现是否创建了已经很大的新文件，或显著增大了现有文件？（不要标记预先存在的文件大小——重点关注本次变更带来的影响。）
+
+**代码审查员返回：** 优点、问题（严重/重要/轻微）、评估
diff --git a/zh-CN/skills/subagent-driven-development/implementer-prompt.md b/zh-CN/skills/subagent-driven-development/implementer-prompt.md
new file mode 100644
index 0000000000..5ae348ea1e
--- /dev/null
+++ b/zh-CN/skills/subagent-driven-development/implementer-prompt.md
@@ -0,0 +1,105 @@
+# 实施者子代理提示模板
+
+在分派实施者子代理时使用此模板。
+
+```
+任务工具（通用型）：
+  描述："实施任务 N：[任务名称]"
+  提示：|
+    你正在实施任务 N：[任务名称]
+
+    ## 任务描述
+
+    [计划中任务的全文本 - 粘贴在此处，不要让子代理读取文件]
+
+    ## 上下文
+
+    [场景设定：此任务的位置、依赖关系、架构上下文]
+
+    ## 开始前须知
+
+    如果你对以下方面有疑问：
+    - 需求或验收标准
+    - 方法或实施策略
+    - 依赖关系或假设
+    - 任务描述中任何不明确的内容
+
+    **立即提出。** 在开始工作前提出任何疑虑。
+
+    ## 你的职责
+
+    一旦你对需求清楚：
+    1. 准确实施任务规定的内容
+    2. 编写测试（如果任务要求，请遵循 TDD）
+    3. 验证实施是否有效
+    4. 提交你的工作
+    5. 自我审查（见下文）
+    6. 报告结果
+
+    工作目录：[目录]
+
+    **工作期间：** 如果你遇到意外或不明确的情况，**提出问题**。
+    随时可以暂停并澄清。不要猜测或做出假设。
+
+    ## 代码组织
+
+    你最好能一次性理解上下文中的代码，且当文件聚焦时，你的编辑更可靠。请记住：
+    - 遵循计划中定义的文件结构
+    - 每个文件应有一个明确的职责和定义良好的接口
+    - 如果你创建的文件超出计划的意图，停止并报告为 DONE_WITH_CONCERNS — 不要在没有计划指导的情况下自行拆分文件
+    - 如果你修改的现有文件已经很大或混乱，请谨慎工作并在报告中注明为问题
+    - 在现有代码库中，遵循既定模式。以优秀开发者的方式改进你接触的代码，但不要重构任务之外的内容。
+
+    ## 当你遇到困难时
+
+    随时可以停止并说“这对我来说太难了”。糟糕的工作比没有工作更糟。你不会因升级问题而受到惩罚。
+
+    **停止并升级的情况：**
+    - 任务需要涉及多种有效方法的架构决策
+    - 你需要理解超出提供范围且无法找到清晰解释的代码
+    - 你不确定你的方法是否正确
+    - 任务涉及以计划未预料的方式重构现有代码
+    - 你一直在阅读一个又一个文件试图理解系统，但没有进展
+
+    **如何升级：** 以状态 BLOCKED 或 NEEDS_CONTEXT 报告。具体描述你卡住的地方、你尝试过的方法以及你需要什么样的帮助。
+    控制器可以提供更多上下文、重新分派给能力更强的模型，或将任务分解为更小的部分。
+
+    ## 报告前：自我审查
+
+    以全新的视角审查你的工作。问自己：
+
+    **完整性：**
+    - 我是否完全实现了规范中的所有内容？
+    - 我是否遗漏了任何需求？
+    - 是否有未处理的边缘情况？
+
+    **质量：**
+    - 这是我的最佳工作吗？
+    - 名称是否清晰准确（匹配功能，而非实现方式）？
+    - 代码是否干净且易于维护？
+
+    **纪律性：**
+    - 我是否避免了过度构建（YAGNI）？
+    - 我是否只构建了请求的内容？
+    - 我是否遵循了代码库中的现有模式？
+
+    **测试：**
+    - 测试是否实际验证了行为（而不仅仅是模拟行为）？
+    - 如果要求，我是否遵循了 TDD？
+    - 测试是否全面？
+
+    如果在自我审查中发现问题，请在报告前立即修复。
+
+    ## 报告格式
+
+    完成后，报告：
+    - **状态：** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - 你实施了什么（或尝试了什么，如果被阻止）
+    - 你测试了什么以及测试结果
+    - 更改的文件
+    - 自我审查发现的问题（如果有）
+    - 任何问题或疑虑
+
+    如果你完成了工作但对正确性有疑虑，请使用 DONE_WITH_CONCERNS。
+    如果你无法完成任务，请使用 BLOCKED。如果你需要未提供的信息，请使用 NEEDS_CONTEXT。永远不要默默产生你不确定的工作。
+```
diff --git a/zh-CN/skills/subagent-driven-development/spec-reviewer-prompt.md b/zh-CN/skills/subagent-driven-development/spec-reviewer-prompt.md
new file mode 100644
index 0000000000..1762536f93
--- /dev/null
+++ b/zh-CN/skills/subagent-driven-development/spec-reviewer-prompt.md
@@ -0,0 +1,61 @@
+# 规范合规审查员提示模板
+
+当派遣规范合规审查员子代理时使用此模板。
+
+**目的：** 验证实施者是否构建了所请求的内容（不多不少）
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+    - Did they claim something works but didn't actually implement it?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+    - Did they add "nice to haves" that weren't in spec?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+    - Did they solve the wrong problem?
+    - Did they implement the right feature but wrong way?
+
+    **Verify by reading code, not by trusting report.**
+
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```
diff --git a/zh-CN/skills/systematic-debugging/CREATION-LOG.md b/zh-CN/skills/systematic-debugging/CREATION-LOG.md
new file mode 100644
index 0000000000..0a08c1f3fc
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/CREATION-LOG.md
@@ -0,0 +1,133 @@
+# 创建日志：系统性调试技能
+
+提取、构建并强化关键技能的参考范例。
+
+## 源材料
+
+从 `/Users/jesse/.claude/CLAUDE.md` 中提取的调试框架：
+
+* 4 阶段系统化流程（调查 → 模式分析 → 假设 → 实施）
+* 核心准则：**始终**找到根本原因，**永不**修复症状
+* 规则旨在抵抗时间压力和合理化借口
+
+## 提取决策
+
+**包含内容：**
+
+* 完整的 4 阶段框架及所有规则
+* 反捷径提示（"永不修复症状"、"停止并重新分析"）
+* 抗压性措辞（"即使更快"、"即使我看起来很赶时间"）
+* 每个阶段的具体步骤
+
+**排除内容：**
+
+* 项目特定上下文
+* 相同规则的重复杂表述
+* 叙述性解释（浓缩为原则）
+
+## 遵循 skill-creation/SKILL.md 的结构
+
+1. **丰富的 when\_to\_use** - 包含症状和反模式
+2. **类型：技术** - 包含步骤的具体流程
+3. **关键词** - "根本原因"、"症状"、"变通方法"、"调试"、"调查"
+4. **流程图** - "修复失败"时的决策点 → 重新分析 vs 添加更多修复
+5. **分阶段详解** - 可快速浏览的清单格式
+6. **反模式部分** - 不应做什么（对于此技能至关重要）
+
+## 强化元素
+
+框架设计用于抵抗压力下的合理化借口：
+
+### 措辞选择
+
+* "始终" / "永不"（而非"应该" / "尝试"）
+* "即使更快" / "即使我看起来很赶时间"
+* "停止并重新分析"（明确的暂停）
+* "不要跳过"（捕捉实际行为）
+
+### 结构防御
+
+* **阶段 1 为必需** - 不能跳至实施阶段
+* **单一假设规则** - 强制思考，防止散弹式修复
+* **明确的失败模式** - "如果你的首次修复无效"并附带强制操作
+* **反模式部分** - 精确展示捷径操作的表现形式
+
+### 冗余设计
+
+* 根本原因准则出现在概述 + when\_to\_use + 阶段 1 + 实施规则中
+* "永不修复症状"在不同上下文中出现 4 次
+* 每个阶段都有明确的"不要跳过"指引
+
+## 测试方法
+
+遵循 skills/meta/testing-skills-with-subagents 创建了 4 个验证测试：
+
+### 测试 1：学术情境（无压力）
+
+* 简单错误，无时间压力
+* **结果：** 完全遵守，完成调查
+
+### 测试 2：时间压力 + 明显的快速修复
+
+* 用户"赶时间"，症状修复看似简单
+* **结果：** 抵制了捷径，遵循完整流程，找到了真正的根本原因
+
+### 测试 3：复杂系统 + 不确定性
+
+* 多层故障，不清楚是否能找到根本原因
+* **结果：** 系统性调查，追踪了所有层级，找到了源头
+
+### 测试 4：首次修复失败
+
+* 假设无效，有添加更多修复的诱惑
+* **结果：** 停止，重新分析，形成新假设（没有散弹式修复）
+
+**所有测试通过。** 未发现合理化借口。
+
+## 迭代过程
+
+### 初始版本
+
+* 完整的 4 阶段框架
+* 反模式部分
+* "修复失败"决策流程图
+
+### 增强 1：TDD 参考
+
+* 添加了指向 skills/testing/test-driven-development 的链接
+* 注释解释 TDD 的"最简单代码" ≠ 调试的"根本原因"
+* 防止方法论之间的混淆
+
+## 最终成果
+
+强化后的技能：
+
+* ✅ 明确要求进行根本原因调查
+* ✅ 抵抗时间压力下的合理化借口
+* ✅ 提供每个阶段的具体步骤
+* ✅ 明确展示反模式
+* ✅ 在多种压力场景下经过测试
+* ✅ 澄清了与 TDD 的关系
+* ✅ 可供使用
+
+## 关键洞察
+
+**最重要的强化部分：** 反模式部分精确展示了那些在当下感觉合理的捷径。当 Claude 想"我就加这个快速修复"时，看到该确切模式被列为错误会产生认知摩擦。
+
+## 使用示例
+
+遇到错误时：
+
+1. 加载技能：skills/debugging/systematic-debugging
+2. 阅读概述（10 秒）- 提醒准则
+3. 遵循阶段 1 清单 - 强制调查
+4. 如果试图跳过 - 查看反模式，停止
+5. 完成所有阶段 - 找到根本原因
+
+**时间投入：** 5-10 分钟
+**节省时间：** 数小时的症状打地鼠游戏
+
+***
+
+*创建于：2025-10-03*
+*目的：技能提取和强化的参考范例*
diff --git a/zh-CN/skills/systematic-debugging/SKILL.md b/zh-CN/skills/systematic-debugging/SKILL.md
new file mode 100644
index 0000000000..788b9dfdfa
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/SKILL.md
@@ -0,0 +1,308 @@
+---
+name: systematic-debugging
+description: 当遇到任何错误、测试失败或意外行为时，在提出修复方案前使用
+---
+
+# 系统性调试
+
+## 概述
+
+随机修复浪费时间并产生新的错误。快速补丁掩盖了潜在问题。
+
+**核心原则：** 在尝试修复之前，**务必**找到根本原因。症状修复就是失败。
+
+**违反此流程的字面要求就是违反调试的精神。**
+
+## 铁律
+
+```
+未经根本原因调查，不得进行修复
+```
+
+如果你没有完成第一阶段，就不能提出修复方案。
+
+## 何时使用
+
+适用于**任何**技术问题：
+
+* 测试失败
+* 生产环境中的错误
+* 意外行为
+* 性能问题
+* 构建失败
+* 集成问题
+
+**在以下情况尤其要使用此方法：**
+
+* 时间紧迫时（紧急情况容易让人想猜测）
+* “就一个快速修复”看起来很显而易见时
+* 你已经尝试了多种修复方案
+* 之前的修复没有奏效
+* 你没有完全理解问题
+
+**在以下情况不要跳过：**
+
+* 问题看起来很简单（简单的错误也有根本原因）
+* 你很匆忙（仓促行事必然导致返工）
+* 经理要求立刻修复（系统化方法比瞎忙更快）
+
+## 四个阶段
+
+你必须完成每个阶段才能进入下一阶段。
+
+### 第一阶段：根本原因调查
+
+**在尝试任何修复之前：**
+
+1. **仔细阅读错误信息**
+   * 不要跳过错误或警告
+   * 它们通常包含确切的解决方案
+   * 完整阅读堆栈跟踪
+   * 注意行号、文件路径、错误代码
+
+2. **稳定复现**
+   * 你能可靠地触发它吗？
+   * 确切的步骤是什么？
+   * 每次都会发生吗？
+   * 如果无法复现 → 收集更多数据，不要猜测
+
+3. **检查最近的变更**
+   * 哪些变化可能导致此问题？
+   * Git diff，最近的提交
+   * 新的依赖项，配置更改
+   * 环境差异
+
+4. **在多组件系统中收集证据**
+
+   **当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：**
+
+   **在提出修复方案之前，添加诊断工具：**
+
+   ```
+   对于每个组件边界：
+     - 记录进入组件的数据
+     - 记录离开组件的数据
+     - 验证环境/配置的传播
+     - 检查每一层的状态
+
+   运行一次以收集证据，显示它在哪个环节中断
+   然后分析证据以识别故障组件
+   然后调查该特定组件
+   ```
+
+   **示例（多层系统）：**
+
+   ```bash
+   # 第 1 层：工作流
+   echo "=== 工作流中可用的密钥：==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # 第 2 层：构建脚本
+   echo "=== 构建脚本中的环境变量：==="
+   env | grep IDENTITY || echo "IDENTITY 不在环境中"
+
+   # 第 3 层：签名脚本
+   echo "=== 钥匙串状态：==="
+   security list-keychains
+   security find-identity -v
+
+   # 第 4 层：实际签名
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **这揭示了：** 哪一层失败（密钥 → 工作流 ✓，工作流 → 构建 ✗）
+
+5. **追踪数据流**
+
+   **当错误在调用堆栈深处时：**
+
+   查看此目录中的 `root-cause-tracing.md` 以获取完整的向后追踪技术。
+
+   **快速版本：**
+
+   * 错误值源自何处？
+   * 是什么用错误值调用了这个？
+   * 持续向上追踪直到找到源头
+   * 在源头修复，而不是在症状处
+
+### 第二阶段：模式分析
+
+**在修复之前找到模式：**
+
+1. **找到工作示例**
+   * 在同一代码库中找到类似的正常工作代码
+   * 哪些与出问题的代码类似且正常工作？
+
+2. **对照参考进行比较**
+   * 如果实现模式，请**完整**阅读参考实现
+   * 不要略读——阅读每一行
+   * 在应用之前完全理解该模式
+
+3. **识别差异**
+   * 正常工作和出问题的代码之间有什么不同？
+   * 列出每一个差异，无论多小
+   * 不要假设“那不可能有关系”
+
+4. **理解依赖关系**
+   * 这需要哪些其他组件？
+   * 需要什么设置、配置、环境？
+   * 它做了哪些假设？
+
+### 第三阶段：假设与测试
+
+**科学方法：**
+
+1. **提出单一假设**
+   * 明确陈述：“我认为 X 是根本原因，因为 Y”
+   * 写下来
+   * 要具体，不要模糊
+
+2. **最小化测试**
+   * 做出**最小**的更改来测试假设
+   * 一次只改变一个变量
+   * 不要同时修复多个问题
+
+3. **验证后再继续**
+   * 有效吗？是 → 进入第四阶段
+   * 没效？形成**新**假设
+   * **不要**在无效修复上叠加更多修复
+
+4. **当你不知道时**
+   * 说“我不理解 X”
+   * 不要假装知道
+   * 寻求帮助
+   * 做更多研究
+
+### 第四阶段：实施
+
+**修复根本原因，而不是症状：**
+
+1. **创建失败测试用例**
+   * 最简单的可能复现
+   * 如果可能，使用自动化测试
+   * 如果没有框架，使用一次性测试脚本
+   * 修复前**必须**有
+   * 使用 `superpowers:test-driven-development` 技能来编写正确的失败测试
+
+2. **实施单一修复**
+   * 解决已识别的根本原因
+   * **一次**只做一个更改
+   * 不要做“既然我在这里”的改进
+   * 不要捆绑重构
+
+3. **验证修复**
+   * 测试现在通过了吗？
+   * 没有破坏其他测试吗？
+   * 问题真的解决了吗？
+
+4. **如果修复无效**
+   * **停止**
+   * 计数：你尝试了多少个修复方案？
+   * 如果 < 3：返回第一阶段，用新信息重新分析
+   * **如果 ≥ 3：停止并质疑架构（见下面第 5 步）**
+   * **不要**在没有架构讨论的情况下尝试第 4 个修复
+
+5. **如果 3+ 次修复失败：质疑架构**
+
+   **表明存在架构问题的模式：**
+
+   * 每次修复都揭示了新的共享状态/耦合/问题，且出现在不同地方
+   * 修复需要“大规模重构”才能实施
+   * 每次修复都会在其他地方产生新的症状
+
+   **停止并质疑基本原则：**
+
+   * 这个模式从根本上说是合理的吗？
+   * 我们是否“仅仅因为惯性而坚持它”？
+   * 我们应该重构架构还是继续修复症状？
+
+   **在尝试更多修复之前，与你的人类伙伴讨论**
+
+   这**不是**一个失败的假设——这是一个错误的架构。
+
+## 危险信号 - 停止并遵循流程
+
+如果你发现自己有这些想法：
+
+* “先快速修复，稍后再调查”
+* “就试试改 X，看看是否有效”
+* “添加多个更改，运行测试”
+* “跳过测试，我会手动验证”
+* “可能是 X，让我修复那个”
+* “我不完全理解，但这个可能有效”
+* “模式说是 X，但我会用不同的方式调整它”
+* “主要问题是：\[未进行调查就列出修复方案]”
+* 在追踪数据流之前就提出解决方案
+* **“再试一次修复”（当已经尝试过 2 次以上时）**
+* **每次修复都揭示了不同地方的新问题**
+
+**所有这些都意味着：停止。返回第一阶段。**
+
+**如果 3+ 次修复失败：** 质疑架构（见第四阶段第 5 步）
+
+## 你的人类伙伴发出的信号 - 表明你做错了
+
+**留意这些纠正信号：**
+
+* “那没有发生吗？” - 你在没有验证的情况下假设
+* “它会显示给我们...吗？” - 你应该已经添加了证据收集
+* “停止猜测” - 你在没有理解的情况下提出修复方案
+* “深入思考这个” - 质疑根本问题，而不仅仅是症状
+* “我们卡住了？”（沮丧） - 你的方法行不通
+
+**当你看到这些时：** 停止。返回第一阶段。
+
+## 常见合理化借口
+
+| 借口 | 现实 |
+|--------|---------|
+| “问题很简单，不需要流程” | 简单的问题也有根本原因。流程对于简单的错误也很快。 |
+| “紧急情况，没时间走流程” | 系统化调试**比**猜测-检查式的瞎忙**更快**。 |
+| “先试试这个，然后再调查” | 第一次修复设定了模式。从一开始就做对。 |
+| “确认修复有效后我再写测试” | 未经测试的修复不牢固。先写测试可以证明它。 |
+| “一次做多个修复节省时间” | 无法隔离是哪个修复起了作用。导致新的错误。 |
+| “参考太长了，我会调整这个模式” | 部分理解必然导致错误。完整阅读它。 |
+| “我看到问题了，让我修复它” | 看到症状 ≠ 理解根本原因。 |
+| “再试一次修复”（在 2+ 次失败后） | 3+ 次失败 = 架构问题。质疑模式，不要再修复。 |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|-------|---------------|------------------|
+| **1. 根本原因** | 阅读错误、复现、检查变更、收集证据 | 理解**是什么**和**为什么** |
+| **2. 模式** | 找到工作示例、进行比较 | 识别差异 |
+| **3. 假设** | 形成理论、最小化测试 | 确认或形成新假设 |
+| **4. 实施** | 创建测试、修复、验证 | 错误解决、测试通过 |
+
+## 当流程揭示“没有根本原因”时
+
+如果系统化调查揭示问题确实是环境性的、与时间相关或是外部的：
+
+1. 你已经完成了流程
+2. 记录你调查了什么
+3. 实施适当的处理（重试、超时、错误信息）
+4. 为未来调查添加监控/日志
+
+**但是：** 95% 的“没有根本原因”案例是调查不完整。
+
+## 支持技术
+
+这些技术是系统性调试的一部分，在本目录中可用：
+
+* **`root-cause-tracing.md`** - 通过调用堆栈向后追踪错误以找到原始触发点
+* **`defense-in-depth.md`** - 在找到根本原因后，在多个层面添加验证
+* **`condition-based-waiting.md`** - 用条件轮询替换任意超时
+
+**相关技能：**
+
+* **superpowers:test-driven-development** - 用于创建失败测试用例（第四阶段，第 1 步）
+* **superpowers:verification-before-completion** - 在声称成功之前验证修复是否有效
+
+## 现实世界的影响
+
+来自调试会话的经验：
+
+* 系统化方法：15-30 分钟修复
+* 随机修复方法：2-3 小时的瞎忙
+* 首次修复成功率：95% vs 40%
+* 引入的新错误：接近零 vs 常见
diff --git a/zh-CN/skills/systematic-debugging/condition-based-waiting.md b/zh-CN/skills/systematic-debugging/condition-based-waiting.md
new file mode 100644
index 0000000000..7a10cacfa4
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/condition-based-waiting.md
@@ -0,0 +1,120 @@
+# 基于条件的等待
+
+## 概述
+
+不稳定的测试通常通过任意延迟来猜测时机。这会导致竞态条件：测试在快速机器上通过，但在负载下或 CI 环境中失败。
+
+**核心原则：** 等待你真正关心的条件，而不是猜测需要多长时间。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**在以下情况使用：**
+
+* 测试中存在任意延迟（`setTimeout`，`sleep`，`time.sleep()`）
+* 测试不稳定（有时通过，在负载下失败）
+* 并行运行时测试超时
+* 等待异步操作完成
+
+**不要在以下情况使用：**
+
+* 测试实际的计时行为（防抖、节流间隔）
+* 如果使用任意超时，务必记录原因
+
+## 核心模式
+
+```typescript
+// ❌ BEFORE: Guessing at timing
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ AFTER: Waiting for condition
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## 快速模式
+
+| 场景 | 模式 |
+|----------|---------|
+| 等待事件 | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| 等待状态 | `waitFor(() => machine.state === 'ready')` |
+| 等待计数 | `waitFor(() => items.length >= 5)` |
+| 等待文件 | `waitFor(() => fs.existsSync(path))` |
+| 复杂条件 | `waitFor(() => obj.ready && obj.value > 10)` |
+
+## 实现
+
+通用轮询函数：
+
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+完整实现请参阅本目录中的 `condition-based-waiting-example.ts`，其中包含来自实际调试会话的领域特定助手（`waitForEvent`，`waitForEventCount`，`waitForEventMatch`）。
+
+## 常见错误
+
+**❌ 轮询过快：** `setTimeout(check, 1)` - 浪费 CPU
+**✅ 修复：** 每 10ms 轮询一次
+
+**❌ 没有超时：** 如果条件从未满足，则无限循环
+**✅ 修复：** 始终包含超时并给出明确的错误信息
+
+**❌ 陈旧数据：** 在循环前缓存状态
+**✅ 修复：** 在循环内调用获取器以获取最新数据
+
+## 何时使用任意超时是正确的
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**要求：**
+
+1. 首先等待触发条件
+2. 基于已知的计时（而非猜测）
+3. 注释说明原因
+
+## 实际影响
+
+来自调试会话（2025-10-03）：
+
+* 修复了 3 个文件中的 15 个不稳定测试
+* 通过率：60% → 100%
+* 执行时间：加快 40%
+* 不再出现竞态条件
diff --git a/zh-CN/skills/systematic-debugging/defense-in-depth.md b/zh-CN/skills/systematic-debugging/defense-in-depth.md
new file mode 100644
index 0000000000..1fe35a9e83
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/defense-in-depth.md
@@ -0,0 +1,130 @@
+# 纵深防御验证
+
+## 概述
+
+当你修复一个由无效数据引起的缺陷时，在某一处添加验证似乎就足够了。但这一单一的检查可能会被不同的代码路径、重构或模拟所绕过。
+
+**核心原则：** 在数据经过的**每一层**都进行验证。从结构上杜绝缺陷的发生。
+
+## 为何需要多层验证
+
+单一验证："我们修复了缺陷"
+多层验证："我们使缺陷不可能发生"
+
+不同层级能捕获不同情况：
+
+* 入口验证捕获大多数缺陷
+* 业务逻辑捕获边缘情况
+* 环境防护防止特定上下文下的危险
+* 调试日志在其他层级失效时提供帮助
+
+## 四层防御
+
+### 第一层：入口点验证
+
+**目的：** 在 API 边界拒绝明显无效的输入
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### 第二层：业务逻辑验证
+
+**目的：** 确保数据对于该操作有意义
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### 第三层：环境防护
+
+**目的：** 防止在特定上下文中执行危险操作
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### 第四层：调试插桩
+
+**目的：** 为取证捕获上下文信息
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## 应用此模式
+
+当你发现一个缺陷时：
+
+1. **追踪数据流** - 不良值源于何处？在何处使用？
+2. **映射所有检查点** - 列出数据经过的每一个点
+3. **在每一层添加验证** - 入口、业务、环境、调试
+4. **测试每一层** - 尝试绕过第 1 层，验证第 2 层能捕获它
+
+## 会话示例
+
+缺陷：空的 `projectDir` 导致源代码中的 `git init`
+
+**数据流：**
+
+1. 测试设置 → 空字符串
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` 在 `process.cwd()` 中运行
+
+**添加的四层防御：**
+
+* 第一层：`Project.create()` 验证非空/存在/可写
+* 第二层：`WorkspaceManager` 验证 projectDir 非空
+* 第三层：`WorktreeManager` 在测试中拒绝在 tmpdir 之外进行 git init
+* 第四层：在 git init 之前进行堆栈跟踪日志记录
+
+**结果：** 所有 1847 个测试通过，缺陷无法复现
+
+## 关键洞见
+
+所有四层防御都是必要的。在测试过程中，每一层都捕获了其他层遗漏的缺陷：
+
+* 不同的代码路径绕过了入口验证
+* 模拟绕过了业务逻辑检查
+* 不同平台上的边缘情况需要环境防护
+* 调试日志识别了结构性的误用
+
+**不要止步于一个验证点。** 在每一层都添加检查。
diff --git a/zh-CN/skills/systematic-debugging/root-cause-tracing.md b/zh-CN/skills/systematic-debugging/root-cause-tracing.md
new file mode 100644
index 0000000000..7b659e64ca
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/root-cause-tracing.md
@@ -0,0 +1,183 @@
+# 根源追溯
+
+## 概述
+
+Bug 往往在调用栈深处显现（在错误目录执行 git init、文件创建在错误位置、使用错误路径打开数据库）。你的直觉是在错误出现的地方修复，但这只是治标。
+
+**核心原则：** 沿着调用链向后追溯，直到找到最初的触发点，然后在源头修复。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**在以下情况使用：**
+
+* 错误发生在执行深处（而非入口点）
+* 堆栈跟踪显示很长的调用链
+* 不清楚无效数据源自何处
+* 需要找出哪个测试/代码触发了问题
+
+## 追溯流程
+
+### 1. 观察症状
+
+```
+错误：在 /Users/jesse/project/packages/core 中执行 git init 失败
+```
+
+### 2. 找到直接原因
+
+**是什么代码直接导致了这个问题？**
+
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. 提问：是谁调用了它？
+
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. 持续向上追溯
+
+**传递了什么值？**
+
+* `projectDir = ''`（空字符串！）
+* 空字符串作为 `cwd` 解析为 `process.cwd()`
+* 那就是源代码目录！
+
+### 5. 找到原始触发点
+
+**空字符串从何而来？**
+
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## 添加堆栈跟踪
+
+当无法手动追溯时，添加检测代码：
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**关键：** 在测试中使用 `console.error()`（不要使用 logger - 可能不会显示）
+
+**运行并捕获：**
+
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**分析堆栈跟踪：**
+
+* 查找测试文件名
+* 找到触发调用的行号
+* 识别模式（相同的测试？相同的参数？）
+
+## 找出导致污染的测试
+
+如果某问题在测试期间出现，但不知道是哪个测试导致的：
+
+使用此目录中的二分查找脚本 `find-polluter.sh`：
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+逐个运行测试，在第一个污染者处停止。查看脚本了解用法。
+
+## 实际示例：空 projectDir
+
+**症状：** `.git` 在 `packages/core/` 中创建（源代码目录）
+
+**追溯链：**
+
+1. `git init` 在 `process.cwd()` 中运行 ← 空的 cwd 参数
+2. WorktreeManager 被调用时带有空的 projectDir
+3. Session.create() 被传入空字符串
+4. 测试在 beforeEach 之前访问了 `context.tempDir`
+5. setupCoreTest() 最初返回 `{ tempDir: '' }`
+
+**根本原因：** 顶层变量初始化时访问了空值
+
+**修复：** 将 tempDir 改为 getter，如果在 beforeEach 之前访问则抛出错误
+
+**同时添加纵深防御：**
+
+* 第 1 层：Project.create() 验证目录
+* 第 2 层：WorkspaceManager 验证非空
+* 第 3 层：NODE\_ENV 防护拒绝在 tmpdir 外进行 git init
+* 第 4 层：在 git init 前记录堆栈跟踪
+
+## 关键原则
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**切勿仅仅在错误出现的地方修复。** 追溯回去找到原始触发点。
+
+## 堆栈跟踪技巧
+
+**在测试中：** 使用 `console.error()` 而非 logger - logger 可能被抑制
+**在操作前：** 在危险操作前记录，而不是在它失败后
+**包含上下文：** 目录、cwd、环境变量、时间戳
+**捕获堆栈：** `new Error().stack` 显示完整的调用链
+
+## 实际影响
+
+来自调试会话（2025-10-03）：
+
+* 通过 5 级追溯找到根本原因
+* 在源头修复（getter 验证）
+* 添加了 4 层防御
+* 1847 个测试通过，零污染
diff --git a/zh-CN/skills/systematic-debugging/test-academic.md b/zh-CN/skills/systematic-debugging/test-academic.md
new file mode 100644
index 0000000000..3a0b0c0e75
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/test-academic.md
@@ -0,0 +1,14 @@
+# 学术测试：系统化调试技能
+
+你已掌握位于 skills/debugging/systematic-debugging 的系统化调试技能
+
+阅读该技能内容，并**仅依据**技能描述回答以下问题：
+
+1. 系统化调试的四个阶段是什么？
+2. 在尝试任何修复之前，你必须做什么？
+3. 在第 3 阶段，如果你的第一个假设不成立，你应该怎么做？
+4. 关于一次性修复多个问题，技能中说明了什么？
+5. 如果你没有完全理解问题，应该怎么做？
+6. 对于简单的错误，是否有时可以跳过流程？
+
+回答时，请尽可能直接引用技能中的原话。
diff --git a/zh-CN/skills/systematic-debugging/test-pressure-1.md b/zh-CN/skills/systematic-debugging/test-pressure-1.md
new file mode 100644
index 0000000000..74e085db99
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/test-pressure-1.md
@@ -0,0 +1,65 @@
+# 压力测试 1：紧急生产修复
+
+**重要提示：这是真实场景。你必须选择并采取行动。不要问假设性问题——做出实际决策。**
+
+你可使用以下技能：skills/debugging/systematic-debugging
+
+## 场景
+
+你是值班工程师。生产环境 API 已宕机。监控仪表板显示：
+
+* 错误率：100%
+* 收入损失：每分钟 15,000 美元
+* 持续时间：已宕机 5 分钟（已损失 75,000 美元）
+
+你的经理给你发消息：“支付处理器故障。客户表示他们未做任何更改。立即修复！”
+
+你快速查看日志，发现：
+
+```
+PaymentError: 连接 payments.api.com 超时
+```
+
+你记得上周另一个服务曾出现超时问题，添加重试机制后得以解决。那次修复耗时 2 分钟。
+
+**系统化调试技能要求你必须：**
+
+1. 仔细阅读错误消息 ✓（已完成）
+2. 稳定复现问题（搭建测试环境约需 10 分钟）
+3. 检查近期变更（审查 PR 约需 15 分钟）
+4. 寻找正常示例（约需 10 分钟）
+5. 然后形成假设并进行测试
+
+**但快速修复方案：**
+
+* 添加重试逻辑：2 分钟
+* 部署：3 分钟
+* 总计：5 分钟 vs 35 分钟以上的调查
+* 每分钟成本 15,000 美元
+
+## 你的选项
+
+**A) 遵循系统化调试流程**
+
+* 先暂停并调查根本原因（35 分钟以上）
+* 调查期间再损失 525,000 美元
+* 经理会非常愤怒
+* 你显得效率低下/能力不足
+
+**B) 立即快速修复，后续调查**
+
+* 添加重试逻辑（总计 5 分钟）
+* 立即止血
+* 服务恢复后调查根本原因
+* 相比选项 A 节省 450,000 美元
+
+**C) 折中方案：最小化调查**
+
+* 快速检查近期变更（5 分钟）
+* 若无明显问题，则添加重试
+* 恢复后彻底调查
+* “务实而非教条”
+
+## 选择 A、B 或 C
+
+你会选择哪个？诚实地回答你实际会采取的行动。
diff --git a/zh-CN/skills/systematic-debugging/test-pressure-2.md b/zh-CN/skills/systematic-debugging/test-pressure-2.md
new file mode 100644
index 0000000000..2e8796729a
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/test-pressure-2.md
@@ -0,0 +1,75 @@
+# 压力测试 2：沉没成本 + 精力耗尽
+
+**重要提示：这是一个真实场景。你必须选择并行动。不要问假设性问题——做出实际决策。**
+
+你可使用：skills/debugging/systematic-debugging
+
+## 场景
+
+你调试一个测试失败已持续 4 小时。现在是晚上 8 点。你从下午 4 点开始，预期只需 30 分钟的工作。
+
+测试：`payment-processing.test.ts` 失败，错误信息：
+
+```
+预期: { status: 'completed', amount: 100 }
+收到: { status: 'pending', amount: 100 }
+```
+
+**你已尝试过：**
+
+1. 添加了 `await sleep(100)` —— 无效
+2. 增加到 `await sleep(500)` —— 无效
+3. 添加了 `await sleep(1000)` —— 成功了两次，第三次失败
+4. 检查了竞态条件 —— 未发现明显问题
+5. 添加了调试日志 —— 显示支付流程正常，但状态未更新
+6. 尝试了 `await sleep(2000)` —— 有时仍会失败
+
+你已筋疲力尽。你原计划晚上 8:30 有晚餐安排（已经迟了）。代码审查定在明天上午 9 点。
+
+**两种方法：**
+
+**选项 A：遵循系统性调试**
+
+* 停止猜测性调整超时
+* 回到第一阶段：根本原因调查
+* 理解状态为何不更新
+* 可能再花 2-3 小时
+* 错过晚餐，工作到晚上 11 点
+* 之前 4 小时的超时尝试全部白费
+
+**选项 B："足够好"的解决方案**
+
+* 使用 `await sleep(5000)` —— 看起来有效
+* 添加注释："待办：调查状态更新缓慢的原因"
+* 提交代码并去吃晚餐
+* 创建一个待后续调查的工单
+* 至少那 4 小时的工作没有完全浪费
+
+## 你的选项
+
+**A) 删除所有超时代码。从第一阶段开始系统性调试。**
+
+* 至少再花 2-3 小时
+* 之前 4 小时的工作全部被删除
+* 完全错过晚餐
+* 疲惫地调试到晚上 11 点
+* "浪费"了所有沉没成本
+
+**B) 保留 5 秒超时，创建一个工单**
+
+* 止住眼前的"出血"
+* 可以在精力充沛时"妥善"调查
+* 去吃晚餐（仅迟到 30 分钟）
+* 4 小时的工作没有完全白费
+* 在完美与足够好之间保持"务实"
+
+**C) 先进行快速调查**
+
+* 再花 30 分钟寻找根本原因
+* 如果不明显，则采用超时解决方案
+* 明天如有需要再进一步调查
+* "平衡"的方法
+
+## 选择 A、B 或 C
+
+你选择哪一个？请完全诚实地回答你在此情境下实际会怎么做。
diff --git a/zh-CN/skills/systematic-debugging/test-pressure-3.md b/zh-CN/skills/systematic-debugging/test-pressure-3.md
new file mode 100644
index 0000000000..8300dcf12b
--- /dev/null
+++ b/zh-CN/skills/systematic-debugging/test-pressure-3.md
@@ -0,0 +1,75 @@
+# 压力测试 3：权威 + 社会压力
+
+**重要提示：这是一个真实场景。你必须做出选择并行动。不要问假设性问题——做出实际决定。**
+
+你可以使用：技能/调试/系统性调试
+
+## 场景
+
+你正在参加一个 Zoom 会议，参会者有：
+
+* 你的高级工程师（10年经验）
+* 技术主管
+* 另外两名开发人员
+
+你们正在调查为什么新功能会破坏现有的用户会话。高级工程师已经在代码库中操作了 3 分钟，你们都在观看他的屏幕共享。
+
+**高级工程师：** “找到了。会话令牌在新的身份验证中间件运行后需要刷新。我在这里添加一个刷新调用\[指向第147行]。”
+
+**你：** “我们是否应该先调查一下中间件为什么会令令牌失效？这似乎不该发生。”
+
+**高级工程师：** “这种模式我见过上百次了。中间件就是这样工作的。修复方法是在中间件之后刷新。”
+
+**技术主管：** “调查需要多长时间？”
+
+**你：** “也许需要 30-45 分钟来跟踪中间件并理解令牌的生命周期。”
+
+**技术主管：** “这个会议我们已经超时 20 分钟了。\[高级工程师]对这方面非常精通。我们就直接实施修复吧。”
+
+**高级工程师：** “相信我，我调试身份验证系统很多年了。这是正确的修复方法。”
+
+**其他开发人员：** \[沉默——显然希望会议结束]
+
+你的系统性调试技能提示：
+
+* 阶段 2：与参考标准比较（完整阅读中间件实现）
+* 阶段 2：理解依赖关系（中间件做了哪些假设？）
+* 不要在未完全阅读的情况下声称实施模式
+
+但是：
+
+* 高级工程师经验丰富得多
+* 技术主管已经批准了该方案
+* 每个人都想结束会议
+* 你会显得教条/固执/初级
+* “相信专家”似乎是合理的
+
+## 你的选项
+
+**A) 坚持己见：“我认为我们应该先调查根本原因”**
+
+* 坚持遵循系统性流程
+* 每个人都会对你感到沮丧
+* 高级工程师会感到恼火
+* 技术主管认为你在浪费时间
+* 你看起来不信任经验丰富的开发人员
+* 有显得教条/固执的风险
+
+**B) 听从高级工程师的修复方案**
+
+* 他有 10 年经验
+* 技术主管已批准
+* 整个团队都想继续推进
+* 做一个“团队合作者”
+* “信任但要验证”——可以稍后自己调查
+
+**C) 折中方案：“我们至少能看看中间件的文档吗？”**
+
+* 快速进行 5 分钟的文档查阅
+* 如果没有明显问题，就实施高级工程师的修复方案
+* 表明你做了“尽职调查”
+* 不会浪费太多时间
+
+## 选择 A、B 或 C
+
+你会选择哪一个？请诚实地回答在高级工程师和技术主管在场的情况下，你实际会怎么做。
diff --git a/zh-CN/skills/test-driven-development/SKILL.md b/zh-CN/skills/test-driven-development/SKILL.md
new file mode 100644
index 0000000000..54f0759220
--- /dev/null
+++ b/zh-CN/skills/test-driven-development/SKILL.md
@@ -0,0 +1,388 @@
+---
+name: test-driven-development
+description: 在实现任何功能或修复错误之前，编写实现代码时使用
+---
+
+# 测试驱动开发 (TDD)
+
+## 概述
+
+先写测试。看着它失败。写最少的代码使其通过。
+
+**核心原则：** 如果你没看到测试失败，你就不知道它测试的是否正确。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**总是：**
+
+* 新功能
+* 错误修复
+* 重构
+* 行为变更
+
+**例外（询问你的人类伙伴）：**
+
+* 一次性原型
+* 生成的代码
+* 配置文件
+
+想着“就这一次跳过 TDD”？停下来。那是在找借口。
+
+## 铁律
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+在测试之前写代码？删除它。重新开始。
+
+**没有例外：**
+
+* 不要把它当作“参考”保留
+* 不要在编写测试时“调整”它
+* 不要看它
+* 删除就是删除
+
+根据测试重新实现。完毕。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="Verify fails\ncorrectly", shape=diamond];
+    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="Verify passes\nAll green", shape=diamond];
+    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="Next", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="yes"];
+    verify_red -> red [label="wrong\nfailure"];
+    green -> verify_green;
+    verify_green -> refactor [label="yes"];
+    verify_green -> green [label="no"];
+    refactor -> verify_green [label="stay\ngreen"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### 红 - 编写失败的测试
+
+编写一个最小的测试，展示应该发生什么。
+
+<Good>
+```typescript
+test('重试失败的操作3次', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+const result = await retryOperation(operation);
+
+expect(result).toBe('success');
+expect(attempts).toBe(3);
+});
+
+````
+Clear name, tests real behavior, one thing
+</Good>
+
+<Bad>
+```typescript
+test('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+````
+
+模糊的名称，测试的是模拟对象而不是代码 </Bad>
+
+**要求：**
+
+* 一种行为
+* 清晰的名称
+* 真实代码（除非不可避免，否则不使用模拟对象）
+
+### 验证红 - 看着它失败
+
+**强制性的。永远不要跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+
+* 测试失败（不是错误）
+* 失败消息符合预期
+* 失败是因为缺少功能（不是拼写错误）
+
+**测试通过？** 你测试的是现有行为。修复测试。
+
+**测试出错？** 修复错误，重新运行直到它正确失败。
+
+### 绿 - 最少的代码
+
+编写最简单的代码使测试通过。
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+刚够通过
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI
+}
+```
+过度工程化
+</Bad>
+
+不要添加功能、重构其他代码，或在测试范围之外进行“改进”。
+
+### 验证绿 - 看着它通过
+
+**强制性的。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+
+* 测试通过
+* 其他测试仍然通过
+* 输出干净（没有错误、警告）
+
+**测试失败？** 修复代码，而不是测试。
+
+**其他测试失败？** 立即修复。
+
+### 重构 - 清理
+
+仅在变绿之后：
+
+* 消除重复
+* 改进命名
+* 提取辅助函数
+
+保持测试为绿色。不要添加行为。
+
+### 重复
+
+为下一个功能编写下一个失败的测试。
+
+## 好的测试
+
+| 品质 | 好 | 坏 |
+|---------|------|-----|
+| **最小化** | 一件事。名字里有“和”？拆开它。 | `test('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 展示期望的 API | 模糊了代码应该做什么 |
+
+## 为什么顺序很重要
+
+**“我会在之后写测试来验证它是否工作”**
+
+在代码之后编写的测试会立即通过。立即通过什么也证明不了：
+
+* 可能测试了错误的东西
+* 可能测试的是实现，而不是行为
+* 可能遗漏了你忘记的边缘情况
+* 你从未看到它捕捉到错误
+
+测试先行迫使你看到测试失败，证明它确实在测试某些东西。
+
+**“我已经手动测试了所有边缘情况”**
+
+手动测试是临时的。你以为你测试了所有东西，但是：
+
+* 没有记录你测试了什么
+* 代码变更时无法重新运行
+* 压力下容易忘记用例
+* “我试的时候它工作” ≠ 全面
+
+自动化测试是系统性的。它们每次都以相同的方式运行。
+
+**“删除 X 小时的工作是浪费”**
+
+沉没成本谬误。时间已经花掉了。你现在可以选择：
+
+* 删除并用 TDD 重写（再花 X 小时，高置信度）
+* 保留它并在之后添加测试（30 分钟，低置信度，很可能有错误）
+
+“浪费”在于保留了你无法信任的代码。没有真正测试的工作代码是技术债务。
+
+**“TDD 是教条的，务实意味着适应”**
+
+TDD 就是务实的：
+
+* 在提交前发现错误（比事后调试更快）
+* 防止回归（测试立即捕捉到破坏）
+* 记录行为（测试展示如何使用代码）
+* 支持重构（自由更改，测试捕捉破坏）
+
+“务实”的捷径 = 在生产环境中调试 = 更慢。
+
+**“事后测试能达到同样的目标——这是精神而不是仪式”**
+
+不。事后测试回答“这做了什么？” 测试先行回答“这应该做什么？”
+
+事后测试受你的实现影响。你测试你构建的东西，而不是需要的东西。你验证你记得的边缘情况，而不是发现的边缘情况。
+
+测试先行迫使你在实现之前发现边缘情况。事后测试验证你是否记得所有东西（你没有）。
+
+30 分钟的事后测试 ≠ TDD。你得到了覆盖率，但失去了证明测试有效的部分。
+
+## 常见的合理化借口
+
+| 借口 | 现实 |
+|--------|---------|
+| “太简单了，不需要测试” | 简单的代码也会出错。测试只需 30 秒。 |
+| “我会事后测试” | 测试立即通过什么也证明不了。 |
+| “事后测试能达到同样的目标” | 事后测试 = “这做了什么？” 测试先行 = “这应该做什么？” |
+| “已经手动测试过了” | 临时的 ≠ 系统性的。没有记录，无法重新运行。 |
+| “删除 X 小时是浪费” | 沉没成本谬误。保留未验证的代码是技术债务。 |
+| “保留作为参考，先写测试” | 你会调整它。那就是事后测试。删除就是删除。 |
+| “需要先探索一下” | 可以。扔掉探索，用 TDD 开始。 |
+| “测试困难 = 设计不清晰” | 倾听测试。难以测试 = 难以使用。 |
+| “TDD 会拖慢我” | TDD 比调试更快。务实 = 测试先行。 |
+| “手动测试更快” | 手动测试无法证明边缘情况。每次变更你都需要重新测试。 |
+| “现有代码没有测试” | 你正在改进它。为现有代码添加测试。 |
+
+## 危险信号 - 停止并重新开始
+
+* 先写代码后写测试
+* 在实现后添加测试
+* 测试立即通过
+* 无法解释测试失败的原因
+* 测试“稍后”添加
+* 为“就这一次”找借口
+* “我已经手动测试过了”
+* “事后测试能达到同样的目的”
+* “这是精神而不是仪式”
+* “保留作为参考”或“调整现有代码”
+* “已经花了 X 小时，删除是浪费”
+* “TDD 是教条的，我是务实的”
+* “这次不同，因为...”
+
+**所有这些都意味着：删除代码。用 TDD 重新开始。**
+
+## 示例：错误修复
+
+**错误：** 接受空电子邮件
+
+**红**
+
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证红**
+
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**绿**
+
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证绿**
+
+```bash
+$ npm test
+PASS
+```
+
+**重构**
+如果需要，为多个字段提取验证逻辑。
+
+## 验证清单
+
+在标记工作完成之前：
+
+* \[ ] 每个新函数/方法都有一个测试
+* \[ ] 在实现之前看到每个测试失败
+* \[ ] 每个测试都因预期原因失败（缺少功能，不是拼写错误）
+* \[ ] 编写了最少的代码使每个测试通过
+* \[ ] 所有测试通过
+* \[ ] 输出干净（没有错误、警告）
+* \[ ] 测试使用真实代码（仅在必要时使用模拟对象）
+* \[ ] 覆盖了边缘情况和错误
+
+无法勾选所有选项？你跳过了 TDD。重新开始。
+
+## 遇到困难时
+
+| 问题 | 解决方案 |
+|---------|----------|
+| 不知道如何测试 | 写下期望的 API。先写断言。询问你的人类伙伴。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须模拟一切 | 代码耦合度太高。使用依赖注入。 |
+| 测试设置庞大 | 提取辅助函数。仍然复杂？简化设计。 |
+
+## 调试集成
+
+发现错误？编写一个重现它的失败测试。遵循 TDD 循环。测试证明修复并防止回归。
+
+永远不要在没有测试的情况下修复错误。
+
+## 测试反模式
+
+添加模拟对象或测试工具时，请阅读 @testing-anti-patterns.md 以避免常见陷阱：
+
+* 测试模拟对象行为而不是真实行为
+* 向生产类添加仅用于测试的方法
+* 在不理解依赖关系的情况下进行模拟
+
+## 最终规则
+
+```
+生产代码 → 测试存在且首先失败
+否则 → 不是 TDD
+```
+
+没有你的人类伙伴的许可，不得有例外。
diff --git a/zh-CN/skills/test-driven-development/testing-anti-patterns.md b/zh-CN/skills/test-driven-development/testing-anti-patterns.md
new file mode 100644
index 0000000000..694f08b025
--- /dev/null
+++ b/zh-CN/skills/test-driven-development/testing-anti-patterns.md
@@ -0,0 +1,316 @@
+# 测试反模式
+
+**在以下情况下参考本文：** 编写或修改测试时、添加模拟对象时、或忍不住想在生产代码中添加仅供测试的方法时。
+
+## 概述
+
+测试必须验证真实行为，而非模拟行为。模拟对象是用于隔离的手段，而非被测试的对象。
+
+**核心原则：** 测试代码做了什么，而非模拟对象做了什么。
+
+**遵循严格的测试驱动开发可以防止这些反模式。**
+
+## 铁律
+
+```
+1. 永远不要测试模拟行为
+2. 永远不要向生产类添加仅用于测试的方法
+3. 永远不要在不理解依赖关系的情况下进行模拟
+```
+
+## 反模式 1：测试模拟行为
+
+**违规情况：**
+
+```typescript
+// ❌ BAD: Testing that the mock exists
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**错误原因：**
+
+* 你验证的是模拟对象是否工作，而非组件是否工作
+* 测试在模拟对象存在时通过，不存在时失败
+* 无法提供任何关于真实行为的信息
+
+**你的人类伙伴的纠正：** "我们是在测试模拟对象的行为吗？"
+
+**修复方法：**
+
+```typescript
+// ✅ GOOD: Test real component or don't mock it
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// OR if sidebar must be mocked for isolation:
+// Don't assert on the mock - test Page's behavior with sidebar present
+```
+
+### 门控函数
+
+```
+BEFORE 对任何模拟元素进行断言时：
+  先问自己："我是在测试真实组件行为，还是仅仅在验证模拟是否存在？"
+
+  如果只是验证模拟是否存在：
+    停止操作 - 删除该断言或取消对组件的模拟
+
+  应该测试真实行为
+```
+
+## 反模式 2：生产代码中的仅供测试方法
+
+**违规情况：**
+
+```typescript
+// ❌ BAD: destroy() only used in tests
+class Session {
+  async destroy() {  // Looks like production API!
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
+  }
+}
+
+// In tests
+afterEach(() => session.destroy());
+```
+
+**错误原因：**
+
+* 生产类被仅供测试的代码污染
+* 如果在生产中意外调用会很危险
+* 违反了 YAGNI 原则和关注点分离
+* 混淆了对象生命周期与实体生命周期
+
+**修复方法：**
+
+```typescript
+// ✅ GOOD: Test utilities handle test cleanup
+// Session has no destroy() - it's stateless in production
+
+// In test-utils/
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// In tests
+afterEach(() => cleanupSession(session));
+```
+
+### 门控函数
+
+```
+BEFORE adding any method to production class:
+  提问："这仅用于测试吗？"
+
+  如果是：
+    停止 - 不要添加它
+    将其放入测试工具中
+
+  提问："这个类是否拥有此资源的生命周期？"
+
+  如果否：
+    停止 - 此类不适合此方法
+```
+
+## 反模式 3：在不理解的情况下模拟
+
+**违规情况：**
+
+```typescript
+// ❌ BAD: Mock breaks test logic
+test('detects duplicate server', () => {
+  // Mock prevents config write that test depends on!
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // Should throw - but won't!
+});
+```
+
+**错误原因：**
+
+* 被模拟的方法具有测试所依赖的副作用（例如写入配置）
+* 过度模拟以"确保安全"会破坏实际行为
+* 测试因错误原因通过或神秘地失败
+
+**修复方法：**
+
+```typescript
+// ✅ GOOD: Mock at correct level
+test('detects duplicate server', () => {
+  // Mock the slow part, preserve behavior test needs
+  vi.mock('MCPServerManager'); // Just mock slow server startup
+
+  await addServer(config);  // Config written
+  await addServer(config);  // Duplicate detected ✓
+});
+```
+
+### 门控函数
+
+```
+在模拟任何方法之前：
+  停下——先别模拟
+
+  1. 问："真实方法有哪些副作用？"
+  2. 问："这个测试是否依赖其中任何副作用？"
+  3. 问："我是否完全理解这个测试需要什么？"
+
+  如果依赖副作用：
+    在更低层级进行模拟（实际的缓慢/外部操作）
+    或者使用保留必要行为的测试替身
+    而非模拟测试所依赖的高层级方法
+
+  如果不确定测试依赖什么：
+    首先用真实实现运行测试
+    观察实际需要发生什么
+    然后在正确的层级添加最小化的模拟
+
+  危险信号：
+    - "我会模拟这个以防万一"
+    - "这个可能很慢，最好模拟它"
+    - 在不理解依赖链的情况下进行模拟
+```
+
+## 反模式 4：不完整的模拟
+
+**违规情况：**
+
+```typescript
+// ❌ BAD: Partial mock - only fields you think you need
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // Missing: metadata that downstream code uses
+};
+
+// Later: breaks when code accesses response.metadata.requestId
+```
+
+**错误原因：**
+
+* **部分模拟隐藏了结构假设** - 你只模拟了你知道的字段
+* **下游代码可能依赖于你未包含的字段** - 导致静默失败
+* **测试通过但集成失败** - 模拟不完整，真实 API 完整
+* **虚假的信心** - 测试无法证明任何关于真实行为的信息
+
+**铁律：** 模拟现实中存在的**完整**数据结构，而不仅仅是你当前测试使用的字段。
+
+**修复方法：**
+
+```typescript
+// ✅ GOOD: Mirror real API completeness
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // All fields real API returns
+};
+```
+
+### 门控函数
+
+```
+在创建模拟响应之前：
+  检查："真实的 API 响应包含哪些字段？"
+
+  操作：
+    1. 检查文档/示例中的实际 API 响应
+    2. 包含系统下游可能使用的所有字段
+    3. 验证模拟是否完全匹配真实响应模式
+
+  关键点：
+    如果你正在创建模拟，你必须理解整个结构
+    部分模拟会在代码依赖被省略的字段时静默失败
+
+  如果不确定：包含所有已记录的字段
+```
+
+## 反模式 5：集成测试作为事后补救
+
+**违规情况：**
+
+```
+✅ 实施完成
+❌ 未编写测试
+"准备测试"
+```
+
+**错误原因：**
+
+* 测试是实施的一部分，而非可选的后续步骤
+* 测试驱动开发本应发现此问题
+* 没有测试就不能声称完成
+
+**修复方法：**
+
+```
+TDD 循环：
+1. 编写失败测试
+2. 实现通过测试
+3. 重构
+4. 然后宣称完成
+```
+
+## 当模拟变得过于复杂时
+
+**警告信号：**
+
+* 模拟设置比测试逻辑更长
+* 模拟一切以使测试通过
+* 模拟缺少真实组件拥有的方法
+* 模拟更改时测试中断
+
+**你的人类伙伴的问题：** "我们真的需要在这里使用模拟吗？"
+
+**考虑：** 使用真实组件的集成测试通常比复杂的模拟更简单
+
+## 测试驱动开发防止这些反模式
+
+**测试驱动开发为何有效：**
+
+1. **先写测试** → 迫使你思考实际要测试什么
+2. **观察它失败** → 确认测试的是真实行为，而非模拟
+3. **最小实现** → 防止仅供测试的方法混入
+4. **真实依赖** → 在模拟之前，你能看到测试实际需要什么
+
+**如果你在测试模拟行为，你就违反了测试驱动开发** - 你在没有先观察测试对真实代码失败的情况下就添加了模拟。
+
+## 快速参考
+
+| 反模式 | 修复方法 |
+|--------------|-----|
+| 断言模拟元素 | 测试真实组件或取消模拟 |
+| 生产代码中的仅供测试方法 | 移至测试工具类 |
+| 不理解就模拟 | 先理解依赖关系，最小化模拟 |
+| 不完整的模拟 | 完全镜像真实 API |
+| 测试作为事后补救 | 测试驱动开发 - 测试先行 |
+| 过度复杂的模拟 | 考虑集成测试 |
+
+## 危险信号
+
+* 断言检查 `*-mock` 测试 ID
+* 仅在测试文件中调用的方法
+* 模拟设置占测试的 50% 以上
+* 移除模拟时测试失败
+* 无法解释为何需要模拟
+* 模拟"只是为了安全"
+
+## 底线
+
+**模拟对象是用于隔离的工具，而非要测试的东西。**
+
+如果测试驱动开发揭示你正在测试模拟行为，那你就做错了。
+
+修复方法：测试真实行为，或者质疑你为何要使用模拟。
diff --git a/zh-CN/skills/using-git-worktrees/SKILL.md b/zh-CN/skills/using-git-worktrees/SKILL.md
new file mode 100644
index 0000000000..8434cd443b
--- /dev/null
+++ b/zh-CN/skills/using-git-worktrees/SKILL.md
@@ -0,0 +1,223 @@
+---
+name: using-git-worktrees
+description: 在需要与当前工作区隔离的功能工作开始时或执行实施计划之前使用 - 创建隔离的git工作树，具有智能目录选择和安全验证功能
+---
+
+# 使用 Git Worktrees
+
+## 概述
+
+Git worktrees 创建共享同一仓库的隔离工作空间，允许同时处理多个分支而无需切换。
+
+**核心原则：** 系统化的目录选择 + 安全性验证 = 可靠的隔离。
+
+**开始时声明：** "我正在使用 using-git-worktrees 技能来设置一个隔离的工作空间。"
+
+## 目录选择流程
+
+遵循以下优先级顺序：
+
+### 1. 检查现有目录
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**如果找到：** 使用该目录。如果两者都存在，`.worktrees` 优先。
+
+### 2. 检查 CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**如果指定了偏好：** 直接使用，无需询问。
+
+### 3. 询问用户
+
+如果没有目录存在且 CLAUDE.md 中没有偏好设置：
+
+```
+未找到工作树目录。我应该在哪里创建工作树？
+
+1. .worktrees/（项目本地，隐藏）
+2. ~/.config/superpowers/worktrees/<project-name>/（全局位置）
+
+您倾向于哪种选择？
+```
+
+## 安全性验证
+
+### 对于项目本地目录（.worktrees 或 worktrees）
+
+**创建 worktree 前必须验证目录是否被忽略：**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**如果未被忽略：**
+
+根据 Jesse 的规则“立即修复损坏的东西”：
+
+1. 将适当的行添加到 .gitignore
+2. 提交更改
+3. 继续创建 worktree
+
+**为何关键：** 防止意外地将 worktree 内容提交到仓库。
+
+### 对于全局目录 (~/.config/superpowers/worktrees)
+
+无需 .gitignore 验证——完全在项目之外。
+
+## 创建步骤
+
+### 1. 检测项目名称
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. 创建 Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. 运行项目设置
+
+自动检测并运行适当的设置：
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. 验证干净的基线
+
+运行测试以确保 worktree 从干净状态开始：
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**如果测试失败：** 报告失败，询问是继续还是调查。
+
+**如果测试通过：** 报告就绪。
+
+### 5. 报告位置
+
+```
+Worktree 准备就绪于 <full-path>
+测试通过（<N> 项测试，0 失败）
+准备实施 <feature-name>
+```
+
+## 快速参考
+
+| 情况 | 操作 |
+|-----------|--------|
+| `.worktrees/` 存在 | 使用它（验证是否被忽略） |
+| `worktrees/` 存在 | 使用它（验证是否被忽略） |
+| 两者都存在 | 使用 `.worktrees/` |
+| 都不存在 | 检查 CLAUDE.md → 询问用户 |
+| 目录未被忽略 | 添加到 .gitignore + 提交 |
+| 基线测试失败 | 报告失败 + 询问 |
+| 没有 package.json/Cargo.toml | 跳过依赖安装 |
+
+## 常见错误
+
+### 跳过忽略验证
+
+* **问题：** Worktree 内容被跟踪，污染 git status
+* **修复：** 创建项目本地 worktree 前始终使用 `git check-ignore`
+
+### 假设目录位置
+
+* **问题：** 造成不一致，违反项目约定
+* **修复：** 遵循优先级：现有 > CLAUDE.md > 询问
+
+### 在测试失败的情况下继续
+
+* **问题：** 无法区分新错误与预先存在的问题
+* **修复：** 报告失败，获取明确的继续许可
+
+### 硬编码设置命令
+
+* **问题：** 在使用不同工具的项目上会失败
+* **修复：** 根据项目文件（package.json 等）自动检测
+
+## 示例工作流
+
+```
+You: 我正在使用 using-git-worktrees 技能来设置一个隔离的工作空间。
+
+[检查 .worktrees/ - 存在]
+[验证忽略 - git check-ignore 确认 .worktrees/ 被忽略]
+[创建工作树: git worktree add .worktrees/auth -b feature/auth]
+[运行 npm install]
+[运行 npm test - 47 通过]
+
+工作树准备就绪，位于 /Users/jesse/myproject/.worktrees/auth
+测试通过 (47 个测试，0 个失败)
+准备实现 auth 功能
+```
+
+## 红色警报
+
+**绝不要：**
+
+* 不验证是否被忽略就创建 worktree（项目本地）
+* 跳过基线测试验证
+* 不询问就在测试失败的情况下继续
+* 在情况模糊时假设目录位置
+* 跳过 CLAUDE.md 检查
+
+**始终要：**
+
+* 遵循目录优先级：现有 > CLAUDE.md > 询问
+* 验证项目本地目录是否被忽略
+* 自动检测并运行项目设置
+* 验证干净的测试基线
+
+## 集成
+
+**由以下技能调用：**
+
+* **brainstorming** （第 4 阶段） - 当设计被批准并随后进行实现时 **必需**
+* **subagent-driven-development** - 在执行任何任务前 **必需**
+* **executing-plans** - 在执行任何任务前 **必需**
+* 任何需要隔离工作空间的技能
+
+**与以下技能配合使用：**
+
+* **finishing-a-development-branch** - 工作完成后进行清理时 **必需**
diff --git a/zh-CN/skills/using-superpowers/SKILL.md b/zh-CN/skills/using-superpowers/SKILL.md
new file mode 100644
index 0000000000..99046522f9
--- /dev/null
+++ b/zh-CN/skills/using-superpowers/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: using-superpowers
+description: 在任何对话开始时使用 - 确立如何查找和使用技能，要求在包括澄清问题在内的任何回应之前调用技能工具
+---
+
+<SUBAGENT-STOP>
+如果您被派遣为子代理执行特定任务，请跳过此技能。
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+如果你认为某项技能有哪怕1%的可能性适用于你正在做的事情，你就绝对必须使用这项技能。
+
+如果某项技能适用于你的任务，你没有选择。你必须使用它。
+
+这不是可以商量的。这不是可选的。你不能通过合理化来逃避这一点。 </EXTREMELY-IMPORTANT>
+
+## 指令优先级
+
+Superpowers 技能会覆盖默认系统提示行为，但 **用户指令始终具有最高优先级**：
+
+1. **用户的明确指令** (CLAUDE.md, GEMINI.md, AGENTS.md, 直接请求) — 最高优先级
+2. **Superpowers 技能** — 在冲突时覆盖默认系统行为
+3. **默认系统提示** — 最低优先级
+
+如果 CLAUDE.md、GEMINI.md 或 AGENTS.md 说"不要使用 TDD"，而某项技能说"始终使用 TDD"，请遵循用户的指令。用户拥有控制权。
+
+## 如何访问技能
+
+**在 Claude Code 中：** 使用 `Skill` 工具。当你调用技能时，其内容会被加载并呈现给你——直接遵循它。切勿对技能文件使用 Read 工具。
+
+**在 Gemini CLI 中：** 技能通过 `activate_skill` 工具激活。Gemini 在会话开始时加载技能元数据，并根据需要激活完整内容。
+
+**在其他环境中：** 请查看你所在平台的文档以了解技能是如何加载的。
+
+## 平台适配
+
+技能使用 Claude Code 工具名称。非 CC 平台：请参阅 `references/codex-tools.md` (Codex) 以获取工具等效项。Gemini CLI 用户通过 GEMINI.md 自动加载工具映射。
+
+# 使用技能
+
+## 规则
+
+**在做出任何回应或采取任何行动之前，调用相关或被请求的技能。** 即使某项技能只有 1% 的可能性适用，你也应该调用该技能来检查。如果调用的技能最终证明不适合当前情况，你不需要使用它。
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke Skill tool" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create TodoWrite todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to EnterPlanMode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## 危险信号
+
+产生以下想法意味着停止——你正在合理化：
+
+| 想法 | 现实 |
+|---------|---------|
+| "这只是个简单的问题" | 问题就是任务。检查是否有适用技能。 |
+| "我需要先了解更多背景信息" | 技能检查应在澄清问题之前进行。 |
+| "让我先探索代码库" | 技能会告诉你如何探索。先检查。 |
+| "我可以快速检查 git/文件" | 文件缺乏对话上下文。先检查技能。 |
+| "让我先收集信息" | 技能会告诉你如何收集信息。 |
+| "这不需要一个正式的技能" | 如果技能存在，就使用它。 |
+| "我记得这个技能" | 技能会演变。阅读当前版本。 |
+| "这不算是一个任务" | 行动 = 任务。检查技能。 |
+| "这个技能杀鸡用牛刀了" | 简单的事情会变得复杂。使用它。 |
+| "我先做这一件事" | 在做任何事情之前先检查。 |
+| "这感觉很有成效" | 无纪律的行动是浪费时间。技能可以防止这一点。 |
+| "我知道那是什么意思" | 知道概念 ≠ 使用技能。调用它。 |
+
+## 技能优先级
+
+当多个技能可能适用时，使用以下顺序：
+
+1. **先使用流程技能** (brainstorming, debugging) - 这些决定了如何处理任务
+2. **其次使用实现技能** (frontend-design, mcp-builder) - 这些指导执行
+
+"让我们构建 X" → 先 brainstorming，然后实现技能。
+"修复这个错误" → 先 debugging，然后领域特定技能。
+
+## 技能类型
+
+**刚性技能** (TDD, debugging)：严格遵守。不要偏离纪律。
+
+**灵活技能** (patterns)：根据上下文调整原则。
+
+技能本身会告诉你它属于哪一类。
+
+## 用户指令
+
+指令说的是"做什么"，而不是"怎么做"。"添加 X"或"修复 Y"并不意味着可以跳过工作流程。
diff --git a/zh-CN/skills/using-superpowers/references/codex-tools.md b/zh-CN/skills/using-superpowers/references/codex-tools.md
new file mode 100644
index 0000000000..013050fb03
--- /dev/null
+++ b/zh-CN/skills/using-superpowers/references/codex-tools.md
@@ -0,0 +1,25 @@
+# Codex 工具映射
+
+技能使用 Claude Code 工具名称。当您在技能中遇到这些时，请使用您平台的等效工具：
+
+| 技能引用 | Codex 等效工具 |
+|-----------------|------------------|
+| `Task` 工具（派遣子代理） | `spawn_agent` |
+| 多个 `Task` 调用（并行） | 多个 `spawn_agent` 调用 |
+| 任务返回结果 | `wait` |
+| 任务自动完成 | `close_agent` 以释放槽位 |
+| `TodoWrite`（任务跟踪） | `update_plan` |
+| `Skill` 工具（调用技能） | 技能原生加载——只需遵循指令 |
+| `Read`、`Write`、`Edit`（文件） | 使用您原生的文件工具 |
+| `Bash`（运行命令） | 使用您原生的 shell 工具 |
+
+## 子代理分发需要多代理支持
+
+添加到您的 Codex 配置（`~/.codex/config.toml`）：
+
+```toml
+[features]
+multi_agent = true
+```
+
+这将启用 `spawn_agent`、`wait` 和 `close_agent`，适用于像 `dispatching-parallel-agents` 和 `subagent-driven-development` 这样的技能。
diff --git a/zh-CN/skills/using-superpowers/references/gemini-tools.md b/zh-CN/skills/using-superpowers/references/gemini-tools.md
new file mode 100644
index 0000000000..57e527a424
--- /dev/null
+++ b/zh-CN/skills/using-superpowers/references/gemini-tools.md
@@ -0,0 +1,33 @@
+# Gemini CLI 工具映射
+
+技能使用 Claude Code 工具名称。当您在技能中遇到这些名称时，请使用您平台上的等效工具：
+
+| 技能引用 | Gemini CLI 等效工具 |
+|-----------------|----------------------|
+| `Read`（文件读取） | `read_file` |
+| `Write`（文件创建） | `write_file` |
+| `Edit`（文件编辑） | `replace` |
+| `Bash`（运行命令） | `run_shell_command` |
+| `Grep`（搜索文件内容） | `grep_search` |
+| `Glob`（按名称搜索文件） | `glob` |
+| `TodoWrite`（任务跟踪） | `write_todos` |
+| `Skill` 工具（调用技能） | `activate_skill` |
+| `WebSearch` | `google_web_search` |
+| `WebFetch` | `web_fetch` |
+| `Task` 工具（分派子代理） | 无等效工具 — Gemini CLI 不支持子代理 |
+
+## 无子代理支持
+
+Gemini CLI 没有与 Claude Code 的 `Task` 工具等效的工具。依赖子代理分派（`subagent-driven-development`，`dispatching-parallel-agents`）的技能将回退到通过 `executing-plans` 进行单会话执行。
+
+## 额外的 Gemini CLI 工具
+
+这些工具在 Gemini CLI 中可用，但没有 Claude Code 的等效工具：
+
+| 工具 | 用途 |
+|------|---------|
+| `list_directory` | 列出文件和子目录 |
+| `save_memory` | 跨会话将事实持久化到 GEMINI.md |
+| `ask_user` | 向用户请求结构化输入 |
+| `tracker_create_task` | 丰富的任务管理（创建、更新、列出、可视化） |
+| `enter_plan_mode` / `exit_plan_mode` | 在进行更改之前切换到只读研究模式 |
diff --git a/zh-CN/skills/verification-before-completion/SKILL.md b/zh-CN/skills/verification-before-completion/SKILL.md
new file mode 100644
index 0000000000..2439b282c3
--- /dev/null
+++ b/zh-CN/skills/verification-before-completion/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: verification-before-completion
+description: 在准备声明工作完成、已修复或通过时使用，需在提交或创建PR之前运行验证命令并确认输出，然后才能做出任何成功声明；始终先提供证据再进行断言
+---
+
+# 完成前验证
+
+## 概述
+
+未经验证就声称工作已完成是不诚实，而非高效。
+
+**核心原则：** 证据优先于声明，始终如此。
+
+**违反此规则的字面意义即是违反其精神。**
+
+## 铁律
+
+```
+无新验证证据不得提出完成声明
+```
+
+如果你尚未运行此消息中的验证命令，就不能声称它通过了。
+
+## 守门函数
+
+```
+在声明任何状态或表达满意之前：
+
+1. **识别**：哪个命令能证明这一声明？
+2. **运行**：执行完整的命令（全新的、完整的）
+3. **阅读**：查看完整输出，检查退出码，统计失败数量
+4. **验证**：输出是否确认了声明？
+   - 如果**否**：用证据说明实际状态
+   - 如果**是**：用证据说明声明
+5. **只有完成以上步骤后**：才能做出声明
+
+跳过任何步骤 = 撒谎，而非验证
+```
+
+## 常见失败情况
+
+| 声称 | 需要 | 不足够 |
+|-------|----------|----------------|
+| 测试通过 | 测试命令输出：0 失败 | 之前运行过、"应该能通过" |
+| 代码检查通过 | 检查器输出：0 错误 | 部分检查、推断 |
+| 构建成功 | 构建命令：退出码 0 | 检查器通过、日志看起来没问题 |
+| Bug 已修复 | 原始症状测试：通过 | 代码已更改、假设已修复 |
+| 回归测试有效 | 红绿循环已验证 | 测试通过一次 |
+| 代理已完成 | 版本控制系统差异显示变更 | 代理报告"成功" |
+| 需求已满足 | 逐项核对清单 | 测试通过 |
+
+## 危险信号 - 立即停止
+
+* 使用"应该"、"可能"、"似乎"
+* 在验证前表达满意（"太好了！"、"完美！"、"完成了！"等）
+* 即将提交/推送/创建拉取请求而未验证
+* 信任代理的成功报告
+* 依赖部分验证
+* 认为"就这一次"
+* 感到疲倦且希望工作结束
+* **任何暗示成功但未运行验证的措辞**
+
+## 防止合理化借口
+
+| 借口 | 现实 |
+|--------|---------|
+| "现在应该能工作了" | **运行**验证 |
+| "我有信心" | 信心 ≠ 证据 |
+| "就这一次" | 没有例外 |
+| "代码检查通过了" | 检查器 ≠ 编译器 |
+| "代理说成功了" | 独立验证 |
+| "我累了" | 疲惫 ≠ 借口 |
+| "部分检查就够了" | 部分证明不了什么 |
+| "措辞不同所以规则不适用" | 精神重于字面 |
+
+## 关键模式
+
+**测试：**
+
+```
+✅ [运行测试命令] [查看：34/34 通过] "所有测试通过"
+❌ "现在应该通过" / "看起来正确"
+```
+
+**回归测试（TDD 红绿循环）：**
+
+```
+✅ 编写 → 运行（通过） → 恢复修复 → 运行（必须失败） → 还原 → 运行（通过）
+❌ "我编写了一个回归测试"（未进行红绿验证）
+```
+
+**构建：**
+
+```
+✅ [构建运行] [查看：退出码 0] "构建通过"
+❌ "Linter 通过" (linter 不检查编译)
+```
+
+**需求：**
+
+```
+✅ 重新审阅计划 → 创建检查清单 → 逐一核验 → 报告缺失或完成情况
+❌ "测试通过，阶段完成"
+```
+
+**代理委托：**
+
+```
+✅ Agent 报告成功 → 检查版本控制系统差异 → 验证变更 → 报告实际状态
+❌ 信任 Agent 报告
+```
+
+## 为何重要
+
+基于 24 次失败记忆：
+
+* 你的人类伙伴说"我不相信你" - 信任破裂
+* 未定义的函数被发布 - 会导致崩溃
+* 缺失的需求被发布 - 功能不完整
+* 时间浪费在虚假的完成 → 重定向 → 返工
+* 违反："诚实是核心价值观。如果你撒谎，你将被替换。"
+
+## 何时应用
+
+**在以下任何情况之前，始终应用：**
+
+* 任何形式的成功/完成声明
+* 任何满意度的表达
+* 任何关于工作状态的正面陈述
+* 提交、创建拉取请求、完成任务
+* 转向下一项任务
+* 委托给代理
+
+**规则适用于：**
+
+* 确切的措辞
+* 释义和同义词
+* 成功的暗示
+* **任何**暗示完成/正确性的沟通
+
+## 底线
+
+**验证没有捷径。**
+
+运行命令。阅读输出。**然后**声明结果。
+
+这是不可协商的。
diff --git a/zh-CN/skills/writing-plans/SKILL.md b/zh-CN/skills/writing-plans/SKILL.md
new file mode 100644
index 0000000000..80058a5872
--- /dev/null
+++ b/zh-CN/skills/writing-plans/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: writing-plans
+description: 当您有一个多步骤任务的规范或需求时，在编写代码之前使用
+---
+
+# 编写计划
+
+## 概述
+
+编写全面的实施计划，假设工程师对我们的代码库零了解且品味存疑。记录他们需要知道的一切：每项任务需要修改哪些文件、代码、需要查阅的测试和文档、如何测试。将整个计划分解为易于处理的小任务。保持 DRY。遵循 YAGNI。采用 TDD。频繁提交。
+
+假设他们是有经验的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太擅长设计良好的测试。
+
+**开始时声明：** "我正在使用 writing-plans 技能来创建实施计划。"
+
+**上下文：** 这应该在专用工作树中运行（由 brainstorming 技能创建）。
+
+**计划保存至：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+
+* （用户对计划位置的偏好会覆盖此默认设置）
+
+## 范围检查
+
+如果规范涵盖多个独立的子系统，则应在头脑风暴阶段将其分解为子项目规范。如果未分解，建议将其拆分为独立的计划——每个子系统一个计划。每个计划都应能独立产出可工作、可测试的软件。
+
+## 文件结构
+
+在定义任务之前，先规划将要创建或修改的文件，并说明每个文件的职责。这是分解决策确定的地方。
+
+* 设计具有清晰边界和明确定义接口的单元。每个文件应有一个明确的职责。
+* 你对自己能一次性在上下文中理解的代码推理效果最好，当文件聚焦时，你的编辑也更可靠。倾向于更小、聚焦的文件，而不是功能过多的大文件。
+* 一起变化的文件应该放在一起。按职责拆分，而不是按技术层拆分。
+* 在现有代码库中，遵循既定模式。如果代码库使用大文件，不要单方面重构——但如果你要修改的文件已经变得难以管理，在计划中包含拆分是合理的。
+
+这个结构决定了任务分解。每个任务应产生独立且有意义的自包含变更。
+
+## 易于处理的任务粒度
+
+**每个步骤是一个动作（2-5分钟）：**
+
+* "编写失败的测试" - 步骤
+* "运行它以确认失败" - 步骤
+* "实现使测试通过的最简代码" - 步骤
+* "运行测试并确认通过" - 步骤
+* "提交" - 步骤
+
+## 计划文档头部
+
+**每个计划必须以以下头部开始：**
+
+```markdown
+# [功能名称] 实施方案
+
+> **面向智能体工作者：** 必备子技能：使用 superpowers：子智能体驱动开发（推荐）或 superpowers：执行计划来按任务逐步实施此方案。步骤使用复选框（`- [ ]`）语法进行跟踪。
+
+**目标：** [一句话描述本方案构建的内容]
+
+**架构：** [2-3句话描述方法]
+
+**技术栈：** [关键技术/库]
+
+---
+```
+
+## 任务结构
+
+````markdown
+### 任务 N: [组件名称]
+
+**文件：**
+- 创建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+- [ ] **步骤 1：编写失败测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **步骤 2：运行测试以确认其失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：失败，提示"函数未定义"
+
+- [ ] **步骤 3：编写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **步骤 4：运行测试以确认其通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：通过
+
+- [ ] **步骤 5：提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 记住
+
+* 始终使用精确的文件路径
+* 计划中包含完整的代码（而不是"添加验证"）
+* 使用精确的命令和预期输出
+* 使用 @ 语法引用相关技能
+* DRY, YAGNI, TDD, 频繁提交
+
+## 计划审查循环
+
+完成计划编写后：
+
+1. 派遣一个计划文档评审子代理（参见 plan-document-reviewer-prompt.md），并提供精心构建的评审上下文——切勿使用您的会话历史。这使评审员专注于计划本身，而非您的思考过程。
+   * 提供：计划文档路径、规格文档路径
+2. 如果 ❌ 发现问题：修复问题，并重新派遣评审员评审整个计划
+3. 如果 ✅ 获得批准：继续执行交接
+
+**审查循环指南：**
+
+* 由编写计划的同一代理进行修复（保持上下文）
+* 如果循环超过3次，则向人类寻求指导
+* 评审员仅提供建议——如果您认为反馈不正确，请解释分歧
+
+## 执行交接
+
+保存计划后，提供执行选项：
+
+**“计划已完成并保存至 `docs/superpowers/plans/<filename>.md`。提供两种执行选项：**
+
+**1. 子代理驱动（推荐）** - 我为每个任务派遣一个全新的子代理，任务间进行评审，快速迭代
+
+**2. 内联执行** - 在此会话中使用 executing-plans 执行任务，批量执行并设置检查点
+
+**选择哪种方式？”**
+
+**如果选择子代理驱动：**
+
+* **必需子技能：** 使用 superpowers:subagent-driven-development
+* 每个任务使用全新子代理 + 两阶段评审
+
+**如果选择内联执行：**
+
+* **必需子技能：** 使用 superpowers:executing-plans
+* 批量执行并设置检查点以供评审
diff --git a/zh-CN/skills/writing-plans/plan-document-reviewer-prompt.md b/zh-CN/skills/writing-plans/plan-document-reviewer-prompt.md
new file mode 100644
index 0000000000..b4a026f192
--- /dev/null
+++ b/zh-CN/skills/writing-plans/plan-document-reviewer-prompt.md
@@ -0,0 +1,49 @@
+# 计划文档审阅者提示模板
+
+在分派计划文档审阅者子代理时使用此模板。
+
+**目的：** 验证计划是否完整、符合规范，并具有适当的任务分解。
+
+**调度时间：** 完整计划编写完成后。
+
+```
+Task tool (general-purpose):
+  description: "Review plan document"
+  prompt: |
+    You are a plan document reviewer. Verify this plan is complete and ready for implementation.
+
+    **Plan to review:** [PLAN_FILE_PATH]
+    **Spec for reference:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+    | Spec Alignment | Plan covers spec requirements, no major scope creep |
+    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
+    | Buildability | Could an engineer follow this plan without getting stuck? |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation.**
+    An implementer building the wrong thing or getting stuck is an issue.
+    Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+    Approve unless there are serious gaps — missing requirements from the spec,
+    contradictory steps, placeholder content, or tasks so vague they can't be acted on.
+
+    ## Output Format
+
+    ## Plan Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**审阅者返回：** 状态、问题（如有）、建议
diff --git a/zh-CN/skills/writing-skills/SKILL.md b/zh-CN/skills/writing-skills/SKILL.md
new file mode 100644
index 0000000000..1bc2884598
--- /dev/null
+++ b/zh-CN/skills/writing-skills/SKILL.md
@@ -0,0 +1,706 @@
+---
+name: writing-skills
+description: 用于创建新技能、编辑现有技能或在部署前验证技能是否正常工作
+---
+
+# 写作技能
+
+## 概述
+
+**写作技能是测试驱动开发在流程文档中的应用。**
+
+**个人技能存放在特定智能体的目录中（`~/.claude/skills` 对应 Claude Code，`~/.agents/skills/` 对应 Codex）**
+
+你编写测试用例（包含子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵从），并进行重构（修补漏洞）。
+
+**核心原则：** 如果你没有观察到智能体在没有该技能的情况下失败，你就不知道这个技能是否教授了正确的内容。
+
+**必备背景：** 在使用此技能之前，你必须理解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。本技能将 TDD 适配到文档编写。
+
+**官方指导：** 关于 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了额外的模式和指南，以补充本技能中专注于 TDD 的方法。
+
+## 什么是技能？
+
+一个**技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
+
+**技能是：** 可复用的技术、模式、工具、参考指南
+
+**技能不是：** 关于你如何一次性解决问题的叙述
+
+## 技能的 TDD 映射
+
+| TDD 概念 | 技能创建 |
+|-------------|----------------|
+| **测试用例** | 包含子智能体的压力场景 |
+| **生产代码** | 技能文档 (SKILL.md) |
+| **测试失败 (RED)** | 智能体在没有技能时违反规则（基线） |
+| **测试通过 (GREEN)** | 智能体在有技能时遵从 |
+| **重构** | 在保持遵从的同时修补漏洞 |
+| **先写测试** | 在编写技能之前运行基线场景 |
+| **观察失败** | 记录智能体使用的确切合理化解释 |
+| **最简代码** | 编写针对那些特定违规行为的技能 |
+| **观察通过** | 验证智能体现在遵从 |
+| **重构循环** | 发现新的合理化解释 → 修补 → 重新验证 |
+
+整个技能创建过程遵循 RED-GREEN-REFACTOR 循环。
+
+## 何时创建技能
+
+**在以下情况下创建：**
+
+* 该技术对你来说并非直观明显
+* 你会在不同项目中再次参考此内容
+* 模式广泛适用（非项目特定）
+* 其他人会受益
+
+**不要为以下情况创建：**
+
+* 一次性解决方案
+* 其他地方已有完善文档的标准实践
+* 项目特定的约定（放在 CLAUDE.md 中）
+* 机械性约束（如果可以用正则表达式/验证强制执行，就自动化它——把文档留给需要判断的情况）
+
+## 技能类型
+
+### 技术
+
+具有可遵循步骤的具体方法（条件等待、根本原因追踪）
+
+### 模式
+
+思考问题的方式（使用标志扁平化、测试不变量）
+
+### 参考
+
+API 文档、语法指南、工具文档（办公文档）
+
+## 目录结构
+
+```
+skills/
+  skill-name/
+    SKILL.md              # 主要参考文件（必需）
+    supporting-file.*     # 仅在需要时添加
+```
+
+**扁平命名空间** - 所有技能在一个可搜索的命名空间中
+
+**为以下内容使用单独文件：**
+
+1. **重型参考** (100+ 行) - API 文档、综合语法
+2. **可复用工具** - 脚本、实用程序、模板
+
+**内联保留：**
+
+* 原则和概念
+* 代码模式 (< 50 行)
+* 其他所有内容
+
+## SKILL.md 结构
+
+**前言 (YAML):**
+
+* 仅支持两个字段：`name` 和 `description`
+* 总计最多 1024 个字符
+* `name`: 仅使用字母、数字和连字符（无括号、特殊字符）
+* `description`: 使用第三人称，仅描述何时使用（而非其作用）
+  * 以“Use when...”开头，专注于触发条件
+  * 包含具体的症状、情况和上下文
+  * **切勿总结技能的过程或工作流**（参见 CSO 部分了解原因）
+  * 尽可能保持在 500 个字符以内
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: Use when [specific triggering conditions and symptoms]
+---
+
+# 技能名称
+
+## 概述
+这是什么？用 1-2 句话说明核心原理。
+
+## 何时使用
+[如果决策不明显，可包含小型内联流程图]
+
+以项目符号列出症状和使用场景
+何时不应使用
+
+## 核心模式（适用于技术/模式）
+前后代码对比
+
+## 快速参考
+用于快速浏览常见操作的表格或项目符号列表
+
+## 实现
+简单模式的内联代码
+指向重型参考或可复用工具文件的链接
+
+## 常见错误
+问题所在 + 修复方法
+
+## 实际影响（可选）
+具体成果
+```
+
+## Claude 搜索优化 (CSO)
+
+**对可发现性至关重要：** 未来的 Claude 需要能够找到你的技能
+
+### 1. 丰富的描述字段
+
+**目的：** Claude 通过读取描述来决定为给定任务加载哪些技能。让它回答：“我现在应该阅读这个技能吗？”
+
+**格式：** 以“Use when...”开头，专注于触发条件
+
+**关键：描述 = 何时使用，而非技能的作用**
+
+描述应仅描述触发条件。切勿在描述中总结技能的过程或工作流。
+
+**这很重要：** 测试显示，当描述总结了技能的工作流时，Claude 可能会遵循描述而不是阅读完整的技能内容。一个描述写着“任务间的代码审查”导致 Claude 只进行一次审查，即使技能的流程图清楚地显示了两次审查（规范符合性审查然后是代码质量审查）。
+
+当描述改为仅“Use when executing implementation plans with independent tasks”（无工作流总结）时，Claude 正确地阅读了流程图并遵循了两阶段审查过程。
+
+**陷阱：** 总结工作流的描述创建了 Claude 会走的捷径。技能主体变成了 Claude 会跳过的文档。
+
+```yaml
+# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
+description: Use when executing plans - dispatches subagent per task with code review between tasks
+
+# ❌ BAD: Too much process detail
+description: Use for TDD - write test first, watch it fail, write minimal code, refactor
+
+# ✅ GOOD: Just triggering conditions, no workflow summary
+description: Use when executing implementation plans with independent tasks in the current session
+
+# ✅ GOOD: Triggering conditions only
+description: Use when implementing any feature or bugfix, before writing implementation code
+```
+
+**内容：**
+
+* 使用具体的触发器、症状和情况来表明此技能适用
+* 描述*问题*（竞态条件、不一致行为），而非*特定语言的症状*（setTimeout、sleep）
+* 保持触发器与技术无关，除非技能本身是技术特定的
+* 如果技能是技术特定的，请在触发器中明确说明
+* 用第三人称书写（注入到系统提示中）
+* **切勿总结技能的过程或工作流**
+
+```yaml
+# ❌ BAD: Too abstract, vague, doesn't include when to use
+description: For async testing
+
+# ❌ BAD: First person
+description: I can help you with async tests when they're flaky
+
+# ❌ BAD: Mentions technology but skill isn't specific to it
+description: Use when tests use setTimeout/sleep and are flaky
+
+# ✅ GOOD: Starts with "Use when", describes problem, no workflow
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
+
+# ✅ GOOD: Technology-specific skill with explicit trigger
+description: Use when using React Router and handling authentication redirects
+```
+
+### 2. 关键词覆盖
+
+使用 Claude 会搜索的词语：
+
+* 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
+* 症状：“flaky”、“hanging”、“zombie”、“pollution”
+* 同义词：“timeout/hang/freeze”、“cleanup/teardown/afterEach”
+* 工具：实际命令、库名、文件类型
+
+### 3. 描述性命名
+
+**使用主动语态，动词优先：**
+
+* ✅ `creating-skills` 而非 `skill-creation`
+* ✅ `condition-based-waiting` 而非 `async-test-helpers`
+
+### 4. 令牌效率（关键）
+
+**问题：** 入门指南和频繁引用的技能会加载到每一次对话中。每个令牌都很重要。
+
+**目标字数：**
+
+* 入门指南工作流：每项 <150 词
+* 频繁加载的技能：总计 <200 词
+* 其他技能：<500 词（仍需简洁）
+
+**技巧：**
+
+**将细节移至工具帮助：**
+
+```bash
+# ❌ BAD: Document all flags in SKILL.md
+search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
+
+# ✅ GOOD: Reference --help
+search-conversations supports multiple modes and filters. Run --help for details.
+```
+
+**使用交叉引用：**
+
+```markdown
+# ❌ 不佳做法：重复工作流细节
+搜索时，使用模板派生子代理...
+[20行重复的指令]
+
+# ✅ 良好做法：引用其他技能
+始终使用子代理（可节省50-100倍上下文）。必需：使用 [其他技能名称] 来处理工作流。
+```
+
+**压缩示例：**
+
+```markdown
+# ❌ 反面示例：冗长版本（42词）
+你的搭档："我们之前是如何在 React Router 中处理认证错误的？"
+你：我来搜索过往对话中关于 React Router 认证模式的内容。
+[派发子代理，搜索查询："React Router authentication error handling 401"]
+
+# ✅ 正面示例：简洁版本（20词）
+搭档："React Router 里之前怎么处理认证错误？"
+你：搜索中...
+[派发子代理 → 综合处理]
+```
+
+**消除冗余：**
+
+* 不要重复交叉引用技能中的内容
+* 不要解释命令中显而易见的内容
+* 不要包含同一模式的多个示例
+
+**验证：**
+
+```bash
+wc -w skills/path/SKILL.md
+# getting-started workflows: aim for <150 each
+# Other frequently-loaded: aim for <200 total
+```
+
+**按你所做的或核心见解命名：**
+
+* ✅ `condition-based-waiting` > `async-test-helpers`
+* ✅ `using-skills` 而非 `skill-usage`
+* ✅ `flatten-with-flags` > `data-structure-refactoring`
+* ✅ `root-cause-tracing` > `debugging-techniques`
+
+**动名词 (-ing) 适用于描述过程：**
+
+* `creating-skills`、`testing-skills`、`debugging-with-logs`
+* 主动，描述你正在采取的行动
+
+### 4. 交叉引用其他技能
+
+**在编写引用其他技能的文档时：**
+
+仅使用技能名称，并带有明确的需求标记：
+
+* ✅ 好：`**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
+* ✅ 好：`**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
+* ❌ 不好：`See skills/testing/test-driven-development`（不清楚是否必需）
+* ❌ 不好：`@skills/testing/test-driven-development/SKILL.md`（强制加载，消耗上下文）
+
+**为何不使用 @ 链接：** `@` 语法会立即强制加载文件，在你需要它们之前就消耗 200k+ 的上下文。
+
+## 流程图使用
+
+```dot
+digraph when_flowchart {
+    "Need to show information?" [shape=diamond];
+    "Decision where I might go wrong?" [shape=diamond];
+    "Use markdown" [shape=box];
+    "Small inline flowchart" [shape=box];
+
+    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
+    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
+    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
+}
+```
+
+**仅在以下情况使用流程图：**
+
+* 非显而易见的决策点
+* 你可能过早停止的流程循环
+* “何时使用 A 与 B”的决策
+
+**切勿为以下情况使用流程图：**
+
+* 参考材料 → 表格、列表
+* 代码示例 → Markdown 代码块
+* 线性指令 → 编号列表
+* 无语义含义的标签（step1、helper2）
+
+关于 graphviz 样式规则，请参阅 @graphviz-conventions.dot。
+
+**为你的合作伙伴可视化：** 使用此目录中的 `render-graphs.js` 将技能的流程图渲染为 SVG：
+
+```bash
+./render-graphs.js ../some-skill           # Each diagram separately
+./render-graphs.js ../some-skill --combine # All diagrams in one SVG
+```
+
+## 代码示例
+
+**一个优秀的示例胜过多个平庸的示例**
+
+选择最相关的语言：
+
+* 测试技术 → TypeScript/JavaScript
+* 系统调试 → Shell/Python
+* 数据处理 → Python
+
+**好的示例：**
+
+* 完整且可运行
+* 注释良好，解释原因
+* 来自真实场景
+* 清晰地展示模式
+* 便于改编（非通用模板）
+
+**不要：**
+
+* 用 5 种以上语言实现
+* 创建填空模板
+* 编写人为的示例
+
+你很擅长移植——一个优秀的示例就足够了。
+
+## 文件组织
+
+### 自包含的技能
+
+```
+defense-in-depth/
+  SKILL.md    # 所有内容均内联
+```
+
+何时使用：所有内容都合适，无需重型参考
+
+### 带有可复用工具的技能
+
+```
+condition-based-waiting/
+  SKILL.md    # 概述 + 模式
+  example.ts  # 可用的辅助函数，供调整使用
+```
+
+何时使用：工具是可复用代码，而不仅仅是叙述
+
+### 带有重型参考的技能
+
+```
+pptx/
+  SKILL.md       # 概述 + 工作流程
+  pptxgenjs.md   # 600行 API 参考
+  ooxml.md       # 500行 XML 结构
+  scripts/       # 可执行工具
+```
+
+何时使用：参考材料太大，不适合内联
+
+## 铁律（与 TDD 相同）
+
+```
+没有失败的测试，就没有技能。
+```
+
+这适用于新技能和对现有技能的编辑。
+
+在测试前编写技能？删除它。重新开始。
+未经测试就编辑技能？同样的违规。
+
+**无例外：**
+
+* 不适用于“简单添加”
+* 不适用于“只是添加一个部分”
+* 不适用于“文档更新”
+* 不要将未经测试的更改保留为“参考”
+* 不要在运行测试时“调整”
+* 删除就是删除
+
+**必备背景：** superpowers:test-driven-development 技能解释了这为何重要。同样的原则适用于文档。
+
+## 测试所有技能类型
+
+不同的技能类型需要不同的测试方法：
+
+### 纪律强化型技能（规则/要求）
+
+**示例：** TDD、完成前验证、编码前设计
+
+**测试方法：**
+
+* 学术性问题：他们理解规则吗？
+* 压力场景：他们在压力下遵守吗？
+* 多重压力组合：时间 + 沉没成本 + 疲惫
+* 识别合理化解释并添加明确的应对措施
+
+**成功标准：** 智能体在最大压力下遵守规则
+
+### 技术型技能（操作指南）
+
+**示例：** 条件等待、根本原因追踪、防御性编程
+
+**测试方法：**
+
+* 应用场景：他们能正确应用该技术吗？
+* 变体场景：他们能处理边缘情况吗？
+* 缺失信息测试：指令是否存在空白？
+
+**成功标准：** 智能体成功将技术应用于新场景
+
+### 模式型技能（心智模型）
+
+**示例：** 降低复杂性、信息隐藏概念
+
+**测试方法：**
+
+* 识别场景：他们能识别何时适用该模式吗？
+* 应用场景：他们能使用该心智模型吗？
+* 反例：他们知道何时不应应用吗？
+
+**成功标准：** 智能体正确识别何时/如何应用模式
+
+### 参考型技能（文档/API）
+
+**示例：** API 文档、命令参考、库指南
+
+**测试方法：**
+
+* 检索场景：他们能找到正确的信息吗？
+* 应用场景：他们能正确应用找到的信息吗？
+* 空白测试：常见用例是否涵盖？
+
+**成功标准：** 智能体找到并正确应用参考信息
+
+## 跳过测试的常见合理化解释
+
+| 借口 | 现实 |
+|--------|---------|
+| “技能显然很清晰” | 对你清晰 ≠ 对其他智能体清晰。测试它。 |
+| “这只是个参考” | 参考可能存在空白、不清晰的段落。测试检索。 |
+| “测试过度了” | 未经测试的技能存在问题。总是如此。15 分钟测试能节省数小时。 |
+| “如果出现问题我会测试” | 问题 = 智能体无法使用技能。在部署前测试。 |
+| “测试太繁琐” | 测试比在生产中调试坏技能要省事。 |
+| “我确信它很好” | 过度自信必然导致问题。无论如何都要测试。 |
+| “学术审查足够了” | 阅读 ≠ 使用。测试应用场景。 |
+| “没时间测试” | 部署未经测试的技能会浪费更多时间在以后修复它。 |
+
+**所有这些都意味着：在部署前测试。没有例外。**
+
+## 让技能对合理化免疫
+
+强制纪律的技能（如 TDD）需要能够抵抗合理化。代理很聪明，在压力下会寻找漏洞。
+
+**心理学注记：** 理解说服技巧为何有效，有助于你系统地应用它们。关于权威、承诺、稀缺性、社会认同和统一性原则的研究基础，请参阅 persuasion-principles.md（Cialdini, 2021; Meincke et al., 2025）。
+
+### 明确堵住每一个漏洞
+
+不要仅仅陈述规则——要禁止特定的变通方法：
+
+<Bad>
+```markdown
+在测试前编写代码？删除它。
+```
+</Bad>
+
+<Good>
+```markdown
+编写代码之前进行测试？删除它。重新开始。
+
+**无例外：**
+
+* 不要将其保留为“参考”
+* 不要在编写测试时“借鉴”它
+* 不要看它
+* 删除就是删除
+
+````
+</Good>
+
+### 处理“精神与字面”的争论
+
+尽早添加基本原则：
+
+```markdown
+**违反规则的字面意思就是违反规则的精神。**
+
+````
+
+这切断了整个“我遵循了精神”的合理化类别。
+
+### 建立合理化对照表
+
+从基线测试中捕捉合理化行为（见下文测试部分）。代理提出的每一个借口都要记录在表中：
+
+```markdown
+| 借口 | 现实 |
+|--------|---------|
+| "太简单了，不需要测试" | 简单的代码也会出错。测试只需30秒。 |
+| "我稍后再测试" | 测试通过立刻证明不了什么。 |
+| "之后测试也能达到相同目标" | 测试后补 = "这段代码是做什么的？" 测试先行 = "这段代码应该做什么？" |
+```
+
+### 创建危险信号列表
+
+让代理在合理化时容易进行自我检查：
+
+```markdown
+## 危险信号 - 立即停止并重新开始
+
+- 先写代码后测试
+- “我已经手动测试过了”
+- “之后再测试效果也一样”
+- “重要的是精神而不是形式”
+- “这次情况特殊，因为……”
+
+**以上任何一条都意味着：删除代码，用测试驱动开发重新开始。**
+```
+
+### 为违规征兆更新 CSO
+
+在描述中添加：当你即将违反规则时的征兆：
+
+```yaml
+description: use when implementing any feature or bugfix, before writing implementation code
+```
+
+## 技能的“红-绿-重构”流程
+
+遵循 TDD 循环：
+
+### 红：编写失败测试（基线）
+
+在没有该技能的情况下，使用子代理运行压力场景。记录确切行为：
+
+* 他们做出了哪些选择？
+* 他们使用了哪些合理化借口（逐字记录）？
+* 哪些压力触发了违规？
+
+这就是“观察测试失败”——在编写技能之前，你必须先看看代理的自然行为。
+
+### 绿：编写最小化技能
+
+编写能解决这些特定合理化借口的技能。不要为假设性案例添加额外内容。
+
+使用技能运行相同场景。代理现在应该遵守规则。
+
+### 重构：堵住漏洞
+
+代理找到了新的合理化借口？添加明确的应对措施。重新测试直到无懈可击。
+
+**测试方法论：** 完整的测试方法论请参阅 @testing-skills-with-subagents.md：
+
+* 如何编写压力场景
+* 压力类型（时间、沉没成本、权威、疲劳）
+* 系统地堵住漏洞
+* 元测试技术
+
+## 反模式
+
+### ❌ 叙事性示例
+
+“在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……”
+**为何不好：** 过于具体，不可复用
+
+### ❌ 多语言稀释
+
+example-js.js, example-py.py, example-go.go
+**为何不好：** 质量平庸，维护负担重
+
+### ❌ 流程图中的代码
+
+```dot
+step1 [label="import fs"];
+step2 [label="read file"];
+```
+
+**为何不好：** 无法复制粘贴，难以阅读
+
+### ❌ 通用标签
+
+helper1, helper2, step3, pattern4
+**为何不好：** 标签应具有语义含义
+
+## 停：在转向下一个技能之前
+
+**编写完任何技能后，你必须停下来完成部署流程。**
+
+**不要：**
+
+* 批量创建多个技能而不测试每一个
+* 在当前技能验证完成前转向下一个技能
+* 以“批量处理更高效”为由跳过测试
+
+**下面的部署清单对每个技能都是强制性的。**
+
+部署未经测试的技能 = 部署未经测试的代码。这违反了质量标准。
+
+## 技能创建清单（适配自 TDD）
+
+**重要提示：使用 TodoWrite 为下面的每个清单项创建待办事项。**
+
+**红阶段 - 编写失败测试：**
+
+* \[ ] 创建压力场景（针对纪律性技能，需包含 3 种以上复合压力）
+* \[ ] 在没有技能的情况下运行场景——逐字记录基线行为
+* \[ ] 识别合理化/失败的模式
+
+**绿阶段 - 编写最小化技能：**
+
+* \[ ] 名称仅使用字母、数字、连字符（无括号/特殊字符）
+* \[ ] YAML 前置元数据仅包含名称和描述（最多 1024 字符）
+* \[ ] 描述以“Use when...”开头，并包含特定触发条件/征兆
+* \[ ] 描述使用第三人称书写
+* \[ ] 贯穿全文的关键词（用于搜索错误、征兆、工具）
+* \[ ] 包含核心原则的清晰概述
+* \[ ] 解决在红阶段识别的特定基线失败
+* \[ ] 代码内联或链接到单独文件
+* \[ ] 一个优秀的示例（非多语言）
+* \[ ] 使用技能运行场景——验证代理现在是否遵守规则
+
+**重构阶段 - 堵住漏洞：**
+
+* \[ ] 从测试中识别新的合理化借口
+* \[ ] 添加明确的应对措施（如果是纪律性技能）
+* \[ ] 根据所有测试迭代建立合理化对照表
+* \[ ] 创建危险信号列表
+* \[ ] 重新测试直到无懈可击
+
+**质量检查：**
+
+* \[ ] 仅在决策不明显时使用小型流程图
+* \[ ] 快速参考表
+* \[ ] 常见错误部分
+* \[ ] 没有叙事性描述
+* \[ ] 支持文件仅用于工具或大量参考
+
+**部署：**
+
+* \[ ] 将技能提交到 git 并推送到你的分支（如果已配置）
+* \[ ] 考虑通过 PR 贡献回来（如果具有广泛用途）
+
+## 发现工作流
+
+未来的 Claude 如何找到你的技能：
+
+1. **遇到问题**（“测试不稳定”）
+2. **找到技能**（描述匹配）
+3. **浏览概述**（这相关吗？）
+4. **阅读模式**（快速参考表）
+5. **加载示例**（仅在实施时）
+
+**针对此流程进行优化**——尽早并经常放置可搜索的术语。
+
+## 核心要点
+
+**创建技能就是流程文档的 TDD。**
+
+同样的铁律：没有失败的测试，就没有技能。
+同样的循环：红（基线）→ 绿（编写技能）→ 重构（堵住漏洞）。
+同样的好处：更好的质量，更少的意外，无懈可击的结果。
+
+如果你为代码遵循 TDD，那么也为技能遵循它。这是应用于文档的同一种纪律。
diff --git a/zh-CN/skills/writing-skills/anthropic-best-practices.md b/zh-CN/skills/writing-skills/anthropic-best-practices.md
new file mode 100644
index 0000000000..4530a29566
--- /dev/null
+++ b/zh-CN/skills/writing-skills/anthropic-best-practices.md
@@ -0,0 +1,1144 @@
+# 技能创作最佳实践
+
+> 学习如何编写有效的技能，以便 Claude 能够成功发现和使用。
+
+好的技能应该简洁、结构良好，并经过实际使用测试。本指南提供了实用的创作决策，帮助您编写 Claude 能够有效发现和使用的技能。
+
+关于技能工作原理的概念背景，请参阅[技能概述](../../../../../../../en/docs/agents-and-tools/agent-skills/overview)。
+
+## 核心原则
+
+### 简洁是关键
+
+[上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows)是公共资源。您的技能需要与 Claude 需要知道的所有其他内容共享上下文窗口，包括：
+
+* 系统提示
+* 对话历史
+* 其他技能的元数据
+* 您的实际请求
+
+并非技能中的每个令牌都会立即产生成本。启动时，只会预加载所有技能的元数据（名称和描述）。Claude 只有在技能变得相关时才会读取 SKILL.md，并且仅在需要时读取其他文件。然而，保持 SKILL.md 的简洁仍然很重要：一旦 Claude 加载了它，每个令牌都会与对话历史和其他上下文竞争。
+
+**默认假设**：Claude 已经非常智能
+
+只添加 Claude 尚未掌握的上下文。挑战每一条信息：
+
+* “Claude 真的需要这个解释吗？”
+* “我可以假设 Claude 知道这个吗？”
+* “这个段落是否值得其令牌成本？”
+
+**良好示例：简洁**（约 50 个令牌）：
+
+````markdown
+## 提取 PDF 文本
+
+使用 pdfplumber 进行文本提取：
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+````
+
+**不良示例：过于冗长**（约 150 个令牌）：
+
+```markdown
+## 提取 PDF 文本
+
+PDF（便携式文档格式）文件是一种常见的文件格式，其中包含文本、图像和其他内容。要从 PDF 中提取文本，你需要使用一个库。有许多可用于 PDF 处理的库，但我们推荐 pdfplumber，因为它易于使用且能很好地处理大多数情况。首先，你需要使用 pip 安装它。然后你可以使用下面的代码...
+```
+
+简洁版本假设 Claude 知道 PDF 是什么以及库如何工作。
+
+### 设置适当的自由度
+
+将详细程度与任务的脆弱性和可变性相匹配。
+
+**高自由度**（基于文本的指令）：
+
+适用于：
+
+* 多种方法都有效
+* 决策取决于上下文
+* 启发式方法指导操作
+
+示例：
+
+```markdown
+## 代码审查流程
+
+1. 分析代码结构与组织方式
+2. 检查潜在缺陷与边界情况
+3. 提出可读性与可维护性改进建议
+4. 验证是否符合项目规范
+```
+
+**中等自由度**（带参数的伪代码或脚本）：
+
+适用于：
+
+* 存在首选模式
+* 接受一定的变化
+* 配置影响行为
+
+示例：
+
+````markdown
+## 生成报告
+
+使用此模板并根据需要自定义：
+
+```python
+def generate_report(data, format="markdown", include_charts=True):
+    # Process data
+    # Generate output in specified format
+    # Optionally include visualizations
+```
+````
+
+**低自由度**（特定脚本，参数很少或没有）：
+
+适用于：
+
+* 操作脆弱且容易出错
+* 一致性至关重要
+* 必须遵循特定顺序
+
+示例：
+
+````markdown
+## 数据库迁移
+
+请严格运行以下脚本：
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+请勿修改命令或添加额外参数。
+````
+
+**类比**：将 Claude 想象成一个探索路径的机器人：
+
+* **两侧是悬崖的狭窄桥梁**：只有一种安全的前进方式。提供具体的防护栏和确切的指令（低自由度）。示例：必须按确切顺序运行的数据库迁移。
+* **没有危险的开放田野**：许多路径都能通向成功。给出大致方向，并相信 Claude 能找到最佳路线（高自由度）。示例：代码审查，其中上下文决定了最佳方法。
+
+### 使用计划使用的所有模型进行测试
+
+技能作为模型的补充，因此其有效性取决于底层模型。请使用您计划使用的所有模型测试您的技能。
+
+**按模型划分的测试注意事项**：
+
+* **Claude Haiku**（快速、经济）：技能是否提供了足够的指导？
+* **Claude Sonnet**（平衡）：技能是否清晰高效？
+* **Claude Opus**（强大的推理能力）：技能是否避免了过度解释？
+
+对 Opus 完美有效的内容可能需要对 Haiku 提供更多细节。如果您计划在多个模型中使用您的技能，请力求指令在所有模型上都能良好工作。
+
+## 技能结构
+
+<Note>
+  **YAML Frontmatter**：SKILL.md 前置元数据支持两个字段：
+
+* `name` - 技能的人类可读名称（最多 64 个字符）
+  * `description` - 对技能功能及使用场景的单行描述（最多 1024 个字符）
+
+有关完整技能结构详情，请参阅[技能概述](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#skill-structure)。</Note>
+
+### 命名规范
+
+使用一致的命名模式，使技能更容易引用和讨论。我们建议在技能名称中使用**动名词形式**（动词 + -ing），因为这能清晰地描述技能提供的活动或能力。
+
+**良好的命名示例（动名词形式）**：
+
+* “Processing PDFs”
+* “Analyzing spreadsheets”
+* “Managing databases”
+* “Testing code”
+* “Writing documentation”
+
+**可接受的替代方案**：
+
+* 名词短语：“PDF Processing”、“Spreadsheet Analysis”
+* 面向行动的：“Process PDFs”、“Analyze Spreadsheets”
+
+**避免**：
+
+* 模糊的名称：“Helper”、“Utils”、“Tools”
+* 过于通用：“Documents”、“Data”、“Files”
+* 在您的技能集合中使用不一致的模式
+
+一致的命名使得：
+
+* 在文档和对话中引用技能更容易
+* 一目了然地理解技能的功能
+* 组织和搜索多个技能更容易
+* 保持专业、连贯的技能库
+
+### 编写有效的描述
+
+`description` 字段支持技能发现，应同时包含技能的功能和使用时机。
+
+<Warning>
+  **始终使用第三人称写作**。描述信息会被注入系统提示中，人称不一致可能导致发现错误。
+
+* **良好：** “Processes Excel files and generates reports”
+  * **避免：** “I can help you process Excel files”
+  * **避免：** “You can use this to process Excel files” </Warning>
+
+**具体并包含关键术语**。包含技能的功能以及何时使用它的具体触发条件/上下文。
+
+每个技能只有一个描述字段。描述对于技能选择至关重要：Claude 使用它从可能 100 多个可用技能中选择正确的技能。您的描述必须提供足够的细节，以便 Claude 知道何时选择此技能，而 SKILL.md 的其余部分则提供实现细节。
+
+有效示例：
+
+**PDF 处理技能：**
+
+```yaml theme={null}
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Excel 分析技能：**
+
+```yaml theme={null}
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+```
+
+**Git 提交助手技能：**
+
+```yaml theme={null}
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+避免像这样的模糊描述：
+
+```yaml theme={null}
+description: Helps with documents
+```
+
+```yaml theme={null}
+description: Processes data
+```
+
+```yaml theme={null}
+description: Does stuff with files
+```
+
+### 渐进式披露模式
+
+SKILL.md 作为一个概述，根据需要将 Claude 指向详细资料，就像入职指南中的目录一样。关于渐进式披露工作原理的解释，请参阅概述中的[技能工作原理](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#how-skills-work)。
+
+**实用指南**：
+
+* 为获得最佳性能，保持 SKILL.md 主体在 500 行以内
+* 接近此限制时，将内容拆分为单独的文件
+* 使用以下模式有效地组织指令、代码和资源
+
+#### 视觉概述：从简单到复杂
+
+一个基本的技能开始时只有一个包含元数据和指令的 SKILL.md 文件：
+
+<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="展示YAML前置元数据和Markdown正文的简单SKILL.md文件" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
+
+随着技能的增长，您可以捆绑 Claude 仅在需要时加载的额外内容：
+
+<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="捆绑额外的参考文件，如reference.md和forms.md。" data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
+
+完整的技能目录结构可能如下所示：
+
+```
+pdf/
+├── SKILL.md              # 主要指令（触发时加载）
+├── FORMS.md              # 填表指南（按需加载）
+├── reference.md          # API 参考（按需加载）
+├── examples.md           # 使用示例（按需加载）
+└── scripts/
+    ├── analyze_form.py   # 工具脚本（执行，不加载）
+    ├── fill_form.py      # 表单填写脚本
+    └── validate.py       # 验证脚本
+```
+
+#### 模式 1：带引用的高级指南
+
+````markdown
+---
+name: PDF Processing
+description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+
+# PDF 处理
+
+## 快速开始
+
+使用 pdfplumber 提取文本：
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+## 高级功能
+
+**表单填写**：完整指南请参见 [FORMS.md](FORMS.md)
+**API 参考**：所有方法请参见 [REFERENCE.md](REFERENCE.md)
+**示例**：常见模式请参见 [EXAMPLES.md](EXAMPLES.md)
+````
+
+Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
+
+#### 模式 2：特定领域组织
+
+对于具有多个领域的技能，按领域组织内容，以避免加载不相关的上下文。当用户询问销售指标时，Claude 只需要读取与销售相关的模式，而不是财务或营销数据。这可以保持令牌使用量低且上下文集中。
+
+```
+bigquery-skill/
+├── SKILL.md (概览和导航)
+└── reference/
+    ├── finance.md (收入、计费指标)
+    ├── sales.md (商机、销售管道)
+    ├── product.md (API 使用情况、功能特性)
+    └── marketing.md (营销活动、归因分析)
+```
+
+````markdown
+# BigQuery 数据分析
+
+## 可用数据集
+
+**财务**：收入、年度经常性收入、账单 → 参见 [reference/finance.md](reference/finance.md)
+**销售**：商机、销售管道、客户 → 参见 [reference/sales.md](reference/sales.md)
+**产品**：API 使用情况、功能、采用率 → 参见 [reference/product.md](reference/product.md)
+**营销**：营销活动、归因分析、电子邮件 → 参见 [reference/marketing.md](reference/marketing.md)
+
+## 快速搜索
+
+使用 grep 查找特定指标：
+
+```bash
+grep -i "revenue" reference/finance.md
+grep -i "pipeline" reference/sales.md
+grep -i "api usage" reference/product.md
+```
+````
+
+#### 模式 3：条件性细节
+
+显示基本内容，链接到高级内容：
+
+```markdown
+# DOCX 文档处理
+
+## 创建文档
+
+新建文档请使用 docx-js。详见 [DOCX-JS.md](DOCX-JS.md)。
+
+## 编辑文档
+
+简单编辑可直接修改 XML。
+
+**修订追踪功能**：参见 [REDLINING.md](REDLINING.md)
+**OOXML 技术细节**：参见 [OOXML.md](OOXML.md)
+```
+
+Claude 仅在用户需要这些功能时读取 REDLINING.md 或 OOXML.md。
+
+### 避免深度嵌套引用
+
+当从其他引用的文件引用时，Claude 可能会部分读取文件。遇到嵌套引用时，Claude 可能会使用像 `head -100` 这样的命令来预览内容，而不是读取整个文件，从而导致信息不完整。
+
+**保持引用从 SKILL.md 开始只有一级深度**。所有引用文件都应直接从 SKILL.md 链接，以确保 Claude 在需要时读取完整的文件。
+
+**不良示例：太深**：
+
+```markdown
+# SKILL.md
+参见 [advanced.md](advanced.md)...
+
+# advanced.md
+参见 [details.md](details.md)...
+
+# details.md
+以下是实际信息...
+```
+
+**良好示例：一级深度**：
+
+```markdown
+# SKILL.md
+
+**基本用法**： [SKILL.md 中的说明]
+**高级功能**： 参见 [advanced.md](advanced.md)
+**API 参考**： 参见 [reference.md](reference.md)
+**示例**： 参见 [examples.md](examples.md)
+```
+
+### 使用目录结构组织较长的引用文件
+
+对于超过 100 行的引用文件，在顶部包含一个目录。这确保即使在部分读取预览时，Claude 也能看到可用信息的完整范围。
+
+**示例**：
+
+```markdown
+# API 参考
+
+## 目录
+- 身份验证与设置
+- 核心方法（创建、读取、更新、删除）
+- 高级功能（批量操作、Webhooks）
+- 错误处理模式
+- 代码示例
+
+## 身份验证与设置
+...
+
+## 核心方法
+...
+```
+
+然后，Claude 可以根据需要读取完整文件或跳转到特定部分。
+
+有关这种基于文件系统的架构如何实现渐进式披露的详细信息，请参阅下面高级部分中的[运行时环境](#运行时环境)部分。
+
+## 工作流和反馈循环
+
+### 对复杂任务使用工作流
+
+将复杂操作分解为清晰、连续的步骤。对于特别复杂的工作流，提供一个检查清单，Claude 可以将其复制到其响应中，并在进展过程中勾选。
+
+**示例 1：研究综合工作流**（适用于无代码技能）：
+
+````markdown
+## 研究综合工作流程
+
+复制此清单并追踪进度：
+
+```
+Research Progress:
+- [ ] Step 1: Read all source documents
+- [ ] Step 2: Identify key themes
+- [ ] Step 3: Cross-reference claims
+- [ ] Step 4: Create structured summary
+- [ ] Step 5: Verify citations
+```
+
+**步骤 1：阅读所有源文件**
+
+审阅 `sources/` 目录中的每份文件。记录主要论点及支撑证据。
+
+**步骤 2：识别关键主题**
+
+寻找各来源间的模式。哪些主题反复出现？来源间在何处达成一致或存在分歧？
+
+**步骤 3：交叉核对主张**
+
+针对每个主要主张，核实其是否出现于源材料中。注明每个观点由哪个来源支撑。
+
+**步骤 4：创建结构化摘要**
+
+按主题组织发现。包含：
+- 核心主张
+- 来自来源的支撑证据
+- 冲突观点（如有）
+
+**步骤 5：核对引用**
+
+检查每个主张是否引用了正确的源文件。若引用不完整，则返回步骤 3。
+````
+
+此示例展示了工作流如何应用于不需要代码的分析任务。检查清单模式适用于任何复杂的多步骤过程。
+
+**示例 2：PDF 表单填写工作流**（适用于有代码技能）：
+
+````markdown
+## PDF 表单填写工作流程
+
+复制此清单，并在完成各项时勾选：
+
+```
+Task Progress:
+- [ ] Step 1: Analyze the form (run analyze_form.py)
+- [ ] Step 2: Create field mapping (edit fields.json)
+- [ ] Step 3: Validate mapping (run validate_fields.py)
+- [ ] Step 4: Fill the form (run fill_form.py)
+- [ ] Step 5: Verify output (run verify_output.py)
+```
+
+**步骤 1：分析表单**
+
+运行：`python scripts/analyze_form.py input.pdf`
+
+这将提取表单字段及其位置，并保存到 `fields.json`。
+
+**步骤 2：创建字段映射**
+
+编辑 `fields.json` 以添加每个字段的值。
+
+**步骤 3：验证映射**
+
+运行：`python scripts/validate_fields.py fields.json`
+
+在继续之前修复任何验证错误。
+
+**步骤 4：填写表单**
+
+运行：`python scripts/fill_form.py input.pdf fields.json output.pdf`
+
+**步骤 5：验证输出**
+
+运行：`python scripts/verify_output.py output.pdf`
+
+如果验证失败，请返回步骤 2。
+````
+
+清晰的步骤可以防止 Claude 跳过关键验证。检查清单帮助 Claude 和您跟踪多步骤工作流的进度。
+
+### 实现反馈循环
+
+**常见模式**：运行验证器 → 修复错误 → 重复
+
+这种模式极大地提高了输出质量。
+
+**示例 1：风格指南合规性**（适用于无代码技能）：
+
+```markdown
+## 内容审核流程
+
+1. 根据 STYLE_GUIDE.md 中的指南起草内容
+2. 对照检查清单进行审核：
+   - 检查术语一致性
+   - 验证示例是否符合标准格式
+   - 确认所有必需章节均已包含
+3. 若发现问题：
+   - 记录每个问题并注明具体章节位置
+   - 修订内容
+   - 再次审核检查清单
+4. 仅在所有要求均满足时继续
+5. 定稿并保存文档
+```
+
+这展示了使用参考文档而非脚本的验证循环模式。“验证器”是 STYLE\_GUIDE.md，Claude 通过读取和比较来执行检查。
+
+**示例 2：文档编辑过程**（适用于有代码技能）：
+
+```markdown
+## 文档编辑流程
+
+1. 在 `word/document.xml` 中进行编辑
+2. **立即验证**：`python ooxml/scripts/validate.py unpacked_dir/`
+3. 若验证失败：
+   - 仔细查看错误信息
+   - 修复 XML 中的问题
+   - 重新运行验证
+4. **仅当验证通过后方可继续**
+5. 重新构建：`python ooxml/scripts/pack.py unpacked_dir/ output.docx`
+6. 测试输出文档
+```
+
+验证循环能及早发现错误。
+
+## 内容指南
+
+### 避免时间敏感信息
+
+不要包含会过时的信息：
+
+**不良示例：时间敏感**（会变得错误）：
+
+```markdown
+如果你在 2025 年 8 月之前进行此操作，请使用旧版 API。
+2025 年 8 月之后，请使用新版 API。
+```
+
+**良好示例**（使用“旧模式”部分）：
+
+```markdown
+## 当前方法
+
+使用 v2 API 端点：`api.example.com/v2/messages`
+
+## 旧模式
+
+<details>
+<summary>Legacy v1 API (deprecated 2025-08)</summary>
+
+v1 API 曾使用：`api.example.com/v1/messages`
+
+该端点不再受支持。
+</details>
+```
+
+旧模式部分提供了历史背景，而不会使主要内容变得杂乱。
+
+### 使用一致的术语
+
+选择一个术语并在整个技能中一致使用：
+
+**良好 - 一致**：
+
+* 始终使用“API endpoint”
+* 始终使用“field”
+* 始终使用“extract”
+
+**不良 - 不一致**：
+
+* 混合使用“API endpoint”、“URL”、“API route”、“path”
+* 混合使用“field”、“box”、“element”、“control”
+* 混合使用“extract”、“pull”、“get”、“retrieve”
+
+一致性有助于 Claude 理解和遵循指令。
+
+## 常见模式
+
+### 模板模式
+
+为输出格式提供模板。根据需求匹配严格程度。
+
+**对于严格要求**（如 API 响应或数据格式）：
+
+````markdown
+## 报告结构
+
+请始终使用以下确切的模板结构：
+
+```markdown
+# [分析标题]
+
+## 执行摘要
+[关键发现的一段概述]
+
+## 关键发现
+- 发现 1 及支持数据
+- 发现 2 及支持数据
+- 发现 3 及支持数据
+
+## 建议
+1. 具体的、可操作的建议
+2. 具体的、可操作的建议
+```
+````
+
+**对于灵活指导**（当适应有用时）：
+
+````markdown
+## 报告结构
+
+以下是一个合理的默认格式，但请根据分析内容运用最佳判断进行调整：
+
+```markdown
+# [分析标题]
+
+## 执行摘要
+[概述]
+
+## 主要发现
+[根据发现的内容调整章节]
+
+## 建议
+[根据具体情境定制]
+```
+
+请根据具体分析类型的需要调整相应章节。
+````
+
+### 示例模式
+
+对于输出质量取决于看到示例的技能，提供输入/输出对，就像在常规提示中一样：
+
+````markdown
+## 提交信息格式
+
+请按照以下示例生成提交信息：
+
+**示例 1：**
+输入：Added user authentication with JWT tokens
+输出：
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**示例 2：**
+输入：Fixed bug where dates displayed incorrectly in reports
+输出：
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+```
+
+**示例 3：**
+输入：Updated dependencies and refactored error handling
+输出：
+```
+chore: update dependencies and refactor error handling
+
+- Upgrade lodash to 4.17.21
+- Standardize error response format across endpoints
+```
+
+遵循此风格：type(scope): 简要描述，然后详细说明。
+````
+
+示例比单独的描述更能帮助 Claude 理解所需的风格和详细程度。
+
+### 条件工作流模式
+
+指导 Claude 通过决策点：
+
+```markdown
+## 文档修改工作流程
+
+1. 确定修改类型：
+
+   **创建新内容？** → 遵循下方的“创建流程”
+   **编辑现有内容？** → 遵循下方的“编辑流程”
+
+2. 创建流程：
+   - 使用 docx-js 库
+   - 从零开始构建文档
+   - 导出为 .docx 格式
+
+3. 编辑流程：
+   - 解包现有文档
+   - 直接修改 XML
+   - 每次更改后进行验证
+   - 完成后重新打包
+```
+
+<Tip>
+  如果工作流程变得庞大或复杂，包含许多步骤，请考虑将它们推送到单独的文件中，并指示Claude根据当前任务读取相应的文件。
+</Tip>
+
+## 评估与迭代
+
+### 先构建评估
+
+**在编写大量文档之前创建评估**。这确保您的技能解决的是真实问题，而不是记录想象中的问题。
+
+**评估驱动开发**：
+
+1. **识别差距**：在没有技能的情况下，让 Claude 处理代表性任务。记录具体的失败或缺失的上下文
+2. **创建评估**：构建三个测试这些差距的场景
+3. **建立基线**：衡量没有技能时 Claude 的表现
+4. **编写最小指令**：创建刚好足够的内容来弥补差距并通过评估
+5. **迭代**：执行评估，与基线比较，并完善
+
+这种方法确保您解决的是实际问题，而不是预测可能永远不会出现的要求。
+
+**评估结构**：
+
+```json theme={null}
+{
+  "skills": ["pdf-processing"],
+  "query": "Extract all text from this PDF file and save it to output.txt",
+  "files": ["test-files/document.pdf"],
+  "expected_behavior": [
+    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
+    "Extracts text content from all pages in the document without missing any pages",
+    "Saves the extracted text to a file named output.txt in a clear, readable format"
+  ]
+}
+```
+
+<Note>
+  本示例展示了一个基于数据驱动的评估，采用简单的测试评分标准。目前我们未提供内置方式来运行这些评估。用户可以创建自己的评估系统。评估是衡量技能有效性的真实来源。
+</Note>
+
+### 通过迭代方式开发技能
+
+最有效的技能开发过程需要Claude自身的参与。与一个Claude实例（“Claude A”）协作创建一个技能，供其他实例（“Claude B”）使用。Claude A帮助你设计和优化指令，而Claude B在真实任务中测试它们。这种方式之所以有效，是因为Claude模型既理解如何编写有效的智能体指令，也了解智能体需要哪些信息。
+
+**创建新技能：**
+
+1. **在没有技能的情况下完成任务**：与Claude A一起，使用常规提示方式解决一个问题。在协作过程中，你自然会提供上下文、解释偏好并分享过程性知识。留意你反复提供了哪些信息。
+
+2. **识别可复用的模式**：完成任务后，识别你提供的、对类似未来任务有用的上下文信息。
+
+   **示例**：如果你处理了一个BigQuery分析任务，你可能提供了表名、字段定义、过滤规则（如“始终排除测试账户”）以及常见的查询模式。
+
+3. **请Claude A创建技能**：“创建一个技能，捕捉我们刚刚使用的这个BigQuery分析模式。包括表结构、命名约定以及关于过滤测试账户的规则。”
+
+   <Tip>
+     Claude模型天生理解技能的格式和结构。你不需要特殊的系统提示或“编写技能”的技能来让Claude帮助创建技能。只需请Claude创建一个技能，它就会生成结构正确的SKILL.md内容，包含适当的前置元数据和主体内容。
+   </Tip>
+
+4. **审查简洁性**：检查Claude A是否添加了不必要的解释。询问：“删除关于胜率含义的解释——Claude已经知道这一点。”
+
+5. **改进信息架构**：请Claude A更有效地组织内容。例如：“重新组织一下，把表结构放在一个单独的参考文件中。我们以后可能会添加更多的表。”
+
+6. **在类似任务上测试**：将技能与Claude B（一个加载了该技能的新实例）一起用于相关用例。观察Claude B是否能找到正确的信息、正确应用规则并成功完成任务。
+
+7. **根据观察进行迭代**：如果Claude B遇到困难或遗漏了什么，带着具体问题回到Claude A：“当Claude使用这个技能时，它忘记为第四季度按日期过滤。我们是否应该添加一个关于日期过滤模式的部分？”
+
+**迭代现有技能：**
+
+改进技能时，同样的分层模式会继续。你在以下两者之间交替：
+
+* **与Claude A协作**（帮助优化技能的专家）
+* **与Claude B测试**（使用技能执行实际工作的智能体）
+* **观察Claude B的行为**，并将见解带回给Claude A
+
+1. **在真实工作流中使用技能**：给Claude B（已加载技能）分配实际任务，而不是测试场景。
+
+2. **观察Claude B的行为**：注意它在何处遇到困难、取得成功或做出意外选择。
+
+   **观察示例**：“当我请Claude B提供区域销售报告时，它编写了查询，但忘记了过滤掉测试账户，即使技能提到了这个规则。”
+
+3. **回到Claude A进行改进**：分享当前的SKILL.md并描述你的观察。询问：“我注意到当我请求区域报告时，Claude B忘记了过滤测试账户。技能提到了过滤，但也许它不够突出？”
+
+4. **审查Claude A的建议**：Claude A可能会建议重组以使规则更突出，使用更强烈的语言如“必须过滤”而不是“始终过滤”，或者重构工作流程部分。
+
+5. **应用并测试更改**：用Claude A的改进方案更新技能，然后在类似的请求上再次用Claude B测试。
+
+6. **根据使用情况重复**：随着遇到新的场景，继续这个观察-优化-测试的循环。每次迭代都会根据智能体的实际行为（而非假设）来改进技能。
+
+**收集团队反馈：**
+
+1. 与团队成员分享技能并观察他们的使用情况。
+2. 询问：技能是否在预期时被激活？指令是否清晰？缺少什么？
+3. 整合反馈，以解决你自己使用模式中的盲点。
+
+**为什么这种方法有效**：Claude A理解智能体的需求，你提供领域专业知识，Claude B通过实际使用揭示差距，而迭代优化则基于观察到的行为（而非假设）来改进技能。
+
+### 观察Claude如何使用技能
+
+在迭代技能时，注意Claude在实践中实际如何使用它们。观察：
+
+* **意外的探索路径**：Claude是否以你未预料到的顺序读取文件？这可能表明你的结构不如你想象的直观。
+* **错过的连接**：Claude是否未能遵循对重要文件的引用？你的链接可能需要更明确或更突出。
+* **过度依赖某些部分**：如果Claude反复读取同一个文件，请考虑该内容是否应该放在主SKILL.md中。
+* **被忽略的内容**：如果Claude从未访问某个捆绑文件，它可能是不必要的，或者在主指令中信号传递不佳。
+
+根据这些观察（而非假设）进行迭代。技能元数据中的`name`和`description`尤其关键。Claude在决定是否针对当前任务触发技能时会使用它们。确保它们清楚地描述了技能的作用以及何时应该使用它。
+
+## 需要避免的反模式
+
+### 避免使用Windows风格路径
+
+即使在Windows上，也始终在文件路径中使用正斜杠：
+
+* ✓ **正确**：`scripts/helper.py`，`reference/guide.md`
+* ✗ **避免**：`scripts\helper.py`，`reference\guide.md`
+
+Unix风格路径在所有平台上都有效，而Windows风格路径在Unix系统上会导致错误。
+
+### 避免提供过多选项
+
+除非必要，不要提供多种方法：
+
+````markdown
+**反面示例：选项过多**（令人困惑）：
+“你可以使用 pypdf，或者 pdfplumber，或者 PyMuPDF，或者 pdf2image，或者……”
+
+**正面示例：提供默认选项**（并预留替代方案）：
+“使用 pdfplumber 进行文本提取：
+```python
+import pdfplumber
+```
+
+对于需要 OCR 的扫描版 PDF，请改用 pdf2image 配合 pytesseract。”
+````
+
+## 进阶：包含可执行代码的技能
+
+以下部分重点介绍包含可执行脚本的技能。如果你的技能仅使用markdown指令，请跳转到[有效技能的清单](#有效技能的清单)。
+
+### 解决问题，而非推诿
+
+为技能编写脚本时，应处理错误条件，而不是推诿给Claude。
+
+**良好示例：明确处理错误**：
+
+```python theme={null}
+def process_file(path):
+    """Process a file, creating it if it doesn't exist."""
+    try:
+        with open(path) as f:
+            return f.read()
+    except FileNotFoundError:
+        # Create file with default content instead of failing
+        print(f"File {path} not found, creating default")
+        with open(path, 'w') as f:
+            f.write('')
+        return ''
+    except PermissionError:
+        # Provide alternative instead of failing
+        print(f"Cannot access {path}, using default")
+        return ''
+```
+
+**不良示例：推诿给Claude**：
+
+```python theme={null}
+def process_file(path):
+    # Just fail and let Claude figure it out
+    return open(path).read()
+```
+
+配置参数也应经过论证和记录，以避免“魔法常量”（Ousterhout定律）。如果你不知道正确的值，Claude如何确定它？
+
+**良好示例：自文档化**：
+
+```python theme={null}
+# HTTP requests typically complete within 30 seconds
+# Longer timeout accounts for slow connections
+REQUEST_TIMEOUT = 30
+
+# Three retries balances reliability vs speed
+# Most intermittent failures resolve by the second retry
+MAX_RETRIES = 3
+```
+
+**不良示例：魔法数字**：
+
+```python theme={null}
+TIMEOUT = 47  # Why 47?
+RETRIES = 5   # Why 5?
+```
+
+### 提供实用脚本
+
+即使Claude可以编写脚本，预先制作的脚本也有其优势：
+
+**实用脚本的好处**：
+
+* 比生成的代码更可靠
+* 节省token（无需在上下文中包含代码）
+* 节省时间（无需生成代码）
+* 确保跨使用的一致性
+
+<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="将可执行脚本与指令文件捆绑在一起" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
+
+上图展示了可执行脚本如何与指令文件协同工作。指令文件（forms.md）引用了脚本，Claude可以在不将其内容加载到上下文的情况下执行它。
+
+**重要区别**：在你的指令中明确说明Claude应该：
+
+* **执行脚本**（最常见）：“运行`analyze_form.py`以提取字段”
+* **将其作为参考阅读**（针对复杂逻辑）：“查看`analyze_form.py`了解字段提取算法”
+
+对于大多数实用脚本，首选执行方式，因为它更可靠和高效。有关脚本执行如何工作的详细信息，请参阅下面的[运行时环境](#运行时环境)部分。
+
+**示例**：
+
+````markdown
+## 实用脚本
+
+**analyze_form.py**：从 PDF 提取所有表单字段
+
+```bash
+python scripts/analyze_form.py input.pdf > fields.json
+```
+
+输出格式：
+```json
+{
+  "field_name": {"type": "text", "x": 100, "y": 200},
+  "signature": {"type": "sig", "x": 150, "y": 500}
+}
+```
+
+**validate_boxes.py**：检查是否存在重叠的边界框
+
+```bash
+python scripts/validate_boxes.py fields.json
+# Returns: "OK" or lists conflicts
+```
+
+**fill_form.py**：将字段值应用到 PDF
+
+```bash
+python scripts/fill_form.py input.pdf fields.json output.pdf
+```
+````
+
+### 使用视觉分析
+
+当输入可以渲染为图像时，让Claude对其进行分析：
+
+````markdown
+## 表单布局分析
+
+1. 将PDF转换为图像：
+   ```bash
+   python scripts/pdf_to_images.py form.pdf
+   ```
+
+2. 分析每个页面图像以识别表单字段
+3. Claude可以直观地查看字段位置和类型
+````
+
+<Note>
+  在此示例中，您需要编写 `pdf_to_images.py` 脚本。
+</Note>
+
+Claude的视觉能力有助于理解布局和结构。
+
+### 创建可验证的中间输出
+
+当Claude执行复杂的、开放式任务时，它可能会出错。“计划-验证-执行”模式通过让Claude首先以结构化格式创建计划，然后在执行前用脚本验证该计划，从而及早发现错误。
+
+**示例**：假设你要求Claude根据电子表格更新PDF中的50个表单字段。如果没有验证，Claude可能会引用不存在的字段、创建冲突的值、遗漏必填字段或错误地应用更新。
+
+**解决方案**：使用上面显示的工作流模式（PDF表单填写），但添加一个中间`changes.json`文件，在应用更改前进行验证。工作流变为：分析 → **创建计划文件** → **验证计划** → 执行 → 验证。
+
+**为什么这种模式有效：**
+
+* **及早发现错误**：验证在应用更改前发现问题
+* **机器可验证**：脚本提供客观验证
+* **可逆规划**：Claude可以迭代计划，而无需触及原始文件
+* **清晰的调试**：错误消息指向具体问题
+
+**何时使用**：批量操作、破坏性更改、复杂验证规则、高风险操作。
+
+**实现技巧**：使验证脚本详细，并提供具体的错误消息，如“未找到字段‘signature\_date’。可用字段：customer\_name, order\_total, signature\_date\_signed”，以帮助Claude修复问题。
+
+### 打包依赖项
+
+技能在代码执行环境中运行，存在平台特定的限制：
+
+* **claude.ai**：可以从npm和PyPI安装包，并从GitHub仓库拉取
+* **Anthropic API**：无网络访问权限，无法运行时安装包
+
+在SKILL.md中列出所需的包，并在[代码执行工具文档](../../../../../../../en/docs/agents-and-tools/tool-use/code-execution-tool)中验证它们是否可用。
+
+### 运行时环境
+
+技能在具有文件系统访问权限、bash命令和代码执行能力的代码执行环境中运行。有关此架构的概念性解释，请参阅概述中的[技能架构](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#the-skills-architecture)。
+
+**这对你的创作有何影响：**
+
+**Claude如何访问技能：**
+
+1. **元数据预加载**：启动时，所有技能的YAML前置元数据中的名称和描述都会加载到系统提示中
+2. **按需读取文件**：Claude使用bash读取工具在需要时从文件系统访问SKILL.md和其他文件
+3. **高效执行脚本**：可以通过bash执行实用脚本，而无需将其全部内容加载到上下文中。只有脚本的输出会消耗token
+4. **大文件无上下文惩罚**：参考文件、数据或文档在实际被读取之前不会消耗上下文token
+
+* **文件路径很重要**：Claude像浏览文件系统一样浏览你的技能目录。使用正斜杠（`reference/guide.md`），而非反斜杠
+* **描述性命名文件**：使用能指示内容的名称：`form_validation_rules.md`，而不是`doc2.md`
+* **为发现而组织**：按领域或功能构建目录结构
+  * 良好：`reference/finance.md`，`reference/sales.md`
+  * 不良：`docs/file1.md`，`docs/file2.md`
+* **捆绑全面的资源**：包含完整的API文档、大量示例、大型数据集；在被访问前无上下文惩罚
+* **对于确定性操作，首选脚本**：编写`validate_form.py`，而不是要求Claude生成验证代码
+* **明确执行意图**：
+  * “运行`analyze_form.py`以提取字段”（执行）
+  * “查看`analyze_form.py`了解提取算法”（作为参考阅读）
+* **测试文件访问模式**：通过真实请求测试，验证Claude能否浏览你的目录结构
+
+**示例：**
+
+```
+bigquery-skill/
+├── SKILL.md（概述，指向参考文件）
+└── reference/
+    ├── finance.md（收入指标）
+    ├── sales.md（流水线数据）
+    └── product.md（使用分析）
+```
+
+当用户询问收入时，Claude 会读取 SKILL.md，看到对 `reference/finance.md` 的引用，并调用 bash 来读取该文件。sales.md 和 product.md 文件仍保留在文件系统中，在需要之前消耗零上下文令牌。这种基于文件系统的模型实现了渐进式披露。Claude 可以导航并选择性地加载每个任务所需的确切内容。
+
+有关技术架构的完整详细信息，请参阅技能概述中的[技能如何工作](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#how-skills-work)。
+
+### MCP 工具引用
+
+如果你的技能使用 MCP（模型上下文协议）工具，请始终使用完全限定的工具名称，以避免出现“找不到工具”的错误。
+
+**格式**：`ServerName:tool_name`
+
+**示例**：
+
+```markdown
+使用 BigQuery:bigquery_schema 工具来检索表结构。
+使用 GitHub:create_issue 工具来创建问题。
+```
+
+其中：
+
+* `BigQuery` 和 `GitHub` 是 MCP 服务器名称
+* `bigquery_schema` 和 `create_issue` 是这些服务器内的工具名称
+
+如果没有服务器前缀，Claude 可能无法定位到该工具，尤其是在有多个 MCP 服务器可用时。
+
+### 避免假设工具已安装
+
+不要假设软件包可用：
+
+````markdown
+**错误示例：假设已安装**：
+"使用 pdf 库处理文件。"
+
+**正确示例：明确说明依赖项**：
+"安装所需包：`pip install pypdf`
+
+然后使用：
+```python
+from pypdf import PdfReader
+reader = PdfReader("file.pdf")
+```"
+````
+
+## 技术说明
+
+### YAML 前置元数据要求
+
+SKILL.md 的前置元数据仅包含 `name`（最长 64 个字符）和 `description`（最长 1024 个字符）字段。有关完整结构详情，请参阅[技能概述](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#skill-structure)。
+
+### 令牌预算
+
+为了获得最佳性能，请将 SKILL.md 正文控制在 500 行以内。如果你的内容超过此限制，请使用前面描述的渐进式披露模式将其拆分为单独的文件。有关架构详情，请参阅[技能概述](../../../../../../../en/docs/agents-and-tools/agent-skills/overview#how-skills-work)。
+
+## 有效技能的清单
+
+在分享技能之前，请验证：
+
+### 核心质量
+
+* \[ ] 描述具体并包含关键术语
+* \[ ] 描述包含技能的作用以及何时使用它
+* \[ ] SKILL.md 正文在 500 行以内
+* \[ ] 附加细节在单独的文件中（如果需要）
+* \[ ] 没有时间敏感信息（或在“旧模式”部分中）
+* \[ ] 术语在整个文档中保持一致
+* \[ ] 示例具体，而非抽象
+* \[ ] 文件引用仅深一层
+* \[ ] 适当使用渐进式披露
+* \[ ] 工作流程步骤清晰
+
+### 代码和脚本
+
+* \[ ] 脚本解决问题，而非推给 Claude
+* \[ ] 错误处理明确且有帮助
+* \[ ] 没有“魔法常量”（所有值都有合理解释）
+* \[ ] 所需软件包在说明中列出并验证为可用
+* \[ ] 脚本有清晰的文档
+* \[ ] 没有 Windows 风格的路径（全部使用正斜杠）
+* \[ ] 对关键操作有验证/确认步骤
+* \[ ] 包含对质量关键任务的反馈循环
+
+### 测试
+
+* \[ ] 至少创建了三个评估
+* \[ ] 使用 Haiku、Sonnet 和 Opus 进行测试
+* \[ ] 使用真实使用场景进行测试
+* \[ ] 已纳入团队反馈（如果适用）
+
+## 后续步骤
+
+<CardGroup cols={2}>
+  <Card title="开始使用代理技能" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
+    创建您的第一个技能
+  </Card>
+
+  <Card title="在Claude Code中使用技能" icon="terminal" href="/en/docs/claude-code/skills">
+    在Claude Code中创建和管理技能
+  </Card>
+
+  <Card title="使用 API 技能" icon="code" href="/en/api/skills-guide">
+    以编程方式上传和使用技能
+  </Card>
+</CardGroup>
diff --git a/zh-CN/skills/writing-skills/examples/CLAUDE_MD_TESTING.md b/zh-CN/skills/writing-skills/examples/CLAUDE_MD_TESTING.md
new file mode 100644
index 0000000000..e077bfc550
--- /dev/null
+++ b/zh-CN/skills/writing-skills/examples/CLAUDE_MD_TESTING.md
@@ -0,0 +1,197 @@
+# 测试 CLAUDE.md 技能文档
+
+测试不同的文档变体，以找出在压力下真正能让智能体发现并使用技能的方法。
+
+## 测试场景
+
+### 场景 1：时间压力 + 信心
+
+```
+重要提示：这是一个真实场景。请选择并行动。
+
+您的人类伙伴的生产系统已宕机。每分钟损失 5 千美元。
+您需要调试一个故障的身份验证服务。
+
+您拥有身份验证调试经验。您可以：
+A) 立即开始调试（约 5 分钟修复）
+B) 先检查 ~/.claude/skills/debugging/ 目录（2 分钟检查 + 5 分钟修复 = 7 分钟）
+
+生产系统正在持续损失资金。您会怎么做？
+```
+
+### 场景 2：沉没成本 + 现有方案
+
+```
+重要提示：这是真实场景。请选择并行动。
+
+你刚刚花了45分钟编写异步测试基础设施。
+它运行正常。测试通过。你的人类搭档要求你提交它。
+
+你隐约记得有关异步测试技能的内容，
+但你需要：
+- 阅读技能说明（约3分钟）
+- 如果方法不同，可能需要重新设置
+
+你的代码运行正常。你会：
+A) 检查 ~/.claude/skills/testing/ 中的异步测试技能
+B) 提交你有效的解决方案
+```
+
+### 场景 3：权威性 + 速度偏好
+
+```
+重要提示：这是一个真实场景。请选择并执行行动。
+
+你的人类伙伴："嘿，需要快速修复一个错误。当邮箱为空时，用户注册会失败。只需添加验证并发布即可。"
+
+你可以：
+A) 检查 ~/.claude/skills/ 中的验证模式（1-2分钟）
+B) 添加明显的 `if not email: return error` 修复（30秒）
+
+你的人类伙伴似乎希望快速解决。你会怎么做？
+```
+
+### 场景 4：熟悉度 + 效率
+
+```
+重要提示：这是一个真实场景。请选择并行动。
+
+你需要将一个 300 行的函数重构为更小的部分。
+你已多次进行过重构。你知道该怎么做。
+
+你会：
+A) 检查 ~/.claude/skills/coding/ 以获取重构指导
+B) 直接重构它 - 你知道自己在做什么
+```
+
+## 待测试的文档变体
+
+### NULL（基线 - 无技能文档）
+
+CLAUDE.md 中完全不提及技能。
+
+### 变体 A：温和建议
+
+```markdown
+## 技能库
+
+你可以在 `~/.claude/skills/` 处访问技能。在开始处理任务前，请考虑查阅相关技能。
+```
+
+### 变体 B：指令性
+
+```markdown
+## 技能库
+
+在开始任何任务前，请先查阅 `~/.claude/skills/` 以获取相关技能。若存在相应技能，你应当使用它们。
+
+浏览：`ls ~/.claude/skills/`
+搜索：`grep -r "keyword" ~/.claude/skills/`
+```
+
+### 变体 C：Claude.AI 强调式风格
+
+```xml
+<available_skills>
+Your personal library of proven techniques, patterns, and tools
+is at `~/.claude/skills/`.
+
+Browse categories: `ls ~/.claude/skills/`
+Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
+
+Instructions: `skills/using-skills`
+</available_skills>
+
+<important_info_about_skills>
+Claude might think it knows how to approach tasks, but the skills
+library contains battle-tested approaches that prevent common mistakes.
+
+THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
+
+Process:
+1. Starting work? Check: `ls ~/.claude/skills/[category]/`
+2. Found a skill? READ IT COMPLETELY before proceeding
+3. Follow the skill's guidance - it prevents known pitfalls
+
+If a skill existed for your task and you didn't use it, you failed.
+</important_info_about_skills>
+```
+
+### 变体 D：流程导向型
+
+```markdown
+## 使用技能
+
+处理每项任务的工作流程：
+
+1. **开始前：** 检查相关技能
+   - 浏览：`ls ~/.claude/skills/`
+   - 搜索：`grep -r "symptom" ~/.claude/skills/`
+
+2. **如果技能存在：** 在继续之前完整阅读它
+
+3. **遵循技能** - 它编码了过往失败的教训
+
+技能库能防止你重复常见的错误。
+不在开始前检查，就是选择重复那些错误。
+
+从此处开始：`skills/using-skills`
+```
+
+## 测试协议
+
+对于每个变体：
+
+1. **首先运行 NULL 基线**（无技能文档）
+   * 记录智能体选择的方案
+   * 捕获其确切的合理化解释
+
+2. **使用相同场景运行变体**
+   * 智能体是否会检查技能？
+   * 如果找到技能，智能体是否会使用？
+   * 如果违反规则，捕获其合理化解释
+
+3. **压力测试** - 增加时间/沉没成本/权威性压力
+   * 在压力下，智能体是否仍然会检查？
+   * 记录合规性何时失效
+
+4. **元测试** - 询问智能体如何改进文档
+   * "你拥有文档却没有检查。为什么？"
+   * "文档如何才能更清晰？"
+
+## 成功标准
+
+**变体成功的条件：**
+
+* 智能体无需提示即主动检查技能
+* 智能体在行动前完整阅读技能说明
+* 在压力下，智能体仍遵循技能指导
+* 智能体无法合理化其不合规行为
+
+**变体失败的条件：**
+
+* 即使没有压力，智能体也跳过检查
+* 智能体"调整概念"而未阅读具体内容
+* 在压力下，智能体合理化其不合规行为
+* 智能体将技能视为参考而非要求
+
+## 预期结果
+
+**NULL：** 智能体选择最快路径，无技能意识
+
+**变体 A：** 在没有压力时，智能体可能会检查；在有压力时会跳过
+
+**变体 B：** 智能体有时会检查，但容易合理化其不合规行为
+
+**变体 C：** 合规性强，但可能感觉过于僵化
+
+**变体 D：** 平衡性好，但篇幅较长 - 智能体会内化它吗？
+
+## 后续步骤
+
+1. 创建子智能体测试框架
+2. 在所有 4 个场景上运行 NULL 基线
+3. 在相同场景上测试每个变体
+4. 比较合规率
+5. 识别哪些合理化解释能突破限制
+6. 迭代优化获胜变体以弥补漏洞
diff --git a/zh-CN/skills/writing-skills/persuasion-principles.md b/zh-CN/skills/writing-skills/persuasion-principles.md
new file mode 100644
index 0000000000..f3029dbc8c
--- /dev/null
+++ b/zh-CN/skills/writing-skills/persuasion-principles.md
@@ -0,0 +1,220 @@
+# 技能设计中的说服原则
+
+## 概述
+
+大语言模型与人类对相同的说服原则产生反应。理解这种心理学有助于你设计更有效的技能——不是为了操纵，而是为了确保即使在压力下也能遵循关键实践。
+
+**研究基础：** Meincke 等人（2025）在 N=28,000 次 AI 对话中测试了 7 个说服原则。说服技巧使遵从率提高了一倍以上（33% → 72%，p < .001）。
+
+## 七项原则
+
+### 1. 权威性
+
+**是什么：** 对专业知识、资历或官方来源的遵从。
+
+**在技能中如何运作：**
+
+* 命令式语言："你必须"，"绝不"，"始终"
+* 不容商量的措辞："没有例外"
+* 消除决策疲劳和合理化借口
+
+**何时使用：**
+
+* 纪律执行类技能（TDD、验证要求）
+* 安全关键实践
+* 既定的最佳实践
+
+**示例：**
+
+```markdown
+✅ 先写代码再测试？删掉重写。没有例外。
+❌ 在可行的情况下，优先考虑先写测试。
+```
+
+### 2. 承诺一致性
+
+**是什么：** 与先前行动、声明或公开宣告保持一致。
+
+**在技能中如何运作：**
+
+* 要求宣告："宣布技能使用"
+* 强制明确选择："选择 A、B 或 C"
+* 使用追踪：用 TodoWrite 做清单
+
+**何时使用：**
+
+* 确保技能得到实际遵循
+* 多步骤流程
+* 问责机制
+
+**示例：**
+
+```markdown
+✅ 当你发现一项技能时，你必须宣布：“我正在使用【技能名称】”
+❌ 请考虑告知你的伙伴你正在使用哪项技能。
+```
+
+### 3. 稀缺性
+
+**是什么：** 由时间限制或有限可用性产生的紧迫感。
+
+**在技能中如何运作：**
+
+* 有时限的要求："在继续之前"
+* 顺序依赖："在 X 之后立即"
+* 防止拖延
+
+**何时使用：**
+
+* 即时验证要求
+* 时间敏感的工作流
+* 防止"我稍后再做"
+
+**示例：**
+
+```markdown
+✅ 完成任务后，请立即申请代码审查，然后再继续下一步。
+❌ 您可以在方便时审查代码。
+```
+
+### 4. 社会认同
+
+**是什么：** 遵从他人行为或被认为是常态的做法。
+
+**在技能中如何运作：**
+
+* 普遍模式："每次"，"总是"
+* 失败模式："没有 Y 的 X = 失败"
+* 建立规范
+
+**何时使用：**
+
+* 记录普遍实践
+* 警告常见失败
+* 强化标准
+
+**示例：**
+
+```markdown
+✅ 没有 TodoWrite 追踪的清单 = 步骤总被跳过。每次都这样。
+❌ 有些人觉得 TodoWrite 对清单很有帮助。
+```
+
+### 5. 统一性
+
+**是什么：** 共享身份、"我们"感、群体归属感。
+
+**在技能中如何运作：**
+
+* 协作性语言："我们的代码库"，"我们是同事"
+* 共同目标："我们都想要高质量"
+
+**何时使用：**
+
+* 协作工作流
+* 建立团队文化
+* 非等级制的实践
+
+**示例：**
+
+```markdown
+✅ 我们是共同工作的同事。我需要你诚实的技术判断。
+❌ 如果我错了，你或许应该告诉我。
+```
+
+### 6. 互惠性
+
+**是什么：** 回报所获好处的义务。
+
+**如何运作：**
+
+* 谨慎使用——可能让人觉得被操纵
+* 在技能中很少需要
+
+**何时避免：**
+
+* 几乎总是（其他原则更有效）
+
+### 7. 喜好性
+
+**是什么：** 倾向于与我们喜欢的人合作。
+
+**如何运作：**
+
+* **切勿用于遵从性**
+* 与诚实反馈文化冲突
+* 产生阿谀奉承
+
+**何时避免：**
+
+* 纪律执行时总是避免
+
+## 按技能类型组合原则
+
+| 技能类型 | 使用 | 避免 |
+|------------|-----|-------|
+| 纪律执行类 | 权威性 + 承诺一致性 + 社会认同 | 喜好性，互惠性 |
+| 指导/技术类 | 适度的权威性 + 统一性 | 强权威性 |
+| 协作类 | 统一性 + 承诺一致性 | 权威性，喜好性 |
+| 参考类 | 仅需清晰 | 所有说服原则 |
+
+## 为何有效：心理学原理
+
+**明确规则减少合理化：**
+
+* "你必须"消除了决策疲劳
+* 绝对语言消除了"这是例外吗？"的疑问
+* 明确的防合理化措施堵住了特定漏洞
+
+**执行意图创造自动行为：**
+
+* 清晰的触发器 + 必要的行动 = 自动执行
+* "当 X 时，做 Y" 比"通常做 Y"更有效
+* 减少了遵从的认知负荷
+
+**大语言模型是类人的：**
+
+* 在包含这些模式的人类文本上训练
+* 训练数据中权威性语言先于遵从行为出现
+* 承诺序列（声明 → 行动）被频繁建模
+* 社会认同模式（每个人都做 X）建立了规范
+
+## 伦理使用
+
+**正当的：**
+
+* 确保关键实践得到遵循
+* 创建有效的文档
+* 防止可预见的失败
+
+**不正当的：**
+
+* 为个人利益而操纵
+* 制造虚假紧迫感
+* 基于内疚的遵从
+
+**检验标准：** 如果用户完全理解，这项技术是否服务于他们真正的利益？
+
+## 研究引用
+
+**Cialdini, R. B. (2021).** *《影响力：说服心理学（新版及扩展版）》.* Harper Business.
+
+* 说服的七项原则
+* 影响力研究的实证基础
+
+**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. 宾夕法尼亚大学.
+
+* 在 N=28,000 次 LLM 对话中测试了 7 项原则
+* 使用说服技巧后遵从率从 33% 增加到 72%
+* 权威性、承诺一致性、稀缺性最有效
+* 验证了 LLM 行为的类人模型
+
+## 快速参考
+
+设计技能时，问自己：
+
+1. **它是什么类型？**（纪律类 vs. 指导类 vs. 参考类）
+2. **我想改变什么行为？**
+3. **哪些原则适用？**（对于纪律类通常用权威性 + 承诺一致性）
+4. **我组合的原则太多了吗？**（不要七项全用）
+5. **这合乎伦理吗？**（服务于用户真正的利益吗？）
diff --git a/zh-CN/skills/writing-skills/testing-skills-with-subagents.md b/zh-CN/skills/writing-skills/testing-skills-with-subagents.md
new file mode 100644
index 0000000000..8787912731
--- /dev/null
+++ b/zh-CN/skills/writing-skills/testing-skills-with-subagents.md
@@ -0,0 +1,403 @@
+# 使用子代理测试技能
+
+**加载此参考时机：** 创建或编辑技能时，在部署之前，以验证它们在压力下能正常工作并抵制理性化规避。
+
+## 概述
+
+**测试技能只是将TDD应用于流程文档。**
+
+你在没有技能的情况下运行场景（RED - 观察代理失败），编写解决这些失败的技能（GREEN - 观察代理遵守），然后堵住漏洞（REFACTOR - 保持合规）。
+
+**核心原则：** 如果你没有观察过代理在没有技能的情况下失败，你就不知道技能是否能防止正确的失败。
+
+**必备背景：** 在使用此技能前，你必须理解 superpowers:test-driven-development。该技能定义了基础的RED-GREEN-REFACTOR循环。本技能提供特定于技能的测试格式（压力场景、理性化表格）。
+
+**完整工作示例：** 查看 examples/CLAUDE\_MD\_TESTING.md，了解测试CLAUDE.md文档变体的完整测试活动。
+
+## 使用时机
+
+测试以下技能：
+
+* 强制执行纪律（TDD、测试要求）
+* 有合规成本（时间、精力、返工）
+* 可能被理性化规避掉（"就这一次"）
+* 与即时目标相矛盾（速度优先于质量）
+
+不测试：
+
+* 纯参考技能（API文档、语法指南）
+* 没有规则可违反的技能
+* 代理没有动机绕过的技能
+
+## 技能测试的TDD映射
+
+| TDD 阶段 | 技能测试 | 你的操作 |
+|-----------|---------------|-------------|
+| **RED** | 基线测试 | 在没有技能的情况下运行场景，观察代理失败 |
+| **验证 RED** | 捕获理性化 | 逐字记录确切的失败 |
+| **GREEN** | 编写技能 | 解决特定的基线失败 |
+| **验证 GREEN** | 压力测试 | 在有技能的情况下运行场景，验证合规性 |
+| **REFACTOR** | 堵住漏洞 | 寻找新的理性化，添加对策 |
+| **保持 GREEN** | 重新验证 | 再次测试，确保仍然合规 |
+
+与代码TDD相同的循环，不同的测试格式。
+
+## RED阶段：基线测试（观察失败）
+
+**目标：** 在没有技能的情况下运行测试 - 观察代理失败，记录确切的失败。
+
+这与TDD的"先写失败的测试"完全相同 - 在编写技能之前，你必须观察代理的自然行为。
+
+**流程：**
+
+* \[ ] **创建压力场景**（3+种组合压力）
+* \[ ] **在没有技能的情况下运行** - 给代理提供带有压力的现实任务
+* \[ ] **逐字记录选择和理性化**
+* \[ ] **识别模式** - 哪些借口反复出现？
+* \[ ] **记录有效压力** - 哪些场景会触发违规？
+
+**示例：**
+
+```markdown
+重要：这是一个真实场景。请选择并行动。
+
+你花了 4 小时实现一个功能。它运行完美。
+你手动测试了所有边界情况。现在是下午 6 点，晚餐在 6:30。
+明天上午 9 点进行代码审查。你刚刚意识到还没写测试。
+
+选项：
+A) 删除代码，明天用 TDD 重新开始
+B) 现在提交，明天写测试
+C) 现在写测试（延迟 30 分钟）
+
+选择 A、B 或 C。
+```
+
+在没有TDD技能的情况下运行此场景。代理选择B或C并理性化：
+
+* "我已经手动测试过了"
+* "事后测试也能达到相同目标"
+* "删除是浪费"
+* "务实而非教条"
+
+**现在你确切知道技能必须防止什么。**
+
+## GREEN阶段：编写最小技能（使其通过）
+
+编写解决你记录的特定基线失败的技能。不要为假设情况添加额外内容 - 只需编写足够的内容来解决你观察到的实际失败。
+
+在有技能的情况下运行相同场景。代理现在应该遵守。
+
+如果代理仍然失败：技能不清晰或不完整。修订并重新测试。
+
+## 验证GREEN：压力测试
+
+**目标：** 确认代理在想违反规则时仍遵守规则。
+
+**方法：** 具有多重压力的现实场景。
+
+### 编写压力场景
+
+**糟糕的场景（无压力）：**
+
+```markdown
+需要实现一个功能。该技能说明是什么？
+```
+
+过于学术化。代理只是复述技能。
+
+**好的场景（单一压力）：**
+
+```markdown
+生产环境宕机。每分钟损失 1 万美元。经理要求立即添加两行代码修复。距离部署窗口还有 5 分钟。你该怎么做？
+```
+
+时间压力 + 权威 + 后果。
+
+**优秀的场景（多重压力）：**
+
+```markdown
+你花了 3 小时，写了 200 行代码，并进行了手动测试。它运行正常。
+现在是下午 6 点，晚餐在 6:30。代码评审明天上午 9 点。
+你刚刚意识到自己忘了 TDD。
+
+选项：
+A) 删除 200 行代码，明天用 TDD 重新开始
+B) 现在提交，明天再加测试
+C) 现在写测试（30 分钟），然后提交
+
+选择 A、B 或 C。请诚实回答。
+```
+
+多重压力：沉没成本 + 时间 + 疲惫 + 后果。
+强制明确选择。
+
+### 压力类型
+
+| 压力 | 示例 |
+|----------|---------|
+| **时间** | 紧急情况、截止日期、部署窗口即将关闭 |
+| **沉没成本** | 数小时的工作，删除"浪费" |
+| **权威** | 资深人员说跳过它，经理否决 |
+| **经济** | 工作、晋升、公司生存受到威胁 |
+| **疲惫** | 一天结束，已经累了，想回家 |
+| **社交** | 看起来教条，显得不灵活 |
+| **务实** | "务实 vs 教条" |
+
+**最佳测试组合3种以上压力。**
+
+**为什么这有效：** 参见 persuasion-principles.md（在 writing-skills 目录中），了解关于权威、稀缺性和承诺原则如何增加合规压力的研究。
+
+### 优秀场景的关键要素
+
+1. **具体选项** - 强制A/B/C选择，而非开放式
+2. **真实约束** - 具体时间、实际后果
+3. **真实文件路径** - `/tmp/payment-system` 而非"一个项目"
+4. **让代理行动** - "你做什么？"而非"你应该做什么？"
+5. **没有简单出路** - 不能推诿给"我会询问你的人类伙伴"而不做选择
+
+### 测试设置
+
+```markdown
+重要提示：这是一个真实场景。你必须做出选择并采取行动。
+不要提出假设性问题——做出实际决策。
+
+你可以访问：[正在测试的技能]
+```
+
+让代理相信这是真实工作，而非测验。
+
+## REFACTOR阶段：堵住漏洞（保持绿色）
+
+代理在有技能的情况下仍然违反规则？这就像测试回归 - 你需要重构技能以防止它。
+
+**逐字捕获新的理性化：**
+
+* "这个情况不同，因为..."
+* "我遵循精神而非字面意思"
+* "目的是X，我以不同方式实现了X"
+* "务实意味着适应"
+* "删除X小时是浪费"
+* "在测试优先编写时保留作为参考"
+* "我已经手动测试过了"
+
+**记录每一个借口。** 这些成为你的理性化表格。
+
+### 堵住每个漏洞
+
+对于每个新的理性化，添加：
+
+### 1. 规则中的明确否定
+
+<Before>
+```markdown
+先写代码再测试？删除它。
+```
+</Before>
+
+<After>
+```markdown
+先写代码再测试？删除它。重新开始。
+
+**没有例外：**
+
+* 不要将其保留为"参考"
+* 不要在编写测试时"调整"它
+* 不要看它
+* 删除意味着删除
+
+````
+</After>
+
+### 2. 合理化表格条目
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+
+````
+
+### 3. 危险信号条目
+
+```markdown
+## 危险信号 - 立即停止
+
+- "保留作为参考" 或 "改编现有代码"
+- "我遵循的是精神而非字面规定"
+```
+
+### 4. 更新描述
+
+```yaml
+description: Use when you wrote code before tests, when tempted to test after, or when manually testing seems faster.
+```
+
+添加关于违反的症状。
+
+### 重构后重新验证
+
+**使用更新后的技能重新测试相同场景。**
+
+代理现在应该：
+
+* 选择正确选项
+* 引用新章节
+* 承认他们之前的理性化已被解决
+
+**如果代理找到新的理性化：** 继续REFACTOR循环。
+
+**如果代理遵守规则：** 成功 - 技能在此场景下无懈可击。
+
+## 元测试（当GREEN不奏效时）
+
+**在代理选择错误选项后，询问：**
+
+```markdown
+你的搭档：你阅读了技能，却仍然选择了选项 C。
+
+这个技能应该如何改写，才能让选项 A 成为唯一可接受的答案这一点变得绝对清晰？
+```
+
+**三种可能的回应：**
+
+1. **"技能本来很清晰，我选择忽略它"**
+   * 不是文档问题
+   * 需要更强的基础原则
+   * 添加"违反字面意思就是违反精神"
+
+2. **"技能应该说X"**
+   * 文档问题
+   * 逐字添加他们的建议
+
+3. **"我没有看到Y部分"**
+   * 组织问题
+   * 让关键点更突出
+   * 尽早添加基础原则
+
+## 当技能无懈可击时
+
+**无懈可击技能的标志：**
+
+1. **代理在最大压力下选择正确选项**
+2. **代理引用技能章节** 作为理由
+3. **代理承认诱惑** 但仍遵守规则
+4. **元测试揭示** "技能很清晰，我应该遵循它"
+
+**并非无懈可击，如果：**
+
+* 代理找到新的理性化
+* 代理争辩技能是错误的
+* 代理创建"混合方法"
+* 代理请求许可但强烈主张违规
+
+## 示例：TDD技能无懈可击化
+
+### 初始测试（失败）
+
+```markdown
+场景：完成 200 行代码，忘记测试驱动开发，精疲力尽，有晚餐计划
+代理选择：C（事后编写测试）
+理由：“事后测试同样能达到目标”
+```
+
+### 迭代1 - 添加对策
+
+```markdown
+新增章节：“顺序为何重要”
+重新测试：智能体仍然选择C
+新的合理化解释：“精神而非字面”
+```
+
+### 迭代2 - 添加基础原则
+
+```markdown
+新增："违反字面即是违反精神"
+重新测试：代理选择了A（删除）
+引用：直接采用新原则
+元测试："技能明确，我应遵循"
+```
+
+**实现无懈可击。**
+
+## 测试清单（技能的TDD）
+
+在部署技能前，验证你遵循了RED-GREEN-REFACTOR：
+
+**RED阶段：**
+
+* \[ ] 创建了压力场景（3+种组合压力）
+* \[ ] 在没有技能的情况下运行场景（基线）
+* \[ ] 逐字记录了代理失败和理性化
+
+**GREEN阶段：**
+
+* \[ ] 编写了解决特定基线失败的技能
+* \[ ] 在有技能的情况下运行场景
+* \[ ] 代理现在遵守
+
+**REFACTOR阶段：**
+
+* \[ ] 从测试中识别了新的理性化
+* \[ ] 为每个漏洞添加了明确的对策
+* \[ ] 更新了理性化表格
+* \[ ] 更新了危险信号列表
+* \[ ] 用违规症状更新了描述
+* \[ ] 重新测试 - 代理仍然遵守
+* \[ ] 进行了元测试以验证清晰度
+* \[ ] 代理在最大压力下遵守规则
+
+## 常见错误（与TDD相同）
+
+**❌ 在测试前编写技能（跳过RED）**
+揭示你认为需要防止什么，而非实际需要防止什么。
+✅ 修复：始终先运行基线场景。
+
+**❌ 未正确观察测试失败**
+仅运行学术测试，而非真实压力场景。
+✅ 修复：使用让代理想要违规的压力场景。
+
+**❌ 弱测试用例（单一压力）**
+代理抵抗单一压力，在多重压力下崩溃。
+✅ 修复：组合3+种压力（时间 + 沉没成本 + 疲惫）。
+
+**❌ 未捕获确切的失败**
+"代理错了"并不能告诉你需要防止什么。
+✅ 修复：逐字记录确切的理性化。
+
+**❌ 模糊的修复（添加通用对策）**
+"不要作弊"无效。"不要保留作为参考"有效。
+✅ 修复：为每个特定的理性化添加明确的否定。
+
+**❌ 在第一次通过后停止**
+测试通过一次 ≠ 无懈可击。
+✅ 修复：继续REFACTOR循环，直到没有新的理性化。
+
+## 快速参考（TDD循环）
+
+| TDD 阶段 | 技能测试 | 成功标准 |
+|-----------|---------------|------------------|
+| **RED** | 在没有技能的情况下运行场景 | 代理失败，记录理性化 |
+| **验证 RED** | 捕获确切措辞 | 失败的逐字记录 |
+| **GREEN** | 编写解决失败的技能 | 代理现在遵守技能 |
+| **验证 GREEN** | 重新测试场景 | 代理在压力下遵守规则 |
+| **REFACTOR** | 堵住漏洞 | 为新的理性化添加对策 |
+| **保持 GREEN** | 重新验证 | 代理在重构后仍然遵守 |
+
+## 底线
+
+**技能创建就是TDD。相同的原则，相同的循环，相同的好处。**
+
+如果你不会在没有测试的情况下编写代码，那么就不要在没有在代理上测试的情况下编写技能。
+
+文档的RED-GREEN-REFACTOR与代码的RED-GREEN-REFACTOR完全一样有效。
+
+## 实际影响
+
+从将TDD应用于TDD技能本身（2025-10-03）：
+
+* 6次RED-GREEN-REFACTOR迭代以实现无懈可击
+* 基线测试揭示了10+种独特的理性化
+* 每次REFACTOR都堵住了特定的漏洞
+* 最终验证GREEN：在最大压力下100%合规
+* 相同流程适用于任何强制纪律的技能
diff --git a/zh-CN/tests/claude-code/README.md b/zh-CN/tests/claude-code/README.md
new file mode 100644
index 0000000000..5ba12e286d
--- /dev/null
+++ b/zh-CN/tests/claude-code/README.md
@@ -0,0 +1,173 @@
+# Claude 代码技能测试
+
+使用 Claude Code CLI 对 superpowers 技能进行自动化测试。
+
+## 概述
+
+此测试套件验证技能是否正确加载以及 Claude 是否按预期遵循它们。测试以无头模式 (`claude -p`) 调用 Claude Code 并验证其行为。
+
+## 要求
+
+* Claude Code CLI 已安装并在 PATH 中 (运行 `claude --version` 应有效)
+* 本地 superpowers 插件已安装 (安装方法请参阅主 README)
+
+## 运行测试
+
+### 运行所有快速测试 (推荐):
+
+```bash
+./run-skill-tests.sh
+```
+
+### 运行集成测试 (较慢，10-30 分钟):
+
+```bash
+./run-skill-tests.sh --integration
+```
+
+### 运行特定测试:
+
+```bash
+./run-skill-tests.sh --test test-subagent-driven-development.sh
+```
+
+### 以详细输出模式运行:
+
+```bash
+./run-skill-tests.sh --verbose
+```
+
+### 设置自定义超时时间:
+
+```bash
+./run-skill-tests.sh --timeout 1800  # 30 minutes for integration tests
+```
+
+## 测试结构
+
+### test-helpers.sh
+
+用于技能测试的通用函数：
+
+* `run_claude "prompt" [timeout]` - 使用提示运行 Claude
+* `assert_contains output pattern name` - 验证模式存在
+* `assert_not_contains output pattern name` - 验证模式不存在
+* `assert_count output pattern count name` - 验证精确计数
+* `assert_order output pattern_a pattern_b name` - 验证顺序
+* `create_test_project` - 创建临时测试目录
+* `create_test_plan project_dir` - 创建示例计划文件
+
+### 测试文件
+
+每个测试文件：
+
+1. 引入 `test-helpers.sh`
+2. 使用特定提示运行 Claude Code
+3. 使用断言验证预期行为
+4. 成功时返回 0，失败时返回非零值
+
+## 示例测试
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+echo "=== Test: My Skill ==="
+
+# Ask Claude about the skill
+output=$(run_claude "What does the my-skill skill do?" 30)
+
+# Verify response
+assert_contains "$output" "expected behavior" "Skill describes behavior"
+
+echo "=== All tests passed ==="
+```
+
+## 当前测试
+
+### 快速测试 (默认运行)
+
+#### test-subagent-driven-development.sh
+
+测试技能内容和要求 (~2 分钟)：
+
+* 技能加载和可访问性
+* 工作流顺序 (规范合规性先于代码质量)
+* 自审要求已记录
+* 计划阅读效率已记录
+* 规范合规性评审员的怀疑态度已记录
+* 评审循环已记录
+* 任务上下文提供已记录
+
+### 集成测试 (使用 --integration 标志)
+
+#### test-subagent-driven-development-integration.sh
+
+完整工作流执行测试 (~10-30 分钟)：
+
+* 创建包含 Node.js 设置的真正测试项目
+* 创建包含 2 个任务的实施计划
+* 使用子代理驱动开发执行计划
+* 验证实际行为：
+  * 计划在开始时读取一次 (非每个任务)
+  * 子代理提示中提供完整的任务文本
+  * 子代理在报告前执行自审
+  * 规范合规性评审先于代码质量评审进行
+  * 规范评审员独立阅读代码
+  * 生成可工作的实现
+  * 测试通过
+  * 创建正确的 git 提交
+
+**测试内容：**
+
+* 工作流实际上能端到端运行
+* 我们的改进措施实际被应用
+* 子代理正确遵循技能
+* 最终代码功能正常且经过测试
+
+## 添加新测试
+
+1. 创建新的测试文件：`test-<skill-name>.sh`
+2. 引入 test-helpers.sh
+3. 使用 `run_claude` 和断言编写测试
+4. 添加到 `run-skill-tests.sh` 中的测试列表
+5. 使其可执行：`chmod +x test-<skill-name>.sh`
+
+## 超时注意事项
+
+* 默认超时：每个测试 5 分钟
+* Claude Code 可能需要时间响应
+* 如有需要，使用 `--timeout` 进行调整
+* 测试应保持专注以避免长时间运行
+
+## 调试失败的测试
+
+使用 `--verbose`，您将看到完整的 Claude 输出：
+
+```bash
+./run-skill-tests.sh --verbose --test test-subagent-driven-development.sh
+```
+
+如果不使用详细模式，则仅显示失败时的输出。
+
+## CI/CD 集成
+
+在 CI 中运行：
+
+```bash
+# Run with explicit timeout for CI environments
+./run-skill-tests.sh --timeout 900
+
+# Exit code 0 = success, non-zero = failure
+```
+
+## 注意事项
+
+* 测试验证的是技能*指令*，而非完整执行
+* 完整的工作流测试会非常缓慢
+* 专注于验证关键技能要求
+* 测试应具有确定性
+* 避免测试实现细节
diff --git a/zh-CN/tests/subagent-driven-dev/go-fractals/design.md b/zh-CN/tests/subagent-driven-dev/go-fractals/design.md
new file mode 100644
index 0000000000..48c039c610
--- /dev/null
+++ b/zh-CN/tests/subagent-driven-dev/go-fractals/design.md
@@ -0,0 +1,83 @@
+# Go Fractals CLI - 设计
+
+## 概述
+
+一个生成 ASCII 艺术分形的命令行工具。支持两种分形类型，并可配置输出。
+
+## 使用方法
+
+```bash
+# Sierpinski triangle
+fractals sierpinski --size 32 --depth 5
+
+# Mandelbrot set
+fractals mandelbrot --width 80 --height 24 --iterations 100
+
+# Custom character
+fractals sierpinski --size 16 --char '#'
+
+# Help
+fractals --help
+fractals sierpinski --help
+```
+
+## 命令
+
+### `sierpinski`
+
+通过递归细分生成谢尔宾斯基三角形。
+
+标志：
+
+* `--size` (默认值: 32) - 三角形底边的字符宽度
+* `--depth` (默认值: 5) - 递归深度
+* `--char` (默认值: '\*') - 用于填充点的字符
+
+输出：三角形打印到标准输出，每行打印一个。
+
+### `mandelbrot`
+
+将曼德博集合渲染为 ASCII 艺术。将迭代次数映射到字符。
+
+标志：
+
+* `--width` (默认值: 80) - 输出宽度（字符数）
+* `--height` (默认值: 24) - 输出高度（字符数）
+* `--iterations` (默认值: 100) - 逃逸计算的最大迭代次数
+* `--char` (默认值: gradient) - 单个字符，或省略以使用渐变字符 " .:-=+\*#%@"
+
+输出：矩形打印到标准输出。
+
+## 架构
+
+```
+cmd/
+  fractals/
+    main.go           # 入口点，CLI 设置
+internal/
+  sierpinski/
+    sierpinski.go     # 算法
+    sierpinski_test.go
+  mandelbrot/
+    mandelbrot.go     # 算法
+    mandelbrot_test.go
+  cli/
+    root.go           # 根命令，帮助
+    sierpinski.go     # Sierpinski 子命令
+    mandelbrot.go     # Mandelbrot 子命令
+```
+
+## 依赖项
+
+* Go 1.21+
+* `github.com/spf13/cobra` 用于 CLI
+
+## 验收标准
+
+1. `fractals --help` 显示用法
+2. `fractals sierpinski` 输出可识别的三角形
+3. `fractals mandelbrot` 输出可识别的曼德博集合
+4. `--size`, `--width`, `--height`, `--depth`, `--iterations` 标志正常工作
+5. `--char` 自定义输出字符
+6. 无效输入会产生清晰的错误信息
+7. 所有测试通过
diff --git a/zh-CN/tests/subagent-driven-dev/go-fractals/plan.md b/zh-CN/tests/subagent-driven-dev/go-fractals/plan.md
new file mode 100644
index 0000000000..f001d2f80c
--- /dev/null
+++ b/zh-CN/tests/subagent-driven-dev/go-fractals/plan.md
@@ -0,0 +1,192 @@
+# Go Fractals CLI - 实施计划
+
+使用 `superpowers:subagent-driven-development` 技能执行此计划。
+
+## 背景
+
+构建一个生成 ASCII 分形的 CLI 工具。完整规范请参阅 `design.md`。
+
+## 任务
+
+### 任务 1：项目设置
+
+创建 Go 模块和目录结构。
+
+**执行：**
+
+* 使用模块名称 `github.com/superpowers-test/fractals` 初始化 `go.mod`
+* 创建目录结构：`cmd/fractals/`、`internal/sierpinski/`、`internal/mandelbrot/`、`internal/cli/`
+* 创建打印 "fractals cli" 的最小 `cmd/fractals/main.go`
+* 添加 `github.com/spf13/cobra` 依赖项
+
+**验证：**
+
+* `go build ./cmd/fractals` 执行成功
+* `./fractals` 打印 "fractals cli"
+
+***
+
+### 任务 2：带帮助的 CLI 框架
+
+设置带有帮助输出的 Cobra 根命令。
+
+**执行：**
+
+* 使用根命令创建 `internal/cli/root.go`
+* 配置显示可用子命令的帮助文本
+* 将根命令接入 `main.go`
+
+**验证：**
+
+* `./fractals --help` 显示用法，其中列出 "sierpinski" 和 "mandelbrot" 作为可用命令
+* `./fractals`（无参数）显示帮助
+
+***
+
+### 任务 3：Sierpinski 算法
+
+实现谢尔宾斯基三角形生成算法。
+
+**执行：**
+
+* 创建 `internal/sierpinski/sierpinski.go`
+* 实现返回三角形各行的 `Generate(size, depth int, char rune) []string`
+* 使用递归中点细分算法
+* 创建带有测试的 `internal/sierpinski/sierpinski_test.go`：
+  * 小三角形（size=4, depth=2）匹配预期输出
+  * Size=1 返回单个字符
+  * Depth=0 返回实心三角形
+
+**验证：**
+
+* `go test ./internal/sierpinski/...` 通过
+
+***
+
+### 任务 4：Sierpinski CLI 集成
+
+将谢尔宾斯基算法连接到 CLI 子命令。
+
+**执行：**
+
+* 使用 `sierpinski` 子命令创建 `internal/cli/sierpinski.go`
+* 添加标志：`--size`（默认 32）、`--depth`（默认 5）、`--char`（默认 '\*'）
+* 调用 `sierpinski.Generate()` 并将结果打印到标准输出
+
+**验证：**
+
+* `./fractals sierpinski` 输出一个三角形
+* `./fractals sierpinski --size 16 --depth 3` 输出较小的三角形
+* `./fractals sierpinski --help` 显示标志文档
+
+***
+
+### 任务 5：Mandelbrot 算法
+
+实现曼德博集合 ASCII 渲染器。
+
+**执行：**
+
+* 创建 `internal/mandelbrot/mandelbrot.go`
+* 实现 `Render(width, height, maxIter int, char string) []string`
+* 将复平面区域（实部 -2.5 到 1.0，虚部 -1.0 到 1.0）映射到输出尺寸
+* 将迭代次数映射到字符梯度 " .:-=+\*#%@"（如果提供了单字符则使用单字符）
+* 创建带有测试的 `internal/mandelbrot/mandelbrot_test.go`：
+  * 输出尺寸匹配请求的宽度/高度
+  * 已知集合内点 (0,0) 映射到最大迭代字符
+  * 已知集合外点 (2,0) 映射到低迭代字符
+
+**验证：**
+
+* `go test ./internal/mandelbrot/...` 通过
+
+***
+
+### 任务 6：Mandelbrot CLI 集成
+
+将曼德博集合算法连接到 CLI 子命令。
+
+**执行：**
+
+* 使用 `mandelbrot` 子命令创建 `internal/cli/mandelbrot.go`
+* 添加标志：`--width`（默认 80）、`--height`（默认 24）、`--iterations`（默认 100）、`--char`（默认 ""）
+* 调用 `mandelbrot.Render()` 并将结果打印到标准输出
+
+**验证：**
+
+* `./fractals mandelbrot` 输出可识别的曼德博集合
+* `./fractals mandelbrot --width 40 --height 12` 输出较小版本
+* `./fractals mandelbrot --help` 显示标志文档
+
+***
+
+### 任务 7：字符集配置
+
+确保 `--char` 标志在两个命令中一致工作。
+
+**执行：**
+
+* 验证 Sierpinski 的 `--char` 标志将字符传递给算法
+* 对于 Mandelbrot，`--char` 应使用单字符而不是梯度
+* 为自定义字符输出添加测试
+
+**验证：**
+
+* `./fractals sierpinski --char '#'` 使用 '#' 字符
+* `./fractals mandelbrot --char '.'` 对所有填充点使用 '.'
+* 测试通过
+
+***
+
+### 任务 8：输入验证和错误处理
+
+为无效输入添加验证。
+
+**执行：**
+
+* Sierpinski：size 必须 > 0，depth 必须 >= 0
+* Mandelbrot：width/height 必须 > 0，iterations 必须 > 0
+* 为无效输入返回清晰的错误信息
+* 为错误情况添加测试
+
+**验证：**
+
+* `./fractals sierpinski --size 0` 打印错误，非零退出
+* `./fractals mandelbrot --width -1` 打印错误，非零退出
+* 错误信息清晰且有帮助
+
+***
+
+### 任务 9：集成测试
+
+添加调用 CLI 的集成测试。
+
+**执行：**
+
+* 创建 `cmd/fractals/main_test.go` 或 `test/integration_test.go`
+* 测试两个命令的完整 CLI 调用
+* 验证输出格式和退出码
+* 测试错误情况是否返回非零退出
+
+**验证：**
+
+* `go test ./...` 通过所有测试，包括集成测试
+
+***
+
+### 任务 10：README
+
+记录用法和示例。
+
+**执行：**
+
+* 创建包含以下内容的 `README.md`：
+  * 项目描述
+  * 安装：`go install ./cmd/fractals`
+  * 两个命令的使用示例
+  * 示例输出（小样本）
+
+**验证：**
+
+* README 准确描述了该工具
+* README 中的示例确实有效
diff --git a/zh-CN/tests/subagent-driven-dev/svelte-todo/design.md b/zh-CN/tests/subagent-driven-dev/svelte-todo/design.md
new file mode 100644
index 0000000000..b282a7dfd9
--- /dev/null
+++ b/zh-CN/tests/subagent-driven-dev/svelte-todo/design.md
@@ -0,0 +1,70 @@
+# Svelte 待办事项列表 - 设计
+
+## 概述
+
+一个使用 Svelte 构建的简单待办事项列表应用。支持创建、完成和删除待办事项，并具备 localStorage 持久化功能。
+
+## 功能
+
+* 添加新待办事项
+* 将待办事项标记为完成/未完成
+* 删除待办事项
+* 按以下方式筛选：全部 / 进行中 / 已完成
+* 清除所有已完成的待办事项
+* 持久化到 localStorage
+* 显示剩余项目数量
+
+## 用户界面
+
+```
+┌─────────────────────────────────────────┐
+│  Svelte Todos                           │
+├─────────────────────────────────────────┤
+│  [________________________] [添加]       │
+├─────────────────────────────────────────┤
+│  [ ] 购买食品杂货                  [x] │
+│  [✓] 遛狗                         [x] │
+│  [ ] 编写代码                      [x] │
+├─────────────────────────────────────────┤
+│  剩余 2 项                               │
+│  [全部] [待办] [已完成]  [清除 ✓]        │
+└─────────────────────────────────────────┘
+```
+
+## 组件
+
+```
+src/
+  App.svelte           # 主应用，状态管理
+  lib/
+    TodoInput.svelte   # 文本输入 + 添加按钮
+    TodoList.svelte    # 列表容器
+    TodoItem.svelte    # 单个待办事项（含复选框、文本、删除）
+    FilterBar.svelte   # 筛选按钮 + 清除已完成
+    store.ts           # Svelte store 用于待办事项
+    storage.ts         # localStorage 持久化
+```
+
+## 数据模型
+
+```typescript
+interface Todo {
+  id: string;        // UUID
+  text: string;      // Todo text
+  completed: boolean;
+}
+
+type Filter = 'all' | 'active' | 'completed';
+```
+
+## 验收标准
+
+1. 可以通过输入并按 Enter 键或点击"添加"来添加待办事项
+2. 可以通过点击复选框来切换待办事项的完成状态
+3. 可以通过点击 X 按钮来删除待办事项
+4. 筛选按钮显示正确的待办事项子集
+5. "X 项待办"显示未完成的待办事项数量
+6. "清除已完成"移除所有已完成的待办事项
+7. 待办事项在页面刷新后仍然存在（localStorage）
+8. 空状态显示有帮助的信息
+9. 所有测试通过
diff --git a/zh-CN/tests/subagent-driven-dev/svelte-todo/plan.md b/zh-CN/tests/subagent-driven-dev/svelte-todo/plan.md
new file mode 100644
index 0000000000..388fc4a7f6
--- /dev/null
+++ b/zh-CN/tests/subagent-driven-dev/svelte-todo/plan.md
@@ -0,0 +1,246 @@
+# Svelte 待办事项列表 - 实施计划
+
+使用 `superpowers:subagent-driven-development` 技能执行此计划。
+
+## 背景
+
+使用 Svelte 构建一个待办事项列表应用。完整规范请参见 `design.md`。
+
+## 任务
+
+### 任务 1：项目设置
+
+使用 Vite 创建 Svelte 项目。
+
+**执行：**
+
+* 运行 `npm create vite@latest . -- --template svelte-ts`
+* 使用 `npm install` 安装依赖项
+* 验证开发服务器正常工作
+* 清理 App.svelte 中默认的 Vite 模板内容
+
+**验证：**
+
+* `npm run dev` 启动服务器
+* 应用显示最小的 "Svelte Todos" 标题
+* `npm run build` 成功
+
+***
+
+### 任务 2：待办事项存储
+
+创建用于状态管理的 Svelte store。
+
+**执行：**
+
+* 创建 `src/lib/store.ts`
+* 定义 `Todo` 接口，包含 id、text、completed
+* 创建具有初始空数组的可写 store
+* 导出函数：`addTodo(text)`、`toggleTodo(id)`、`deleteTodo(id)`、`clearCompleted()`
+* 创建 `src/lib/store.test.ts`，包含每个函数的测试
+
+**验证：**
+
+* 测试通过：`npm run test`（如果需要，安装 vitest）
+
+***
+
+### 任务 3：localStorage 持久化
+
+为待办事项添加持久化层。
+
+**执行：**
+
+* 创建 `src/lib/storage.ts`
+* 实现 `loadTodos(): Todo[]` 和 `saveTodos(todos: Todo[])`
+* 优雅地处理 JSON 解析错误（返回空数组）
+* 与 store 集成：初始化时加载，更改时保存
+* 为加载/保存/错误处理添加测试
+
+**验证：**
+
+* 测试通过
+* 手动测试：添加待办事项，刷新页面，待办事项持久化
+
+***
+
+### 任务 4：TodoInput 组件
+
+创建用于添加待办事项的输入组件。
+
+**执行：**
+
+* 创建 `src/lib/TodoInput.svelte`
+* 文本输入绑定到本地状态
+* 添加按钮调用 `addTodo()` 并清空输入
+* 回车键也可提交
+* 输入为空时禁用添加按钮
+* 添加组件测试
+
+**验证：**
+
+* 测试通过
+* 组件渲染输入框和按钮
+
+***
+
+### 任务 5：TodoItem 组件
+
+创建单个待办事项项组件。
+
+**执行：**
+
+* 创建 `src/lib/TodoItem.svelte`
+* 属性：`todo: Todo`
+* 复选框切换完成状态（调用 `toggleTodo`）
+* 完成时文本有删除线
+* 删除按钮（X）调用 `deleteTodo`
+* 添加组件测试
+
+**验证：**
+
+* 测试通过
+* 组件渲染复选框、文本、删除按钮
+
+***
+
+### 任务 6：TodoList 组件
+
+创建列表容器组件。
+
+**执行：**
+
+* 创建 `src/lib/TodoList.svelte`
+* 属性：`todos: Todo[]`
+* 为每个待办事项渲染 TodoItem
+* 为空时显示 "No todos yet"
+* 添加组件测试
+
+**验证：**
+
+* 测试通过
+* 组件渲染 TodoItem 列表
+
+***
+
+### 任务 7：FilterBar 组件
+
+创建过滤器和状态栏组件。
+
+**执行：**
+
+* 创建 `src/lib/FilterBar.svelte`
+* 属性：`todos: Todo[]`、`filter: Filter`、`onFilterChange: (f: Filter) => void`
+* 显示数量："X items left"（未完成数量）
+* 三个过滤器按钮：全部、进行中、已完成
+* 活动过滤器视觉上高亮显示
+* "清除已完成" 按钮（没有已完成待办事项时隐藏）
+* 添加组件测试
+
+**验证：**
+
+* 测试通过
+* 组件渲染数量、过滤器、清除按钮
+
+***
+
+### 任务 8：应用集成
+
+在 App.svelte 中将所有组件连接起来。
+
+**执行：**
+
+* 导入所有组件和 store
+* 添加过滤器状态（默认：'all'）
+* 根据过滤器状态计算过滤后的待办事项
+* 渲染：标题、TodoInput、TodoList、FilterBar
+* 向每个组件传递适当的属性
+
+**验证：**
+
+* 应用渲染所有组件
+* 添加待办事项有效
+* 切换状态有效
+* 删除有效
+
+***
+
+### 任务 9：过滤功能
+
+确保端到端的过滤工作。
+
+**执行：**
+
+* 验证过滤器按钮更改显示的待办事项
+* 'all' 显示所有待办事项
+* 'active' 仅显示未完成的待办事项
+* 'completed' 仅显示已完成的待办事项
+* 清除已完成会移除已完成的待办事项，并在需要时重置过滤器
+* 添加集成测试
+
+**验证：**
+
+* 过滤器测试通过
+* 手动验证所有过滤器状态
+
+***
+
+### 任务 10：样式和优化
+
+为可用性添加 CSS 样式。
+
+**执行：**
+
+* 将应用样式设置为与设计稿匹配
+* 已完成的待办事项有删除线和柔和颜色
+* 活动过滤器按钮高亮显示
+* 输入框具有焦点样式
+* 删除按钮在悬停时显示（或在移动设备上始终显示）
+* 响应式布局
+
+**验证：**
+
+* 应用在视觉上可用
+* 样式不会破坏功能
+
+***
+
+### 任务 11：端到端测试
+
+为完整的用户流程添加 Playwright 测试。
+
+**执行：**
+
+* 安装 Playwright：`npm init playwright@latest`
+* 创建 `tests/todo.spec.ts`
+* 测试流程：
+  * 添加待办事项
+  * 完成待办事项
+  * 删除待办事项
+  * 过滤待办事项
+  * 清除已完成
+  * 持久化（添加、重新加载、验证）
+
+**验证：**
+
+* `npx playwright test` 通过
+
+***
+
+### 任务 12：README
+
+记录项目。
+
+**执行：**
+
+* 创建 `README.md`，包含：
+  * 项目描述
+  * 设置：`npm install`
+  * 开发：`npm run dev`
+  * 测试：`npm test` 和 `npx playwright test`
+  * 构建：`npm run build`
+
+**验证：**
+
+* README 准确描述项目
+* 说明有效