源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件
快速开始 | 安装 | 为什么 | Skills | 工作流 | English | Showcase | FAQ
安装后，告诉 Agent 一句话即可启动：
用 workflow-start 开始
Agent 会自动检查当前工件目录，内容级判断（不看文件时间戳，而是比较 proposal 范围 vs 契约意图锁）你处于哪个阶段，然后路由到正确的下一个 skill。
- 启动新的变更 →
用 workflow-start 开始 - 恢复旧的变更 →
继续上次的工作流 - 不确定当前状态 →
帮我看看现在该干什么
Claude Code 的主流方式是插件 marketplace：
/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow
/plugin update spec-superflow@spec-superflowMarketplace 安装自动加载 hooks，每次新会话自动注入上下文。
# 方式一：通过 ssf CLI
npx spec-superflow@latest install-cursor
# 方式二：直接运行脚本
curl -fsSL https://raw.githubusercontent.com/MageByte-Zero/spec-superflow/main/scripts/install-cursor.mjs | node -Cursor 原生发现
.cursor/skills/、.agents/skills/、~/.cursor/skills/等目录，也可以在 Customize → Rules → Remote Rule (Github) 导入。脚本会自动部署 skills、scripts、docs 等运行时依赖。
Codex 的主流方式是 Plugin Directory / marketplace。本仓库已提供 .codex-plugin/plugin.json 和 .agents/plugins/marketplace.json。
# 在 Codex CLI 中打开插件目录
codex
/plugins
# 或添加社区 marketplace 后安装
codex plugin marketplace add hashgraph-online/awesome-codex-plugins
codex plugin add spec-superflow@awesome-codex-plugins
# 直接从指定 release tag 安装（不等待社区镜像同步）
codex plugin marketplace add MageByte-Zero/spec-superflow --ref v0.9.0
codex plugin add spec-superflow@spec-superflow
# 升级并验证社区 marketplace 安装
codex plugin marketplace upgrade awesome-codex-plugins
codex plugin add spec-superflow@awesome-codex-plugins
codex plugin list | rg spec-superflowCodex App 打开 Plugins 面板，安装或启用 spec-superflow。通过 CLI 安装或升级后，重启 Codex App 并新开会话；旧会话不会热加载 skills。
copilot plugin marketplace add MageByte-Zero/spec-superflow
copilot plugin install spec-superflow@spec-superflowgemini extensions install https://github.com/MageByte-Zero/spec-superflow
gemini extensions update spec-superflow # 升级更多平台（Cline / Kiro / Windsurf / Qwen / Amazon Q / Roo Code / Continue / Pi / OpenCode / WorkBuddy / Trae）
| 平台 | 安装方式 | 状态 |
|---|---|---|
| Cline | npx spec-superflow@latest install-cline |
已提供安装器 |
| Kiro | npx spec-superflow@latest install-kiro |
已提供安装器 |
| Windsurf | npx spec-superflow@latest install-windsurf |
已提供安装器 |
| Qwen Code | npx spec-superflow@latest install-qwen |
已提供安装器 |
| Amazon Q Developer | npx spec-superflow@latest install-amazon-q |
已提供安装器 |
| Roo Code | npx spec-superflow@latest install-roocode |
已提供安装器 |
| Continue | npx spec-superflow@latest install-continue |
已提供安装器 |
| Pi | npx spec-superflow@latest install-pi |
已提供安装器 |
| OpenCode | .opencode/plugins/spec-superflow.js 或 .agents/skills -> skills/ |
已提供入口 |
| WorkBuddy | npx spec-superflow@latest install-workbuddy |
已提供安装器 |
| Trae IDE / TRAE Work | .trae/skills/、~/.trae/skills/ 或上传 zip/.skill |
手动/导入 |
共支持 17 个平台，完整安装说明见 INSTALL.md，支持矩阵见 docs/platform-matrix.md。
npm install -g spec-superflow # 全局安装
npx spec-superflow list # 或通过 npx 使用| 命令 | 功能 |
|---|---|
ssf list |
列出所有 changes 及状态 |
ssf validate <dir> |
验证工件完整性 |
ssf doctor |
健康检查（版本、hooks、skills、文档一致性） |
ssf version <semver> |
一键同步版本号到所有 manifest |
ssf state <sub> <dir> |
管理 .spec-superflow.yaml 状态文件 |
ssf inject <dir> |
生成 phase-guard 产物；仅在检测到单一平台标记时可省略 --platforms |
ssf audit <dir> |
生成决策点审计报告 |
ssf checkpoint save <dir> --task <id> --next <text> |
保存任务级会话恢复点 |
ssf checkpoint list <dir> |
列出 checkpoint 及 stale 状态 |
ssf checkpoint show <dir> <id> |
查看单个恢复点 |
ssf handoff create <dir> --type <type> ... |
创建 prototype/research/experiment handoff |
ssf handoff list <dir> |
列出 handoff 生命周期状态 |
ssf handoff finish <dir> <id> |
校验 handoff 结果 |
ssf handoff resolve <dir> <id> --decision <decision> |
记录显式 handoff 决策 |
ssf execution plan <dir> ... |
为 full/hotfix 在 <change>/.superpowers/sdd/execution-plan.json 记录受 guard 保护的执行计划（SDD 默认） |
ssf execution show <dir> [--json] |
查看并校验当前执行计划、wave 与 receipt |
ssf execution revise <dir> ... |
将已有计划保留/升级为 SDD，并生成新 revision；不允许降级 |
ssf execution review <dir> ... |
为一个计划 wave 记录 review receipt |
ssf install-cursor |
部署到 Cursor .cursor/ 目录 |
ssf install-workbuddy |
部署到 WorkBuddy marketplace 插件（含 skills/rules/runtime） |
ssf install-cline |
部署到 Cline .cline/ + .clinerules/ |
ssf install-kiro |
部署到 Kiro .kiro/ + .kiro/steering/ |
ssf install-windsurf |
部署到 Windsurf .windsurf/ + .windsurf/rules/ |
ssf install-qwen |
部署到 Qwen Code .qwen/ + .qwen/rules/ |
ssf install-amazon-q |
部署到 Amazon Q .amazonq/ + .amazonq/rules/ |
ssf install-roocode |
部署到 Roo Code .roo/ + .roo/rules/ |
ssf install-continue |
部署到 Continue .continue/ + .continue/rules/ |
ssf install-pi |
部署到 Pi .pi/skills/（无规则目录） |
- 当前版本：
v0.9.0 - v0.9.0 highlights：支持 Node 20/22、model profiles 只读解析，以及 code-reviewer 的最小性审查；详见 CHANGELOG.md
- 自包含插件，不需要运行时安装 OpenSpec 或 Superpowers
- 上游来源：Fission-AI/OpenSpec 和 obra/superpowers
- 版本历史见 CHANGELOG.md
ssf inject 示例：
ssf inject changes/my-change --platforms cursor
ssf inject changes/my-change --platforms all省略 --platforms 时，只有在项目中恰好检测到一个平台标记时才会自动写入；如果检测到多个平台，必须显式指定 --platforms <platform> 或 --platforms all。
会话恢复与可选 prototype：
ssf checkpoint save changes/my-change --task 1.1 --next "Run focused tests"
ssf checkpoint list changes/my-change
ssf handoff create changes/my-change --type research --objective "Compare approaches" --expected-output "Recommendation" --acceptance "Evidence recorded"Prototype 只在用户明确确认后创建；后端、CLI、配置和内部重构不会自动进入 prototype 流程。handoff 结果不会自动修改 design.md 或 tasks.md。
Delta spec 的规范路径是 specs/<capability>/spec.md；扁平的 specs/<capability>.md 和根级 specs/spec.md 不会被视为合法规范。
对 full/hotfix，DP-4 不是一段任意文本：开始实现前必须保存并校验 current
execution plan。它位于 <change>/.superpowers/sdd/execution-plan.json，不写入
execution-contract.md。SDD 是 default；只有用户给出 explicit override 时，才能选择
inline 或 batch-inline。后者始终是串行模式，绝不自动成为默认或冒充并行。
tweak 保持轻量例外，不要求 execution plan 或 wave receipt。
ssf execution plan changes/my-change --mode sdd --reason "independent work" \
--wave foundation:parallel:1.1,1.2 \
--wave integration:serial:2.1:foundation
ssf execution show changes/my-change --json
# 将已有 inline/batch-inline 计划升级为 sdd，或重规划已有 sdd 计划；不能降级。
# 每次修订都会生成新 revision 并清除旧 review receipt。
ssf execution revise changes/my-change --mode sdd --reason "need parallel work" \
--wave foundation:parallel:1.1,1.2 \
--wave integration:serial:2.1:foundation
# 每个 wave 都先写入非空 review report，再记录 receipt。
ssf execution review changes/my-change --wave foundation --base <sha> --head <sha> \
--report .superpowers/sdd/reviews/foundation.md --verdict pass--report 相对于 <change> 解析，且必须位于
<change>/.superpowers/sdd/reviews/ 之下。--base 和 --head 必须是该
<change> Git 工作树中的真实 commit，且 base 必须是 head 的祖先。
<change>/.superpowers/sdd/reviews/ 的目录层级必须是物理、非符号链接目录；
report 本身必须为普通、非空、非符号链接文件。
每个 wave 的 review receipt 必须是当前 revision 的 pass，依赖 wave 和 closing
才会放行；修订计划会使旧 receipt 失效。恢复、切换和手动保存等 #47 的 slash
command 尚未实现，不能据此假定存在 /ssf:* 命令。
用 AI 写代码时，最常碰到两个失控点：
-
还没想清楚要做什么，AI 就开始写代码。 你说了句"帮我加个权限控制"，它就开始改几十个文件。改到一半才发现 —— 到底要 RBAC 还是 ABAC？
-
规划文档写得明明白白，但执行阶段还是会跑偏。 proposal 写了、design 画了，但实现过程中没人盯着测试、没人卡 review，等到合并才发现行为不对。
spec-superflow 在这两个失控点之间建起一道硬墙： 需求澄清 → 工件沉淀（Schema 引擎验证格式）→ 执行契约桥接 → TDD + SDD + Review Gate 三重纪律强制执行 → 验证收口 → delta spec 同步防止规范腐烂。
| 设计原则 | 说明 |
|---|---|
| Spec First | 没有稳定的规划工件，不允许进入实现 |
| Guarded Handoff | execution-contract.md 是规划到实现的唯一交接层 |
| Strong Guardrails | 实现中违反契约的行为被明确拦截并回退 |
| Schema Validated | 规划期工件经过 Schema 引擎验证 |
| Execute Disciplined | TDD 铁律 + SDD 子代理驱动 + Review Gate |
| Self-Contained | 不需要安装 OpenSpec 或 Superpowers，一个插件全包 |
✅ 推荐： 大型功能开发、多人协作项目、长期维护项目、需要 TDD + Review Gate 的棕地项目。
❌ 不推荐： 一次性脚本/工具、纯咨询/问答。
v0.6.0 起自动模式检测：hotfix（≤2 文件，最小契约 + DP-3 后执行）和 tweak（≤4 文件，纯配置/文档，直接编辑）让小型变更也能高效使用。
| # | Skill | 阶段 | 职责 |
|---|---|---|---|
| 1 | workflow-start |
入口 | 内容级状态检测、8 状态路由、阻止非法跳转 |
| 2 | need-explorer |
探索 | 一次一问 + 方案对比 + 推荐 |
| 3 | spec-writer |
规格 | 产出 proposal/specs/design/tasks，Schema 引擎实时验证 |
| 4 | contract-builder |
桥接 | 解析引擎自动提取 4 工件 → 压缩为 execution-contract.md |
| 5 | build-executor |
执行 | TDD 铁律 + SDD 子代理驱动 + Review Gate |
| 6 | bug-investigator |
调试 | 4 阶段根因分析，3+ 修复失败 → 质疑架构 |
| 7 | code-reviewer |
审查 | 结构化审查，三级问题分级 |
| 8 | release-archivist |
收口 | 验证前完成铁律 + 归档 + 风险总结 |
| 9 | spec-merger |
同步 | Delta Spec → 主规范智能合并 |
你说"帮我加一个权限控制"
│
▼
workflow-start ← 唯一入口。内容级状态检测、路由到正确 skill
│
▼
exploring need-explorer："你要 RBAC 还是 ABAC？多大粒度？"
▼
specifying spec-writer 产出 4 份工件 + Schema 引擎验证
▼
bridging contract-builder 自动提取 → execution-contract.md
│
◇ 用户批准 ◇ ← 唯一一次人工介入
│
▼
executing build-executor: TDD → SDD → Review Gate
│
├──[bug]──→ debugging → bug-investigator
▼
closing release-archivist 验证 + 归档
▼
syncing spec-merger（delta spec → 主规范）
关键约束： 没有 execution-contract.md 或未被批准 → 不允许实现；full/hotfix 没有 current execution plan、或任一 wave 缺少 pass review receipt → 不允许推进；需求变更 → 强制回退；遇到 bug → 强制走 debugging，不允许"随便试试"。
- hotfix — ≤2 文件、无新模块时，走
exploring -> bridging -> approved-for-build -> executing。可跳过proposal.md、design.md、tasks.md、specs/等完整规划工件，但仍必须先生成一份新的最小execution-contract.md，并完成 DP-3 批准后才能进入实现 - tweak — ≤4 文件、纯配置/文档修改时，跳过规划+桥接，直接编辑
可以在项目根目录的 spec-superflow.config.json 中，为不同执行角色配置平台模型 ID：
{
"models": {
"mechanical": "vendor-small",
"standard": "vendor-standard",
"strong": "vendor-strong",
"review": "vendor-review"
}
}| Profile | 角色 |
|---|---|
mechanical |
低成本、机械性修改 |
standard |
集成与判断任务 |
strong |
架构、设计与最终审查 |
review |
与 diff 匹配的代码审查 |
使用以下命令只读解析一个 profile：
ssf config --resolve-model mechanical该命令只解析本地配置，不调用平台 API，也不切换当前会话模型。支持 model 字段的平台由控制器显式传入返回的模型 ID；若结果为 configured: false，则没有自动选择能力，不能臆造供应商模型，仍须遵守现有的显式指定 model 要求。
spec-superflow 和 OpenSpec / Superpowers 什么关系？
源码级融合，不是简单并列。吸收了两者的引擎（Schema/验证/解析 + TDD/SDD/调试/审查），独创了 contract-builder 桥接层和 8 状态路由。自包含，不需要安装上游运行时。
能和我已有的 OpenSpec 或 Superpowers 共存吗？
建议不要在同一会话混用。已有 OpenSpec 工件目录的项目可以直接用 spec-superflow 接管 —— contract-builder 能读取现有文件生成 execution contract。
execution contract 怎么知道该更新了？
内容级检测（不是文件时间戳）：proposal 范围变了、specs 已批准需求改了、design 架构约束变了、tasks 批次变了 → 视为过时，回退到 contract-builder。
SDD (Subagent-Driven Development) 怎么工作的？
full/hotfix 默认 SDD：先在 <change>/.superpowers/sdd/execution-plan.json 保存带依赖和策略的 execution plan，再按可执行 wave 派实施子代理；每个 wave 先有 review report，再写 pass/fail review receipt。只有用户 explicit override 才能选择 inline 或 Batch Inline；Batch Inline 仍是串行。进度台账防止会话压缩后丢失进度。
Star 一下，下次需要的时候能找到。