spec-superflow

---

spec-superflow 把 OpenSpec 的结构化规划与 Superpowers 的验证纪律组合成一个自包含插件。v2 将新任务收敛为两个入口：明确的小改动直接执行，需要共同确认范围的改动先形成一份短计划再执行。

当前版本：v2.1.0

默认行为偏向低成本：当前会话内执行、最终审查一次、最终验证一次、普通调试留在执行阶段。子代理、逐波审查和 worktree 都需要显式选择。

Marketplace 与各平台安装器会把 Skill 和同版本 CLI runtime 一起升级。Skill 只调用当前安装包内的 runtime，不会误用 PATH 中另一份旧 ssf。

为什么是 v2

旧流程把任务分成多个模式，并在规划、契约、执行和审查之间复制状态。复杂任务可以得到约束，但普通任务也会承担固定成本，状态或收据损坏时还可能反复回跳。

v2 删除新任务的模式问卷和手写 execution-contract.md，一份执行计划就是唯一的执行依据：

旧默认	v2 默认
五种路径选择	direct 或 planned
四份规划文档 + 手写契约	proposal.md + tasks.md；spec/design 按需
逐阶段确认	planned 只确认一次具体计划
SDD/子代理和逐任务审查	当前会话执行 + 最终审查
自动 worktree	当前目录特性分支；worktree 显式启用
调试切换独立状态	普通诊断留在 executing
多处缓存可阻塞计划	已批准的 schema v2 执行计划是唯一判断依据

已有变更继续按原来的状态、审批记录和审查结果恢复，不会被自动迁移或重置。默认 Skill 只保留 v2 流程；识别到旧版收据或执行计划时，才按需读取旧流程恢复规则。

快速开始

要求 Node.js 20+。

npm install -g spec-superflow
mkdir -p changes/fix-login-timeout

目标、边界和验证方式已经明确时，直接执行：

ssf workflow start changes/fix-login-timeout \
  --path direct \
  --scope "修复登录超时，不改变认证协议"

ssf workflow complete changes/fix-login-timeout \
  --verification-command "npm test"

范围需要先对齐时，创建两份短文档：

changes/add-session-refresh/
├── proposal.md   # 目标、边界、验收、风险
└── tasks.md      # 有序 checkbox 任务及每项完成后的检查结果

用户批准这份具体计划后开始执行：

ssf workflow start changes/add-session-refresh \
  --path planned \
  --confirm \
  --reason "用户已批准 proposal.md 与 tasks.md"

ssf workflow complete changes/add-session-refresh \
  --verification-command "npm test"

planned 默认生成 inline + final 执行计划。只有明确需要委派时才增加 --mode sdd；只有确实需要独立目录时才运行 ssf isolate <dir> --worktree。

两个执行路径

Direct

适合意图清楚、影响面可判断、验证可复现的改动。它不生成规划包、推荐收据或执行契约，只记录用户请求的范围和最终验证结果。

如果执行中发现范围扩大，补齐 proposal.md 和 tasks.md，再以一次明确批准升级到 planned，无需重开状态机。

Planned

适合跨模块、公共接口、数据语义、安装器或状态机等需要先对齐的改动。

• proposal.md：目标、非目标、验收条件、主要风险。
• tasks.md：唯一编号的 checkbox 任务，每项写清完成条件和检查结果。
• specs/：行为约束或发布基线需要更新时添加。
• design.md：存在真实技术取舍时添加。

实现默认在当前会话串行完成，最后审查完整 Git range。失败审查必须使用稳定 issue ID；同一问题连续三次仍未解决时才进入人工裁决，不把无关问题累计成死循环。

9 个 Skills

Skill 是按需加载的职责模块，不是每次都要走完的九个阶段。新任务只调用当前工作需要的 skill；旧状态机和契约规则仅用于恢复已有变更。

Skill	作用	v2 中何时使用
workflow-start	识别新任务或恢复已有 change，选择 direct / planned 并建立执行上下文	显式启用 spec-superflow 时的入口；普通编码会话不自动激活
need-explorer	澄清问题、范围、非目标和成功标准，比较可选方案	需求模糊或需要先做取舍时按需使用
spec-writer	编写 proposal.md 与 tasks.md；只在需要时增加 specs/design	planned 路径需要形成可批准计划时使用
build-executor	按已授权范围实现、运行相关验证并记录必要进度	direct 和已批准的 planned 都进入这里；默认当前会话连续执行
bug-investigator	复现问题、追踪根因、验证最小修复，避免试错循环	执行中遇到缺陷或测试失败时调用；新任务仍停留在 executing
code-reviewer	审查完整 Git range，验证范围、正确性和实现质量	Native 默认只做一次最终审查；逐波审查仅在显式选择时使用
spec-merger	将 change 中的 delta specs 原子同步到主规格库并检测冲突	只有实际存在 delta specs 时，在完成前使用
release-archivist	运行最终验证，记录验证通过或用户明确接受风险，并处理已授权的合并与归档	实现完成时使用；失败保留实际结果并返回执行阶段修复
contract-builder	维护旧变更的 execution-contract.md 和既有审批义务	仅兼容 legacy change；新 direct / planned 不调用

典型调用链保持短小：

Direct:  workflow-start → build-executor → release-archivist
Planned: need-explorer? → spec-writer → workflow-start → build-executor
         → code-reviewer → spec-merger? → release-archivist
Bug:     build-executor → bug-investigator → build-executor
Legacy:  按已有状态恢复；必要时才进入 contract-builder

其中 ? 表示只有满足条件才调用。默认链路不创建子代理、不逐任务审查，也不自动创建 worktree。

完成任务、处理失败与恢复

workflow complete 会执行一次最终验证。planned 路径还会检查任务、最终审查和已有 delta spec 的同步状态。失败保持在执行阶段，修复后重试；不会把失败写成通过。

这里的“完成”不是让 AI 写一句“已经修好”，而是保存可以核对的结果：执行了什么验证命令、退出码是多少、审查覆盖了哪段 Git 变更，以及检查是否通过。验证通过后状态记为 verified；只有用户明确同意带着已知问题交付时，才记为 accepted-risk。验证失败、Git 审查范围为空或记录损坏，都不能算完成。

用户决定带着已知问题结束时，可以显式记录风险：

ssf workflow complete changes/example \
  --accept-risk \
  --confirm \
  --reason "接受已记录的兼容性限制，后续单独处理"

结果是 accepted-risk，原来的失败结果仍会保留，并且不会自动合并分支。

恢复已有任务：

ssf resume changes/example
ssf checkpoint list changes/example

缺失或损坏的授权记录、审查结果或 Git 范围信息会明确报错；工具不会用默认值伪造通过。完整状态与兼容规则见 状态机文档。

Git 隔离

默认在当前 checkout 创建特性分支，减少目录切换和路径漂移：

ssf isolate changes/example

只有需要同时维护多个 checkout 时才使用 worktree：

ssf isolate changes/example --worktree

隔离信息会记录目标仓库、分支和路径；恢复时必须匹配这份记录。ssf finish 只处理已验证的隔离分支，验证失败会保留分支和工作目录供修复。

安装

Claude Code

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

OpenAI Codex CLI / App

codex plugin marketplace add MageByte-Zero/spec-superflow --ref v2.1.0
codex plugin add spec-superflow@spec-superflow

Codex 不启用 SessionStart 自动注入；请按需调用 workflow-start，或进入已有 spec-superflow change 后恢复。

Cursor

npx spec-superflow@latest install-cursor

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

CatPaw（妙手，导入包预览）

node scripts/spec-superflow.mjs package-catpaw ./catpaw-spec-superflow

在妙手「技能」中导入生成的文件夹。包内包含同版本 CLI 和九个流程技能，升级时一起重新导入。此命令随下一版本发布；目前已验证包结构与本地 CLI，尚未完成妙手客户端验收。

项目另支持 19 个 AI 编程平台。其他平台的安装器、目录和卸载方式见 INSTALL.md，能力差异见 平台矩阵。

命令

命令	用途
`ssf workflow start --path direct	planned`
ssf workflow complete <dir> ...	验证并记录交付结果
ssf isolate <dir> [--worktree]	创建特性分支或显式 worktree
ssf resume [dir]	读取恢复上下文
`ssf checkpoint save	list
ssf validate <dir>	验证规划和 delta spec
ssf sync <dir>	原子同步 delta spec 到发布基线
ssf doctor	检查安装、版本和资源一致性
ssf finish <dir>	验证并合并已记录的隔离分支
ssf package-catpaw <new-dir>	生成妙手可导入的完整技能文件夹

运行 ssf --help 查看完整命令。workflow recommend/select/accept、旧 execution plan 和八状态路由只用于恢复 v1 变更。

设计边界

• 按需规划：小改动不承担完整 SDD 的固定成本。
• 一次批准即可执行：新 planned 任务把批准范围和执行模式写入 schema v2 执行计划，后续不重复确认。
• 结果必须可核对：空 Git range、截断范围、损坏 hash 或过期审查不能通过。
• 人类决策可见：可接受风险，但必须留下理由，且不能伪造验证成功。
• 零运行时依赖：CLI 使用 Node.js 标准库；TypeScript 仅用于构建。
• 按需加载：普通会话不应被 SessionStart 或全局规则强制注入完整工作流。

项目借鉴 OpenSpec 的规格组织与 Superpowers 的 TDD、调试和审查纪律，但运行时不依赖二者。

关注「码哥跳动」

开发

npm install
npm run build
npm test
npm run validate
npm run check-versions

贡献说明见 CONTRIBUTING.md，版本历史见 CHANGELOG.md。

License

MIT