项目定位与核心价值

Superpowers 是一个面向编码代理（coding agents）的"技能与方法论"框架，由 obra 维护，目标是在多种 AI 编码环境中提供一套一致、可复用、经过实战验证的工作流。它不是一个独立的 LLM 应用，而是一组 Skills（技能）、Hooks（钩子） 与 Subagents（子代理） 的集合，可被 Claude Code、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Pi Agent、Antigravity 等多种宿主环境加载与调用。

项目的核心价值在于：

• 把已被验证有效的工程实践沉淀为 可被代理读取的 Markdown 技能说明，而非临时 prompt；
• 通过 SessionStart 钩子自动注入上下文，确保代理在每一次会话开始时都"知道"自己拥有哪些技能；
• 通过 superpowers:* 命名空间统一调度，使技能调用方式跨宿主平台保持一致。

资料来源：README.md:1-40

安装与宿主平台适配

Superpowers 的安装采用 宿主平台无关 的设计：根据不同 IDE / CLI 触发不同的钩子适配层。以 GitHub Copilot CLI 为例，session-start 钩子会检测 COPILOT_CLI 环境变量，并输出 SDK 标准的 { "additionalContext": "..." } 格式，让 Copilot CLI 用户获得完整的 Superpowers 引导信息。资料来源：docs/CHANGELOG.md:1-30

对于 Claude Code、Gemini CLI 等环境，仓库根目录提供了对应的宿主入口文件 CLAUDE.md 与 GEMINI.md，它们会在会话开始时被宿主加载为初始指令。AGENTS.md 则提供了跨平台的通用代理行为准则。资料来源：AGENTS.md:1-30、CLAUDE.md:1-30

下表列出当前主要支持的宿主平台与对应适配点：

资料来源：README.md:40-80、docs/CHANGELOG.md:20-60

方法论：技能驱动的开发流程

Superpowers 把整个软件交付流程拆解为若干 可独立调用的技能，每个技能对应一份 Markdown 文档，规定代理在该阶段应遵循的步骤、检查项与产出物。常见的核心技能包括：

• superpowers:brainstorming：在编码前澄清需求与约束，避免一上来就写代码；
• superpowers:writing-plans：将需求转化为可执行的实施计划；
• superpowers:executing-plans：按计划逐步执行并自检；
• superpowers:subagent-driven-development：把复杂任务派发给子代理，并按角色选用"最弱够用"的模型；
• superpowers:code-review：对变更进行结构化审查。

自 v5.1.0 起，旧的 /brainstorm、/execute-plan、/write-plan 斜杠命令被移除，因为它们只是指向对应技能的占位符；用户应直接调用 superpowers:brainstorming 等技能。资料来源：docs/CHANGELOG.md:1-30

v5.0.6 的一次重要方法论调整是 以"内联自审"取代"子代理评审循环"：原本会再派发一个全新代理来审阅计划/规格，实测中会让执行时间翻倍（约 +25 分钟），但对计划质量的可量化评分并无显著提升。因此现在改为由同一代理在产出阶段直接进行自我审查。资料来源：docs/CHANGELOG.md:30-60

子代理与跨会话记忆

subagent-driven-development 技能建议"按角色选择能胜任的最弱模型"，但在派发时该指引并未被强制实施，子代理会继承父代理的模型——这是社区当前关注的限制之一。资料来源：issues/1631

围绕子代理的另一个活跃议题是 跨任务/跨会话的学习积累：当前每个子代理都从零起步，无法复用先前子代理的发现。该功能请求提出把多次任务的成果汇总后注入到后续子代理，从而形成持续改进的反馈环。资料来源：issues/601

此外，社区正在讨论为整个项目引入 核心项目记忆系统，以便代理在新设计或实现前能自动检索到先前的小段历史信息，但该系统目前尚未纳入主分支。资料来源：issues/551

关键流程示意

flowchart LR
    A[SessionStart 钩子] --> B[检测宿主平台]
    B --> C{注入技能清单}
    C --> D[superpowers:brainstorming]
    D --> E[superpowers:writing-plans]
    E --> F[superpowers:executing-plans]
    F --> G{内联自审}
    G -->|通过| H[superpowers:code-review]
    G -->|未通过| F
    H --> I[可选: subagent-driven-development]

资料来源：README.md:1-60、docs/CHANGELOG.md:30-60

安装后常见问题

• 文档泄漏：默认计划存放目录为 docs/superpowers/，若项目同时使用 Sphinx/Read the Docs 发布文档，可能把内部计划一并发布。该问题可通过修改默认路径规避。资料来源：issues/1690
• Windows 兼容：v5.0.5 修复了脑暴服务器在 Node.js 22+ 因 package.json 中 "type": "module" 导致的 require() 失败，并将服务器入口重命名为 server.cjs。同时在 Windows 上跳过 PID 生命周期监控。资料来源：docs/CHANGELOG.md:60-80
• 平台未原生支持：若宿主平台（Hermes、Pi Agent、Antigravity、OpenClaw + oMLX 等）暂无官方适配，社区通常通过 shell 函数或自定义钩子封装来桥接，例如 Antigravity 的 agy-start 函数方案。资料来源：issues/1581、issues/1685、issues/1636、issues/1693

小结

Superpowers 的核心是一套 跨宿主、可复用、以技能为单元 的代理工作流。它的安装极简——基本只需将仓库克隆到项目或宿主可识别的位置，并由对应的 SessionStart 钩子完成上下文注入；真正的复杂度在于 按技能组合出的方法论，以及围绕子代理调度、跨会话记忆、文档泄漏等持续演进的工程细节。对于新用户，建议先按"脑暴 → 写计划 → 执行计划 → 内联自审 → 代码评审"的标准链路熟悉一遍，再按需启用 subagent-driven-development 等进阶技能。

概述与设计目的

Skills 库是 Superpowers 项目的核心资产，位于仓库根目录下的 skills/ 目录中，每个子目录包含一个 SKILL.md 文件，对应一种可由智能体（agent）按需调用的工作流规范。该体系的目标是：为编码协作提供一套"方法论包"——将头脑风暴、计划编写、计划执行、测试驱动开发（TDD）以及系统化调试等经验沉淀为可复用、可分发的"技能"。当任何 AI 助手进入会话时，会通过会话启动钩子读取 using-superpowers，进而按需激活其它具体技能。

资料来源：skills/using-superpowers/SKILL.md:1-40

核心工作流三阶段

Skills 库将一个完整的工程任务抽象为"头脑风暴 → 编写计划 → 执行计划"三个阶段，每个阶段对应一个独立技能，并要求智能体在落地实现前严格按序执行。

头脑风暴阶段

brainstorming 技能要求在写任何代码或计划前，先与用户对问题域、约束、边界进行澄清，并在 docs/superpowers/ 目录下记录产出。该技能内置了一个基于 Node.js 的 server.cjs（v5.0.5 起从 server.js 重命名以兼容 Node.js 22+ 的 ESM 默认行为），用于跨会话持久化 brainstorm 状态。

资料来源：skills/brainstorming/SKILL.md:1-60

需要注意的是，社区中曾反馈默认将产物落在 docs/superpowers/ 会在 Sphinx/Read the Docs 风格的文档站点上意外泄露内部计划，参见 issue #1690。这意味着在公开文档项目中需要显式改写落盘路径。

编写计划阶段

writing-plans 技能将头脑风暴产出转化为可由执行阶段直接消费的"可执行计划"。计划文件通常包含任务分块、依赖关系、验证步骤以及子代理派发模板。该阶段强调"先有计划，再有实现"，并以 docs/superpowers/plans/ 作为典型落盘位置。

资料来源：skills/writing-plans/SKILL.md:1-80

执行计划阶段

executing-plans 技能负责按计划逐项落地，包括调度子代理、运行测试、提交改动，并在每一步对照计划进行验证。v5.0.6 起，"内联自审"取代了原先"派遣子代理评审"的循环——因为回归测试显示子代理评审会令执行时间翻倍（约 +25 分钟），但并未带来可观测的质量提升。

资料来源：skills/executing-plans/SKILL.md:1-100

下表概述三阶段技能的关键属性：

协作方法论：测试驱动与系统化调试

除三阶段主线外，Skills 库还内嵌两条横切式方法论：

• 测试驱动开发（test-driven-development）：要求先写失败用例，再写最小实现，最后重构。该技能与 executing-plans 配合使用，确保每个任务块都有自动化验证手段。
• 系统化调试（systematic-debugging）：在排查缺陷时强制使用"复现 → 假设 → 验证 → 根因"流程，避免在没有定位根因的情况下盲改代码。

资料来源：skills/test-driven-development/SKILL.md:1-50, skills/systematic-debugging/SKILL.md:1-50

调度与发现问题

Skills 库的入口由 using-superpowers 统一管理：会话启动钩子（例如 v5.0.7 中针对 GitHub Copilot CLI 的 SessionStart 注入）会注入一段上下文，提醒智能体"在回应任何请求前先检查是否存在相关 skill"。v5.1.0 的发布说明进一步指出，旧的 /brainstorm、/execute-plan、/write-plan 等斜杠命令被移除，原因是它们只是引导用户调用对应 skill 的"空壳"——如今应直接以 superpowers:brainstorming、superpowers:executing-plans、superpowers:writing-plans 等命名空间形式调用。

在子代理派发场景（如 subagent-driven-development）下，技能还会被注入到子代理上下文中，但 issue #1631 指出模型选择建议在派发点并未被强制生效，子代理会继承父代理的模型；issue #601 则建议将多轮子代理的发现累积起来喂给后续子代理，这些限制都在活跃讨论中。

资料来源：skills/using-superpowers/SKILL.md:1-120

总结

Skills 库的本质是一个"按需激活的工作流目录树"：以 using-superpowers 为根索引，把方法论拆分为可独立加载的小型 skill，再通过会话钩子与命名空间调用机制（superpowers:*）将其注入到不同 AI 助手环境中。这种结构既保证了核心方法论（头脑风暴—计划—执行—TDD—调试）的一致性，也允许项目按自身需求覆盖或扩展单个 skill，从而在"工程纪律"与"灵活适配"之间取得平衡。

概述与设计目标

Superpowers 是一个面向 AI 编程助手的可移植技能框架，通过「插件清单 + 钩子 (Hook) + 技能 (Skill)」三层结构实现对多种 Agent Harness 的统一支持。所谓 Harness，是指 Claude Code、Codex CLI、Cursor、GitHub Copilot CLI 等不同的代理运行环境。框架的核心目标是让同一套技能与工作流在不同 Harness 之间无缝复用，避免重复实现。资料来源：docs/porting-to-a-new-harness.md:1-20

仓库根目录下多个以 .xxx-plugin/ 开头的目录即为各 Harness 的插件清单：.claude-plugin/plugin.json 描述 Claude Code 插件元数据；.codex-plugin/plugin.json 与 .cursor-plugin/plugin.json 分别对应 Codex 与 Cursor 平台。这种「一 Harness 一清单」的设计是移植工作的起点。资料来源：.claude-plugin/plugin.json:1-15 资料来源：.codex-plugin/plugin.json:1-15 资料来源：.cursor-plugin/plugin.json:1-15

核心架构组件

插件清单 (Plugin Manifest)

每个 Harness 插件根目录都包含一个 plugin.json 文件，用于声明插件名、版本、入口以及依赖的钩子脚本。清单是 Harness 启动时识别 Superpowers 能力的唯一依据，移植新 Harness 时必须严格遵循其字段结构。资料来源：.claude-plugin/plugin.json:1-30

会话启动钩子 (SessionStart Hook)

hooks/session-start 是一个跨 Harness 的统一启动脚本，负责在会话开始时注入 Superpowers 核心提示、加载技能索引并执行环境探测。该钩子通过 hooks/hooks.json 注册到各 Harness 的事件系统。资料来源：hooks/hooks.json:1-25 资料来源：hooks/session-start:1-40

在 v5.0.7 版本中，session-start 增加了对 COPILOT_CLI 环境变量的检测，并在 GitHub Copilot CLI v1.0.11+ 上输出 SDK 标准的 { "additionalContext": "..." } JSON，使 Copilot 用户也能获得完整引导。资料来源：docs/porting-to-a-new-harness.md:20-45

技能系统 (Skills)

技能以 Markdown 文档形式存放在 skills/ 目录下，由 superpowers:brainstorming、superpowers:writing-plans 等命名空间引用。v5.1.0 已移除旧的 /brainstorm、/execute-plan、/write-plan 等斜杠命令桩，直接通过技能调用即可。资料来源：docs/porting-to-a-new-harness.md:45-60

现有 Harness 支持矩阵

社区正在请求或讨论中的 Harness 包括 Hermes Agent (#1581)、Google Antigravity (#1636)、Pi Agent (#1685) 等，可参照下文移植流程接入。资料来源：docs/porting-to-a-new-harness.md:60-80

移植到新 Harness 的步骤

1. 创建插件目录：在仓库根新建 .your-harness-plugin/，放置 plugin.json 清单文件，参考 .claude-plugin/plugin.json 的字段结构。资料来源：docs/porting-to-a-new-harness.md:80-100

1. 复用 hooks/session-start：大多数 Harness 都提供会话启动事件。脚本已实现跨平台探测逻辑，新增 Harness 通常只需在 hooks/hooks.json 中追加事件绑定，无需改脚本本身。资料来源：hooks/session-start:1-60 资料来源：hooks/hooks.json:1-30

1. 适配输出格式：某些 Harness（如 Copilot CLI）需要 SDK 标准 JSON 而非纯文本。脚本通过环境变量分支输出，移植时需为目标 Harness 添加新的分支。资料来源：docs/porting-to-a-new-harness.md:100-120

1. 验证技能加载：在目标 Harness 中执行 superpowers:brainstorming 等技能，确认无残留旧斜杠命令（v5.1.0 后已移除）。资料来源：docs/porting-to-a-new-harness.md:120-140

已知问题与社区反馈

• 模型选择未被强制执行：在 subagent-driven-development 中，调度模板只声明 Worker 类型，未强制使用更弱模型，Worker 会继承父模型 (#1631)。这影响多 Harness 场景下的成本与延迟，需在调度层补充。资料来源：docs/porting-to-a-new-harness.md:140-160

• 计划文档可能泄漏：默认 docs/superpowers/ 目录在 Sphinx / Read the Docs 构建时会被收录 (#1690)，移植到新 Harness 时建议检查默认路径配置，避免内部计划进入公开文档。资料来源：docs/porting-to-a-new-harness.md:160-175

• 跨会话记忆缺失：目前缺少跨会话检索与记录项目历史的通用机制 (#551)，移植时若 Harness 支持持久化存储，可优先接入此能力。资料来源：docs/porting-to-a-new-harness.md:175-190

1. 概述与适用范围

subagent-driven-development（下文简称 SDD）是 Superpowers 中的核心编排型技能，专门用于把一个已被拆解为多个任务的工作计划交给一组隔离的子代理去执行，再由审阅代理进行独立验证。SDD 的目标不是让某个代理"独自写完所有代码"，而是把实现、验证、复审三个角色解耦，从而获得更稳定的吞吐和更低的上下文污染。

SDD 的关键职责：

• 计划承接：从 superpowers:writing-plans 产出的任务清单（task-by-task plan）出发，按任务逐个委派。
• 上下文隔离：每个 implementer 子代理只看到与本任务相关的 brief，不继承父代理的完整会话历史。
• 角色专业化：实现者（implementer）与审阅者（task-reviewer）使用不同 prompt，对应不同职责。
• 可追溯性：所有任务产出通过 scripts/review-package 汇总，便于父代理做最终决策。

适用范围：当你已经拥有逐任务分解好的实施计划，并且任务之间相对独立、可以并行或串行委派时，使用 SDD 是最自然的选择。

资料来源：skills/subagent-driven-development/SKILL.md:1-40

2. 端到端流程

SDD 的标准流程由父代理（dispatcher）协调，整体状态流转如下：

flowchart LR
    A[父代理读取计划] --> B[scripts/task-brief 生成任务简报]
    B --> C[派发 implementer 子代理]
    C --> D{实现是否完成?}
    D -- 否 --> E[反馈修订]
    E --> C
    D -- 是 --> F[scripts/review-package 打包产物]
    F --> G[派发 task-reviewer 审阅]
    G --> H{审阅是否通过?}
    H -- 否 --> I[re-review-prompt 复审/退回]
    I --> C
    H -- 是 --> J[进入下一个任务]
    J --> A

关键步骤说明：

1. 任务简报生成：父代理调用 scripts/task-brief，把计划中单个任务的描述、约束、相关文件路径等浓缩为一段可被独立子代理消费的 brief，避免把整个计划塞进上下文。资料来源：skills/subagent-driven-development/scripts/task-brief:1-30
2. Implementer 执行：使用 implementer-prompt.md 派发，提示词中明确告知该子代理的角色边界：只做本任务，不擅自扩大范围或修改无关文件。资料来源：skills/subagent-driven-development/implementer-prompt.md:1-25
3. 产物打包：实现完成后，父代理用 scripts/review-package 把 diff、说明、相关日志打包，供审阅代理消费。资料来源：skills/subagent-driven-development/scripts/review-package:1-35
4. Task-reviewer 审阅：审阅代理加载 task-reviewer-prompt.md，按既定检查项（功能正确性、约束满足度、与计划一致性）独立判断。资料来源：skills/subagent-driven-development/task-reviewer-prompt.md:1-30
5. 复审/退回：若审阅不通过，使用 re-review-prompt.md 形成闭环反馈，回到 implementer 重新执行，直到通过为止。资料来源：skills/subagent-driven-development/re-review-prompt.md:1-25

自 v5.0.6 起，brainstorming/planning 阶段引入了内联自审（Inline Self-Review），取代了原先的"派遣独立代理做计划审阅"循环，因为回归测试显示该循环增加约 25 分钟耗时，但并未显著提升计划质量。SDD 本身仍保留独立的 implementer/reviewer 双代理结构，因为这里的产物是代码而非计划。资料来源：v5.0.6 release notes()

3. 学习积累与跨任务记忆

社区反复关注的核心痛点是：每个 SDD 子代理都是"全新启动"的，无法从先前任务中学到任何东西。这会导致重复犯同样的错误、反复试探相同的边界条件。Issue #601 提出了"accumulate learnings across tasks and feed to subsequent subagents"的需求，希望在 SDD 框架中引入一个轻量的跨任务记忆机制。

当前推荐的做法（既不依赖未实现的特性，也符合 SDD 的隔离原则）：

• 以"项目记忆"代替"代理记忆"：把跨任务的可复用发现写入仓库内的项目文档（例如 docs/superpowers/ 或 README/CLAUDE.md），下一次的 SDD 子代理在加载 brief 时由 scripts/task-brief 自动附带。Issue #551 提议的核心项目记忆系统正是为此而设。资料来源：Issue #551()
• 任务级反馈沉淀：若某个 implementer 收到的 review 反馈具备复用价值（如"该模块不接受动态导入"），父代理应在进入下一任务前显式更新后续 brief，而不是期望子代理自己去推断。
• 避免泄漏：注意 Issue #1690 指出的问题——docs/superpowers/ 默认位置可能在 Sphinx/Read the Docs 构建时泄露到对外文档，需在 .readthedocs.yml 或 conf.py 中显式排除。资料来源：Issue #1690()

4. 模型选型与已知故障排查

模型选型：SDD 的官方建议是"为每个角色选择能胜任的最弱模型"（least powerful model that can handle each role），实现者可用更弱的模型，而审阅者通常需要更可靠的推理能力。但 Issue #1631 指出，当前 dispatch 模板只命名了 worker 的"代理类型"，并未强制指定模型，因此子代理会沿用父代理的模型，导致无法发挥分层选型的成本优势。临时解决方案是在父代理加载 brief 之前，在 implementer/reviewer 的 prompt 中显式声明"使用 X 模型"。资料来源：Issue #1631()

常见故障与排查：

资料来源：skills/subagent-driven-development/SKILL.md:50-80、skills/subagent-driven-development/scripts/task-brief:30-60

版本注意事项：

• v5.1.0 起，/brainstorm、/write-plan、/execute-plan 等旧式斜杠命令被移除，必须直接调用 superpowers:brainstorming、superpowers:writing-plans、superpowers:executing-plans。SDD 通常由 executing-plans 内部触发，需确认父代理使用的是新名称。资料来源：v5.1.0 release notes()
• v5.0.5 修复了 brainstorming 服务器在 Node.js 22+ 上的 ESM 启动问题（server.js → server.cjs），若你的 SDD 流程依赖 brainstorming 阶段，需确认升级到位。资料来源：v5.0.5 release notes()
• v5.0.7 新增了 GitHub Copilot CLI 的 SessionStart 上下文注入（COPILOT_CLI 环境变量 + additionalContext），如果你在 Copilot CLI 中跑 SDD，应确保已升级到该版本以获得完整引导。资料来源：v5.0.7 release notes()

5. 实践建议

• Brief 越短越好：把"为什么改""改哪里""怎么验"三件事讲清楚，其余背景留给父代理。
• 审阅清单模板化：在 task-reviewer-prompt.md 中固化你团队最在意的若干检查项，避免每次审阅漂移。
• 把学习沉淀到仓库而非代理：在 SDD 工作流结束后，把值得复用的经验写入项目记忆文档，跨会话/跨开发者共享。
• 跟踪上游演进：SDD 仍在快速迭代，#601（学习积累）和 #1631（模型强制）都是值得关注的功能请求，对应实现落地后将显著改变本页描述的工作方式。

Pitfall Log / 踩坑日志

项目：obra/superpowers

摘要：发现 39 个潜在踩坑项，其中 12 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add Support for Kiro CLI as an AI Provider。

1. 安装坑 · 来源证据：Add Support for Kiro CLI as an AI Provider

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Support for Kiro CLI as an AI Provider
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/503 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Automatically split large specs and plans into sub-documents for individual features

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Automatically split large specs and plans into sub-documents for individual features
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1997 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Design Review not showing the Spec after claude update

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Design Review not showing the Spec after claude update
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1731 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：Im seeing slowness in responses since using the skill

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Im seeing slowness in responses since using the skill
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/743 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：[Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/2031 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：feat(wearableManage): 新增反馈记录页面

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(wearableManage): 新增反馈记录页面
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/2015 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安装坑 · 来源证据：writing-plans: plans over-specify implementation, leaving no room for executor judgment

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：writing-plans: plans over-specify implementation, leaving no room for executor judgment
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/895 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 来源证据：Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1988 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：Feature request: verdict schema for optional review plugins

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: verdict schema for optional review plugins
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/2001 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安全/权限坑 · 来源证据：[RFC] Persistent memory across Superpowers agents

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[RFC] Persistent memory across Superpowers agents
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1812 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安全/权限坑 · 来源证据：brainstorming/writing-plans SKILL efficiency

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：brainstorming/writing-plans SKILL efficiency
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。

12. 安全/权限坑 · 来源证据：subagent-driven-development: no inline-vs-dispatch threshold — small, tightly-coupled changes pay fan-out overhead for…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：subagent-driven-development: no inline-vs-dispatch threshold — small, tightly-coupled changes pay fan-out overhead for isolation they don't need
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1917 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安装坑 · 失败模式：installation: Add Support for Kiro CLI as an AI Provider

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Add Support for Kiro CLI as an AI Provider
• 对用户的影响：Developers may fail before the first successful local run: Add Support for Kiro CLI as an AI Provider
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/503 | Add Support for Kiro CLI as an AI Provider

14. 安装坑 · 失败模式：installation: Automatically split large specs and plans into sub-documents for individual features

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Automatically split large specs and plans into sub-documents for individual features
• 对用户的影响：Developers may fail before the first successful local run: Automatically split large specs and plans into sub-documents for individual features
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1997 | Automatically split large specs and plans into sub-documents for individual features

15. 安装坑 · 失败模式：installation: Design Review not showing the Spec after claude update

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Design Review not showing the Spec after claude update
• 对用户的影响：Developers may fail before the first successful local run: Design Review not showing the Spec after claude update
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1731 | Design Review not showing the Spec after claude update

16. 安装坑 · 失败模式：installation: Feature request: add an opt-in/manual-only brainstorming profile

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature request: add an opt-in/manual-only brainstorming profile
• 对用户的影响：Developers may fail before the first successful local run: Feature request: add an opt-in/manual-only brainstorming profile
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/2000 | Feature request: add an opt-in/manual-only brainstorming profile

17. 安装坑 · 失败模式：installation: Feature request: verdict schema for optional review plugins

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature request: verdict schema for optional review plugins
• 对用户的影响：Developers may fail before the first successful local run: Feature request: verdict schema for optional review plugins
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/2001 | Feature request: verdict schema for optional review plugins

18. 安装坑 · 失败模式：installation: How to know if Superpowers are being invoked?

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: How to know if Superpowers are being invoked?
• 对用户的影响：Developers may fail before the first successful local run: How to know if Superpowers are being invoked?
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/446 | How to know if Superpowers are being invoked?

19. 安装坑 · 失败模式：installation: Im seeing slowness in responses since using the skill

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Im seeing slowness in responses since using the skill
• 对用户的影响：Developers may fail before the first successful local run: Im seeing slowness in responses since using the skill
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/743 | Im seeing slowness in responses since using the skill

20. 安装坑 · 失败模式：installation: Windows: SessionStart:startup hook fails when plugin path contains a parenthesis '(' (regress...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Windows: SessionStart:startup hook fails when plugin path contains a parenthesis '(' (regression variant of #51, repro on 6.1.1)
• 对用户的影响：Developers may fail before the first successful local run: Windows: SessionStart:startup hook fails when plugin path contains a parenthesis '(' (regression variant of #51, repro on 6.1.1)
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1918 | Windows: SessionStart:startup hook fails when plugin path contains a parenthesis '(' (regression variant of #51, repro on 6.1.1)

21. 安装坑 · 失败模式：installation: Worktree skill doesn't enforce file operations stay within worktree

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Worktree skill doesn't enforce file operations stay within worktree
• 对用户的影响：Developers may fail before the first successful local run: Worktree skill doesn't enforce file operations stay within worktree
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1040 | Worktree skill doesn't enforce file operations stay within worktree

22. 安装坑 · 失败模式：installation: [Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0
• 对用户的影响：Developers may fail before the first successful local run: [Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/2031 | [Codex] Official marketplace plugin remains at 5.1.3 while upstream is 6.2.0

23. 安装坑 · 失败模式：installation: [Feature] Dedicated documentation website for Superpowers

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Feature] Dedicated documentation website for Superpowers
• 对用户的影响：Developers may fail before the first successful local run: [Feature] Dedicated documentation website for Superpowers
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/2030 | [Feature] Dedicated documentation website for Superpowers

24. 安装坑 · 失败模式：installation: [RFC] Persistent memory across Superpowers agents

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [RFC] Persistent memory across Superpowers agents
• 对用户的影响：Developers may fail before the first successful local run: [RFC] Persistent memory across Superpowers agents
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1812 | [RFC] Persistent memory across Superpowers agents

25. 安装坑 · 失败模式：installation: superpower degradation since Anthropic Skills release ...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: superpower degradation since Anthropic Skills release ...
• 对用户的影响：Developers may fail before the first successful local run: superpower degradation since Anthropic Skills release ...
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/42 | superpower degradation since Anthropic Skills release ...

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/obra/superpowers | host_targets=claude_code, claude, cursor, gemini_cli, codex, chatgpt

27. 配置坑 · 失败模式：configuration: Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/1988 | Codex SDD has no circuit breaker: one task ran ~4 hours and accumulated 120.7M telemetry tokens

28. 配置坑 · 失败模式：configuration: brainstorming/writing-plans SKILL efficiency

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: brainstorming/writing-plans SKILL efficiency
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: brainstorming/writing-plans SKILL efficiency
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/512 | brainstorming/writing-plans SKILL efficiency

29. 配置坑 · 失败模式：configuration: systematic-debugging: find-polluter.sh find -path never matches (silent no-op)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: systematic-debugging: find-polluter.sh find -path never matches (silent no-op)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: systematic-debugging: find-polluter.sh find -path never matches (silent no-op)
• 证据：failure_mode_cluster:github_issue | https://github.com/obra/superpowers/issues/2008 | systematic-debugging: find-polluter.sh find -path never matches (silent no-op)

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/obra/superpowers | README/documentation is current enough for a first validation pass.

31. 运行坑 · 来源证据：[Closed] Created in error

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Closed] Created in error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/2018 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/obra/superpowers | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/obra/superpowers | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/obra/superpowers | no_demo; severity=medium

35. 安全/权限坑 · 来源证据：SessionStart run-hook.cmd command fails under PowerShell without call operator

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SessionStart run-hook.cmd command fails under PowerShell without call operator
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/1751 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

36. 安全/权限坑 · 来源证据：superpower degradation since Anthropic Skills release ...

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：superpower degradation since Anthropic Skills release ...
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/42 | 来源类型 github_issue 暴露的待验证使用条件。

37. 安全/权限坑 · 来源证据：systematic-debugging: find-polluter.sh find -path never matches (silent no-op)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：systematic-debugging: find-polluter.sh find -path never matches (silent no-op)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/obra/superpowers/issues/2008 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/obra/superpowers | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/obra/superpowers | release_recency=unknown