osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

redesign sm-flow v4.0 as protocol-layer harness

Browse Source 
- Reposition sm-flow as orchestration harness over OpenSpec lifecycle
- Adopt 4 user commands (Actions, Not Phases) instead of phase numbers
- Rename all stages to English verbs (clarify through archive)
- Reorder execution: grill before specify to eliminate rework loops
- Simplify core rules from 19 to 6 hard constraints in SKILL.md
- Simplify conflict classification from 4 categories to 2+1
- Switch devflow strategy to decisions.md-only process log during execution
- Upgrade micro mode from artifact compression to gate merging
- Add observable outputs for quality constraints
- Add design review doc and user guide
- Append v4.0 changelog to workflow.md
This commit is contained in:
zhuyongxin
2026-05-25 17:28:15 +08:00
parent 1f01e30c4e
commit 71e0b7f801
9 changed files with 1170 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/sm-flow/SKILL.md
+50 -50
View File
@@ -1,74 +1,75 @@
--- ---
name: sm-flow name: sm-flow
description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。 description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
--- ---
# SM Flow # SM Flow
SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。 SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
## 角色定位 sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。
你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。 ## 四层架构
## 真理源分层 ```
sm-flow → 编排层（harness）：阶段、门控、产物约束、人类对齐
OpenSpec → 执行引擎：propose/apply/archive 的能力提供方
devflow/ → 记忆层：为编排层提供上下文，接收执行结果的回填
code → 实现结果：apply 的产出
```
- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。 - OpenSpec 是唯一执行真理源：apply 阶段只能基于 OpenSpec 执行，不能绕过 OpenSpec 直接写代码。
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。 - devflow 是上下文真理源：术语、历史决策、验收记录来自 devflow，用于增强 OpenSpec，不替代 OpenSpec。
- 代码是实现结果：只能在执行真理源足够明确后修改。 - 如果 devflow 和 OpenSpec 冲突，先汇报冲突、让用户确认、修正 OpenSpec，再继续执行。
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。 - propose 阶段产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 apply 的执行许可。
- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。 - 只有通过 commit 检查后的 OpenSpec 才是 **Committed OpenSpec**；apply 只能执行 Committed OpenSpec。
- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
## 核心规则 ## 核心规则
- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。 以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。
- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。 1. **OpenSpec 是唯一执行真理源**。apply 只能基于 Committed OpenSpec 执行。Draft OpenSpec 是讨论对象，不是执行许可。
- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。 2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。 3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
- Phase 0、0.5、1、2、2.5、2.9 只有在显式 checkpoint 后才算完成；checkpoint 至少汇报当前阶段、能力来源、产出物、已满足退出条件和未解决阻塞。 4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。 5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。 6. **降级执行必须标注**。fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
- Phase 1.5 必须显式检查 `brief/prd -> proposal -> design -> specs -> tasks` 的 cross-artifact 对齐；发现缺口时先修 OpenSpec，再继续后续阶段。
- Phase 2 必须先建立 question pool，再按 one-at-a-time 规则消费 `user-interview` 问题；问题池至少覆盖术语、边界、验收，复杂变更还要补充模块、接口、权限、消费者、响应结构或生命周期维度。 每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。 ## 用户命令
- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。 | 命令 | 用户意图 | harness 内部行为 |
- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。 |---|---|---|
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。 | `/sm-flow` | 完整流程 | clarify → context → propose → grill → specify → audit → commit → apply → archive |
- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。 | `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。 | `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。 | `/sm-flow archive` | 收尾 | 回填 devflow + 归档确认 |
- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
- `micro` 只能压缩产物重量，不能跳过关键 gate；Phase 0.5 最小上下文收集、Phase 2 最小澄清、Phase 2.9 commit gate 和 Phase 4 轻量回填必须保留。 用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
- devflow 记录必须按阶段就近更新；Phase 4 主要做 consolidation，而不是第一次补写 `brief.md`、`evidence.md`、`decisions.md` 或 `acceptance.md`。
## 首次加载 ## 首次加载
执行前只读取当前任务需要的 reference 文件： 执行前只读取当前任务需要的 reference 文件：
- 需要逐阶段执行时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。 - 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。 - archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。 - 子 skill 无法直接调用时，读取 `references/fallbacks.md`。
## 启动检查 ## 内部阶段
按 `references/operating-rules.md` 执行启动检查、项目 slug 规则和 devflow 产物分层。 9 个内部阶段，按执行顺序：
## 阶段总览 1. clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。
2. context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。
1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。 3. propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。
2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。 4. grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。 5. specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。
4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。 6. audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。
5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。 7. commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。 8. apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。
7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。 9. archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。
8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。
每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
@@ -81,4 +82,3 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
## 完成标准 ## 完成标准
流程完成标准见 `references/operating-rules.md`。 流程完成标准见 `references/operating-rules.md`。
.agents/skills/sm-flow/references/archive-rules.md
+15 -16
View File
@@ -1,6 +1,6 @@
# 归档规则 # 归档规则
Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。 archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。
## 目录规则 ## 目录规则
@@ -10,12 +10,12 @@ Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为
devflow/projects/YYYY-MM-DD-{slug}/ devflow/projects/YYYY-MM-DD-{slug}/
``` ```
默认创建以下必要文件： archive 阶段创建以下文件：
- `brief.md` - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md` - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
- `decisions.md` - `decisions.md`：保持为最终版，整理格式。
- `acceptance.md` - `acceptance.md`：从实现结果和验证结果提取。
同时维护仓库级索引： 同时维护仓库级索引：
@@ -44,11 +44,12 @@ devflow/projects/YYYY-MM-DD-{slug}/
| 来源 | 提取内容 | 写入位置 | | 来源 | 提取内容 | 写入位置 |
| --- | --- | --- | | --- | --- | --- |
| `decisions.md`（过程日志） | question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍 | `decisions.md`（整理格式为最终版） |
| `decisions.md`（过程日志） | evidence-driven 结论、代码/文档证据 | `evidence.md` |
| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` | | `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` |
| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` | | `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` |
| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 | | `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 |
| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` | | `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` |
| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` |
| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` | | 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` |
| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` | | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` | | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
@@ -57,7 +58,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
## 索引维护规则 ## 索引维护规则
`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。 `devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。
最小字段： 最小字段：
@@ -67,9 +68,9 @@ devflow/projects/YYYY-MM-DD-{slug}/
规则： 规则：
- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。 - 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
- Phase 4 新建或更新项目档案时，必须新增或更新对应行。 - archive 阶段新建或更新项目档案时，必须新增或更新对应行。
- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。 - 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。 - 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。 - 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
## 验收记录规则 ## 验收记录规则
@@ -85,7 +86,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
- 如果验证通过，记录命令/步骤和覆盖范围。 - 如果验证通过，记录命令/步骤和覆盖范围。
- 如果验证失败，记录失败摘要和是否阻塞验收。 - 如果验证失败，记录失败摘要和是否阻塞验收。
- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。 - 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
## ADR 规则 ## ADR 规则
@@ -111,19 +112,17 @@ devflow/compound/YYYY-MM-DD-decision-{slug}.md
OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息： OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息：
- Phase 4 可以建议 archive，但必须先询问用户。 - archive 阶段可以建议 archive，但必须先询问用户。
- 在用户确认前，不要执行 archive。 - 在用户确认前，不要执行 archive。
- 如果用户暂不归档，在 acceptance 中记录原因或状态。 - 如果用户暂不归档，在 acceptance 中记录原因或状态。
- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。 - 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。
## 归档交接 ## 归档交接
Phase 4 结束时告诉用户： archive 阶段结束时告诉用户：
- 创建或更新了哪些档案文件。 - 创建或更新了哪些档案文件。
- `devflow/index.md` 是否已更新。 - `devflow/index.md` 是否已更新。
- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
- 还剩哪些风险或后续事项。 - 还剩哪些风险或后续事项。
- 明确询问：是否现在 archive OpenSpec change？ - 明确询问：是否现在 archive OpenSpec change？
.agents/skills/sm-flow/references/fallbacks.md
+49 -46
View File
@@ -1,39 +1,39 @@
# Fallback 协议 # 降级协议
当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。 当子 skill 无法直接调用时，sm-flow 使用内置执行协议接管。这不是能力缺失，而是 harness 的正常能力切换。
## Fallback 记录要求 使用任何降级前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称。产物中也必须记录"本阶段为降级执行"。
任何 fallback 都必须同时满足以下记录要求： ## 降级记录要求
任何降级都必须同时满足以下记录要求：
1. 在对用户的阶段汇报里声明： 1. 在对用户的阶段汇报里声明：
- 目标 capability - 目标 capability
- 不可用原因 - 不可用原因
- 使用的 fallback 协议名 - 使用的降级协议名
- 本次降级风险 2. 在 `decisions.md` 中留下同样的降级记录。
2. 在 `decisions.md`、`evidence.md` 或 `acceptance.md` 中留下同样的降级记录。 3. 如果当前阶段需要 checkpoint，则降级声明是 checkpoint 完成条件的一部分。
3. 如果当前阶段需要 checkpoint，则 fallback 声明是 checkpoint 完成条件的一部分。
4. 如果没有完成这些声明和记录，该阶段不得视为已完成。 4. 如果没有完成这些声明和记录，该阶段不得视为已完成。
除非某个 fallback 额外说明，否则下面各节默认继承这组通用记录要求，不再重复要求“记录本阶段 fallback 声明”。 除非某个降级额外说明，否则下面各节默认继承这组通用记录要求，不再重复。
## OpenSpec 提案 fallback ## OpenSpec 提案降级
1. 创建或识别 `openspec/changes/{slug}/`。 specify 阶段调用 `openspec-propose` 不可用时使用。propose 阶段使用 sm-flow 内置协议（轻量 proposal），不需要降级。
2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
3. 写入 `proposal.md`，包含： 1. 确认 `openspec/changes/{slug}/proposal.md` 已存在（propose 阶段产出）。
- 问题 2. 读取 grill 阶段的 decisions.md 记录，获取已确认的需求和决策。
- 建议方案 3. 写入 `design.md`，包含：
- 范围 - 关键技术决策
- 非目标
- 来自 devflow 的上下文约束 - 来自 devflow 的上下文约束
- 风险 - 架构约束和风险
4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。 4. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。 5. 只为外部可见行为或发生变化的需求编写 specs。
6. 只为外部可见行为或发生变化的需求编写 specs。 6. 确保 design/specs/tasks 与 proposal 对齐。
7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。 7. 如果存在高风险假设，在 specify checkpoint 中向用户汇报。
## OpenSpec 修正 fallback ## OpenSpec 修正降级
当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时： 当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
@@ -42,33 +42,32 @@
3. 向用户汇报冲突和推荐修正。 3. 向用户汇报冲突和推荐修正。
4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。 4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
5. 再同步更新 devflow 文档；不要只改 devflow。 5. 再同步更新 devflow 文档；不要只改 devflow。
6. 额外记录冲突修正状态。 6. 额外记录冲突修正状态到 decisions.md。
## OpenSpec 执行 fallback ## OpenSpec 执行降级
仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。 apply 阶段调用 `openspec-apply-change` 不可用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。 1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。 2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。 3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。 4. 确认 commit 后已经获得用户明确的 apply 授权；单个 grill 决策确认不能替代 apply 授权。
5. 修改前先检查现有代码。 5. 修改前先检查现有代码。
6. 一次实现一个 OpenSpec task 的纵向切片。 6. 一次实现一个 OpenSpec task 的纵向切片。
7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类： 7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，做三类判断：
- 实现偏差：OpenSpec 正确，代码偏离；修代码。 - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停执行，修正 OpenSpec 并重新提交后继续。
- 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。 - 代码偏离（实现没按 OpenSpec 做）→ 修代码。
- 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。 - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
- 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。 8. 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
9. 用最窄但有效的命令验证每个切片。 9. 用最窄但有效的命令验证每个切片。
10. 只有验证通过或明确记录原因后，才更新 task 状态。 10. 只有验证通过或明确记录原因后，才更新 task 状态。
11. 如果失败原因不确定，停止并进入 diagnose。 11. 如果失败原因不确定，停止并进入 diagnose。
12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。 12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
13. 额外记录任务推进状态和验证状态。 13. 额外记录任务推进状态和验证状态。
## PRD fallback ## PRD 降级
优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。 specify 阶段调用 `to-prd` 不可用时使用。优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
规则： 规则：
@@ -77,16 +76,19 @@
- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。 - 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
- 额外记录是否创建了独立 `prd.md`。 - 额外记录是否创建了独立 `prd.md`。
## 文档化追问 fallback ## 文档化追问降级
grill 阶段调用 `grill-with-docs` 不可用时使用。
1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。 1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。 2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。 3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
4. 对 user-interview 问题，一次只问一个并等待用户确认。 4. 对 user-interview 问题，一次只问一个并等待用户确认。
5. 术语确认后立即更新词汇表。 5. evidence-driven 和 user-interview 交替推进，避免攒到一起汇报。
6. 影响实现的澄清必须回写 OpenSpec。 6. 术语确认后立即更新词汇表。
7. 只为难以逆转的真实权衡创建 ADR。 7. 影响实现的澄清必须回写 proposal.md。
8. 额外记录 question pool 和已消费问题。 8. 只为难以逆转的真实权衡创建 ADR。
9. 额外记录 question pool 和已消费问题。
快速模式的最小问题： 快速模式的最小问题：
@@ -94,9 +96,9 @@
- 边界：哪些内容明确不在范围内？是否需要用户确认？ - 边界：哪些内容明确不在范围内？是否需要用户确认？
- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？ - 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
## 架构审计 fallback ## 架构审计降级
产出一份短架构审计： audit 阶段调用 `zoom-out` 不可用时使用。产出一份短架构审计：
1. 画出输入 → 处理 → 输出。 1. 画出输入 → 处理 → 输出。
2. 列出相关模块和调用方。 2. 列出相关模块和调用方。
@@ -106,7 +108,9 @@
6. 如果影响实现，回写 OpenSpec design/tasks。 6. 如果影响实现，回写 OpenSpec design/tasks。
7. 额外记录审计结论回写状态。 7. 额外记录审计结论回写状态。
## Diagnose fallback ## Diagnose 降级
apply 阶段调用 `diagnose` 不可用时使用。
1. 复现问题，或捕获准确失败信息。 1. 复现问题，或捕获准确失败信息。
2. 最小化失败案例。 2. 最小化失败案例。
@@ -118,9 +122,9 @@
8. 运行回归验证。 8. 运行回归验证。
9. 额外记录根因分类和回归结果。 9. 额外记录根因分类和回归结果。
## TDD fallback ## TDD 降级
使用纵向切片，不要水平批量写测试： apply 阶段调用 `tdd` 不可用时使用。使用纵向切片，不要水平批量写测试：
1. 从 OpenSpec specs 中选择一个外部可见行为。 1. 从 OpenSpec specs 中选择一个外部可见行为。
2. 写一个失败测试。 2. 写一个失败测试。
@@ -128,4 +132,3 @@
4. 只在测试通过时重构。 4. 只在测试通过时重构。
5. 对下一个 OpenSpec 行为重复以上步骤。 5. 对下一个 OpenSpec 行为重复以上步骤。
6. 额外记录当前行为切片的测试状态。 6. 额外记录当前行为切片的测试状态。
.agents/skills/sm-flow/references/operating-rules.md
+67 -49
View File
@@ -4,91 +4,109 @@
## 接口影响分级 ## 接口影响分级
接口影响分级决定“记录在哪里”以及“是否需要独立接口文档”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义，或内部决策逻辑改变可观察行为的变更，都必须先做分级。 接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。
| 级别 | 判断条件 | 产物要求 | | 级别 | 判断条件 | 产物要求 |
| --- | --- | --- | | --- | --- | --- |
| L1 内部实现 | 不改变调用方可观察行为 | 在 OpenSpec tasks 或 acceptance 记录验证 | | L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
| L2 内部接口 | 内部 DTO/service/event/RPC/decision-logic 变化，且所有消费者仍在同一实现边界内 | 在 OpenSpec design/specs/tasks 或 devflow evidence/decisions 中内联记录影响 | | L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
| L3 协作接口 | 影响其他模块/服务、前端、外部系统、跨团队消费者、数据库契约、事件、回调或 SDK | 产出独立接口文档或等价独立章节 | | L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
| L4 破坏性接口 | 破坏兼容、改变语义/错误码/状态机、可能让旧调用方失败，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR | | L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
判断启发： 判断策略：
- 如果变更只是把接口恢复到原 OpenSpec 或既有文档承诺，通常是 L1 或 L2。 - 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
- 如果决策逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。 - 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
- 如果旧调用方不改代码就可能失败，或会观察到缺失/额外数据、不同状态或不同错误码，按 L4 处理。 - 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
- 如果消费者边界或兼容性不明确，默认提高一级，并转成 `user-interview` 问题。 - 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
## 启动检查 ## 启动检查
1. 判断启动模式： 1. 识别用户命令意图：
- `/sm-flow`（无参数）：完整流程，从 clarify 开始。
- `/sm-flow apply [change]`：只执行，检查 commit gate → apply。
- `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。
- `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。
- 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
2. 判断启动模式：
- 完整模式：用户提供粗略想法或初始 PRD。 - 完整模式：用户提供粗略想法或初始 PRD。
- Research 模式：用户已有 research，需要生成或修正 OpenSpec。 - Research 模式：用户已有 research，需要转成或修正 OpenSpec。
- PRD 文件模式：用户提供已有 PRD 路径。 - PRD 文件模式：用户提供已有 PRD 路径。
- 指定阶段模式：用户希望从某个 Phase 恢复。 - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
- 快速模式：小改动；Phase 2 和 Phase 4 可以轻量化，但不能跳过。 - 快速模式：小改动，合并 gate（见下文）。
2. 如果缺少 `devflow/`，初始化： 3. 如果缺少 `devflow/`，初始化：
- `devflow/projects/` - `devflow/projects/`
- `devflow/glossary/CONTEXT.md` - `devflow/glossary/CONTEXT.md`
- `devflow/compound/` - `devflow/compound/`
- `devflow/reference/` - `devflow/reference/`
3. 如果根目录旧 `CONTEXT.md` 存在，而 `devflow/glossary/CONTEXT.md` 缺失或为空，询问是迁移还是合并。 4. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
4. 检查 OpenSpec 和辅助能力是否可用： 5. 检查 OpenSpec 和子 skill 是否可用：
- OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change` - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
- 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out` - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
5. 如果 OpenSpec 能力不可用，不要静默绕过；要走 fallback 协议，并在 Phase 3 前披露降级风险。 6. 如果 OpenSpec 不可用，不要直接绕过；使用内置执行协议（见 `references/fallbacks.md`），并在 apply 前向用户说明。
## 项目标识规则 ## 项目标识规则
- 整个流程使用同一个 slug。 - 整个流程使用同一个 slug。
- 优先使用 OpenSpec change name。 - 优先使用 OpenSpec change name。
- 如果还没有，则从功能标题生成 kebab-case slug。 - 如果还没有，则从功能标题生成 kebab-case slug。
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/` - 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。 - 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
## Devflow 产物分层 ## Devflow 产物分层
Devflow 是辅助 OpenSpec 的人类可读档案层，不应复制 OpenSpec 的执行产物。 Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。
必需产物： **过程日志**（clarify → apply 期间维护）：
- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change - `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论、汇报状态
- `decisions.md`：user-interview 条目、确认结果、取舍、风险接受、OpenSpec 回写记录
- `acceptance.md`：结果、验证、未验证项、归档状态、后续事项
按需产物： **最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：
- `prd.md`：复杂需求、用户明确要求，或需要对外协作 - `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
- `research.md`：真实调研、代码考古、竞品/API 对比或复杂方案比较 - `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态。
- `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
- `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec
- `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用
- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用
分档： **按需产物**（archive 阶段按需创建）：
- `micro`：使用 `brief.md`、`decisions.md`、`acceptance.md`；证据很少时并入 `brief.md` - `prd.md`：需求复杂、用户明确要求、或需要对外协作。
- `standard`：使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` - `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较。
- `complex`：`standard` 基础上按需增加 PRD/research/design/tasks/alignment - `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要。
- `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec。
- `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。
**规模分档**：
- `micro`：小且低风险，gate 合并（见快速模式），最终档案同 standard。
- `standard`：默认模式。
- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。
## 快速模式 ## 快速模式
快速模式只适用于小而低风险的变更。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留： 快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物：
- 最小 Phase 0.5 上下文收集：至少检查 glossary 和相关 ADR ```
- 最小 Phase 2 澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报 standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit
- Phase 2.9 commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行 micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查）
- Phase 3 仍由 OpenSpec tasks/specs 驱动执行 ```
- 轻量 Phase 4 回填：记录验收结果、OpenSpec 链接和归档状态
micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + commit gate）。
无论什么模式，以下内容必须保留：
- context 最小上下文收集：至少检查 glossary 和相关 ADR。
- grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。
- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
- apply 仍由 OpenSpec tasks/specs 驱动执行。
- archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
## 完成标准 ## 完成标准
只有同时满足以下条件，流程才算完成： 只有同时满足以下条件，流程才算完成：
- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态 - OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。
- 实现或规划工作已完成，且执行依据来自 OpenSpec - 实现或规划工作已完成，且执行依据来自 OpenSpec。
- 已运行验证，或已记录未运行验证的原因 - 已运行验证，或已记录未运行验证的原因。
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含所选分档要求的必要产物 - `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
.agents/skills/sm-flow/references/phase-contracts.md
+120 -114
View File
@@ -1,8 +1,10 @@
# 阶段契约 # 阶段契约
本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。 本文件是 SM Flow 的逐阶段执行准则。核心原则：**sm-flow 编排 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
## Phase 0 — 入口澄清 执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。
## clarify — 入口澄清
**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。 **进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
@@ -24,9 +26,9 @@
- 初步 slug。 - 初步 slug。
- devflow 规模分档：`micro` / `standard` / `complex`。 - devflow 规模分档：`micro` / `standard` / `complex`。
## Phase 0.5 — Devflow 上下文收集 ## context — 上下文收集
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。 **进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。
**动作**： **动作**：
- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。 - 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
@@ -38,104 +40,58 @@
- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。 - 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。
**退出条件**： **退出条件**：
- 已形成“OpenSpec 输入上下文摘要”。 - 已形成"OpenSpec 输入上下文摘要"。
- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。 - 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
- 已列出相关 ADR 和不能违反的历史决策。 - 已列出相关 ADR 和不能违反的历史决策。
- 已列出需要写入或修正 OpenSpec 的上下文点。 - 已列出需要写入或修正 OpenSpec 的上下文点。
**输出**： **输出**：
- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。 - 上下文摘要，写入 `decisions.md`（过程日志）。会影响实现的上下文必须标记为"需进入 OpenSpec"。
## Phase 1 — OpenSpec propose ## propose — 轻量 propose
**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。 **进入条件**：clarify + context 已经足够生成轻量 proposal。
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。 **执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。
**动作**： **动作**：
- 优先调用 `openspec-propose`。 - 创建或识别 `openspec/changes/{slug}/`。
- 如果不可用，执行 `references/fallbacks.md#openspec-提案-fallback`，但仍必须产出 OpenSpec 文件。 - 写入 `proposal.md`，包含：问题、建议方案、范围、非目标、来自 devflow 的上下文约束、风险。
- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec： - **不生成 design.md、specs/、tasks.md**——这些留待 grill 澄清需求后在 specify 阶段补全。
- proposal 写清为什么做、做什么、范围和非目标。 - 用 context 阶段的 devflow 上下文增强 proposal。
- design 写入上下文约束、历史 ADR、关键技术决策。 - 在承诺方案方向前，先检查相关仓库代码。
- specs 写成可验收的外部行为。
- tasks 写成可执行的纵向切片。
- 在承诺设计细节前，先检查相关仓库代码。
**退出条件**： **退出条件**：
- `openspec/changes/<slug>/proposal.md` 存在。 - `openspec/changes/{slug}/proposal.md` 存在。
- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。 - 关键假设已显式记录。
- 关键假设已显式记录在 OpenSpec 或 research 中。
**输出**： **输出**：
- Draft OpenSpec proposal、design、specs 和 task list。 - Draft OpenSpec proposal.md（轻量版）。
**Human checkpoint**： **Human checkpoint**：
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。 - 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。 - 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。
## Phase 1.5 — PRD / OpenSpec 对齐 ## grill — 人类对齐澄清
**进入条件**：Phase 1 已有 OpenSpec 产物。 **进入条件**：propose 已有轻量 proposal.md。
**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。 **显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；降级必须标记为"文档化追问降级"。
**动作**：
- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
- 显式检查 `brief/prd -> proposal -> design -> specs -> tasks` 的 cross-artifact 对齐关系：
- `brief/prd` 中的目标、范围、非目标和验收预期是否进入 `proposal`。
- `proposal` 中的范围、约束和关键承诺是否进入 `design`。
- `design` 中影响实现的约束、接口影响和架构结论是否进入 `specs` 或 `tasks`。
- `specs` 中的可观察行为是否被 `tasks` 覆盖为可执行切片。
- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
- OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
- OpenSpec 是否使用 glossary 中的正确术语。
- OpenSpec 是否遵守相关 ADR。
- specs 是否能表达可观察行为。
- tasks 是否能驱动实现，而不是泛泛描述。
- 检查是否涉及接口影响：
- 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
- 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
- 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
- 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
- 如果某个行为、术语、字段、约束或实现切片只出现在上游产物，必须显式标记 gap，并在进入下一阶段前修复 OpenSpec。
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
**退出条件**：
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
- `brief/prd -> proposal -> design -> specs -> tasks` 的下游链路没有未处理 gap。
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
- 所有已知冲突已修正或等待用户决策。
**输出**：
- `brief.md`，以及按需创建的 `prd.md`。
- OpenSpec 对齐检查记录。
- 必要的 OpenSpec 修正。
## Phase 2 — Human-in-the-loop 澄清
**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
**动作**： **动作**：
- 优先使用 `grill-with-docs`。 - 优先使用 `grill-with-docs`。
- 进入 Phase 2 时先建立一个 question pool，并记录到 `decisions.md` 或 `evidence.md`： - 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
- 默认至少覆盖术语、边界、验收三个维度。 - 默认至少覆盖术语、边界、验收三个维度。
- 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。 - 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
- 先声明本阶段采用的澄清模式，并逐项标记： - 逐项标记每个问题的模式：
- `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。 - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。 - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
- 至少覆盖三个维度：术语、边界、验收。 - evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。
- 从问题池中选择下一个未解决问题推进；可以并行整理 evidence-driven 证据，但 `user-interview` 仍然必须 one-at-a-time。
- 一次只问一个 `user-interview` 问题。 - 一次只问一个 `user-interview` 问题。
- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。 - 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。
- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。 - 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。
- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。 - 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。 - 如果澄清结果影响实现，必须回写 proposal.md。
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
@@ -146,18 +102,63 @@
- 所有 user-interview 决策已获得用户确认。 - 所有 user-interview 决策已获得用户确认。
- 没有未解决或代理代确认的 user-interview 问题。 - 没有未解决或代理代确认的 user-interview 问题。
- 没有未判级或未确认的接口影响问题。 - 没有未判级或未确认的接口影响问题。
- 影响实现的结论已回写 OpenSpec。 - 影响实现的结论已回写 proposal.md。
- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
**输出**： **输出**：
- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。 - 更新后的 proposal.md。
- 更新后的 OpenSpec。 - 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。
- 更新后的词汇表和 ADR。 - 更新后的词汇表和 ADR。
## Phase 2.5 — 架构审计 **Human checkpoint**：
- 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
- 询问是否继续进入 specify 细化阶段。
**进入条件**：Phase 2 已解决主要产品、领域和验收问题。 ## specify — 细化 + 对齐
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。 **进入条件**：grill 已退出，需求已通过澄清稳定下来。
**显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。
**动作**：
- 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md：
- 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。
- 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。
- 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。
- 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。
- **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表：
- `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。
- `proposal` 中的范围、约束和关键承诺 → `design` 是否覆盖。
- `design` 中影响实现的约束、接口影响和架构结论 → `specs` 或 `tasks` 是否覆盖。
- `specs` 中的可观察行为 → `tasks` 是否覆盖为可执行切片。
- 每项标记：已对齐 / 存在 gap。
- 检查是否涉及接口影响：
- 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
- 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
- 接口内部判断逻辑是否改变调用方可观察行为。
- 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 `user-interview` 问题。
- 如果存在 gap，在进入下一阶段前修复 OpenSpec。
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
**退出条件**：
- `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
- cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
- 所有已知冲突已修正或等待用户决策。
**输出**：
- 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。
- `brief.md`，以及按需创建的 `prd.md`。
- cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
- 必要的 OpenSpec 修正。
## audit — 架构审计
**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；降级必须标记为"架构审计降级"。
**动作**： **动作**：
- 画出输入 → 处理 → 输出的模块链路。 - 画出输入 → 处理 → 输出的模块链路。
@@ -165,25 +166,26 @@
- 检查是否与既有架构、ADR、OpenSpec design 冲突。 - 检查是否与既有架构、ADR、OpenSpec design 冲突。
- 用不超过五句话写出架构风险评估。 - 用不超过五句话写出架构风险评估。
- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。 - 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
- 审计结论写入 `decisions.md`。
**退出条件**： **退出条件**：
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。 - 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。 - OpenSpec design/tasks 已反映会影响实现的架构审计结论。
**输出**： **输出**：
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。 - 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
- 必要的 OpenSpec design/tasks 修正。 - 必要的 OpenSpec design/tasks 修正。
**Human checkpoint**： **Human checkpoint**：
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。 - 询问是否进入 commit。
## Phase 2.9 — Commit OpenSpec ## commit — Commit OpenSpec
**进入条件**： **进入条件**：
- Phase 2 已解决术语、边界、验收三个维度的高价值问题。 - grill 已解决术语、边界、验收三个维度的高价值问题。
- 所有 `user-interview` 问题都已获得用户显式确认。 - 所有 `user-interview` 问题都已获得用户显式确认。
- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。 - audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
**动作**： **动作**：
@@ -191,48 +193,47 @@
- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。 - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
- 复核 `brief/prd -> proposal -> design -> specs -> tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。 - 复核 cross-artifact 对齐：`brief/prd → proposal → design → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。
- 检查 `evidence.md` 和 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。 - 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。
- 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。 - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。
- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。 - 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。 - 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。 - 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。
**退出条件**： **退出条件**：
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。 - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。 - apply 所需的 proposal、design、specs 和 tasks 均存在且一致。
- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。 - 所有 preflight 风险已消除或明确记录为已接受。
**输出**： **输出**：
- Committed OpenSpec 状态说明。 - Committed OpenSpec 状态说明。
- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。 - preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。
**Human checkpoint**： **Human checkpoint**：
- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。 - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。 - 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。 - 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
## Phase 3 — OpenSpec apply ## apply — OpenSpec 执行
**进入条件**： **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。 - `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。
- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。 - commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
- devflow 与 OpenSpec 没有未解决冲突。 - devflow 与 OpenSpec 没有未解决冲突。
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默降级。
**动作**： **动作**：
- 优先调用 `openspec-apply-change`。 - 优先调用 `openspec-apply-change`。
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
- 按 OpenSpec tasks 的纵向切片实现。 - 按 OpenSpec tasks 的纵向切片实现。
- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 Phase 3 不算真正开始。 - 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续： - 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
- 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。 - OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
- 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。 - 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
- 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。 - 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
- 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。 - 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
- 当用户要求、行为复杂或回归风险高时使用 TDD。 - 当用户要求、行为复杂或回归风险高时使用 TDD。
- 当测试失败、行为意外或原因不确定时使用 diagnose。 - 当测试失败、行为意外或原因不确定时使用 diagnose。
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
@@ -247,27 +248,32 @@
**输出**： **输出**：
- 代码变更、必要测试和实现说明。 - 代码变更、必要测试和实现说明。
- 更新后的 OpenSpec task 状态。 - 更新后的 OpenSpec task 状态。
- 冲突记录写入 `decisions.md`。
## Phase 4 — 回填 Devflow ## archive — 回填 + 归档
**进入条件**：实现或规划工作已经达到可交接状态。 **进入条件**：实现或规划工作已经达到可交接状态。
**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。 **显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动降级。
**动作**： **动作**：
- 遵循 `references/archive-rules.md`。 - 遵循 `references/archive-rules.md`。
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。 - 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
- 把 Phase 0 到 Phase 3 已经形成的过程内记录整理为最终档案；不要把 Phase 4 当作第一次补写这些记录。 - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。
- `decisions.md`：保持为最终版，整理格式。
- `acceptance.md`：从实现结果和验证结果提取。
- 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
- 如果本次流程产生可复用经验，写入 compound knowledge。 - 如果本次流程产生可复用经验，写入 compound knowledge。
- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。 - 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。
**退出条件**： **退出条件**：
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。 - `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。
- `devflow/index.md` 已包含或更新本项目条目。 - `devflow/index.md` 已包含或更新本项目条目。
- 用户已被询问是否 archive OpenSpec change。 - 用户已被询问是否 archive OpenSpec change。
**输出**： **输出**：
- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。 - 完整 devflow 档案。
- 归档交接清单：创建或更新了哪些文件、验证分类、剩余风险、是否 archive。
.agents/skills/sm-flow/references/templates.md
+37 -3
View File
@@ -51,11 +51,25 @@
```markdown ```markdown
# {标题} Decisions # {标题} Decisions
## Question Pool
| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
| Q2 | 边界 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
| Q3 | 验收 | {question} | evidence-driven / user-interview | 已解决 / 未解决 |
## Evidence-driven
| 结论 | 证据来源 | 是否已汇报用户 |
|---|---|---|
| {conclusion} | {file/doc/test/ADR} | 已汇报 / 待汇报 |
## User-interview ## User-interview
| 问题 | 用户回答 | 决策 | OpenSpec 回写 | | 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
| --- | --- | --- | --- | |---|---|---|---|
| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 | | {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 |
## 关键取舍 ## 关键取舍
@@ -329,6 +343,26 @@
- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用} - OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
``` ```
## Cross-Artifact 对齐检查表模板
specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。
```markdown
## Cross-Artifact 对齐检查
| 上游 → 下游 | 检查内容 | 状态 |
|---|---|---|
| brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap |
| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
| specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |
### Gap 详情（如有）
- gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
- 修复：{如何修正 OpenSpec}
```
## 复合知识模板 ## 复合知识模板
```markdown ```markdown
skill-workbench/docs/sm-flow/design-review.md
+432
View File
@@ -0,0 +1,432 @@
# SM-Flow 设计评审与修改方向
**日期**：2026-05-25
**目的**：基于完整代码审阅和讨论，落地当前设计的评估结论和下一步修改方向。
---
## 核心定位：sm-flow 是一个协议层 Harness
### 本质认知
sm-flow 不是一个"更好的 skill"，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。
### Harness 能力对照
| Harness 能力 | sm-flow 的实现 |
|---|---|
| 流程编排 | Phase 0 → 0.5 → 1 → 1.5 → 2 → 2.5 → 2.9 → 3 → 4 |
| 门控 | Draft/Committed gate、checkpoint、退出条件 |
| 上下文管理 | Phase 0.5 harvest、首次加载策略、按需读取 |
| 权限控制 | human-in-the-loop、user-interview 必须等确认 |
| 工具调度 | 每个 Phase 指定子 skill、fallback 链 |
| 护栏 | micro≠skip、不得猜测式修 bug、冲突必须先分类 |
### 四层架构
```
Claude Code Harness → 代码层：工具权限、hooks、context window（agent 绕不过）
sm-flow Harness → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
OpenSpec → 执行引擎：propose/apply/archive 的具体操作
Sub-skills → 能力层：grill、zoom-out、diagnose、tdd
```
sm-flow 位于 Claude Code harness 和 OpenSpec 之间。Claude Code harness 控制 agent **能做什么**（工具、权限、context），sm-flow harness 控制 agent **怎么做**（顺序、条件、标准）。OpenSpec 是被调度的执行引擎，子 skill 是被调用的能力单元。
### 与代码层 Harness 的关键区别
- 代码层 harness（Claude Code）是**代码实现**的，agent 物理上绕不过
- 协议层 harness（sm-flow）是**提示词实现**的，agent 理论上可以违反
因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力。这些机制的本质就是**弥补提示词 harness 缺乏物理强制力的弱点**。
### 这个定位对后续设计的指导意义
以 harness 思想为核心，所有后续修改都应该回答同一个问题：
> **这条规则/机制是在约束 agent 的什么行为？约束力够不够？会不会过度限制 agent 的判断力？**
具体推论：
1. **约束粒度**：当前以阶段级约束为主，关键动作（冲突分类、one-at-a-time）单独加约束。粒度选择合理，后续新增约束应遵循同一粒度策略。
2. **可组合性**：harness 的子模块能否独立加载？当前 Phase 2 的 grill、Phase 2.5 的 zoom-out 已经有独立性，但缺少独立的进入协议。
3. **可观测性**：checkpoint 机制是 harness 的 telemetry。每个 checkpoint 汇报当前阶段、能力来源、产出物、退出条件、blocker——这相当于告诉外部"agent 现在在做什么、为什么卡住了"。
4. **设计自由度**：作为 harness，sm-flow 天然有权约束被编排对象（OpenSpec）的使用方式——task 粒度检查、specs 可验收性评分、apply 进度汇报格式都是合理的编排行为。
---
## 当前状态评估
### 架构概览
```
SKILL.md（~85行） ← 入口协议：定位、真理源、~22条硬规则、阶段总览
references/
├── phase-contracts.md（~274行） ← 逐阶段契约：进入/动作/输出/退出/checkpoint
├── operating-rules.md（~95行） ← 运行规则：接口分级、启动检查、产物分层、快速模式、完成标准
├── fallbacks.md（~132行） ← 降级协议：通用记录要求 + 8 个 fallback
├── archive-rules.md（~130行） ← 归档规则：提取映射、索引维护、验收分类、ADR 条件
└── templates.md（~352行） ← 产物模板：brief/evidence/decisions/acceptance/PRD/ADR/...
```
总计约 1070 行。首次加载只读 SKILL.md + phase-contracts.md（~360 行），其余按需补读。
### 演进脉络
```
v1 dev-flow：基础流程骨架（Phase 1-4）
↓ 痛点：产物散落 5 个目录，archive 后上下文全丢
v2 增加 devflow/ 聚合层（人类档案层 vs 机器工作区分离）
↓ 痛点：devflow 产物越来越完整，agent 直接拿 devflow 写代码，OpenSpec 被架空
v3 真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
↓ 痛点：devflow 和 OpenSpec 产物大量重叠；grill 后返工 proposal/design
v3.1 Draft/Committed 分离 + 可执行 gate + 产物瘦身 + 接口影响分级
↓ 痛点：规则太多堆在 SKILL.md，agent 加载后上下文被冲走
v3.1+ 协议瘦身：SKILL.md 减负 → operating-rules.md + fallback 去重 + 引用自洽
```
每一版都从真实执行失败中提炼，不是理论推演。
### 已经做得好的
**1. 协议自洽性**
SKILL.md → phase-contracts → operating-rules → fallbacks → archive-rules → templates 之间的引用关系完整。cross-reference 断链问题（fallback 锚点中文名、接口分级引用）已修掉。
**2. 失败驱动迭代**
retrospective.md 逐阶段分析"应该做什么 / 实际做了什么 / 没做到什么"，使用问题.md 收集了 7 个真实痛点。当前版本的规则几乎都能追溯到一次真实失败。
**3. 对 agent 行为模式的准确预判**
规则大量出现"不得把单个决策确认推断为执行授权""micro 不等于跳过""evidence-driven 不是自动通过"——这些是 agent 的真实偷懒模式。规则写的不是"应该做什么"，而是"agent 会怎么绕过，以及如何堵死"。
**4. 7 个核心设计决策逻辑自洽**
| # | 决策 | 为什么 |
|---|---|---|
| 1 | OpenSpec 是唯一执行真理源 | 防止 devflow 和 OpenSpec 成为并列执行依据 |
| 2 | Draft / Committed 分离 | Phase 1 产出是讨论对象，Phase 2.9 是显式 gate |
| 3 | devflow 按阶段就近写入，Phase 4 做 consolidation | 防止 Phase 4 变成"第一次补写" |
| 4 | Question Pool + one-at-a-time | 先列全风险面，再逐项消费 |
| 5 | Cross-artifact 对齐链 | brief→proposal→design→specs→tasks 每层接住上游 |
| 6 | 能力绑定而非路径绑定 | 子 skill 可跨平台迁移 |
| 7 | Micro ≠ Skip | 产物可合并，gate 不能省略 |
---
## 已确认的修改方向
### 修改 1：定位修正——明确"协议层 Harness"身份 ✅ 已实施
**问题**：当前 SKILL.md 说"不替代 OpenSpec，而是增强"，但实际上 sm-flow 是一个编排 OpenSpec 生命周期的协议层 harness。OpenSpec 是被调度的执行引擎，sm-flow 控制它什么时候跑、怎么跑、跑完怎么收。
**修改方向**：
- SKILL.md 角色定位段落改写，以 harness 思想为核心：sm-flow 编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec
- 不再说"不替代"，正面描述编排职责
- 真理源分层改为四层架构：
```
sm-flow → 编排层（harness）：阶段、门控、产物约束、人类对齐
OpenSpec → 执行引擎：propose/apply/archive 的能力提供方
devflow/ → 记忆层：为编排层提供上下文，接收执行结果的回填
code → 实现结果：apply 的产出
```
**影响范围**：SKILL.md 的角色定位和真理源分层段落。其他规则不需要变——它们本来就在做 harness 的事。
**设计自由度**：定位明确后，未来 sm-flow 约束 OpenSpec 使用方式（task 粒度检查、specs 可验收性评分、apply 进度汇报格式）都是合理的编排行为，不再需要解释"为什么 sm-flow 可以管 OpenSpec"。
### 修改 2：Fallback 重新定位——从"降级"到"内置执行引擎" ✅ 已实施
**问题**：当前 fallbacks.md 把 OpenSpec 不可用时的处理称为"降级协议"。但从 harness 视角看，sm-flow 作为编排层天然需要自带执行能力——当外部执行引擎（OpenSpec CLI）不可用时，harness 自己接管执行不是"降级"，而是正常的能力切换。
**修改方向**：
- fallbacks.md 中 OpenSpec 相关的 fallback 重新定位为"内置执行协议"
- 优先级描述改为：优先使用 openspec CLI / 原生 skill（外部执行引擎）→ 不可用时 sm-flow 使用内置执行协议（内置执行引擎）
- SKILL.md 首次加载或角色定位部分加一句：sm-flow 不强制依赖 openspec CLI，内置执行协议可以纯文件方式完成整个流程
- 措辞从"降级风险"调整为"外部引擎不可用，切换为内置引擎"，保留声明和记录要求，但去掉"降级"暗示的能力不足感
**影响范围**：fallbacks.md 的措辞 + SKILL.md 首次加载或角色定位段落。
### 修改 3：新用户上手体验——devflow 概念延迟暴露 ✅ 已实施
**问题**：SKILL.md 第一段就直接引入 `devflow/` 概念，对不熟悉的新用户来说突兀。从 harness 视角看，devflow 是 harness 的内部记忆机制，不是用户需要理解的概念——就像用户不需要理解 Claude Code 的 context window 管理一样。
**修改方向**：
- SKILL.md 角色定位段落中，先用一句话说清 sm-flow 会自动管理项目长期记忆，用户不需要手动维护
- 把 devflow 的技术细节从角色定位移到真理源分层段落中自然引出
- 对用户可见的概念只有：sm-flow（流程）→ OpenSpec（变更）→ 代码（结果）
**影响范围**：SKILL.md 角色定位段落。
---
## 待讨论的设计问题
以下是已识别但尚未决定是否修改的问题，留待后续讨论。
### 问题 1：流程总成本 ✅ 已确认方向
**分析**：问题不是"流程太贵"，而是**固定成本没有随规模充分缩放**。Phase 0/0.5/1.5/2.5/2.9/4 的成本基本是 O(1) 的——不随代码量线性增长。当前 micro 只压缩了产物（少写几个文件），没有压缩 gate 数量。
| 改动规模 | 代码工作量 | 流程开销 | 开销占比 | 感受 |
|---|---|---|---|---|
| micro（30min 代码） | 30 min | 40-60 min | ~60% | 太重 |
| standard（2h 代码） | 2 h | 1-1.5 h | ~40% | 还行 |
| complex（1-2d 代码） | 12 h | 2-3 h | ~20% | 值得 |
**确认方向**：micro 模式下合并 gate，不只是压缩产物。
```
当前 standard：Phase 1 checkpoint → Phase 1.5 → Phase 2 → Phase 2.5 checkpoint → Phase 2.9
micro 合并后：Phase 1+1.5 合并 checkpoint → Phase 2（最少 1 个问题） → Phase 2.9（简化检查）
```
micro 的定位从"产物变少"变为"gate 变少但保留最关键的"（Phase 2 最小澄清 + Phase 2.9 commit gate）。
**✅ 已落地**：operating-rules.md 快速模式段落已重写（gate 合并策略），phase-contracts.md 中各阶段已使用英文命名并体现 micro 行为。
### 问题 2：Phase 1 ↔ Phase 2 循环收敛 ✅ 已确认方向
**根因**：当前阶段顺序是 Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然要回写已经细化过的 design/specs/tasks，形成不可避免的返工循环。这不是 agent 执行问题，是**流程顺序决定了返工必然存在**。
这也是使用问题.md 中第 3 条提到的核心痛点："propose 之后生成了 task、design 等产物，再用 grill 澄清需求，澄清完又得回去更新"。
**确认方向**：调整阶段执行顺序，先澄清再细化。Phase 1 只产出轻量 proposal，Phase 2 在轻量 proposal 上做 grill，Phase 1.5 在需求稳定后才补全完整 OpenSpec。
| | Phase 1（轻量 propose） | Phase 1.5（细化 + 对齐） |
|---|---|---|
| 执行者 | sm-flow 内置协议 | openspec-propose 或内置协议 |
| 产出 | 只写 proposal.md（范围、问题、方案方向、非目标） | 补全 design.md + specs/ + tasks.md |
| 目的 | 建立讨论对象 | 需求稳定后生成完整 OpenSpec |
| token 成本 | 低 | 正常 |
调整后的阶段顺序：
```
Phase 0 入口澄清
Phase 0.5 devflow 上下文收集
Phase 1 轻量 propose（sm-flow 内置协议，只写 proposal.md） ← 不调用 openspec-propose
Phase 2 grill 澄清（基于 proposal.md，把需求钉死）
Phase 1.5 细化 + cross-artifact 对齐（调用 openspec-propose 补全 design/specs/tasks）
Phase 2.5 架构审计
Phase 2.9 commit gate
Phase 3 apply
Phase 4 回填 devflow
```
**三个附带收益**：
1. **循环消失**：grill 在细化之前，不存在"细化 → grill → 回写细化"的循环
2. **token 节省**：micro 模式下 Phase 1 只写轻量 proposal，不浪费 token 写详细产物（与问题 1 联动）
3. **openspec-propose 角色更准确**：不再是"从零 propose"，而是"基于已稳定的 proposal 做细化补全"——harness 对执行引擎的合理调度
**Phase 编号不变，Phase 2 和 Phase 1.5 的执行顺序对调**。阶段总览列表中的编号保持原样，但实际执行顺序变为 0 → 0.5 → 1 → 2 → 1.5 → 2.5 → 2.9 → 3 → 4。
**✅ 已落地**：SKILL.md 阶段总览使用英文命名（clarify → archive），phase-contracts.md 已按新顺序重写（grill 在 specify 前），fallbacks.md 中 OpenSpec 提案降级触发时机改到 specify 阶段。
### 问题 3：devflow 就近写入 vs agent 注意力 ✅ 已确认方向
**分析**：Phase 1-3 期间要求 agent 同时维护 OpenSpec（执行真理源）和 devflow（人类档案层），本质上是**双重记录**——同一份内容写两遍，Phase 4 还要再检查修正，变成三次写入。
**确认方向**：Phase 1-3 只维护一个轻量 decisions.md 作为过程日志，Phase 4 从中提取完整 devflow。
| 阶段 | 写入什么 | 性质 |
|---|---|---|
| Phase 1-3 | 只维护 `decisions.md`（grill 结论、关键决策、验证结果） | 过程日志，轻量追加 |
| Phase 4 | 从 decisions.md + OpenSpec 产物提取 brief/evidence/acceptance | 最终档案，一次性提取 |
**约束**：Phase 4 的 devflow 提取必须基于 decisions.md 和 OpenSpec 产物，不能是纯粹的事后回忆录。decisions.md 是提取的依据链。
**✅ 已落地**：SKILL.md 核心规则已改为"clarify → apply 只维护 decisions.md 作为过程日志；archive 阶段从中提取完整 devflow 档案"，phase-contracts.md 各阶段退出条件已同步更新。
### 问题 4：部分阶段独立使用 ✅ 已确认方向
**问题**：当前支持"指定阶段模式"，但从中间启动时上游阶段的产物可能不满足当前阶段的进入条件。
**确认方向**：借鉴 OpenSpec 的 "Actions, Not Phases" 设计哲学——**用户命令表达意图，不表达阶段**。阶段是 harness 的内部词汇，不是用户的 API。
**用户命令设计（4 个）**：
```
/sm-flow → 完整流程（从入口到归档）
/sm-flow explore → 先聊聊（需求不清楚）
/sm-flow apply → 直接执行（已有 Committed OpenSpec）
/sm-flow archive → 归档（执行完了，回填 devflow + 归档 OpenSpec）
```
| 命令 | 用户意图 | harness 内部行为 |
|---|---|---|
| `/sm-flow` | 从头到尾 | 完整编排 9 个阶段 |
| `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
| `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
| `/sm-flow archive` | 收尾 | backfill devflow + 归档确认 |
**典型使用场景**：
```
# 第一次：完整规划
/sm-flow 给站内消息加 OMC 支持
→ 走完 propose → grill → specify → audit → commit
→ 停在 apply 前，用户说"先不执行了"
# 第二次：继续执行
/sm-flow apply ops-message-support
→ 进入 apply，执行完 tasks
# 第三次：归档
/sm-flow archive ops-message-support
→ 回填 devflow，询问是否归档 OpenSpec change
```
三个阶段，三次调用，每次只做一个用户意图的事。
**阶段命名（内部协议）**：
借鉴 OpenSpec 的动词式命名风格，阶段名称保留为 **agent 的词汇表**（用于 checkpoint 汇报和进度通知），不作为用户命令：
```
旧编号 → 描述名（内部） 做什么
Phase 0 → clarify 入口澄清
Phase 0.5 → context 上下文收集
Phase 1 → propose 轻量 propose（只写 proposal）
Phase 2 → grill 人类对齐澄清
Phase 1.5 → specify 细化 + 对齐（补全 design/specs/tasks）
Phase 2.5 → audit 架构审计
Phase 2.9 → commit commit gate
Phase 3 → apply OpenSpec 执行
Phase 4 → archive 回填 devflow + 归档确认
```
**agent 用阶段名做 telemetry**：
- "当前在 grill 阶段，已解决 2/5 个问题"
- "grill 完成，进入 specify"
**用户用自然语言交互**：
- "/sm-flow" → 启动完整流程
- "ops-message-support 的 grill 已经做完了，继续" → harness 识别意图，自动补做最小前置检查
- "帮我检查一下 add-dark-mode 的 OpenSpec 对齐" → harness 识别意图，只做 specify 阶段的对齐检查
**核心原则**：用户只需要知道四件事（完整流程 / explore / apply / archive），其余全部通过自然语言交互，由 harness 识别意图后编排。
**✅ 已落地**：SKILL.md 用户命令表格（4 个命令），operating-rules.md 启动检查已识别用户命令意图，phase-contracts.md 所有阶段已使用英文命名。
### 问题 5：workflow.md 的维护方式 ✅ 已确认方向
**问题**：workflow.md 是 590 行的设计演进文档，混合了三类内容：设计理念（稳定）、变更日志（每次迭代追加）、历史对比（写完不动）。读者需要翻 590 行才能理解"现在的设计是什么"。
**确认方向**：方向 A——顶部加"当前设计理念"摘要，历史部分作为审计轨迹保留。
```markdown
# SM-Flow 工作流
## 当前设计理念（v4 方向）
- sm-flow 是协议层 harness，编排 OpenSpec 生命周期
- 四层架构：harness → OpenSpec → devflow → code
- 用户命令 4 个：/sm-flow / explore / apply / archive
- 9 个内部阶段（英文描述命名）：clarify → context → propose → grill → specify → audit → commit → apply → archive
- 阶段名是内部协议，不是用户 API
- 真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
- Draft/Committed 分离
- ...（20-30 行）
---
## 演进历史
（原有的 v1→v3.1+ 内容不动）
```
**来源**：design-review.md 的"核心定位"章节可以直接作为摘要的草稿。
**⏳ 待落地**：在 workflow.md 顶部插入当前设计理念摘要段落（本项属于文档维护，不在 skill 文件范围内）。
### 问题 6：SKILL.md 核心规则分类 ✅ 已确认方向
**问题**：当前 ~22 条核心规则平铺在一个列表里，混合了三种不同性质的约束。agent 读到第 15 条已经记不清前 5 条的优先级。
**确认方向**：三类分组 + 英文阶段命名 + 质量约束必须有可观测产出。
**A. 三类分组**
```markdown
## 核心规则
### 硬约束（违反即流程失败）
- apply 必须通过 OpenSpec apply 执行
- 不得跳过 context
- 不得跳过 grill（至少三个高价值问题）
- 不得跳过 commit
- 不得猜测式修 bug
- fallback 产物必须标注
- micro 不能跳过关键 gate
### 流程约束（必须按顺序做）
- 先建 question pool，再消费 user-interview
- 单个 grill 决策确认不等于 apply 授权
- 冲突必须先分类再处理
- 影响实现的发现必须先回写 OpenSpec
- 子 skill 必须显式调用或显式降级
- clarify → apply 只维护 decisions.md，archive 阶段提取完整档案
- archive 前必须询问是否归档
### 质量约束（必须有可观测产出）
- specify 的 checkpoint 必须包含 cross-artifact 对齐检查表（4 行，每行标记已对齐/存在 gap）
- evidence-driven 结论必须写入 decisions.md，且 checkpoint 必须列出汇报状态
- user-interview 必须在 decisions.md 中记录问题原文、用户原话、确认状态；未确认的不能从 question pool 移除
- checkpoint 必须包含：当前阶段、能力来源、产出物清单、已满足退出条件、未解决阻塞
- human-in-the-loop 检查点：propose 后、audit 后、commit 后、apply 前
> 三类约束都不可违反。分类的目的是帮助快速定位规则类型。
> 质量约束必须转化为可观测的产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
```
**B. 阶段编号改为英文描述名**
去掉 Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 的数字编号，全部用英文动词：
```
clarify → 入口澄清
context → 上下文收集
propose → 轻量 propose（只写 proposal）
grill → 人类对齐澄清
specify → 细化 + cross-artifact 对齐
audit → 架构审计
commit → commit gate
apply → OpenSpec 执行
archive → 回填 devflow + 归档确认
```
执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive
用户命令是 API（4 个），阶段名是内部协议（9 个）。风格统一（英文动词），职责分离。
**C. 质量约束的可观测产出原则**
协议层 harness 的核心弱点：质量约束如果没有可观测的产出，agent 一定会跳过。
| 约束 | 原写法（软） | 改为（硬） |
|---|---|---|
| evidence-driven 汇报 | "必须向用户汇报" | 写入 decisions.md + checkpoint 列出汇报状态 |
| user-interview 确认 | "必须等待用户显式回答" | decisions.md 记录问题原文/用户原话/确认状态 |
| cross-artifact 对齐 | "必须显式检查" | checkpoint 包含 4 行对齐检查表，每行标记已对齐/存在 gap |
**✅ 已落地**：SKILL.md 核心规则已按三类分组重写（硬约束 / 流程约束 / 质量约束），phase-contracts.md 所有阶段使用英文命名，各 checkpoint 退出条件已加可观测产出检查。
### 问题 7：grill 阶段 evidence-driven 和 user-interview 的节奏 ✅ 已确认方向
**问题**：当前规则说"可以并行整理 evidence-driven 证据，但 user-interview 仍然必须 one-at-a-time"。但 agent 可能把所有 evidence-driven 结论一口气汇报完，然后才问 user-interview 问题，导致用户被动接收大量信息后再被采访。
**确认方向**：在 grill 阶段的动作描述里明确"交替推进"。
```markdown
grill 阶段的推进节奏：
- evidence-driven 和 user-interview 应交替推进，避免把所有证据结论攒到一起汇报
- 典型模式：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续
- evidence-driven 可以并行查证（不需要用户参与），但汇报和 user-interview 穿插进行
```
**实际落地**：phase-contracts.md grill 阶段动作描述已调整。经评估后，"交替推进"对 agent 的要求过高（LLM 天然倾向批量处理），改为更务实的"先批量查证 evidence-driven 并一次性汇报，再逐个处理 user-interview"，降低执行复杂度同时保留核心约束。
skill-workbench/docs/sm-flow/workflow.md
+209 -2
View File
@@ -1,4 +1,62 @@
# 增强版工作流总结 # 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](./使用方式.md)，包括：
- 4 个用户命令的典型场景
- 完整规划 → 执行 → 归档的分次调用示例
- 自然语言交互方式
- 规模分档（micro / standard / complex）
- devflow 自动维护机制
- OpenSpec 集成与 Draft/Committed 分离
- 常见问题解答
---
## 演进历史
以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
## 旧工作流 vs 新工作流 ## 旧工作流 vs 新工作流
@@ -583,8 +641,157 @@ references/operating-rules.md
- 修正 fallback 锚点，避免 skill 指向不存在的章节名 - 修正 fallback 锚点，避免 skill 指向不存在的章节名
- 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则 - 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
这轮修正说明一件事：协议产品化不只是“把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。 这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、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） |
skill-workbench/docs/sm-flow/使用方式.md
+191
View File
@@ -0,0 +1,191 @@
# SM-Flow 使用方式
本文档面向 sm-flow 的用户，说明如何启动、交互和使用 sm-flow。
## 快速开始
sm-flow 通过 4 个用户命令覆盖完整生命周期。你不需要了解内部阶段，只需表达意图。
| 命令 | 意图 | 典型场景 |
|---|---|---|
| `/sm-flow` | 完整流程 | 有粗略想法，从头规划到执行 |
| `/sm-flow explore` | 先聊聊 | 需求不清楚，带上下文探索 |
| `/sm-flow apply [change]` | 只执行 | 已有 Committed OpenSpec，直接实现 |
| `/sm-flow archive [change]` | 收尾 | 执行完了，回填 devflow + 归档 |
你也可以用自然语言指定阶段继续，例如：
```
ops-message-support 的 grill 已经做完了，继续
帮我检查一下 add-dark-mode 的 OpenSpec 对齐
```
sm-flow 会识别意图，自动补做最小前置检查，然后从指定阶段继续。
## 典型使用流程
### 场景 1：完整规划 → 执行 → 归档（分三次调用）
```bash
# 第一次：完整规划
/sm-flow 给站内消息加 OMC 支持
→ 走完 clarify → context → propose → grill → specify → audit → commit
→ 停在 apply 前，你说"先不执行了"
# 第二次：继续执行
/sm-flow apply ops-message-support
→ 进入 apply，执行完 tasks
# 第三次：归档
/sm-flow archive ops-message-support
→ 回填 devflow，询问是否归档 OpenSpec change
```
三个阶段，三次调用，每次只做一个用户意图的事。
### 场景 2：需求不清楚，先探索
```bash
/sm-flow explore 我们在考虑是否要重构消息队列
→ sm-flow 读取 devflow 上下文，和你讨论需求边界、风险、替代方案
→ 不生成 OpenSpec，只帮你理清思路
→ 如果讨论出明确方向，下次可以用 /sm-flow 启动完整流程
```
### 场景 3：小改动，快速模式
```bash
/sm-flow 修复按钮的拼写错误
→ sm-flow 识别为 micro 规模
→ 合并 gate：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
→ 保留最关键的门控，但流程更轻量
```
### 场景 4：从中间继续
```bash
# 上次对话停在 grill 阶段
add-dark-mode 的 grill 已经做完了，继续
→ sm-flow 识别意图，自动补做 specify 的最小前置检查
→ 从 specify 阶段继续
```
## 交互模式
### Human Checkpoint
sm-flow 在关键节点会暂停并询问你：
- **propose 后**：说明 proposal 范围、关键假设、主要风险，询问是否继续 grill
- **grill 后**：汇报已解决和未解决的问题、proposal 变更，询问是否继续 specify
- **audit 后**：说明架构风险、OpenSpec 修正点，询问是否进入 commit
- **commit 后**：说明 Committed OpenSpec 范围、接口影响、剩余风险，询问是否进入 apply
- **archive 前**：询问是否归档 OpenSpec change
你可以选择继续、暂停、或要求返回上一阶段。
### Grill 阶段的一对一澄清
grill 阶段会建立一个 question pool，覆盖术语、边界、验收三个维度。问题分两类：
- **evidence-driven**：sm-flow 先查证代码、文档、OpenSpec 或 ADR，再向你汇报证据和结论
- **user-interview**：sm-flow 一次只问一个问题，等你确认后才继续
典型节奏：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续。
### 自然语言交互
除了 4 个命令，你可以用自然语言与 sm-flow 交互：
```
# 指定 change name
继续 ops-message-support
# 指定阶段
add-dark-mode 的 specify 做完了吗？
# 指定动作
帮我检查一下 add-dark-mode 的 cross-artifact 对齐
# 混合表达
ops-message-support 的 grill 已经确认了术语和边界，继续 specify
```
sm-flow 会识别意图，自动编排后续阶段。
## 规模分档
sm-flow 根据变更规模自动分档，调整流程重量：
| 分档 | 适用场景 | 流程特点 |
|---|---|---|
| `micro` | 小改动、低风险、需求明确 | gate 合并，grill 最少 1 个问题，commit 简化检查 |
| `standard` | 默认模式 | 完整 9 阶段流程 |
| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 基础上增加扩展产物（PRD/research/design/tasks/alignment） |
你不需要显式指定分档，sm-flow 会在 clarify 阶段自动判断。如果判断不准，会作为 user-interview 问题等待你确认。
## devflow：自动维护的项目长期记忆
sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。你不需要手动管理它。
```
devflow/
├── projects/YYYY-MM-DD-{slug}/ ← 项目档案（brief/evidence/decisions/acceptance）
├── glossary/CONTEXT.md ← 领域词汇表
├── compound/ ← 跨项目知识沉淀
├── reference/ ← 共享模板
└── index.md ← 项目索引
```
**clarify → apply 期间**：sm-flow 只维护 `decisions.md` 作为过程日志（grill 结论、关键决策、验证结果）。
**archive 阶段**：从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
**下次使用时**：sm-flow 会自动读取 devflow 上下文，增强 OpenSpec 产物。术语、历史决策、验收记录不会丢失。
## OpenSpec 集成
sm-flow 编排 OpenSpec 的生命周期，但不强制依赖 OpenSpec CLI：
- **优先使用 OpenSpec CLI**：如果 `openspec-propose`、`openspec-apply-change`、`openspec-archive-change` 可用，sm-flow 会调用它们
- **内置执行协议**：如果 OpenSpec CLI 不可用，sm-flow 使用内置协议接管（标注为降级执行）
Draft / Committed 分离：
- **Draft OpenSpec**：propose 阶段产出，是讨论对象，不是执行许可
- **Committed OpenSpec**：通过 commit gate 后，成为 apply 的执行依据
- **apply 只执行 Committed OpenSpec**：防止未经澄清的方案直接进入实现
## 常见问题
### Q: 我需要在启动前准备什么？
不需要。sm-flow 会从你的粗略想法、issue、PRD 或已有 research 开始。如果信息不足，clarify 阶段会追问。
### Q: 我可以跳过某个阶段吗？
不可以。sm-flow 的门控是硬约束（grill 至少 3 个问题、commit gate 必须通过）。但 micro 模式会合并 gate，减少流程开销。
### Q: 如果 OpenSpec 不可用怎么办？
sm-flow 会使用内置执行协议接管，标注为降级执行。产物仍然写入 `openspec/changes/{slug}/`，只是不通过 OpenSpec CLI。
### Q: devflow 和 OpenSpec 冲突怎么办？
sm-flow 会先汇报冲突，等你确认，然后修正 OpenSpec，再继续执行。devflow 是上下文，OpenSpec 是执行真理源。
### Q: 我可以修改已经 commit 的 OpenSpec 吗？
可以。如果 apply 阶段发现规格遗漏、设计冲突或用户变更，sm-flow 会暂停 apply，修正 OpenSpec 后重新提交。
### Q: archive 阶段会自动归档 OpenSpec 吗？
不会。archive 阶段会回填 devflow，然后询问你是否归档 OpenSpec change。在你说"是"之前，不会执行归档。
## 参考文档
- **设计理念**：[workflow.md](./workflow.md) — 当前设计理念（v4 方向）和演进历史
- **设计评审**：[design-review.md](./design-review.md) — 核心定位、状态评估、已确认修改方向
- **回溯分析**：[retrospective.md](./retrospective.md) — 历史执行失败分析
- **使用问题**：[使用问题.md](./使用问题.md) — 真实痛点收集