1. obra/superpowers 深度研究报告

1.1. 执行摘要

Superpowers（obra/superpowers）是一套面向“编码智能体”的工程化开发工作流框架：它把一组可组合的 skills（技能文档）与少量 启动注入/钩子 组合起来，让智能体在“从需求澄清→设计→计划→实现→审查→收尾”的全过程中按流程行事，而不是直接上手写代码。项目 README 明确描述其从启动会话开始就会“后退一步”逼近规格说明（spec），在设计通过后产出可执行的实现计划（plan），再进入（可用时）子智能体驱动的实现与审查闭环，并强调 skills 会自动触发、无需用户手动操控。

在实现层面，Superpowers 的“自动化”关键不在于复杂的运行时代码，而在于：平台 SessionStart 钩子在会话开始时注入 using-superpowers 的全文作为“引导上下文”，该引导要求智能体在每次任务前执行“技能选择”，并通过平台提供的 Skill 工具加载其它技能。钩子配置位于 hooks/hooks.json（注册 SessionStart 事件、匹配 startup/resume/clear/compact 等生命周期场景、同步执行 session-start 脚本）。

从工作流视角，仓库内的 13 个核心技能可以分为：引导与元技能（using-superpowers, writing-skills）、需求/设计（brainstorming）、环境隔离（using-git-worktrees）、计划（writing-plans）、执行调度（subagent-driven-development, executing-plans, dispatching-parallel-agents）、质量与验证（test-driven-development, requesting-code-review, receiving-code-review, systematic-debugging, verification-before-completion）、收尾（finishing-a-development-branch）。README 还给出了“基础工作流”的阶段式激活顺序（brainstorming→worktrees→writing-plans→subagent-driven/executing→TDD→code review→finish branch），并强调“在任何任务前会检查相关技能”。

社区层面（非主证据），中文平台与英文博客普遍将 Superpowers 描述为把 Claude Code/Cursor 等从“随手写代码”拉向“工程化纪律”的技能库/插件，并常提到“钩子注入 + 技能库 +（可选）命令/工具层”的集成结构；但这些教程质量参差不齐，部分站点（如 AI 摘要站）可能含错，需要以仓库源码为准。

1.2. 项目概览与总体架构

Superpowers 的“架构”可以概括为三层：平台插件/钩子层 → 引导技能（bootstrap skill）→ 其它技能按需加载。

第一层是平台集成：以 Claude Code 为例，hooks/hooks.json 注册 SessionStart 钩子（matcher 为 startup|resume|clear|compact）并同步执行 run-hook.cmd session-start。其中 run-hook.cmd 是跨平台包装器：Windows 上寻找 Git Bash / PATH 上的 bash；Unix 上直接 exec bash 调用对应脚本；若找不到 bash 则静默退出（意味着“插件仍可用，但不会注入 SessionStart 上下文”）。

第二层是会话启动注入：hooks/session-start 脚本读取 skills/using-superpowers/SKILL.md，将其包装在 <EXTREMELY_IMPORTANT> 块中作为 session_context，并输出 JSON。脚本区分平台：Claude Code 读取 hookSpecificOutput.additionalContext；Cursor 等读取 additional_context，且脚本特别避免“双字段同时输出导致重复注入”。

第三层是技能系统本身：技能是目录结构 skills/<skill-name>/SKILL.md，并带 YAML frontmatter（name, description）。仓库的 lib/skills-core.js 实现了基础能力：解析 frontmatter、递归发现技能、解析技能名到路径、以及“个人技能覆盖/遮蔽 superpowers 技能”的解析规则（除非显式使用 superpowers: 前缀强制走 superpowers 版本）。citeturn36view3turn35view2

下面给出一个生命周期总览（流程图）——用于回答“每个技能在何阶段激活”的统一参考框架。

flowchart TD
  A[SessionStart: 平台钩子触发] --> B[注入 using-superpowers 引导上下文]
  B --> C{每次任务前: 技能选择}
  C -->|需求/设计不清晰| D[brainstorming: 产出 spec]
  D --> E[using-git-worktrees: 建隔离工作区/分支]
  E --> F[writing-plans: 产出可执行 plan]
  F --> G{执行能力}
  G -->|有 subagents| H[subagent-driven-development]
  G -->|无 subagents/需并行会话| I[executing-plans]
  H --> J[test-driven-development: 实现中约束]
  I --> J
  J --> K[requesting-code-review: 阶段性审查]
  K --> L{出现 bug/失败?}
  L -->|是| M[systematic-debugging]
  M --> N[verification-before-completion]
  L -->|否| N
  N --> O[finishing-a-development-branch: 合并/PR/保留/丢弃]
  K --> P[receiving-code-review: 接收&实施评审反馈]
  C -->|多域并行问题| Q[dispatching-parallel-agents]
  B --> R[writing-skills: 编写/验证新技能（元工作流）]

1.3. 技能对比表

下表以“技能名→目的→激活阶段→典型输入/输出→可见配置/约定”为主线。注意：多数技能是流程型文档，不提供机器可解析的“配置键”；若仓库未明确给出，则标为“未指定”。

1.4. 技能逐一解析

本节按“目的→输入/输出→配置/约定→激活阶段”逐个给出更细颗粒的信息；若仓库未明确说明“机器级输入输出格式/配置项”，则直言“未指定”，并以技能文本所暗示的产物作为 I/O。

using-superpowers
目的：作为 bootstrap 引导，告诉智能体“你拥有 superpowers”，并要求对后续任务使用 Skill 工具加载其它技能；该技能的全文在 SessionStart 时被注入上下文。
输入：会话启动事件（平台侧）；输出：一段 <EXTREMELY_IMPORTANT> 上下文，包含 using-superpowers 全文与迁移警告。
配置/约定：由 hooks/session-start 读取 ${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md；Claude Code 与 Cursor 输出字段不同以避免重复注入。
激活阶段：SessionStart→持续生效（每次任务前的技能选择由其约束）。

brainstorming
目的：在写代码前用苏格拉底式提问把需求收敛成明确 spec，并分段呈现让用户签核；README 将其定义为基础流程第 1 步。
输入：用户的模糊想法/目标/约束；输出：设计/规格文档（默认 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md）以及清晰的“下一步”。
配置/约定：spec 文件默认路径如上；并在得到批准后进入 worktree/plan 阶段（在技能清单与 checklist 中体现）。
激活阶段：需求不清晰、准备构建功能/系统时，且在触碰实现代码之前。

using-git-worktrees
目的：把后续工作隔离到新 worktree/分支，并在开始实现前验证“干净基线”（依赖安装、测试通过）；README 将其定义为设计批准后的步骤。
输入：git 仓库、目标分支名、项目依赖标识文件（package.json/Cargo.toml/requirements.txt 等）；输出：worktree 目录、git worktree add 的新分支、依赖安装与基线测试结果报告。
配置/约定：目录选择的优先级与安全验证（git check-ignore）是硬约束；若 .gitignore 缺失则要求立刻修复并提交。
激活阶段：设计批准后、编写/执行实现计划之前（也被 SDD/Executing Plans 列为 required）。

writing-plans
目的：把 spec 转成“上下文为零且缺乏判断力的初级工程师也能照做”的计划，任务粒度 2–5 分钟，并强制 DRY/YAGNI/TDD/频繁提交；README 将其定义为基础流程的计划阶段。
输入：已批准的 spec、代码库现状；输出：计划文档（默认 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md），包含每任务的文件路径、示例代码、验证命令与预期输出。
配置/约定：plan 头部强制声明后续必须用 subagent-driven-development（若可用）或 executing-plans 执行；计划位置可被“用户偏好”覆盖（但仓库未定义偏好存储格式，属未指定）。
激活阶段：设计批准后、任何实现开始前。

subagent-driven-development
目的：以“每任务一个新子智能体 + 两阶段评审（先 spec 合规、再代码质量）”执行计划；通过隔离上下文减少污染并提升质量。
输入：plan（通常作为文件与全文任务列表）、每任务必要上下文；输出：每任务一组提交与评审结论、TodoWrite 状态推进、最终全局 review，然后调用收尾技能完成合并/PR 等。
配置/约定：required skills 列表明确包含 using-git-worktrees、writing-plans、requesting-code-review、finishing-a-development-branch，并要求子智能体遵循 test-driven-development。
激活阶段：已有 plan 且平台支持 subagents 时（README 明示“有 subagents 就不要给选项，SDD 是标准路径”）。citeturn12view0turn24view0

executing-plans
目的：在“没有 subagents 或需要并行会话”的情况下执行计划：先批判性审阅 plan，再逐任务执行与验证，遇阻就停下问；完成后必须进入 finishing-a-development-branch。
输入：plan 文件；输出：执行后的代码/测试/验证结果与完成报告；并触发收尾流程。citeturn11view0turn18view0
配置/约定：特别提示“有 subagents 的平台（Claude Code/Codex）用 SDD 会显著更好”；并将 worktrees / writing-plans / finishing-branch 列为 required workflow skills。
激活阶段：已有 plan，且不采用 SDD 的执行路径。citeturn24view0

test-driven-development
目的：强制 RED–GREEN–REFACTOR：先写测试、确认失败、写最小实现、确认变绿、再重构，且强调“没看过失败就不可信”；README 将其作为实现阶段的强制技能。
输入：一个待实现/修复的行为描述；输出：可复现的自动化测试、实现代码、以及“看过失败与变绿”的证据链（具体命令由项目决定）。
配置/约定：规则性约束为主，无仓库级配置键；例外需征求人类同伴（原文给出例外类别）。
激活阶段：实现任何功能/bugfix/重构时（除非明确例外）。

requesting-code-review
目的：在任务间/大功能完成/合并前，通过子智能体审查阻断错误级联；强调要提供“精心构造的 review 上下文”，不要把会话历史塞给 reviewer。
输入：BASE_SHA/HEAD_SHA、计划或需求、变更摘要；输出：分严重度的问题列表与是否可继续的结论（严重问题阻断）。
配置/约定：使用 Task 工具调用 superpowers:code-reviewer 类型并填模板（模板文件路径在技能中给出）；这形成“技能→子任务→技能”的链式触发。
激活阶段：SDD 每任务后、executing-plans 每批次后、合并前或卡住时。

receiving-code-review
目的：收到反馈时不做“社交表演”，而是按“读完→复述/澄清→验证→评估→回应→逐条实施并测试”的技术流程处理。
输入：评审意见；输出：澄清问题、逐条变更与验证、必要时基于技术理由反驳。
配置/约定：强约束“在任何不清晰项未澄清前不要动手”；无机器配置键。
激活阶段：评审意见进入后的反馈处理阶段。

systematic-debugging
目的：把调试变成严格流程：Phase 1 根因调查→Phase 2 模式对比→Phase 3 假设与最小验证→Phase 4 实施；铁律“未做根因调查不得修复”
输入：错误信息、复现路径、近期变更、系统边界数据；输出：根因定位证据、最小修改验证、最终修复与回归测试；并建议在实施阶段通过 TDD 形成失败用例。
配置/约定：强调在多组件系统要先加诊断再修复；具体日志格式/工具未指定（由项目决定）。
激活阶段：任何 bug/测试失败/异常行为出现时（在提出修复之前）。

verification-before-completion
目的：在宣称“完成/修复/通过”前必须给出新鲜证据（跑命令、读输出、确认符合主张），否则等同“说谎”；这是对所有阶段的“闸门函数”。
输入：一个要做出的状态主张与对应可证明命令；输出：带证据的主张或带证据的失败状态。
配置/约定：无仓库级键；但与 hooks 脚本“避免重复注入”的实践共同体现该项目对“可验证性/可控性”的偏好。
激活阶段：任何提交/PR/任务完成/进入下一任务/表达满意之前。

dispatching-parallel-agents
目的：当有 2+ 独立问题域（不同测试文件/子系统）时并行派发多个 agent，同步推进，最后整合与全量验证。
输入：多组互不依赖的失败域上下文；输出：每域独立结论与修复建议/补丁，最终合并并跑全套测试。
配置/约定：强调每个 agent 任务必须范围窄、上下文自包含、不要共享会话历史；并行示例以 Task(...) 形式给出
激活阶段：多域并行可行且不会相互干扰时。

finishing-a-development-branch
目的：实现完成后，先验证测试再给出 4 个清晰选项（本地合并/推送并建 PR/保留/丢弃），并执行所选流程与 worktree 清理。
输入：当前分支、基线分支、测试命令、worktree 路径；输出：合并后的 main/master、或 PR、或保留、或删除；并按选项清理 worktree。
配置/约定：被 executing-plans 与 SDD 明确调用；强制“测试不过就停止”。
激活阶段：任务完成、准备集成/收尾之时。

writing-skills
目的：把“写技能文档”当作一种 TDD：先构造压力场景看 agent 在无技能时失败，再写技能补洞并验证通过，迭代 refactor；属于维护/扩展技能库的元流程。
输入：失败案例（rationalizations/漏洞）、目标技能的触发条件；输出：新的 skills/<name>/SKILL.md（可能含 supporting files），以及对技能可发现性（CSO）的优化建议。
配置/约定：明确个人技能目录（Claude Code ~/.claude/skills；Codex ~/.agents/skills/），以及 frontmatter 仅支持 name/description；并强调 description 只能写“何时使用”，否则会导致模型只看 description 不读正文。
激活阶段：创建/编辑/验证技能时（非日常开发必经，但对扩展系统关键）。

1.5. 触发与编排机制

1.5.1. 从平台事件到技能系统的启动注入

Superpowers 的“自动触发”首先依赖平台事件：Claude Code/兼容平台在会话启动（startup/resume/clear/compact）触发 SessionStart，根据 hooks/hooks.json 同步执行 run-hook.cmd session-start。citeturn9view0turn10view1 该包装器在 Unix 直接 exec bash，在 Windows 寻找 Git Bash 或 PATH bash；找不到 bash 会静默退出，因此“看不到 superpowers 注入”时应优先排查 bash/脚本执行链。

hooks/session-start 的关键行为是：读取 skills/using-superpowers/SKILL.md 全文、做 JSON 转义、拼接成 <EXTREMELY_IMPORTANT> 块，并输出给平台注入。它还通过环境变量 CLAUDE_PLUGIN_ROOT 判断当前是否 Claude Code：若是，则只输出 hookSpecificOutput.additionalContext；否则输出 additional_context，以避免 Claude Code 同时读取两个字段导致“双倍注入”。

下面用时序图刻画该启动链路。

sequenceDiagram
  participant U as 用户
  participant P as 平台(Claude Code/Cursor)
  participant H as run-hook.cmd
  participant S as session-start脚本
  participant A as 智能体(LLM)

  U->>P: 启动/恢复会话(或 /clear 等)
  P->>P: 触发 SessionStart (matcher: startup|resume|clear|compact)
  P->>H: 同步执行 "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start"
  H->>S: 以 bash 运行 hooks/session-start
  S->>S: 读取 skills/using-superpowers/SKILL.md 并转义
  alt Claude Code (CLAUDE_PLUGIN_ROOT 已设置)
    S-->>P: 输出 hookSpecificOutput.additionalContext(JSON)
  else 其它平台(如 Cursor)
    S-->>P: 输出 additional_context(JSON)
  end
  P-->>A: 将  上下文注入会话
  A-->>U: 首轮响应携带“Superpowers 已启用”的引导

（该图对应 hooks/hooks.json 与 hooks/session-start 的显式代码路径。

1.5.2. 技能如何“触发”其他技能：三类机制

Superpowers 内部的技能链式触发主要有三种机制，分别对应你问题中的“事件类型、hooks、消息传递/约定、代码路径”。

第一类是显式子技能/工作流依赖：例如 executing-plans 要求在完成全部任务后“必须”使用 finishing-a-development-branch；subagent-driven-development 的 Integration 区列出 required workflow skills，并要求子智能体使用 test-driven-development。这类触发不是运行时自动调用，而是写进技能契约里的“强制下一步”。

第二类是文件约定驱动的阶段推进：brainstorming 默认把 spec 存到 docs/superpowers/specs/...，writing-plans 默认把 plan 存到 docs/superpowers/plans/...，后续执行型技能以“读取 plan 文件”为起点。这构成“产物文件”在技能间传递上下文的主要通道。

第三类是平台 Tool/子智能体消息传递：以 SDD 为代表，它要求 controller（主智能体）为每个任务构造“只包含必要信息”的 dispatch，上游产物（plan 的具体任务文本、spec 路径、相关文件差异等）通过 Task/子智能体提示词传递，下游产出（DONE/BLOCKED 等状态与提交 SHA）再反馈给 controller 决策下一步，并在每个任务后触发评审。

仓库还提供了“可测试的触发观测方式”：tests/skill-triggering/run-test.sh 用 claude -p headless 执行自然语言 prompt，并在 stream-json 输出中检查是否出现 {"name":"Skill" ... "skill":"...<skillname>"} 来判定技能是否被触发。这为“技能触发是否发生”提供了可自动化验证的观测点。

1.5.3. 代表性触发流：从计划到子智能体执行与收尾

下面给出第二个代表性时序图：从 writing-plans 产出 plan，到 subagent-driven-development 调度子智能体执行、两阶段评审、最后调用 finishing-a-development-branch 收尾。其关键依据来自 writing-plans 的 “Execution Handoff”、subagent-driven-development 的流程图与 integration 列表、以及 finishing-a-development-branch 的“4 选项收尾”流程。

sequenceDiagram
  participant U as 用户
  participant C as 主智能体(Controller)
  participant SK as Skill工具
  participant I as 子智能体(Implementer)
  participant SR as 子智能体(Spec Reviewer)
  participant QR as 子智能体(Code Quality Reviewer)
  participant G as Git/测试环境

  U->>C: 设计已确认，“go / 开始实现”
  C->>SK: 调用 writing-plans / 或读取已存在 plan
  C-->>U: Plan 已保存，询问是否执行
  alt 平台支持 subagents
    C->>SK: 调用 subagent-driven-development
    C->>C: 读取 plan，抽取任务全文，创建 TodoWrite
    loop 对每个任务
      C->>I: 派发任务(含任务全文+必要上下文，不含会话历史)
      I->>G: 按 TDD 编写失败测试→最小实现→跑测试→提交
      C->>SR: 派发 spec 合规评审(基于需求/plan)
      alt 不合规/缺漏
        SR-->>C: 问题清单
        C->>I: 要求修复并补证据
      end
      C->>QR: 派发代码质量评审
      alt 质量问题
        QR-->>C: 问题清单
        C->>I: 修复并复检
      end
      C->>C: TodoWrite 标记任务完成
    end
    C->>SK: 调用 finishing-a-development-branch
    C-->>U: 给出 4 个收尾选项并执行所选
  else 无 subagents
    C->>SK: 调用 executing-plans 分批执行
    C->>SK: 完成后调用 finishing-a-development-branch
  end

1.6. 工作流模式与使用场景

本节将“模式”定义为：一组技能被组合使用、并由平台能力（是否支持 subagents、是否支持插件钩子、是否 headless CLI）决定的运行方式。每种模式都给出前置条件、典型技能组合、以及优缺点。

1.6.1. 交互式工程化默认模式

前置条件：任一支持插件/技能系统的平台（README 明确 Claude Code、Cursor 具有插件市场；其它平台需手动安装）。
典型组合：using-superpowers（启动注入）→brainstorming→using-git-worktrees→writing-plans→（subagent-driven-development 或 executing-plans）→test-driven-development→requesting-code-review→finishing-a-development-branch，并在出现 bug/宣称完成前分别触发 systematic-debugging、verification-before-completion。
优点：覆盖端到端；把“设计/计划/验证/收尾”变成硬门槛；与 README 所述“你无需做任何特殊操作，skills 会自动触发”的目标一致。
缺点：对时间与文本产物（spec/plan）要求更高；对不愿写文档/不愿等审查的人可能显得“啰嗦”；在平台钩子失效时体验下降（尤其 Windows 缺 bash 会静默不注入）。

1.6.2. 子智能体驱动执行模式

前置条件：平台支持 subagents（README 明确“有 subagents 的平台执行质量更高”，并在写计划时把 SDD 设为标准路径）。
典型组合：writing-plans→subagent-driven-development（每任务 implementer + spec reviewer + code reviewer）→requesting-code-review（贯穿审查）→finishing-a-development-branch；实施中子智能体使用 test-driven-development。
优点：上下文隔离、并行化潜力更高；两阶段评审把“符合需求”和“工程质量”分开，减少“先实现再解释”式偏航。
缺点：依赖平台能力与成本（更多调用）；对 plan 的质量非常敏感：计划越具体，子智能体越能“机械化”完成；反之会频繁 NEEDS_CONTEXT/BLOCKED（技能虽给出处理规则，但具体阈值未指定）。

1.6.3. 非 subagents 或并行会话执行模式

前置条件：没有 subagents，或希望在独立会话/批次中执行（例如把执行与设计分开）。
典型组合：writing-plans→executing-plans（批次执行+检查点）→requesting-code-review（每批后）→finishing-a-development-branch。
优点：对平台要求更低；更适合“必须人类在环”或“需要频繁中断确认”的场景。
缺点：执行效率通常低于 SDD；同一会话上下文更容易污染；更依赖人类在检查点提供反馈。

1.6.4. 并行调查/修复模式

前置条件：存在多个互不依赖的问题域（例如多文件测试失败、多个子系统独立故障）。
典型组合：dispatching-parallel-agents +（每个问题域内部用 systematic-debugging/test-driven-development）+ 最终 verification-before-completion 做全量验证。
优点：最大化吞吐；减少“串行排队”的时间浪费。
缺点：需要严格隔离编辑范围，否则会产生冲突；如果问题实际上相关，会导致重复工作甚至相互干扰（技能明确提醒“相关失败不要并行”）。

1.6.5. 技能开发与自动化验证模式

前置条件：需要扩展技能库或验证技能是否真能约束智能体；通常需要 Claude Code CLI（claude -p headless）。
典型组合：writing-skills（设计技能与测试场景）+ tests/claude-code/run-skill-tests.sh 或 tests/skill-triggering/run-test.sh（自动验证触发与遵循）。
优点：把“技能是否有效”变成可重复测试，而不是主观感觉；也为 CI 集成提供脚手架（仓库自身未提供 GitHub Actions 工作流文件，CI 属外部自建范畴）。
缺点：依赖 CLI 环境、权限与 token；测试耗时可能较长（集成测试 10–30 分钟在 README 中提及）。