spec-superflow

<h1 align="center">spec-superflow</h1> <p align="center"> <strong>按改动风险选择轻量或完整路径的 AI 编程工作流插件</strong> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a> <a href="https://github.com/MageByte-Zero/spec-superflow/stargazers"><img src="https://img.shields.io/github/stars/MageByte-Zero/spec-superflow" alt="GitHub Stars"></a> <a href="https://www.npmjs.com/package/spec-superflow"><img src="https://img.shields.io/npm/v/spec-superflow" alt="npm version"></a> </p> <p align="center"> <a href="#快速开始">快速开始</a> | <a href="#安装">安装</a> | <a href="#为什么需要它">为什么</a> | <a href="#核心-skills">Skills</a> | <a href="#工作流">工作流</a> | <a href="docs/README_en.md">English</a> | <a href="docs/showcase.html">Showcase</a> | <a href="#常见问题">FAQ</a> </p>

---

快速开始

安装后，告诉 Agent 一句话即可启动：

用 workflow-start 开始

Agent 会自动检查当前工件目录，内容级判断（不看文件时间戳，而是比较 proposal 范围 vs 契约意图锁）你处于哪个阶段，然后路由到正确的下一个 skill。

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

安装

Claude Code（Marketplace）

Claude Code 的主流方式是插件 marketplace：

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

Marketplace 安装自动加载 hooks，每次新会话自动注入上下文。

Cursor（Skills 目录 / GitHub 导入）

# 方式一：通过 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 等运行时依赖。

OpenAI Codex CLI / App

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 v1.0.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-superflow

Codex App 打开 Plugins 面板，安装或启用 spec-superflow。通过 CLI 安装或升级后，重启 Codex App 并新开会话；旧会话不会热加载 skills。

GitHub Copilot CLI

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

Gemini CLI

gemini extensions install https://github.com/MageByte-Zero/spec-superflow
gemini extensions update spec-superflow   # 升级

更多平台（Cline / Kiro / Windsurf / Qwen / Amazon Q / Roo Code / Continue / Pi / Qoder / OpenCode / WorkBuddy / CodeBuddy / 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 | 已提供安装器 | | Qoder | npx spec-superflow@latest install-qoder | 已提供安装器 | | OpenCode | .opencode/plugins/spec-superflow.js 或 .agents/skills -> skills/ | 已提供入口 | | WorkBuddy | npx spec-superflow@latest install-workbuddy | 已提供安装器 | | CodeBuddy Code CLI | ssf install-codebuddy | 已提供安装器 | | Trae IDE / TRAE Work | .trae/skills/、~/.trae/skills/ 或上传 zip/.skill | 手动/导入 |

共支持 19 个平台，完整安装说明见 INSTALL.md，支持矩阵见 docs/platform-matrix.md。

CLI 工具链

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 resume [change] | 只读恢复摘要；唯一活跃 change 可自动选择 | | ssf switch <change> | 只读返回明确 change 的恢复上下文；adapter 可据此切换当前 AI 对话关注对象 | | ssf save <change> --task <id> --next <text> | 手动写入兼容 checkpoint；不自动 commit、push 或 sync | | 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 recommend <dir> ... | 基于任务量、wave 和工作流列出可用执行方式并给出推荐 | | ssf execution plan <dir> ... | 在用户确认选择后，为 Full/legacy Hotfix 保存受 guard 保护的执行计划 | | 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-codebuddy | 部署到 ~/.codebuddy/（CodeBuddy Code CLI） | | ssf uninstall-codebuddy | 从 ~/.codebuddy/ 移除 spec-superflow（CodeBuddy Code CLI） | | 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/（无规则目录） | | ssf install-qoder | 部署到 Qoder .qoder/ + .qoder/rules/ |

版本

• 当前版本：v1.0.1
• v1.0：默认按风险走 Quick、direct Hotfix、Tweak 或 Full；小改动只保留边界与验证，复杂改动才进入完整规划、契约和审查
• 自包含插件，不需要运行时安装 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 resume                         # 只在唯一活跃 change 时自动选择
ssf resume changes/my-change       # 只读恢复指定 change 的摘要
ssf switch changes/another-change  # 只读返回明确 change 的恢复上下文
ssf save changes/my-change --task 1.1 --next "Run focused tests"
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"

resume 与 switch 都是只读恢复操作；resume 只会在恰好一个活跃 change 时自动选择目标。switch 只返回明确目标的恢复上下文，不修改 cwd、TUI 会话或任何隐藏指针；CLI 本身不切换当前对话关注对象，CodeBuddy/WorkBuddy adapter 或宿主 Agent 可用该上下文完成该动作。save 仅手动写入既有 checkpoint 协议，绝不自动 commit、push 或 sync。/ssf:resume、/ssf:switch、/ssf:save 是 CodeBuddy/WorkBuddy 使用的 Markdown command adapter：它们分发到同一 CLI guard，不为其他平台承诺完全相同的 slash 名称。

Prototype 只在用户明确确认后创建；后端、CLI、配置和内部重构不会自动进入 prototype 流程。handoff 结果不会自动修改 design.md 或 tasks.md。

Delta spec 的规范路径是 specs/<capability>/spec.md；扁平的 specs/<capability>.md 和根级 specs/spec.md 不会被视为合法规范。

Requirement 标题的规范形式是 ### Requirement: 名称。为兼容已存在的中文工件，解析器也接受 ### 需求：名称 和 ### REQ-<ID>: 名称；其它三级标题不会被当作需求。ssf sync 会先校验全部 delta，再一次性发布，任一 delta 无效时不会写入基线或发布回执。

活动规格与发布基线

活动工作流只以 changes/<change>/ 为事实来源：其中的 specs/ 是可审计的 delta spec。项目根 specs/ 是发布后的规范基线，不参与活动 change 的状态转换。运行 ssf sync changes/<change> 时，CLI 会把 ADDED/MODIFIED/REMOVED/RENAMED 操作应用到根基线的 ## Requirements，并在 change 状态写入可重算的发布回执。closing 会同时核验 delta 与基线；任一侧同步后被修改，都必须重新同步，spec_merged: true 不能绕过该检查。

插件仓库与使用项目的边界

本仓库发布的是 workflow、模板、脚本、测试和文档，不是某一次真实运行的工作目录。因此不会提交 changes/<change>/、.spec-superflow.yaml、.superpowers/ 或 ssf sync 生成的根 specs/；它们默认由 .gitignore 排除。需要展示完整流程时，只维护脱敏、固定的 docs/examples/ 示例。

在使用此插件的项目中，活动输入仍是 changes/<change>/specs/，根 specs/ 仍是可选的发布基线。消费者可按自己的审计或发布要求决定是否将这些项目工件纳入版本控制；这不会改变活动工作流只读取 change 的规则。

受 guard 保护的执行计划

对 Full/legacy Hotfix，DP-4 不是一段任意文本：开始实现前必须保存并校验 current execution plan。它位于 <change>/.superpowers/sdd/execution-plan.json，不写入 execution-contract.md。先运行 ssf execution recommend，它会根据任务量和 wave 策略列出 inline、batch-inline、sdd，并给出可审计的推荐理由，同时把当前 wave 的 推荐凭据保存为 <change>/.superpowers/sdd/execution-recommendation.json；Agent 必须将这些 候选项和推荐展示给用户。plan 或 revise 只接受匹配当前 artifact、contract 和 wave 的 凭据。用户用 --confirm 明确确认选择；若选择与推荐不同，必须额外 传入 --acknowledge-recommendation 记录已知风险。Batch Inline 始终串行，绝不冒充并行。 Quick、direct Hotfix 与 tweak 保持轻量例外：正常完成时不要求 contract、execution plan、wave receipt 或 DP；在边界内验证后持久化 test_result: pass。但一旦进入 DP-5 调试升级，任何路径都必须先有当前有效的 execution plan，才可记录失败尝试或持久化升级。

ssf execution recommend changes/my-change \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation --json
ssf execution plan changes/my-change --mode sdd --confirm --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 recommend changes/my-change \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation --json
ssf execution revise changes/my-change --mode sdd --confirm --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 失效。恢复、切换和手动保存是 control-plane overlay，不会增加第九个状态；其 CLI 与 CodeBuddy/WorkBuddy Markdown adapter 保持相同 guard。

---

为什么需要它

用 AI 写代码时，最常见的两个问题是：

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

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

spec-superflow 把这两类问题分开处理：先判断改动风险；小改动直接在明确边界内完成并验证，复杂改动再经过需求、规格、执行契约、实现和审查。这样既不让简单问题变成流程项目，也不让高风险改动跳过必要检查。

| 设计原则 | 说明 | |---|---| | 先选路径 | 根据文件数、边界和风险选择 Quick、Hotfix、Tweak 或 Full | | 复杂改动先对齐 | Full 路径用规格与执行契约确认范围和验收方式 | | 实现可验证 | 每条路径都要求与风险相称的测试或检查 | | 有问题先定位 | 遇到失败先复现和找根因，不连续试错 | | 自包含 | 不需要额外安装 OpenSpec 或 Superpowers |

适用场景

✅ 推荐： 大型功能开发、多人协作项目、长期维护项目、需要 TDD + Review Gate 的棕地项目。

❌ 不推荐： 一次性脚本/工具、纯咨询/问答。

四级模式：Quick（≤3 文件/任务低风险代码）、direct Hotfix（incident 且≤2）、Tweak（≤4 配置/文档）直接执行并验证；Full 与 legacy Hotfix 保留规划、契约和 review。

---

核心 Skills

| # | Skill | 阶段 | 职责 | |---|---|---|---| | 1 | workflow-start | 入口 | 内容级状态检测、8 状态路由、阻止非法跳转 | | 2 | need-explorer | 探索 | 一次一问 + 方案对比 + 推荐 | | 3 | spec-writer | 规格 | 产出 proposal/specs/design/tasks，Schema