Superpowers 项目工作流概览

项目定位

Superpowers 不是一个常规 Web 服务或库应用，而是一套面向 AI 编码代理的“软件开发方法论 + 技能库 + 多平台插件包装”。核心内容在 skills/，每个技能用 SKILL.md 描述触发条件和执行流程；不同 harness 通过插件 manifest、启动 hook 或提示注入，把同一套技能暴露给 Claude Code、Codex、Codex App、Cursor、Gemini CLI、OpenCode、Copilot CLI 等环境。

项目目标是让代理在写代码前自动走规范流程：先澄清需求和设计，再写计划，然后按 TDD、代码审查、验证和分支收尾推进。仓库也强烈约束贡献流程：必须解决真实问题、避免重复 PR、核心库只接收通用能力、技能内容变更需要评估证据。

核心组件

区域	作用
`skills/`	核心技能库，定义 brainstorming、writing-plans、TDD、debugging、review、worktree、branch finishing 等代理工作流程。
`hooks/`	会话启动 hook，将 `using-superpowers` bootstrap 注入支持 hooks 的平台。
`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `.opencode/`	各平台插件入口和元数据。
`docs/`	平台说明、测试说明、历史设计文档和实现计划。
`tests/`	针对技能触发、Claude Code 集成、OpenCode 插件、brainstorm server、显式技能请求等的测试脚本。
`scripts/`	维护脚本，包括版本号同步和同步到 Codex 插件仓库。
`.github/`	Issue/PR 模板，强制问题描述、重复检查、环境和评估证据。

运行时工作流

用户安装 Superpowers 插件或扩展。
harness 启动会话时加载 bootstrap：
- Claude/Cursor/Copilot 通过 hooks/session-start 注入 skills/using-superpowers/SKILL.md。
- Gemini 通过 GEMINI.md 引用 using-superpowers 及 Gemini 工具映射。
- OpenCode 通过 .opencode/plugins/superpowers.js 注册 skills/，并把 bootstrap 插入首条用户消息。
- Codex 插件通过 .codex-plugin/plugin.json 声明技能目录和界面元数据。
using-superpowers 要求代理在任何响应或动作前检查并加载相关技能。
典型建设流程：
- brainstorming：理解上下文、逐个澄清问题、提出方案、写 spec。
- using-git-worktrees：需要时创建或确认隔离工作区。
- writing-plans：根据 spec 写可执行计划，要求小步骤、完整代码、验证命令、频繁提交。
- subagent-driven-development 或 executing-plans：按计划执行；推荐每个任务一个 fresh subagent，并经过 spec review 和 code quality review。
- test-driven-development：实现时遵守 RED-GREEN-REFACTOR。
- systematic-debugging：遇到 bug 或失败时先定位根因再修复。
- requesting-code-review / receiving-code-review：在任务完成或收到反馈时做严谨审查。
- verification-before-completion：声明完成前必须用证据验证。
- finishing-a-development-branch：测试通过后，选择本地合并、创建 PR、保留分支或丢弃。

ASCII 流程图

+---------------------------+
| Install plugin/extension  |
+-------------+-------------+
              |
              v
+---------------------------+
| Harness starts session    |
+-------------+-------------+
              |
              v
+---------------------------+
| Inject using-superpowers  |
| bootstrap context         |
+-------------+-------------+
              |
              v
+---------------------------+
| User asks for work        |
+-------------+-------------+
              |
              v
+---------------------------+
| Check/load relevant skill |
+-------------+-------------+
              |
              v
       +------+------+
       | Build/change? |
       +------+------+
              |
         yes  v
+---------------------------+
| brainstorming             |
| clarify -> options -> spec|
+-------------+-------------+
              |
              v
+---------------------------+
| optional isolated worktree|
+-------------+-------------+
              |
              v
+---------------------------+
| writing-plans             |
| spec -> exact task plan   |
+-------------+-------------+
              |
              v
       +------+------+
       | Subagents    |
       | available?   |
       +---+------+---+
           |      |
        yes|      |no
           v      v
+----------------+  +----------------+
| subagent-driven|  | executing-plans|
| development    |  | inline batches |
+-------+--------+  +--------+-------+
        |                    |
        +----------+---------+
                   |
                   v
+-----------------------------------+
| Per task: TDD -> tests -> commit  |
| -> spec review -> quality review  |
+------------------+----------------+
                   |
                   v
       +-----------+-----------+
       | Failure or bug found? |
       +------+----------------+
              |
        yes   v
+---------------------------+
| systematic-debugging      |
| root cause -> failing test|
| -> single fix -> verify   |
+-------------+-------------+
              |
              v
+---------------------------+
| verification before claim |
+-------------+-------------+
              |
              v
+---------------------------+
| finishing development     |
| merge / PR / keep / drop  |
+---------------------------+

贡献和 PR 工作流

该仓库对 PR 要求很高。提交前必须：

读完整 .github/PULL_REQUEST_TEMPLATE.md，每一节都写具体内容。
搜索 open 和 closed PR，确认没有重复或已有失败尝试。
证明问题真实存在，不能只说“优化”“可能会出问题”。
确认变更属于 core；项目特定、领域特定、第三方服务集成通常应做成独立插件。
如果改技能内容，使用 writing-skills 并做 adversarial pressure testing。
至少在一个 harness 测试，并在 PR 环境表里说明。
给人类审查完整 diff，得到明确同意后再开 PR。

测试和维护工作流

工作	入口
Claude Code 技能测试	`tests/claude-code/run-skill-tests.sh`
OpenCode 插件测试	`tests/opencode/run-tests.sh`
Brainstorm visual companion server 测试	`tests/brainstorm-server/*.test.js`
显式技能请求测试	`tests/explicit-skill-requests/`
技能触发测试	`tests/skill-triggering/`
Codex 插件同步测试	`tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
版本号同步/审计	`scripts/bump-version.sh`
同步到 OpenAI Codex 插件仓库	`scripts/sync-to-codex-plugin.sh`

Markdown 文件用途清单

根目录和平台入口

文件	作用
`PROJECT_WORKFLOW_OVERVIEW.md`	本文档，汇总仓库工作流、ASCII 流程图和 Markdown 文件用途。
`README.md`	项目总说明：Superpowers 是什么、安装方式、基本工作流、技能库概览、贡献和社区信息。
`AGENTS.md`	面向代理的贡献守则，强调 PR 前置检查、真实问题、核心范围、人类审查和拒收类型。
`CLAUDE.md`	Claude Code 使用的代理贡献守则，内容与 `AGENTS.md` 同类，用于约束 Claude 环境。
`GEMINI.md`	Gemini CLI 上下文入口，引用 `using-superpowers` 和 Gemini 工具映射。
`CODE_OF_CONDUCT.md`	项目社区行为准则。
`RELEASE-NOTES.md`	版本发布记录，按版本记录新增功能、修复和平台支持变化。
`.opencode/INSTALL.md`	OpenCode 快速安装、迁移、使用、更新和排障说明。

GitHub 模板

文件	作用
`.github/PULL_REQUEST_TEMPLATE.md`	PR 模板，要求问题、变更、核心适配性、替代方案、已有 PR、测试环境、评估和人类审查。
`.github/ISSUE_TEMPLATE/bug_report.md`	Bug 报告模板，要求环境、重复检查、复现步骤、预期/实际行为和日志或 transcript。
`.github/ISSUE_TEMPLATE/feature_request.md`	功能请求模板，要求真实问题、方案、替代方案和是否适合 core。
`.github/ISSUE_TEMPLATE/platform_support.md`	新 IDE/平台支持请求模板，收集平台、插件能力和手动安装尝试结果。

docs 文档

文件	作用
`docs/README.opencode.md`	OpenCode 完整使用指南，覆盖安装、技能加载、个人/项目技能、更新、工作原理和排障。
`docs/testing.md`	Superpowers 技能测试指南，重点说明 Claude Code headless 集成测试、token 分析和新增测试方式。
`docs/windows/polyglot-hooks.md`	Windows/macOS/Linux 跨平台 hook 方案，解释 `.cmd` + shell polyglot wrapper 的原因和写法。

历史设计和实现计划

文件	作用
`docs/plans/2025-11-22-opencode-support-design.md`	OpenCode 支持设计文档，描述插件架构、技能发现、工具和启动注入方案。
`docs/plans/2025-11-22-opencode-support-implementation.md`	OpenCode 支持的详细实现计划，按任务落地设计。
`docs/plans/2025-11-28-skills-improvements-from-user-feedback.md`	来自真实使用反馈的技能改进问题分析和候选变更。
`docs/plans/2026-01-17-visual-brainstorming.md`	Visual Brainstorming Companion 的实现计划，包括服务器、helper、测试和技能说明。
`docs/superpowers/specs/2026-01-22-document-review-system-design.md`	文档审查系统设计：为 spec 和 plan 增加 reviewer loop。
`docs/superpowers/plans/2026-01-22-document-review-system.md`	文档审查系统的实现计划。
`docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md`	Visual brainstorming 重构设计，改为浏览器显示和终端命令驱动。
`docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md`	Visual brainstorming 重构的实现计划。
`docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`	零依赖 brainstorm server 设计，说明 WebSocket、HTTP、文件监听和兼容性。
`docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md`	零依赖 brainstorm server 的实现计划。
`docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md`	Codex App 兼容性设计，主要处理 worktree/finishing 技能对托管工作区的适配。
`docs/superpowers/plans/2026-03-23-codex-app-compatibility.md`	Codex App 兼容性的实现计划。
`docs/superpowers/specs/2026-04-06-worktree-rototill-design.md`	Worktree 重构设计，提出检测现有隔离状态、优先原生工具、按来源清理。
`docs/superpowers/plans/2026-04-06-worktree-rototill.md`	Worktree 重构的实现计划。

核心技能

文件	作用
`skills/using-superpowers/SKILL.md`	启动技能，定义“先检查技能再响应”的总规则、技能优先级和平台适配。
`skills/brainstorming/SKILL.md`	创造性工作前的需求澄清和设计流程，要求先 spec 后实现。
`skills/writing-plans/SKILL.md`	根据 spec 编写可执行实现计划，强调小步骤、TDD、完整代码和验证命令。
`skills/subagent-driven-development/SKILL.md`	推荐执行模式：每个任务派 fresh subagent，实现后做 spec review 和 code quality review。
`skills/executing-plans/SKILL.md`	无或不使用 subagent 时的计划执行流程，带检查点和完成分支交接。
`skills/test-driven-development/SKILL.md`	TDD 铁律和 RED-GREEN-REFACTOR 流程。
`skills/systematic-debugging/SKILL.md`	系统化调试流程，要求先根因调查、模式分析、假设验证，再修复。
`skills/verification-before-completion/SKILL.md`	完成声明前的验证门禁，要求实际运行命令并确认结果。
`skills/requesting-code-review/SKILL.md`	完成任务或合并前请求代码审查的流程。
`skills/receiving-code-review/SKILL.md`	收到代码审查意见后的处理流程，强调技术判断和验证，不盲从。
`skills/dispatching-parallel-agents/SKILL.md`	多个相互独立任务的并行代理派发策略。
`skills/using-git-worktrees/SKILL.md`	为功能工作建立或确认隔离工作区，优先使用 harness 原生 worktree 工具。
`skills/finishing-a-development-branch/SKILL.md`	开发完成后的测试验证、环境识别、合并/PR/保留/丢弃选择和清理流程。
`skills/writing-skills/SKILL.md`	编写或修改技能的元技能，覆盖技能结构、描述、CSO、测试和反规避设计。

技能引用和 prompt 模板

文件	作用
`skills/brainstorming/spec-document-reviewer-prompt.md`	Brainstorming 后审查 spec 文档的 subagent prompt 模板。
`skills/brainstorming/visual-companion.md`	Brainstorming 的浏览器视觉伴侣详细指南，包括服务器、页面推送和事件读取。
`skills/writing-plans/plan-document-reviewer-prompt.md`	Writing-plans 后审查 plan 文档的 subagent prompt 模板。
`skills/requesting-code-review/code-reviewer.md`	代码审查 subagent 的 prompt，规定审查重点、严重级别和输出格式。
`skills/subagent-driven-development/implementer-prompt.md`	SDD 中实现任务的 subagent prompt 模板。
`skills/subagent-driven-development/spec-reviewer-prompt.md`	SDD 中检查实现是否符合任务/spec 的 reviewer prompt 模板。
`skills/subagent-driven-development/code-quality-reviewer-prompt.md`	SDD 中检查代码质量的 reviewer prompt 模板。
`skills/test-driven-development/testing-anti-patterns.md`	TDD 技能的反模式参考，说明脆弱测试、过度 mock、实现细节测试等问题。
`skills/systematic-debugging/root-cause-tracing.md`	调试时从症状向上追踪坏值来源的技术说明。
`skills/systematic-debugging/defense-in-depth.md`	防御纵深修复策略，避免只在单点打补丁。
`skills/systematic-debugging/condition-based-waiting.md`	用条件等待替代固定 sleep 的调试/测试模式。
`skills/systematic-debugging/CREATION-LOG.md`	Systematic debugging 技能创建和演进记录。
`skills/systematic-debugging/test-academic.md`	Systematic debugging 的学术式测试场景。
`skills/systematic-debugging/test-pressure-1.md`	Systematic debugging 的压力测试场景 1。
`skills/systematic-debugging/test-pressure-2.md`	Systematic debugging 的压力测试场景 2。
`skills/systematic-debugging/test-pressure-3.md`	Systematic debugging 的压力测试场景 3。
`skills/using-superpowers/references/codex-tools.md`	Codex 环境下 Claude Code 工具名到 Codex 工具/行为的映射。
`skills/using-superpowers/references/copilot-tools.md`	Copilot CLI 环境下的工具映射和适配说明。
`skills/using-superpowers/references/gemini-tools.md`	Gemini CLI 环境下的工具映射和适配说明。
`skills/writing-skills/anthropic-best-practices.md`	Anthropic 技能作者指南参考，用于对照但不直接替代本项目技能哲学。
`skills/writing-skills/persuasion-principles.md`	技能设计中的说服原则，用于让代理更可靠地遵守流程。
`skills/writing-skills/testing-skills-with-subagents.md`	用 subagent 压力测试技能的流程，映射到 RED-GREEN-REFACTOR。
`skills/writing-skills/examples/CLAUDE_MD_TESTING.md`	测试 CLAUDE.md/技能文档措辞有效性的示例场景和协议。

测试夹具文档

文件	作用
`tests/claude-code/README.md`	Claude Code 技能测试套件说明，包括运行方式、测试结构、现有测试和调试方法。
`tests/subagent-driven-dev/go-fractals/design.md`	SDD 测试夹具：Go fractals 示例的设计文档。
`tests/subagent-driven-dev/go-fractals/plan.md`	SDD 测试夹具：Go fractals 示例的实现计划。
`tests/subagent-driven-dev/svelte-todo/design.md`	SDD 测试夹具：Svelte todo 示例的设计文档。
`tests/subagent-driven-dev/svelte-todo/plan.md`	SDD 测试夹具：Svelte todo 示例的实现计划。