spec-superflow 2.0 发布：小任务走 Direct，复杂任务走 Planned

AI 编程最难兼顾的两件事，是速度和确定性。

只追求速度，小任务做得很快，遇到跨模块改造却容易在执行中改变需求、遗漏边界；只追求严谨，每个任务都写完整规格、设计和审查材料，一个小修复也会被流程拖慢。

spec-superflow 2.0 给出的答案，是让流程随风险变化。

边界清楚的小任务走 Direct，在当前会话连续开发、验证和交付；复杂任务走 Planned，用 proposal、tasks 和按需规格锁定目标，再通过完整范围审查与最终验证保证实现没有漂移。

它融合了 OpenSpec 的结构化规划能力，也吸收了 Superpowers 的调试、审查和验证纪律。最终得到的不是两套工具的简单拼接，而是一套能覆盖真实软件开发复杂度的 AI 工程工作流。

一套工作流，覆盖两类完全不同的开发任务

spec-superflow 2.0 把新任务收敛为两个入口。

Direct：让明确的小任务直接进入开发

Direct 适合目标、边界和验证方式都清楚的工作，例如：

• 修复一个已经定位的登录超时；
• 调整配置、文档或局部交互；
• 修改少量文件且不改变公共协议；
• 已经知道根因和验收命令的缺陷修复。

它不强制先生成完整规划工件，也不默认派发子代理或创建 worktree。AI 可以留在当前会话连续理解代码、完成实现、自检并运行最终验证，减少上下文交接和重复读取。

Direct 的价值不是“少写几份文档”，而是让简单任务保持简单。

Planned：让复杂任务从批准范围走到可验证交付

Planned 面向跨模块、公共接口、状态机、数据语义和多人协作等复杂变更。

默认只需要两份核心工件：

• proposal.md：为什么改、要改变什么、边界在哪里；
• tasks.md：怎样执行、每一步如何验证。

当行为基线需要精确定义时，再增加 delta specs；当存在架构选择和长期约束时，再增加 design。工件由风险决定，不用固定模板把任务越写越重。

批准以后，执行始终围绕同一份计划推进。范围发生变化，系统会明确识别漂移；实现完成后，审查覆盖完整 Git range，最终验证记录真实结果。复杂任务因此既能持续推进，也不会在几十轮对话后变成另一个需求。

OpenSpec 管“做什么”，Superpowers 管“怎样可靠地做完”

OpenSpec 最有价值的地方，是把需求从聊天内容变成可检查的工程对象。

proposal 保存变更动机和范围；delta spec 用 ADDED、MODIFIED、REMOVED、RENAMED 表达行为变化；Requirement 与 Scenario 把“应该这样工作”变成可以测试的约束。这让复杂任务在进入代码前就有稳定边界。

Superpowers 的优势则在执行纪律：先理解再实现，遇到失败先调查根因，完成前审查真实改动并运行验证。它解决的是 AI 容易“写完就宣布完成”的问题。

spec-superflow 2.0 把两者连接成一条闭环：

1. 用风险选择 Direct 或 Planned；
2. Planned 用结构化工件锁定目标，Direct 保留明确 scope；
3. 默认在当前会话连续执行，减少上下文损耗；
4. 失败进入根因调试回环，修复后回到原执行链；
5. 按入口加载审查强度，最后统一验证；
6. 只有真实验证通过，才能记录为 verified。

如果某项风险经过人类判断可以接受，也能记录为 accepted-risk，但失败证据会被保留，不会被包装成验证通过。机器负责提供证据，人类保留最终决策权。

复杂任务为什么不容易漂移

很多 AI 工作流的问题不在“有没有计划”，而在计划、代码、审查和验证是不是同一件事。

spec-superflow 2.0 为这条链路补齐了几个关键约束。

规划事实只有一个来源。 新 Planned 任务由 schema v2 execution plan 承载授权、范围和执行模式，避免多份摘要彼此不一致。

审查覆盖完整改动。 它拒绝空 Git range，也不会用 HEAD~1 把多提交变更截成最后一次提交。审查证据必须与实际变更范围一致。

验证结果绑定最终状态。 finish 验证会记录影响结果的输入指纹。代码或环境发生变化，就不能继续复用旧的“通过”。

恢复必须回到正确目录和分支。 默认隔离方式是普通特性分支；只有明确需要多个并行 checkout 时才创建 worktree。恢复记录会校验仓库、分支和路径，submodule 与失败重试也保留在正确隔离环境中。

路径边界可以验证。 symlink、安装目标、overlay 和跨平台 realpath 都经过边界检查，避免自动化流程把文件写到预期目录之外。

这些能力平时不会增加对话负担，却会在复杂任务最容易失控的位置发挥作用。

9 个 Skills，是能力菜单，不是九个必经阶段

小任务最短可以是：

workflow-start → build-executor → release-archivist

复杂任务则按需要组合：

need-explorer? → spec-writer → workflow-start
→ build-executor → code-reviewer → spec-merger?
→ release-archivist

问号代表按需启用。你获得的是一组可以组合的工程能力，而不是一条所有任务都必须走完的流水线。

默认更轻，也保留高级执行能力

2.0 默认使用 Native 模式，让当前 Agent 在当前会话持续实现。普通任务不必为了“流程完整”自动拆成子任务、派发多个 Agent，再等待逐波审查。

复杂任务需要并行时，SDD、子代理和逐波 review 仍然可以显式启用；需要同时维护多个 checkout 时，也可以显式选择 worktree。区别在于这些能力现在由任务需要触发，而不是成为每次开发的固定成本。

普通会话也不会被 SessionStart 或全局规则塞入完整工作流；进入已有 change 或显式调用时，才读取需要的说明和状态。

这让 spec-superflow 既适合一个文件的小修复，也能承载跨模块、跨提交、长周期的复杂开发。

经过大版本验证，而不只是改了流程说明

从 v1.2.0 到 v2.0.0，本次升级跨越 5 个提交、115 个文件，Git shortstat 为 3374 行新增、3291 行删除。

本地发布候选完成了：

• 153 个测试 suite、916 个自动化测试；
• raw package 安装与运行 smoke test；
• CLI、Skills、模板、安装器和文档一致性检查；
• Linux、macOS 与 Windows 路径边界覆盖。

项目保持零运行时依赖，Node.js 20+ 即可运行，并为 Codex、Claude Code、Cursor、GitHub Copilot CLI、Gemini CLI、OpenCode、WorkBuddy、Trae 等 19 个 AI 编程平台提供接入方式。

使用方式一：安装 2.0

截至本文发布准备时，v2.0.0 tag 已指向包含新版 README 的最新提交。GitHub Release 与 npm 2.0.0 仍等待 Marketplace 版本门禁，因此 Codex CLI / App 可以先固定 tag 安装：

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

其他平台可以从仓库根目录运行安装器，也可以查阅 INSTALL.md 中对应平台的命令。

使用方式二：用 Direct 完成一个小任务

边界明确的小任务，直接启动 Direct：

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"

如果验证失败，状态不会被写成通过。修复后继续执行同一个 change，再次完成验证即可。

使用方式三：用 Planned 推进复杂任务

复杂任务先创建 proposal.md 和 tasks.md。涉及公共行为时补充 specs，存在架构取舍时补充 design。用户确认范围后启动：

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

执行过程中可以随时检查和恢复：

ssf resume changes/add-session-refresh
ssf checkpoint save changes/add-session-refresh
ssf validate changes/add-session-refresh

如果包含 delta specs，交付前使用 ssf sync 原子同步正式规格；完成实现、完整范围审查和最终验证后，再执行关闭与归档。

使用方式四：选择分支或显式 worktree

默认创建普通特性分支：

ssf isolate changes/add-session-refresh

只有需要同时维护多个 checkout 时才显式创建 worktree：

ssf isolate changes/add-session-refresh --worktree

恢复和完成操作都会核对记录中的仓库、分支和路径，避免在错误目录继续执行。

选择标准可以压缩成三句：目标和验证清楚，用 Direct；需要先批准范围，用 Planned；只有并行收益或隔离需求明确时，才启用子代理和 worktree。

让 AI 编程既快，又能对最终结果负责

spec-superflow 2.0 的目标很明确：小任务不被流程拖慢，复杂任务不因对话变长而漂移。

OpenSpec 提供可持续维护的需求与规格结构，Superpowers 提供根因调试、代码审查和完成前验证，spec-superflow 则把它们变成可以在真实项目里按风险运行的完整闭环。

如果你正在用 Codex、Claude Code、Cursor 或其他 AI Agent 开发项目，可以从一个 Direct 小任务开始；下一次遇到跨模块改造，再用 Planned 感受范围锁定、执行恢复和完整审查带来的确定性。

项目地址：MageByte-Zero/spec-superflow。欢迎 Star、试用和提交反馈。

也欢迎关注公众号「码哥跳动」。我会继续分享 AI 编程工作流、Agent 工程实践，以及如何让大模型真正进入可验证的软件开发流程。