[research@ai4se] : ~ $ ▌
cd ../
[tools] | | 10 min

# 定制 OpenSpec：用 Custom Schema 把 Superpowers 接进规格工作流

按 OpenSpec 官方三层定制说明，说明何时用 config、何时 fork/新建 schema；以 community schema superpowers-bridge 展示如何把 brainstorming、writing-plans、worktree、subagent TDD 等能力编入 Artifact DAG，并给出入口门禁与反模式。

[openspec][superpowers][coding-agents]

OpenSpec 管「做什么」的规格真相，Superpowers 管「怎么做」的执行纪律——各自都很强。硬把两套流程叠在同一会话里，却很容易出现三类摩擦：产物重复（brainstorm 写进 docs/superpowers/specs/，OpenSpec 再写一遍 design.md）、任务双轨（粗粒度 tasks.md 与 TDD 微步骤 plan.md 各记各的）、手工编排（每一步都要人决定该唤哪个 skill）。

正路不是改 Superpowers 源码，也不是改写 opsx 的 SKILL.md，而是走 OpenSpec 官方已经提供的定制面——尤其是 Custom Schemas。社区 schema superpowers-bridge 正是这条路上的范例：在 prompt / schema 层把两边接上，不改任何一方上游。

若你更关心「OpenSpec / Superpowers / gstack 各自管哪一层」，见先前的 三层交付栈；本文聚焦 怎么用官方定制机制把兼容做实。

OpenSpec 官方三层定制

Customization 把能力分成三层：

层级做什么适合谁
Project Config默认 schema、注入 context / 按 artifact 的 rules大多数团队
Custom Schemas自定义产物图、模板、指令与依赖有独特流程的团队
Global Overrides用户级 schema，跨项目复用Power users

Project Config（openspec/config.yaml）最轻：设 schema: 默认值，写全局 context:，再按 artifact id 挂 rules:。生成任意产物时，context 进所有 prompt，rules 只进匹配的 artifact。多数「我们用 TypeScript + 提案必须含回滚」级别的约束，到这里就够。

Custom Schemas 才是换工作流形状的地方。项目内 openspec/schemas/<name>/ 放 schema.yaml + templates/，可用：

openspec schema fork spec-driven my-workflow
# 或
openspec schema init research-first
openspec schema validate my-workflow

Schema 解析顺序：--schema CLI → change 目录元数据 → config.yaml → 默认 spec-driven。不确定当前用的是哪套时：openspec schema which --all。

Global Overrides（如 ~/.local/share/openspec/schemas/）便于个人跨仓复用；官方仍更推荐项目级 schema——跟代码一起版本管理、CI 可校验。

选型一句话：改语气与默认值用 Config；改产物图与技能编排用 Custom Schema。

为何接 Superpowers 要用 Custom Schema

superpowers-bridge README 里明确驳回了两条捷径：

  1. 在 config.yaml 塞自定义字段（例如幻想中的 skill_bindings）——CLI 不认识、无校验、无可发现性，还要改多处 SKILL。
  2. 直接改 opsx skill 文件——侵入每个 change，且升级 SKILL.md 时会被覆盖。

Custom Schema 走的是官方原生机制：CLI 校验结构，openspec schemas 自动列出，每个 change 可独立选 --schema spec-driven 或 --schema superpowers-bridge，不修改任何既有 SKILL.md。集成发生在 prompt 层：artifact instruction 里用 Skill 工具唤起 Superpowers，并 重定向输出路径（例如 brainstorming 不得写入 docs/superpowers/specs/，而写入本 change 的 brainstorm.md）。

OpenSpec 也开始维护 Community Schemas 表：superpowers-bridge 与 nanopm、e2e-runbooks 一样，不进 core，按自己的发布节奏，复制进项目即可用——这正是「完美兼容」的工程形态：契约在 schema，实现在各自仓库。

焦点：Artifact DAG

superpowers-bridge 相对内置 spec-driven，把「规格治理」与「执行技能」编进同一张产物依赖图。下图是 文件存在性依赖（OpenSpec 图引擎认的 requires:），不是口语里的「感觉顺序」。

superpowers-bridge Artifact DAG：brainstorm 分叉到 proposal/design，经 specs、tasks 到 plan，再进入 apply、verify、retrospective

ASCII 对照（与上游 README 一致）：

brainstorm ──┬──→ proposal ──→ specs ──┐
             │                         ├──→ tasks ──→ plan ──→ [apply] ──→ verify ──→ retrospective
             └──→ design ──────────────┘

与 spec-driven 的关键差异：

spec-drivensuperpowers-bridge
入口proposal（手写/直接开）brainstorm（唤起 brainstorming skill）
计划层tasks（粗检查表）tasks + plan（TDD 微步骤）
apply 前提tasksplan
apply 方式按任务推进worktree + subagent-driven-development（传递式带上 TDD 与 code-review）
apply 之后（无）verify + retrospective
新增产物—brainstorm、plan、verify、retrospective

design 在 bridge 里是 必选：把 brainstorm 的原始对话整理成 Context / Goals / Decisions / Risks / Migration；tasks 与 plan 会引用它，但图上的虚线 ref 不是硬 requires。

Apply 生命周期（运行时顺序）

DAG 只保证「文件谁先存在」。真正落地时，apply 还有一套 有序步骤；verify.md / retrospective.md 虽在图上挂着依赖，实际是在 apply 编排里写出。

superpowers-bridge Apply 生命周期：从 plan 就绪到 PR 最后，含 verify 失败回环

要点：

  • PR 是最后一步——复盘与 archive 先完成，PR diff 才能带上完整变更记忆。
  • verify 失败 → 回修 → 再 verify，不是「勾完任务就算完」。
  • Schema 不提供 executing-plans 回退：需要能跑 subagent 的平台（Claude Code、Codex 等）；否则请用内置 spec-driven，避免静默丢掉 TDD / review 传递激活。

七点 Superpowers 触点与输出重定向

#Skill落点触发
1brainstormingbrainstorm artifact直接（含 PRECHECK）
2writing-plansplan artifact直接（含 PRECHECK）
3using-git-worktreesapply 步骤 1直接
4subagent-driven-developmentapply 步骤 2直接
5test-driven-development在 #4 内传递式
6requesting-code-review在 #4 内传递式
7finishing-a-development-branchapply 步骤 6直接

另加 OpenSpec 内置：openspec-verify-change（步骤 3 → verify.md）。retrospective 补上 Superpowers 原生未覆盖的 证据优先复盘 产物。

输出重定向是兼容的关键：安装 bridge 之后，若仍让 brainstorming 写到 docs/superpowers/specs/，等于绕过 schema，留下孤儿产物。正确落点是 openspec/changes/<change>/。

轻量落地与门禁

安装本质是复制 schema 包并校验（详见上游 README 的 one-shot / bash 两种方式）：

# 概念步骤：复制到 openspec/schemas/superpowers-bridge/
openspec schema validate superpowers-bridge
# 可选：把 CLAUDE.md fragment 写入路由规则；并确认 Superpowers 插件已安装

不是每个改动都要开 change。 仪式应与风险成正比：新能力、破坏性变更、架构变更 → 走 opsx；纯 bugfix（恢复既定行为）、补测、文档、配置微调 → 直接 PR。

若口头 brainstorm 已在进行，升格为 /opsx:propose 前建议五条件齐备：范围锁死、主设计分叉已选、跨系统依赖可归类、验收可陈述、对话在收敛——且 升格需要人确认，不要自动开 change。

常见反模式：

  1. 装了 bridge 仍把设计写进 docs/superpowers/specs/ 或 plans/
  2. 带着未解决的 blocking TBD 就 promote
  3. typo / 超时调整也开完整 change
  4. 在无 subagent 的环境硬开 bridge，却期望「差不多能用」

快速命令路径（有 schema 后）：

/opsx:ff <change>     # 一气呵成规划产物到 plan
/opsx:apply
/opsx:verify
/opsx:continue        # → retrospective
/opsx:archive

收束

OpenSpec 的定制面已经足够「吸纳」Superpowers：Config 管语境与规则，Custom Schema 管产物图与技能编排，Community Schemas 管跨仓分发。superpowers-bridge 证明兼容可以 Occam 式落地——不改上游、可校验、可按 change 选型——并补上证据优先的 retrospective。

你要的「完美兼容」不是把两套工具揉成一个二进制，而是让规格真相与执行纪律在同一张 DAG 上对齐。定制官方文档是说明书；Artifact DAG 是说明书变成工程现实的那张图。

参考