openspec-superpowers

English | 中文

在 OpenSpec 上集成 Superpowers 的 Subagent-Driven Development Test-Driven Development 功能。

OpenSpec 负责「想清楚做什么」—— Superpowers 负责「高效地做出来」

实现原理

本项目在 OpenSpec 与 Superpowers 之间建立桥接：在 OpenSpec 的「提案」与「归档」之间，插入 Superpowers 的「计划」与「执行」阶段。不修改任何原有技能，只新增两个桥接技能。

OpenSpec 原流程：

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:archive

扩展后流程：

探索(/opsx:explore) ──► 提案(/opsx:propose) ──► 计划(/opsx:write-plan) ──► 执行(/opsx:executing-plans) ──► 归档(/opsx:archive)

| 阶段 | 技能 | 做什么 | 产物 | |------|------|--------|------| | 探索 | /opsx:explore <想法>| 理解需求、分析代码、明确范围 | 对话记录、决策 | | 提案 | /opsx:propose <清晰完整的需求> | 一次性生成 proposal、design、tasks | proposal.md, design.md, tasks.md | | 计划 | /opsx:write-plan | 将 tasks 转化为可执行的实施计划 | 带标注的计划文件 | | 执行 | /opsx:executing-plans | 按计划逐任务执行，同步回 tasks.md | 代码变更 | | 归档 | /opsx:archive | 归档变更、同步 specs、清理状态 | 归档目录 |

安装

前置依赖：OpenSpec、Superpowers

# 1. 初始化 OpenSpec
openspec init

# 2. 安装桥接技能，自动检测项目中的 AI 工具目录（如 .claude/），将新技能分发到对应位置
npx openspec-superpowers

命令参考

/opsx:write-plan [--max-tasks N] <change-name>

将 OpenSpec 的 tasks.md 转化为 Superpowers 实施计划。读取 proposal、design、tasks 等产物，调用 superpowers:writing-plans 生成计划文件，每个计划任务通过 <!-- openspec-task: LABEL --> 标注映射回 OpenSpec 任务。生成后自动验证映射覆盖率。

• <change-name> 可省略，自动检测或从上下文推断
• --max-tasks N 默认 10，超限时拆分为多个计划文件并提示确认
• 产物输出到 docs/superpowers/plans/YYYY-MM-DD-<change-name>.md

/opsx:executing-plans <change-name>

按计划逐任务执行代码实现，完成后自动同步进度到 tasks.md。若计划不存在，会引导先生成计划。提供两种执行模式：子代理驱动（推荐，每任务独立子代理+审查）和内联执行（批量执行+检查点）。

• <change-name> 可省略，自动检测或从上下文推断
• 同步规则：仅当一个 OpenSpec 任务对应的所有计划任务都完成时才标记 [x]，部分完成只报告进度

流程演示

第一步：探索

You: /opsx:explore 想给博客加个用户登录功能

AI 会提出澄清性问题、勾勒认证选项、探索现有代码库。需求不清晰时先探索，清晰后进入提案。

提示：如果需求很明确，可跳过此步骤。

第二步：提案

You: /opsx:propose 为博客添加邮箱密码登录，支持注册和登录...
AI: ● Starting with a description
    ● Creating proposal.md
      ⎿ ◼ Create proposal.md artifact
         ◻ Create specs artifacts › blocked by #1               
         ◻ Create design.md artifact › blocked by #1
         ◻ Create tasks.md artifact › blocked by #2, #3  
    ● All artifacts created ...

OpenSpec 会在项目下创建文件：

/openspec/changes/add-user-login
  /specs/login
      spec.md    ← 本次变更引入的 spec 变化
  .openspec.yaml
  proposal.md    ← 这个变更是什么以及为什么
  design.md      ← 如何实现（技术设计）
  tasks.md       ← 实施任务清单

tasks.md 内容示例：

## 1. 核心功能实现
- [ ] 1.1 创建 User 数据模型
- [ ] 1.2 实现注册 API
- [ ] 1.3 实现登录 API
- [ ] 1.4 创建登录页面
- [ ] 1.5 添加鉴权中间件

第三步：计划

You: /opsx:write-plan add-user-login
AI: ● Using change: add-user-login ...
    ● All artifacts loaded ...
    ● Skill(superpowers:writing-plans)
    ● Now let me verify the mapping coverage ...
    ● Plan Created

读取 OpenSpec 产物，生成 Superpowers 实施计划文件 docs/superpowers/plans/2026-01-01-add-user-login.md，每个任务通过标注映射回 OpenSpec：

<!-- openspec-task: 1.1 -->
### Task 1: 创建 User 数据模型
文件: src/models/User.ts
步骤: ...
验证: ...
提交：...

<!-- openspec-task: 1.2 -->
### Task 2: 实现注册 API
文件: src/routes/auth.ts
步骤: ...
验证: ...
提交：...

生成后自动验证映射覆盖率，确保每个 OpenSpec 任务都被覆盖。

第四步：执行

You: /opsx:executing-plans add-user-login
AI: ● Using change: add-user-login ...
    ● Change status looks good ...
    ● Plan found: docs/superpowers/plans/2026-01-01-add-user-login.md
    ● Skill(superpowers:subagent-driven-development)
    ● Spec review ...
    ● superpowers:code-reviewer...
    ● Both reviews complete. Now syncing OpenSpec tasks.md

按计划逐任务执行（推荐子代理驱动模式）。每完成一个任务，自动将状态同步回 tasks.md：

- [x] 1.1 创建 User 数据模型      ← 已完成
- [x] 1.2 实现注册 API            ← 已完成
- [ ] 1.3 实现登录 API            ← 进行中
- [ ] 1.4 创建登录页面
- [ ] 1.5 添加鉴权中间件

第五步：归档

You: /opsx:archive add-user-login
AI: ● Archiving the add-user-login change. Let me check its status first.
    ● All artifacts are complete ...
    ● Syncing specs first, then archiving.
    ● Specs synced. Now performing the archive.
    ● Archive Complete.

最终文件结构：

/openspec
  /changes/archive/2026-01-01-add-user-login
    /specs/login
        spec.md    ← 本次变更引入的 spec 变化
    .openspec.yaml
    proposal.md    ← 这个变更是什么以及为什么
    design.md      ← 如何实现（技术设计）
    tasks.md       ← 实施任务清单
  /specs/login
    spec.md        ← 主 spec 项目的能力事实来源

所有任务完成后，归档会检查产物和任务的完成状态，对比变更中的 delta spec 与主 spec 的差异并同步，确保 spec 事实来源准确。最后将变更目录移至 openspec/changes/archive/2026-01-01-add-user-login/，工作区恢复干净。

进阶技巧

模型选择

• 探索和提案阶段建议使用 Claude Opus 4.7 / GPT-5.5 等高智能模型，确保需求理解准确。
• 计划阶段建议使用 Claude Opus 4.7 / GPT-5.5 等高智能模型，确保生成的计划足够详尽。
• 执行阶段可使用 DeepSeek-V4-Pro 等高性价比模型，因为计划已经足够详细。
• 归档阶段建议使用 Claude Opus 4.7 / GPT-5.5 等高智能模型，因为会涉及 spec 差异对比及汇总，确保 spec 事实来源的准确性。

新会话

每一步命令都基于 <change-name> 自动查找并填充上下文，因此完全可以在新会话中继续执行，搭配不同的 IDE 和模型并行工作：

• Claude Code 写 phase-01 plan，Codex 写 phase-02 plan
• Claude Code(DeepSeek-V4-Pro) 执行 phase-01 任务，Claude Code(Claude Opus 4.7) 写 phase-02 plan

提示：Claude Code 可以通过指定配置文件的方式，达到不同窗口配置不同厂商的模型效果。claude --settings ~/.claude/settings-deepseek.json

节省 token

基于 <change-name> 自动填充上下文有时会占用大量 token，甚至需要跨多个 5h 用量周期才能完成。（无限 token 用户可忽略此部分）

编写计划时：通过 Claude Code 的 @file 语法指定必要文档，避免加载全部上下文，在一个周期内完成计划编写：

/opsx:write-plan @openspec/changes/<change-name>/design.md @openspec/changes/<change-name>/tasks.md

执行计划时：大计划一般会拆成多个小计划，当执行到最后几个计划时，执行中断（订阅额度用光、隔天继续等），若再次启动会因为 Prompt Caching 过期而浪费一次缓存写入。可以指定某个计划及必要文件，在新会话中继续：

/opsx:executing-plans @docs/superpowers/plans/2026-01-01-add-user-login-3.1-4.5.md @openspec/changes/<change-name>/design.md @openspec/changes/<change-name>/tasks.md

流程定制

这一套流程不是固定的，可通过 openspec config profile 选择启用不同的 workflow 命令集，按需调整组合。例如仅保留核心流程，或新增 verify 等扩展命令。

License

MIT