spec-superflow

源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件

为什么需要它 | 使用方式 | English | Showcase | Skills | 快速开始 | 工作流 | FAQ

为什么需要它

用 AI 写代码时，最常碰到两个失控点：

• 还没想清楚要做什么，AI 就开始写代码。 你说了句"帮我加个权限控制"，它就开始改几十个文件。改到一半才发现 —— 到底要 RBAC 还是 ABAC？

• 规划文档写得明明白白，但执行阶段还是会跑偏。 proposal 写了、design 画了，但实现过程中没人盯着测试、没人卡 review，等到合并才发现行为不对。

spec-superflow 在两个失控点之间用源码级的引擎 + 桥接协议建立起一道硬墙：

spec-explorer 先把需求问清楚 -> spec-forger 把意图沉淀为正式工件（Schema 引擎验证格式）-> bridge-contract 把规划压缩成执行契约 execution-contract.md -> execution-governor 以 TDD + SDD + Review Gate 三重纪律强制执行 -> systematic-debugger 处理执行中的阻塞 -> code-reviewer 审查每批产出 -> closure-archivist 验证后收口 -> spec-syncer 同步 delta spec 防止规范腐烂。

它不是把 OpenSpec 和 Superpowers 并排安装再手工拼接，而是把两者的核心引擎和能力吸收进一个自包含的工作流 owner。

适用场景

✅ 推荐使用

❌ 不推荐使用

💡 经验法则

如果一个改动你不需要写 proposal 和 design doc 就能想清楚，那 spec-superflow 可能太重了。

简单判断：如果你会在团队周会上花 5 分钟以上解释这个改动，那 spec-superflow 是值得的。

推荐使用方式

入口永远从这里开始

触发入口是 workflow-orchestrator。

每次开始或恢复一个变更，你只需要告诉 Agent 一句话：

用 workflow-orchestrator 开始

workflow-orchestrator 会检查当前工件目录，内容级检测（不只是检查文件是否存在，还比较 proposal 范围 vs 契约意图锁），判断你处于哪个阶段，然后自动路由到正确的下一个 skill。

完整流程：一次贯穿 7 个状态

你说"帮我加一个权限控制"
       │
       ▼
┌──────────────────┐
│ workflow-orchestrator  │  ← 唯一入口。内容级状态检测、路由到正确 skill
└──────┬───────────┘
       │
       ▼
   exploring         spec-explorer 追问："你要 RBAC 还是 ABAC？" "多大粒度？"
       │                  一次一个问题，2-3 方案对比，推荐最佳并解释原因
       ▼
   specifying        spec-forger 产出 4 份工件 + Schema 引擎实时验证
       │                  proposal + specs + design + tasks
       │                  不合格 → 拒绝，指出问题 → 修订后重新验证
       ▼
   bridging          bridge-contract 解析引擎自动提取 → 压缩为 execution-contract.md
       │                 ┌────────────────────────────────────────────┐
       │                 │ execution-contract.md                      │
       │                 │  - Intent Lock (从 proposal 自动提取)      │
       │                 │  - Approved Behavior (从 specs 自动提取)   │
       │                 │  - Design Constraints (从 design 自动提取) │
       │                 │  - Task Batches (从 tasks 自动提取)         │
       │                 │  - Test Obligations & Review Gates          │
       │                 └────────────────────────────────────────────┘
       │
  ◇ 用户批准 ◇        ← 唯一一次人工介入：你看一眼，确认，然后说"批准"
       │
       ▼
   executing         execution-governor
       │                 ├─ TDD 铁律: NO PRODUCTION CODE WITHOUT FAILING TEST
       │                 ├─ SDD: 子代理实施 → 双重审查(spec合规+代码质量) → 修复 → 重新审查
       │                 ├─ Review Gate: 每批次完成后 code-reviewer 审查
       │                 └─ 进度台账: .superpowers/sdd/progress.md 防会话压缩丢失
       │
       ├──[遇到 bug]──→ debugging
       │                 systematic-debugger
       │                 4 阶段根因分析: 根因 → 模式分析 → 假设验证 → 实现修复
       │                 3+ 次修复失败 → 质疑架构 → 升给用户
       │
       ▼
   closing           closure-archivist
       │                 验证前完成铁律: NO COMPLETION CLAIMS WITHOUT FRESH EVIDENCE
       │                 运行测试 → 读输出 → 确认通过 → 才说完成
       │
       ▼
   syncing           spec-syncer (如果存在 delta spec)
                         ADDED/MODIFIED/REMOVED/RENAMED → 智能合并到主规范
                         冲突检测: 多个变更同时改同一个 capability

关键约束：

• 没有 execution-contract.md 或未被用户批准 → 不允许进入实现
• 实现中违反契约 → 拦截并回退，不是靠开发者"感觉不对"来手动纠偏
• 需求变更 → 强制回退到 specifying 或 bridging，不在执行阶段悄悄改
• 遇到 bug → 强制走 debugging 状态，不允许"随便试试看能不能修"

为什么它厉害：真正的源码级融合

市面上 AI 编程工作流基本是两派：

spec-superflow 不是"两边都装"，而是"去重叠、留异同、加独创"：

OpenSpec 独有 ──────→ 吸收             Superpowers 独有 ──────→ 吸收
  Schema 引擎                    TDD 铁律 (RED-GREEN-REFACTOR)
  Delta Spec (ADDED/MODIFIED)    SDD (子代理驱动 + 双层审查)
  三维度验证 (verify-change)      系统化调试 (4 阶段根因分析)
  Spec 同步 (sync-specs)          结构化代码审查 (三级问题分级)
  批量归档冲突解决                 验证前完成铁律
                                  并行代理调度
                                        │
┌───────────────────────────────────────┼───────────────────────────────────────┐
│                              spec-superflow 独创                              │
│                                                                              │
│  🔗 桥接层 execution-contract.md — 解析引擎自动提取 4 工件 → 1 份可检查契约    │
│  🧭 内容级状态检测 — 不只是检查文件存在，还比较 proposal scope vs contract lock │
│  🚦 7 状态机 — exploring/specifying/bridging/approved/executing/debugging/closing  │
│  🧩 9 skill 协同 — 入口路由 → 澄清 → 锻造 → 桥接 → 执行 ⇄ 调试 → 审查 → 收口 → 同步  │
│                                                                              │
│  每个 skill 背后有真实的引擎代码：                                              │
│  - src/schema/       ← OpenSpec 基因: Requirement, Delta, Spec 类型定义       │
│  - src/validation/   ← OpenSpec 基因: 验证器 (SHALL/MUST, Scenario, Delta)    │
│  - src/parsing/      ← OpenSpec 基因: Requirement 块解析 + Delta Spec 解析     │
│  - scripts/          ← Superpowers 基因: task-brief, review-package 辅助工具  │
│  - hooks/            ← Superpowers 基因: session-start 多平台引导注入          │
│  - implementer/reviewer 模板 ← Superpowers 基因: SDD 双层审查提示模板           │
└──────────────────────────────────────────────────────────────────────────────┘

核心 Skills

快速开始

安装

支持 Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI / Trae 共 7 个平台。

Claude Code（推荐）：

/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow

Cursor：

/add-plugin spec-superflow

Gemini CLI：

gemini extensions install https://github.com/MageByte-Zero/spec-superflow

Trae：

git clone https://github.com/MageByte-Zero/spec-superflow.git
mkdir -p ~/.trae/skills
cp -R spec-superflow/skills/* ~/.trae/skills/

所有平台安装方式见 INSTALL.md。

Session-Start Hook（可选但推荐）

在 Claude Code / Cursor 中安装 hooks 后，每次会话启动自动注入 workflow-orchestrator：

# Claude Code 自动加载 hooks/hooks.json
# Cursor 自动加载 hooks/hooks-cursor.json

这样每次新会话开始时，Agent 自动知道 spec-superflow 已就绪。

使用

安装完成后，告诉 Agent：

• 启动新的变更 → "用 workflow-orchestrator 开始"
• 恢复旧的变更 → "继续上次的工作流"
• 不确定当前状态 → "帮我看看现在该干什么"

Agent 会自动检查当前工件，内容级判断处于哪个阶段。

工作流

对于名为 <change-name> 的变更，推荐的工件目录：

workflow/
├── specs/                          # 主规范库（spec-syncer 维护）
│   └── <capability>/spec.md
└── changes/<change-name>/
    ├── proposal.md
    ├── design.md
    ├── tasks.md
    ├── specs/                      # Delta specs（变更结束后 syncer 合并到主规范）
    │   └── <capability>/spec.md
    └── execution-contract.md

流程线是：

proposal/specs/design/tasks -> execution-contract.md -> 用户批准 -> 开始实现
                                                              │
                                              ┌─ TDD ─ SDD ─ Review ─┤
                                              │                       │
                                              └─ debugger ─ reviewer ─┘

规划本身不等于可以实现。 如果 execution-contract.md 缺失、过时或未被用户批准，工作流会拒绝进入实现阶段。

引擎架构

spec-superflow/
├── src/                              # ← 嵌入式引擎（TypeScript 源码）
│   ├── schema/                       #   类型定义：Requirement, Delta, Spec, Change
│   ├── validation/                   #   验证器：SHALL/MUST, Scenario, Delta 冲突检测
│   └── parsing/                      #   解析器：Requirement 块 + Delta Spec
│
├── skills/                           # 9 个 Skill
│   ├── workflow-orchestrator/        #   入口路由（7 状态 + 内容级检测）
│   ├── spec-explorer/                #   需求澄清
│   ├── spec-forger/                  #   工件生成（Schema 验证）
│   ├── bridge-contract/              #   桥接契约（自动提取）
│   ├── execution-governor/           #   执行总督（TDD + SDD）
│   │   ├── implementer-prompt.md     #   子代理实施模板
│   │   └── task-reviewer-prompt.md   #   子代理审查模板
│   ├── systematic-debugger/          #   4 阶段根因调试
│   ├── code-reviewer/                #   结构化审查
│   │   └── code-reviewer-prompt.md   #   审查者提示模板
│   ├── closure-archivist/            #   验证 + 收口
│   └── spec-syncer/                  #   Delta Spec → 主规范同步
│
├── scripts/                          # 辅助脚本
│   ├── task-brief                    #   提取单任务文本
│   ├── review-package                #   生成审查 diff
│   └── validate-artifacts            #   引擎验证入口
│
├── hooks/                            # Session-start 钩子（多平台）
├── templates/                        # 6 个工件模板
├── schemas/                          # YAML Schema 定义
└── package.json

示例

两个完整 change 示例展示了从 proposal 到 execution contract 的贯通路径：

• docs/examples/add-dark-mode/ -- 新 UI 功能（暗色模式）
• docs/examples/refactor-auth-boundary/ -- brownfield 后端重构（认证边界）

阅读顺序：proposal.md -> specs/ -> design.md -> tasks.md -> execution-contract.md

常用问题

spec-superflow 是源码级融合，不是简单并列：

• 吸收了 OpenSpec 的 Schema/验证/解析引擎（src/ 目录），但丢弃了 CLI 命令和 profile 系统
• 吸收了 Superpowers 的 TDD 铁律、SDD 子代理模式、系统化调试、代码审查（skill 内嵌 + 辅助脚本），但丢弃了 brainstorming、writing-plans（方法论已融入 spec-explorer/spec-forger）
• 独创了 bridge-contract 桥接层 — 将规划语言转化为可检查的执行契约
• 自包含 — 不需要安装 OpenSpec 或 Superpowers 运行时
• 9 个 skill vs OpenSpec 的 12 个 AI command + Superpowers 的 14 个 skill — 去重叠、留异同、加独创

建议不要在同一个会话中混用。如果同时激活 OpenSpec 的 /opsx:* 和 spec-superflow 的 workflow-orchestrator，可能出现两套流程竞争。选择一个做 workflow owner。

已有 OpenSpec 工件目录的项目可以直接用 spec-superflow 接管——bridge-contract 能读取现有的 proposal/specs/design/tasks 生成 execution contract。

以下情况视为 contract 过时（内容级检测，不只是文件时间戳）：

• proposal.md 范围变了（比较 intent lock 字段）
• specs/ 里的已批准需求改了
• design.md 架构或接口约束变了
• tasks.md 执行批次变了

过时后 workflow-orchestrator 会回退到 bridge-contract，不会继续执行。

spec-forger 生成工件后自动运行 src/validation/validator.ts：

• spec.md：每个 Requirement 必须含 SHALL 或 MUST，至少 1 个 #### Scenario:
• Delta spec：ADDED/MODIFIED 必须有 requirement text + scenario，同 spec 内不能有跨段冲突（如 MODIFIED 和 REMOVED 同时出现）
• proposal.md：## Why 至少 50 字符，## What Changes 不能为空
• tasks.md：每个任务必须有完成定义

不合格 → 拒绝进入 bridge-contract。

执行阶段的核心模式：

1. Pre-flight 审查 — 扫描计划冲突
2. 每任务循环：派实施子代理（用 implementer-prompt.md）→ 生成 review-package diff → 派审查子代理（用 task-reviewer-prompt.md）→ 双向判断（spec 合规 + 代码质量）→ 不合格 → 修复 → 重新审查
3. 进度台账 — .superpowers/sdd/progress.md 防止会话压缩后丢失进度
4. 最终全分支审查 — code-reviewer 审查完整变更

模型选择策略：机械任务用便宜模型，集成/判断用标准模型，架构/最终审查用最强模型。

版本历史

• v0.2.0 — 源码级融合。新增引擎层（src/），从 6 skill 扩展到 9 skill。新增 TDD 铁律、SDD、系统化调试、代码审查、Delta Spec 同步。7 状态机。
• v0.1.0 — 首次发布。6 skill 工作流，bridge-contract 桥接层，6 状态机。

Star 一下，下次需要的时候能找到。