| 工具 | 层 | 职责 | 接口 | 产出 |
|---|---|---|---|---|
| Superpowers | 方法论（HOW） | 提供开发流程指导 | Skill tool / Read SKILL.md | 方法步骤 |
| OpenSpec | 治理（WHAT） | 定义 artifact 及依赖关系 | openspec CLI | 文件结构 |
两者在设计上是完全正交的——没有任何一层意识到彼此的存在。要把它们配合使用，用户需要自己填补 6 道鸿沟。
Superpowers skills 设计为通过 Skill 工具调用（Claude Code 原生支持）。
但 OpenSpec 的 instruction 字段写的是 "Use the Skill tool to invoke superpowers:brainstorming"——如果你的平台不支持 Skill 工具（如 OpenCode、Gemini CLI 等），这个 instruction 直接不可用。
必须手动逐条改成 Read 方式。
Superpowers skill 文件的实际路径因平台 + 用户名 + 安装方式不同而变化：
Windows: C:\Users\Alice\.cache\opencode\packages\...\brainstorming\SKILL.md
Linux: /home/bob/.cache/opencode/packages/.../brainstorming/SKILL.md
schema.yaml 里写死的路径换台机器就炸。必须在每台机器上手动查找并替换所有路径（涉及 7 个 skill、4 个文件共 10+ 处）。
两边各自有一套实体，但没有标准对应关系：
| Superpowers skill | OpenSpec artifact | 手动集成的工作 |
|---|---|---|
| brainstorming | brainstorm | 写 instruction：去读 SKILL.md → 填 brainstorm.md 模板 |
| writing-plans | plan | 同上，重复 |
| subagent-driven-dev | apply 阶段 | 写 instruction：调度子 Agent TDD 编码 |
| using-git-worktrees | apply 阶段 | 写 instruction：创建 worktree |
| finishing-branch | finish 阶段 | 写 instruction：合并策略 |
7 个 skills × 7 个 artifacts，每个 instruction 都要手动写路径 + 配模板 + 指定输出位置。全部是手工作业，没有复用性。
按照 OpenSpec 的设计，生成一个变更的全部 artifact 需要：
openspec instructions brainstorm --change X
→ 读 brainstorming skill → 写 brainstorm.md
openspec instructions proposal --change X
→ 读 writing-plans skill → 写 proposal.md
openspec instructions specs --change X
→ 读 writing-plans skill → 写 specs.md
...（重复 7 次）
每次都要手动敲命令、读 skill、写文件。7 个 artifact 就要 7 轮手动操作。
12 个 OPSX 命令就是为了解决这个——每条命令封装一个完整阶段（创建/实现/验证/收尾），用户一个 /opsx-ff 走完所有 7 个 artifact 的生成。
Superpowers 更新后 skill 内容可能变化（如 brainstorming 流程改版）。schema.yaml 里的 instruction 写的是"读这个文件然后执行"，但：
- 谁来判断新版 skill 和现有 instruction 是否兼容？
- 兼容性断裂时谁会告警？
- 如何回滚到已知可用的版本？
这些没有标准机制。
skills.lock.json 做的就是这件事：记录 7 个 skill 文件在部署时的 SHA-256 哈希，后续部署时自动比对，哈希不匹配则 WARNING。
即便 1-5 全部手工配好，也只能在一个工作目录下一次做一个变更。
想做第二个变更？要么等当前的 finish，要么手动 git stash——然后面临上下文切换丢失、变更碎片化的风险。
worktree 隔离是在你真正用这个组合做多变更开发时才会遇到的瓶颈。但它恰恰是 AI 编码场景下最高频的需求。
| 鸿沟 | 没有 oso | 有 oso |
|---|---|---|
| 工具接口 | 手动改 7 条 instruction | 预置适配 |
| 路径 | 每台机器手动替换 10+ 处路径 | setup 脚本自动检测并替换 |
| 映射 | 手动维护 skill ↔ artifact 对应关系 | 写入 schema.yaml，开箱即用 |
| 编排 | 手动敲 7 轮命令完成一个变更 | /opsx-ff 一键完成 |
| 版本锁 | 无，靠人工注意 | SHA-256 自动校验 |
| 隔离 | 无，多变更冲突 | git worktree 强制执行 |
# 没有 oso：数小时手工配置，每次换机器重来
# 有 oso：
npm install -g @moyaspace/openspec-superpowers-opencode
openspec-superpowers-opencode init my-project
# 以上 6 个鸿沟一次填平