superpowers-zh Documentation

File: README.md Copy Chapter

superpowers-zh（AI 编程超能力 · 中文增强版）

🌐 简体中文 | 繁體中文 | English (upstream)

🦸 superpowers（300k+ ⭐）完整汉化 + 4 个中国原创 skills — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活。从头脑风暴到代码审查，从 TDD 到调试，每个 skill 都是经过实战验证的工作方法论。

Chinese community edition of superpowers — 21 skills across 26 AI coding tools, including full translations and China-specific development skills.

📖 免费配套学习 → 从零学会 AI 编程（182 节）＋ 从零构建 AI 智能体（40 节）：两门免费实操课 + 实战社区，superpowers 装好后配上方法论效率翻倍（站上共 14 门课、700 节，全部 ¥0——另有 大模型原理 / AI 绘画 / 写小说 / 漫剧 / 量化 / DeepSeek / 深度专注 等）

🌍 Also available in English · 日本語 · Español · 한국어 · 繁體中文

🧠 新：让 Claude Code / Codex / Cursor / Gemini CLI 不再失忆 → engram：一条 npx @jnmetacode/engram install，自动记住每次会话问过什么、改了哪些文件、最后怎么解决的，下次开会话自动带回（带出处）。记忆跨工具共享——Codex 里定的事，Claude Code 也知道。全本地、零依赖、中文友好。

📊 项目规模 Copy Section

❤️ 赞助商  _{🙏 想出现在这里？联系 **[email protected]** 赞助} Copy Chapter

感谢 APINEBULA 大屏赞助本项目！APINEBULA 是银河录像局旗下的企业级 AI 聚合平台，背靠大平台资源，面向开发者、团队与企业用户提供稳定、高性价比的大模型 API 接入服务。平台聚合 Claude、GPT、Gemini 等主流满血模型，一个接口接入全球顶尖 AI 大模型，各大模型价格低至 1 折起，支持企业级高并发、正式合同、对公打款与开票服务，适合 AI 编程、Agent 开发、业务系统集成等多种场景！

🎁 通过此链接注册并在充值时填写 agent 优惠码可享 9 折优惠！

| | 88API Token聚合平台
🧠 聚合 GPT、Claude、Gemini、Grok、DeepSeek、Kimi、GLM 等语言与编程模型；
🎨 图片模型：GPT-Image、Gemini、Grok 等；
🎬 视频模型：Seedance、Veo、MiniMax H3、Kling、Grok 等；
🎙️ 语音能力：Whisper、TTS 等。从文案、出图、改图，到视频生成与配音
🎁新用户注册送体验额度，可以检测模型能力。站内有人工客服值守！

👉香港正规企业运营 稳定供应 全绿满血 不降智 提供发票 |
| --- | --- |

这是什么？ Copy Chapter

superpowers 是目前最火的 AI 编程 skills 框架（300k+ stars），为 AI 编程工具提供系统化的工作方法论。

superpowers-zh 在完整翻译的基础上，新增了面向中国开发者的特色 skills。

| 没装 superpowers-zh：

你：给用户模块加个批量导出功能
AI：好的，我来实现...（直接开始写代码）
    export async function exportUsers() { ... }
你：等等，格式不对，没分页，大数据量会 OOM...
``` | **装了 superpowers-zh：**

你：给用户模块加个批量导出功能
AI：在开始实现之前，我需要了解几个关键问题：
1. 导出格式是 CSV 还是 Excel？
2. 预计数据量多大？需要异步处理吗？
3. 有权限要求吗？
→ 给出 2-3 个方案，确认后再动手

| --- | --- |



### 🆚 与英文上游的区别（老被问，一次说清）

| 维度 | superpowers（英文上游） | superpowers-zh（中文增强版） |
|------|----------------------|---------------------------|
| ⭐ Star 数 | 300k+ | — |
| 📦 Skills 总数 | 15 | **21**（15 翻译 + 4 国产原创 + 2 上游历史保留） |
| 🌐 语言 | 英文 | 中文（技术术语保留英文） |
| 🤖 **支持工具** | **6 款**：Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI | **26 款**：上述 6 款 + Hermes Agent / Trae / Kiro / Qwen Code / OpenClaw / Claw Code / Antigravity / DeerFlow / VS Code / Windsurf / Aider / Qoder / CodeBuddy（腾讯） / CodeArts（华为云码道） / Cline / Kilo Code / Crush / ZCode（智谱）/ DeepSeek Harness / Reasonix |
| ⚡ **安装方式** | 按工具分别装（每款一条不同的 plugin marketplace 命令） | **`npx superpowers-zh` 一条命令自动识别项目里的工具并安装**；识别不出可 `--tool <name>` 显式指定 |
| 🇨🇳 Git 平台 | GitHub 为主 | GitHub + Gitee + Coding + 极狐 GitLab + **CNB（腾讯云原生构建）** |
| 🇨🇳 CI/CD 示例 | GitHub Actions | GitHub Actions + Gitee Go + Coding CI + 极狐 CI + `.cnb.yml` |
| 🇨🇳 代码审查风格 | 西方直接风格 | 适配国内团队沟通文化 |
| 🇨🇳 Git 提交规范 | 无 | Conventional Commits 中文适配 |
| 🇨🇳 中文文档规范 | 无 | 中文排版 + 中英混排规则 + 告别机翻味 |
| ➕ MCP 服务器构建 | 无 | 独立 `mcp-builder` skill |
| ➕ 工作流执行器 | 无 | 独立 `workflow-runner` skill（多角色 YAML 编排） |
| ➕ 翻译 skill 内的增量 | — | 仅 2 处，均在正文显式标注「本节是 superpowers-zh 的增量内容」：`executing-plans` 的「常见异常处理」、`using-superpowers` 的「中国特色技能路由」。**上游各节均为逐节翻译，不被改动**；audit 会强制未标注的增量报错 |
| 🔄 版本跟进 | 独立迭代 | **同步上游 + 国产增量叠加** |
| 🤝 接受新 skill PR | 一般不接受（原文：*"we don't generally accept contributions of new skills"*） | 欢迎 PR（中国开发者痛点优先） |
| 💬 社区 | Discord | 微信公众号「AI不止语」+ 微信群 + QQ 群 |
| 📜 License | MIT | MIT |

**一句话总结：** 英文上游 = 方法论内核；中文增强版 = 方法论内核 **+** 26 款工具一键适配 **+** 国内 Git/CI 生态 **+** 中文化表达习惯。

### 🤖 支持 26 款主流 AI 编程工具

| 工具 | 类型 | 一键安装 | 手动安装 |
|------|------|:---:|:---:|
| [Claude Code](https://claude.ai/code) | CLI | `npx superpowers-zh` | `.claude/skills/` |
| [Copilot CLI](https://githubnext.com/projects/copilot-cli) | CLI | `npx superpowers-zh --tool copilot` | `.claude/skills/` |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --global --tool hermes` | `~/.hermes/skills/` |
| [Cursor](https://cursor.sh) | IDE | `npx superpowers-zh` | `.cursor/skills/` |
| [Windsurf](https://windsurf.com) | IDE | `npx superpowers-zh` | `.windsurf/skills/`（全局 `~/.codeium/windsurf/skills/`） |
| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/skills/` |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | CLI | `npx superpowers-zh` | `.gemini/skills/` |
| [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.agents/skills/` |
| [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
| [Trae](https://trae.ai) | IDE | `npx superpowers-zh` | `.trae/skills/` + `.trae/rules/` |
| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 插件 | `npx superpowers-zh` | `.github/superpowers/` + `.github/instructions/` |
| [DeerFlow 2.0](https://github.com/bytedance/deer-flow) | Agent 框架 | `npx superpowers-zh` | `skills/custom/` |
| [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
| [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
| [Qwen Code](https://github.com/QwenLM/qwen-code) | CLI | `npx superpowers-zh` | `.qwen/skills/` + `QWEN.md` |
| [Antigravity](https://antigravity.google) | IDE | `npx superpowers-zh` | `.agents/skills/` |
| [Claw Code](https://github.com/ultraworkers/claw-code) | CLI (Rust) | `npx superpowers-zh` | `.claw/skills/` |
| [Qoder](https://qoder.com) (阿里 AI IDE) | IDE | `npx superpowers-zh` | `.qoder/skills/` + `.qoder/rules/` |
| [CodeBuddy](https://copilot.tencent.com) (腾讯 AI IDE) | IDE | `npx superpowers-zh` | `.codebuddy/skills/` + `CODEBUDDY.md` |
| [华为云码道 CodeArts](https://codearts.huaweicloud.com/) | IDE | `npx superpowers-zh` | `.codeartsdoer/skills/` |
| [Cline](https://cline.bot) | IDE 插件 | `npx superpowers-zh --tool cline` | `.cline/skills/` + `.clinerules/` |
| [Kilo Code](https://kilo.ai) | IDE 插件 | `npx superpowers-zh --tool kilocode` | `.kilocode/skills/` + `.kilocode/rules/` |
| [Crush](https://github.com/charmbracelet/crush) | CLI | `npx superpowers-zh` | `.crush/skills/` |
| [ZCode](https://zcode.z.ai/) (智谱 ADE) | IDE | `npx superpowers-zh --global --tool zcode` | `~/.zcode/skills/`（仅全局，项目级路径官方未公开） |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) | CLI | `npx superpowers-zh` | `.dsh/skills/` + `AGENTS.md` |
| [Reasonix](https://reasonix.io/) | CLI | `npx superpowers-zh` | `.reasonix/skills/` + `REASONIX.md`（全局 Windows 为 `%APPDATA%\reasonix\skills`） |

> 运行 `npx superpowers-zh` 会自动检测你项目中使用的工具，将 21 个 skills 安装到正确位置。

### 翻译的 Skills（15 个）

| Skill | 用途 |
|-------|------|
| **头脑风暴** (brainstorming) | 需求分析 → 设计规格，不写代码先想清楚 |
| **编写计划** (writing-plans) | 把规格拆成可执行的实施步骤 |
| **执行计划** (executing-plans) | 按计划逐步实施，每步验证 |
| **测试驱动开发** (test-driven-development) | 严格 TDD：先写测试，再写代码 |
| **系统化调试** (systematic-debugging) | 四阶段调试法：定位→分析→假设→修复 |
| **诊断 Superpowers** (diagnosing-superpowers) | 会话跑偏时读 transcript 取证，每条结论带 `path:line`，可整理成 issue |
| **请求代码审查** (requesting-code-review) | 派遣审查 agent 检查代码质量 |
| **接收代码审查** (receiving-code-review) | 技术严谨地处理审查反馈，拒绝敷衍 |
| **完成前验证** (verification-before-completion) | 证据先行——声称完成前必须跑验证 |
| **派遣并行 Agent** (dispatching-parallel-agents) | 多任务并发执行 |
| **子 Agent 驱动开发** (subagent-driven-development) | 每个任务一个 agent，两轮审查 |
| **Git Worktree 使用** (using-git-worktrees) | 隔离式特性开发 |
| **完成开发分支** (finishing-a-development-branch) | 合并/PR/保留/丢弃四选一 |
| **编写 Skills** (writing-skills) | 创建新 skill 的方法论 |
| **使用 Superpowers** (using-superpowers) | 元技能：如何调用和优先使用 skills |

### 🇨🇳 中国原创 Skills（4 个）· 上游历史保留（2 个）

> ⚠️ **下表前 4 个 chinese-\* 为「手动调用」skill**——不会自动触发，需在对话中显式输入 `/chinese-xxx` 才会加载。
> 设计为参考资料而非工作流，避免污染上游 skill 的自动调度（如 `requesting-code-review`、`brainstorming` 等）。
>
> ⚠️ **表格最后两个（mcp-builder / workflow-runner）不是中国原创** —— 它们来自上游，上游后来移除了，本 fork 保留下来继续维护。全仓 21 个 skill = 15 翻译 + 4 中国原创 + 2 上游历史保留。

| Skill | 用途 | 调用方式 | 上游有吗？ |
|-------|------|---------|:---:|
| **中文代码审查** (chinese-code-review) | 符合国内团队文化的代码审查规范 | `/chinese-code-review`（手动） | 无 |
| **中文 Git 工作流** (chinese-git-workflow) | 适配 Gitee/Coding/极狐 GitLab/CNB | `/chinese-git-workflow`（手动） | 无 |
| **中文技术文档** (chinese-documentation) | 中文排版规范、中英混排、告别机翻味 | `/chinese-documentation`（手动） | 无 |
| **中文提交规范** (chinese-commit-conventions) | 适配国内团队的 commit message 规范 | `/chinese-commit-conventions`（手动） | 无 |
| **MCP 服务器构建** (mcp-builder) | 构建生产级 MCP 工具，扩展 AI 能力边界 | 自动 | 曾有，上游已移除 |
| **工作流执行器** (workflow-runner) | 在 AI 工具内运行多角色 YAML 工作流 | 自动 | 曾有，上游已移除 |

---

## 快速开始

### 方式一：npm 安装（推荐）

**项目级**（默认，装到当前项目）：

```bash
cd /your/project
npx superpowers-zh

⚠️ 项目级安装不要在主目录（~）下跑。v1.2.1 起会拒绝并提示，老版本会把 skills 和 CLAUDE.md 等 bootstrap 文件写到你的 home 目录，污染所有项目。如已误装见下文「卸载 / 误装清理」。想让 skills 对所有项目生效，请用下面的全局安装，而不是在 ~ 下跑项目级。

全局安装（v1.7.0+，装到用户目录，所有项目共享，适合同时维护多个项目）：

npx superpowers-zh --global                 # 自动检测已装工具
npx superpowers-zh --global --tool claude   # 或指定工具

全局安装把 skills 装到工具的用户级目录（如 ~/.claude/skills），一次安装所有项目自动可用，更新时也只需重装一次。项目级优先、全局兜底，二者可共存。

支持通用全局安装的工具（均为 docs 已证实的用户级加载路径）：Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts · ZCode · DeepSeek Harness · Reasonix。其中 Codex CLI 全局装到 ~/.agents/skills（Codex 启动扫描目录）；Crush 在 Windows 上装到 %LOCALAPPDATA%\crush\skills（其 README 明确 Windows 走这里，不是 ~/.config）。其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code）规则是项目级或存于应用内设置，--global 会提示改用项目级；Gemini CLI / Antigravity 有各自专属的全局方式（Gemini 走扩展目录），见对应 docs/README.*.md。

方式二：Claude Code Plugin Marketplace Copy Section

仅限 Claude Code。 走官方 plugin 机制装，好处是升级只要一条 claude plugin update，不用重跑 npx：

claude plugin marketplace add jnMetaCode/superpowers-zh
claude plugin install superpowers-zh@superpowers-zh

装完 claude plugin list 应该看到：

❯ superpowers-zh@superpowers-zh
    Version: <当前版本>
    Scope: user
    Status: ✔ enabled

升级与卸载：

claude plugin marketplace update superpowers-zh          # 先刷新 marketplace 缓存
claude plugin update superpowers-zh@superpowers-zh       # 再升级 plugin（需重启生效）
claude plugin uninstall superpowers-zh@superpowers-zh    # 卸载

和方式一怎么选？ marketplace 装的是完整 plugin（skills + hooks + bootstrap 由 Claude Code 统一托管、随版本更新），但只服务 Claude Code 一款工具。要装给其余 25 款工具，仍然用方式一的 npx superpowers-zh。两者可以共存，但同一个项目里别重复装 Claude Code，否则 skills 会出现两份。

方式三：手动安装（low-fidelity，仅作备选） Copy Section

⚠️ 手动 cp -r skills 是低保版安装，不等同于完整 plugin。

superpowers-zh 是一个完整 plugin，包含：skills/（21 个能力）+ hooks/（SessionStart 钩子，让 skill 在合适时机自动触发）+ CLAUDE.md / GEMINI.md 等 bootstrap 引导文件 + 4 套 plugin manifest（Claude Code / Cursor / Codex / Marketplace）。

下面的 cp -r skills 命令只复制 skills 目录，不会自动配置 hooks、不会生成 bootstrap 引导。结果：skills 物理上存在，但 AI 不会在合适时机自动调用，需要你每次手动喊 "use brainstorming skill" 之类。

强烈推荐用方式一 npx superpowers-zh —— 它会一键处理 skills 复制 + bootstrap 生成 + hooks 配置 + 工具特定适配。仅在 npx 不可用（极端无网络环境）时才退到手动。

# 克隆仓库
git clone https://github.com/jnMetaCode/superpowers-zh.git

# 复制 skills 到你的项目（选择你使用的工具）
cp -r superpowers-zh/skills /your/project/.claude/skills      # Claude Code / Copilot CLI
cp -r superpowers-zh/skills /your/project/.hermes/skills      # Hermes Agent
cp -r superpowers-zh/skills /your/project/.cursor/skills      # Cursor
cp -r superpowers-zh/skills /your/project/.codex/skills       # Codex CLI
cp -r superpowers-zh/skills /your/project/.kiro/skills        # Kiro
cp -r superpowers-zh/skills /your/project/skills/custom       # DeerFlow 2.0
cp -r superpowers-zh/skills /your/project/.trae/rules         # Trae
cp -r superpowers-zh/skills /your/project/.agents        # Antigravity
cp -r superpowers-zh/skills /your/project/.github/superpowers # VS Code (Copilot)
cp -r superpowers-zh/skills /your/project/skills              # OpenClaw
cp -r superpowers-zh/skills /your/project/.windsurf/skills   # Windsurf
cp -r superpowers-zh/skills /your/project/.gemini/skills     # Gemini CLI
cp -r superpowers-zh/skills /your/project/.aider/skills      # Aider
cp -r superpowers-zh/skills /your/project/.opencode/skills   # OpenCode
cp -r superpowers-zh/skills /your/project/.qwen/skills       # Qwen Code
cp -r superpowers-zh/skills /your/project/.claw/skills       # Claw Code（Rust 版）
cp -r superpowers-zh/skills /your/project/.qoder/skills      # Qoder（阿里 AI IDE）

方式四：在配置文件中引用 Copy Section

根据你使用的工具，在对应配置文件中引用 skills：

详细安装指南：Kiro · DeerFlow · Trae · Antigravity · VS Code · Codex · OpenCode · OpenClaw · Windsurf · Gemini CLI · Aider · Qwen Code · Hermes Agent · Claw Code · Qoder · CodeBuddy · 华为云码道 · Kimi Code · Pi · Cline · Kilo Code · Crush

卸载 / 误装清理（v1.2.1+） Copy Section

cd /your/project          # 或 cd ~ 如果误装到了主目录
npx superpowers-zh@latest --uninstall

会做这些：

• 删除所有装过的 skill 目录（.claude/skills/、.trae/skills/ 等）
• 删除独立 bootstrap 文件（.trae/rules/superpowers-zh.md、.qoder/rules/superpowers-zh.md、.agents/rules.md）
• 清理追加到 CLAUDE.md / HERMES.md / GEMINI.md / CONVENTIONS.md 里的 superpowers-zh 段，保留你自己写的内容

数据安全说明：v1.2.1 起，安装会把追加内容包在 `` 哨兵注释之间，卸载按哨兵精确切除。识别不可靠时跳过 + 警告，绝不会误删用户内容。

其他参数：

贡献 Copy Chapter

欢迎参与！翻译改进、新增 skills、Bug 修复都可以。

贡献方向 Copy Section

我们只接收符合 superpowers 定位的 skill——AI 编程工作流方法论。好的 skill 应该：

• 教 AI 助手怎么干活，而不是某个框架/语言的教程
• 解决上游英文版不覆盖的中国开发者痛点
• 有明确的步骤、检查清单、示例，AI 加载后能直接执行

欢迎提 Issue 讨论你的想法！

交流 · Community Copy Chapter

| 微信扫码关注 | 微信公众号 「AI不止语」（微信搜索 AI_BuZhiYu）— 技术问答 · 项目更新 · 实战文章

渠道 加入方式

QQ 2群 点击加入（群号 1071280067）

微信群 关注公众号后回复「群」获取入群方式 |
| --- | --- |

🌟 相关项目生态 Copy Chapter

九个项目组合使用，覆盖 AI 编程 + AI 视频创作 + 桌面陪伴的完整链路。

🔥 重点推荐：[agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator) — 一句话调度 276 个 AI 专家协作，几分钟交付完整方案 Copy Section

以前写个方案：你当指挥官，把 AI 轮流扮演 5 个角色，复制粘贴 10 次，1 小时没了。

现在： 丢一句话进去 "做一个电商退款流程"，产品 → 架构 → 安全 → 测试 → DBA 自动接力，几分钟完整方案落地。

• 🎭 276+ 专家角色（含 64 个中国市场原创：小红书 / 抖音 / 微信 / 飞书 / 钉钉）
• 🧩 零代码 YAML，一行 prompt 就能跑
• 💰 15 种大模型可选（DeepSeek / Claude / OpenAI / Ollama 等，11 种免 key）
• 🔗 与 superpowers-zh 互补：本项目管"怎么做"（方法论），orchestrator 管"谁来做"（角色协作）

👉 立即体验 agency-orchestrator →

致谢 Copy Chapter

• 原始英文版：obra/superpowers（MIT 协议）
• 感谢 @obra 创建了这个优秀的项目

许可证 Copy Chapter

MIT License — 自由使用，商业或个人均可。

📌 最近更新 Copy Chapter

🆕 v1.7.12 更新亮点 —— 通过 Claude Code 插件市场安装的用户请更新（此前技能之间互相调用会失败）：

• 🐛 插件模式下跨技能调用全部失败（#124）—— 正文照抄了上游的 superpowers: 前缀，而本插件叫 superpowers-zh，于是 Skill("superpowers:systematic-debugging") 返回 Unknown skill。32 处已改为裸技能名（两种分发模式都能解析）
• 🐛 Crush 在 Windows 上装错目录 —— 官方是 %LOCALAPPDATA%\crush\skills，我们两个平台都装 ~/.config。文档早写对了，代码没跟上
• 🐛 render-graphs.js —— 取上游的安全加固与 Windows 修复，但不跟它改 ESM（那会在 Node 20 的普通项目里直接加载失败）
• 🆕 新增 DeepSeek Harness 支持（#122）—— 项目级 .dsh/skills/ + 全局 ~/.dsh/skills/，引导写 AGENTS.md；四条路径全部有官方出处
• 🐛 在管理员 PowerShell 里跑会把 skills 装进 C:\Windows\System32（#125）—— 管理员终端的默认工作目录就是那里。补系统目录护栏，且不提供 --force 绕过
• 🆕 新增 Reasonix 支持（#42）—— 项目级 .reasonix/skills/ + REASONIX.md；Windows 全局是 %APPDATA%\reasonix\skills，与 Unix 不同构
• 🆕 新增 ZCode（智谱）支持（工具数 23 → 26）—— 只做全局安装：官方文档只公开了 ~/.zcode/skills/，项目级是应用内 UI 导入、不暴露磁盘路径，所以项目级会被明确拒绝而不是猜路径装进去
• 🛡️ 6 条新门禁（前缀回归、Windows 路径、卸载不误删用户文件、全局-only 工具项目级必拒、上游漂移计量…），verify-release 115 → 144

📋 官网侧改动（版本提示条、22 份工具文档入口、结构化数据、分享大图、可访问性、sitemap…）见 完整 Release Notes →

📈 Star 趋势 Copy Chapter

File: README.zh-Hant.md Copy Chapter

superpowers-zh（AI 編程超能力 · 中文增強版）

🌐 简体中文 | 繁體中文 | English (upstream)

🦸 superpowers（300k+ ⭐）完整漢化 + 4 個中國原創 skills — 讓 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 編程工具真正會幹活。從頭腦風暴到程式碼審查，從 TDD 到除錯，每個 skill 都是經過實戰驗證的工作方法論。

Chinese community edition of superpowers — 21 skills across 26 AI coding tools, including full translations and China-specific development skills.

📖 免費配套學習 → 從零學會 AI 編程(182 節)＋ AI 智能體課程(40 節)— 繁體中文實作課程,免費（站上共 13 門課、648 節，全部 ¥0——另有 AI 繪畫 / 寫小說 / 漫劇 / 量化 / DeepSeek / 深度專注 等）

📊 專案規模 Copy Section

❤️ 贊助商  _{🙏 想出現在這裡？聯絡 **[email protected]** 贊助} Copy Chapter

感謝 APINEBULA 大屏贊助本專案！APINEBULA 是銀河錄像局旗下的企業級 AI 聚合平台，背靠大型平台資源，面向開發者、團隊與企業使用者提供穩定、高性價比的大型模型 API 接入服務。平台聚合 Claude、GPT、Gemini 等主流滿血模型，一個介面接入全球頂尖 AI 大型模型，各大模型價格低至 1 折起，支援企業級高併發、正式合約、對公付款與開票服務，適合 AI 編程、Agent 開發、業務系統整合等多種場景！

🎁 透過此連結註冊並在儲值時填寫 agent 優惠碼可享 9 折優惠！

| | 88API Token 聚合平台
🧠 聚合 GPT、Claude、Gemini、Grok、DeepSeek、Kimi、GLM 等語言與編程模型；
🎨 圖片模型：GPT-Image、Gemini、Grok 等；
🎬 影片模型：Seedance、Veo、MiniMax H3、Kling、Grok 等；
🎙️ 語音能力：Whisper、TTS 等。從文案、出圖、改圖，到影片生成與配音
🎁新使用者註冊即送體驗額度，可以檢測模型能力。站內有人工客服值守！

👉香港正規企業營運 穩定供應 全綠滿血 不降智 提供發票 |
| --- | --- |

這是什麼？ Copy Chapter

superpowers 是目前最火的 AI 編程 skills 框架（300k+ stars），為 AI 編程工具提供系統化的工作方法論。

superpowers-zh 在完整翻譯的基礎上，新增了面向中國開發者的特色 skills。

| 沒裝 superpowers-zh：

你：給使用者模組加個批次匯出功能
AI：好的，我來實作...（直接開始寫程式碼）
    export async function exportUsers() { ... }
你：等等，格式不對，沒分頁，大量資料會 OOM...
``` | **裝了 superpowers-zh：**

你：給使用者模組加個批次匯出功能
AI：在開始實作之前，我需要了解幾個關鍵問題：
1. 匯出格式是 CSV 還是 Excel？
2. 預計資料量多大？需要非同步處理嗎？
3. 有權限要求嗎？
→ 給出 2-3 個方案，確認後再動手

| --- | --- |



### 🆚 與英文上游的區別（老被問，一次說清）

| 維度 | superpowers（英文上游） | superpowers-zh（中文增強版） |
|------|----------------------|---------------------------|
| ⭐ Star 數 | 300k+ | — |
| 📦 Skills 總數 | 15 | **21**（15 翻譯 + 4 國產原創 + 2 上游歷史保留） |
| 🌐 語言 | 英文 | 中文（技術術語保留英文） |
| 🤖 **支援工具** | **6 款**：Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI | **26 款**：上述 6 款 + Hermes Agent / Trae / Kiro / Qwen Code / OpenClaw / Claw Code / Antigravity / DeerFlow / VS Code / Windsurf / Aider / Qoder / CodeBuddy（騰訊） / CodeArts（華為雲碼道） / Cline / Kilo Code / Crush / ZCode（智譜）/ DeepSeek Harness / Reasonix |
| ⚡ **安裝方式** | 按工具分別裝（每款一條不同的 plugin marketplace 命令） | **`npx superpowers-zh` 一條命令自動識別專案裡的工具並安裝**；識別不出可 `--tool <name>` 顯式指定 |
| 🇨🇳 Git 平台 | GitHub 為主 | GitHub + Gitee + Coding + 極狐 GitLab + **CNB（騰訊雲原生建置）** |
| 🇨🇳 CI/CD 範例 | GitHub Actions | GitHub Actions + Gitee Go + Coding CI + 極狐 CI + `.cnb.yml` |
| 🇨🇳 程式碼審查風格 | 西方直接風格 | 適配國內團隊溝通文化 |
| 🇨🇳 Git 提交規範 | 無 | Conventional Commits 中文適配 |
| 🇨🇳 中文文件規範 | 無 | 中文排版 + 中英混排規則 + 告別機翻味 |
| ➕ MCP 伺服器建置 | 無 | 獨立 `mcp-builder` skill |
| ➕ 工作流執行器 | 無 | 獨立 `workflow-runner` skill（多角色 YAML 編排） |
| ➕ 翻譯 skill 內的增量 | — | 僅 2 處，均在正文顯式標註「本節是 superpowers-zh 的增量內容」：`executing-plans` 的「常見異常處理」、`using-superpowers` 的「中國特色技能路由」。**上游各節均為逐節翻譯，不被改動**；audit 會強制未標註的增量報錯 |
| 🔄 版本跟進 | 獨立迭代 | **同步上游 + 國產增量疊加** |
| 🤝 接受新 skill PR | 一般不接受（原文：*"we don't generally accept contributions of new skills"*） | 歡迎 PR（中國開發者痛點優先） |
| 💬 社群 | Discord | 微信公眾號「AI不止語」+ 微信群 + QQ 群 |
| 📜 License | MIT | MIT |

**一句話總結：** 英文上游 = 方法論核心；中文增強版 = 方法論核心 **+** 26 款工具一鍵適配 **+** 國內 Git/CI 生態 **+** 中文化表達習慣。

### 🤖 支援 26 款主流 AI 編程工具

| 工具 | 類型 | 一鍵安裝 | 手動安裝 |
|------|------|:---:|:---:|
| [Claude Code](https://claude.ai/code) | CLI | `npx superpowers-zh` | `.claude/skills/` |
| [Copilot CLI](https://githubnext.com/projects/copilot-cli) | CLI | `npx superpowers-zh --tool copilot` | `.claude/skills/` |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --global --tool hermes` | `~/.hermes/skills/` |
| [Cursor](https://cursor.sh) | IDE | `npx superpowers-zh` | `.cursor/skills/` |
| [Windsurf](https://windsurf.com) | IDE | `npx superpowers-zh` | `.windsurf/skills/`（全局 `~/.codeium/windsurf/skills/`） |
| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/skills/` |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | CLI | `npx superpowers-zh` | `.gemini/skills/` |
| [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.agents/skills/` |
| [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
| [Trae](https://trae.ai) | IDE | `npx superpowers-zh` | `.trae/skills/` + `.trae/rules/` |
| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 外掛 | `npx superpowers-zh` | `.github/superpowers/` + `.github/instructions/` |
| [DeerFlow 2.0](https://github.com/bytedance/deer-flow) | Agent 框架 | `npx superpowers-zh` | `skills/custom/` |
| [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
| [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
| [Qwen Code](https://github.com/QwenLM/qwen-code) | CLI | `npx superpowers-zh` | `.qwen/skills/` + `QWEN.md` |
| [Antigravity](https://antigravity.google) | IDE | `npx superpowers-zh` | `.agents/skills/` |
| [Claw Code](https://github.com/ultraworkers/claw-code) | CLI (Rust) | `npx superpowers-zh` | `.claw/skills/` |
| [Qoder](https://qoder.com) (阿里 AI IDE) | IDE | `npx superpowers-zh` | `.qoder/skills/` + `.qoder/rules/` |
| [CodeBuddy](https://copilot.tencent.com) (騰訊 AI IDE) | IDE | `npx superpowers-zh` | `.codebuddy/skills/` + `CODEBUDDY.md` |
| [華為雲碼道 CodeArts](https://codearts.huaweicloud.com/) | IDE | `npx superpowers-zh` | `.codeartsdoer/skills/` |
| [Cline](https://cline.bot) | IDE 外掛 | `npx superpowers-zh --tool cline` | `.cline/skills/` + `.clinerules/` |
| [Kilo Code](https://kilo.ai) | IDE 外掛 | `npx superpowers-zh --tool kilocode` | `.kilocode/skills/` + `.kilocode/rules/` |
| [Crush](https://github.com/charmbracelet/crush) | CLI | `npx superpowers-zh` | `.crush/skills/` |
| [ZCode](https://zcode.z.ai/) (智譜 ADE) | IDE | `npx superpowers-zh --global --tool zcode` | `~/.zcode/skills/`（僅全域，專案級路徑官方未公開） |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) | CLI | `npx superpowers-zh` | `.dsh/skills/` + `AGENTS.md` |
| [Reasonix](https://reasonix.io/) | CLI | `npx superpowers-zh` | `.reasonix/skills/` + `REASONIX.md`（全域 Windows 為 `%APPDATA%\reasonix\skills`） |

> 執行 `npx superpowers-zh` 會自動偵測你專案中使用的工具，將 21 個 skills 安裝到正確位置。

### 翻譯的 Skills（15 個）

| Skill | 用途 |
|-------|------|
| **頭腦風暴** (brainstorming) | 需求分析 → 設計規格，不寫程式碼先想清楚 |
| **編寫計畫** (writing-plans) | 把規格拆成可執行的實施步驟 |
| **執行計畫** (executing-plans) | 按計畫逐步實施，每步驗證 |
| **測試驅動開發** (test-driven-development) | 嚴格 TDD：先寫測試，再寫程式碼 |
| **系統化除錯** (systematic-debugging) | 四階段除錯法：定位→分析→假設→修復 |
| **診斷 Superpowers** (diagnosing-superpowers) | 會話跑偏時讀 transcript 取證，每條結論帶 `path:line`，可整理成 issue |
| **請求程式碼審查** (requesting-code-review) | 派遣審查 agent 檢查程式碼品質 |
| **接收程式碼審查** (receiving-code-review) | 技術嚴謹地處理審查回饋，拒絕敷衍 |
| **完成前驗證** (verification-before-completion) | 證據先行——聲稱完成前必須跑驗證 |
| **派遣並行 Agent** (dispatching-parallel-agents) | 多任務並行執行 |
| **子 Agent 驅動開發** (subagent-driven-development) | 每個任務一個 agent，兩輪審查 |
| **Git Worktree 使用** (using-git-worktrees) | 隔離式特性開發 |
| **完成開發分支** (finishing-a-development-branch) | 合併/PR/保留/丟棄四選一 |
| **編寫 Skills** (writing-skills) | 建立新 skill 的方法論 |
| **使用 Superpowers** (using-superpowers) | 元技能：如何呼叫和優先使用 skills |

### 🇨🇳 中國原創 Skills（4 個）· 上游歷史保留（2 個）

> ⚠️ **下表前 4 個 chinese-\* 為「手動呼叫」skill**——不會自動觸發，需在對話中顯式輸入 `/chinese-xxx` 才會載入。
> 設計為參考資料而非工作流，避免污染上游 skill 的自動排程（如 `requesting-code-review`、`brainstorming` 等）。
>
> ⚠️ **表格最後兩個（mcp-builder / workflow-runner）不是中國原創** —— 它們來自上游，上游後來移除了，本 fork 保留下來繼續維護。全倉 21 個 skill = 15 翻譯 + 4 中國原創 + 2 上游歷史保留。

| Skill | 用途 | 呼叫方式 | 上游有嗎？ |
|-------|------|---------|:---:|
| **中文程式碼審查** (chinese-code-review) | 符合國內團隊文化的程式碼審查規範 | `/chinese-code-review`（手動） | 無 |
| **中文 Git 工作流** (chinese-git-workflow) | 適配 Gitee/Coding/極狐 GitLab/CNB | `/chinese-git-workflow`（手動） | 無 |
| **中文技術文件** (chinese-documentation) | 中文排版規範、中英混排、告別機翻味 | `/chinese-documentation`（手動） | 無 |
| **中文提交規範** (chinese-commit-conventions) | 適配國內團隊的 commit message 規範 | `/chinese-commit-conventions`（手動） | 無 |
| **MCP 伺服器建置** (mcp-builder) | 建置生產級 MCP 工具，擴展 AI 能力邊界 | 自動 | 曾有，上游已移除 |
| **工作流執行器** (workflow-runner) | 在 AI 工具內執行多角色 YAML 工作流 | 自動 | 曾有，上游已移除 |

---

## 快速開始

### 方式一：npm 安裝（推薦）

**專案級**（預設，裝到目前專案）：

```bash
cd /your/project
npx superpowers-zh

⚠️ 專案級安裝不要在主目錄（~）下跑。v1.2.1 起會拒絕並提示，舊版本會把 skills 和 CLAUDE.md 等 bootstrap 檔案寫到你的 home 目錄，污染所有專案。如已誤裝見下文「解除安裝 / 誤裝清理」。想讓 skills 對所有專案生效，請用下面的全域安裝，而不是在 ~ 下跑專案級。

全域安裝（v1.7.0+，裝到使用者目錄，所有專案共享，適合同時維護多個專案）：

npx superpowers-zh --global                 # 自動偵測已裝工具
npx superpowers-zh --global --tool claude   # 或指定工具

全域安裝把 skills 裝到工具的使用者級目錄（如 ~/.claude/skills），一次安裝所有專案自動可用，更新時也只需重裝一次。專案級優先、全域兜底，二者可共存。

支援通用全域安裝的工具（均為 docs 已證實的使用者級載入路徑）：Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts · ZCode · DeepSeek Harness · Reasonix。其中 Codex CLI 全域裝到 ~/.agents/skills（Codex 啟動掃描目錄）；Crush 在 Windows 上裝到 %LOCALAPPDATA%\crush\skills（其 README 明確 Windows 走這裡，不是 ~/.config）。其餘工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code）規則是專案級或存於應用內設定，--global 會提示改用專案級；Gemini CLI / Antigravity 有各自專屬的全域方式（Gemini 走擴充目錄），見對應 docs/README.*.md。

方式二：Claude Code Plugin Marketplace Copy Section

僅限 Claude Code。 走官方 plugin 機制安裝，好處是升級只要一條 claude plugin update，不用重跑 npx：

claude plugin marketplace add jnMetaCode/superpowers-zh
claude plugin install superpowers-zh@superpowers-zh

裝完 claude plugin list 應該看到：

❯ superpowers-zh@superpowers-zh
    Version: <当前版本>
    Scope: user
    Status: ✔ enabled

升級與卸載：

claude plugin marketplace update superpowers-zh          # 先刷新 marketplace 快取
claude plugin update superpowers-zh@superpowers-zh       # 再升級 plugin（需重啟生效）
claude plugin uninstall superpowers-zh@superpowers-zh    # 卸載

和方式一怎麼選？ marketplace 裝的是完整 plugin（skills + hooks + bootstrap 由 Claude Code 統一託管、隨版本更新），但只服務 Claude Code 一款工具。要裝給其餘 25 款工具，仍然用方式一的 npx superpowers-zh。兩者可以共存，但同一個專案裡別重複裝 Claude Code，否則 skills 會出現兩份。

方式三：手動安裝（low-fidelity，僅作備選） Copy Section

⚠️ 手動 cp -r skills 是低保版安裝，不等同於完整 plugin。

superpowers-zh 是一個完整 plugin，包含：skills/（21 個能力）+ hooks/（SessionStart 鉤子，讓 skill 在合適時機自動觸發）+ CLAUDE.md / GEMINI.md 等 bootstrap 引導檔案 + 4 套 plugin manifest（Claude Code / Cursor / Codex / Marketplace）。

下面的 cp -r skills 命令只複製 skills 目錄，不會自動設定 hooks、不會產生 bootstrap 引導。結果：skills 物理上存在，但 AI 不會在合適時機自動呼叫，需要你每次手動喊 "use brainstorming skill" 之類。

強烈推薦用方式一 npx superpowers-zh —— 它會一鍵處理 skills 複製 + bootstrap 產生 + hooks 設定 + 工具特定適配。僅在 npx 不可用（極端無網路環境）時才退到手動。

# 複製倉庫
git clone https://github.com/jnMetaCode/superpowers-zh.git

# 複製 skills 到你的專案（選擇你使用的工具）
cp -r superpowers-zh/skills /your/project/.claude/skills      # Claude Code / Copilot CLI
cp -r superpowers-zh/skills /your/project/.hermes/skills      # Hermes Agent
cp -r superpowers-zh/skills /your/project/.cursor/skills      # Cursor
cp -r superpowers-zh/skills /your/project/.codex/skills       # Codex CLI
cp -r superpowers-zh/skills /your/project/.kiro/skills        # Kiro
cp -r superpowers-zh/skills /your/project/skills/custom       # DeerFlow 2.0
cp -r superpowers-zh/skills /your/project/.trae/rules         # Trae
cp -r superpowers-zh/skills /your/project/.agents        # Antigravity
cp -r superpowers-zh/skills /your/project/.github/superpowers # VS Code (Copilot)
cp -r superpowers-zh/skills /your/project/skills              # OpenClaw
cp -r superpowers-zh/skills /your/project/.windsurf/skills   # Windsurf
cp -r superpowers-zh/skills /your/project/.gemini/skills     # Gemini CLI
cp -r superpowers-zh/skills /your/project/.aider/skills      # Aider
cp -r superpowers-zh/skills /your/project/.opencode/skills   # OpenCode
cp -r superpowers-zh/skills /your/project/.qwen/skills       # Qwen Code
cp -r superpowers-zh/skills /your/project/.claw/skills       # Claw Code（Rust 版）
cp -r superpowers-zh/skills /your/project/.qoder/skills      # Qoder（阿里 AI IDE）

方式四：在設定檔中引用 Copy Section

根據你使用的工具，在對應設定檔中引用 skills：

詳細安裝指南：Kiro · DeerFlow · Trae · Antigravity · VS Code · Codex · OpenCode · OpenClaw · Windsurf · Gemini CLI · Aider · Qwen Code · Hermes Agent · Claw Code · Qoder · CodeBuddy · 華為雲碼道 · Kimi Code · Pi

解除安裝 / 誤裝清理（v1.2.1+） Copy Section

cd /your/project          # 或 cd ~ 如果誤裝到了主目錄
npx superpowers-zh@latest --uninstall

會做這些：

• 刪除所有裝過的 skill 目錄（.claude/skills/、.trae/skills/ 等）
• 刪除獨立 bootstrap 檔案（.trae/rules/superpowers-zh.md、.qoder/rules/superpowers-zh.md、.agents/rules.md）
• 清理追加到 CLAUDE.md / HERMES.md / GEMINI.md / CONVENTIONS.md 裡的 superpowers-zh 段，保留你自己寫的內容

資料安全說明：v1.2.1 起，安裝會把追加內容包在 `` 哨兵註解之間，解除安裝按哨兵精確切除。識別不可靠時跳過 + 警告，絕不會誤刪使用者內容。

其他參數：

貢獻 Copy Chapter

歡迎參與！翻譯改進、新增 skills、Bug 修復都可以。

貢獻方向 Copy Section

我們只接收符合 superpowers 定位的 skill——AI 編程工作流方法論。好的 skill 應該：

• 教 AI 助手怎麼幹活，而不是某個框架/語言的教程
• 解決上游英文版不涵蓋的中國開發者痛點
• 有明確的步驟、檢查清單、範例，AI 載入後能直接執行

歡迎提 Issue 討論你的想法！

交流 · Community Copy Chapter

| 微信掃碼關注 | 微信公眾號 「AI不止語」（微信搜尋 AI_BuZhiYu）— 技術問答 · 專案更新 · 實戰文章

管道 加入方式

QQ 2群 點擊加入（群號 1071280067）

微信群 關注公眾號後回覆「群」取得入群方式 |
| --- | --- |

🌟 相關專案生態 Copy Chapter

九個專案組合使用，涵蓋 AI 編程 + AI 影片創作 + 桌面陪伴的完整鏈路。

🔥 重點推薦：[agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator) — 一句話調度 276 個 AI 專家協作，幾分鐘交付完整方案 Copy Section

以前寫個方案：你當指揮官，把 AI 輪流扮演 5 個角色，複製貼上 10 次，1 小時沒了。

現在： 丟一句話進去 "做一個電商退款流程"，產品 → 架構 → 安全 → 測試 → DBA 自動接力，幾分鐘完整方案落地。

• 🎭 276+ 專家角色（含 64 個中國市場原創：小紅書 / 抖音 / 微信 / 飛書 / 釘釘）
• 🧩 零程式碼 YAML，一行 prompt 就能跑
• 💰 15 種大模型可選（DeepSeek / Claude / OpenAI / Ollama 等，11 種免 key）
• 🔗 與 superpowers-zh 互補：本專案管"怎麼做"（方法論），orchestrator 管"誰來做"（角色協作）

👉 立即體驗 agency-orchestrator →

致謝 Copy Chapter

• 原始英文版：obra/superpowers（MIT 協議）
• 感謝 @obra 建立了這個優秀的專案

授權條款 Copy Chapter

MIT License — 自由使用，商業或個人均可。

📌 最近更新 Copy Chapter

🆕 v1.7.12 更新亮點 —— 透過 Claude Code 外掛市集安裝的使用者請更新（此前技能之間互相呼叫會失敗）：

• 🐛 外掛模式下跨技能呼叫全部失敗（#124）—— 正文照抄了上游的 superpowers: 前綴，而本外掛叫 superpowers-zh，於是 Skill("superpowers:systematic-debugging") 回傳 Unknown skill。32 處已改為裸技能名（兩種分發模式都能解析）
• 🐛 Crush 在 Windows 上裝錯目錄 —— 官方是 %LOCALAPPDATA%\crush\skills，我們兩個平台都裝 ~/.config。文件早寫對了，程式碼沒跟上
• 🐛 render-graphs.js —— 取上游的安全加固與 Windows 修復，但不跟它改 ESM（那會在 Node 20 的普通專案裡直接載入失敗）
• 🆕 新增 DeepSeek Harness 支援（#122）—— 專案級 .dsh/skills/ + 全域 ~/.dsh/skills/，引導寫 AGENTS.md；四條路徑全部有官方出處
• 🐛 在管理員 PowerShell 裡跑會把 skills 裝進 C:\Windows\System32（#125）—— 管理員終端的預設工作目錄就是那裡。補系統目錄護欄，且不提供 --force 繞過
• 🆕 新增 Reasonix 支援（#42）—— 專案級 .reasonix/skills/ + REASONIX.md；Windows 全域是 %APPDATA%\reasonix\skills，與 Unix 不同構
• 🆕 新增 ZCode（智譜）支援（工具數 23 → 26）—— 只做全域安裝：官方文件只公開了 ~/.zcode/skills/，專案級是應用內 UI 匯入、不暴露磁碟路徑，所以專案級會被明確拒絕而不是猜路徑裝進去
• 🛡️ 6 條新門禁（前綴回歸、Windows 路徑、解除安裝不誤刪使用者檔案、全域-only 工具專案級必拒、上游漂移計量…），verify-release 115 → 144

📋 官網側改動（版本提示條、22 份工具文件入口、結構化資料、分享大圖、無障礙、sitemap…）見 完整 Release Notes →

📈 Star 趨勢 Copy Chapter

File: CLAUDE.md Copy Chapter

Superpowers — 贡献者指南

如果你是 AI Agent Copy Chapter

停下来。做任何事之前先读这一节。

本仓库的 PR 拒绝率是 94%。被拒的 PR 里几乎每一条都是没读或没遵守本指南的 agent 提交的。维护者会在数小时内关掉劣质 PR，并经常公开评论："This pull request is slop that's made of lies."（这个 PR 是一堆谎言堆出来的劣质内容。）

你的职责是保护你的人类伙伴免受这种结局。 提交一个低质量 PR 帮不到他们 —— 浪费维护者的时间，砸他们的口碑，PR 也照样会被关闭。这不是帮忙，这是让他们丢人。

向本仓库提 PR 之前，你必须：

1. 完整读完 PR 模板 .github/PULL_REQUEST_TEMPLATE.md，每一节都用真实、具体的内容填写。不要写概要。不要写占位符。
2. 搜索已有 PR —— open 和 closed 都要搜 —— 找处理同一问题的 PR。如果有重复，停下，告诉你的人类伙伴。不要再开一个重复 PR。
3. 核实这是真问题。 如果你的人类伙伴只是让你"修一些问题"或者"给这个仓库做点贡献"而没有具体遇到什么问题，反推回去。问清楚到底什么坏了、什么报错了、用户体验是什么样的。
4. 确认这个改动属于 core。 如果它是某个领域专属、某个工具专属、或者推广某个第三方项目，它应该作为独立 plugin 存在。告诉你的人类伙伴。
5. 把完整 diff 给你的人类伙伴看，拿到他们明确批准之后再提交。

任何一项检查不过，不要开 PR。向你的人类伙伴解释为什么会被拒、需要改什么。他们会感谢你帮他们避免丢脸。

Pull Request 要求 Copy Chapter

每个 PR 都必须完整填写 PR 模板。 不允许任何一节留空或填占位文字。跳过 section 的 PR 会被关掉，连 review 都不会做。

开 PR 之前，你必须搜索已有 PR —— open 和 closed 都要搜 —— 找处理同一问题或相关领域的 PR。在 "Existing PRs" 一节里写清楚你找到了什么。如果之前有 PR 被关闭，具体说明你的方法和它的差异，以及为什么你这次能成功。

没有人类参与痕迹的 PR 会被关闭。 提交前必须有真人 review 完整的 proposed diff。

我们不会接受的内容 Copy Chapter

第三方依赖 Copy Section

凡是引入对第三方项目的可选或必选依赖的 PR，除非是为新 harness（新的 IDE 或 CLI 工具）添加支持，否则不会被接受。Superpowers 在设计上是零依赖 plugin。如果你的改动需要外部工具或服务，它应该作为独立 plugin 存在。

给 skill "合规化" 的改动 Copy Section

我们内部的 skill 哲学跟 Anthropic 公开的 skill 写作指南不一样。我们的 skill 内容是经过大量测试与调优、针对真实 agent 行为校准过的。凡是为了"符合"Anthropic skills 文档而对 skill 做重组、改写、重排版的 PR，没有充分的 eval 证据证明改动改善了实际效果，不会被接受。改动行为塑造类内容的门槛非常高。

项目专属或个人配置 Copy Section

只对某个具体项目、团队、领域、工作流有用的 skill、hook 或配置，不属于 core。请发布为独立 plugin。

批量、广撒网式 PR Copy Section

不要把 issue tracker 翻一遍然后在一个 session 里给多个 issue 各开一个 PR。每个 PR 都需要：对问题的真实理解、对历史尝试的调查、对完整 diff 的人类 review。明显是批量产物 —— 把 agent 指向 issue 列表然后告诉它"修一下" —— 这种 PR 一律关闭。要贡献，就挑一个 issue，深入理解，提交高质量工作。

推测性或理论性修复 Copy Section

每个 PR 都必须解决某人真实经历过的问题。"我的 review agent 标了这个"或"这理论上可能出问题"不是问题陈述。如果你说不出促使这个改动的具体 session、错误或用户体验，不要提交 PR。

领域专属 skill Copy Section

Superpowers core 包含的是对所有用户都有益的通用 skill，跟项目类型无关。针对特定领域（作品集生成、预测市场、游戏）、特定工具或特定工作流的 skill，属于独立 plugin。问问自己："如果有人在做完全不同类型的项目，这个 skill 对他还有用吗？"如果没用，请单独发布。

Fork 专属改动 Copy Section

如果你维护一个有定制化的 fork，不要提 PR 来同步你的 fork 或者把 fork 专属改动推到上游。重新打品牌、添加 fork 专属功能、合并 fork 分支的 PR 会被关闭。

编造的内容 Copy Section

包含编造的论点、虚构的问题描述或幻觉出来的功能的 PR，会被立刻关闭。本仓库 94% 拒绝率 —— 维护者见过 AI slop 的所有花样。他们看得出来。

打包不相关改动 Copy Section

包含多个不相关改动的 PR 会被关闭。请拆成多个 PR。

新 Harness 支持 Copy Chapter

如果你的 PR 是给新 harness（IDE、CLI 工具、agent runner）加支持，你必须附上 session transcript 证明集成端到端可用。

真正的集成会在 session 开始时加载 using-superpowers bootstrap。bootstrap 是让 skill 在恰当时机自动触发的关键。没有它，skill 就是死重 —— 文件在磁盘上但永远不会被调用。

验收测试。 在新 harness 里开一个干净 session，发这条用户消息：

Let's make a react todo list

可工作的集成会在写任何代码之前自动触发 brainstorming skill。把完整 transcript 贴在 PR 里。

以下情况不算真正集成，会被关闭：

• 手动把 skill 文件拷进 harness
• 在运行时用 npx skills 之类 shim 包装
• 任何需要用户每个 session 手动 opt-in skill 的方案
• 任何在上述验收测试里 brainstorming 不会自动触发的方案

如果你不确定你的集成是否在 session 开始时加载 bootstrap，那就是没加载。

Skill 改动需要 eval Copy Chapter

Skill 不是普通文档 —— 它是塑造 agent 行为的代码。如果你修改 skill 内容：

• 用 superpowers:writing-skills 来开发和测试改动
• 跨多个 session 跑对抗式压力测试
• 在 PR 里附上 before/after eval 结果
• 不要在没有改进证据的情况下修改精心调优过的内容（Red Flags 表、rationalization 列表、"human partner" 措辞等）

贡献前先理解项目 Copy Chapter

在提议改 skill 设计、workflow 哲学或架构之前，先读已有 skill，理解项目的设计决策。Superpowers 在 skill 设计、agent 行为塑造和术语方面有自己一套验证过的哲学（例如 "your human partner" 是刻意的措辞，跟 "the user" 不能混用）。在不理解项目"为什么这样存在"的前提下重写项目的语气、重组它的方法的改动，会被拒绝。

通用原则 Copy Chapter

• 提交前读 .github/PULL_REQUEST_TEMPLATE.md
• 一个 PR 解决一个问题
• 至少在一种 harness 上测试，并在 environment 表里报告结果
• 描述你解决了什么问题，不只是你改了什么

关于本中文 fork（superpowers-zh） Copy Chapter

本仓库 jnMetaCode/superpowers-zh 是上游 obra/superpowers 的中文增强 fork，定位为：完整翻译上游 skill + 叠加 4 个中国原创 skill（chinese-code-review / chinese-commit-conventions / chinese-documentation / chinese-git-workflow）+ 多工具适配（npx 一条命令支持 26 款 IDE/CLI）。

上述规则适用于向 obra/superpowers 上游提 PR 时的行为约束。 向中文 fork 提 PR 时按本仓库自己的 PR 模板与流程执行，但其中的核心原则同样适用：

• 提交前先在 jnMetaCode/superpowers-zh 搜已有 PR / issue 查重
• 不交付 AI slop（编造、批量、推测性修复均会被关闭）
• 真人必须 review 完整 diff 后再提交

特别提示： 中文化内容、chinese-* skill、针对国内 IDE 的工具适配等改动，按上游 "Fork-specific changes" 规则向 obra/superpowers 提 PR 会被关闭 —— 这类内容只提到本 fork。

File: CODE_OF_CONDUCT.md Copy Chapter

贡献者公约行为准则

我们的承诺 Copy Chapter

作为成员、贡献者和领导者，我们承诺让每个人都能在我们的社区中获得无骚扰的体验，无论其年龄、体型、可见或不可见的残疾、民族、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何。

我们承诺以有助于建设一个开放、友好、多元、包容且健康的社区的方式行事和互动。

我们的标准 Copy Chapter

有助于为社区营造积极环境的行为包括：

• 对他人表现出同理心和善意
• 尊重不同的观点、看法和经历
• 给予和优雅地接受建设性反馈
• 为自己的错误承担责任并向受影响者道歉，同时从中吸取教训
• 关注的不仅是个人的最佳利益，还有整个社区的最佳利益

不可接受的行为包括：

• 使用性暗示的语言或图像，以及任何形式的性关注或挑逗
• 挑衅、侮辱性或贬低性评论，以及人身攻击或政治攻击
• 公开或私下的骚扰
• 未经明确许可，发布他人的私人信息，如物理地址或电子邮件地址
• 其他在专业环境中被合理认为不恰当的行为

执行责任 Copy Chapter

社区领导者负责阐明和执行我们的行为标准，并对任何他们认为不恰当、具有威胁性、冒犯性或有害的行为采取适当且公平的纠正措施。

社区领导者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、Wiki 编辑、Issue 和其他贡献，并在适当时说明审核决定的原因。

适用范围 Copy Chapter

本行为准则适用于所有社区空间，也适用于个人在公共空间中正式代表社区的情况。代表社区的例子包括使用官方电子邮件地址、通过官方社交媒体账号发帖，或在线上或线下活动中担任指定代表。

执行 Copy Chapter

可以向负责执行的社区领导者报告滥用、骚扰或其他不可接受的行为，联系方式为 [email protected]。所有投诉将被及时、公正地审查和调查。

所有社区领导者都有义务尊重事件报告者的隐私和安全。

执行指南 Copy Chapter

社区领导者将遵循以下社区影响指南，以确定对违反本行为准则的行为的处理方式：

1. 纠正 Copy Section

社区影响：使用不恰当的语言或其他在社区中被视为不专业或不受欢迎的行为。

后果：社区领导者发出私下书面警告，说明违规的性质以及该行为不恰当的原因。可能会要求公开道歉。

2. 警告 Copy Section

社区影响：通过单次事件或一系列行为造成的违规。

后果：发出警告，说明持续此类行为的后果。在指定时间内，不得与相关人员互动，包括与执行行为准则的人员进行非主动的互动。这包括避免在社区空间以及社交媒体等外部渠道中的互动。违反这些条款可能导致临时或永久封禁。

3. 临时封禁 Copy Section

社区影响：严重违反社区标准，包括持续的不恰当行为。

后果：在指定时间内临时禁止与社区进行任何形式的互动或公开沟通。在此期间，不允许与相关人员进行任何公开或私下互动，包括与执行行为准则的人员进行非主动的互动。违反这些条款可能导致永久封禁。

4. 永久封禁 Copy Section

社区影响：表现出持续违反社区标准的模式，包括持续的不恰当行为、对个人的骚扰，或对某类群体的攻击或贬低。

后果：永久禁止在社区内进行任何形式的公开互动。

来源 Copy Chapter

本行为准则改编自贡献者公约 2.0 版本，可在 https://www.contributor-covenant.org/version/2/0/code_of_conduct.html 查看。

社区影响指南受到 Mozilla 行为准则执行阶梯的启发。

有关本行为准则的常见问题，请参阅 https://www.contributor-covenant.org/faq。翻译版本可在 https://www.contributor-covenant.org/translations 查看。

File: gemini-extension.json Copy Chapter

{
"name": "superpowers-zh",
"description": "AI 编程超能力中文版 — TDD、调试、代码审查等经过实战验证的工作方法论",
"version": "1.8.0",
"contextFileName": "GEMINI.md"
}

File: GEMINI.md Copy Chapter

[Binary file]

File: package.json Copy Chapter

{
"name": "superpowers-zh",
"version": "1.8.0",
"engines": {
"node": ">=20.0.0"
},
"description": "AI 编程超能力中文增强版 — superpowers（300k+ ⭐）完整汉化 + 4 个中国原创 skills，支持 Claude Code / Copilot CLI / Hermes Agent / Cursor / Claw Code / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款工具",
"type": "module",
"main": ".opencode/plugins/superpowers.js",
"bin": {
"superpowers-zh": "bin/superpowers-zh.js"
},
"scripts": {
"site": "node site/build.mjs",
"site:deploy": "node site/build.mjs && wrangler pages deploy site/dist --project-name=superpowers-zh-site",
"version": "node scripts/sync-plugin-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .cursor-plugin/plugin.json .codex-plugin/plugin.json .kimi-plugin/plugin.json gemini-extension.json"
},
"files": [
"bin/",
"skills/",
"hooks/",
"assets/",
".claude-plugin/",
".cursor-plugin/",
".codex/INSTALL.md",
".codex-plugin/",
".opencode/INSTALL.md",
".opencode/plugins/",
"index.js",
".pi/extensions/",
"CLAUDE.md",
"GEMINI.md",
"RELEASE-NOTES.md",
"RELEASE-NOTES.zh.md",
"gemini-extension.json",
"docs/",
"README.md",
"LICENSE"
],
"keywords": [
"superpowers",
"claude-code",
"cursor",
"codex",
"gemini",
"kiro",
"deerflow",
"trae",
"antigravity",
"openclaw",
"windsurf",
"aider",
"opencode",
"qwen",
"vscode",
"copilot",
"hermes",
"hermes-agent",
"claw-code",
"qoder",
"codebuddy",
"codearts",
"ai-coding",
"skills",
"chinese",
"中文",
"tdd",
"debugging",
"code-review",
"pi-package"
],
"pi": {
"skills": [
"./skills"
],
"extensions": [
"./.pi/extensions/superpowers.ts"
]
},
"repository": {
"type": "git",
"url": "git+https://github.com/jnMetaCode/superpowers-zh.git"
},
"homepage": "https://github.com/jnMetaCode/superpowers-zh",
"author": "jnMetaCode",
"license": "MIT"
}

File: RELEASE-NOTES.md Copy Chapter

Superpowers Release Notes

v5.1.0 (2026-04-30) Copy Chapter

Removals Copy Section

• Legacy slash commands removed — /brainstorm, /execute-plan, and /write-plan are gone. They were deprecated stubs that did nothing but tell the user to invoke the corresponding skill. Invoke superpowers:brainstorming, superpowers:executing-plans, and superpowers:writing-plans directly instead. (#1188)
• superpowers:code-reviewer named agent removed — the agent was the plugin's only named agent and was used by exactly two skills, while every other reviewer/implementer subagent in the repo dispatches general-purpose with a prompt template alongside its skill. The agent's persona and checklist have been merged into skills/requesting-code-review/code-reviewer.md as a self-contained Task-dispatch template. Anyone dispatching Task (superpowers:code-reviewer) should switch to Task (general-purpose) with the prompt template instead. (PR #1299)
• Integration sections removed from skills — these were a legacy of the time before agents had native skills systems and didn't help with steering.

Worktree Skills Rewrite Copy Section

using-git-worktrees and finishing-a-development-branch now detect when the agent is already running inside an isolated worktree and prefer the harness's native worktree controls before falling back to git worktree. Behavior was TDD-validated and cross-platform-checked across five harnesses. (PRI-974, PR #1121)

• Environment detection — both skills check GIT_DIR != GIT_COMMON before doing anything; if already in a linked worktree, creation is skipped entirely. A submodule guard prevents false detection.
• Consent before creating worktrees — using-git-worktrees no longer creates worktrees implicitly; the skill asks the user first. Fixes #991 (subagent-driven-development was auto-creating worktrees without consent).
• Native tool preference (Step 1a) — when the harness exposes its own worktree tool (e.g. Codex), the skill defers to it. The user's stated preference is respected when expressed.
• Provenance-based cleanup — finishing-a-development-branch only cleans up worktrees inside .worktrees/ (created by superpowers); anything outside is left alone. Fixes #940 (Option 2 was incorrectly cleaning up worktrees), #999 (merge-then-remove ordering), and #238 (cd to repo root before git worktree remove).
• Detached HEAD handling — the finishing menu collapses to two options when there is no branch to merge from.
• Hardcoded /Users/jesse paths in skill examples replaced with generic placeholders. (#858, PR #1122)

Contributor Guidelines for AI Agents Copy Section

Two new sections at the top of CLAUDE.md (symlinked to AGENTS.md) speak directly to AI agents. An audit of the last 100 closed PRs against this repo showed a 94% rejection rate driven by AI-generated slop: agents that didn't read the PR template, opened duplicates, fabricated problem descriptions, or pushed fork- or domain-specific changes upstream.

• Pre-submission checklist — read the PR template, search for existing PRs, verify a real problem exists, confirm the change belongs in core, and show the human partner the complete diff before submitting.
• What we will not accept — third-party dependencies, "compliance" rewrites of skill content, project-specific configuration, bulk PRs, speculative fixes, domain-specific skills, fork-specific changes, fabricated content, and bundled unrelated changes.
• New harness PRs require a session transcript — most past new-harness integrations copied skill files or wrapped with npx skills instead of loading the using-superpowers bootstrap at session start. The acceptance test ("Let's make a react todo list" must auto-trigger brainstorming in a clean session) and a complete transcript are now required.

Codex Plugin Mirror Tooling Copy Section

New sync-to-codex-plugin script mirrors superpowers into the OpenAI Codex plugin marketplace as prime-radiant-inc/openai-codex-plugins. Path/user-agnostic so any team member can run it. (PR #1165)

• Clones the fork fresh into a temp directory per run, regenerates overlays inline, and opens a PR; auto-detects upstream from the script's own location and preflights rsync/git/gh auth/python3.
• --bootstrap flag for first-time setup; EXCLUDES patterns anchored to source root; assets/ excluded.
• Mirrors CODE_OF_CONDUCT.md; drops the agents/openai.yaml overlay.
• Seeds interface.defaultPrompt in the mirrored plugin.json. (PR #1180 by @arittr)
• Codex plugin files are committed to the source repo so the sync script uses canonical versions; Codex marketplace metadata is preserved.

OpenCode Copy Section

• Bootstrap content cached at module level — getBootstrapContent() was calling fs.existsSync + fs.readFileSync + frontmatter regex on every agent step (the experimental.chat.messages.transform hook fires on every step in OpenCode's agent loop). Now read once, cached for the session lifetime, with a null sentinel for the missing-file case. 15 regression tests cover cache behavior, fs call counts, the injection guard, the missing-file sentinel, and cache reset. (Fixes #1202)
• Integration tests modernized.
• Install caveats clarified in the README.

Code Review Consolidation Copy Section

requesting-code-review is now self-contained: the persona, checklist, and dispatch template live in skills/requesting-code-review/code-reviewer.md and the skill dispatches Task (general-purpose) directly. (PR #1299)

• Single source of truth — the persona/checklist that previously lived in both agents/code-reviewer.md and the skill's placeholder template (and drifted independently) is now one file.
• subagent-driven-development follows suit — its code-quality-reviewer-prompt.md now dispatches Task (general-purpose) instead of the named agent.
• Behavioral test added — tests/claude-code/test-requesting-code-review.sh plants real bugs (SQL injection, plaintext password handling, credential logging) into a tiny project and asserts the dispatched reviewer flags every planted issue at Critical/Important severity and refuses to approve the diff.
• Codex and Copilot workaround docs trimmed — the "Named agent dispatch" sections in references/codex-tools.md and references/copilot-tools.md documented how to flatten a named agent into a generic dispatch. With no named agents shipping, the workaround is unnecessary; both sections were dropped.

Subagent-Driven Development Copy Section

• No more pause every 3 tasks — the "review after each batch (3 tasks)" cadence in requesting-code-review (originally for executing-plans) was leaking into subagent-driven-development. Replaced with "each task or at natural checkpoints" plus an explicit continuous-execution directive.
• SDD integration test now runs its assertions — three independent bugs caused the test to silently bail before printing any verification results: an unresolved .. segment in the working-dir path, a set -euo pipefail interaction with find | sort | head -1 (SIGPIPE on the producer killed the script), and a missing --plugin-dir on the claude -p invocation that caused the test to load the installed plugin instead of the working tree. All three fixed; six verification tests now actually run against a real end-to-end SDD run.

Cursor Copy Section

• Windows SessionStart hook routed through run-hook.cmd instead of invoking the extensionless session-start script directly. Fixes Windows opening the file in an editor instead of running it. Also removed an accidental UTF-8 BOM from hooks-cursor.json.

Gemini CLI Copy Section

• Subagent dispatch mapping — Gemini's Task dispatch now maps to @agent-name / @generalist, with parallel subagent dispatch documented for independent tasks.

Skills Copy Section

• Terminology cleanups across skill content.

Documentation & Install Copy Section

• Factory Droid installation instructions added to README.
• Quickstart install links in README. (PR #1293 by @arittr)
• Codex plugin install guidance updated. (PR #1288 by @arittr)
• Codex wait mapping corrected to wait_agent in the tools reference.
• Install order reorganized; Codex install instructions cleaned up.
• Removed vestigial CHANGELOG.md in favor of RELEASE-NOTES.md as the single source. (PR #1163 by @shaanmajid)
• Discord invite link fixed; release announcements link and a detailed Discord description added to the Community section.

Community Copy Section

• @shaanmajid — vestigial CHANGELOG.md removal (PR #1163)
• @arittr — README quickstart install links (#1293), Codex plugin install guidance (#1288), sync-to-codex-plugin interface.defaultPrompt seed (#1180)

v5.0.7 (2026-03-31) Copy Chapter

GitHub Copilot CLI Support Copy Section

• SessionStart context injection — Copilot CLI v1.0.11 added support for additionalContext in sessionStart hook output. The session-start hook now detects the COPILOT_CLI environment variable and emits the SDK-standard { "additionalContext": "..." } format, giving Copilot CLI users the full superpowers bootstrap at session start. (Original fix by @culinablaz in PR #910)
• Tool mapping — added references/copilot-tools.md with the full Claude Code to Copilot CLI tool equivalence table
• Skill and README updates — added Copilot CLI to the using-superpowers skill's platform instructions and README installation section

OpenCode Fixes Copy Section

• Skills path consistency — the bootstrap text no longer advertises a misleading configDir/skills/superpowers/ path that didn't match the runtime path. The agent should use the native skill tool, not navigate to files by path. Tests now use consistent paths derived from a single source of truth. (#847, #916)
• Bootstrap as user message — moved bootstrap injection from experimental.chat.system.transform to experimental.chat.messages.transform, prepending to the first user message instead of adding a system message. Avoids token bloat from system messages repeated every turn (#750) and fixes compatibility with Qwen and other models that break on multiple system messages (#894).

v5.0.6 (2026-03-24) Copy Chapter

Inline Self-Review Replaces Subagent Review Loops Copy Section

The subagent review loop (dispatching a fresh agent to review plans/specs) doubled execution time (~25 min overhead) without measurably improving plan quality. Regression testing across 5 versions with 5 trials each showed identical quality scores regardless of whether the review loop ran.

• brainstorming — replaced Spec Review Loop (subagent dispatch + 3-iteration cap) with inline Spec Self-Review checklist: placeholder scan, internal consistency, scope check, ambiguity check
• writing-plans — replaced Plan Review Loop (subagent dispatch + 3-iteration cap) with inline Self-Review checklist: spec coverage, placeholder scan, type consistency
• writing-plans — added explicit "No Placeholders" section defining plan failures (TBD, vague descriptions, undefined references, "similar to Task N")
• Self-review catches 3-5 real bugs per run in ~30s instead of ~25 min, with comparable defect rates to the subagent approach

Brainstorm Server Copy Section

• Session directory restructured — the brainstorm server session directory now contains two peer subdirectories: content/ (HTML files served to the browser) and state/ (events, server-info, pid, log). Previously, server state and user interaction data were stored alongside served content, making them accessible over HTTP. The screen_dir and state_dir paths are both included in the server-started JSON. (Reported by 吉田仁)

Bug Fixes Copy Section

• Owner-PID lifecycle fixes — the brainstorm server's owner-PID monitoring had two bugs causing false shutdowns within 60 seconds: (1) EPERM from cross-user PIDs (Tailscale SSH, etc.) was treated as "process dead", and (2) on WSL the grandparent PID resolves to a short-lived subprocess that exits before the first lifecycle check. Fixed by treating EPERM as "alive" and validating the owner PID at startup — if it's already dead, monitoring is disabled and the server relies on the 30-minute idle timeout. This also removes the Windows/MSYS2-specific carve-out from start-server.sh since the server now handles it generically. (#879)
• writing-skills — corrected false claim that SKILL.md frontmatter supports "only two fields"; now says "two required fields" and links to the agentskills.io specification for all supported fields (PR #882 by @arittr)

Codex App Compatibility Copy Section

• codex-tools — added named agent dispatch mapping documenting how to translate Claude Code's named agent types to Codex's spawn_agent with worker roles (PR #647 by @arittr)
• codex-tools — added environment detection and Codex App finishing sections for worktree-aware skills (by @arittr)
• Design spec — added Codex App compatibility design spec (PRI-823) covering read-only environment detection, worktree-safe skill behavior, and sandbox fallback patterns (by @arittr)

v5.0.5 (2026-03-17) Copy Chapter

Bug Fixes Copy Section

• Brainstorm server ESM fix — renamed server.js → server.cjs so the brainstorming server starts correctly on Node.js 22+ where the root package.json "type": "module" caused require() to fail. (PR #784 by @sarbojitrana, fixes #774, #780, #783)
• Brainstorm owner-PID on Windows — skip PID lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js, preventing the server from self-terminating after 60 seconds. (#770, docs from PR #768 by @lucasyhzlu-debug)
• stop-server.sh reliability — verify the server process actually died before reporting success. SIGTERM + 2s wait + SIGKILL fallback. (#723)

Changed Copy Section

• Execution handoff — restore user choice between subagent-driven and inline execution after plan writing. Subagent-driven is recommended but no longer mandatory.

v5.0.4 (2026-03-16) Copy Chapter

Review Loop Refinements Copy Section

Dramatically reduces token usage and speeds up spec and plan reviews by eliminating unnecessary review passes and tightening reviewer focus.

• Single whole-plan review — plan reviewer now reviews the complete plan in one pass instead of chunk-by-chunk. Removed all chunk-related concepts (## Chunk N: headings, 1000-line chunk limits, per-chunk dispatch).
• Raised the bar for blocking issues — both spec and plan reviewer prompts now include a "Calibration" section: only flag issues that would cause real problems during implementation. Minor wording, stylistic preferences, and formatting quibbles should not block approval.
• Reduced max review iterations — from 5 to 3 for both spec and plan review loops. If the reviewer is calibrated correctly, 3 rounds is plenty.
• Streamlined reviewer checklists — spec reviewer trimmed from 7 categories to 5; plan reviewer from 7 to 4. Removed formatting-focused checks (task syntax, chunk size) in favor of substance (buildability, spec alignment).

OpenCode Copy Section

• One-line plugin install — OpenCode plugin now auto-registers the skills directory via a config hook. No symlinks or skills.paths config needed. Install is just adding one line to opencode.json. (PR #753)
• Added package.json so OpenCode can install superpowers as an npm package from git.

Bug Fixes Copy Section

• Verify server actually stopped — stop-server.sh now confirms the process is dead before reporting success. SIGTERM + 2s wait + SIGKILL fallback. Reports failure if the process survives. (PR #751)
• Generic agent language — brainstorm companion waiting page now says "the agent" instead of "Claude".

v5.0.3 (2026-03-15) Copy Chapter

Cursor Support Copy Section

• Cursor hooks — added hooks/hooks-cursor.json with Cursor's camelCase format (sessionStart, version: 1) and updated .cursor-plugin/plugin.json to reference it. Fixed platform detection in session-start to check CURSOR_PLUGIN_ROOT first (Cursor may also set CLAUDE_PLUGIN_ROOT). (Based on PR #709)

Bug Fixes Copy Section

• Stop firing SessionStart hook on --resume — the startup hook was re-injecting context on resumed sessions, which already have the context in their conversation history. The hook now fires only on startup, clear, and compact.
• Bash 5.3+ hook hang — replaced heredoc (cat <<EOF) with printf in hooks/session-start. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. (#572, #571)
• POSIX-safe hook script — replaced ${BASH_SOURCE[0]:-$0} with $0 in hooks/session-start. Fixes "Bad substitution" error on Ubuntu/Debian where /bin/sh is dash. (#553)
• Portable shebangs — replaced #!/bin/bash with #!/usr/bin/env bash in all shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where /bin/bash is outdated or missing. (#700)
• Brainstorm server on Windows — auto-detect Windows/Git Bash (OSTYPE=msys*, MSYSTEM) and switch to foreground mode, fixing silent server failure caused by nohup/disown process reaping. (#737)
• Codex docs fix — replaced deprecated collab flag with multi_agent in Codex documentation. (PR #749)

v5.0.2 (2026-03-11) Copy Chapter

Zero-Dependency Brainstorm Server Copy Section

Removed all vendored node_modules — server.js is now fully self-contained

• Replaced Express/Chokidar/WebSocket dependencies with zero-dependency Node.js server using built-in http, fs, and crypto modules
• Removed ~1,200 lines of vendored node_modules/, package.json, and package-lock.json
• Custom WebSocket protocol implementation (RFC 6455 framing, ping/pong, proper close handshake)
• Native fs.watch() file watching replaces Chokidar
• Full test suite: HTTP serving, WebSocket protocol, file watching, and integration tests

Brainstorm Server Reliability Copy Section

• Auto-exit after 30 minutes idle — server shuts down when no clients are connected, preventing orphaned processes
• Owner process tracking — server monitors the parent harness PID and exits when the owning session dies
• Liveness check — skill verifies server is responsive before reusing an existing instance
• Encoding fix — proper <meta charset="utf-8"> on served HTML pages

Subagent Context Isolation Copy Section

• All delegation skills (brainstorming, dispatching-parallel-agents, requesting-code-review, subagent-driven-development, writing-plans) now include context isolation principle
• Subagents receive only the context they need, preventing context window pollution

v5.0.1 (2026-03-10) Copy Chapter

Agentskills Compliance Copy Section

Brainstorm-server moved into skill directory

• Moved lib/brainstorm-server/ → skills/brainstorming/scripts/ per the agentskills.io specification
• All ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/ references replaced with relative scripts/ paths
• Skills are now fully portable across platforms — no platform-specific env vars needed to locate scripts
• lib/ directory removed (was the last remaining content)

New Features Copy Section

Gemini CLI extension

• Native Gemini CLI extension support via gemini-extension.json and GEMINI.md at repo root
• GEMINI.md @imports using-superpowers skill and tool mapping table at session start
• Gemini CLI tool mapping reference (skills/using-superpowers/references/gemini-tools.md) — translates Claude Code tool names (Read, Write, Edit, Bash, etc.) to Gemini CLI equivalents (read_file, write_file, replace, etc.)
• Documents Gemini CLI limitations: no subagent support, skills fall back to executing-plans
• Extension root at repo root for cross-platform compatibility (avoids Windows symlink issues)
• Install instructions added to README

Improvements Copy Section

Multi-platform brainstorm server launch

• Per-platform launch instructions in visual-companion.md: Claude Code (default mode), Codex (auto-foreground via CODEX_CI), Gemini CLI (--foreground with is_background), and fallback for other environments
• Server now writes startup JSON to $SCREEN_DIR/.server-info so agents can find the URL and port even when stdout is hidden by background execution

Brainstorm server dependencies bundled

• node_modules vendored into the repo so the brainstorm server works immediately on fresh plugin installs without requiring npm at runtime
• Removed fsevents from bundled deps (macOS-only native binary; chokidar falls back gracefully without it)
• Fallback auto-install via npm install if node_modules is missing

OpenCode tool mapping fix

• TodoWrite → todowrite (was incorrectly mapped to update_plan); verified against OpenCode source

Bug Fixes Copy Section

Windows/Linux: single quotes break SessionStart hook (#577, #529, #644, PR #585)

• Single quotes around ${CLAUDE_PLUGIN_ROOT} in hooks.json fail on Windows (cmd.exe doesn't recognize single quotes as path delimiters) and on Linux (single quotes prevent variable expansion)
• Fix: replaced single quotes with escaped double quotes — works across macOS bash, Windows cmd.exe, Windows Git Bash, and Linux, with and without spaces in paths
• Verified on Windows 11 (NT 10.0.26200.0) with Claude Code 2.1.72 and Git for Windows

Brainstorming spec review loop skipped (#677)

• The spec review loop (dispatch spec-document-reviewer subagent, iterate until approved) existed in the prose "After the Design" section but was missing from the checklist and process flow diagram
• Since agents follow the diagram and checklist more reliably than prose, the spec review step was being skipped entirely
• Added step 7 (spec review loop) to the checklist and corresponding nodes to the dot graph
• Tested with claude --plugin-dir and claude-session-driver: worker now correctly dispatches the reviewer

Cursor install command (PR #676)

• Fixed Cursor install command in README: /plugin-add → /add-plugin (confirmed via Cursor 2.5 release announcement)

User review gate in brainstorming (#565)

• Added explicit user review step between spec completion and writing-plans handoff
• User must approve the spec before implementation planning begins
• Checklist, process flow, and prose updated with the new gate

Session-start hook emits context only once per platform

• Hook now detects whether it's running in Claude Code or another platform
• Emits hookSpecificOutput for Claude Code, additional_context for others — prevents double context injection

Linting fix in token analysis script

• except: → except Exception: in tests/claude-code/analyze-token-usage.py

Maintenance Copy Section

Removed dead code

• Deleted lib/skills-core.js and its test (tests/opencode/test-skills-core.js) — unused since February 2026
• Removed skills-core existence check from tests/opencode/test-plugin-loading.sh

Community Copy Section

• @karuturi — Claude Code official marketplace install instructions (PR #610)
• @mvanhorn — session-start hook dual-emit fix, OpenCode tool mapping fix
• @daniel-graham — linting fix for bare except
• PR #585 author — Windows/Linux hooks quoting fix

v5.0.0 (2026-03-09) Copy Chapter

Breaking Changes Copy Section

Specs and plans directory restructured

• Specs (brainstorming output) now save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
• Plans (writing-plans output) now save to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
• User preferences for spec/plan locations override these defaults
• All internal skill references, test files, and example paths updated to match
• Migration: move existing files from docs/plans/ to new locations if desired

Subagent-driven development mandatory on capable harnesses

Writing-plans no longer offers a choice between subagent-driven and executing-plans. On harnesses with subagent support (Claude Code, Codex), subagent-driven-development is required. Executing-plans is reserved for harnesses without subagent capability, and now tells the user that Superpowers works better on a subagent-capable platform.

Executing-plans no longer batches

Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers.

Slash commands deprecated

/brainstorm, /write-plan, and /execute-plan now show deprecation notices pointing users to the corresponding skills. Commands will be removed in the next major release.

New Features Copy Section

Visual brainstorming companion

Optional browser-based companion for brainstorming sessions. When a topic would benefit from visuals, the brainstorming skill offers to show mockups, diagrams, comparisons, and other content in a browser window alongside terminal conversation.

• lib/brainstorm-server/ — WebSocket server with browser helper library, session management scripts, and dark/light themed frame template ("Superpowers Brainstorming" with GitHub link)
• skills/brainstorming/visual-companion.md — Progressive disclosure guide for server workflow, screen authoring, and feedback collection
• Brainstorming skill adds a visual companion decision point to its process flow: after exploring project context, the skill evaluates whether upcoming questions involve visual content and offers the companion in its own message
• Per-question decision: even after accepting, each question is evaluated for whether browser or terminal is more appropriate
• Integration tests in tests/brainstorm-server/

Document review system

Automated review loops for spec and plan documents using subagent dispatch:

• skills/brainstorming/spec-document-reviewer-prompt.md — Reviewer checks completeness, consistency, architecture, and YAGNI
• skills/writing-plans/plan-document-reviewer-prompt.md — Reviewer checks spec alignment, task decomposition, file structure, and file size
• Brainstorming dispatches spec reviewer after writing the design doc
• Writing-plans includes chunk-based plan review loop after each section
• Review loops repeat until approved or escalate after 5 iterations
• End-to-end tests in tests/claude-code/test-document-review-system.sh
• Design spec and implementation plan in docs/superpowers/

Architecture guidance across the skill pipeline

Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development:

• Brainstorming — New sections: "Design for isolation and clarity" (clear boundaries, well-defined interfaces, independently testable units) and "Working in existing codebases" (follow existing patterns, targeted improvements only)
• Writing-plans — New "File Structure" section: map out files and responsibilities before defining tasks. New "Scope Check" backstop: catch multi-subsystem specs that should have been decomposed during brainstorming
• SDD implementer — New "Code Organization" section (follow plan's file structure, report concerns about growing files) and "When You're in Over Your Head" escalation guidance
• SDD code quality reviewer — Now checks architecture, unit decomposition, plan conformance, and file growth
• Spec/plan reviewers — Architecture and file size added to review criteria
• Scope assessment — Brainstorming now assesses whether a project is too large for a single spec. Multi-subsystem requests are flagged early and decomposed into sub-projects, each with its own spec → plan → implementation cycle

Subagent-driven development improvements

• Model selection — Guidance for choosing model capability by task type: cheap models for mechanical implementation, standard for integration, capable for architecture and review
• Implementer status protocol — Subagents now report DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. Controller handles each status appropriately: re-dispatching with more context, upgrading model capability, breaking tasks apart, or escalating to human

Improvements Copy Section

Instruction priority hierarchy

Added explicit priority ordering to using-superpowers:

1. User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
2. Superpowers skills — override default system behavior
3. Default system prompt — lowest priority

If CLAUDE.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," the user's instructions win.

SUBAGENT-STOP gate

Added <SUBAGENT-STOP> block to using-superpowers. Subagents dispatched for specific tasks now skip the skill instead of activating the 1% rule and invoking full skill workflows.

Multi-platform improvements

• Codex tool mapping moved to progressive disclosure reference file (references/codex-tools.md)
• Platform Adaptation pointer added so non-Claude-Code platforms can find tool equivalents
• Plan headers now address "agentic workers" instead of "Claude" specifically
• Collab feature requirement documented in docs/README.codex.md

Writing-plans template updates

• Plan steps now use checkbox syntax (- [ ] **Step N:**) for progress tracking
• Plan header references both subagent-driven-development and executing-plans with platform-aware routing

v4.3.1 (2026-02-21) Copy Chapter

Added Copy Section

Cursor support

Superpowers now works with Cursor's plugin system. Includes a .cursor-plugin/plugin.json manifest and Cursor-specific installation instructions in the README. The SessionStart hook output now includes an additional_context field alongside the existing hookSpecificOutput.additionalContext for Cursor hook compatibility.

Fixed Copy Section

Windows: Restored polyglot wrapper for reliable hook execution (#518, #504, #491, #487, #466, #440)

Claude Code's .sh auto-detection on Windows was prepending bash to the hook command, breaking execution. The fix:

• Renamed session-start.sh to session-start (extensionless) so auto-detection doesn't interfere
• Restored run-hook.cmd polyglot wrapper with multi-location bash discovery (standard Git for Windows paths, then PATH fallback)
• Exits silently if no bash is found rather than erroring
• On Unix, the wrapper runs the script directly via exec bash
• Uses POSIX-safe dirname "$0" path resolution (works on dash/sh, not just bash)

This fixes SessionStart failures on Windows with spaces in paths, missing WSL, set -euo pipefail fragility on MSYS, and backslash mangling.

v4.3.0 (2026-02-12) Copy Chapter

This fix should dramatically improve superpowers skills compliance and should reduce the chances of Claude entering its native plan mode unintentionally.

Changed Copy Section

Brainstorming skill now enforces its workflow instead of describing it

Models were skipping the design phase and jumping straight to implementation skills like frontend-design, or collapsing the entire brainstorming process into a single text block. The skill now uses hard gates, a mandatory checklist, and a graphviz process flow to enforce compliance:

• <HARD-GATE>: no implementation skills, code, or scaffolding until design is presented and user approves
• Explicit checklist (6 items) that must be created as tasks and completed in order
• Graphviz process flow with writing-plans as the only valid terminal state
• Anti-pattern callout for "this is too simple to need a design" — the exact rationalization models use to skip the process
• Design section sizing based on section complexity, not project complexity

Using-superpowers workflow graph intercepts EnterPlanMode

Added an EnterPlanMode intercept to the skill flow graph. When the model is about to enter Claude's native plan mode, it checks whether brainstorming has happened and routes through the brainstorming skill instead. Plan mode is never entered.

Fixed Copy Section

SessionStart hook now runs synchronously

Changed async: true to async: false in hooks.json. When async, the hook could fail to complete before the model's first turn, meaning using-superpowers instructions weren't in context for the first message.

v4.2.0 (2026-02-05) Copy Chapter

Breaking Changes Copy Section

Codex: Replaced bootstrap CLI with native skill discovery

The superpowers-codex bootstrap CLI, Windows .cmd wrapper, and related bootstrap content file have been removed. Codex now uses native skill discovery via ~/.agents/skills/superpowers/ symlink, so the old use_skill/find_skills CLI tools are no longer needed.

Installation is now just clone + symlink (documented in INSTALL.md). No Node.js dependency required. The old ~/.codex/skills/ path is deprecated.

Fixes Copy Section

Windows: Fixed Claude Code 2.1.x hook execution (#331)

Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects .sh files in commands and prepends bash. This broke the polyglot wrapper pattern because bash "run-hook.cmd" session-start.sh tries to execute the .cmd file as a bash script.

Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).

Windows: SessionStart hook runs async to prevent terminal freeze (#404, #413, #414, #419)

The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing all keyboard input. Running the hook async prevents the freeze while still injecting superpowers context.

Windows: Fixed O(n^2) escape_for_json performance

The character-by-character loop using ${input:$i:1} was O(n^2) in bash due to substring copy overhead. On Windows Git Bash this took 60+ seconds. Replaced with bash parameter substitution (${s//old/new}) which runs each pattern as a single C-level pass — 7x faster on macOS, dramatically faster on Windows.

Codex: Fixed Windows/PowerShell invocation (#285, #243)

• Windows doesn't respect shebangs, so directly invoking the extensionless superpowers-codex script triggered an "Open with" dialog. All invocations now prefixed with node.
• Fixed ~/ path expansion on Windows — PowerShell doesn't expand ~ when passed as an argument to node. Changed to $HOME which expands correctly in both bash and PowerShell.

Codex: Fixed path resolution in installer

Used fileURLToPath() instead of manual URL pathname parsing to correctly handle paths with spaces and special characters on all platforms.

Codex: Fixed stale skills path in writing-skills

Updated ~/.codex/skills/ reference (deprecated) to ~/.agents/skills/ for native discovery.

Improvements Copy Section

Worktree isolation now required before implementation

Added using-git-worktrees as a required skill for both subagent-driven-development and executing-plans. Implementation workflows now explicitly require setting up an isolated worktree before starting work, preventing accidental work directly on main.

Main branch protection softened to require explicit consent

Instead of prohibiting main branch work entirely, the skills now allow it with explicit user consent. More flexible while still ensuring users are aware of the implications.

Simplified installation verification

Removed /help command check and specific slash command list from verification steps. Skills are primarily invoked by describing what you want to do, not by running specific commands.

Codex: Clarified subagent tool mapping in bootstrap

Improved documentation of how Codex tools map to Claude Code equivalents for subagent workflows.

Tests Copy Section

• Added worktree requirement test for subagent-driven-development
• Added main branch red flag warning test
• Fixed case sensitivity in skill recognition test assertions

v4.1.1 (2026-01-23) Copy Chapter

Fixes Copy Section

OpenCode: Standardized on plugins/ directory per official docs (#343)

OpenCode's official documentation uses ~/.config/opencode/plugins/ (plural). Our docs previously used plugin/ (singular). While OpenCode accepts both forms, we've standardized on the official convention to avoid confusion.

Changes:

• Renamed .opencode/plugin/ to .opencode/plugins/ in repo structure
• Updated all installation docs (INSTALL.md, README.opencode.md) across all platforms
• Updated test scripts to match

OpenCode: Fixed symlink instructions (#339, #342)

• Added explicit rm before ln -s (fixes "file already exists" errors on reinstall)
• Added missing skills symlink step that was absent from INSTALL.md
• Updated from deprecated use_skill/find_skills to native skill tool references

v4.1.0 (2026-01-23) Copy Chapter

Breaking Changes Copy Section

OpenCode: Switched to native skills system

Superpowers for OpenCode now uses OpenCode's native skill tool instead of custom use_skill/find_skills tools. This is a cleaner integration that works with OpenCode's built-in skill discovery.

Migration required: Skills must be symlinked to ~/.config/opencode/skills/superpowers/ (see updated installation docs).

Fixes Copy Section

OpenCode: Fixed agent reset on session start (#226)

The previous bootstrap injection method using session.prompt({ noReply: true }) caused OpenCode to reset the selected agent to "build" on first message. Now uses experimental.chat.system.transform hook which modifies the system prompt directly without side effects.

OpenCode: Fixed Windows installation (#232)

• Removed dependency on skills-core.js (eliminates broken relative imports when file is copied instead of symlinked)
• Added comprehensive Windows installation docs for cmd.exe, PowerShell, and Git Bash
• Documented proper symlink vs junction usage for each platform

Claude Code: Fixed Windows hook execution for Claude Code 2.1.x

Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects .sh files in commands and prepends bash . This broke the polyglot wrapper pattern because bash "run-hook.cmd" session-start.sh tries to execute the .cmd file as a bash script.

Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).

v4.0.3 (2025-12-26) Copy Chapter

Improvements Copy Section

Strengthened using-superpowers skill for explicit skill requests

Addressed a failure mode where Claude would skip invoking a skill even when the user explicitly requested it by name (e.g., "subagent-driven-development, please"). Claude would think "I know what that means" and start working directly instead of loading the skill.

Changes:

• Updated "The Rule" to say "Invoke relevant or requested skills" instead of "Check for skills" - emphasizing active invocation over passive checking
• Added "BEFORE any response or action" - the original wording only mentioned "response" but Claude would sometimes take action without responding first
• Added reassurance that invoking a wrong skill is okay - reduces hesitation
• Added new red flag: "I know what that means" → Knowing the concept ≠ using the skill

Added explicit skill request tests

New test suite in tests/explicit-skill-requests/ that verifies Claude correctly invokes skills when users request them by name. Includes single-turn and multi-turn test scenarios.

v4.0.2 (2025-12-23) Copy Chapter

Fixes Copy Section

Slash commands now user-only

Added disable-model-invocation: true to all three slash commands (/brainstorm, /execute-plan, /write-plan). Claude can no longer invoke these commands via the Skill tool—they're restricted to manual user invocation only.

The underlying skills (superpowers:brainstorming, superpowers:executing-plans, superpowers:writing-plans) remain available for Claude to invoke autonomously. This change prevents confusion when Claude would invoke a command that just redirects to a skill anyway.

v4.0.1 (2025-12-23) Copy Chapter

Fixes Copy Section

Clarified how to access skills in Claude Code

Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The using-superpowers skill now explicitly states that the Skill tool loads skill content directly—no need to read files.

• Added "How to Access Skills" section to using-superpowers
• Changed "read the skill" → "invoke the skill" in instructions
• Updated slash commands to use fully qualified skill names (e.g., superpowers:brainstorming)

Added GitHub thread reply guidance to receiving-code-review (h/t @ralphbean)

Added a note about replying to inline review comments in the original thread rather than as top-level PR comments.

Added automation-over-documentation guidance to writing-skills (h/t @EthanJStark)

Added guidance that mechanical constraints should be automated, not documented—save skills for judgment calls.

v4.0.0 (2025-12-17) Copy Chapter

New Features Copy Section

Two-stage code review in subagent-driven-development

Subagent workflows now use two separate review stages after each task:

1. Spec compliance review - Skeptical reviewer verifies implementation matches spec exactly. Catches missing requirements AND over-building. Won't trust implementer's report—reads actual code.

2. Code quality review - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability.

This catches the common failure mode where code is well-written but doesn't match what was requested. Reviews are loops, not one-shot: if reviewer finds issues, implementer fixes them, then reviewer checks again.

Other subagent workflow improvements:

• Controller provides full task text to workers (not file references)
• Workers can ask clarifying questions before AND during work
• Self-review checklist before reporting completion
• Plan read once at start, extracted to TodoWrite

New prompt templates in skills/subagent-driven-development/:

• implementer-prompt.md - Includes self-review checklist, encourages questions
• spec-reviewer-prompt.md - Skeptical verification against requirements
• code-quality-reviewer-prompt.md - Standard code review

Debugging techniques consolidated with tools

systematic-debugging now bundles supporting techniques and tools:

• root-cause-tracing.md - Trace bugs backward through call stack
• defense-in-depth.md - Add validation at multiple layers
• condition-based-waiting.md - Replace arbitrary timeouts with condition polling
• find-polluter.sh - Bisection script to find which test creates pollution
• condition-based-waiting-example.ts - Complete implementation from real debugging session

Testing anti-patterns reference

test-driven-development now includes testing-anti-patterns.md covering:

• Testing mock behavior instead of real behavior
• Adding test-only methods to production classes
• Mocking without understanding dependencies
• Incomplete mocks that hide structural assumptions

Skill test infrastructure

Three new test frameworks for validating skill behavior:

tests/skill-triggering/ - Validates skills trigger from naive prompts without explicit naming. Tests 6 skills to ensure descriptions alone are sufficient.

tests/claude-code/ - Integration tests using claude -p for headless testing. Verifies skill usage via session transcript (JSONL) analysis. Includes analyze-token-usage.py for cost tracking.

tests/subagent-driven-dev/ - End-to-end workflow validation with two complete test projects:

• go-fractals/ - CLI tool with Sierpinski/Mandelbrot (10 tasks)
• svelte-todo/ - CRUD app with localStorage and Playwright (12 tasks)

Major Changes Copy Section

DOT flowcharts as executable specifications

Rewrote key skills using DOT/GraphViz flowcharts as the authoritative process definition. Prose becomes supporting content.

The Description Trap (documented in writing-skills): Discovered that skill descriptions override flowchart content when descriptions contain workflow summaries. Claude follows the short description instead of reading the detailed flowchart. Fix: descriptions must be trigger-only ("Use when X") with no process details.

Skill priority in using-superpowers

When multiple skills apply, process skills (brainstorming, debugging) now explicitly come before implementation skills. "Build X" triggers brainstorming first, then domain skills.

brainstorming trigger strengthened

Description changed to imperative: "You MUST use this before any creative work—creating features, building components, adding functionality, or modifying behavior."

Breaking Changes Copy Section

Skill consolidation - Six standalone skills merged:

• root-cause-tracing, defense-in-depth, condition-based-waiting → bundled in systematic-debugging/
• testing-skills-with-subagents → bundled in writing-skills/
• testing-anti-patterns → bundled in test-driven-development/
• sharing-skills removed (obsolete)

Other Improvements Copy Section

• render-graphs.js - Tool to extract DOT diagrams from skills and render to SVG
• Rationalizations table in using-superpowers - Scannable format including new entries: "I need more context first", "Let me explore first", "This feels productive"
• docs/testing.md - Guide to testing skills with Claude Code integration tests

v3.6.2 (2025-12-03) Copy Chapter

Fixed Copy Section

• Linux Compatibility: Fixed polyglot hook wrapper (run-hook.cmd) to use POSIX-compliant syntax
  • Replaced bash-specific ${BASH_SOURCE[0]:-$0} with standard $0 on line 16
  • Resolves "Bad substitution" error on Ubuntu/Debian systems where /bin/sh is dash
  • Fixes #141

v3.5.1 (2025-11-24) Copy Chapter

Changed Copy Section

• OpenCode Bootstrap Refactor: Switched from chat.message hook to session.created event for bootstrap injection
  • Bootstrap now injects at session creation via session.prompt() with noReply: true
  • Explicitly tells the model that using-superpowers is already loaded to prevent redundant skill loading
  • Consolidated bootstrap content generation into shared getBootstrapContent() helper
  • Cleaner single-implementation approach (removed fallback pattern)

v3.5.0 (2025-11-23) Copy Chapter

Added Copy Section

• OpenCode Support: Native JavaScript plugin for OpenCode.ai
  • Custom tools: use_skill and find_skills
  • Message insertion pattern for skill persistence across context compaction
  • Automatic context injection via chat.message hook
  • Auto re-injection on session.compacted events
  • Three-tier skill priority: project > personal > superpowers
  • Project-local skills support (.opencode/skills/)
  • Shared core module (lib/skills-core.js) for code reuse with Codex
  • Automated test suite with proper isolation (tests/opencode/)
  • Platform-specific documentation (docs/README.opencode.md, docs/README.codex.md)

Changed Copy Section

• Refactored Codex Implementation: Now uses shared lib/skills-core.js ES module

  • Eliminates code duplication between Codex and OpenCode
  • Single source of truth for skill discovery and parsing
  • Codex successfully loads ES modules via Node.js interop

• Improved Documentation: Rewrote README to explain problem/solution clearly

  • Removed duplicate sections and conflicting information
  • Added complete workflow description (brainstorm → plan → execute → finish)
  • Simplified platform installation instructions
  • Emphasized skill-checking protocol over automatic activation claims

v3.4.1 (2025-10-31) Copy Chapter

Improvements Copy Section

• Optimized superpowers bootstrap to eliminate redundant skill execution. The using-superpowers skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute using-superpowers manually despite already having the content from session start.

v3.4.0 (2025-10-30) Copy Chapter

Improvements Copy Section

• Simplified brainstorming skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features.

v3.3.1 (2025-10-28) Copy Chapter

Improvements Copy Section

• Updated brainstorming skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans.
• Applied writing clarity improvements to brainstorming skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction).

Bug Fixes Copy Section

• Clarified writing-skills guidance so it points to the correct agent-specific personal skill directories (~/.claude/skills for Claude Code, ~/.codex/skills for Codex).

v3.3.0 (2025-10-28) Copy Chapter

New Features Copy Section

Experimental Codex Support

• Added unified superpowers-codex script with bootstrap/use-skill/find-skills commands
• Cross-platform Node.js implementation (works on Windows, macOS, Linux)
• Namespaced skills: superpowers:skill-name for superpowers skills, skill-name for personal
• Personal skills override superpowers skills when names match
• Clean skill display: shows name/description without raw frontmatter
• Helpful context: shows supporting files directory for each skill
• Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
• Bootstrap integration with minimal AGENTS.md for automatic startup
• Complete installation guide and bootstrap instructions specific to Codex

Key differences from Claude Code integration:

• Single unified script instead of separate tools
• Tool substitution system for Codex-specific equivalents
• Simplified subagent handling (manual work instead of delegation)
• Updated terminology: "Superpowers skills" instead of "Core skills"

Files Added Copy Section

• .codex/INSTALL.md - Installation guide for Codex users
• .codex/superpowers-bootstrap.md - Bootstrap instructions with Codex adaptations
• .codex/superpowers-codex - Unified Node.js executable with all functionality

Note: Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.

v3.2.3 (2025-10-23) Copy Chapter

Improvements Copy Section

Updated using-superpowers skill to use Skill tool instead of Read tool

• Changed skill invocation instructions from Read tool to Skill tool
• Updated description: "using Read tool" → "using Skill tool"
• Updated step 3: "Use the Read tool" → "Use the Skill tool to read and run"
• Updated rationalization list: "Read the current version" → "Run the current version"

The Skill tool is the proper mechanism for invoking skills in Claude Code. This update corrects the bootstrap instructions to guide agents toward the correct tool.

Files Changed Copy Section

• Updated: skills/using-superpowers/SKILL.md - Changed tool references from Read to Skill

v3.2.2 (2025-10-21) Copy Chapter

Improvements Copy Section

Strengthened using-superpowers skill against agent rationalization

• Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking
  • "If even 1% chance a skill applies, you MUST read it"
  • "You do not have a choice. You cannot rationalize your way out."
• Added MANDATORY FIRST RESPONSE PROTOCOL checklist
  • 5-step process agents must complete before any response
  • Explicit "responding without this = failure" consequence
• Added Common Rationalizations section with 8 specific evasion patterns
  • "This is just a simple question" → WRONG
  • "I can check files quickly" → WRONG
  • "Let me gather information first" → WRONG
  • Plus 5 more common patterns observed in agent behavior

These changes address observed agent behavior where they rationalize around skill usage despite clear instructions. The forceful language and pre-emptive counter-arguments aim to make non-compliance harder.

Files Changed Copy Section

• Updated: skills/using-superpowers/SKILL.md - Added three layers of enforcement to prevent skill-skipping rationalization

v3.2.1 (2025-10-20) Copy Chapter

New Features Copy Section

Code reviewer agent now included in plugin

• Added superpowers:code-reviewer agent to plugin's agents/ directory
• Agent provides systematic code review against plans and coding standards
• Previously required users to have personal agent configuration
• All skill references updated to use namespaced superpowers:code-reviewer
• Fixes #55

Files Changed Copy Section

• New: agents/code-reviewer.md - Agent definition with review checklist and output format
• Updated: skills/requesting-code-review/SKILL.md - References to superpowers:code-reviewer
• Updated: skills/subagent-driven-development/SKILL.md - References to superpowers:code-reviewer

v3.2.0 (2025-10-18) Copy Chapter

New Features Copy Section

Design documentation in brainstorming workflow

• Added Phase 4: Design Documentation to brainstorming skill
• Design documents now written to docs/plans/YYYY-MM-DD-<topic>-design.md before implementation
• Restores functionality from original brainstorming command that was lost during skill conversion
• Documents written before worktree setup and implementation planning
• Tested with subagent to verify compliance under time pressure

Breaking Changes Copy Section

Skill reference namespace standardization

• All internal skill references now use superpowers: namespace prefix
• Updated format: superpowers:test-driven-development (previously just test-driven-development)
• Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references
• Aligns with how skills are invoked using the Skill tool
• Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills

Improvements Copy Section

Design vs implementation plan naming

• Design documents use -design.md suffix to prevent filename collisions
• Implementation plans continue using existing YYYY-MM-DD-<feature-name>.md format
• Both stored in docs/plans/ directory with clear naming distinction

v3.1.1 (2025-10-17) Copy Chapter

Bug Fixes Copy Section

• Fixed command syntax in README (#44) - Updated all command references to use correct namespaced syntax (/superpowers:brainstorm instead of /brainstorm). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins.

v3.1.0 (2025-10-17) Copy Chapter

Breaking Changes Copy Section

Skill names standardized to lowercase

• All skill frontmatter name: fields now use lowercase kebab-case matching directory names
• Examples: brainstorming, test-driven-development, using-git-worktrees
• All skill announcements and cross-references updated to lowercase format
• This ensures consistent naming across directory names, frontmatter, and documentation

New Features Copy Section

Enhanced brainstorming skill

• Added Quick Reference table showing phases, activities, and tool usage
• Added copyable workflow checklist for tracking progress
• Added decision flowchart for when to revisit earlier phases
• Added comprehensive AskUserQuestion tool guidance with concrete examples
• Added "Question Patterns" section explaining when to use structured vs open-ended questions
• Restructured Key Principles as scannable table

Anthropic best practices integration

• Added skills/writing-skills/anthropic-best-practices.md - Official Anthropic skill authoring guide
• Referenced in writing-skills SKILL.md for comprehensive guidance
• Provides patterns for progressive disclosure, workflows, and evaluation

Improvements Copy Section

Skill cross-reference clarity

• All skill references now use explicit requirement markers:
  • **REQUIRED BACKGROUND:** - Prerequisites you must understand
  • **REQUIRED SUB-SKILL:** - Skills that must be used in workflow
  • **Complementary skills:** - Optional but helpful related skills
• Removed old path format (skills/collaboration/X → just X)
• Updated Integration sections with categorized relationships (Required vs Complementary)
• Updated cross-reference documentation with best practices

Alignment with Anthropic best practices

• Fixed description grammar and voice (fully third-person)
• Added Quick Reference tables for scanning
• Added workflow checklists Claude can copy and track
• Appropriate use of flowcharts for non-obvious decision points
• Improved scannable table formats
• All skills well under 500-line recommendation

Bug Fixes Copy Section

• Re-added missing command redirects - Restored commands/brainstorm.md and commands/write-plan.md that were accidentally removed in v3.0 migration
• Fixed defense-in-depth name mismatch (was Defense-in-Depth-Validation)
• Fixed receiving-code-review name mismatch (was Code-Review-Reception)
• Fixed commands/brainstorm.md reference to correct skill name
• Removed references to non-existent related skills

Documentation Copy Section

writing-skills improvements

• Updated cross-referencing guidance with explicit requirement markers
• Added reference to Anthropic's official best practices
• Improved examples showing proper skill reference format

v3.0.1 (2025-10-16) Copy Chapter

Changes Copy Section

We now use Anthropic's first-party skills system!

v2.0.2 (2025-10-12) Copy Chapter

Bug Fixes Copy Section

• Fixed false warning when local skills repo is ahead of upstream - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn).

v2.0.1 (2025-10-12) Copy Chapter

Bug Fixes Copy Section

• Fixed session-start hook execution in plugin context (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by:
  • Using ${BASH_SOURCE[0]:-$0} fallback when BASH_SOURCE is unbound in Claude Code's execution context
  • Adding || true to handle empty grep results gracefully when filtering status flags

Superpowers v2.0.0 Release Notes

Overview Copy Chapter

Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift.

The headline change is skills repository separation: all skills, scripts, and documentation have moved from the plugin into a dedicated repository (obra/superpowers-skills). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin.

Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core using-skills documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. find-skills now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow.

Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource.

Breaking Changes Copy Chapter

Skills Repository Separation Copy Section

The biggest change: Skills no longer live in the plugin. They've been moved to a separate repository at obra/superpowers-skills.

What this means for you:

• First install: Plugin automatically clones skills to ~/.config/superpowers/skills/
• Forking: During setup, you'll be offered the option to fork the skills repo (if gh is installed)
• Updates: Skills auto-update on session start (fast-forward when possible)
• Contributing: Work on branches, commit locally, submit PRs to upstream
• No more shadowing: Old two-tier system (personal/core) replaced with single-repo branch workflow

Migration:

If you have an existing installation:

1. Your old ~/.config/superpowers/.git will be backed up to ~/.config/superpowers/.git.bak
2. Old skills will be backed up to ~/.config/superpowers/skills.bak
3. Fresh clone of obra/superpowers-skills will be created at ~/.config/superpowers/skills/

Removed Features Copy Section

• Personal superpowers overlay system - Replaced with git branch workflow
• setup-personal-superpowers hook - Replaced by initialize-skills.sh

New Features Copy Chapter

Skills Repository Infrastructure Copy Section

Automatic Clone & Setup (lib/initialize-skills.sh)

• Clones obra/superpowers-skills on first run
• Offers fork creation if GitHub CLI is installed
• Sets up upstream/origin remotes correctly
• Handles migration from old installation

Auto-Update

• Fetches from tracking remote on every session start
• Auto-merges with fast-forward when possible
• Notifies when manual sync needed (branch diverged)
• Uses pulling-updates-from-skills-repository skill for manual sync

New Skills Copy Section

Problem-Solving Skills (skills/problem-solving/)

• collision-zone-thinking - Force unrelated concepts together for emergent insights
• inversion-exercise - Flip assumptions to reveal hidden constraints
• meta-pattern-recognition - Spot universal principles across domains
• scale-game - Test at extremes to expose fundamental truths
• simplification-cascades - Find insights that eliminate multiple components
• when-stuck - Dispatch to right problem-solving technique

Research Skills (skills/research/)

• tracing-knowledge-lineages - Understand how ideas evolved over time

Architecture Skills (skills/architecture/)

• preserving-productive-tensions - Keep multiple valid approaches instead of forcing premature resolution

Skills Improvements Copy Section

using-skills (formerly getting-started)

• Renamed from getting-started to using-skills
• Complete rewrite with imperative tone (v4.0.0)
• Front-loaded critical rules
• Added "Why" explanations for all workflows
• Always includes /SKILL.md suffix in references
• Clearer distinction between rigid rules and flexible patterns

writing-skills

• Cross-referencing guidance moved from using-skills
• Added token efficiency section (word count targets)
• Improved CSO (Claude Search Optimization) guidance

sharing-skills

• Updated for new branch-and-PR workflow (v2.0.0)
• Removed personal/core split references

pulling-updates-from-skills-repository (new)

• Complete workflow for syncing with upstream
• Replaces old "updating-skills" skill

Tools Improvements Copy Section

find-skills

• Now outputs full paths with /SKILL.md suffix
• Makes paths directly usable with Read tool
• Updated help text

skill-run

• Moved from scripts/ to skills/using-skills/
• Improved documentation

Plugin Infrastructure Copy Section

Session Start Hook

• Now loads from skills repository location
• Shows full skills list at session start
• Prints skills location info
• Shows update status (updated successfully / behind upstream)
• Moved "skills behind" warning to end of output

Environment Variables

• SUPERPOWERS_SKILLS_ROOT set to ~/.config/superpowers/skills
• Used consistently throughout all paths

Bug Fixes Copy Chapter

• Fixed duplicate upstream remote addition when forking
• Fixed find-skills double "skills/" prefix in output
• Removed obsolete setup-personal-superpowers call from session-start
• Fixed path references throughout hooks and commands

Documentation Copy Chapter

README Copy Section

• Updated for new skills repository architecture
• Prominent link to superpowers-skills repo
• Updated auto-update description
• Fixed skill names and references
• Updated Meta skills list

Testing Documentation Copy Section

• Added comprehensive testing checklist (docs/TESTING-CHECKLIST.md)
• Created local marketplace config for testing
• Documented manual testing scenarios

Technical Details Copy Chapter

File Changes Copy Section

Added:

• lib/initialize-skills.sh - Skills repo initialization and auto-update
• docs/TESTING-CHECKLIST.md - Manual testing scenarios
• .claude-plugin/marketplace.json - Local testing config

Removed:

• skills/ directory (82 files) - Now in obra/superpowers-skills
• scripts/ directory - Now in obra/superpowers-skills/skills/using-skills/
• hooks/setup-personal-superpowers.sh - Obsolete

Modified:

• hooks/session-start.sh - Use skills from ~/.config/superpowers/skills
• commands/brainstorm.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
• commands/write-plan.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
• commands/execute-plan.md - Updated paths to SUPERPOWERS_SKILLS_ROOT
• README.md - Complete rewrite for new architecture

Commit History Copy Section

This release includes:

• 20+ commits for skills repository separation
• PR #1: Amplifier-inspired problem-solving and research skills
• PR #2: Personal superpowers overlay system (later replaced)
• Multiple skill refinements and documentation improvements

Upgrade Instructions Copy Chapter

Fresh Install Copy Section

# In Claude Code
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

The plugin handles everything automatically.

Upgrading from v1.x Copy Section

1. Backup your personal skills (if you have any):

   bash Copy

   cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup

2. Update the plugin:

   bash Copy

   /plugin update superpowers

3. On next session start:

   • Old installation will be backed up automatically
   • Fresh skills repo will be cloned
   • If you have GitHub CLI, you'll be offered the option to fork

4. Migrate personal skills (if you had any):

   • Create a branch in your local skills repo
   • Copy your personal skills from backup
   • Commit and push to your fork
   • Consider contributing back via PR

What's Next Copy Chapter

For Users Copy Section

• Explore the new problem-solving skills
• Try the branch-based workflow for skill improvements
• Contribute skills back to the community

For Contributors Copy Section

• Skills repository is now at https://github.com/obra/superpowers-skills
• Fork → Branch → PR workflow
• See skills/meta/writing-skills/SKILL.md for TDD approach to documentation

Known Issues Copy Chapter

None at this time.

Credits Copy Chapter

• Problem-solving skills inspired by Amplifier patterns
• Community contributions and feedback
• Extensive testing and iteration on skill effectiveness

Full Changelog: https://github.com/obra/superpowers/compare/dd013f6...main
Skills Repository: https://github.com/obra/superpowers-skills
Issues: https://github.com/obra/superpowers/issues

File: RELEASE-NOTES.zh.md Copy Chapter

Superpowers-ZH 中文版 Release Notes

本文档记录 jnMetaCode/superpowers-zh 中文 fork 自身的 release 历史。

上游 obra/superpowers 的英文 release notes 见 RELEASE-NOTES.md（原样保留，未翻译）。

v1.8.0 (2026-10-19) Copy Chapter

同步上游 v7.0.0，所有用户建议更新。 brainstorming 按上游从头重写，另有一批 hook、脚本和示例修复。

🔁 brainstorming 重写：先弄清你想要什么 Copy Section

• 先判断"我到底知道多少"：要紧的信息都在请求里（"把图标改成矢车菊蓝"），就直接做；缺了东西才开始对话
• 第一条消息只有两件事：告诉你可以跳过提问让它直接开始，以及一个让你开始描述的开放问题
• 每条消息只问一个问题，先让你描述，只在你卡住时才给选项；你说"你猜一个吧""你觉得呢"，它就直接提方案
• 理解一部分就复述一部分（约 200-300 字），标明哪些是它的猜测，请你纠正
• 意图清楚后再定规模：快速明确的任务 / 小改动（对话里定）/ 需要书面设计的项目，你可以推翻
• 书面设计交给你之前，先由一个扮演该领域建造者的子代理检查（builder check），只把必须由你回答的问题一次性带回来；取代原来的 spec 审查（spec-document-reviewer-prompt.md 已删除，新增 builder-check-prompt.md）
• 不再限于软件：一场分享、一门生意、一次装修也适用
• 硬门槛保留：完整描述获批之前不构建；唯一例外是你同意的一次性 spike，要保留它的代码算新需求

本 fork 的补充（上游没有）： 中文里"你看着办""你定吧"是请它拿主意，不是让它跳过提问直接动手。eval 中未加这句说明时，智能体两次把"反正你看着办吧"当成跳过流程、未经批准就开始写代码；补充后复测未再出现。

eval 摘要： 8 个场景（含非软件、施压、spike、"你看着办"），对比旧中文版、新中文版和上游英文原文，被测模型 claude-opus-5-5。新中文版与英文原文表现一致，都明显优于旧版：旧版普遍先给 A–E 选项菜单、一条消息问多个问题；新版一次一个开放问题并分块复述。受账号额度限制，每组样本为 1–2 次。

🐛 修复 Copy Section

• SessionStart hook：Claude Code 以空 PATH 启动 hook 时，不再因找不到 dirname/cat 而丢失 bootstrap；Windows 上不再误选 WSL 启动器或执行当前目录下的同名程序，hook 退出码不再丢失（同步上游 v7）
• executing-plans：测试成功但没有输出时，task-done 也会记账（此前返回 1 且不记账）
• subagent-driven-development：sdd-workspace 不再覆盖你自己的 .superpowers/sdd/.gitignore；Windows Git Bash 下计划标记改为仓库相对路径
• 视觉伴侣：内容里的 $&、$' 等不再被当作替换模式篡改
• 带参数调用 skill：Claude Code 会把正文里的 $1 等替换成参数。requesting-code-review 的 BASE_SHA 示例（同步上游），以及本 fork 的 chinese-code-review（参数化查询示例）、chinese-commit-conventions（husky 命令）都已改写；CI 新增检查防止再出现
• systematic-debugging：诊断示例只报告变量是否设置，不再把凭据值打印到日志
• OpenCode 文档：「固定到特定版本」示例此前写 #v1.7.13，这个 tag 不存在，照抄会安装失败；已改为 #v1.7.14，audit 会检查文档引用的 tag 是否存在
• 发版脚本：npm version 同步了 .kimi-plugin/plugin.json 的版本号，但没把它加入提交

🌐 官网 Copy Section

• 繁体界面的分类标签与简介修正；skill 数、工具数、中国原创数改为构建时自动生成
• 404 页的样式此前被 CSP 拦截而错位，已修复，并加上英文与繁体提示
• 首页发布提示条此前一直显示 v1.7.12 的内容，已更正，并改为发版时必须同步更新（否则构建失败）
• FAQ 补充：各安装方式（npx 项目级 / 全局 / Claude Code 插件市场）的更新与卸载、装完怎么确认生效、没生效怎么排查
• skill 详情页：<HARD-GATE> 等标签块此前结构错误（结束标签落进段落，后面整页被嵌进去），现在显示为带标签名的提示框，<Good>/`` 正反例分别标绿、标红
• 浅色主题：代码块文字此前几乎看不见（对比度 1.33:1），链接、行内代码、标签、页脚文字也偏淡，已全部调到 4.5:1 以上
• 手机端：此前 320px 宽度下 16 个页面需要横向滑动，现在全部 70 个页面都不会

📦 包体积 Copy Section

删除 5 张已无引用的赞助商图片，Sidrune 横幅从 924 KB 压到 19 KB（显示效果不变）。

v1.7.14 (2026-09-26) Copy Chapter

同步上游 v6.4.2（含 v6.4.1），OpenCode 用户尤其建议更新。 对应 #133、#131。

✨ 新 skill：diagnosing-superpowers（第 21 个） Copy Section

会话跑偏时——重复劳动、无视计划、太慢、太贵、某个技能没触发——让它读磁盘上的会话记录，按 7 个维度并行分析，出一份每条结论都带 path:line 的报告；需要时整理成 issue、打包脱敏材料。它只报告发生了什么，不替你诊断 skill 本身。

与上游唯一的有意偏离：issue 目标是本仓 jnMetaCode/superpowers-zh，不是 obra/superpowers——你跑的是译文，问题先在这里分流，确认是上游行为再转报。

🔁 executing-plans 重写：内联执行 Copy Section

从「单独会话 + 检查点」改成在当前会话里自己当实现者：task-start 取简报和 BASE，task-done 跑测试、只有通过才记账本，最后派一个最强模型做整分支审查。与 SDD 共用工作区和账本，中途可以换执行方式。遇到计划缺陷自己裁决并记账，只有 4 类硬停止。

旧版里本 fork 自加的「常见异常处理」（计划有误就停下问）与此直接冲突，已删除。

✂️ writing-plans：更短的计划 Copy Section

• 步骤只写实现者无法自己决定的东西：签名、文件、规格取值、测试断言；函数体由实现者写
• 新增「审查重点」：规格隐含、但没有测试覆盖的 5 个最可能伤人的输入，交给最终审查逐条检查
• 自检新增「比例」：计划比规格长好几倍，就是把程序抄了一遍
• 执行交接改为「子代理驱动 / 原生执行」二选一，并要求先审阅计划

其他上游变更 Copy Section

• brainstorming：「建立共同理解」——先弄清意图并写回给你确认；HARD-GATE 按路径细分（架构级：设计批准只许写规格，规格批准只许写计划）
• code-reviewer：规格是愿景文档，规格没提的行为按正常人的期待来判；列出「不予判断的项」交执行者裁决
• TDD：宣称完成前跑整个项目测试套件，看到的失败必须写进报告
• SDD：sdd-workspace 解决同名计划（docs/a/plan.md vs docs/b/plan.md）共用工作区的问题；review-package 拒绝空区间和非后代 HEAD
• 技能自带脚本一律经解释器调用（bash scripts/…）——有些插件打包器会去掉可执行位
• 新增 Claude Code、Muse 工具参考；SessionStart hook 支持 Muse

🐛 OpenCode 工具映射过期（#131） Copy Section

插件还停在 v5.0.7：告诉模型用 @mention 派子代理——那是 TUI 里用户的输入方式，模型没有这个工具。现已换成上游 v6.4.2 插件：V1 映射到 task + subagent_type，V2（OpenCode 2.0.4+）映射到 subagent，并通过 setup() 原生注册 skill；新增根目录 index.js 供 V2 目录形式加载。安装文档同步更新。

🐛 visual-companion.md 一直是旧版 Copy Section

中文版比 v6.3.0 还旧：教你读 $SCREEN_DIR/.server-info，而实际脚本写的是 $STATE_DIR/server-info；缺 --open、会话 key、4 小时空闲超时等说明。标题数没变，所以 audit 看不出来。已整篇按上游重译。

已知问题（上游未修，原样同步） Copy Section

• task-done 在测试命令完全没有输出时会误判失败（上游 #2385）
• task-done 账本记的是日志最后一行，node --test 会记成 # duration_ms …（上游 #2342）

v1.7.13 (2026-09-08) Copy Chapter

只有 TRAE 国内版用户需要更新。 处理 #35 时发现 Trae 此前完全没有全局安装，而国内版的全局目录还跟国际版不同构。

🐛 TRAE CN 全局目录是 `~/.trae-cn/skills`，不是 `~/.trae/skills` Copy Section

TRAE CN 官方文档「技能所在目录」：

全局是 .trae-cn，差一个后缀就是又一次「装了 20 个文件、工具一个都不读」。而国际版文档没有给出全局路径 —— 按本仓一贯口径不猜，所以国际版不做全局。

npx superpowers-zh --tool trae             # 项目级，两版通用（.trae/skills/）
npx superpowers-zh --global --tool traecn  # 全局，仅国内版（~/.trae-cn/skills/）

别名 traecn / trae-cn / trae-china。%userprofile% 就是主目录，两平台在「主目录下的 .trae-cn/skills」这点上同构，不需要 dirWin。

为什么单独成一条而不是挂到 Trae 上：挂上去，国际版用户跑 --global --tool trae 就会装进一个 TRAE 根本不扫的目录 —— 正是这个 issue 想避免的事。项目级两版同构，仍由 --tool trae 一条覆盖。

🐛 拒绝文案说了假话 Copy Section

全局-only 工具的项目级拒绝此前是一段写死的通用文案，内容是 ZCode 的情况（「项目级导入是应用内 UI 动作、不暴露磁盘路径」）。这对 TRAE CN 是假的 —— 它的项目级路径文档写得清清楚楚。

改成按工具可覆盖，TRAE CN 现在说的是真实原因：

❌ TRAE CN 不支持项目级安装。

  TRAE CN 的项目级技能目录与国际版 TRAE 相同（.trae/skills/），
  已经由 Trae 这一条覆盖，请直接用：
    npx superpowers-zh --tool trae
  本条目只用于 TRAE CN 独有的**全局**目录（~/.trae-cn/skills）。

🧮 工具数仍是 26，不是 27 Copy Section

TRAE CN 在安装器里占一条，但它是同一个 IDE 的国内发行版，单独成条只为承载独有的全局路径。计进产品数就是灌水，站点工具墙还会出现两张同名 Trae 卡片让人不知道点哪个。

新增 editionOf 标记，audit 的计数口径把这类条目排掉 —— 这是 Copilot CLI 那条例外（共用 .claude/skills 但单独计数）的镜像另一半。

🛡️ 门禁自己的两个 bug Copy Section

加 UA 不是放宽判活口径：400 仍算死链，只是不再因为「对方不接待 curl」而误判。往文档里塞一条 reasonix.io 的真 404 做负向测试，照样被抓。

另外补了一条 dot 流程图门禁：graphviz 遇到「边引用了未声明的节点」不报错、只会静默新建一个孤儿框。同步上游 v6.3.0 时改了 SDD 流程图的节点文案，正是这个场景。

audit 163 pass / 0 warn，verify-release 163 → 164 pass。

v1.7.12 (2026-09-07) Copy Chapter

通过 Claude Code 插件市场安装的用户请更新。 本版修的是一个「装了，但技能之间互相调不动」的问题，
并新增三款工具支持：ZCode（智谱）、DeepSeek Harness 与 Reasonix，工具数 23 → 26。

🐛 插件模式下跨技能调用全部失败（[#116 之外最实的一条：#124](https://github.com/jnMetaCode/superpowers-zh/issues/124)） Copy Section

报告人给的证据完整到可以直接复现（v1.7.10 / 插件市场安装 / Windows）：

Skill("superpowers:systematic-debugging")     -> Unknown skill
Skill("superpowers-zh:systematic-debugging")  -> 正常加载

Claude Code 按「<插件名>:<技能名>」注册插件技能，而本插件在
.claude-plugin/plugin.json 里叫 superpowers-zh。可我们的 skill 正文里照抄了上游的
superpowers: 前缀 —— 实测全仓 superpowers-zh: 0 处、superpowers: 32 处，
分布在 11 个文件。凡是 skill A 让你去用 skill B 的地方，插件用户都会撞上 Unknown skill。

但没有按报告里建议的换成 superpowers-zh:。 本 fork 有两条分发路径，命名空间不同：

证据是安装器自己生成的 bootstrap —— 它列的就是裸名。也就是说那 32 处在两种模式下
都是错的；只改成 superpowers-zh: 等于修好插件模式、又给主分发路径挖一个反向的坑。

改成裸技能名：npx 模式直接正确；插件模式下模型按后缀匹配得到
superpowers-zh:xxx，而不是照着一个确定不存在的全限定名去调。

另有 1 处特例：copilot-tools.md 里那句是举例说明「插件智能体」的命名形式，且
code-reviewer 在本 fork 根本不是技能，改成通用写法 <插件名>:<智能体名>。

🐛 Crush 在 Windows 上装到了它不扫描的目录 Copy Section

Crush README 的 Agent Skills 一节写明
Windows 走 %LOCALAPPDATA%\crush\skills\（它给 Windows 用户的上手命令就是
mkdir "$env:LOCALAPPDATA\crush\skills"），而我们两个平台都装 ~/.config/crush/skills。

而我们自己的 docs/README.crush.md 早就写对了 —— 又一次「文档描述的是意图，
代码做的是另一回事」，与 v1.7.10 修 Aider 时同一句话。

global 支持可选的 dirWin，按平台选路。OpenCode 的 .config/ 没动：其官方文档
没有任何 Windows 专属说明，没证据就不猜路径。

🐛 render-graphs.js：取上游的两处修复，但不跟它改 ESM Copy Section

上游 v6.3.0 改了三处，我们只取两处：

实测（--no-experimental-detect-command 模拟 Node 20）：上游版报
To load an ES module, set "type": "module" + SyntaxError，我们改后版本正常执行。

🔄 对齐上游 v6.3.0：13 个镜像文件、+415 / -44 行正文 Copy Section

旧门禁对已翻译的文件只比「标题数」—— 标题不变，正文改多少行都看不见。上游 v6.3.0
给 skill 正文加了 415 行，我们这边一声不吭。这一版补了基线文件
.upstream-sync.json 之后，第一次量出了这个缺口，并分四批补完：

其中 SDD 那条是行为塑造上最实的一处改动。旧版本里，控制者一遇到「审查发现」与
「计划原文」冲突就停下来问人类伙伴；v6.3.0 改成由控制者自己裁决，每条裁决以
Ruling: <决定> — <为什么> — <错了的代价> 记进账本，收尾时汇总成「我作出的裁决」
交回来。只留四类硬停止：不可逆或破坏性操作、涉及安全的动作、工作树之外按惯例
该先问一声的副作用（合并 / 推送共享分支 / 发布）、以及坏到每条路都只能靠猜的计划。
理由是上游写在正文里的一句话：一个错误的裁决，代价是看得见也撤得掉的返工；
一个停在问题上的会话，代价是一整天，而且什么也换不来。

配套的流程图节点也跟着改了（「询问人类伙伴以哪个为准」→「对冲突作出裁决，把裁决
记进账本」），预检扫描的产出从一句结论改成一张必须逐行填的表。

唯一有意不同步的是 writing-skills/render-graphs.js 的 CJS → ESM，理由见上一节。
这条分歧写进了 .upstream-sync.json 的 evidence 字段，免得下次同步时被当成遗漏又"修"一遍。

🆕 新增 ZCode（智谱）支持 —— 只做全局，因为项目级路径官方从未公开（[#95](https://github.com/jnMetaCode/superpowers-zh/issues/95) [#120](https://github.com/jnMetaCode/superpowers-zh/issues/120)） Copy Section

npx superpowers-zh --global --tool zcode     # -> ~/.zcode/skills/

#120 附了一份完整补丁，写着装到
.zcode/skills + 写 .zcode/AGENTS.md。没有采纳 —— 提交者自己写明那是「让 AI 按
zcode 的目录结构适配」生成的，而官方文档里查无此路径。

ZCode 官方技能文档（中英文版一致）只给出一个磁盘路径：

ZCode Agent 的用户级技能目录：~/.zcode/skills/<skill-name>/SKILL.md

项目级在文档里是应用内的 UI 导入动作（设置 → 技能 → 导入，可选「链接到来源目录」或
「复制成 ZCode 内部副本」，导入目标可选「全局」或「当前项目」），从不暴露项目级磁盘
路径。.zcode/AGENTS.md 同样查无实据 —— AGENTS.md 在 ZCode 里确实是六类扩展之一，
但位置与作用域文档页没写明。

所以项目级安装被明确拒绝（退出码 1、项目里零写入），并指向 --global：

❌ ZCode 不支持项目级安装。
  其官方文档只给出用户级技能目录，项目级导入是应用内的 UI 动作、不暴露磁盘路径。
  猜一个路径装进去只会「装了不生效」，所以这里直接拒绝。

猜路径的代价这仓已经付过三次（Codex 项目级、Windsurf 全局、VS Code），这次不付第四次。

技能装好后在 ZCode 里用 $skill-name 调用（设置 → 技能 里可查看与启停）。因为不写
bootstrap，不会自动触发，需要显式调用 —— 这个限制写在 docs/README.zcode.md 里。
若你查到 ZCode 的项目级路径或 AGENTS.md 的确切位置，欢迎开 issue，我们会补上。

工具数 23 → 24，支持全局安装的工具 11 → 12。

🆕 新增 DeepSeek Harness（dsh）支持（[#122](https://github.com/jnMetaCode/superpowers-zh/issues/122)） Copy Section

npx superpowers-zh                          # 自动检测 .dsh/
npx superpowers-zh --global --tool dsh      # -> ~/.dsh/skills/ + ~/.dsh/AGENTS.md

与 ZCode 相反，这款四条路径全部有一手出处，所以项目级与全局都支持：

装过 Antigravity 或 Codex 的项目其实已经被覆盖一半：dsh 的技能发现 rank 200 是
.agents/skills，正是那两款用的目录。文档里写明了别重复装。同理 dsh 也读 CLAUDE.md，
装过 Claude Code 的项目引导那半已生效 —— 但 .claude/skills 不在 dsh 的技能根列表里，
技能仍需单独装。

🆕 新增 Reasonix 支持（[#42](https://github.com/jnMetaCode/superpowers-zh/issues/42)） Copy Section

npx superpowers-zh                           # 自动检测 .reasonix/ 或 reasonix.toml
npx superpowers-zh --global --tool reasonix

Reasonix（esengine/DeepSeek-Reasonix）是 DeepSeek 原生的终端 coding
agent。#42 的 issue 模板整个没填，但产品是真实存在的，官方文档也齐全：

Windows 路径走上一版为 Crush 加的 dirWin 机制。全局安装不写引导文件：官方说
「用户全局文件先加载」但没写明那个文件的确切路径，不确认就不写 —— 全局仍装 skills，
只是不自动触发，想要自动触发用项目级安装。

🐛 在管理员 PowerShell 里跑，会把 skills 装进 C:\Windows\System32（[#125](https://github.com/jnMetaCode/superpowers-zh/issues/125)） Copy Section

issue 正文只有一张截图、模板全空。但那张截图把事情说清楚了：

PS C:\Windows\system32> npx superpowers-zh --tool trae
  模式: 项目级
  目标: C:\Windows\System32
  ✅ Trae [项目]: 20 个 skills -> C:\Windows\System32\.trae\skills
  ✅ Trae: bootstrap rule -> C:\Windows\System32\.trae\rules\superpowers-zh.md

管理员权限打开的 PowerShell，默认工作目录就是 C:\Windows\System32。 用户在那里
直接跑 npx，我们就老老实实把 20 个 skill 目录写进了 Windows 系统目录。

我们本来就有「拒绝装进用户主目录」的护栏（--force 可绕过），却从没拦过系统目录。
现在补上，且不提供 --force 绕过 —— 装到系统目录没有任何正当用途，给个开关只会
让人照着开关走。

⚠️  当前目录是系统目录: C:\Windows\System32
  常见原因：**用管理员权限打开的 PowerShell / cmd，默认工作目录就是
  C:\Windows\System32**，直接在里面跑 npx 就会装到这里（issue #125）。
  正确做法 —— 先切到你的项目目录： cd D:\path\to\your\project

覆盖 Windows（%SystemRoot%、%ProgramFiles%、%ProgramData%、盘符根）与
Unix（/、/usr、/etc、/bin、/sbin、/var、/opt、/System、/Library）。
主目录与系统临时目录豁免（各有自己的处理）。

关于截图里那个「检测到当前版本文件损坏」弹窗：那是 TRAE 自己的完整性检查提示，
我们没有证据表明它是本次安装导致的，所以不宣称因果。能确认并已修的是：
我们不该往系统目录写东西。

🛡️ 这一版新增 / 修好的门禁 Copy Section

每条都做过反向验证（把问题造回去，必须报错）：

verify-release 115 → 163 pass，audit 162 pass / 0 warn。

🌐 官网（不影响安装包） Copy Section

本版官网侧改动较多，逐条见提交历史：版本提示条（此前站上对「谁该重装」零表述）、
22 份工具文档入口、JSON-LD 结构化数据、1200×630 分享大图、可访问性修复
（57 个页面两个 h1 / 搜索框焦点被抹掉 / 全站无 skip link）、sitemap 的 lastmod
不再谎报「今天改的」、抖音二维码 177 KB → 31 KB。

v1.7.11 (2026-08-28) Copy Chapter

Codex CLI / VS Code / Windsurf / Qwen Code / DeerFlow / Claw Code 用户请重新安装。

v1.7.10 那次核查查出三款装错，当时的结论是「既然错过一次，就该问一句还有几个」。这一版把剩下没查过的全部查完了 —— 逐款对官方文档（拿不到文档的对源码），一款一款过。

结果：又是四款「装了完全不生效」。都是我们自己写的路径，都没查过官方文档。

🐛 Codex CLI：项目级装到了 Codex 从不扫描的目录 Copy Section

官方 skills 文档给出的扫描目录完整清单：

$CWD/.agents/skills、$CWD/../.agents/skills、$REPO_ROOT/.agents/skills
$HOME/.agents/skills、/etc/codex/skills、内置 skill

没有 .codex/skills。 而我们项目级正是装到那里。

讽刺的是全局（~/.agents/skills）一直是对的，原注释还专门写明「不是 ~/.codex/skills」—— 说明当初查过全局，却没顺手核一下项目级。

已改为 .agents/skills，并在安装时清理旧位置（只清我们装的，用户自己放在 .codex/skills 下的不动，已实测）。与 Antigravity 共用 .agents/skills 是 Agent Skills 开放约定，不是冲突。

这个改动还牵出一个既有 bug：自动检测有顺序依赖。 检测原来是边装边判的 —— Codex 装完会创建 .agents/，循环走到 Antigravity（detect: '.agents'）时它就被误判成「项目里有这个工具」，于是多装一份。任何「装了 A 会创建 B 的检测标记」的组合都会中招。改为先把所有工具的检测结果一次算完再开始装：检测必须基于安装前的项目状态。

🐛 VS Code (Copilot)：装的 20 个文件，Copilot 一个都不读 Copy Section

官方文档明确 Copilot 只自动读这几处：

.github/copilot-instructions.md / AGENTS.md / CLAUDE.md   （始终生效）
.github/instructions/*.instructions.md                    （按 applyTo 匹配）

我们把 20 个 skill 拷进 .github/superpowers/ —— 不在其中，而且装完什么引导都不写。

旧文档更说明问题：它写着「建议你创建 .github/copilot-instructions.md 引用这些 skills」并给了示例 —— 我们知道需要引导，却让用户自己动手，而绝大多数人不会照做。

现在自动生成 .github/instructions/superpowers-zh.instructions.md（applyTo: "**"，约 4.5 KB 的索引），正文仍留在 .github/superpowers/ 按需读取 —— 与 Cline / Kilo / Kiro 同一套「常驻只放索引」的思路。刻意不动用户的 copilot-instructions.md，那是他们的文件。

🐛 Windsurf：`--global` 装在 Windsurf 不读的地方 Copy Section

官方文档写明两个路径不同构：

测试为什么没抓到：只验退出码，不验落盘位置。 装到错目录退出码照样是 0 —— 「跑通了」不等于「装对了」。已补 GLOBAL_DIR 断言：每款全局工具逐个断言 skill 真落在官方读的那个目录，外加一条自检（以后加全局工具不能漏断言）。双向验证过：把路径改回旧值立刻报错。

🐛 DeerFlow：检测标记根本不存在（Aider 同款） Copy Section

安装路径 skills/custom/ 是对的（官方文档确认自动扫描 ["skills/public", "skills/custom"] 两个写死的目录）。但 detect 写的是 deer_flow —— 用 GitHub API 列了 deer-flow main 分支顶层目录：

.agent .github backend contracts deploy docker docs frontend plans
pr-build scripts skills tests

没有 deer_flow。 与 Aider 的 .aider 是同一个毛病：真实检出从来没被自动检测到过。改认 skills/public（skills 机制本身、随仓库版本控制，任何检出都有），deer_flow 保留作 1.x 兼容。

顺带删掉文档里那段 export DEERFLOW_SKILLS_DIR=... —— 官方文档里没有这个环境变量，目录是写死的。

🐛 Qwen Code：缺 bootstrap（skill 是死重）+ 我们把产品搞混了 Copy Section

路径是对的，但两个问题：

① 产品搞混。 文档标题写「Qwen Code (通义灵码)」、链接指向 tongyi.aliyun.com。实际 Qwen Code 是 QwenLM/qwen-code 这个命令行工具（Gemini CLI 的 fork）；通义灵码是阿里的 IDE 插件，是另一个产品，路径完全不同 —— 照我们的文档去配通义灵码是配不通的。与 #119 的 Qoder 表是同一类错误：把两个产品面混成一份说明。

② 只装 skills、不写 bootstrap。 Claude 写 CLAUDE.md、Gemini 写 GEMINI.md，而 Qwen Code 的对应物 QWEN.md 我们完全没用。按上游的原则：没有 bootstrap，skill 就是死重 —— 文件在磁盘上但很少被调用。已补（项目级写 ./QWEN.md，全局写 ~/.qwen/QWEN.md，已有文件用哨兵注释追加而非覆盖），并补上全局卸载的残留缺口。

🆕 Claw Code：补 bootstrap + 补文档（23 款里唯一没有安装文档的一款） Copy Section

路径拿到了源码级证据（ultraworkers/claw-code 的 rust/crates/plugins/src/lib.rs 明写发现 .claw/skills、.omc/skills、.agents/skills；USAGE.md 列出指令文件优先级 CLAUDE.md > CLAW.md > AGENTS.md）。补上 CLAW.md bootstrap 与 docs/README.claw.md，并写明一条实用提醒：claw 也扫 .agents/skills，装过 Antigravity 的项目其实已经能读到，重复装会加载两份。

🆕 CodeBuddy / CodeArts 补 `--global`（全局支持 9 → 11 款） Copy Section

两款的用户级路径此前都写着「尚未验证」，现已拿到官方出处：

支持通用全局安装的工具由 9 款增至 11 款：Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts。

🐛 4 条死链，其中 2 条是编造出来的仓库地址 Copy Section

核查 OpenClaw 时发现文档链的是 github.com/anthropics/openclaw —— 那个仓库不存在。顺手全仓扫了一遍外链，45 条里 4 条是死的：

前两条是编造出来的出处。这比没有出处更坏：它让人以为核实过了。已固化成外链验活门禁（两遍制：并行快扫出嫌疑名单，再串行复核，两遍都判死才算死 —— 一个会误报的门禁比没有门禁更糟，人会学会忽略它）。

🌐 官网：工具墙停在 20 款，三处文案自己打自己 Copy Section

首页统计块写「20 支持工具」，同一屏的标题写「23 款工具通用」，FAQ 又枚举了 23 款。根因是文案计数跟着 installer 改到了 23，而 site/build.mjs 的工具数组从来没人补 —— Cline / Kilo Code / Crush 的用户在安装命令下拉里找不到自己的工具。

• 工具列表 20 → 23，统计块改成从列表长度算，不再硬编码
• 修 4 条错的：Claw Code 已能自动检出（不必再 --tool claw）、Hermes 改给 --global（项目级给了等于给「装了不生效」）、Qwen Code 类型 IDE → CLI、Antigravity 类型 CLI → IDE
• FAQ「支持全局」清单 7 → 11 款（三语同步）
• skill 详情页 6 条死链：SKILL.md 里指向兄弟文件的相对链接（implementer-prompt.md、../requesting-code-review/code-reviewer.md 等）站点上没有这些 .md，../ 开头的 404，其余被渲染器打成 href="#" —— 点了没反应，比 404 还难查。现在解析到 GitHub 源文件
• 新增赞助商独立页，导航栏补当前页高亮

🛡️ 测试与门禁 Copy Section

这一版查出的问题，旧门禁一个都发现不了。逐条补上，并全部做过反向验证（把问题造回去，必须报错）：

verify-release.sh 101 → 115 pass；audit.sh → 170 pass。

📋 这一轮六款，六种失效方式 Copy Section

共同点：全部是我们自己写的，全部没查过官方文档。 现在每条路径在代码注释里都带出处链接与核对结论 —— 下次改之前先看那行注释。

v1.7.10 (2026-08-12) Copy Chapter

Aider 和 Kiro 用户请重新安装。 本版本源于一次对「我们自己那层工具支持」的系统核查 —— 起因是 v1.7.9 修 Hermes 时发现：我们从支持它起就装错了目录。既然错过一次，就该问一句还有几个。

答案是：又查出三个，全部是我们自己写的、全部没查过官方文档。

🐛 Aider：两个错叠在一起，等于完全不可用 Copy Section

① 真实的 Aider 项目从来没被自动检测到过。

检测标记写的是 .aider，即要求存在一个 .aider/ 目录 —— 而 Aider 根本不创建这个目录。它在项目根留下的是 .aider. 前缀的产物：.aider.conf.yml、.aider.chat.history.md、.aider.tags.cache.v3/。

实测：造一个含这三样的真实 Aider 项目跑 npx superpowers-zh，输出「未检测到任何已知 AI 编程工具」。而文档一直写着「会自动检测 .aider.conf.yml 文件」—— 文档描述的是意图，代码做的是另一回事。

已改为认这四个标记。

② CONVENTIONS.md 不会被 Aider 自动加载。

代码注释和文档都断言「Aider 原生支持自动加载此文件」。官方文档说的是反的：必须 aider --read CONVENTIONS.md，或在 .aider.conf.yml 里写 read: CONVENTIONS.md。

最糟的是文档「Skills 未生效」排障的第 3 条写着「Aider 会自动读取 CONVENTIONS.md，无需额外配置」—— 用户卡住时来查文档，看到的正好是让他继续卡住的那句。

改法照搬 v1.7.9 的 Hermes：装完打印可直接用的两种激活方式，不替用户改 .aider.conf.yml（那是他们的文件）。

🐛 Kiro：错的方向正好相反 —— 每一轮烧 335 KB Copy Section

Kiro 官方文档明确：.kiro/steering/ 下的文件默认就是 inclusion: always，"loaded into every Kiro interaction automatically"。

而我们把 20 个 skill 的正文整个装了进去。实测 47 个 md、335 KB，每一轮对话全量进上下文。

讽刺的是这个问题我们早解过 —— 当初给 Cline / Kilo Code 做适配时专门设计了「常驻位置只放索引、正文按需读取」（那次是 182 KB）。只是没意识到 Kiro 的 steering 是同一性质。现在照搬：

76 倍。 升级路径是这次最要紧的一块：老用户通常直接重装而不会先卸载，不清旧布局的话新旧两份并存、335 KB 一点没减 —— 那就等于没修。所以安装时先清 .kiro/steering/ 下与我们 skill 同名的目录，并打印清理了几个。你自己写的 steering 文件不会被动，已实测。

另外文档里写的加载模式 alwaysApply: true / globs: "*.ts" —— 这两个键 Kiro 文档里根本不存在，是 Cursor / Trae 的约定被误写成了 Kiro 的。Kiro 实际用 inclusion / fileMatchPattern。已按官方文档重写整篇。

🐛 Qoder：工具映射表是编的（[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119)） Copy Section

报告人说 Qoder IDE 里没有 general-purpose 子智能体，而我们的 qoder-tools.md 白纸黑字写着有。查该文件的引入 commit —— 没有引用任何来源。

对照 Qoder 官方子代理文档，4 行错了 2 行：Explore → explore-agent、Plan → plan-agent 都是错的，文档里就是同名；「Qoder 有内置 code-reviewer」也是编的（文档里的 api-reviewer 是用户自建示例）。

但最关键的不是这几行 —— 那张表根本没标适用范围。官方文档只覆盖 Qoder CLI，报告人用的是 Qoder IDE，两个产品面本来就不同，而我们的表让 IDE 用户当成了权威。已补适用范围、来源链接、核对日期，和一节 IDE/CLI 差异说明。

🛡️ 把「拿代码测代码」的盲区堵上 Copy Section

Aider 那个 bug 能在 90 项全绿的情况下活下来，是因为测试写的是 mkdir .aider 然后断言认出 Aider —— 拿代码测代码，真实标记一个都没测。

已补：

• Aider 的三个真实标记进检测测试；case 分支加 *.yml（.aider.conf.yml 是文件不是目录，用目录冒充等于测了个假场景）
• Kiro 两条硬回归守卫：steering 下只能有 1 个 md、常驻总字节 < 20 KB；外加升级路径断言（旧布局必须清掉、用户文件必须保留）。双向验证过 —— 模拟退回旧布局，两条断言都会失败

verify-release.sh 90 → 101 pass。

📋 四个工具，四种失效方式 Copy Section

四个都是我们自己那层写的，四个都没查官方文档。 这已经不是个案。剩余工具的核查还在继续，会在后续版本陆续修。

✅ 发版前门禁 Copy Section

• audit.sh 166 pass / 0 warn / 0 fail
• verify-release.sh 101 pass / 0 fail

v1.7.9 (2026-08-11) Copy Chapter

如果你在用 Hermes Agent，请重新安装。 本版本之前我们对 Hermes 的支持是坏的 —— 不是"不好用"，是装完完全不生效。

🐛 Hermes：我们一直装错了目录（[#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)） Copy Section

报告人说「项目级 .hermes/skills/ 里的 20 个 skill 全部返回 404，必须手动复制到 ~/.hermes/skills/ 才被识别」。查官方文档核实，他是对的：

Hermes 只自动加载 ~/.hermes/skills/（原文称其为 "the primary directory and source of truth"），项目级目录不会被自动发现；外部目录必须写进 ~/.hermes/config.yaml 的 skills.external_dirs。

而我们从支持 Hermes 起就只装项目级 .hermes/skills/ —— 那个目录 Hermes 根本不读。装了 20 个 skill，一个都不生效，比不支持更糟：用户以为装好了。

改法：

• 全局成为推荐装法 —— npx superpowers-zh --global --tool hermes 装到 ~/.hermes/skills/，装完即生效，skills_list 直接能看到 20 个 skill

• 项目级保留（skills 可以随仓库分发），但装完打印可直接粘贴的配置片段，带绝对路径：

  yaml Copy

  skills:
    external_dirs:
      - /your/project/.hermes/skills

  我们不替你改 config.yaml —— 那是你的文件。文档里特意写明「配置里不存在的路径会被静默跳过」，所以写错不会报错、只会"没生效"，这个坑值得先说。

过程中拦住了一次自己猜路径： 第一版全局实现把 HERMES.md 引导文件写到了 $HOME 根目录。Hermes 的用户级指令文件约定没有公开文档 —— 那是在猜路径 + 污染用户主目录。已改为全局模式不写 bootstrap，并在文档里说明理由。实测：全局装完 $HOME 根目录 0 个新文件、卸载 0 残留。

🔧 发版工具：`bump-version.sh` 缺 jq 时会静默改错 Copy Section

本次发版时踩到：机器上没有 jq，脚本不报错退出，而是每个文件打一行 command not found 后继续往下跑，最后以 unbound variable 收场 —— 版本号一个都没写进去，但输出里混着 "Done."。已加前置检查：缺 jq 直接退出并给出安装命令。

ℹ️ #45 的后半部分未动（说明理由） Copy Section

#45 还提到 7 个 skill 文件里有 24 处硬编码的 Claude 工具名（TodoWrite / Read / Bash 等）。本次不动，理由：那属于行为塑造内容，且 references/hermes-tools.md 已有完整映射表。正确解法是强化「查映射表」的引用，而不是把正文改成某个 harness 专属的工具名 —— 那会伤到其余 22 款工具。

✅ 发版前门禁 Copy Section

• audit.sh 166 pass / 0 warn / 0 fail
• verify-release.sh 90 pass / 0 fail（--global 支持清单 6 → 7 款，新增 hermes）

v1.7.8 (2026-08-08) Copy Chapter

本版本源于一次定位核查：按「superpowers-zh 只是完整翻译上游 + 增加更多工具支持」这个定位，逐层比对我们与 obra/superpowers 的差异。结论是定位基本站得住，但不完全 —— 查出 5 处偏离，全部修掉。

🔍 核查方法 Copy Section

1. 文件级：上游 skills/ 与我们逐文件比对，分出「仅上游有」「仅我们有」
2. 内容级：14 个翻译 skill 各自比对标题数（排除代码围栏）、表格行数、列表项数
3. 溯源：每处差异追查来源 —— 是声明过的 fork 增量，还是漏译／漏同步

🐛 修掉的 5 处偏离 Copy Section

① antigravity-tools.md 上游有、我们没有

而 installer 里明明支持 Antigravity —— 该工具用户拿不到任何工具映射。影响是实质的：Antigravity 没有 todo 工具（manage_task 管的是后台进程），没这份映射，所有说「创建待办」的 skill 在它上面都会走偏。已翻译补入，并按上游同序列入平台适配清单。

② finishing-a-development-branch 漏同步 3 个 commit

C 块时的 commit 清单不全，漏了 fbb6dba / bcfe798 / 9dff1a9。其中 9dff1a9 是行为变更：上游把菜单从 4 个选项减为 3 个，删掉了「丢弃这份工作」，丢弃改为只在人类伙伴明确提出时才走的独立小节；基础分支判定也从盲跑 merge-base 改为「先确认，合并到错分支代价很高」。已照上游当前状态整体重译（一次拿到全部 4 个 commit），并断言 D 块的 worktree 修复完整保留。

③ writing-plans 漏译整节 —— 上游的 Task Right-Sizing（任务边界怎么划）我们完全没有。

④ writing-skills 四个问题 —— 漏译 H2 整节 Match the Form to the Failure（含「禁令在塑形类问题上会反噬」的实测结论）、漏译 H3 Micro-Test Wording Before Full Scenarios、两个连续小节都编号为 4、节名仍是过时的「Claude 搜索优化（CSO）」（上游早已改名 SDO），正文两处引用一并同步。

⑤ fork 增量插在了上游步骤序列中间

executing-plans 把「处理常见异常」插成步骤 3，于是上游的 Step 3: Complete Development 被挤成我们的「步骤 4」；Remember 也从上游的 6 条被加到 7 条。这不是「不影响上游」，是改了上游的结构编号。

改为外挂式：增量移出步骤序列、挂在「何时停下来求助」之后（它本就是那节三种情形的展开），步骤编号恢复 1/2/3，Remember 恢复 6 条。

🛡️ 让「不影响上游」成为可执行的检查 Copy Section

README 声明会漂移，所以新增 audit 3c-bis：

翻译 skill 的标题数必须等于「上游标题数 + 本文件里带标注的增量节数」

增量节靠正文里一行标注声明（本节是 superpowers-zh 的增量内容），标注与内容同处一文件、不会各自漂移。未标注就多出章节 = 隐性分叉，直接 FAIL。 已双向验证：偷偷加一节会被拦下并给出可操作提示，加标注后放行。

目前全仓仅 2 处带标注的增量：executing-plans 的「常见异常处理」、using-superpowers 的「中国特色技能路由」。

🐛 修掉一个让守卫从未生效的 bug Copy Section

3c-bis 第一次测试没拦住。查出原因：grep -c 匹配到 0 个时输出 "0" 但退出码为 1，写成 $(grep -c ... || echo 0) 会拼出 "0\n0"，后续整数比较直接报错、检查静默失效。改用 ; true 只吞退出码。

全仓扫同一模式，测试辅助里也有 3 处（上游同样有）：test-helpers.sh 的 assert_count、test-subagent-driven-development-integration.sh 的 task_count / todo_count。后果是这些断言永远无法正常失败 —— 模式没匹配到时比较报错而非判定失败。三处一并修掉并加注释。（tests/ 不进 npm 包，仅开发使用。）

修复后 audit 由 154 升到 166 pass —— 因为 3c-bis 现在真的对 14 个 skill 都跑了。

✅ 核查后的定位现状 Copy Section

纯增量部分（符合定位）：

• 6 个 fork 专属 skill：chinese-* ×4 + mcp-builder + workflow-runner
• 3 个 fork 专属 references：copilot / hermes / qoder（我们支持、上游不支持或已删的 harness）
• 2 处带标注的翻译 skill 内增量

14 个翻译 skill 的上游各节现已全部逐节对应。

scripts/audit.sh 166 pass / 0 warn / 0 fail、scripts/verify-release.sh 90 pass / 0 fail。

v1.7.7 (2026-08-08) Copy Chapter

🆕 新增 Crush 适配（工具数 22 → 23，关 #40） Copy Section

查权威源（charmbracelet/crush repo 文档）确认：Crush 遵循 Agent Skills 开放标准，项目级自动发现四个目录，无需任何配置：

.crush/skills    .agents/skills    .claude/skills    .cursor/skills

用户级为 ~/.config/crush/skills，因此支持 --global。

⚠️ 一个重要副作用： 已经为 Claude Code / Cursor / Codex / Antigravity 装过 superpowers-zh 的用户，Crush 现在就已经能读到那些 skills —— 此时不要再装 --tool crush，否则同一批 skills 会有两份被重复加载。docs/README.crush.md 里给了确认命令。

skills-only 适配，不需要 bootstrap；不动你的 crush.json（四个自动发现目录已够用）。实测：装 20 skills / 二次装幂等 / 卸载零残留且正确保留用户的 crush.json；--global 装到 ~/.config/crush/skills 并可干净卸载。

🎯 上个版本新加的计数检查，第一次在真实改动里生效 Copy Section

加 Crush 时漏改了 site/build.mjs 的 5 处计数（三语言标语 + FAQ 枚举）。v1.7.3 引入的 audit Category 5 直接 FAIL 拦下：

❌ 计数不一致: site/build.mjs「官网简体标语」= 22，应为 23
❌ 计数不一致: site/build.mjs「官网 FAQ 枚举」= 22，应为 23
... 共 5 条

已补 site 18 处并重建，三语言首页 23 计数、0 残留、Crush 均已出现。

🔧 `verify-release.sh` 有同样的漂移问题，已修 Copy Section

它有自己独立的覆盖清单 —— 加新工具时不进去就静默不测。本次 Crush 就是这样：分数仍是 82，因为压根没测它。

• SPEC / DETECT / GLOBAL_OK 三处补 Crush
• 顺带发现 B 段还漏了 3 个工具的检测标记：DeerFlow（deer_flow）、VS Code（.github/copilot-instructions.md）、Gemini CLI（GEMINI.md）—— 后两个是文件而非目录，原先的 DETECT 循环一律 mkdir，现按扩展名区分创建方式
• 新增 G 段自检：SPEC 覆盖数必须等于 installer 宣称的工具数；DETECT 覆盖的工具名集合必须包含全部 TARGETS 名字（用集合比对而非数条数 —— 一个工具可以有多个检测标记，数数会误判）

覆盖从 82 项升到 90 项。

✅ 验证 Copy Section

scripts/audit.sh 152 pass / 0 warn / 0 fail、scripts/verify-release.sh 90 pass / 0 fail。

v1.7.6 (2026-08-08) Copy Chapter

上游 v6.2.0 对齐完成 —— #19 的 C 块收尾，scripts/audit.sh 的上游结构漂移告警清零。

🧾 盘点先行：其中 3 项不是风格性改动 Copy Section

C 块表面上是 14 个 refactor(skills) commit（"drop social proof"、"drop The Bottom Line"、"fold into rationalization table"），看着像上游在统一自己的文风。开工前做了逐 commit 盘点，判定标准定为**「删掉的文字里有没有别处没写的规则」**——结论纠正了原本的假设：

• cfb6281 新增了一张 rationalization 表（2 行全新规则），替换掉「与工作流的集成」那份清单
• 03147d2 给 executing-plans 加了「先确保隔离工作区」作为步骤 1（SDD 那一半已随 A 块完成）
• bc86802 把「常见错误」5 个小节 + 「红线」Never/Always 双清单压成 5 行表，规则一条不少——这也是此前唯一有客观漂移证据的 skill

✂️ 其余各项逐条核实后才删 Copy Section

✅ 验证 Copy Section

结构：10 个 skill 的 H2 数与上游逐一对齐（8 个完全相同、2 个差 1）；executing-plans / using-git-worktrees / requesting-code-review 的 superpowers: 引用集与上游完全一致。

行为 eval —— 两轮共 11 题全对。 专门考被删段落里的规则是否仍生效：原生 worktree 工具 vs git worktree add（答出「第一大错误」与「幽灵状态」）、跳过 check-ignore 的后果、目录名优先级、基线失败能否继续、能否无证据宣称完成、审查建议有疑问时该照做还是反驳、能否先打补丁再查根因、能否自己读 diff 代替派审查者（命中 cfb6281 新增表行）、方案里的「以后可能用得上」怎么处理（命中 YAGNI 新落点）。

回归：scripts/audit.sh 150 pass / 0 warn / 0 fail、scripts/verify-release.sh 82 pass / 0 fail。

audit PASS 由 152 降至 150 —— 上游有意删除的两个「集成」节里各有 superpowers: 引用，Category 4b 因此少 2 项检查；引用集已核对与上游一致。

v1.7.5 (2026-08-07) Copy Chapter

对齐上游 v6.2.0 的 B 块 + D 块（#19）。

🐛 worktree 清理静默空转（真 bug，我们与上游同样存在） Copy Section

finishing-a-development-branch 的步骤 6 在步骤 5 已经 cd 到主仓库根之后，才用 git rev-parse --show-toplevel 重算 WORKTREE_PATH —— 于是拿到主根路径，.worktrees/ 溯源判断永远匹配不上，清理静默空转，随后分支删除还会因为 worktree 仍挂着而失败。上游记录说测试对象不得不偏离 skill 原文才能跑通。

修法：步骤 2 趁还在工作区内就捕获，步骤 6 消费该值并加显式警告说明为何不能重算；去掉步骤 6 冗余的 MAIN_ROOT 推导与 cd；选项 2 补上菜单已声称的分离 HEAD 推送变体。

已实际复现验证（临时仓库 + .worktrees/feature）：旧逻辑算得 main → 溯源未命中 → 清理空转；新逻辑捕获到 main/.worktrees/feature → 命中 → worktree remove 与 branch -D 均成功。

🐛 我们把 Gemini 的子智能体支持写错了 Copy Section

gemini-tools.md 原文称 Gemini CLI 没有 Task 等价物、依赖子智能体的 skill「退化为 executing-plans 单会话执行」。这是错的 —— Gemini CLI 通过 invoke_agent（agent_name: "generalist"，也可用 @generalist 聊天语法）支持子智能体，且支持同一响应内多调用并行分派。

这个错误会让 Gemini CLI 用户的 subagent-driven-development / dispatching-parallel-agents / requesting-code-review 全部瘸腿。按上游重写（33 → 62 行），补齐指令文件层级加载、~/.gemini/skills 与 ~/.agents/skills 优先级、模板填写、并行分派，以及此前缺失的 20 个工具名。已全仓扫描确认无别处重复该说法。

🔄 `testing-anti-patterns.md` → `writing-good-tests.md` Copy Section

上游把 299 行的反模式枚举重写为 198 行的两条原则：

• 原则 1「点名它要抓的破坏」 —— 写测试体前先答"什么生产改动会让它失败，那是 bug 还是决定"。含镜像断言、变更探测器、测行为不测文本、测你的代码不测框架
• 原则 2「跑真东西」 —— mock 不配拥有断言、在正确层级 mock、替身要具体、完整镜像真实数据、生产类只承载生产方法
• 新增变异检查：收尾前在脑中变异生产代码，每种现实变异都应至少让一个测试失败
• 触发条件放宽到「编写或修改任何测试时」

TDD SKILL.md 同步：删掉「为什么顺序很重要」整节长散文（论点折进合理化借口表，5 行扩写）、删掉末尾已失效的「测试反模式」一节。

🔧 audit 结构漂移度量修正（此前一直在虚报欠账） Copy Section

audit.sh 用 grep -cE '^#{1,4} ' 数标题，但这会把 ``` 围栏内的 shell 注释（# 运行测试）当成 markdown 标题 —— 多几行 bash 注释就能凭空造出「结构漂移」。

用正确口径（awk 逐行跟踪围栏）重算 14 个 skill，3 条告警里 2 条是假阳性：

双向验证：给 brainstorming 加 5 个真标题会触发告警，加 5 行围栏内 shell 注释不触发。

✅ 验证 Copy Section

• 两个新/改文件章节均与上游一一对应；writing-good-tests.md 指标精确一致（12 bold 要点 / 11 行表格 / 11 条危险信号 / 14 项代码记号）
• 行为 eval 8 个判断场景：8/8 全对。附带一个有价值的对照：agent 拿不到 writing-good-tests.md、只能退回 SKILL.md 四条摘要时得分 6/8 —— 错的恰好是只存在于参考文件里的两条规则（部分 mock 静默失败、琐碎转发 getter 不配有测试）。说明参考文件承载着摘要覆盖不到的承重规则。
• scripts/audit.sh 152 pass / 1 warn / 0 fail（原 150/3）、scripts/verify-release.sh 82 pass / 0 fail

v1.7.4 (2026-08-07) Copy Chapter

🔄 SDD 同步上游 v6.2.0：plan 作用域工作区 + 基于唤回的修复循环（#19 A 块） Copy Section

对齐上游 subagent-driven-development 的 6 个 commit。这是 #19 拆分后的 A 块 —— 注意 v1.7.1 刚对齐过 SDD，本次是那之后的新增量。

为什么脚本与文档必须整块一起改： 我们的 SKILL.md 里写的是旧签名 review-package BASE HEAD。脚本换成 plan 作用域签名后若不同步改文档，agent 会照旧签名调用直接吃 usage 错误 —— 比不同步更糟。

plan 作用域工作区（结构性修复）

原先所有计划共用 .superpowers/sdd/ 一个目录，一份过期账本被误读成当前进度会让控制者跳过整段任务序列（上游称之为观察到的最昂贵失败）。现在每个计划一个 .superpowers/sdd/<计划文件名>/，从结构上消除误读。账本新增身份行 # SDD ledger — plan: <路径>。

• sdd-workspace / review-package 在我们这边与上游 v6.1.1 字节一致（从未汉化），直接取上游版
• task-brief 只手工应用上游那两处改动，保留 fork 适配（awk 同时匹配 Task N 与 任务 N，因为本仓库 writing-plans 产出中文标题）

SKILL.md 全面重写（平铺 14 节 → 生命周期结构）

• 修复循环：一轮 = 一次修复分派 + 一次定向复审，每任务上限五轮。第 1-3 轮唤回原实现者（context 完整），第 4-5 轮换全新实现者 + 高一档模型
• 熔断：第 5 轮仍有未解决发现则停止分派，逐条裁定 —— 搁置（附裁定）或在承重项上 BLOCKED。只在上限处裁定，提早裁定等于换名字的预先定性
• Minor 发现与「计划要求的」发现两条路在循环外
• 新增「常见的合理化借口」表取代原「红线」清单
• 新增 re-review-prompt.md（106 行全文翻译）

🧹 清除 v1.7.1 遗留的生成产物 Copy Section

三个 SDD 文件末尾都残留着 </content> —— v1.7.1 那次重写（PR #108, d7885ca）留下的，上游没有。这些文件会整体进 agent 的 prompt，属于污染。已全部清除并全仓扫描确认无同类残留。

✅ 验证（含行为 eval） Copy Section

结构性核对

• 章节结构与上游 14 节一一对应；superpowers: 引用集与上游完全一致
• 26 项关键技术记号（脚本签名、账本行格式、四种状态、ADDRESSED/NOT ADDRESSED、数值门槛）逐一确认存在，无漏译
• 两个 dot 图节点/边数与上游精确一致（6/6 与 23/28），且无幽灵节点、无孤立节点 —— 手工翻译 dot 标签最易在边里写错，会静默产生幽灵节点

脚本实测（临时 git 仓库）

• 两个计划各得独立目录；往 A 计划写 ledger 后 B 计划目录仍为空（关键回归）
• .gitignore 落在 .superpowers/sdd/ 层且 git status 干净
• 中文「任务 2」与英文「Task 3」经新路径均抽取成功
• review-package 旧签名正确报 usage 错误

行为 eval —— 新机制 7 个场景全对

考察译文是否真的传达了新规则（第 2 轮该唤回还是换新、第 4 轮模型档位、第 5 轮能否再开一轮、承重发现该搁置还是停下、Minor 走哪条路、遇到别的计划的账本怎么办、控制者能否自己修）：7/7 正确，连「运行环境无法唤回时才改派全新实现者」这个细节都答出。

集成 eval —— 真实 agent 的准备阶段

用 tests/subagent-driven-dev/go-fractals 脚手架跑真实执行的准备阶段，验证 agent 是否按新签名调脚本（旧习惯可能让它省掉 PLAN_FILE）：

• ✔ 实际调用 sdd-workspace plan.md，带上了 PLAN_FILE 参数
• ✔ 同时检查了 plan 作用域账本和旧扁平路径的游离账本
• ✔ 账本第一行为正确的身份行
• ✔ 工作区落在 .superpowers/sdd/plan/，未在旧扁平路径写账本
• ✔ 起飞前冲突扫描产出 5 条打包成一次的提问（而非逐条打断）
• ✔ 建了 10 条待办，并按指令在分派实现者前停下

回归：scripts/audit.sh 150 pass / 0 fail、scripts/verify-release.sh 82 pass / 0 fail。SDD 已从 audit 的上游漂移警告里消失（结构层级现已对齐）。

audit PASS 由 153 降至 150，是上游有意删除 Integration 一节（原列 executing-plans / test-driven-development / writing-plans 三个引用）导致 Category 4b 少 3 项引用检查，非静默跳过。

v1.7.3 (2026-08-07) Copy Chapter

🐛 同步上游两处纯代码修复（对齐 v6.1.1 → v6.2.0 时挑出） Copy Section

两个文件在我们这边都与上游 v6.1.1 字节一致（从未汉化改动），因此可直接取上游版 —— 无需翻译、无需 eval。

• hooks/hooks.json 加 "shell": "bash"（上游 5151e7a）：SessionStart hook 在 Windows 上原先不经 Git Bash 分发。我们的 hooks.json 与上游除这一行外完全相同。这条直接改善 Windows 用户的 bootstrap 可靠性 —— bootstrap 不加载，skill 就是死重。
• skills/systematic-debugging/find-polluter.sh（上游 6015d37、c8921b5）：修三个真 bug，已逐个实测新旧版对比：
  • pattern 带 ./ 前缀时匹配不到（find . 输出 ./ 前缀路径）：旧 1 个 → 新 2 个
  • -path 的 **/ 无法匹配零层目录，src/**/*.test.ts 漏掉 src/top.test.ts：旧 1 个 → 新 2 个
  • 完全无匹配时计数为 1 而非 0（echo 空串仍算一行）：旧 1 → 新 0

🧪 新增工具计数一致性检查（audit Category 5，+24 项） Copy Section

加一款工具要同步简繁 README（各 6 处）、package.json、CLAUDE.md、site/build.mjs（三语言 15 处）、3 份 plugin manifest —— v1.7.2 全靠人工 grep 才没漏。现在从 installer 的 TARGETS 推导期望值并逐处断言，另加两条结构性检查：README 工具表行数必须等于宣称数、Category 2 实际测试的工具数必须等于宣称数（宣称了就必须测）。

已验证会拦：把标题改成 23 款、删掉一行工具表，两种漂移都被抓到。

口径写进注释：TARGETS 是「安装目标」共 21 个；Copilot CLI 与 CC 共用 .claude/skills（别名映射过去）不占独立条目，但文案里作为独立产品单独计数，所以「文案数 = TARGETS 数 + 1 = 22」。

🐛 修 bash 3.2 下 CJK 报错信息乱码 Copy Section

macOS 自带 bash 3.2.57 解析标识符时不识别多字节字符，$file「 会把「的首字节 0xE3 吞进变量名，导致变量展开为空且字符被截断。报错信息变成「计数不一致: ����= ��应为 22」—— 只在检查失败时才暴露，写检查的人看不到。

复现：bash -c 'f=README.md; echo "文件: $f「标签」结束"' → 文件: ��标签」结束

修法是给紧跟 CJK 标点的变量加花括号。全仓扫描 $var 紧跟非 ASCII 字节的模式，命中 3 处（audit.sh 2 处、verify-release.sh 1 处 —— 后者因为检测项一直全通过，从没暴露过）。

🧹 其他 Copy Section

• .gitignore 补上 .cline/、.clinerules/、.kilocode/ —— 与 .trae/、.qoder/ 一致，避免在本仓库内自测安装器留下未跟踪文件。
• 官网 site/build.mjs 工具计数 20 → 22，三语言 FAQ 枚举补入 Cline、Kilo Code（v1.7.2 发了但站点没跟）。

✅ 验证 Copy Section

• scripts/audit.sh：153 pass / 0 fail（3 项 warn 为上游漂移，见 #19）
• scripts/verify-release.sh：82 pass / 0 fail
• SessionStart hook 冒烟：退出码 0，输出正确的 SessionStart JSON
• npm 包端到端：pack → 从 tarball 安装 → 真实跑安装器 → 卸载零残留

⚠️ audit 的上游漂移 warn 从 2 条变 3 条（新增 using-git-worktrees），且 executing-plans / finishing-a-development-branch 的上游 H 值有变化 —— 这是本次 git fetch upstream 把对比基准从旧快照更新到 v6.2.0 导致的，不是代码改动引起。

v1.7.2 (2026-08-07) Copy Chapter

🆕 新增 Cline 与 Kilo Code 适配（工具数 20 → 22，关 #112、#88） Copy Section

两款都是 VS Code 扩展，加载的是 rules 而非懒加载的 skills —— rules 会并入每一轮 system prompt。照搬「把 20 个 SKILL.md 复制进规则目录」会让每轮对话背着 182 KB 常驻开销（Cline 官方也提示规则超约 300 行后遵守度下降）。

改用仓库既有的 Trae 模式：规则目录只放一份索引（核心规则 + 20 个 skill 的名称/触发条件表，实测 4.5 KB，比全量塞入小 40 倍），skills 本体放各自 skills/ 目录由 agent 按需读取。

• Cline：skills → .cline/skills/，索引 → .clinerules/superpowers-zh.md。不写 YAML frontmatter —— Cline 目前只支持 paths 一个条件字段，无 frontmatter 即始终生效。索引保持在 .clinerules/ 根层单文件（子目录是否递归扫描官方未说明）。
• Kilo Code：skills → .kilocode/skills/，索引 → .kilocode/rules/superpowers-zh.md。有意不走 v7 推荐的 .kilo/rules/ + kilo.jsonc —— 后者需把路径登记进用户的 kilo.jsonc（带注释的 JSONC，安装器安全合并容易改坏用户配置）。官方明确 .kilocode/rules/ 向后兼容且零配置生效，故选它；docs 里写明了想迁到 v7 该改哪一行，以及万一没生效如何反馈。
• 两者均无 --global：Cline 全局 rules 路径随 OS 变（~/Documents/Cline/Rules，Linux/WSL 还有 ~/Cline/Rules 回退），Kilo 全局同样要走 kilo.jsonc 登记 —— 不是通用复制机制能可靠命中的，--global 明确拒绝并指向 docs，绝不写无效路径。
• 路径依据：docs.cline.bot、kilo.ai。

🔧 检测落空时给出针对性建议（关 #48） Copy Section

装了 opencode / codex 但项目里没留下标记目录时，原先只报「未检测到任何已知 AI 编程工具」，用户无从判断下一步。

• 新增 PATH 探测：检测落空时扫 PATH 找已安装的 CLI，直接打印可复制的 --tool 命令。
• 只提示、不自动安装 —— 自动装错工具正是 #33 修掉的问题：PATH 上装了不代表这个项目要用它。
• isOnPath() 只查文件是否存在，不 spawn 进程（不在用户机器上执行探测命令）；Windows 下遍历 PATHEXT。
• --global 模式只建议支持全局的工具，不推荐装不了的。
• 健壮性已测：PATH 为空 / 含空段 / 未定义三种退化情形均优雅退出 1，无未捕获异常。

📄 文档 Copy Section

• 补充 plugin marketplace 安装方式（关 #39）：.claude-plugin/marketplace.json 从 v1.7.x 起就存在且可用，但 README 从未写过怎么用。已实测 plugin validate / marketplace add jnMetaCode/superpowers-zh（GitHub 直连克隆）/ plugin install 全链路通过，安装缓存内含全部 20 个 SKILL.md。简繁 README 新增「方式二」，原手动安装与配置文件引用顺延为方式三 / 四。
• 修正 Copilot CLI 在 Windows 的工具面（关 #93）：copilot-tools.md 原先只记 bash + async:true 一套，但 Windows 实测（Copilot CLI 1.0.69-1）注册的是 powershell + detach，没有 bash/async 家族。现拆成两张表并注明「两套不会同时出现」，补充两个坑：.sh 需显式走 Git Bash；stop_powershell 停不掉 detach:true 的进程，需按真实 Windows PID（非 MSYS PID）Stop-Process。
• 新增 docs/README.cline.md、docs/README.kilocode.md。
• 修正 installer 报错文案里失效的章节锚点（改为指向父级 #快速开始，不再依赖会变的章节编号）。
• 计数 20 → 22 同步：简繁 README、package.json、CLAUDE.md、3 份 plugin manifest。

✅ 验证 Copy Section

• scripts/audit.sh：130 pass / 0 fail（2 项 warn 为既有上游漂移，见 #19）
• 发版前深度验证（比 audit 严，断言实际落盘而非只看退出码）：82 项全通过
  • 22 款工具：装 → 断言 20 个 skill 落盘 → 二次装幂等 → 卸载后零残留；无 skills/skills 嵌套
  • 19 个检测标记逐一验证只触发预期工具，既有 20 款检测结果与改动前一致
  • --global：7 款成功、14 款明确拒绝且退出码 1；拒绝信息引用的 8 份 docs 均存在
  • bootstrap 索引断言：表行数 = 20、无空 description、Cline 无 frontmatter、路径指向正确
• npm 包端到端：npm pack → 从 tarball 装 → 用打包后的二进制真实跑 Cline 自动检测 → 20 skills + 索引生成 → 卸载零残留

v1.7.0 (2026-07-13) Copy Chapter

🆕 新增两款国产 IDE 工具支持（工具数 18 → 20） Copy Section

• CodeBuddy（腾讯 AI IDE，关 #18 / #75）：.codebuddy/skills/ + CODEBUDDY.md bootstrap，加载机制类似 Claude Code。仅项目级（用户级加载路径未证实，暂不做全局）。
• 华为云码道 CodeArts（关 #20）：.codeartsdoer/skills/，skills-only 适配（其 bootstrap/指令文件约定未证实，靠 CodeArts 自身 skill 发现；docs 已说明，不自动触发可手动点名 skill）。
• 两者均逐一核对配置来源（owner 核实 / 用户实测），不臆造无效路径。工具计数在 README / 站点 / package / FAQ / audit 全量同步。

🌐 官网 + README 多语言（新增繁体） Copy Section

• 官网（#100）重构为 LANGS 语言列表驱动，新增繁体中文站（zh-Hant）：63 页（3 语言 × (首页 + 20 skill 详情)），语言切换器 / hreflang / sitemap 齐全；以后加语言只需加一项 + 一个翻译对象。
• README（#101）加语言切换栏，新增完整 README.zh-Hant.md（353 行对齐，台港自然术语）。
• 繁体均手写（台港术语：程式碼 / 專案 / 除錯 / 全域 / 檔案 等），不引入 OpenCC 依赖。日文按定位不纳入本仓库（应作独立 superpowers-ja）。

🧹 官网下架赞助商展示 Copy Section

• 移除官网与 README 的赞助商板块（含 5Cookie Code 展示卡 / logo / 样式 / 资源），仅保留一行赞助联系方式；官网切自定义域名 sp.aiolaola.com。

🌍 全局安装（关 #21） Copy Section

新增 npx superpowers-zh --global，一次安装、所有项目共享，解决多项目用户需要逐个项目重复安装的痛点。

• 项目级（默认）不变：装到 process.cwd() 下工具目录（如 .claude/skills），仅当前项目生效。
• 全局（--global）：装到工具的用户级目录（如 ~/.claude/skills），所有项目自动共享，更新只需重装一次。项目级优先、全局兜底，二者可共存。
• 支持全局的工具（逐一核对各工具 docs 声明的真实加载路径，不臆造）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode。其中 Codex 全局装到 ~/.agents/skills（docs 确认 Codex 启动扫描该目录，而非 ~/.codex/skills）；Claude Code 全局 bootstrap 写 ~/.claude/CLAUDE.md。
• Gemini CLI / Antigravity 有意不纳入通用 --global：Gemini 全局走扩展目录 ~/.gemini/extensions/*/skills/ + manifest、Antigravity 全局 skills 路径未在 docs 证实，通用复制机制覆盖不了 —— --global 会报错并指向各自 docs/README.*.md，避免「装了不生效」。
• 其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Hermes / Claw）规则是项目级或存于应用内设置，--global 明确报错并提示改用项目级，绝不写入无效路径。
• 卸载对称支持：--global --uninstall 从用户级目录移除 skills 并按哨兵精确清理全局 bootstrap。
• home 目录护栏调整：项目级仍拒绝在 ~ 下裸装（污染所有项目），并在提示里引导改用 --global；全局模式本就写用户级目录，跳过该护栏。

📊 文案刷新 Copy Section

• 上游 star 数 233k+ → 250k+（站点、README、package.json description 同步，实测上游已达 252k+）。

v1.6.1 (2026-07-06) Copy Chapter

对齐上游 v6.1.0 / v6.1.1 中与我们架构相关的部分。Gemini CLI 移除是上游这两个版本里改动面最大的一项，但它牵涉我们自己的营销文案（"18 款工具"）和安装器逻辑，评估后判定为独立决策，本版本不包含，留待单独讨论。

🔧 bootstrap 精简（`using-superpowers/SKILL.md`） Copy Section

翻译并合并上游"更精简的每会话 bootstrap"重写：用简洁描述替换原有的 dot 流程图、去重"指令优先级"与"技能优先级"重复内容、去掉"技能类型"（刚性/灵活）分类章节。保留了我们 fork 特有的中国特色技能路由与多工具平台适配指引（Copilot CLI / Hermes Agent / Qoder 等，上游对应文档已删但我们仍维护）。

🐛 Codex 插件清单修复 Copy Section

• .codex-plugin/plugin.json 补 "hooks": {}：Codex 在清单缺少 hooks 字段时会自动 fallback 扫描 hooks/hooks.json（我们仓库里其实是 Claude Code 的 SessionStart hook），导致 Codex 用户安装时被错误注册一个不属于它的 hook 并弹出信任提示。声明空的内联 hooks: {} 可以阻止这个 fallback。
• category 由 "Coding" 改为 "Developer Tools"，对齐上游修正。
• references/codex-tools.md 修正过期的子 agent 结果工具名：wait → wait_agent（wait 现在专指 code-mode 的 exec/wait，不是子 agent 结果工具），并补充"implementer/reviewer 完成后应主动 close_agent"的提示。

未跟进项（有意为之） Copy Section

• Codex 官方 marketplace 打包基础设施（scripts/package-codex-plugin.sh、.agents/plugins/marketplace.json、tests/codex/）——我们的分发方式是 npx superpowers-zh，不走这条上游官方安装通道。
• antigravity-tools.md / claude-code-tools.md 的裁剪——我们本来就没有这两个参考文件，无需处理。
• references/pi-tools.md 的精简（去掉 read/write/edit/bash 等自证性映射行）——验证时发现上游自己这个 v6.1.1 版本的裁剪会让他们自己的 tests/pi/test-pi-extension.mjs 断言（要求文件里出现 write/edit/bash 字样）测试失败，是上游未捕获的回归。为避免把这个 bug 一起同步进来，本版本保留了原有更完整的 pi-tools.md 内容。

v1.6.0 (2026-06-20) Copy Chapter

本版本对齐上游 v6.0.0 的实质性 skill / 基础设施变更，并新增两款 harness 支持。

🆕 新增 harness 支持 Copy Section

• Kimi Code（#59，关 #37）—— 插件清单模型 .kimi-plugin/plugin.json：指向现有 skills/、sessionStart 会话开始自动加载 using-superpowers、skillInstructions 提供 Kimi 工具映射。安装：Kimi 插件管理器 /plugins install https://github.com/jnMetaCode/superpowers-zh。文档见 docs/README.kimi.md。
• Pi (oh-my-pi)（#60，关 #44）—— 扩展模型：package.json 的 pi 字段 + .pi/extensions/superpowers.ts（注册生命周期钩子，注入 using-superpowers bootstrap + Pi 工具映射）。文档见 docs/README.pi.md。

🔒 brainstorm 可视化伴侣安全模型（#58，同步上游 v6.0.0） Copy Section

伴侣服务器重写为每会话密钥鉴权（?key= 或会话 cookie 门禁所有端点）+ 安全响应头（X-Frame-Options: DENY、CSP frame-ancestors 'none'、Cross-Origin-Resource-Policy: same-origin 等），修复旧版无鉴权时本地浏览器可读取屏幕/注入事件的缺口。Token 用 crypto.randomBytes(32)、timingSafeEqual 比较、token 文件 0o600。

🔧 其它 v6 同步 Copy Section

• using-git-worktrees / finishing-a-development-branch（#57）—— 移除已废弃的全局 worktree 目录 ~/.config/superpowers/worktrees/，对齐 v6.0.0。
• hooks/session-start（#58）—— 移除 legacy ~/.config/superpowers/skills 迁移警告，输出补 | cat。
• opencode 测试（#72）—— 修复 setup.sh 拷贝不存在的 lib/ 导致的测试飘红。

SDD（subagent-driven-development）的 v6 重写为性能/成本优化，需专门 eval 验证，故本版本暂未纳入（详见 #19）。

v1.5.0 (2026-05-21) Copy Chapter

🆕 Qoder 适配（第 18 款工具，#26、#34） Copy Section

Qoder 是阿里推出的 AI IDE，社区有多个用户提需求要求支持。本版本完成端到端适配：

• bin/superpowers-zh.js — TARGETS 加 Qoder（dir: .qoder/skills，detect: .qoder），TOOL_ALIASES 加 qoder
• generateQoderBootstrap() — 生成 .qoder/rules/superpowers-zh.md（trigger: always_on + alwaysApply: true），让"先头脑风暴 / 先 TDD / 先验证"等核心规则每个会话自动加载，不依赖模型对 description 的隐式匹配
• skills/using-superpowers/references/qoder-tools.md — 新增工具映射 reference（Qoder 大部分工具与 Claude Code 同名，只有 EnterPlanMode/ExitPlanMode → EnterSpecMode/ExitSpecMode 一个差异；附 Quest MCP 工具清单）
• docs/README.qoder.md — 完整安装/使用/卸载/故障排查指南
• scripts/audit.sh — TOOLS 数组加 qoder，CI 自动跑 18 款工具的 install/idempotent/uninstall 回归

安装方法：

cd /your/qoder-project
npx superpowers-zh --tool qoder     # 显式
# 或在有 .qoder/ 的项目里：
npx superpowers-zh                  # 自动检测

装完重启 Qoder，输入 / 即可看到 20 个 skill。

⚠️ Qoder Rules schema 来源说明 Copy Section

Qoder Rules 的 frontmatter schema（trigger: always_on / model_decision / manual）官方文档（docs.qoder.com/zh/user-guide/rules）目前未公开。本次实现的 schema 来自 GitHub 上 4 份真实社区样本（python-office、termiClaude、QoderTest、TelegramFileServer）的交叉验证。

如果 Qoder 后续改了 schema，生成的 rule 文件可能需要打开 Qoder Settings → Rules 重新选择"始终生效"类型。

🔧 文案对齐 Copy Section

• README、CLAUDE.md、package.json description：17 款 → 18 款
• 3 个 plugin manifest（.claude-plugin/{plugin,marketplace}.json、.cursor-plugin/plugin.json）description 同步

设计取舍：为什么用 always_on bootstrap 而非裸 skill Copy Section

社区有用户（@Yanyz-ok）建议"按 AI 编程工具拆分/重写 skill"。我们刻意不走这条路：

1. skill 是工作方法论，不是工具实现 —— "先写测试再写代码"这个约束在 Claude Code、Qoder、Hermes 上落地工具不同，但方法论不变。重写会让 17 份 SKILL.md 维护负担 ×17 但本质增量 0。
2. 平台内置工具 vs skill 是嵌套关系，不是替代关系 —— Qoder/Quest 的 search_codebase、update_memory 解决"怎么做"，skill 解决"什么时候做"，模型不会混淆。
3. 上游 superpowers 明确禁止"无 eval 证据的工具专属重写" —— fork 守同样规矩。

工具映射写在 references/qoder-tools.md + docs/README.qoder.md 里就够了，不需要每个 skill 内部复制一遍。详见 issue #26 完整讨论。

Refs Copy Section

• closes #26（建议新增 qoder 的支持）
• closes #34（建议支持 qoder，#26 重复）

v1.4.0 (2026-05-12) Copy Chapter

本版本核心目标：修复全量质量审计发现的所有上游漂移 P0 缺陷。改动全部是"主站有的同步过来"性质，不引入主站没有的新功能。

🔴 上游同步：v5.0.6 brainstorm server 拆分（PR #30） Copy Section

上游 v5.0.6（commit 9e3ed21）把 brainstorm server 的内容目录拆成 CONTENT_DIR + STATE_DIR peer 结构，但我们的 server 脚本还停在旧 SCREEN_DIR 单目录版本，导致 visual brainstorming 教程指向新路径但 server 用旧结构卡死。

• skills/brainstorming/scripts/server.cjs — 81 行 cherry-pick 同步
• skills/brainstorming/scripts/start-server.sh — 36 行同步
• skills/brainstorming/scripts/stop-server.sh — 29 行同步

修复后：所有 visual brainstorming 用户路径解析正常。

🔴 上游同步：v5.1.0 Code Review 整合（PR #30） Copy Section

上游 v5.1.0 PR #1299 把 reviewer persona + checklist + dispatch 模板整合到单一 code-reviewer.md 实现 self-contained，并把 SKILL.md 里的 superpowers:code-reviewer 命名子代理引用改成 general-purpose Task + 模板路径形式。我们的版本停留在 v5.0.x 拆分式。

• skills/requesting-code-review/SKILL.md 改 4 处：3 处 superpowers:code-reviewer 引用清零；占位符从 5 个精简到 4 个对齐上游；"执行计划" 集成段从 "每批（3 个任务）后审查" 改为 "每个任务完成后或在自然 checkpoint 审查"（对齐上游 v5.1.0 subagent 节奏调整）
• skills/requesting-code-review/code-reviewer.md 完整重写为 v5.1.0 self-contained 版（H header 6/6 对齐上游）

修复后：所有走 review 流程的用户得到的指令指向 general-purpose Task 而非已废弃的命名子代理。

🔴 上游同步：v5.1.0 worktree 安全修复（PR #28） Copy Section

上游 v5.1.0 #991 修复了两类 worktree 安全问题：subagent 嵌套创建 + cleanup 误删 harness-managed workspace。

• skills/using-git-worktrees/SKILL.md 全面重构：新增 Step 0 检测现有隔离（GIT_DIR/GIT_COMMON + submodule 守卫 + 同意流程）；Step 1 重组为 1a Native Tools + 1b Git Worktree Fallback + 沙盒回退；删除旧"示例工作流"段（含 /Users/jesse 硬编码）
• skills/finishing-a-development-branch/SKILL.md 全面重构：新增 Step 2 检测环境（三态表）；旧 Step 2-5 重编号为 3-6；Step 4 新增分离 HEAD 3 选项变体；Step 5 Option 1 重写（MAIN_ROOT cwd safety + merge→verify→cleanup→delete 严格排序）；Step 6 清理范围限定在 .worktrees/ / worktrees/ / ~/.config/superpowers/worktrees/，外部 harness-managed workspace 一律不动

修复后：subagent 不再嵌套创建 worktree；清理不会误删 harness-managed workspace。

🔴 平台兼容性修复：Windows Cursor hook 回归（PR #30） Copy Section

hooks/hooks-cursor.json 的 command 之前被本地改成直接调 unix shell ./hooks/session-start，丢失上游的 polyglot wrapper ./hooks/run-hook.cmd session-start，Windows + Cursor 组合用户 hook 完全不触发。

• 1 行恢复上游 polyglot wrapper

修复后：Windows Cursor 用户 hook 正常触发。

🆕 防回归基建：CI 自动漂移检测（PR #31） Copy Section

新增 scripts/audit.sh + .github/workflows/audit.yml，每次 PR 自动跑 4 类共 90+ 项检查：

1. 静态校验（JSON parse / SKILL.md frontmatter / symlink / hook 可执行性）
2. Installer 功能（17 款工具装/重装/卸载全跑）
3. 上游对齐（hooks 4 文件 + brainstorm scripts 3 文件 + 14 翻译 skill 结构层级 + code-reviewer.md self-contained 结构）
4. 交叉引用（README → docs/ 链接 + skill 间引用 + 装完后 .claude/skills/using-superpowers/SKILL.md 路径解析）

WARN（不阻塞）vs FAIL（阻塞）分级：本次"4 个 P0 漂"事件如果当时有这个 audit 在 CI 跑，PR 阶段就会被拦下。

未来意义：维护者下次手抖把 hooks-cursor.json 改坏 / 上游同步漏一项，CI 立刻拦下。

🔧 工具链小修 Copy Section

• scripts/sync-plugin-version.js 加入 gemini-extension.json（之前漏掉，导致 gemini extension manifest 卡在 1.1.6 老版本）
• package.json 的 version 钩子 git add 列表同步更新

安装路径方针澄清 Copy Section

本版本明确：有官方 plugin marketplace 的工具（Claude Code / Codex CLI / OpenCode / VS Code）首选 marketplace 路径，npx superpowers-zh 主要服务没有 marketplace 的工具（Cursor / Trae / Kiro / Gemini CLI / Hermes / Aider / Antigravity / Windsurf / Qwen / Claw / OpenClaw / DeerFlow 共 13 款）。fork 不再尝试给 marketplace 工具加 npx 路径的"完整支持"——它们走主站路径即可。

不在本版本范围 Copy Section

• executing-plans/SKILL.md 我们扩写了 105 行中文示例（主动选择，保留——是 fork 的中文优化，非漂移）
• using-superpowers/SKILL.md 的"中国特色技能路由"段（fork 增量，保留）
• 各 reviewer-prompt.md 翻译差异（结构对齐，纯翻译漂移，无行为 bug）
• open issues #18/#21/#26/#20（fork 增量需求，按方针延后）

Refs Copy Section

• PR #28（worktree 安全修复）
• PR #30（brainstorm scripts + code-reviewer 整合 + hooks-cursor + SKILL.md 引用）
• PR #31（audit script + CI workflow）
• issue #19 跟踪上游 v5.0.6 / v5.1.0 同步 → 关键项目全部覆盖

v1.3.0 (2026-05-10) Copy Chapter

跟上游对齐 (v5.1.0) Copy Section

• 同步上游 v5.1.0 的目录变更：上游主动删除了 commands/（3 个 deprecated stub）和 agents/code-reviewer.md（已上升进 requesting-code-review skill）。中文 fork 跟随删除以与上游意图对齐。详见上游 #1188 与 PR #1299。
• bin/superpowers-zh.js 移除安装时复制 agents/ 到 .claude/agents/ 的逻辑，保留 uninstall 时的清理逻辑（用于已装用户清理残留 code-reviewer.md，防止双 source of truth）。
• .github/workflows/ci.yml 删除 "Validate agents" 验证段（agents/ 已删，验证空目录无意义）。

补齐上游遗漏的根级文件 Copy Section

• CLAUDE.md —— 上游 contributor 指南（含 anti-slop-PR 规则）的中文翻译，末尾追加中文 fork 自己的 PR 流程说明。
• AGENTS.md —— 软链接 → CLAUDE.md（mode 120000，跟上游一致）。Codex CLI 等工具从 AGENTS.md 自动加载等同读取 CLAUDE.md。
  • Known limitation：npm pack 默认不跟随 symlink，因此 npm publish 出来的 tarball 不包含 AGENTS.md。这不影响实际使用：AGENTS.md 是 Codex CLI 在用户自己项目目录读的文件，不是从 superpowers-zh 安装包读的；通过 git clone 拿到仓库的贡献者会正确解析 symlink。
• RELEASE-NOTES.md —— 上游 release notes 原样保留（英文版，1180 行）。
• RELEASE-NOTES.zh.md —— 本文件，中文 fork 自身 release 记录。
• .codex-plugin/plugin.json —— Codex CLI plugin manifest（中文版本地化：name/description/displayName 改为中文版，URL 指向 jnMetaCode/superpowers-zh）。
• .version-bump.json —— 上游版本管理配置文件。
• scripts/bump-version.sh —— 上游版本同步脚本（含 --check 漂移检测、--audit 仓库审计）。中文版 npm version 钩子继续用 scripts/sync-plugin-version.js，bump-version.sh 作为补充工具引入。
• assets/app-icon.png + assets/superpowers-small.svg —— Codex marketplace 需要的图标资产。
• 4 个新增上游测试：tests/claude-code/test-requesting-code-review.sh、tests/claude-code/test-worktree-native-preference.sh、tests/opencode/test-bootstrap-caching.{mjs,sh}。

主动修复上游 v5.1.0 的疏忽 Copy Section

• .cursor-plugin/plugin.json 删除 dangling 的 "agents": "./agents/" 和 "commands": "./commands/" 两行。上游 v5.1.0 删了目录但忘了同步清理 manifest（git blame 显示这两行从 2026-02-13 加入后从未更新）。中文 fork 主动修掉（向上游开 issue 是后续动作）。

修中文版自己的老漂移（PR #23） Copy Section

• .claude-plugin/marketplace.json 的 plugins[0].version 卡在 1.1.8 的老漂移修复（追上其他 4 个 manifest，1.3.0 release 时统一升到 1.3.0）。原因是中文版简化版 sync-plugin-version.js 之前只 match 顶层 "version": 字段，跳过嵌套位置；导致 Claude Code marketplace 用户看到的 plugin 版本一直停在 1.1.8，跟 npm 包真实版本不同步。
• scripts/sync-plugin-version.js 增强为支持嵌套字段路径（plugins.0.version）。TARGETS 改为对象数组 { path, field }，对齐上游 .version-bump.json 格式。仍使用 regex 替换而非 JSON re-stringify，保留原文件格式（缩进、行内/多行数组等不被破坏）。

不引入 Copy Section

• 上游 scripts/sync-to-codex-plugin.sh（推 OpenAI Codex marketplace 用，硬编码 prime-radiant-inc/openai-codex-plugins，中文版用不上）
• 配套测试 tests/codex-plugin-sync/test-sync-to-codex-plugin.sh

不动（中文版叠加层全部保留） Copy Section

bin/ + npx 流程、docs/ 中文工具文档、4 个 chinese-* skill、mcp-builder、workflow-runner、README.md 主推 npx 路径、.codex/INSTALL.md、.opencode/INSTALL.md、.gemini/、scripts/sync-plugin-version.js —— 这些是符合"保持上游主流程不变 + 中文版叠加新增"原则的中文 fork 沉淀，全部保留。

v1.2.1 (2026-05-05) Copy Chapter

修复 Copy Section

• --uninstall 数据丢失边界 case —— 加哨兵注释 + 保守 fallback，杜绝在某些路径上误删用户数据。

v1.2.0 (2026-05-05) Copy Chapter

新增 Copy Section

• --uninstall 子命令 —— npx superpowers-zh --uninstall 一条命令清理已安装的 skills（#17）。
• HOME 目录守护 —— uninstall 时强校验工作目录非用户 HOME，杜绝误删全局文件。
• 计数显示修复 —— 安装后输出实际安装的 skill 数量（之前显示固定值）。

v1.1.9 (2026-04-28) Copy Chapter

修复 Copy Section

• Claude Code bootstrap 修复 —— npx 安装到 CC 目标时自动补上 CLAUDE.md bootstrap，根治 skill 不触发问题（#14）。

变更 Copy Section

• Node 引擎要求 提升到 >=20（Node 14/16/18 均已 EOL）。
• README 重排：相关项目表挪到显眼位置；姊妹项目区块独立成"相关项目生态"章节，重点推广 orchestrator。
• QQ 群 标识改为 QQ 2群。

v1.1.8 (2026-04-19) Copy Chapter

新增 Copy Section

• Claw Code 支持（第 17 款工具，Rust 版 AI CLI）—— auto-detect .claw/ 或 CLAW.md，支持 --tool claw/claw-code/clawcode。
• CNB（腾讯云原生构建）平台适配 —— chinese-git-workflow skill 新增 CNB 章节，含 .cnb.yml CI 示例（#6）。

v1.1.0 – v1.1.7 早期开发（2026-03 ~ 2026-04） Copy Chapter

中文 fork 在这一时期完成了主要的多工具适配与中文化基建：

• 第 1 款 → 第 16 款工具陆续上线：Claude Code、Cursor、Codex CLI、Gemini CLI、Trae、VS Code (Copilot)、Antigravity、Hermes Agent、Copilot CLI、Windsurf、Aider、OpenCode、Qwen Code（通义灵码）、Kiro、OpenClaw、DeerFlow 2.0
• 4 个中国原创 skill 沉淀：chinese-code-review、chinese-commit-conventions、chinese-documentation、chinese-git-workflow
• mcp-builder、workflow-runner 两个补充 skill
• npx 一条命令自动检测项目工具并安装
• 跨平台兼容性修复：Windows cpSync 问题、低版本 Node 兼容、Antigravity/Aider/Gemini CLI 自动生成 bootstrap

v1.0.0 (2026-03-09) Copy Chapter

• 中文 fork 初始版本，基于上游 obra/superpowers v5.0.0 翻译。
• 完整翻译 14 个上游 skill。
• 首批支持 Claude Code 一种工具。

File: .upstream-sync.json Copy Chapter

[Binary file]

File: .version-bump.json Copy Chapter

{
"files": [
{ "path": "package.json", "field": "version" },
{ "path": ".claude-plugin/plugin.json", "field": "version" },
{ "path": ".cursor-plugin/plugin.json", "field": "version" },
{ "path": ".codex-plugin/plugin.json", "field": "version" },
{ "path": ".kimi-plugin/plugin.json", "field": "version" },
{ "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
{ "path": "gemini-extension.json", "field": "version" }
],
"audit": {
"exclude": [
"CHANGELOG.md",
"RELEASE-NOTES.md",
"node_modules",
".git",
".version-bump.json",
"scripts/bump-version.sh"
]
}
}

================================================ SYMLINK: AGENTS.md -> CLAUDE.md

File: docs/README.aider.md Copy Chapter

[Binary file]

File: docs/README.antigravity.md Copy Chapter

[Binary file]

File: docs/README.claw.md Copy Chapter

Superpowers 中文版 — Claw Code 安装指南

在 Claw Code 中使用 superpowers-zh 的完整指南。

📌 v1.7.10 及更早版本 Claw Code 没有任何安装文档 —— 23 款支持工具里唯一一个。v1.7.11 补上。

安装 Copy Chapter

cd /your/project
npx superpowers-zh --tool claw

装两样东西：

📌 v1.7.10 及更早只装 skills、不写 CLAW.md。skills 能被发现，但没有引导就不会在恰当时机自动触发。v1.7.11 起补上。

工作原理 Copy Chapter

两处都有源码级证据，不是猜的：

① Skills 目录

claw 自己的源码（rust/crates/plugins/src/lib.rs）里写着：

claw does not load plugin-managed skills and instead discovers skills from local roots such as .claw/skills, .omc/skills, .agents/skills, ~/.omc/skills, and ~/.claude/skills/omc-learned.

所以 .claw/skills/ 是它的主要发现路径之一，无需配置。

② 根指令文件

USAGE.md 列出 claw 加载的根指令文件及优先级：

CLAUDE.md > CLAW.md > AGENTS.md

另外它也读 .claw/CLAUDE.md、.claude/CLAUDE.md、.claw/instructions.md。我们写 CLAW.md。

⚠️ 已有 CLAUDE.md 时要注意 Copy Section

因为优先级是 CLAUDE.md > CLAW.md，如果你的项目里已经有 CLAUDE.md（比如装过 Claude Code），它可能压过我们刚写的 CLAW.md，导致 skill 不自动触发。

安装器检测到这种情况会主动提示。解法是让 CLAUDE.md 也带上引导：

npx superpowers-zh --tool claude

两个文件都带引导就不会互相遮蔽。

装过 Antigravity 的项目不用重复装 Copy Section

注意上面源码里那句 —— claw 也扫 .agents/skills，而那正是我们给 Antigravity 装的目录。如果你已经跑过 npx superpowers-zh --tool antigravity，claw 其实已经能读到这些 skill 了，再装一次 .claw/skills 会让它加载两份。

手动安装 Copy Chapter

git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.claw/skills
cp -r superpowers-zh/skills/* /your/project/.claw/skills/

手动复制不会生成 CLAW.md，skill 不会自动触发。建议优先用 npx superpowers-zh --tool claw。

也可以用 claw 自带的安装命令逐个装：

claw skills install /path/to/superpowers-zh/skills/brainstorming

装完用 /skills list（REPL 内）或 claw skills --output-format json 确认发现的 skill 名。

关于全局安装 Copy Chapter

--global 不支持。claw 的用户级 skill 根是 ~/.omc/skills 和 ~/.claude/skills/omc-learned —— 前者不是我们的目录约定，后者是 claw 自己学习产物的专用目录，都不适合通用 --global 覆盖。

想让所有项目共享，可以给 Claude Code 装全局（npx superpowers-zh --global --tool claude），claw 会读 ~/.claude/ 下的相关约定。

卸载 Copy Chapter

npx superpowers-zh --uninstall

删除 .claw/skills/ 下装过的 skill，并从 CLAW.md 精确切除 superpowers-zh 段（保留你自己写的内容）。实测卸载后零残留。

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• Claw Code 仓库：https://github.com/ultraworkers/claw-code

File: docs/README.cline.md Copy Chapter

Superpowers 中文版 — Cline 安装指南

在 Cline（VS Code AI 编程扩展）中使用 superpowers-zh 的完整指南。

快速安装 Copy Chapter

cd /your/project
npx superpowers-zh --tool cline

自动检测：安装脚本发现项目里有 .clinerules/ 目录时也会自动装 Cline。如果你还没建过 rules，就用上面的 --tool cline 显式指定。

装完会得到两样东西：

.cline/skills/            # 21 个 skill 本体，按需读取
.clinerules/
└── superpowers-zh.md     # 一份小索引，常驻 system prompt

工作原理（和其他工具不一样，值得读一下） Copy Chapter

Cline 没有「skills」概念，它加载的是 Rules：.clinerules/ 目录下所有 .md / .txt 会被合并进每一轮的 system prompt。

这跟 skills 的懒加载完全不同 —— 所以绝不能把 21 个 SKILL.md 直接放进 .clinerules/，那会让每轮对话都背着几万字的常驻开销，Cline 官方也提示规则超过约 300 行后遵守度会下降。

superpowers-zh 的做法：

索引 rule 里明确告诉 Cline：匹配到触发条件就去读对应的 SKILL.md，不要把正文抄进 rules。

为什么不写 YAML frontmatter Copy Section

Cline 目前只支持 paths（glob 数组）一个条件字段。不写 frontmatter 就是「始终生效」，正是我们要的效果，所以索引 rule 是纯 Markdown。

手动安装 Copy Chapter

git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.cline/skills /your/project/.clinerules
cp -r superpowers-zh/skills/* /your/project/.cline/skills/

然后在 .clinerules/superpowers-zh.md 里手写一份索引（内容参考 npx 装出来的那份）。推荐直接用 npx —— 索引表是根据 skills 的 frontmatter 自动生成的，手写容易漏。

关于全局安装 Copy Chapter

--global 对 Cline 不支持。Cline 的全局 rules 目录随操作系统变化：

• macOS / Linux：~/Documents/Cline/Rules
• Windows：Documents\Cline\Rules
• Linux / WSL 有时是 ~/Cline/Rules

没有一条稳定路径能让通用 --global 可靠命中，写错等于「装了不生效」，所以宁可不做。请用项目级安装。想全局用的话，把 npx 生成的那份 superpowers-zh.md 手动拷进你系统上实际的 Cline 全局 rules 目录即可。

使用 Copy Chapter

装好后新开一个 Cline 会话（rules 在会话开始时加载）。然后正常提需求即可：

• 「给用户模块加个批量导出功能」→ 应当先触发 brainstorming 做需求澄清，而不是直接写代码
• 也可以手动点名：「用 test-driven-development skill 做这个」

更新 / 卸载 Copy Chapter

npx superpowers-zh --tool cline      # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall       # 卸载，同时清掉 .clinerules/superpowers-zh.md

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• Cline Rules 文档：https://docs.cline.bot/customization/cline-rules

File: docs/README.codearts.md Copy Chapter

[Binary file]

File: docs/README.codebuddy.md Copy Chapter

CodeBuddy 使用指南

CodeBuddy（腾讯云 AI 编程助手 / AI IDE）加载 superpowers-zh skills 的方式与 Claude Code 类似：项目根目录的 CODEBUDDY.md 作为 bootstrap 引导，skills 放在 .codebuddy/skills/ 下。

一键安装（推荐） Copy Chapter

在你的项目根目录运行：

npx superpowers-zh

自动检测到 .codebuddy/ 或 CODEBUDDY.md 时会安装到 CodeBuddy。检测不到时显式指定：

npx superpowers-zh --tool codebuddy

安装内容：

• .codebuddy/skills/ — 21 个 skill（每个含 SKILL.md）
• CODEBUDDY.md — bootstrap 引导（已存在则在哨兵注释间追加，不覆盖你的内容）

全局安装 Copy Chapter

npx superpowers-zh --global --tool codebuddy

装到 ~/.codebuddy/skills/，bootstrap 写 ~/.codebuddy/CODEBUDDY.md，所有项目共享。

📌 v1.7.10 及更早写着「用户级路径尚未验证」且没有 --global。现已核实：官方目录结构文档确认全局与项目级同构。v1.7.11 起支持。

Skill 加载优先级 Copy Chapter

同名时项目级 > 用户级 > 插件级（官方文档口径）。

记忆文件同理：全局在 ~/.codebuddy/CODEBUDDY.md，项目级放项目根 CODEBUDDY.md（官方称项目根与 .codebuddy/CODEBUDDY.md 两处等价，我们用项目根）。

使用 Copy Chapter

1. 安装完成后重启 CodeBuddy。
2. CodeBuddy 读取 CODEBUDDY.md 后，会在任务匹配某个 skill 的触发条件时，读取对应的 .codebuddy/skills/<skill-name>/SKILL.md 并遵循其流程。
3. 当任务涉及需求分析、TDD、系统化调试、代码审查等场景时，对应 skill 会被引用。

卸载 Copy Chapter

npx superpowers-zh --uninstall

移除 .codebuddy/skills/ 下的 skills，并按哨兵注释精确切除 CODEBUDDY.md 里的 superpowers-zh 段落（不误删你自己的内容）。

故障排查 Copy Chapter

• skills 没生效：确认已重启 CodeBuddy；确认 CODEBUDDY.md 里存在 # Superpowers-ZH 中文增强版 段落。
• 自动检测不到：用 npx superpowers-zh --tool codebuddy 显式指定。

反馈 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• 项目主页：https://github.com/jnMetaCode/superpowers-zh

File: docs/README.codex.md Copy Chapter

Superpowers 中文版 — Codex CLI 安装指南

⚠️ v1.7.10 及更早的项目级安装装错了地方 Copy Chapter

官方文档（developers.openai.com/codex/skills，现 308 跳 learn.chatgpt.com/docs/build-skills）给出的扫描目录完整清单是：

$CWD/.agents/skills
$CWD/../.agents/skills
$REPO_ROOT/.agents/skills
$HOME/.agents/skills
/etc/codex/skills

没有 .codex/skills。 而 v1.7.10 及更早的 npx superpowers-zh --tool codex 正是装到 .codex/skills —— Codex 不扫那里，等于装了完全不生效。全局（~/.agents/skills）一直是对的，只有项目级错。

v1.7.11 起项目级改装 .agents/skills，重装时会自动清掉旧位置里我们装的那些（你自己放在 .codex/skills 下的东西不动）：

cd /your/project
npx superpowers-zh --tool codex

顺带说明：.agents/skills 与 Antigravity 共用，这是 Agent Skills 开放约定，不是冲突。装过其中一个，另一个也能读到。

在 Codex 中使用 superpowers-zh 的完整指南。

快速安装 Copy Chapter

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/jnMetaCode/superpowers-zh/refs/heads/main/.codex/INSTALL.md

Codex 原生插件安装 Copy Chapter

Codex CLI 自带插件管理，可以直接把本仓库注册为 marketplace 安装，不需要 Node.js / npm（已在 codex-cli 0.147.0、0.154.0 上实测）：

codex plugin marketplace add https://github.com/jnMetaCode/superpowers-zh.git
codex plugin add superpowers-zh@superpowers-zh
codex plugin list   # 应显示 superpowers-zh@superpowers-zh  installed, enabled

安装后 21 个 skills 全部可被发现；插件清单声明了空 hooks，不会注册仅适用于 Claude Code 的 SessionStart hook。

更新：

codex plugin marketplace upgrade superpowers-zh
codex plugin add superpowers-zh@superpowers-zh

卸载：

codex plugin remove superpowers-zh@superpowers-zh
codex plugin marketplace remove superpowers-zh   # 可选：连同 marketplace 一起移除

手动安装 Copy Chapter

前置条件 Copy Section

• OpenAI Codex CLI
• Git

步骤 Copy Section

1. 克隆仓库：

   bash Copy

   git clone https://github.com/jnMetaCode/superpowers-zh.git ~/.codex/superpowers-zh

2. 创建 skills 符号链接：

   bash Copy

   mkdir -p ~/.agents/skills
   ln -s ~/.codex/superpowers-zh/skills ~/.agents/skills/superpowers

3. 重启 Codex。

4. 子代理 skills（可选）： dispatching-parallel-agents 和 subagent-driven-development 需要 Codex 的多代理功能。在 Codex 配置中添加：

   toml Copy

   [features]
   multi_agent = true

Windows Copy Section

使用 junction 代替符号链接（无需开发者模式）：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers-zh\skills"

工作原理 Copy Chapter

Codex 原生支持 skill 发现——启动时扫描 ~/.agents/skills/ 目录，解析 SKILL.md 的 frontmatter，按需加载 skills。通过一个符号链接即可注册所有 skills：

~/.agents/skills/superpowers/ → ~/.codex/superpowers-zh/skills/

using-superpowers skill 会自动被发现并强制执行 skill 使用纪律——无需额外配置。

使用 Copy Chapter

Skills 自动发现。Codex 在以下情况激活 skills：

• 你提到 skill 名称（如 "use brainstorming"）
• 任务匹配 skill 的描述
• using-superpowers skill 指示 Codex 使用某个 skill

更新 Copy Chapter

cd ~/.codex/superpowers-zh && git pull

Skills 通过符号链接即时更新。

卸载 Copy Chapter

rm ~/.agents/skills/superpowers

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"

可选：删除克隆的仓库 rm -rf ~/.codex/superpowers-zh

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• 项目主页：https://github.com/jnMetaCode/superpowers-zh

File: docs/README.crush.md Copy Chapter

Superpowers 中文版 — Crush 安装指南

在 Crush（Charm 出品的终端 AI 编程 agent）中使用 superpowers-zh 的完整指南。

⚠️ 先看这一条：你可能已经装好了 Copy Chapter

Crush 遵循 Agent Skills 开放标准，项目级会自动发现下面四个目录，无需任何配置：

.crush/skills      .agents/skills      .claude/skills      .cursor/skills

也就是说 —— 如果你已经为 Claude Code、Cursor、Codex 或 Antigravity 装过 superpowers-zh，Crush 现在就已经能读到那些 skills 了。

这种情况下不要再装 --tool crush，否则同一批 skills 会出现两份，Crush 会重复加载。先确认一下：

ls .claude/skills .cursor/skills .agents/skills .crush/skills 2>/dev/null

只要上面任一目录里已有 21 个 skill，你就不用做任何事。

快速安装 Copy Chapter

只有在上述目录都为空时才需要装：

cd /your/project
npx superpowers-zh --tool crush

自动检测：项目里存在 .crush/、crush.json 或 .crush.json 任一时会自动装 Crush。

全局安装 Copy Chapter

Crush 支持通用全局安装：

npx superpowers-zh --global --tool crush

装到 ~/.config/crush/skills/（Windows：%LOCALAPPDATA%\crush\skills\），所有项目共享。

Crush 的用户级发现路径还包括 ~/.config/agents/skills/（与 Codex、Copilot CLI 等共用的跨运行时别名）。如果你已经用 --global --tool codex 装过，那批 skills 也会被 Crush 看到 —— 同样别重复装。

工作原理 Copy Chapter

Crush 是 skills-only 适配：不需要 bootstrap 或规则文件。每个 skill 是一个含 SKILL.md 的目录，SKILL.md 的 frontmatter 带 name 与 description，Crush 据此按需发现并激活。

如果你想把 skills 放在非标准位置，Crush 也支持在配置里显式声明：

{
  "options": { "skill-path": ["./other-skills"] }
}

或用环境变量 CRUSH_SKILLS_DIR 覆盖默认目录。我们不动你的 crush.json —— 四个自动发现目录已经够用。

更新 / 卸载 Copy Chapter

npx superpowers-zh --tool crush            # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall             # 卸载项目级
npx superpowers-zh --global --uninstall    # 卸载全局

卸载只删我们装进去的 skills，不会碰你的 crush.json。

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• Crush 仓库：https://github.com/charmbracelet/crush
• Crush skills 文档：https://charmbracelet-crush.mintlify.app/configuration/skills

File: docs/README.deepseek-harness.md Copy Chapter

Superpowers 中文版 — DeepSeek Harness 安装指南

在 DeepSeek Harness（dsh）中使用 superpowers-zh 的完整指南。

快速安装 Copy Chapter

cd /your/project
npx superpowers-zh              # 自动检测 .dsh/ 并安装

全局安装（所有项目共享）：

npx superpowers-zh --global --tool dsh

装到哪、为什么 Copy Chapter

四条路径全部取自官方仓库文档，不是猜的：

已经装过别的工具？可能已经生效了一半 Copy Chapter

dsh 的技能发现路径里 rank 200 是 .agents/skills —— 那正是 Antigravity 的项目级目录、也是 Codex CLI 的全局目录（~/.agents/skills）。如果你已经为这两款装过，dsh 已经能读到那批技能，不必重复装（重复装会加载两份）。

同理，dsh 的指令文件候选里包含 CLAUDE.md：装过 Claude Code 的项目，引导那一半已经生效。但 .claude/skills 不在 dsh 的技能根列表里，技能本身仍需按上面的路径安装。

手动安装 Copy Chapter

git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p .dsh/skills
cp -r superpowers-zh/skills/* .dsh/skills/

技能名必须是 kebab-case（官方约束：^[a-z0-9]+(?:-[a-z0-9]+)*$），本仓 21 个 skill 全部符合。

卸载 Copy Chapter

npx superpowers-zh --uninstall              # 项目级
npx superpowers-zh --global --uninstall     # 全局

只移除我们装的技能目录与 AGENTS.md 里哨兵注释包住的那一段，你自己写的内容不受影响。

相关 issue Copy Chapter

• #122 请求兼容 DeepSeek Harness

File: docs/README.deerflow.md Copy Chapter

[Binary file]

File: docs/README.gemini-cli.md Copy Chapter

Superpowers 中文版 — Gemini CLI 安装指南

在 Gemini CLI 中使用 superpowers-zh 的完整指南。

自动安装 Copy Chapter

cd /your/project
npx superpowers-zh

安装脚本会自动检测 .gemini/ 目录并将 skills 复制到 .gemini/skills/ 目录。

手动安装 Copy Chapter

git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.gemini/skills

或作为 Gemini 扩展安装（全局）：

mkdir -p ~/.gemini/extensions/superpowers-zh/skills
cp -r superpowers-zh/skills/* ~/.gemini/extensions/superpowers-zh/skills/
cp superpowers-zh/gemini-extension.json ~/.gemini/extensions/superpowers-zh/

通过 GEMINI.md 引用 Copy Chapter

在项目根目录的 GEMINI.md 中引用 skills：

# 工作方法论

请参考 .gemini/skills/ 目录中的 SKILL.md 文件。
遇到新功能开发时，先使用 brainstorming skill。
编写代码时，遵循 test-driven-development skill。

Skill 加载优先级 Copy Chapter

故障排查 Copy Chapter

Skills 未生效 Copy Section

1. 确认 .gemini/skills/ 目录存在且包含 skill 文件夹
2. 每个 skill 需要包含有效 YAML frontmatter 的 SKILL.md 文件
3. 重启 Gemini CLI

扩展模式未加载 Copy Section

1. 检查 gemini-extension.json 是否正确放在扩展目录中
2. 确认扩展目录结构：~/.gemini/extensions/superpowers-zh/

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• 项目主页：https://github.com/jnMetaCode/superpowers-zh
• Gemini CLI 文档：https://github.com/google-gemini/gemini-cli

File: docs/README.hermes.md Copy Chapter

[Binary file]

File: docs/README.kilocode.md Copy Chapter

Superpowers 中文版 — Kilo Code 安装指南

在 Kilo Code（VS Code AI 编程扩展 / CLI）中使用 superpowers-zh 的完整指南。

快速安装 Copy Chapter

cd /your/project
npx superpowers-zh --tool kilocode

自动检测：项目里存在 .kilocode/、.kilo/ 或 kilo.jsonc 任一时会自动装 Kilo Code。

装完会得到：

.kilocode/skills/         # 21 个 skill 本体，按需读取
.kilocode/rules/
└── superpowers-zh.md     # 一份小索引，自动生效

工作原理 Copy Chapter

Kilo Code 加载的是 Rules（规则会并入 system prompt），不是懒加载的 skills。所以和 Cline 同理：不能把 21 个 SKILL.md 直接塞进 rules 目录，否则每轮对话都背着巨大的常驻开销。

superpowers-zh 的做法：

为什么用 `.kilocode/rules/` 而不是新版的 `kilo.jsonc` Copy Chapter

Kilo Code 从 Roo 衍生的 v5 迁到了基于 OpenCode 的 v7，配置方式变了：

我们选 .kilocode/rules/，原因是不改你的 kilo.jsonc：

1. 官方明确 .kilocode/rules/ 向后兼容，无需任何配置即生效；
2. kilo.jsonc 是带注释的 JSONC，安装脚本要安全合并它很容易把你的配置改坏；
3. 那是你的配置文件，装个 skills 框架不该动它。

如果你想迁到 v7 的方式 Copy Section

手动加一行即可（把现有规则文件挪到 .kilo/rules/ 并登记）：

{
  "instructions": [".kilo/rules/superpowers-zh.md"]
}

改完 kilo.jsonc 后新开一个会话才会生效。

⚠️ 需要说明的是：.kilocode/rules/ 的兼容性来自官方文档中「现有规则会继续工作」的表述。若你在 v7 上装完发现索引 rule 没被加载，按上面的方式迁到 .kilo/rules/ + kilo.jsonc，并欢迎来 issue 里反馈，我们会据此调整默认路径。

手动安装 Copy Chapter

git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.kilocode/skills /your/project/.kilocode/rules
cp -r superpowers-zh/skills/* /your/project/.kilocode/skills/

索引 rule 建议交给 npx 生成 —— 它是按 skills 的 frontmatter 自动拼的，手写容易漏。

关于全局安装 Copy Chapter

--global 对 Kilo Code 不支持：它的全局规则同样要走 kilo.jsonc 登记，没有「复制到某个用户级目录就生效」的通用路径。请用项目级安装。

更新 / 卸载 Copy Chapter

npx superpowers-zh --tool kilocode   # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall       # 卸载，同时清掉 .kilocode/rules/superpowers-zh.md

获取帮助 Copy Chapter

• 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
• Kilo Code 自定义规则文档：https://kilo.ai/docs/customize/custom-rules

File: docs/README.kimi.md Copy Chapter

Superpowers 中文版 · Kimi Code 指南

在 Kimi Code 上使用 superpowers-zh 的完整说明。

安装 Copy Chapter

superpowers-zh 通过 Kimi Code 的插件清单 .kimi-plugin/plugin.json 集成，直接指向仓库现有的 skills/ 目录——不复制 skill、不建 symlink、不装 hook、无任何运行时依赖。

打开插件管理器：

/plugins

如果 Kimi 插件市场已收录，进入 Marketplace > Superpowers 中文版 安装即可。

也可以直接从本仓库安装：

/plugins install https://github.com/jnMetaCode/superpowers-zh

如需验证尚未发布的改动，显式指定分支：

/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main

Kimi Code 在新会话才会应用插件变更。安装、更新、启用、禁用或重载插件后，用 /new 开一个新会话。

工作原理 Copy Chapter

Kimi 插件清单位于 .kimi-plugin/plugin.json，做三件事：

1. 把 Kimi Code 指向仓库现有的 skills/ 目录；
2. 通过 sessionStart.skill 在会话开始时加载 using-superpowers（这是让 skill 在恰当时机自动触发的关键）；
3. 通过 skillInstructions 提供 Kimi 专属的工具映射。

工具映射 Copy Chapter

skill 内容描述的是「动作」而非写死某个运行时的工具名。在 Kimi Code 上它们对应到：

• 「向用户提问」/「问澄清问题」/「给出多选项」→ AskUserQuestion
• 「创建待办」/「在待办清单中标记完成」→ TodoList
• 「分派子智能体」/「Task tool (general-purpose)」→ Agent（用 Kimi 的 subagent 类型，如 coder/explore/plan，不要传 general-purpose）
• 「调用某个 skill」→ Kimi Code 原生 Skill 工具
• 「读文件」/「写文件」/「改文件」→ Read / Write / Edit
• 「跑 shell 命令」→ Bash
• 「搜索文件内容」→ Grep
• 「按路径/模式找文件」→ Glob
• 「抓取 URL」→ FetchURL
• 「联网搜索」→ WebSearch

完整映射写在清单的 skillInstructions 字段里，由 Kimi 在运行时读取。

更新 Copy Chapter

用 Kimi Code 的插件管理器：

/plugins

选中 Superpowers 中文版更新，更新后用 /new 开新会话。

排错 Copy Chapter

插件没加载 Copy Section

1. 跑 /plugins info superpowers-zh 看诊断信息；
2. 确认插件已启用；
3. 安装或更新后用 /new 开新会话。

直接 GitHub 安装装到了旧版本 Copy Section

对于裸仓库 URL，Kimi Code 会装最新的 GitHub release（若存在）。要在下一个 release 前测试未发布的改动，显式指定分支：

/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main

skill 不触发 Copy Section

1. 用 /plugins info superpowers-zh 确认插件已启用；
2. 用 /new 开新会话；
3. 试验收提示词：我们来做个 react todo list。集成正常的话，会在写任何代码之前先加载 brainstorming。

File: docs/README.kiro.md Copy Chapter

[Binary file]

File: docs/README.openclaw.md Copy Chapter

[Binary file]

File: docs/README.opencode.md Copy Chapter

Superpowers 中文版 — OpenCode 安装指南

在 OpenCode.ai 中使用 superpowers-zh 的完整指南。

安装 Copy Chapter

OpenCode V2 需要 2.0.4 或更高版本。

OpenCode V1 Copy Section

在 opencode.json（全局或项目级）的 plugin 数组中添加：

{
  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
}

OpenCode V2（2.0.4 或更高版本） Copy Section

使用 V2 插件配置（注意键名是 plugins）：

{
  "plugins": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
}

如果是 V2 的本地安装，配置的应当是包含 index.js 的仓库目录。OpenCode 2.0.4 和 2.0.7 会拒绝直接配置成 JavaScript 文件路径。通过自动发现找到的插件符号链接仍然受支持。

重启 OpenCode。V2 使用 opencode 命令；opencode2 可能作为别名可用。插件会通过 OpenCode 的插件管理器安装，并注册所有 skills。

验证方式：问 "告诉我你有哪些 superpowers"

从旧版符号链接安装方式迁移（V1） Copy Section

如果你之前使用 git clone 和符号链接安装过 superpowers，请移除旧的配置：

# 移除旧的符号链接
rm -f ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers

# 可选：移除克隆的仓库
rm -rf ~/.config/opencode/superpowers

# 如果你在 opencode.json 中为 superpowers 添加过 skills.paths，请将其移除

然后按照上面的安装步骤操作。

使用 Copy Chapter

查找 Skills Copy Section

使用 OpenCode 原生的 skill 工具列出所有可用 skills：

use skill tool to list skills

加载 Skill Copy Section

use skill tool to load brainstorming

个人 Skills Copy Section

在 ~/.config/opencode/skills/ 中创建你自己的 skills：

mkdir -p ~/.config/opencode/skills/my-skill

创建 ~/.config/opencode/skills/my-skill/SKILL.md：

---
name: my-skill
---

# 我的 Skill

[你的 skill 内容]

项目 Skills Copy Section

在项目的 .opencode/skills/ 目录中创建项目级 skills。

V2 的 Skill 优先级： 项目 skills > 个人 skills > Superpowers skills。在实测的 V1 1.18.31 上，当个人或项目 skill 与自带的 Superpowers skill 同名时，Superpowers 的那个优先；个人和项目 skill 请使用不同的名字。这次迁移没有改变这一行为。

更新 Copy Chapter

OpenCode 通过一个基于 git 的包说明（package spec）安装 Superpowers。有些 OpenCode 和 Bun 版本会把解析出的 git 依赖锁定在 lockfile 或缓存里，所以重启不一定能拿到 Superpowers 的最新提交。如果更新没有生效，清掉 OpenCode 的包缓存，或重新安装插件。

要固定到特定版本，在包说明后面加上标签或提交（V1 的 plugin 键和 V2 的 plugins 键写法相同）：

{
  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git#v1.7.14"]
}

在 V2 上，要固定到包含 V2 插件的版本（v1.7.13 之后的版本）；v1.7.13 及更早的发布只能在 V1 上加载。

工作原理 Copy Chapter

插件做两件事，按 OpenCode 的版本使用各自的 API：

1. 注册 skills 目录，让 OpenCode 无需符号链接或手动配置就能发现所有 superpowers skills。
   • V1： 通过 config hook，注入到 config.skills.paths
   • V2： 通过 setup() 函数，使用 ctx.skill.transform()（V2 原生 API，已确认运行时生效）
2. 注入引导上下文，附带按版本区分的工具映射：V1 会话拿到下面的 V1 工具名，V2 会话拿到 V2 工具名。
   • V1： 通过 experimental.chat.messages.transform hook
   • V2： 通过 ctx.session.hook("context")——V2 中的对应机制（已确认运行时生效）

控制者会话会在临时的模型上下文里收到 using-superpowers 引导内容。被委派出去的子会话仍能使用原生 skills，但不会收到控制者的引导内容。没有父会话的手动 fork 保持控制者行为。当 V2 原生压缩保留了较早的用户消息时（默认的 compaction.keep.tokens 预算），引导内容会放进检查点之前保留下来的第一条用户消息里，和未压缩的会话一样。当压缩移除了所有用户消息时，插件会在检查点之后追加一条临时的引导消息。无论哪种情况，保存的历史都不会改变。

如果会话查询失败，插件会在这次请求里保留引导内容，并在下一次请求时重试。查询失败不会被缓存成控制者判定。

工具映射 Copy Section

Skill 用动作来表述，而不是点名某一个运行时的工具。引导内容会把这些动作映射到你所用的 OpenCode 版本实际提供的工具上。

V1（opencode 1.x）：

• 「创建一条待办」/「在待办列表里标记完成」→ todowrite
• Subagent (general-purpose): 模板 → OpenCode 的 task 工具，传 subagent_type: "general"（探索代码库时用 "explore"）
• 「调用一个 skill」→ OpenCode 的原生 skill 工具
• 「读取文件」→ read
• 「创建文件」/「编辑文件」/「删除文件」→ apply_patch
• 「运行 shell 命令」→ bash
• 「搜索文件内容」/「按文件名查找」→ grep、glob
• 「抓取 URL」→ webfetch

V2（opencode 2.0.4 或更高版本；opencode2 可能作为别名可用）：

• 「创建一条待办」→ V2 没有任何形式的待办工具；映射会让模型改为在一个 markdown 文件（或运行环境自带的计划功能）里跟踪计划
• Subagent (general-purpose): 模板 → OpenCode 的 subagent 工具，传 agent: "general"（或 "explore"）；传 sessionID 可以继续之前的子智能体
• 「调用一个 skill」→ OpenCode 的原生 skill 工具
• 「读取文件」→ read
• 「创建、编辑或删除文件」→ 有 patch 时用 patch 并传 patchText；否则用 write 创建或覆盖文件、edit 做定点修改、shell 删除文件
• 「运行 shell 命令」→ shell（command、workdir、timeout、background）
• 「搜索文件内容」/「按文件名查找」→ grep、glob
• 「抓取 URL」→ webfetch
• 「搜索网络」→ websearch

简单说，V2 把 task 改名为 subagent（智能体名称从 subagent_type 挪到了 agent，继续会话改为带 sessionID 重新调用），apply_patch 改名为 patch，bash 改名为 shell，并且完全去掉了待办工具。可用的写入类工具取决于所选模型：patch 只对选定的 GPT 模型 ID 可用，其他模型使用 write 和 edit。

（V1 清单已对照安装好的 OpenCode 1.18.x CLI 的工具清单核实；V2 清单已对照 OpenCode 2.0.4 和 2.0.7 的宿主契约核实。以上核实由上游 obra/superpowers 完成。）

故障排查 Copy Chapter

插件未加载 Copy Section

V1： 检查 OpenCode 日志：

opencode run --print-logs "hello" 2>&1 | grep -i superpowers

V2： 插件在后台服务进程里加载，它的日志只有加上 --standalone 时 --print-logs 才会显示：

opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers

或者查看 ~/.local/share/opencode/log/opencode.log，过滤 role=server。

同时确认 opencode.json 中的插件路径正确，并且运行的是较新版本的 OpenCode。

Windows 安装问题 Copy Section

部分 Windows 版 OpenCode 对基于 git 的插件说明存在上游安装器问题，包括 git+https URL 的缓存路径问题，以及 Bun 找不到 git.exe（即使它在普通终端里能用）。如果 OpenCode 装不上插件，可以试试用系统的 npm 安装，再让 OpenCode 指向本地包：