源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件
为什么需要它 | 使用方式 | English | Showcase | Skills | 快速开始 | 工作流 | FAQ
--- ## 为什么需要它 用 AI 写代码时，最常碰到两个失控点： - **还没想清楚要做什么，AI 就开始写代码。** 你说了句"帮我加个权限控制"，它就开始改几十个文件。改到一半才发现 —— 到底要 RBAC 还是 ABAC？ - **规划文档写得明明白白，但执行阶段还是会跑偏。** proposal 写了、design 画了，但实现过程中没人盯着测试、没人卡 review，等到合并才发现行为不对。 **spec-superflow 在两个失控点之间用源码级的引擎 + 桥接协议建立起一道硬墙：** `need-explorer` 先把需求问清楚 -> `spec-writer` 把意图沉淀为正式工件（Schema 引擎验证格式）-> `contract-builder` 把规划压缩成执行契约 `execution-contract.md` -> `build-executor` 以 TDD + SDD + Review Gate 三重纪律强制执行 -> `bug-investigator` 处理执行中的阻塞 -> `code-reviewer` 审查每批产出 -> `release-archivist` 验证后收口 -> `spec-merger` 同步 delta spec 防止规范腐烂。 它不是把 OpenSpec 和 Superpowers 并排安装再手工拼接，而是把两者的核心引擎和能力**吸收进一个自包含的工作流 owner**。 | 设计原则 | 说明 | |---|---| | Spec First | 没有稳定的规划工件，不允许进入实现 | | Guarded Handoff | `execution-contract.md` 是规划到实现的唯一交接层 | | Strong Guardrails | 实现过程中违反契约的行为被明确拦截并回退 | | Schema Validated | 规划期工件经过 Schema 引擎验证，不合格不允许进入桥接 | | Execute Disciplined | TDD 铁律 + SDD 子代理驱动 + Review Gate 双重审查 | | Self-Contained | 不需要运行时安装 OpenSpec 或 Superpowers，一个插件全包 | ## 适用场景 ### ✅ 推荐使用 | 场景 | 原因 | |------|------| | **大型功能开发** | 需要明确的规划、审查、测试门禁，防止实现偏离设计 | | **多人协作项目** | `execution-contract.md` 提供明确的协作合约和审查标准 | | **长期维护项目** | `spec-merger` 防止规范腐烂，delta spec 机制支持持续演进 | | **需要 TDD + Review Gate** | 内置 TDD 铁律 + SDD 子代理驱动 + 双重审查 | | **棕地项目（brownfield）** | need-explorer 先检查现有代码，再规划变更 | | **需要规划稳定性检查** | contract-builder 确保规划稳定后才进入实现 | ### ❌ 不推荐使用 | 场景 | 原因 | 建议 | |------|------|------| | **一次性脚本/工具** | 写完即弃，不需要规划、审查、归档 | 直接用 Claude Code 默认行为 | | **纯咨询/问答** | 没有代码产出，不需要执行门禁 | 直接用 Claude Code 或 ChatGPT | > **v0.6.0 起 hotfix/tweak 自动模式检测 + v0.8.0 Batch Inline + v0.8.2 SessionStart token 优化，让以下场景也能高效使用：** > - 小修小补（hotfix 模式，≤2 文件，自动跳过规划阶段） > - 配置/文档变更（tweak 模式，直接编辑，无 contract 开销） > - 个人项目（自动模式检测，轻量流程，token 消耗已大幅降低） ### 💡 经验法则 > **v0.7.0 起，自动模式检测会让 hotfix/tweak 级别的小变更自动走轻量流程，不再把轻微场景排除在外。** > > 简单判断：如果你会在团队周会上花 5 分钟以上解释这个改动，那 spec-superflow 是值得的。 ## 推荐使用方式 ### 入口永远从这里开始 **触发入口是 `workflow-start`。** 每次开始或恢复一个变更，你只需要告诉 Agent 一句话： ``` 用 workflow-start 开始 ``` `workflow-start` 会检查当前工件目录，**内容级检测**（不只是检查文件是否存在，还比较 proposal 范围 vs 契约意图锁），判断你处于哪个阶段，然后自动路由到正确的下一个 skill。 ### 完整流程：一次贯穿 7 个状态 ```text 你说"帮我加一个权限控制" │ ▼ ┌──────────────────┐ │ workflow-start │ ← 唯一入口。内容级状态检测、路由到正确 skill └──────┬───────────┘ │ ▼ exploring need-explorer 追问："你要 RBAC 还是 ABAC？" "多大粒度？" │ 一次一个问题，2-3 方案对比，推荐最佳并解释原因 ▼ specifying spec-writer 产出 4 份工件 + Schema 引擎实时验证 │ proposal + specs + design + tasks │ 不合格 → 拒绝，指出问题 → 修订后重新验证 ▼ bridging contract-builder 解析引擎自动提取 → 压缩为 execution-contract.md │ ┌────────────────────────────────────────────┐ │ │ execution-contract.md │ │ │ - Intent Lock (从 proposal 自动提取) │ │ │ - Approved Behavior (从 specs 自动提取) │ │ │ - Design Constraints (从 design 自动提取) │ │ │ - Task Batches (从 tasks 自动提取) │ │ │ - Test Obligations & Review Gates │ │ └────────────────────────────────────────────┘ │ ◇ 用户批准 ◇ ← 唯一一次人工介入：你看一眼，确认，然后说"批准" │ ▼ executing build-executor │ ├─ TDD 铁律: NO PRODUCTION CODE WITHOUT FAILING TEST │ ├─ SDD: 子代理实施 → 双重审查(spec合规+代码质量) → 修复 → 重新审查 │ ├─ Review Gate: 每批次完成后 code-reviewer 审查 │ └─ 进度台账: .superpowers/sdd/progress.md 防会话压缩丢失 │ ├──[遇到 bug]──→ debugging │ bug-investigator │ 4 阶段根因分析: 根因 → 模式分析 → 假设验证 → 实现修复 │ 3+ 次修复失败 → 质疑架构 → 升给用户 │ ▼ closing release-archivist │ 验证前完成铁律: NO COMPLETION CLAIMS WITHOUT FRESH EVIDENCE │ 运行测试 → 读输出 → 确认通过 → 才说完成 │ ▼ syncing spec-merger (如果存在 delta spec) ADDED/MODIFIED/REMOVED/RENAMED → 智能合并到主规范 冲突检测: 多个变更同时改同一个 capability ``` **关键约束：** - 没有 `execution-contract.md` 或未被用户批准 → **不允许进入实现** - 实现中违反契约 → **拦截并回退**，不是靠开发者"感觉不对"来手动纠偏 - 需求变更 → **强制回退到 `specifying` 或 `bridging`**，不在执行阶段悄悄改 - 遇到 bug → **强制走 debugging 状态**，不允许"随便试试看能不能修" ### 为什么它厉害：真正的源码级融合 市面上 AI 编程工作流基本是两派： | 流派 | 代表 | 优势 | 短板 | |---|---|---|---| | 规划派 | OpenSpec | 产出清晰的 proposal、specs、design、tasks，有 Schema 验证引擎 | 只管写文档，不管执行。文档写完了，实现阶段还是裸奔 | | 纪律派 | Superpowers | TDD、SDD、review gate、系统化调试、验证铁律 | 没有正式的规划工件层和 Schema 验证，对"需求是否已经明确"缺乏硬判断 | **spec-superflow 不是"两边都装"，而是"去重叠、留异同、加独创"：** ```text 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 │ │ 🚦 8 状态机 — exploring/specifying/bridging/approved-for-build/executing/debugging/closing/abandoned │ │ 🧩 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 | # | Skill | 阶段 | 职责 | 来源 | |---|---|---|---|---| | 1 | `workflow-start` | 入口 | 内容级状态检测、8 状态路由、阻止非法跳转 | **独创** | | 2 | `need-explorer` | 探索 | 一次一问+方案对比+推荐。嵌入 brainstorming 提问法 | 融合增强 | | 3 | `spec-writer` | 规格 | 产出 proposal/specs/design/tasks。Schema 引擎实时验证 + writing-plans 粒度 | 融合增强 | | 4 | `contract-builder` | 桥接 | 解析引擎自动提取 4 工件 → 压缩为 execution-contract.md | **独创** | | 5 | `build-executor` | 执行 | TDD 铁律 + SDD 子代理驱动 + Review Gate。内嵌 implementer/reviewer 模板 | 融合增强 | | 6 | `bug-investigator` | 调试 | 4 阶段根因调试。3+ 修复失败 → 质疑架构 | ← Superpowers | | 7 | `code-reviewer` | 审查 | 结构化审查，三级问题分级，禁止表演性同意 | ← Superpowers | | 8 | `release-archivist` | 收口 | 验证前完成铁律 + 归档 + 风险总结 | 融合增强 | | 9 | `spec-merger` | 同步 | Delta Spec (ADDED/MODIFIED/REMOVED/RENAMED) → 主规范智能合并 | ← OpenSpec | ## 快速开始 ### 安装 官方直接支持 **Claude Code / Cursor / OpenAI Codex CLI / OpenAI Codex App / GitHub Copilot CLI / Gemini CLI**。 另外，任何支持本地 `skills/` 目录的客户端，都可以用“通用本地安装”方式接入，例如 OpenCode、Trae、Qoder、Trae CN，或其他可配置技能目录的 IDE。 | 平台 | 安装方式 | 备注 | |---|---|---| | Claude Code | `/plugin marketplace add MageByte-Zero/spec-superflow` + `/plugin install spec-superflow@spec-superflow` | 推荐，零拷贝 | | Cursor | `node /path/to/spec-superflow/scripts/install-cursor.mjs` | 把 skills 部署到 `.cursor/skills/`，生成 `.cursor/rules/phase-guard.mdc` | | OpenAI Codex CLI | `codex plugin marketplace add MageByte-Zero/spec-superflow` + `codex plugin add spec-superflow@spec-superflow` | 已补 `.codex-plugin/` 和 `.agents/plugins/` | | OpenAI Codex App | 先用 CLI 添加 marketplace，再从 `Plugins` 面板安装/启用 | 不在 OpenAI curated 目录里 | | GitHub Copilot CLI | `copilot plugin marketplace add ...` + `copilot plugin install ...` | 从 `plugin.json` + `.claude-plugin/marketplace.json` 识别 | | Gemini CLI | `gemini extensions install https://github.com/MageByte-Zero/spec-superflow` | 支持 `update` | | OpenCode / Trae / Qoder / Trae CN / 其他本地技能客户端 | 克隆仓库后把 `skills/` 指向客户端的本地技能目录 | 本仓库提供 `.agents/skills -> ../skills` 入口 | 所有平台安装方式见 [INSTALL.md](INSTALL.md)。 ### 版本说明 - 当前发布版本：`v0.8.1` - `spec-superflow` 是自包含插件，不需要在运行时单独安装 OpenSpec 或 Superpowers - 上游能力来源分别是 [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) 和 [obra/superpowers](https://github.com/obra/superpowers) - 本仓库不把 OpenSpec / Superpowers 当作运行时依赖来锁定版本号；如果你想看每个版本吸收了哪些上游能力，请直接看 `CHANGELOG.md` - 发布说明会按 `spec-superflow` 版本记录功能基线，而不是要求用户先安装上游工具 ### Session-Start Hook（可选但推荐） - **Claude Code**：自动加载仓库根目录的 `hooks/hooks.json`。 - **Cursor**：把 `hooks/hooks-cursor.json` 复制到目标项目的 `.cursor/hooks.json`（Cursor 只识别 `.cursor/` 下的 hooks）。 这样每次新会话开始时，Agent 自动知道 spec-superflow 已就绪。 ### 使用 安装完成后，告诉 Agent： - 启动新的变更 → "用 workflow-start 开始" - 恢复旧的变更 → "继续上次的工作流" - 不确定当前状态 → "帮我看看现在该干什么" Agent 会自动检查当前工件，**内容级判断**处于哪个阶段。 ### CLI 工具链 除了 skill 工作流，spec-superflow 还提供独立的 CLI 工具： ```bash # 全局安装后可直接使用 ssf 命令 npm install -g spec-superflow # 或在项目中通过 npx 使用 npx spec-superflow list ``` | 命令 | 功能 | |------|------| | `ssf list` | 列出所有 changes 及状态 | | `ssf validate