git-learn/skill-workbench/docs/sm-flow/workflow.md

SM-Flow 工作流

当前设计理念（v4 方向）

核心定位：sm-flow 是一个用提示词实现的协议层 harness——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。

四层架构：

sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出

用户命令（4 个）：

命令	用户意图
/sm-flow	完整流程
/sm-flow explore	先想想（需求不清楚）
/sm-flow apply	只执行（已有 Committed OpenSpec）
/sm-flow archive	收尾（回填 devflow + 归档确认）

内部阶段（9 个，英文动词命名）：

clarify → context → propose → grill → specify → audit → commit → apply → archive
入口澄清   上下文     轻量提案   澄清    细化      审计    提交     执行    归档

阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。

关键设计决策：

• 真理源分层：devflow = 上下文（术语、历史决策、验收记录），OpenSpec = 执行（唯一执行真理源），代码 = 结果。devflow 增强 OpenSpec，不替代 OpenSpec。
• Draft / Committed 分离：propose 产出 Draft OpenSpec（讨论对象），commit gate 后成为 Committed OpenSpec（执行许可）。apply 只执行 Committed OpenSpec。
• grill 在 specify 前：先澄清需求再细化产物，避免"细化 → grill → 回写细化"的返工循环。propose 只写轻量 proposal.md，grill 稳定需求后 specify 才补全 design/specs/tasks。
• devflow 延迟写入：clarify → apply 期间只维护 decisions.md 作为过程日志，archive 阶段从中提取完整 devflow 档案（brief/evidence/acceptance）。
• micro ≠ skip：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
• 质量约束可观测：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。

使用方式：

详细的使用说明见 使用方式.md，包括：

• 4 个用户命令的典型场景
• 完整规划 → 执行 → 归档的分次调用示例
• 自然语言交互方式
• 规模分档（micro / standard / complex）
• devflow 自动维护机制
• OpenSpec 集成与 Draft/Committed 分离
• 常见问题解答

---

演进历史

以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。

旧工作流 vs 新工作流

旧：                       新：
Phase 1  手动整理PRD        Phase 0   手动初始PRD（入口，保留人的判断）
Phase 2  openspec:explore   Phase 1    openspec:propose → research
Phase 3  grill-me           Phase 1.5  to-prd → 结构化PRD（替代初始PRD）
Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
                            Phase 2.5  zoom-out → 架构审计
                            Phase 3    openspec:apply → 执行
                                       diagnose → bug排查
                                       tdd → 质量闭环
横切：                     横切：
       无                            git-guardrails → 安全锁

关键变化：手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。

旧工作流的三个关键缺口

1. 需求澄清后缺少可行性验证

   • 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现
   • 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行"

2. openspec 产出不能沉淀到长期记忆

   • 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢
   • 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文

3. apply 完成后缺少验证闭环

   • 旧：apply → 完成。功能对不对取决于人肉测试
   • 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor）

新增技能的投入产出

技能	学多久	一次省多少	什么时候用
to-prd	0 分钟（自动综合）	10-15 分钟	openspec research 结束后
grill-with-docs	替换已有 grill-me	0 额外时间 + 产出文档	需求澄清阶段
zoom-out	10 秒（一句话）	避免方向性返工	grill 完成后、apply 前
diagnose	5 分钟了解流程	每次 bug 省 20-30 分钟	apply 中遇到问题
tdd	5 分钟了解流程	减少回归 bug	apply 中写代码
git-guardrails	0 分钟（被动生效）	防止灾难性操作	全程自动

为什么这套组合优于单纯依赖 openspec

openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题：

• 领域知识沉淀：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐
• 质量验证：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环
• 流程安全：openspec 不管 AI 误操作 → git-guardrails 补齐安全层

一句话：openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。

v2.0：devflow/ 产物聚合层

问题

v1.0 一次完整流程的产物散落在 5 个位置：

CONTEXT.md                 ← Phase 2 (根目录)
docs/adr/                  ← Phase 2 (docs/)
docs/agents/               ← Phase 1.5 (docs/)
openspec/changes/          ← Phase 1+3 (openspec/)
knowledge/entries/         ← /knowledge-absorber

三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按工具来源组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按项目本身组织。

借鉴 CodeStable 的单一聚合根设计

CodeStable 的核心设计决策：所有产物集中在 codestable/ 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。

dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个人类可读的档案层：

devflow/                              ← 单一入口
├── projects/YYYY-MM-DD-{slug}/       ← 一个 PRD→实现 闭环
│   ├── {slug}-prd.md                 # Phase 0+1.5 需求文档
│   ├── {slug}-research.md            # Phase 1 技术方案（从 openspec 提取）
│   ├── {slug}-design.md              # Phase 1+2.5 设计 + 架构审计
│   ├── {slug}-tasks.md               # Phase 1 任务清单（从 openspec 提取）
│   ├── {slug}-acceptance.md          # Phase 3+4 验收报告
│   └── adr/                          # Phase 2 架构决策
├── glossary/
│   └── CONTEXT.md                    # 跨项目领域词汇表
├── compound/                         # 跨项目知识沉淀
│   └── YYYY-MM-DD-{type}-{slug}.md   # type ∈ {learning, trick, decision, explore}
└── reference/                        # 共享模板/规范

两层架构

	openspec/changes/	devflow/projects/
角色	工具工作区（WAL）	人类档案层（Tables）
谁读	机器	人
生命周期	活跃变更期 → Archive 后清空	永久保留
组织方式	按变更名	按日期 + 项目

关键：openspec archive 后 openspec/changes/ 清空，但 devflow/projects/ 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。

各 Phase 产物路径变化

Phase	v1.0	v2.0
1.5 PRD	docs/agents/<name>-prd.md	devflow/projects/{date}-{slug}/{slug}-prd.md
2 CONTEXT	根目录 CONTEXT.md	devflow/glossary/CONTEXT.md
2 ADR	docs/adr/	devflow/projects/{slug}/adr/
2.5 架构审计	对话中，丢失	devflow/projects/{slug}/{slug}-design.md
4 验收	docs/agents/lessons/	devflow/projects/{slug}/{slug}-acceptance.md
4 经验沉淀	无	devflow/compound/YYYY-MM-DD-{type}-{slug}.md
4 从 openspec 提取	无	提炼到 {slug}-research.md + {slug}-tasks.md

一键启动

已固化为 skill：/dev-flow

/dev-flow                     # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程
/dev-flow --prd docs/my-idea.md  # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1
/dev-flow --from phase2       # 已有 research，从 grill 开始
/dev-flow --from apply        # 已有 PRD + 文档，直接执行
/dev-flow --quick             # 小需求，跳 PRD 精化 + zoom-out

Skill 位置：.claude/skills/dev-flow/SKILL.md

Skill 评估结论（2026-05-19）

详细评估报告见：devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md。

总体判断

dev-flow 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。

最有价值的设计是 devflow/ 产物聚合层：

• openspec/changes/ 负责机器可执行的变更工作区。
• devflow/projects/ 负责人类可回溯的项目档案。
• devflow/glossary/CONTEXT.md 负责跨项目领域词汇。
• devflow/compound/ 负责沉淀可复用工程知识。

评估中发现的核心问题是：早期 SKILL.md 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。

已确认的亮点

1. 产物聚合层设计清晰

   • devflow/projects/YYYY-MM-DD-{slug}/ 解决了 openspec archive 后上下文难以回溯的问题。
   • 工具工作区和人类档案层分离，职责边界明确。

2. 阶段顺序合理

   • Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。

3. Phase 4 很有价值

   • 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
   • 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。

4. 文档化追问方向正确

   • Phase 2 要求一次只问一个问题，并即时更新 CONTEXT.md / ADR。
   • 这符合“边澄清边沉淀”的工作方式。

5. 质量闭环意识强

   • Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
   • TDD 被设计为可选增强，避免对所有任务强制套用重流程。

主要改进点

问题	改进方向
触发描述不够完整	明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景
Claude 工具耦合较强	保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback
依赖安装状态写死	改为启动时检查 required / optional / fallback
子 skill 调用方式不稳	优先调用子 skill；不可调用时读取对应 SKILL.md；不存在时执行最小协议
缺少初始化算法	明确 devflow/ 目录骨架、slug 生成、重名处理和旧 CONTEXT.md 迁移规则
缺少模板	拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板
quick 模式与约束冲突	quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档
Phase 退出条件不足	为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径

产品化方向

评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”：

• SKILL.md 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。
• references/ 承载长内容：Phase 契约、模板、归档规则、fallback 协议。
• 每个 Phase 都要有明确的进入条件和退出条件。
• quick 模式、fallback、归档确认、人类检查点必须写成硬规则。
• devflow/ 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。

后续演进：sm-flow 产品化

基于这次评估，dev-flow 的设计被重构为 .agents/skills/sm-flow/。这一步仍属于 v2 产品化：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。

.agents/skills/sm-flow/
├── SKILL.md                         # 短执行协议
└── references/
    ├── phase-contracts.md           # Phase 输入/动作/输出/退出条件
    ├── templates.md                 # PRD/ADR/验收等模板
    ├── archive-rules.md             # 从 openspec 提取到 devflow 的规则
    └── fallbacks.md                 # 子 skill 不可用时的最小协议

v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 devflow/ 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。

v3.0：OpenSpec-first / Devflow-assisted

背景

v2 跑通后暴露出一个更深的问题：devflow/ 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。

这会导致两套“执行依据”并存：

devflow/projects/{slug}/...     # 人类档案层，也包含 PRD/design/tasks
openspec/changes/{change}/...    # 工具工作区，也包含 proposal/design/specs/tasks

如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。

v3 的核心判断

v3 不重新设计一套替代 openspec 的工作流，而是明确：

devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。

职责分层变为：

层	角色	负责回答
devflow/	上下文真理源 / 长期记忆	为什么这样做？术语是什么？历史决策是什么？之前怎么验收？
openspec/changes/	执行真理源 / 当前变更规格	这次到底改什么？验收标准是什么？任务是否完成？
code	实现结果	OpenSpec apply 后实际落地的代码

v2 vs v3

维度	v2：devflow 聚合层	v3：OpenSpec-first / Devflow-assisted
核心目标	防止 openspec archive 后上下文丢失	防止 devflow 与 openspec 成为并列执行源
devflow 角色	人类可读档案层	上下文增强层 + 归档层
openspec 角色	工具工作区	当前变更的唯一默认执行真理源
Phase 1	openspec propose 产出 research	基于 devflow 上下文生成/修正 OpenSpec 产物
Phase 2	grill-with-docs 更新 glossary/ADR	human-in-the-loop 澄清后必须回写 OpenSpec
Phase 2.5	zoom-out 产出架构审计	架构审计若影响实现，必须回写 OpenSpec design/tasks
Phase 3	openspec apply + diagnose/tdd	默认只能依赖 OpenSpec apply；devflow 只作参考上下文
Phase 4	从 openspec 提炼到 devflow	轻量回填 devflow 必要档案，避免重复 OpenSpec

v3.1：Devflow 产物瘦身

v3 继续跑完整流程后，又暴露出一个实践问题：devflow 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。

因此 v3.1 明确：devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。

默认必要产物收敛为：

devflow/projects/YYYY-MM-DD-{slug}/
├── brief.md        # 背景、目标、范围、非目标、关联 OpenSpec
├── evidence.md     # 代码/文档证据、evidence-driven 结论和汇报状态
├── decisions.md    # user-interview 确认、关键取舍、OpenSpec 回写记录
└── acceptance.md   # 实现结果、验证、未验证项、archive 状态

扩展产物只在有明确理由时创建：

• prd.md：复杂需求、对外协作或用户明确要求。
• research.md：真实调研、代码考古、竞品/API 对比或复杂方案比较。
• design.md：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。
• tasks.md：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
• alignment.md / clarifications.md：冲突或澄清问题很多时拆出；否则并入 decisions.md。

规模分档：

分档	适用场景	devflow 默认产物
micro	小改动、低风险、需求明确	brief.md、decisions.md、acceptance.md；证据少时并入 brief.md
standard	默认模式	brief.md、evidence.md、decisions.md、acceptance.md
complex	高风险、跨模块、需求不清、多人协作	standard + 按需 PRD/research/design/tasks/alignment

v3 新增 Phase 0.5

v3 在 Phase 0 和 Phase 1 之间增加：

Phase 0.5  Devflow Context Harvest

读取：

• devflow/glossary/CONTEXT.md
• 相关项目 PRD/design/tasks/acceptance
• 相关 ADR
• devflow/compound/ 中的 learning、trick、decision、explore

目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。

v3 中各 skill 的参与方式

这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”：

阶段	主要 skill / 工具	作用	产物去向
Phase 0 初始需求 / PRD / research	sm-flow	收集原始需求、已有 PRD 或 research，判断启动模式	入口摘要、初步 slug
Phase 0.5 Devflow Context Harvest	sm-flow	读取 devflow/ 的 glossary、ADR、历史 PRD、acceptance、compound knowledge	作为 Phase 1 的 OpenSpec 输入上下文
Phase 1 OpenSpec propose	openspec-propose	生成或修正 proposal.md、design.md、specs/**/*.md、tasks.md	openspec/changes/<change>/
Phase 1.5 PRD / OpenSpec 对齐	to-prd + sm-flow	检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD	brief.md / 按需 prd.md；冲突回写 OpenSpec
Phase 2 Human-in-the-loop 澄清	grill-with-docs	追问术语、边界、验收；区分 evidence-driven 和 user-interview	evidence.md / decisions.md；影响实现的结论回写 OpenSpec
Phase 2.5 架构审计	zoom-out	拉高视角审查模块、数据流、耦合、架构风险	默认写入 decisions/evidence；复杂审计才拆 design.md；影响实现则回写 OpenSpec
Phase 3 OpenSpec apply	openspec-apply-change	按 OpenSpec specs/tasks 执行实现	代码变更、OpenSpec task 状态
Phase 3 bug/不确定行为	diagnose	复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归	根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance
Phase 3 高风险/复杂行为	tdd	按 OpenSpec specs 做纵向切片测试驱动	测试与实现代码
Phase 4 回填 devflow	sm-flow + openspec-archive-change	从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive	devflow/projects/、devflow/compound/；用户确认后 archive

说明：grill-me 在 v3 中不再作为主要入口，已被 grill-with-docs 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。

v3 的执行规则

1. OpenSpec 是执行真理源

   • Phase 3 默认必须依赖 openspec/changes/<change>/proposal.md、design.md、specs/**/*.md、tasks.md。
   • 不允许直接基于 devflow/projects/... 绕过 OpenSpec 写代码。

2. Devflow 是上下文真理源

   • 术语、历史决策、项目背景、踩坑记录来自 devflow/。
   • 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。

3. 冲突先修 OpenSpec

   • 如果 devflow 和 OpenSpec 冲突，不能直接执行。
   • 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。

4. evidence-driven 也必须汇报

   • 证据驱动不是“AI 自己确认完就继续”。
   • 代理必须汇报查了什么、得出什么结论、是否需要用户确认。

5. user-interview 必须等待确认

   • 涉及范围、偏好、验收口径、风险接受度时，必须问用户。

6. 归档仍回到 devflow

   • OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。
   • Phase 4 询问是否 archive OpenSpec change，不默认执行。

7. devflow 产物按需生成

   • 默认只生成 brief、evidence、decisions、acceptance。
   • PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。
   • 小需求走 micro，不能让文档成本超过实现成本。

v3 流程图

Phase 0    初始需求 / PRD / research
           skill: sm-flow
   ↓
Phase 0.5  读取 devflow 上下文
           skill: sm-flow
   ↓
Phase 1    生成或修正 OpenSpec proposal/design/specs/tasks
           skill: openspec-propose
   ↓
Phase 1.5  PRD / Devflow / OpenSpec 对齐检查
           skill: to-prd + sm-flow
   ↓
Phase 2    human-in-the-loop 澄清，并回写 OpenSpec
           skill: grill-with-docs
   ↓
Phase 2.5  架构审计；影响实现则回写 OpenSpec
           skill: zoom-out
   ↓
Phase 3    OpenSpec apply 执行
           skill: openspec-apply-change；按需 diagnose / tdd
   ↓
Phase 4    回填 devflow，并确认是否 archive
           skill: sm-flow；用户确认后 openspec-archive-change

v3 一句话定位

sm-flow 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。

v3.1：可执行 gate 与使用摩擦修正

v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。

v3.1 不改变 v3 的主轴：

devflow/ 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。

Draft / Committed OpenSpec

Phase 1 产出的 OpenSpec 统一视为 Draft OpenSpec。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。

Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：

Phase 2.9 Commit OpenSpec

Phase 2.9 检查：

• proposal 是否说明范围、非目标和原因。
• design 是否记录关键约束、架构风险和接口影响。
• specs 是否覆盖可观察行为和验收口径。
• tasks 是否是可执行的纵向切片。
• 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。

只有通过 Phase 2.9 的 OpenSpec 才是 Committed OpenSpec，Phase 3 只能执行 Committed OpenSpec。

Grill 必须人工确认

Phase 2 的 grill-with-docs 不是代理自问自答。user-interview 问题必须一次只问一个，等待用户显式回答，并记录到 decisions.md。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。

evidence-driven 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。

Phase 2 在开始追问前，还应该先建立一个 question pool。最小问题池至少覆盖：

• 术语
• 范围边界
• 验收口径

如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，再把这些维度补进问题池。问题池的作用是先把风险面列全，再继续保持 one-at-a-time 的 user-interview 消费节奏，而不是一次把所有问题都抛给用户。

单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。

Phase Checkpoint

v3.1 的另一个收紧点是：关键阶段不再靠“看起来做完了”判断完成，而是靠显式 checkpoint。

关键阶段至少包括：

• Phase 0
• Phase 0.5
• Phase 1
• Phase 2
• Phase 2.5
• Phase 2.9

每个 checkpoint 至少说明：

• 当前阶段
• 调用的 capability 来源
• 产出的关键 artifact
• 已满足的退出条件
• 尚未解决的 blocker

如果没有这些信息，就不应该把阶段视为已完成，更不应该直接进入下一阶段。

Cross-Artifact Alignment

v3.1 之后，Phase 1.5 和 Phase 2.9 不只是“看看文档差不多”，而是要显式检查一条对齐链：

brief/prd -> proposal -> design -> specs -> tasks

检查重点不是格式，而是下游产物有没有把上游已经确定的内容接住，例如：

• brief/prd 里的范围和非目标有没有进入 proposal
• proposal 的关键承诺有没有进入 design
• design 里的实现约束和接口影响有没有进入 specs 或 tasks
• specs 里的可观察行为有没有被 tasks 切成可执行工作

如果字段、术语、约束、行为或切片只停留在上游文档里，就应该视为对齐缺口，先修 OpenSpec，再继续流程。

接口影响分级

v3.1 区分“接口影响记录”和“独立接口文档”：

• 所有接口变更都必须记录影响范围。
• 只有 L3/L4 才强制独立接口文档或等价独立章节。

分级规则：

级别	判断条件	产物要求
L1 内部实现	不改变调用方可观察行为	tasks / acceptance 记录验证
L2 内部接口	内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内	内联接口影响记录
L3 协作接口	影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK	独立接口文档或独立章节
L4 破坏性接口	旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚	独立接口文档 + 迁移/回滚说明，必要时 ADR

接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。

Devflow Index

devflow/index.md 成为 Phase 0.5 的默认入口。上下文查找顺序为：

devflow/index.md
devflow/glossary/CONTEXT.md
相关项目 brief / acceptance / ADR
devflow/compound/

Phase 4 回填项目档案时必须更新 devflow/index.md。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。

另外，v3.1 也把一个实践经验写成硬规则：devflow 不是等到 Phase 4 才第一次补写。brief.md、evidence.md、decisions.md 这类过程内档案应该随阶段就近更新，Phase 4 主要负责 consolidation 和归档口径收束。

Micro 不是 Skip

micro 的目标是降低文档重量，不是给代理发放“可以跳 gate”的许可证。

因此即使是 micro 变更，也仍然要保留：

• Phase 0.5 最小上下文收集
• Phase 2 最小澄清
• Phase 2.9 commit gate
• Phase 4 轻量回填

如果因为“改动很小”就跳过这些 gate，应该视为协议偏差，而不是合法优化。

实现期冲突处理

Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：

分类	含义	处理
实现偏差	OpenSpec 正确，代码没有按规格做	修代码，不改 OpenSpec
规格遗漏	OpenSpec 没覆盖真实边界、接口影响、验收或外部行为	暂停 apply，修正 OpenSpec，重新 commit
设计冲突	OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突	暂停并请用户确认设计方向
用户变更	用户改变目标、范围、验收或风险接受度	更新 proposal/specs/tasks 后继续

冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 decisions.md 或 acceptance.md。

子 skill 兼容

v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 openspec-propose、openspec-apply-change、to-prd、grill-with-docs 都是能力契约。

调用优先级：

1. 平台原生 skill。
2. 本地 SKILL.md，例如 .claude/skills/... 或 .agents/skills/...。
3. sm-flow 的 fallback 协议。

这样 sm-flow 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。

一旦进入 fallback，代理还必须把这次降级本身记录下来。也就是说，fallback 不只是“内部换个做法”，而是一个需要显式声明 capability 缺失、降级原因和风险的协议事件。

v3.1 后续收口：协议瘦身与 review 修正

在执行硬化规则落地后，又做了一轮非常实际的收口：不是再增加新规则，而是把已经确认的规则放到更稳定、可维护的位置，并修掉瘦身过程中暴露的引用问题。

顶层 skill 瘦身

SKILL.md 不再同时承担“入口协议”和“大段运行手册”两种职责，而是收敛为：

• 工作流定位
• 真理源分层
• 核心硬规则
• reference 加载入口
• 阶段总览

原来放在顶层但更适合按需读取的内容，被下沉到新的：

references/operating-rules.md

这里集中放：

• 接口影响分级
• 启动检查
• 项目标识规则
• devflow 产物分层
• 快速模式细则
• 完成标准

这样做的目标不是减少规则，而是减少“启动时一次读太多”和“顶层协议与 reference 抢职责”的问题。

Fallback 去重复

fallbacks.md 也做了第二轮整理：

• 顶部统一定义 fallback 通用记录要求
• 各 fallback 小节只保留自己的额外记录义务

这样可以避免每个 fallback 都重复写一遍“要声明 fallback、要记录 fallback”，同时不丢失协议要求。

Review 驱动的自洽性修正

瘦身后又发现了一类很典型的问题：规则本身没错，但 cross-reference 可能断掉。因此又补了一轮 review 驱动修正，重点包括：

• phase-contracts.md 在首次使用接口分级、分档、快速模式时，显式指向 operating-rules.md
• 修正 fallback 锚点，避免 skill 指向不存在的章节名
• 统一 operating-rules.md 的语言风格，避免在主协议是中文时夹着一整份英文运行规则

这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽。

v4.0：协议层 Harness 重设计

背景

v3.1+ 的规则已经比较完整，但一次完整设计评审暴露出三个结构性问题：

1. 定位模糊：SKILL.md 说”不替代 OpenSpec，而是增强”，但实际上 sm-flow 已经在编排 OpenSpec 的完整生命周期——包括 propose 时机、grill 顺序、commit gate、apply 授权。这不是”增强”，这是”编排”。
2. 阶段顺序导致返工：Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然回写已细化的产物，形成不可避免的返工循环。
3. 规则过载：19 条核心规则平铺在一个列表里，混合了硬约束、流程约束和质量约束。agent 读到第 15 条已经记不清前 5 条的优先级。

核心认知转变

sm-flow 不是一个”更好的 skill”，也不是 OpenSpec 的增强插件。它是一个用提示词实现的协议层 harness——控制 agent 以什么顺序、什么条件、什么标准使用工具。

这个认知来自一个类比：Claude Code harness 是代码实现的（工具权限、hooks、context window），agent 物理上绕不过。sm-flow 是提示词实现的，agent 理论上可以违反。因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力——这些机制的本质就是弥补提示词 harness 缺乏物理强制力的弱点。

四层架构

Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd

用户命令：Actions, Not Phases

借鉴 OpenSpec 的 “Actions, Not Phases” 设计哲学——用户命令表达意图，不表达阶段。阶段是 harness 的内部词汇，不是用户的 API。

v3.1 有 9 个阶段编号（Phase 0 / 0.5 / 1 / 1.5 / 2 / 2.5 / 2.9 / 3 / 4），用户需要记住每个编号对应的含义。v4 收敛为 4 个用户命令：

命令	用户意图
/sm-flow	完整流程（从入口到归档）
/sm-flow explore	先聊聊（需求不清楚）
/sm-flow apply	只执行（已有 Committed OpenSpec）
/sm-flow archive	收尾（回填 devflow + 归档确认）

内部阶段全部改为英文动词命名：

clarify → context → propose → grill → specify → audit → commit → apply → archive

阶段顺序调整：grill 在 specify 前

v3.1 的执行顺序：propose（完整 4 件套）→ grill → specify → audit → commit → apply

v4 的执行顺序：propose（只写轻量 proposal）→ grill → specify（补全 design/specs/tasks）→ audit → commit → apply

核心改变：propose 只写轻量 proposal.md，不调用 openspec-propose。grill 在需求稳定前完成澄清。specify 在需求稳定后才调用 openspec-propose 补全完整 OpenSpec。

这消除了返工循环——grill 在细化之前，不存在”细化 → grill → 回写细化”的问题。

devflow 延迟写入

v3.1 要求 devflow 产物按阶段就近更新（brief、evidence、decisions 随阶段写入），Phase 4 做 consolidation。实践中 agent 同时维护 OpenSpec 和 devflow 形成双重记录。

v4 改为：clarify → apply 期间只维护 decisions.md 作为过程日志。archive 阶段从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。

规则精简：19 条 → 6 条硬约束

v3.1 的 19 条规则按三类分组（硬约束 7 条 / 流程约束 7 条 / 质量约束 5 条）。v4 进一步精简为 6 条硬约束留在 SKILL.md，其余约束下沉到 phase-contracts.md 各阶段退出条件。

v3.1：SKILL.md 包含 19 条三类规则 → agent 需要同时记住所有规则
v4：SKILL.md 只放 6 条硬约束 → agent 按阶段加载对应的过程约束和质量约束

6 条硬约束：

1. OpenSpec 是唯一执行真理源
2. 不得跳过 context
3. 不得跳过 grill（至少 3 个问题）
4. 不得跳过 commit
5. 冲突必须先分类再处理
6. 降级执行必须标注

冲突分类简化

v3.1 的四分类（实现偏差 / 规格遗漏 / 设计冲突 / 用户变更）在实际执行中边界模糊，agent 需要同时判断类型、选择处理方式、记录到 decisions.md、考虑是否回写 OpenSpec。判断链过长。

v4 简化为 2+1：

• OpenSpec 不准 → 修 OpenSpec
• 代码偏离 → 修代码
• 不确定 → 暂停等用户确认

质量约束可观测化

v3.1 的质量约束（如”evidence-driven 必须汇报””user-interview 必须等确认”）缺乏可观测产出，agent 可能形式化地填写而不真正验证。

v4 要求质量约束必须有可观测产出：写入文件 + checkpoint 检查。例如：

约束	v3.1（软）	v4（硬）
evidence-driven 汇报	“必须向用户汇报”	写入 decisions.md + checkpoint 列出汇报状态
user-interview 确认	“必须等待用户回答”	decisions.md 记录问题原文/用户原话/确认状态
cross-artifact 对齐	“必须显式检查”	checkpoint 包含 4 行对齐检查表

Micro 模式升级

v3.1 的 micro 只压缩产物（少写几个文件），没有压缩 gate 数量。v4 的 micro 合并 gate：

v3.1 micro：仍然走完整阶段，只是产物变少
v4 micro：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）

文件结构变化

v3.1：
.agents/skills/sm-flow/
├── SKILL.md                         # ~85行，入口协议 + 19条规则 + 阶段总览
└── references/
    ├── phase-contracts.md           # 阶段契约（Phase 0-4 编号）
    ├── operating-rules.md           # 运行规则
    ├── fallbacks.md                 # 降级协议
    ├── archive-rules.md             # 归档规则
    └── templates.md                 # 产物模板

v4：
.agents/skills/sm-flow/
├── SKILL.md                         # ~50行，入口协议 + 6条硬约束 + 4命令 + 9阶段总览
└── references/
    ├── phase-contracts.md           # 阶段契约（英文命名，grill 在 specify 前）
    ├── operating-rules.md           # 运行规则（启动识别 4 命令，micro 合并 gate）
    ├── fallbacks.md                 # 内置执行协议（冲突 2+1 分类）
    ├── archive-rules.md             # 归档规则（decisions.md 过程日志提取）
    └── templates.md                 # 产物模板（+cross-artifact 对齐检查表）

新增文档

• skill-workbench/docs/sm-flow/使用方式.md：面向用户的使用指南
• skill-workbench/docs/sm-flow/design-review.md：设计评审记录

v3.1 → v4 变更对照

维度	v3.1	v4
定位	“OpenSpec 的上下文增强层和归档闭环层”	“协议层 harness，编排 OpenSpec 完整生命周期”
阶段命名	Phase 0/0.5/1/1.5/2/2.5/2.9/3/4	clarify/context/propose/grill/specify/audit/commit/apply/archive
用户命令	无（用户需要知道阶段编号）	4 个命令（Actions, Not Phases）
propose 产出	完整 4 件套（proposal+design+specs+tasks）	只写轻量 proposal.md
grill 时机	specify 之后	specify 之前
devflow 写入策略	按阶段就近更新多个文件	只维护 decisions.md，archive 提取
核心规则数量	19 条三类分组	6 条硬约束
冲突分类	4 类（实现偏差/规格遗漏/设计冲突/用户变更）	2+1（OpenSpec 不准/代码偏离/不确定）
micro 模式	压缩产物	合并 gate
质量约束	文字描述	可观测产出（写入文件 + checkpoint）

v4.0 验证执行复盘（2026-05-25）

用 entry-expand-collapse 需求跑了一轮完整 sm-flow 流程，验证 v4.0 协议的可执行性。功能变更已回滚，仅保留验证发现。

暴露的问题

#	问题	具体表现	分析结论
1	propose 阶段越界	在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify	需求小时 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议
2	子 skill 伪调用	grill 阶段读了 grill-with-docs 的 SKILL.md 后自行执行，audit 阶段跳过了 zoom-out	Skill 工具调用和 Read 后执行效果等价，关键是"不能跳过"而非"用什么工具调用"。硬约束 #6 已覆盖，不需要改协议
3	spec 遗漏用户行为	spec 写的是"添加 .expanded class"（实现细节），没有写"展开后显示完整正文"（用户可观察行为）	导致第一版实现只切换了 CSS class，正文内容仍显示截断文本。spec 应描述用户可观察的结果而非实现方式

做对的部分

• clarify + context 合并执行正确（micro 模式）
• grill 的 evidence-driven / user-interview 分类和 one-at-a-time 节奏执行到位
• commit gate 的文件存在性检查生效
• apply 阶段的冲突分类（代码偏离）处理正确
• devflow 延迟写入（只维护 decisions.md）降低了维护成本

后续观察项

问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。