Doramagic.ai
English

Doramagic 项目包 · 项目说明书

superpowers 项目

superpowers 是一个面向「软件开发与交付」的开源项目，重点覆盖 宿主能力扩展；Doramagic 已整理安装入口、说明书、上下文包和风险边界，方便先判断再试用。

Repository Overview and Architecture

Superpowers 是一个面向多种 AI 编码代理（Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Antigravity、Pi Agent 等）的可插拔技能（Skills）框架与代理协作工作流。项目本身并不是一个独立应用，而是以插件/技能包的形式分发，让宿主代理在对话启动、规划、编码、评...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 技能链：brainstorming → writing-plans → executing-plans

继续阅读本节完整说明和来源证据。

章节 3.2 子代理驱动开发（subagent-driven-development）

继续阅读本节完整说明和来源证据。

章节 3.3 内联自评审（v5.0.6 引入）

继续阅读本节完整说明和来源证据。

仓库概览与架构

一、项目定位与目标

Superpowers 是一个面向多种 AI 编码代理（Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Antigravity、Pi Agent 等）的可插拔技能（Skills）框架与代理协作工作流。项目本身并不是一个独立应用，而是以插件/技能包的形式分发，让宿主代理在对话启动、规划、编码、评审等阶段具备一致的工作流约束 资料来源：README.md:1-40。

核心目标包括：

  • 流程一致性：通过 brainstorming → writing-plans → executing-plans 三段式技能串联，让不同代理共享同一套工程方法论 资料来源：CHANGELOG.md:1-30]。
  • 跨代理可移植：同一套技能可在多个宿主代理之间复用，通过 AGENTS.md、CLAUDE.md、GEMINI.md 等宿主说明文件做适配 资料来源：AGENTS.md:1-20]。
  • 可观测的钩子层：在会话开始时注入上下文（SessionStart Hook），并通过事件钩子协调子代理分发 资料来源：hooks/hooks.json:1-40。

二、整体架构

整个仓库围绕"宿主代理 → 技能注册表 → 会话钩子 → 子代理工作流"四条主线组织。下面的架构图展示了主要组件及其关系。

graph TB
  Host[宿主代理<br/>Claude Code / Codex / Gemini / Copilot]
  Hook[SessionStart Hook<br/>hooks/hooks.json]
  Skills[技能注册表<br/>skills/*.md]
  Brain[Brainstorming 服务<br/>server.cjs]
  Plan[writing-plans]
  Exec[executing-plans]
  Sub[subagent-driven-development]

  Host -->|会话启动| Hook
  Hook -->|注入 bootstrap 上下文| Host
  Host -->|调用技能| Skills
  Skills --> Brain
  Skills --> Plan
  Skills --> Exec
  Skills --> Sub
  Brain -->|MCP/HTTP| Host
  Sub -->|分发子代理| Host

组件职责一览 资料来源：hooks/hooks.json:1-60]：

组件路径职责
会话钩子hooks/hooks.json监听宿主事件，按环境变量（COPILOT_CLI 等）下发 additionalContext
技能清单skills/存放可被宿主调用的技能脚本与提示词
头脑风暴服务skills/brainstorming/server.cjs与宿主通过本地服务交互，承载长流程对话
代理适配文档AGENTS.md / CLAUDE.md / GEMINI.md针对不同宿主的入口说明
元信息package.json声明 npm 类型（"type": "module"），影响 require() 行为

三、核心工作流

3.1 技能链：`brainstorming` → `writing-plans` → `executing-plans`

这是 Superpowers 默认推荐的三段式流程。在 v5.1.0 中，旧的 /brainstorm、/write-plan、/execute-plan 斜杠命令被彻底移除，要求直接调用对应技能以避免歧义 资料来源：CHANGELOG.md:5-20。社区反馈（如 #756）也表明，保留已弃用命令会令新用户产生困惑，因此当前仓库只保留"技能直调"这一种入口。

3.2 子代理驱动开发（subagent-driven-development）

subagent-driven-development 技能用于将一个复杂任务拆分给多个子代理并行执行。它通过调度模板指定"工作代理类型"来实现分发，但当前实现不会在派发点强制覆盖模型选择，子代理会继承父代理的模型 资料来源：#1631。这意味着模型选型建议（如"按角色使用最弱可用模型"）只能靠规约遵守，而非运行时强制。社区也已提出"跨任务累积学习并下发给后续子代理"的增强需求 资料来源：#601。

3.3 内联自评审（v5.0.6 引入）

brainstorming 与 writing-plans 此前依赖一个独立的子代理评审循环，但回归测试显示该循环使端到端耗时翻倍（≈25 分钟开销）且未带来可测量的质量提升，因此 v5.0.6 改为内联自评审 资料来源：CHANGELOG.md:30-60]。

四、宿主适配与扩展性

Superpowers 通过"一份技能 + 多份宿主说明"的模式实现跨代理复用：

  • AGENTS.md：通用代理入口说明 资料来源：AGENTS.md:1-20。
  • CLAUDE.md：Claude Code 专属入口说明 资料来源：CLAUDE.md:1-20。
  • GEMINI.md：Gemini CLI 专属入口说明 资料来源：GEMINI.md:1-20。
  • GitHub Copilot CLI：v5.0.7 起，SessionStart 钩子会检测 COPILOT_CLI 环境变量，并以 SDK 标准的 {"additionalContext":"..."} 格式下发 bootstrap 上下文 资料来源：CHANGELOG.md:80-110。

社区已请求更多宿主支持，包括 Hermes Agent 资料来源：#1581、Antigravity 2.0 资料来源：#1636、Pi Agent 资料来源：#1685 等。这些适配通常只需要在钩子层和宿主说明文档两端同时扩展即可完成。

五、已知限制与失败模式

现象触发条件临时方案
brainstorming 服务启动失败Node.js 22+ + 根 package.json 为 "type":"module"，导致 require() 报错v5.0.5 已将 server.js 重命名为 server.cjs 资料来源：CHANGELOG.md:60-80
父代理模型被子代理继承subagent-driven-development 派发时未指定模型显式在调度模板中写入目标模型 资料来源：#1631
docs/superpowers/ 内部计划误入正式文档默认输出位置与 Sphinx/Read the Docs 收集路径重叠调整计划输出目录 资料来源：#1690
计划过度规约writing-plans 给执行者留的判断空间过小精简计划中的实现细节 资料来源：#895

六、版本节奏

  • v5.0.5 — 修复 brainstorming 服务 ESM 加载与 Windows 进程监控 资料来源：CHANGELOG.md:60-80]。
  • v5.0.6 — 用内联自评审替换子代理评审循环 资料来源：CHANGELOG.md:30-60]。
  • v5.0.7 — 新增 GitHub Copilot CLI 的 additionalContext 注入 资料来源：CHANGELOG.md:80-110]。
  • v5.1.0 — 移除遗留斜杠命令与 superpowers:code-reviewer 命名代理 资料来源：CHANGELOG.md:1-30。

See Also

  • Brainstorming 技能设计
  • Writing-Plans 与 Executing-Plans 工作流
  • Subagent-Driven-Development 模型与调度
  • 宿主代理适配清单（Claude / Codex / Gemini / Copilot）

来源：https://github.com/obra/superpowers / 项目说明书

Skills Library and Core Workflow

Superpowers 是一个面向编码代理（coding agent）的技能（skill）集合与协作工作流框架，其核心思想是：在代理开始任何实质性工作之前，先通过一套结构化技能引导其完成"理解 → 构思 → 规划 → 执行 → 验证"的完整闭环。using-superpowers 技能是整个体系的入口点，它要求代理在每次会话开始时识别所有可用的相关技能，并按需加载 资料来源...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 头脑风暴（Brainstorming）

继续阅读本节完整说明和来源证据。

章节 编写计划（Writing Plans）

继续阅读本节完整说明和来源证据。

章节 执行计划（Executing Plans）

继续阅读本节完整说明和来源证据。

技能库与核心工作流

概述

Superpowers 是一个面向编码代理（coding agent）的技能（skill）集合与协作工作流框架，其核心思想是：在代理开始任何实质性工作之前，先通过一套结构化技能引导其完成"理解 → 构思 → 规划 → 执行 → 验证"的完整闭环。using-superpowers 技能是整个体系的入口点，它要求代理在每次会话开始时识别所有可用的相关技能，并按需加载 资料来源：skills/using-superpowers/SKILL.md:1-30。

技能库中的每个技能都是一个独立的目录，包含 SKILL.md（技能说明文档）、可能的辅助脚本与提示模板。brainstorming、writing-plans、executing-plans 构成了核心三段式工作流，而 using-git-worktrees、subagent-driven-development、test-driven-development 等则是辅助性技能，用于在不同代理平台（Claude Code、Copilot CLI、Hermes 等）下保证工作流的一致性。

核心工作流的三个阶段

Superpowers 的核心工作流通过三个互相衔接的技能定义了整个开发循环：先发散、再收敛、最后落地。

flowchart LR
    A[用户提出需求] --> B[brainstorming<br/>头脑风暴]
    B --> C[writing-plans<br/>编写实施计划]
    C --> D[executing-plans<br/>执行计划]
    D --> E[验证与回顾]
    E --> F{新需求?}
    F -->|是| B
    F -->|否| G[完成]

头脑风暴（Brainstorming）

brainstorming 技能的目标是在编写任何代码或计划之前，与用户共同明确"真正要解决的问题是什么"。它通过引导式提问收集约束、边界与成功标准，并使用本地 Web 服务器（scripts/server.cjs）将协作上下文以可视化方式呈现给用户 资料来源：skills/brainstorming/SKILL.md:1-50。visual-companion.md 描述了配套的视觉辅助界面，用于在多代理协作场景下保持信息同步 资料来源：skills/brainstorming/visual-companion.md:1-20。

社区关注点：在 v5.0.5 中，服务器脚本从 server.js 重命名为 server.cjs 以修复 Node.js 22+ 下 ESM/require() 冲突问题（参见 issue #774）。

编写计划（Writing Plans）

在头脑风暴收敛出明确目标后，writing-plans 技能会生成一份结构化的实施计划文档。该技能强调"计划不应过度规定实现细节"——这是社区长期讨论的痛点（参见 issue #895）。计划应描述任务序列、验收标准、依赖关系与回滚路径，为执行者保留合理的判断空间 资料来源：skills/writing-plans/SKILL.md:1-60。

plan-document-reviewer-prompt.md 提供了一个独立于 v5.0.6 之前旧"子代理评审循环"的审查提示模板，使代理能够以内联自审（inline self-review） 的方式对计划文档进行质量校验，从而在 v5.0.6 中替代了耗时约 25 分钟但未显著提升质量的子代理评审流程 资料来源：skills/writing-plans/plan-document-reviewer-prompt.md:1-40。

社区关注点：默认计划输出目录 docs/superpowers/ 可能在基于 Sphinx/Read the Docs 的发布流水线中泄漏内部计划（参见 issue #1690）。

执行计划（Executing Plans）

executing-plans 技能将计划文档转化为可追踪的增量任务。执行者应：

  1. 按计划顺序完成任务，每完成一项立即提交；
  2. 在偏离计划时主动与用户确认；
  3. 将执行过程中产生的"经验"反馈回项目记忆（参见 issue #551 提出的跨会话记忆系统需求） 资料来源：skills/executing-plans/SKILL.md:1-50。

支撑性技能

Git Worktrees 隔离

using-git-worktrees 技能建议在执行计划前为任务创建独立的 Git worktree，使计划执行与主分支隔离，避免半成品污染主干 资料来源：skills/using-git-worktrees/SKILL.md:1-30。

子代理驱动开发

subagent-driven-development 技能针对复杂任务将工作分派给子代理。它推荐"使用能胜任该角色的最弱模型"，但社区发现该建议在分派点并未被强制执行，子代理会继承父代理的模型（参见 issue #1631）。此外，跨子代理积累学习成果的机制也是热门需求（参见 issue #601） 资料来源：skills/subagent-driven-development/SKILL.md:1-40。

平台适配与已知差异

Superpowers 通过 SessionStart 钩子向不同代理平台注入引导上下文。v5.0.7 起，钩子会检测 COPILOT_CLI 环境变量，并以 SDK 标准的 { "additionalContext": "..." } 格式向 GitHub Copilot CLI 输出，从而使其获得与 Claude Code 同等的引导能力 资料来源：skills/using-superpowers/SKILL.md:50-80。

下表总结了主要平台的支持矩阵（基于社区 issue 与发布说明整理）：

平台引导机制已知限制
Claude Code原生插件 + SessionStart 钩子Agent Teams（TeammateTool）支持尚未完成（#429）
GitHub Copilot CLIadditionalContext 注入需 CLI ≥ v1.0.11
Google Antigravity需通过 shell 函数桥接官方包未发布（#270、#1636）
Hermes Agent请求中暂无原生包（#1581）
Pi Agent请求中暂无原生包（#1685）
破坏性变更提示：v5.1.0 已移除 /brainstorm、/execute-plan、/write-plan 等遗留斜杠命令以及 superpowers:code-reviewer 具名代理，请直接调用 superpowers:brainstorming、superpowers:executing-plans、superpowers:writing-plans 技能。

常见失败模式

  1. 跳过 brainstorming 直接进入计划：导致计划文档基于模糊目标，难以验收 资料来源：skills/brainstorming/SKILL.md:1-15。
  2. 计划过度规定实现细节：剥夺了执行者的判断空间，可能因环境差异频繁返工（参见 issue #895）。
  3. 遗留斜杠命令混淆：v5.1.0 之前安装的版本会同时显示新旧命令，新用户难以分辨（参见 issue #756）。
  4. 跨会话知识丢失：当前无内置的项目记忆系统，子代理每次启动都是"冷启动"（参见 issue #551）。

参见

  • Subagent Driven Development
  • Brainstorming Server Internals
  • Platform Integration Matrix
  • Release Notes v5.x

来源：https://github.com/obra/superpowers / 项目说明书

Multi-Harness Installation and Integration

Superpowers 是一套面向 AI 编码代理（coding agent）的可复用技能（skills）与工作流集合，本身并不绑定某一个客户端。仓库通过并列的多个插件目录，把同一套 skills 同时分发到不同的 AI 编码客户端（即"harness"），从而实现在不同 IDE / CLI 中复用同一份能力。资料来源：[README.md:1-40]()。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Claude Code

继续阅读本节完整说明和来源证据。

章节 Codex

继续阅读本节完整说明和来源证据。

章节 Cursor

继续阅读本节完整说明和来源证据。

多客户端（Harness）安装与集成

概述

Superpowers 是一套面向 AI 编码代理（coding agent）的可复用技能（skills）与工作流集合，本身并不绑定某一个客户端。仓库通过并列的多个插件目录，把同一套 skills 同时分发到不同的 AI 编码客户端（即"harness"），从而实现在不同 IDE / CLI 中复用同一份能力。资料来源：README.md:1-40。

当前仓库内置的 harness 集成至少包括 Claude Code、Codex、Cursor、OpenCode 与 GitHub Copilot CLI，每个 harness 都对应一个独立的插件清单目录。

支持的 Harness 集成

Claude Code

Claude Code 通过 .claude-plugin/ 目录发布。marketplace.json 声明该插件在官方 Claude 插件市场中的注册信息，plugin.json 则描述插件的入口、版本与组件列表。资料来源：.claude-plugin/marketplace.json:1-30、 .claude-plugin/plugin.json:1-20。社区反馈显示新装用户曾看到已弃用的斜杠命令，v5.1.0 已彻底移除 /brainstorm、/execute-plan、/write-plan 等遗留命令，需直接调用 superpowers:brainstorming 等 skill。资料来源：v5.1.0 release notes。

Codex

Codex 客户端通过 .codex-plugin/ 目录加载，根级的 plugin.json 描述能力清单，使 Codex 能在不感知其他 harness 存在的情况下加载同一套 skills。资料来源：.codex-plugin/plugin.json:1-20。

Cursor

Cursor 通过 .cursor-plugin/ 集成，其 plugin.json 与上述 harness 保持一致的元数据结构，从而保证 skill 在 Cursor 内以同等形式被检索和执行。资料来源：.cursor-plugin/plugin.json:1-20。

OpenCode

OpenCode 的安装说明集中在 .opencode/INSTALL.md，运行时代码为 .opencode/plugins/superpowers.js。该 harness 使用 JavaScript 插件形态而非静态 JSON 清单，因此支持更灵活的事件钩子与会话注入。资料来源：.opencode/INSTALL.md:1-40、 .opencode/plugins/superpowers.js:1-60。

GitHub Copilot CLI

Copilot CLI 在 v5.0.7 起获得完整支持：session-start 钩子会检测 COPILOT_CLI 环境变量，并以 SDK 标准的 { "additionalContext": "..." } 格式输出，使 Copilot CLI 用户获得与 Claude Code 等价的 Superpowers 启动上下文注入。资料来源：v5.0.7 release notes、 .github-plugin/plugin.json:1-20。

实验 / 第三方 Harness

社区中已出现针对 Hermes Agent（Issue #1581）、Google Antigravity（Issue #1636、#270）、Pi Agent（Issue #1685）等客户端的支持请求。这些 harness 暂未合并进主干，但通常可以借助通用插件机制或 shell 函数桥接的方式接入。资料来源：Issue #1581、 Issue #1636、 Issue #1685。

整体架构

graph LR
    Repo["obra/superpowers 仓库"] --> Skills["skills/<br/>核心技能与工作流"]
    Repo --> C[".claude-plugin/"]
    Repo --> X[".codex-plugin/"]
    Repo --> Cu[".cursor-plugin/"]
    Repo --> O[".opencode/"]
    Repo --> Gh[".github-plugin/"]
    C --> Claude["Claude Code"]
    X --> Codex["Codex"]
    Cu --> Cursor["Cursor"]
    O --> OpenCode["OpenCode"]
    Gh --> Copilot["GitHub Copilot CLI"]

各 harness 目录只包含适配层（清单 + 钩子脚本），核心逻辑全部集中在 skills/，因此新增一个 harness 只需要新增一个适配目录并复用 skills/。

安装方式对比

Harness安装形态主要文件触发方式
Claude Code插件市场.claude-plugin/plugin.json/plugin install
Codex本地插件目录.codex-plugin/plugin.json客户端自动发现
Cursor插件清单.cursor-plugin/plugin.json客户端自动发现
OpenCodeJS 插件.opencode/plugins/superpowers.js引用 INSTALL.md
Copilot CLI钩子 + 环境变量.github-plugin/plugin.json检测 COPILOT_CLI

资料来源：.claude-plugin/plugin.json:1-20、 .codex-plugin/plugin.json:1-20、 .cursor-plugin/plugin.json:1-20、 .opencode/INSTALL.md:1-40、 .github-plugin/plugin.json:1-20。

常见问题与规避

  • 弃用命令残留：v5.1.0 之前的版本会在 Claude Code 中出现 /brainstorm 等已弃用命令并与新命令并存，升级到 v5.1.0 即可彻底消除。资料来源：Issue #756、 v5.1.0 release notes。
  • Antigravity 接入：官方未提供原生集成，社区中可通过 shell 函数包装 agy 命令并强制注入 Superpowers 系统提示的方式实现。资料来源：Issue #270、 Issue #1636。
  • 新 harness 适配：先确认该客户端是否具备插件或钩子机制；若没有，可参考 Hermes Agent、Pi Agent 的 issue 中的讨论模式，通过包装脚本在每次会话开始时注入 Superpowers 上下文。

另请参阅

  • Skills 与工作流（skills/）
  • 写作计划 / 头脑风暴流程
  • v5.0.5 — v5.1.0 发布说明
  • Issue #429：Claude Code Agent Teams 协作支持
  • Issue #895：writing-plans 中过度指定实现细节的问题

资料来源：.claude-plugin/plugin.json:1-20、 .codex-plugin/plugin.json:1-20、 .cursor-plugin/plugin.json:1-20、 .opencode/INSTALL.md:1-40、 .github-plugin/plugin.json:1-20。

Operations, Releases, and Known Issues

本页面向运维人员、平台集成方与高级用户，介绍 superpowers 项目的发布流程、近期版本变更、测试与质量控制策略，并汇总社区已追踪的若干关键问题与跨平台支持情况，便于升级、回归测试与多代理运行时接入。

章节 相关页面

继续阅读本节完整说明和来源证据。

运维、发布与已知问题

本页面向运维人员、平台集成方与高级用户，介绍 superpowers 项目的发布流程、近期版本变更、测试与质量控制策略，并汇总社区已追踪的若干关键问题与跨平台支持情况，便于升级、回归测试与多代理运行时接入。

发布与版本管理

superpowers 的发布工作流由 scripts/bump-version.sh 脚本驱动，版本号配置由 .version-bump.json 维护。集中化的发布说明写入 RELEASE-NOTES.md，并以 GitHub Release 的形式发布（资料来源：scripts/bump-version.sh、.version-bump.json）。

当前最新发布版本为 v5.1.0（资料来源：GitHub Releases v5.1.0）。近期发布及其影响如下表所示：

版本类型关键变更对运维的影响
v5.1.0移除移除遗留斜杠命令 /brainstorm、/execute-plan、/write-plan；移除 superpowers:code-reviewer 命名代理旧调用路径将不再可用，需切换为 superpowers:brainstorming、superpowers:executing-plans、superpowers:writing-plans 技能
v5.0.7增强SessionStart 钩子检测 COPILOT_CLI 环境变量，按 SDK 标准发出 { "additionalContext": "..." }GitHub Copilot CLI 用户获得完整 superpowers 引导上下文
v5.0.6重构内联自审取代子代理审查循环平均节省约 25 分钟审查时间，质量评分在 5 版本×5 试验回归中保持一致
v5.0.5修复server.js → server.cjs（Node 22+ ESM 兼容）；Windows 跳过 PID 生命周期监控旧文件名在 ESM 模式下 require() 失败；Windows 路径不再误触发 PID 监控

资料来源：RELEASE-NOTES.md、GitHub Releases v5.0.5、GitHub Releases v5.0.6、GitHub Releases v5.0.7。

测试策略与质量控制

测试约定集中维护在 docs/testing.md 中，作为回归与 CI 流程的依据。v5.0.6 引入的"内联自审"机制替代了原先的"派发独立子代理进行计划/规格审查"循环：原方案令端到端执行时间翻倍，却未在 5 版本×5 试验的回归套件中产生可衡量的质量增益，因此被替换（资料来源：docs/testing.md、GitHub Releases v5.0.6）。

已知问题与社区反馈

社区通过 GitHub Issues 跟踪关键缺陷与功能请求，下述条目对运维有直接影响：

  • #1631 subagent-driven-development 模型选择未在 worker 派发处强制执行：调度模板仅按代理类型派发，子代理会继承父级模型而非推荐的最弱可用模型（资料来源：Issue #1631）。
  • #756 新安装包含已弃用斜杠命令，造成用户困惑：v5.1.0 已通过移除遗留命令解决，但运行 v5.0.x 的环境仍可能呈现此问题（资料来源：Issue #756）。
  • #1690 写作计划/头脑风暴默认 docs/superpowers/ 路径会泄漏到 Sphinx/Read the Docs 公开文档：使用 Read the Docs 的项目（如 okama）应将输出目录移出 docs/，避免内部计划被发布到公开站点（资料来源：Issue #1690）。
  • #1693 通过 OpenClaw 调用 oMLX v0.4.2.dev2 时报 "Native MTP is not enabled" 错误：与 MLX-VLM 运行时 MTP 补丁有关，checkpoint 未携带 mtp.* 权重时触发（资料来源：Issue #1693）。
  • #895 writing-plans 过度规范实现细节，留给执行者的判断空间不足：建议在生成阶段明确抽象层级，避免"逐行伪代码式"计划（资料来源：Issue #895）。
  • #551 跨会话项目记忆系统：当前缺少通用机制让代理在设计/实现前检索相关历史片段（资料来源：Issue #551）。
  • #601 subagent-driven-development 在任务间累积学习并喂给后续子代理：当前每个子代理从零开始，无法复用前序任务的发现（资料来源：Issue #601）。

跨平台与代理生态支持

项目以独立的"支持包"覆盖多家代理运行时：

  • GitHub Copilot CLI：v5.0.7 起通过 SDK 标准 additionalContext 字段在 sessionStart 钩子中下发 superpowers 引导（资料来源：GitHub Releases v5.0.7）。
  • OpenCode：设计文档与实现计划分别记录在 docs/plans/2025-11-22-opencode-support-design.md 与 docs/plans/2025-11-22-opencode-support-implementation.md（资料来源：opencode-support-design、opencode-support-implementation）。
  • Hermes Agent（#1581）、Antigravity 2.0（#1636）、Pi Agent（#1685）、Claude Code Agent Teams / TeammateTool（#429）：均处于社区请求阶段，需关注后续 PR 进展。

升级建议

从 v5.0.x 升级到 v5.1.0 时建议执行以下检查：

  1. 移除代码、脚本与文档中对已弃用斜杠命令（/brainstorm、/execute-plan、/write-plan）的引用，改为调用对应技能；
  2. 审阅内部对 superpowers:code-reviewer 的调用点，按需改为内联自审或显式技能调用；
  3. 确认 CI 与发布流水线中无对 server.js 的硬编码引用（v5.0.5 已更名为 server.cjs）；
  4. 在 Windows 环境下验证 brainstorm 服务器 PID 监控已正确跳过，避免误报进程退出。

另请参阅

  • RELEASE-NOTES.md
  • .version-bump.json
  • scripts/bump-version.sh
  • docs/testing.md
  • docs/plans/2025-11-22-opencode-support-design.md
  • docs/plans/2025-11-22-opencode-support-implementation.md
  • GitHub Issues 列表
  • GitHub Releases

资料来源：RELEASE-NOTES.md、GitHub Releases v5.0.5、GitHub Releases v5.0.6、GitHub Releases v5.0.7。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format

可能影响授权、密钥配置或安全边界。

high 来源证据：feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents

可能影响授权、密钥配置或安全边界。

medium 失败模式：installation: Antigravity 2.0 support

Developers may fail before the first successful local run: Antigravity 2.0 support

medium 失败模式：installation: Feature Request: Hermes Agent harness support — make Superpowers skills available in native H...

Developers may fail before the first successful local run: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format

Pitfall Log / 踩坑日志

项目：obra/superpowers

摘要：发现 26 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format。

1. 安全/权限坑 · 来源证据：Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_a8794497fd53411881056201b8d6df60 | https://github.com/obra/superpowers/issues/1581 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_ab70f8b1398247c2832ed51625870194 | https://github.com/obra/superpowers/issues/601 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 失败模式：installation: Antigravity 2.0 support

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: Antigravity 2.0 support
  • 对用户的影响：Developers may fail before the first successful local run: Antigravity 2.0 support
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Antigravity 2.0 support. Context: Observed during installation or first-run setup.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_3cd7252f6ca5743aa06793d8258fa9c7 | https://github.com/obra/superpowers/issues/1636 | Antigravity 2.0 support

4. 安装坑 · 失败模式：installation: Feature Request: Hermes Agent harness support — make Superpowers skills available in native H...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format
  • 对用户的影响：Developers may fail before the first successful local run: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format. Context: Observed when using python
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_38493ac5020594e127b9094db01ae917 | https://github.com/obra/superpowers/issues/1581 | Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format

5. 安装坑 · 失败模式：installation: Pi Agent package

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: Pi Agent package
  • 对用户的影响：Developers may fail before the first successful local run: Pi Agent package
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Pi Agent package. Context: Observed during installation or first-run setup.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_81abb08cf2718798d6bf3874d5ab48d6 | https://github.com/obra/superpowers/issues/1685 | Pi Agent package

6. 安装坑 · 失败模式：installation: v5.0.4

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: v5.0.4
  • 对用户的影响：Upgrade or migration may change expected behavior: v5.0.4
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v5.0.4. Context: Observed when using node
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_release | fmev_a66cfa915699950289e6adc9ba6aa7e3 | https://github.com/obra/superpowers/releases/tag/v5.0.4 | v5.0.4

7. 安装坑 · 失败模式：installation: v5.0.7

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: v5.0.7
  • 对用户的影响：Upgrade or migration may change expected behavior: v5.0.7
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v5.0.7. Context: Observed during installation or first-run setup.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_release | fmev_c82f72cff463c8cee7702417638522f8 | https://github.com/obra/superpowers/releases/tag/v5.0.7 | v5.0.7

8. 安装坑 · 来源证据：Feature Request: Add a core project memory system for cross-session retrieval and recording

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Add a core project memory system for cross-session retrieval and recording
  • 对用户的影响：可能影响升级、迁移或版本选择。
  • 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_92f8a9266fce437abbce3b0e8ae92679 | https://github.com/obra/superpowers/issues/551 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安装坑 · 来源证据：Pi Agent package

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pi Agent package
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_dc7595e0517f44b4b8f034a3891be1ba | https://github.com/obra/superpowers/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安装坑 · 来源证据：writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (S…

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (Sphinx/Read the Docs)
  • 对用户的影响：可能增加新用户试用和生产接入成本。
  • 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_1d7f3ffcaf6d457eaa212b6de6361956 | https://github.com/obra/superpowers/issues/1690 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 配置坑 · 可能修改宿主 AI 配置

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
  • 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
  • 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
  • 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
  • 证据：capability.host_targets | github_repo:1073224795 | https://github.com/obra/superpowers | host_targets=claude_code, claude, cursor, gemini_cli, codex, chatgpt

12. 配置坑 · 失败模式：configuration: An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw. Context: Observed when using macos
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_d81bff41370623c8daf4066025cfaf5e | https://github.com/obra/superpowers/issues/1693 | An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw

13. 配置坑 · 失败模式：configuration: v5.1.0

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: v5.1.0
  • 对用户的影响：Upgrade or migration may change expected behavior: v5.1.0
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v5.1.0. Context: Source discussion did not expose a precise runtime context.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_release | fmev_cfe36ffa6591177ed40166940fafd243 | https://github.com/obra/superpowers/releases/tag/v5.1.0 | v5.1.0

14. 配置坑 · 失败模式：configuration: writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (Sphinx/Read the Docs)
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (Sphinx/Read the Docs)
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (Sphinx/Read the Docs). Context: Observed when using python
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_2b4c6bebcd3bbc252b75d46bd85091a3 | https://github.com/obra/superpowers/issues/1690 | writing-plans/brainstorming: default docs/superpowers/ location can leak internal plans into published documentation (Sphinx/Read the Docs)

15. 能力坑 · 能力判断依赖假设

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：README/documentation is current enough for a first validation pass.
  • 对用户的影响：假设不成立时，用户拿不到承诺的能力。
  • 建议检查：将假设转成下游验证清单。
  • 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
  • 证据：capability.assumptions | github_repo:1073224795 | https://github.com/obra/superpowers | README/documentation is current enough for a first validation pass.

16. 运行坑 · 失败模式：runtime: v5.0.6

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this runtime risk before relying on the project: v5.0.6
  • 对用户的影响：Upgrade or migration may change expected behavior: v5.0.6
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v5.0.6. Context: Observed when using windows
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_release | fmev_7b0078c8854ff7385e460ca0414c7f37 | https://github.com/obra/superpowers/releases/tag/v5.0.6 | v5.0.6

17. 维护坑 · 维护活跃度未知

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：未记录 last_activity_observed。
  • 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
  • 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
  • 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
  • 证据：evidence.maintainer_signals | github_repo:1073224795 | https://github.com/obra/superpowers | last_activity_observed missing

18. 安全/权限坑 · 下游验证发现风险项

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：下游已经要求复核，不能在页面中弱化。
  • 建议检查：进入安全/权限治理复核队列。
  • 防护动作：下游风险存在时必须保持 review/recommendation 降级。
  • 证据：downstream_validation.risk_items | github_repo:1073224795 | https://github.com/obra/superpowers | no_demo; severity=medium

19. 安全/权限坑 · 存在评分风险

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：风险会影响是否适合普通用户安装。
  • 建议检查：把风险写入边界卡，并确认是否需要人工复核。
  • 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
  • 证据：risks.scoring_risks | github_repo:1073224795 | https://github.com/obra/superpowers | no_demo; severity=medium

20. 安全/权限坑 · 来源证据：An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：An error occurs when calling oMLX v0.4.2.dev2 via OpenClaw
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
  • 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
  • 证据：community_evidence:github | cevd_0c987b4a2f09486a98f35a913fb25ac9 | https://github.com/obra/superpowers/issues/1693 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

21. 能力坑 · 失败模式：capability: subagent-driven-development: Model Selection guidance is not enforced at worker dispatch, so...

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: subagent-driven-development: Model Selection guidance is not enforced at worker dispatch, so workers inherit the parent model
  • 对用户的影响：Developers may hit a documented source-backed failure mode: subagent-driven-development: Model Selection guidance is not enforced at worker dispatch, so workers inherit the parent model
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: subagent-driven-development: Model Selection guidance is not enforced at worker dispatch, so workers inherit the parent model. Context: Source discussion did not expose a precise runtime context.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_569481cf220459459d1ec73627ee6ac5 | https://github.com/obra/superpowers/issues/1631 | subagent-driven-development: Model Selection guidance is not enforced at worker dispatch, so workers inherit the parent model

22. 运行坑 · 失败模式：performance: Feature Request: Add a core project memory system for cross-session retrieval and recording

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this performance risk before relying on the project: Feature Request: Add a core project memory system for cross-session retrieval and recording
  • 对用户的影响：Developers may hit a documented source-backed failure mode: Feature Request: Add a core project memory system for cross-session retrieval and recording
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Add a core project memory system for cross-session retrieval and recording. Context: Source discussion did not expose a precise runtime context.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_5bc7a765569321677f3ea57b0b1b1e36 | https://github.com/obra/superpowers/issues/551 | Feature Request: Add a core project memory system for cross-session retrieval and recording

23. 运行坑 · 失败模式：performance: feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent s...

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this performance risk before relying on the project: feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents
  • 对用户的影响：Developers may hit a documented source-backed failure mode: feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents. Context: Source discussion did not expose a precise runtime context.
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_issue | fmev_c9e9c726023c531c730b3134c2c9b4f7 | https://github.com/obra/superpowers/issues/601 | feat(subagent-driven-development): accumulate learnings across tasks and feed to subsequent subagents

24. 维护坑 · issue/PR 响应质量未知

  • 严重度：low
  • 证据强度：source_linked
  • 发现：issue_or_pr_quality=unknown。
  • 对用户的影响：用户无法判断遇到问题后是否有人维护。
  • 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
  • 防护动作：issue/PR 响应未知时，必须提示维护风险。
  • 证据：evidence.maintainer_signals | github_repo:1073224795 | https://github.com/obra/superpowers | issue_or_pr_quality=unknown

25. 维护坑 · 发布节奏不明确

  • 严重度：low
  • 证据强度：source_linked
  • 发现：release_recency=unknown。
  • 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
  • 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
  • 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
  • 证据：evidence.maintainer_signals | github_repo:1073224795 | https://github.com/obra/superpowers | release_recency=unknown

26. 维护坑 · 失败模式：maintenance: v5.0.5

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v5.0.5
  • 对用户的影响：Upgrade or migration may change expected behavior: v5.0.5
  • 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v5.0.5. Context: Observed when using node, windows
  • 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
  • 证据：failure_mode_cluster:github_release | fmev_291da9532fcd017a534553db73fbf381 | https://github.com/obra/superpowers/releases/tag/v5.0.5 | v5.0.5

来源：Doramagic 发现、验证与编译记录