clean obsolete skill workspace files

upgrade sm-flow v3.1 workflow
2026-05-21 20:17:15 +08:00 · 2026-05-21 19:55:23 +08:00
39 changed files with 955 additions and 1206 deletions
@@ -1,4 +1,4 @@
---
+---
 name: sm-flow
 description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
 ---
@@ -17,6 +17,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
 - 代码是实现结果：只能在执行真理源足够明确后修改。
 - 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
+- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。

 ## 核心规则

@@ -25,16 +27,39 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
 - 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
 - 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
+- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
 - `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
 - `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
+- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
+- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
+- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
 - 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
 - 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
+- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
 - Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
 - 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
+- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
 - fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。

+## 接口影响分级
+
+接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
+| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
+| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
+| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
+
+判断策略：
+
+- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
+- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
+- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
+- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+
 ## 首次加载

 执行前只读取当前任务需要的 reference 文件：
@@ -59,8 +84,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
   - `devflow/reference/`
 3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
 4. 检查 OpenSpec 和子 skill 是否可用：
-   - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
-   - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
+   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
+   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
 5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。

 ## 项目标识
@@ -101,13 +126,14 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
 ## 阶段总览

 1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
-2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
-3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
+2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
+3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
 4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
 5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
 6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
-7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
-8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
+7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
+8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
+9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。

 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。

@@ -117,6 +143,7 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的

 - Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
 - Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
+- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
 - Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
 - Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。

@@ -17,6 +17,10 @@ devflow/projects/YYYY-MM-DD-{slug}/
 - `decisions.md`
 - `acceptance.md`

+同时维护仓库级索引：
+
+- `devflow/index.md`
+
 按需创建以下扩展文件：

 - `prd.md`
@@ -49,6 +53,24 @@ devflow/projects/YYYY-MM-DD-{slug}/
 | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
 | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
 | 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
+
+## 索引维护规则
+
+`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
+
+最小字段：
+
+| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
+| --- | --- | --- | --- | --- | --- |
+
+规则：
+
+- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
+- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
+- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
+- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
+- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。

 ## 验收记录规则

@@ -99,6 +121,7 @@ OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 de
 Phase 4 结束时告诉用户：

 - 创建或更新了哪些档案文件。
+- `devflow/index.md` 是否已更新。
 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
 - 还剩哪些风险或后续事项。
 - 明确询问：是否现在 archive OpenSpec change？
@@ -34,12 +34,20 @@

 1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
 2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
-3. 修改前先检查现有代码。
-4. 一次实现一个 OpenSpec task 的纵向切片。
-5. 用最窄但有效的命令验证每个切片。
-6. 只有验证通过或明确记录原因后，才更新 task 状态。
-7. 如果失败原因不确定，停止并进入 diagnose。
-8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
+3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
+4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
+5. 修改前先检查现有代码。
+6. 一次实现一个 OpenSpec task 的纵向切片。
+7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
+   - 实现偏差：OpenSpec 正确，代码偏离；修代码。
+   - 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
+   - 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
+   - 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
+8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
+9. 用最窄但有效的命令验证每个切片。
+10. 只有验证通过或明确记录原因后，才更新 task 状态。
+11. 如果失败原因不确定，停止并进入 diagnose。
+12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。

 ## PRD fallback

@@ -28,6 +28,8 @@
 **进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。

 **动作**：
+- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
+- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
 - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
@@ -36,6 +38,7 @@

 **退出条件**：
 - 已形成“OpenSpec 输入上下文摘要”。
+- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。

@@ -46,7 +49,7 @@

 **进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。

-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。

 **动作**：
 - 优先调用 `openspec-propose`。
@@ -64,7 +67,7 @@
 - 关键假设已显式记录在 OpenSpec 或 research 中。

 **输出**：
- OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal、design、specs 和 task list。

 **Human checkpoint**：
 - 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
@@ -85,11 +88,16 @@
  - OpenSpec 是否遵守相关 ADR。
  - specs 是否能表达可观察行为。
  - tasks 是否能驱动实现，而不是泛泛描述。
+- 检查是否涉及接口影响：
+  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
+  - 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
+  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。

 **退出条件**：
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - OpenSpec 与 PRD/devflow 上下文没有已知冲突。
+- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
 - 所有已知冲突已修正或等待用户决策。

 **输出**：
@@ -110,6 +118,10 @@
  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
 - 至少覆盖三个维度：术语、边界、验收。
 - 一次只问一个 `user-interview` 问题。
+- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
+- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
+- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
+- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
 - 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
@@ -118,6 +130,8 @@
 - 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
+- 没有未解决或代理代确认的 user-interview 问题。
+- 没有未判级或未确认的接口影响问题。
 - 影响实现的结论已回写 OpenSpec。

 **输出**：
@@ -148,14 +162,46 @@

 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
+
+## Phase 2.9 — Commit OpenSpec
+
+**进入条件**：
+- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
+- 所有 `user-interview` 问题都已获得用户显式确认。
+- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
+- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
+
+**动作**：
+- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
+- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
+- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
+- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
+- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
+- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
+- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
+
+**退出条件**：
+- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
+- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
+- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
+
+**输出**：
+- Committed OpenSpec 状态说明。
+- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
+
+**Human checkpoint**：
+- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
+- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
+- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。

 ## Phase 3 — OpenSpec apply

 **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
+- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
 - devflow 与 OpenSpec 没有未解决冲突。
+- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。

 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。

@@ -163,6 +209,12 @@
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
+- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
+  - 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
+  - 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
+  - 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
+  - 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
+- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
@@ -170,6 +222,7 @@

 **退出条件**：
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。

@@ -188,10 +241,12 @@
 - 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
+- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。

 **退出条件**：
 - `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。

 **输出**：
@@ -65,6 +65,68 @@
  - 风险接受：{accepted by whom/when}
 ```

+## 接口影响记录模板
+
+```markdown
+# {标题} 接口影响记录
+
+## 分级
+
+- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
+- 判级原因：{why this level}
+- 是否需要独立接口文档：是 / 否
+
+## 变更对象
+
+- 接口/字段/DTO/事件/回调/数据库契约：
+- 判断逻辑变化：
+- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
+
+## 影响范围
+
+- 调用方/消费者：
+- 是否跨模块/跨服务/跨团队：
+- 旧调用方是否需要改动：
+
+## 兼容与迁移
+
+- 是否向后兼容：
+- 迁移/灰度/回滚要求：
+- 风险接受：
+
+## 验收方式
+
+- 如何证明新行为正确：
+- 如何证明旧行为未破坏：
+- 需要用户确认的问题：
+```
+
+## 实现期冲突记录模板
+
+```markdown
+# {标题} 实现期冲突记录
+
+## 冲突摘要
+
+- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
+- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
+- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
+
+## 证据
+
+- OpenSpec 依据：
+- 代码或测试证据：
+- 用户反馈：
+
+## 处理
+
+- 决策：
+- 是否需要用户确认：是 / 否
+- OpenSpec 回写：不需要 / 已回写 / 待回写
+- 代码处理：
+- 验证方式：
+```
+
 ## PRD 模板

 ```markdown
@@ -1,136 +0,0 @@
-# Skills v0.5.0 整合修复记录
-
-**日期：** 2026-04-30
-**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致
-
---
-
-## 一句话摘要
-
-在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。
-
---
-
-## 已完成的改动
-
-### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏）
-
-| 位置 | 修改内容 |
-|---|---|
-| 版本号 | `0.3.0` → `0.5.0` |
-| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 |
-| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point |
-| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` |
-| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 |
-| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect |
-| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） |
-
-### 2. `/follow` — 消除旧引用和设计偏差
-
-| 位置 | 修改内容 |
-|---|---|
-| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader |
-| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） |
-| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" |
-| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 |
-
-### 3. `/explore` — 合并冗余阶段
-
-| 位置 | 修改内容 |
-|---|---|
-| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` |
-| 阶段总数 | 5 Phase → 4 Phase |
-| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 |
-| Outcome 模板 | `5/5` → `4/4` |
-
-### 4. References 清理
-
-| 文件 | 操作 |
-|---|---|
-| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 |
-| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 |
-
-### 5. docs 存档清理
-
-| 文件 | 操作 | 原因 |
-|---|---|---|
-| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 |
-| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 |
-| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 |
-| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 |
-
---
-
-## docs 存档最终结构
-
-```
-docs/superpowers/
-├── specs/
-│   ├── issue.md                                    # 原始需求
-│   ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md
-│   └── 2026-04-21-skills-v0.5.0-changelog-design.md
-└── changelog/
-    ├── 2026-04-21-skills-v0.5.0-slim-architecture.md   # 第一次改造 changelog
-    ├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令
-    └── 2026-04-30-skills-v0.5.0-consolidation.md       # 本次整合（本文件）
-```
-
---
-
-## 当前 skill 状态
-
-| 技能 | 版本 | Phase/Mode | 备注 |
-|---|---|---|---|
-| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure |
-| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection |
-| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 |
-
---
-
-## 实践验证结果
-
-**日期：** 2026-04-30  
-**测试目标仓库：**
- 非代码仓库：explore-skill-family（自身）
- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent）
-
-| # | 验证路径 | 目标 | 结果 |
-|---|---|---|---|
-| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ |
-| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start |
-| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 |
-| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 |
-| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 |
-| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 |
-| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 |
-
-### 验证发现的额外修复
-
-验证过程中对 SKILL.md 的追加修改（已在代码中反映）：
- `/essence` Phase 6 → Optional: HTML Card
- `/essence` Mode Selection 上下文感知
- `/essence` Most imported file → Cross-module contract
- `/follow` Mode Selection 来源感知
- `/follow` Runnable Check 不再重扫，引用前置报告
- `/follow` Reader Mode Flow 提升到设计层
- `/follow` Teaching Interaction Rules 收紧
- `/explore` Phase 1+2 合并，5→4 Phase
- `/explore` Project Type Detection 信号改为后端导向
- 删除 `skills/explore/references/deep-fission.md`
-
-### handoff 10 条检查清单逐项结论
-
-| # | 问题 | 结论 |
-|---|---|---|
-| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 |
-| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 |
-| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 |
-| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 |
-| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 |
-| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 |
-| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 |
-| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 |
-| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 |
-| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 |
-
-**总体验收结论：通过。** 文档、边界、行为三者一致。
@@ -0,0 +1,11 @@
+# Devflow Index
+
+`devflow/index.md` 是 Phase 0.5 的默认上下文入口。每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认维护一行，帮助代理先定位相关项目，再读取具体 brief、acceptance、ADR 或 compound knowledge。
+
+| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| 2026-05-18 | knowledge-index-panel | knowledge-index | knowledge-index, search, tags, static-html | `openspec/changes/knowledge-index-panel/` | active |
+| 2026-05-19 | add-clear-filters | knowledge-index | clear-filters, search, tags, year-filter | `openspec/changes/archive/2026-05-19-add-clear-filters/` | archived |
+| 2026-05-19 | add-year-filter | knowledge-index | year-filter, index-panel, frontmatter | `openspec/changes/add-year-filter/` | active |
+| 2026-05-19 | dev-flow-skill-evaluation | sm-flow | dev-flow, sm-flow, skill-evaluation, fallback, phase-contracts | 未关联 | accepted-unarchived |
+| 2026-05-21 | sm-flow-v3-1-upgrade | sm-flow | interface-impact, commit-gate, devflow-index, apply-conflict, skill-compatibility | `openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/` | archived |
@@ -0,0 +1,59 @@
+# SM Flow v3.1 Upgrade Acceptance
+
+## 结果
+
+已接受。
+
+## 验证
+
+### 静态验证
+
+- 命令/检查：`openspec status --change "sm-flow-v3-1-upgrade"`
+- 结果：passed
+- 备注：proposal、design、specs、tasks 均为 complete。
+
+- 命令/检查：`rg -n "Draft OpenSpec|Committed OpenSpec|Phase 2.9|devflow/index.md|接口影响|实现期冲突|能力契约|平台原生 skill|user-interview" ...`
+- 结果：passed
+- 备注：关键术语已覆盖 `.agents/skills/sm-flow/`、OpenSpec change、workflow 文档和 devflow 项目档案。
+
+### 脚本验证
+
+- 命令：`openspec instructions apply --change "sm-flow-v3-1-upgrade" --json`
+- 结果：passed
+- 备注：所有 17 个 OpenSpec tasks 已完成。
+
+### 浏览器/人工验证
+
+- 步骤：不适用，本次是流程文档和 OpenSpec 规则改造。
+- 结果：not run
+- 备注：无 UI 行为。
+
+## 已完成范围
+
+- 增加 Draft OpenSpec / Committed OpenSpec / Phase 2.9 commit gate。
+- 强化 Phase 2 grill 的显式人工确认约束。
+- 增加“单个 grill 决策确认不等于 Phase 3 apply 授权”的硬约束。
+- 增加接口影响 L1-L4 分级和接口影响记录模板。
+- 增加 `devflow/index.md` 和 Phase 0.5 / Phase 4 索引维护规则。
+- 增加 Phase 3 实现期冲突四分类和 fallback 执行规则。
+- 将子 skill 兼容规则改为能力契约优先、路径其次。
+- 更新 `skill-workbench/docs/sm-flow/workflow.md` 的 v3.1 说明。
+
+## 已知限制
+
+- `openspec/config.yaml` 由 OpenSpec CLI 创建并保持未跟踪状态。
+- 工作区存在与本次无关的已删除文件，未处理。
+
+## 流程偏差记录
+
+- 偏差：本次执行中，Phase 2 grill 决策确认后曾直接进入执行文件修改，没有显式停在 Phase 2.9 checkpoint 等待 Phase 3 apply 授权。
+- 分类：实现偏差。v3.1 规格方向正确，但执行过程没有严格遵守“grill 确认 ≠ apply 授权”的门禁。
+- 修正：已回写 OpenSpec，新增 requirement 和 task，要求 Phase 2/2.5 回写后必须停在 Phase 2.9，并等待明确 Phase 3 apply 授权。
+- 当前状态：用户已明确授权“执行apply”，该新增 requirement 已应用到 `.agents/skills/sm-flow/*` 和 workflow 文档。
+
+## 交接
+
+- 下一步：已归档，后续可从 devflow 档案和 OpenSpec archive 回溯。
+- OpenSpec 归档确认：用户已确认归档。
+- OpenSpec 归档位置：`openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/`
+- Specs 同步：未执行；本仓库 `openspec/specs/` 当前无主 spec 文件，本次保留 delta specs 于 archive 中。
@@ -0,0 +1,30 @@
+# SM Flow v3.1 Upgrade Brief
+
+## 背景
+
+- 用户目标：把 `sm-flow` v3 使用中暴露的接口文档、流程顺序、上下文定位、子 skill 兼容和实现期冲突问题固化为 v3.1 协议。
+- 当前问题：v3 已经确立 OpenSpec-first，但缺少接口影响分级、Draft/Committed OpenSpec gate、devflow 索引和 Phase 3 冲突沟通规则。
+- 关联 OpenSpec：`openspec/changes/sm-flow-v3-1-upgrade/`
+- devflow 分档：standard
+
+## 范围
+
+- 本次要做：更新 `sm-flow` skill 本体、phase contracts、fallbacks、templates、workflow 说明，并创建/维护 devflow 索引。
+- 本次不做：修改业务代码、重写 OpenSpec CLI、把 devflow 变成执行真理源、强制所有接口变更都独立产出接口文档。
+- 影响区域：
+  - `.agents/skills/sm-flow/SKILL.md`
+  - `.agents/skills/sm-flow/references/*.md`
+  - `skill-workbench/docs/sm-flow/workflow.md`
+  - `devflow/index.md`
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖
+- specs 覆盖状态：已覆盖
+- tasks 覆盖状态：已覆盖
+
+## OpenSpec 输入上下文摘要
+
+- v3 历史决策：`devflow/` 是上下文真理源，OpenSpec 是执行真理源，代码是实现结果。
+- 用户问题来源：`skill-workbench/docs/sm-flow/使用问题.md`，共 6 个问题，集中在接口产物、流程顺序、上下文检索、子 skill 兼容和实现期冲突。
+- 历史评估来源：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`，已确认子 skill fallback、quick 模式、Phase 退出条件和 OpenSpec-first 是 v3 的关键设计。
@@ -0,0 +1,39 @@
+# SM Flow v3.1 Upgrade Decisions
+
+## User-interview
+
+| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
+| --- | --- | --- | --- |
+| 是否启动 v3.1 改造？ | “开始这次的v3.1改造” | 创建 `sm-flow-v3-1-upgrade` OpenSpec change 并进入改造。 | 已回写 |
+| grill 过程中是否必须人工确认？ | 用户要求“如果 skill 里并没有强调 grill 的过程中一定要人工确认的话，加上这个约束”。 | Phase 2 的 user-interview 问题必须一问一答等待用户显式确认；未确认不能进入 Phase 2.9 / Phase 3。 | 已回写 |
+| 接口变更是否需要记录影响范围？ | 用户要求“只要涉及接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中”。 | 所有接口变更必须有影响记录。 | 已回写 |
+| 接口影响采用什么分级策略？ | 用户确认“可以，先按照分级来实现”。 | 采用 L1-L4 分级：L1 内部实现、L2 内部接口、L3 协作接口、L4 破坏性接口；接口内部判断逻辑按可观察行为评估。 | 已回写 |
+| devflow 上下文索引是否强制维护？ | 用户确认“可以”。 | 强制维护轻量 `devflow/index.md`；Phase 0.5 先查 index，Phase 4 回填时必须更新 index。 | 已回写 |
+| 实现阶段遇到与原设计冲突的质疑或修改时如何处理？ | 用户确认“可以”。 | Phase 3 采用四类实现期冲突分类：实现偏差、规格遗漏、设计冲突、用户变更；先分类和确认，再继续代码或 OpenSpec 修正。 | 已回写 |
+| 子 skill 兼容规则是否采用能力优先？ | 用户确认“可以”。 | 子 skill 绑定能力契约，不绑定单一平台路径；调用优先级为平台原生 skill、本地 `SKILL.md`、sm-flow fallback。 | 已回写 |
+| 单个 grill 决策确认是否等于 apply 授权？ | 用户确认“可以”。 | 单个 `user-interview` 的“可以”只确认该决策；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，等待明确 Phase 3 apply 授权。 | 已回写 |
+
+## Evidence-driven 澄清
+
+| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec |
+| --- | --- | --- | --- | --- | --- |
+| 术语 | evidence-driven | “接口影响范围文档”和“接口文档”是否同一产物？ | 用户分别列为两个问题；流程需要降低文档重复。 | 区分“接口影响记录”和“独立接口文档”。 | 是 |
+| 边界 | evidence-driven | v3.1 是否要改变 OpenSpec-first 主轴？ | v3 skill 本体和历史评估都把 OpenSpec 定义为执行真理源。 | 不改变主轴，只补 gate。 | 是 |
+| 验收 | evidence-driven | 如何证明 v3.1 改造完成？ | OpenSpec specs 已覆盖接口影响、commit gate、上下文索引和 apply 冲突处理。 | 验收以文档规则可检索、OpenSpec status 完成、tasks 勾选为准。 | 是 |
+
+## 关键取舍
+
+- 决策：采用 Draft / Committed OpenSpec，而不是把 grill 移到 propose 前。
+  - 原因：Draft 给澄清提供结构化对象，Committed 防止草稿直接执行。
+  - 影响：新增 Phase 2.9，但减少 Phase 3 规格漂移。
+  - 风险接受：本次 v3.1 接受。
+
+- 决策：接口变更采用 L1-L4 分级。
+  - 原因：所有接口影响都需要追踪，但只有高影响变更需要独立接口文档。
+  - 影响：templates 和 phase contracts 需要增加接口影响记录。
+  - 风险接受：本次 v3.1 接受。
+
+- 决策：为 devflow 增加 `devflow/index.md`。
+  - 原因：项目档案增长后，需要索引而不是每次全量翻阅。
+  - 影响：Phase 0.5 和 Phase 4 都需要维护索引。
+  - 风险接受：本次 v3.1 接受。
@@ -0,0 +1,28 @@
+# SM Flow v3.1 Upgrade Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+| --- | --- | --- | --- |
+| `skill-workbench/docs/sm-flow/使用问题.md` | 用户列出 6 个实践问题，包含接口文档、propose/grill 顺序、devflow 检索、子 skill 兼容、Phase 3 设计冲突。 | v3.1 应围绕这些使用摩擦改协议，而不是重写整个流程。 | 是 |
+| `.agents/skills/sm-flow/SKILL.md` | 当前核心规则已要求 Phase 0.5、Phase 2、Phase 2.5、Phase 3、Phase 4，但没有 Draft/Committed OpenSpec 和接口影响分级。 | 新规则应补 gate，不应推翻 v3 的 OpenSpec-first 主从关系。 | 是 |
+| `.agents/skills/sm-flow/references/phase-contracts.md` | Phase 1 生成 OpenSpec 后进入 Phase 1.5/2/2.5，Phase 3 以 OpenSpec 执行；缺少 Phase 2.9 提交检查。 | “propose 后 grill 返工”应通过草稿/提交分离解释和治理。 | 是 |
+| `.agents/skills/sm-flow/references/fallbacks.md` | 执行 fallback 已要求失败原因不确定时 diagnose，规格不准先修 OpenSpec。 | 可扩展为 Phase 3 实现期冲突分类，不需要新建完全独立流程。 | 是 |
+| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 Claude 工具耦合、子 skill 调用方式不稳、Phase 退出条件不足。 | v3.1 的兼容规则应绑定能力契约，而不是绑定具体平台路径。 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：v3.1 应保留 v3 主轴，只增加 gate 和分级规则。
+  - 证据：当前 skill 文件和 phase contracts 已经清楚表达 OpenSpec-first。
+  - 风险：如果重写阶段顺序，容易引入新的执行歧义。
+  - 用户确认：已通过“开始这次的 v3.1 改造”确认推进。
+
+- 结论：接口文档应分级，不应一刀切。
+  - 证据：用户同时提出“接口影响范围文档”和“接口文档”，说明需要区分影响记录与独立文档。
+  - 风险：分级阈值不清会导致代理低估外部契约风险。
+  - 用户确认：需要在实现时以不确定则确认为规则。
+
+- 结论：Phase 3 应增加实现期沟通规则，而不是让代码建议直接覆盖 OpenSpec。
+  - 证据：用户明确要求“不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到”。
+  - 风险：沟通 gate 会暂停执行，但能保护规格真理源。
+  - 用户确认：已确认这是 v3.1 重点。
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-21
@@ -0,0 +1,54 @@
+## Context
+
+SM Flow v3 已经把 `devflow/` 定位为上下文真理源，把 `openspec/changes/<change>/` 定位为执行真理源。当前摩擦来自执行细节：一些需要人类判断的规则没有形成 gate，导致代理可能过早把 Draft OpenSpec 当成最终规格，或者在 Phase 3 中用代码侧发现直接覆盖原设计。
+
+本次改造的对象是 skill 协议本身，主要文件位于 `.agents/skills/sm-flow/`，历史说明位于 `skill-workbench/docs/sm-flow/workflow.md`。用户提供的问题记录位于 `skill-workbench/docs/sm-flow/使用问题.md`。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让 v3.1 明确“文档不是越多越好”：devflow 记录上下文、证据、决策和验收，OpenSpec 记录执行依据。
+- 对接口变更建立分级规则，避免“所有接口变更都独立成文档”和“接口影响没人记录”两个极端。
+- 引入 Draft / Committed OpenSpec，允许 Phase 1 先形成讨论对象，但禁止未提交的草稿直接进入 Phase 3。
+- 为 devflow 增加索引入口和固定检索顺序，解决项目档案增长后的定位问题。
+- 在 Phase 3 增加实现期沟通和冲突分类规则，避免把用户质疑、测试失败或代码建议直接当作新规格。
+
+**Non-Goals:**
+- 不重写 OpenSpec CLI 或 `.claude/skills/openspec-*`。
+- 不改业务代码或知识索引功能。
+- 不把 devflow 重新提升为执行真理源。
+- 不强制每次接口变更都创建独立接口文档。
+
+## Decisions
+
+1. **Draft / Committed OpenSpec 分离**
+   - 决策：Phase 1 产物称为 Draft OpenSpec；Phase 2 和 Phase 2.5 后进入新增的 Phase 2.9 Commit OpenSpec，只有通过提交检查的 OpenSpec 才能进入 Phase 3。
+   - 原因：完全推迟 OpenSpec 会缺少讨论对象；完全信任 Phase 1 初稿又会让 grill 后返工显得像异常。草稿/提交分离把返工变成正常流程。
+   - 替代方案：把 grill 放到 propose 前。拒绝原因是缺少结构化规格草稿时，澄清容易停留在对话层，难以精确回写 proposal/specs/tasks。
+
+2. **接口影响分级，而不是固定独立文档**
+   - 决策：所有接口变更都必须有接口影响记录；只有 L3/L4 级别才必须独立产出接口文档。
+   - 原因：接口变更需要可追踪，但低风险内部接口不应制造额外文档负担。
+   - 替代方案：凡接口变更都新增接口文档。拒绝原因是会让 micro/standard 变更过重，增加文档重复和漂移。
+
+3. **devflow 通过索引和检索顺序控制增长**
+   - 决策：新增或维护 `devflow/index.md`，并规定 Phase 0.5 的检索顺序为 `devflow/index.md`、`devflow/glossary/CONTEXT.md`、相关项目 brief/acceptance/ADR、compound knowledge。
+   - 原因：devflow 的长期价值来自可回溯；没有索引时，文档越多越像一片温柔但很黏的沼泽。
+   - 替代方案：每次用全文搜索全量扫。拒绝原因是成本随项目数增长，且容易抓到无关历史。
+
+4. **Phase 3 冲突先分类，再执行**
+   - 决策：实现阶段遇到用户质疑、代码建议、测试失败或新事实与 OpenSpec 冲突时，必须分类为实现偏差、规格遗漏、设计冲突或用户变更。
+   - 原因：Phase 3 的职责是执行已提交规格，不是把所有新输入立即吸收成代码改动。
+   - 替代方案：让代理自行判断并继续。拒绝原因是会破坏 OpenSpec 的执行真理源地位。
+
+5. **子 skill 绑定能力契约**
+   - 决策：文档应表达 `openspec-propose`、`openspec-apply-change` 等能力名和调用优先级；`.claude/skills/...` 是一个实现路径，不是唯一前提。
+   - 原因：同一流程应能迁移到 Codex、Claude 或其他代理环境。
+   - 替代方案：固定 Claude 路径。拒绝原因是兼容性弱，且与当前 `.agents/skills/` 运行方式不匹配。
+
+## Risks / Trade-offs
+
+- Draft / Committed OpenSpec 增加一个 Phase 2.9 gate → 用固定检查清单控制成本，避免变成新一轮大文档。
+- 接口影响分级可能被代理误判 → 把分级阈值写成可观察条件，并要求不确定时向用户确认。
+- `devflow/index.md` 需要维护 → Phase 4 回填时把索引更新列为默认动作，减少遗忘。
+- Phase 3 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。
@@ -0,0 +1,34 @@
+## Why
+
+SM Flow v3 已经确立了 OpenSpec-first / Devflow-assisted 的主从关系，但实际使用中仍存在四类摩擦：接口变更文档粒度不清、propose 后再 grill 导致返工、devflow 增长后上下文定位变慢、实现阶段发现设计冲突时容易被代码建议牵着走。
+
+这次 v3.1 改造要把这些摩擦固化为可执行规则，让代理在生成规格、澄清需求、执行 apply 和回填 devflow 时有明确 gate，而不是靠临场判断。
+
+## What Changes
+
+- 增加接口影响分级规则：所有接口变更都必须记录影响，只有达到跨团队、外部契约或破坏性变更阈值时才独立产出接口文档。
+- 增加 OpenSpec 草稿/提交分离：Phase 1 生成 Draft OpenSpec，Phase 2/2.5 澄清和审计后通过 Phase 2.9 提交为 Phase 3 的执行依据。
+- 增加 devflow 上下文定位规则：通过 `devflow/index.md`、项目 `brief.md` 和固定检索顺序减少全量翻阅。
+- 增加实现期冲突处理规则：Phase 3 中用户质疑、测试失败、代码发现和 OpenSpec 冲突时，必须先分类再继续执行。
+- 增加 Phase 3 前 OpenSpec 可执行性检查，确保 proposal/design/specs/tasks、接口影响、未解决用户问题和 devflow 冲突都达标。
+- 调整子 skill 兼容规则：把流程绑定到能力契约，而不是绑定到 Claude 路径；Claude skill 文件只是一个可用实现。
+- 更新 sm-flow skill 本体、phase contracts、fallbacks、templates 和工作流说明文档。
+
+## Capabilities
+
+### New Capabilities
+- `sm-flow-interface-impact`: 定义接口影响分级、接口影响记录和独立接口文档的触发条件。
+- `sm-flow-commit-gate`: 定义 Draft OpenSpec、Committed OpenSpec、Phase 2.9 提交检查和 Phase 3 前可执行性 gate。
+- `sm-flow-context-indexing`: 定义 devflow 上下文索引和固定检索顺序。
+- `sm-flow-apply-conflict-handling`: 定义 Phase 3 实现期冲突分类、用户确认和 OpenSpec 回写规则。
+
+### Modified Capabilities
+<!-- 没有已归档的 openspec/specs 需要修改；当前仓库尚未建立全局 specs 目录。 -->
+
+## Impact
+
+- 修改 `.agents/skills/sm-flow/SKILL.md`。
+- 修改 `.agents/skills/sm-flow/references/phase-contracts.md`、`fallbacks.md`、`templates.md`。
+- 可能新增 `devflow/index.md` 作为长期上下文索引入口。
+- 更新 `skill-workbench/docs/sm-flow/workflow.md`，记录 v3.1 的最终设计。
+- 不修改业务代码，不改变 `knowledge/` 索引功能。
@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: Phase 3 classifies implementation-time conflicts
+SM Flow SHALL classify implementation-time conflicts before changing code or OpenSpec.
+
+#### Scenario: User challenges implementation during apply
+- **WHEN** the user questions or changes implementation behavior during Phase 3 and the request conflicts with Committed OpenSpec
+- **THEN** the flow classifies the issue as implementation deviation, spec omission, design conflict, or user scope change before continuing
+
+#### Scenario: Code suggests a different approach
+- **WHEN** code inspection, tests, or runtime behavior suggests a different approach than Committed OpenSpec
+- **THEN** the flow reports the evidence and classification instead of silently accepting the code-side suggestion
+
+#### Scenario: Conflict is implementation deviation
+- **WHEN** Committed OpenSpec remains correct and implementation diverges from proposal, design, specs, or tasks
+- **THEN** the flow classifies the issue as implementation deviation and fixes the code without changing executable OpenSpec except task status or acceptance notes
+
+#### Scenario: Conflict is spec omission
+- **WHEN** Committed OpenSpec lacks a real boundary, behavior, validation rule, interface impact, or acceptance case discovered during implementation
+- **THEN** the flow classifies the issue as spec omission and returns to OpenSpec repair before continuing apply
+
+#### Scenario: Conflict is design conflict
+- **WHEN** Committed OpenSpec conflicts with architecture, ADR, historical acceptance, data ownership, lifecycle, or module boundaries
+- **THEN** the flow classifies the issue as design conflict, pauses implementation, reports the conflict, and asks the user to confirm the design direction
+
+#### Scenario: Conflict is user scope change
+- **WHEN** the user changes the goal, scope, priority, acceptance expectation, or risk tolerance during implementation
+- **THEN** the flow classifies the issue as user scope change and updates proposal, specs, and tasks before continuing
+
+### Requirement: Spec-affecting conflicts return to OpenSpec repair
+SM Flow SHALL repair OpenSpec before continuing when implementation-time conflicts affect the executable specification.
+
+#### Scenario: Conflict is a spec omission or design conflict
+- **WHEN** a Phase 3 conflict changes scope, externally observable behavior, interface compatibility, architecture decisions, or task slicing
+- **THEN** the flow pauses apply, obtains required user confirmation, updates proposal/design/specs/tasks, reruns the commit gate, and only then resumes Phase 3
+
+#### Scenario: Conflict is implementation deviation
+- **WHEN** the committed specification is still correct and the code diverges from it
+- **THEN** the flow fixes the implementation without changing OpenSpec except for task status or acceptance notes
@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: OpenSpec drafts are not executable
+SM Flow SHALL distinguish Draft OpenSpec from Committed OpenSpec.
+
+#### Scenario: Phase 1 proposal created
+- **WHEN** Phase 1 creates or updates proposal, design, specs, and tasks
+- **THEN** the flow treats those artifacts as Draft OpenSpec until Phase 2, Phase 2.5, and Phase 2.9 checks are complete
+
+#### Scenario: Draft has unresolved questions
+- **WHEN** Draft OpenSpec contains unresolved user-interview questions, unreported evidence-driven conclusions, architecture conflicts, or unrecorded interface impact
+- **THEN** the flow SHALL NOT enter Phase 3
+
+### Requirement: Phase 2.9 commits executable OpenSpec
+SM Flow SHALL include a Phase 2.9 Commit OpenSpec gate before Phase 3.
+
+#### Scenario: Commit gate passes
+- **WHEN** proposal explains scope and non-goals, design captures implementation constraints, specs describe observable behavior, tasks are executable vertical slices, interface impact is recorded, and devflow conflicts are resolved
+- **THEN** the flow marks the OpenSpec change as Committed OpenSpec and may ask the user to proceed to Phase 3
+
+#### Scenario: Commit gate fails
+- **WHEN** any required executable OpenSpec condition is missing
+- **THEN** the flow returns to Phase 1, Phase 2, or Phase 2.5 to repair the missing artifact before implementation
+
+### Requirement: Grill questions require explicit human confirmation
+SM Flow SHALL treat Phase 2 grill as a human-in-the-loop process that requires explicit user confirmation for user-interview questions.
+
+#### Scenario: User-interview grill question is asked
+- **WHEN** Phase 2 raises a user-interview question about terminology, scope, acceptance, risk, priority, or product preference
+- **THEN** the flow asks exactly one question, waits for the user's answer, records the answer, and only then continues to the next user-interview question
+
+#### Scenario: Grill confirmation is missing
+- **WHEN** a user-interview question has no explicit user answer
+- **THEN** the flow SHALL NOT mark the question resolved, SHALL NOT commit OpenSpec, and SHALL NOT enter Phase 3
+
+### Requirement: Grill confirmation does not authorize apply
+SM Flow SHALL distinguish confirmation of an individual grill decision from authorization to enter Phase 3.
+
+#### Scenario: User confirms a grill decision
+- **WHEN** the user answers a Phase 2 user-interview question with confirmation such as "可以", "确认", or equivalent
+- **THEN** the flow records that decision and updates OpenSpec/devflow, but SHALL NOT treat the answer as authorization to modify execution target files
+
+#### Scenario: OpenSpec has been updated after grill
+- **WHEN** Phase 2 or Phase 2.5 findings have been written back to proposal, design, specs, or tasks
+- **THEN** the flow stops at Phase 2.9, reports the Committed OpenSpec check result, and waits for explicit user authorization to enter Phase 3
+
+#### Scenario: Apply authorization is missing
+- **WHEN** the user has not explicitly said to enter apply, start implementation, execute the changes, continue Phase 3, or equivalent
+- **THEN** the flow may update OpenSpec and devflow decision records, but SHALL NOT modify execution target files
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Devflow context lookup uses an index-first strategy
+SM Flow SHALL use a stable index-first devflow lookup order to find relevant context.
+
+#### Scenario: Phase 0.5 starts
+- **WHEN** Phase 0.5 collects devflow context
+- **THEN** the flow checks `devflow/index.md` first, then `devflow/glossary/CONTEXT.md`, then related project brief/acceptance/ADR files, then `devflow/compound/`
+
+#### Scenario: Index is missing during lookup
+- **WHEN** `devflow/index.md` does not exist
+- **THEN** the flow initializes a lightweight index from known project directories, falls back to targeted search for the current lookup, and records that the index was bootstrapped
+
+### Requirement: Phase 4 maintains devflow index
+SM Flow SHALL update devflow index metadata during Phase 4 when a project archive is created or updated.
+
+#### Scenario: Project is backfilled
+- **WHEN** Phase 4 creates or updates `devflow/projects/YYYY-MM-DD-{slug}/`
+- **THEN** the flow updates `devflow/index.md` with date, slug, domain, keywords, related OpenSpec change, and status
+
+#### Scenario: Phase 4 completes without index update
+- **WHEN** Phase 4 has created or updated project backfill files but has not updated `devflow/index.md`
+- **THEN** the flow is incomplete and must update the index before reporting completion
@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Interface changes have impact records
+SM Flow SHALL require every interface-related change to record interface impact before Phase 3.
+
+#### Scenario: Internal interface field changes
+- **WHEN** a change adds, removes, renames, or changes the semantics of a field, DTO, service method, event, API, callback, database contract, or command contract
+- **THEN** the flow records the affected interface, affected consumers, compatibility expectation, and validation method in OpenSpec design/specs/tasks or devflow evidence/decisions
+
+#### Scenario: Interface uncertainty
+- **WHEN** the agent cannot determine whether a change affects an interface contract
+- **THEN** the flow treats it as an interface-impact question and asks for confirmation before Phase 3
+
+#### Scenario: Internal decision logic changes observable behavior
+- **WHEN** a change modifies internal decision logic inside an interface and the result can change returned data, status, error code, permission result, validation result, ordering, filtering, idempotency, timing, or side effects
+- **THEN** the flow treats the change as interface impact even if the interface shape and field names are unchanged
+
+### Requirement: Interface documentation is level-gated
+SM Flow SHALL create an independent interface document only when the interface impact level requires it.
+
+#### Scenario: Low-risk internal interface change
+- **WHEN** an interface change is limited to internal implementation or an internal module boundary and has no external consumers
+- **THEN** the flow records the interface impact inline without requiring a standalone interface document
+
+#### Scenario: External or breaking interface change
+- **WHEN** an interface change affects external APIs, SDKs, callbacks, events, database contracts, cross-team consumers, or breaks backward compatibility
+- **THEN** the flow requires a standalone interface document or equivalent explicit section covering consumers, compatibility, migration, rollback, and validation
+
+### Requirement: Interface impact levels use risk-based classification
+SM Flow SHALL classify interface impact by consumer boundary, contract semantics, and compatibility risk.
+
+#### Scenario: L1 internal implementation
+- **WHEN** a change does not alter any consumer-visible interface shape, field, status, error, data range, ordering, permission result, state transition, side effect, or documented behavior
+- **THEN** the flow classifies it as L1 and records validation in tasks or acceptance without requiring interface impact documentation
+
+#### Scenario: L2 internal interface
+- **WHEN** a change affects internal DTOs, service methods, internal events, internal RPC, or internal decision logic and all consumers are inside the same implementation scope
+- **THEN** the flow classifies it as L2 and records interface impact inline
+
+#### Scenario: L3 collaboration interface
+- **WHEN** a change affects other modules, services, frontend callers, external systems, cross-team consumers, database contracts, events, callbacks, or SDK users
+- **THEN** the flow classifies it as L3 and requires a standalone interface document or equivalent explicit section
+
+#### Scenario: L4 breaking interface
+- **WHEN** old consumers can fail, receive less data, receive more data, observe different statuses or errors, require migration, require rollback, or lose backward compatibility
+- **THEN** the flow classifies it as L4 and requires standalone interface documentation plus migration and rollback notes
@@ -0,0 +1,31 @@
+## 1. OpenSpec Commit Gate
+
+- [x] 1.1 Update `.agents/skills/sm-flow/SKILL.md` to describe Draft OpenSpec, Committed OpenSpec, Phase 2.9, and the Phase 3 executable gate.
+- [x] 1.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with Phase 2.9 entry/action/output/exit criteria.
+- [x] 1.3 Add Phase 3 preflight checks for unresolved user-interview questions, interface impact, devflow conflicts, and executable task/spec quality.
+- [x] 1.4 Require Phase 2 grill user-interview questions to wait for explicit user confirmation before they can be marked resolved.
+- [x] 1.5 Require explicit Phase 3 apply authorization after Phase 2.9; individual grill confirmations must not authorize execution target file changes.
+
+## 2. Interface Impact Rules
+
+- [x] 2.1 Add interface impact level definitions and inline-vs-standalone documentation rules to the sm-flow protocol.
+- [x] 2.2 Add an interface impact template to `.agents/skills/sm-flow/references/templates.md`.
+- [x] 2.3 Update Phase 1.5 / Phase 2 checks so interface changes are identified before Phase 3.
+
+## 3. Devflow Context Indexing
+
+- [x] 3.1 Add devflow index lookup order to Phase 0.5.
+- [x] 3.2 Create or update `devflow/index.md` with existing project entries.
+- [x] 3.3 Update Phase 4 rules so future project backfills maintain the index.
+
+## 4. Apply Conflict Handling
+
+- [x] 4.1 Add Phase 3 implementation-time conflict classification rules.
+- [x] 4.2 Update `.agents/skills/sm-flow/references/fallbacks.md` so execution fallback pauses and repairs OpenSpec for spec-affecting conflicts.
+- [x] 4.3 Ensure conflict classifications are recorded in devflow decisions or acceptance notes.
+
+## 5. Compatibility and Documentation
+
+- [x] 5.1 Reword sub-skill compatibility rules to bind to capability contracts first and implementation paths second.
+- [x] 5.2 Update `skill-workbench/docs/sm-flow/workflow.md` with the final v3.1 design.
+- [x] 5.3 Run OpenSpec status checks and text searches to verify the new terms are consistently documented.
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
@@ -378,6 +378,98 @@ Phase 4    回填 devflow，并确认是否 archive

 `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：
+
+```text
+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` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
+
+单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
+
+### 接口影响分级
+
+v3.1 区分“接口影响记录”和“独立接口文档”：
+
+- 所有接口变更都必须记录影响范围。
+- 只有 L3/L4 才强制独立接口文档或等价独立章节。
+
+分级规则：
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
+| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
+| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
+| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |
+
+接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。
+
+### Devflow Index
+
+`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：
+
+```text
+devflow/index.md
+devflow/glossary/CONTEXT.md
+相关项目 brief / acceptance / ADR
+devflow/compound/
+```
+
+Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
+
+### 实现期冲突处理
+
+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 或其他代理环境中迁移，而不会被某个固定目录锁死。
+



@@ -0,0 +1,8 @@
+1. 如果涉及接口，需要额外产出一份影响接口范围文档
+	1. ❯ 只要涉及到接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中 
+2. 涉及接口变更，需要产出一份接口文档
+3. 顺序问题，目前的顺序是propose之后在，生成了task、design之后，再用grill去澄清需求，这样当澄清完需求后，又得回去更新task、design、proposal等文档，现在的流程，是propose之后，再通过to-prd，生成devflow的产物，然后再grill来更新，哪种设计更合理？
+4. 如果devflow数量多了，如何快速定位需要的上下文
+5. 子skill现在是固定了claude，要考虑兼容情况
+6. 当在开发阶段，我发起质疑或者修改，和原来设计冲突时，不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到，要提出反馈
+	1. 可能需要加多一个步骤，apply实施过程中的沟通？
@@ -1,4 +1,4 @@
---
+---
 name: sm-flow
 description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
 ---
@@ -17,6 +17,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
 - 代码是实现结果：只能在执行真理源足够明确后修改。
 - 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
+- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
+- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。

 ## 核心规则

@@ -25,16 +27,39 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
 - devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
 - 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
 - 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
+- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
 - `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
 - `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
+- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
+- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
+- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
+- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
 - 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
 - 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
+- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
 - Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
 - 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
+- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
 - fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。

+## 接口影响分级
+
+接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
+
+| 级别 | 判断条件 | 产物要求 |
+| --- | --- | --- |
+| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
+| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
+| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
+| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
+
+判断策略：
+
+- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
+- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
+- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
+- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
+
 ## 首次加载

 执行前只读取当前任务需要的 reference 文件：
@@ -59,8 +84,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
   - `devflow/reference/`
 3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
 4. 检查 OpenSpec 和子 skill 是否可用：
-   - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
-   - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
+   - OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
+   - 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
 5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。

 ## 项目标识
@@ -101,13 +126,14 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
 ## 阶段总览

 1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
-2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
-3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
+2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
+3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
 4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
 5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
 6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
-7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
-8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
+7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
+8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
+9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。

 每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。

@@ -117,6 +143,7 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的

 - Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
 - Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
+- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
 - Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
 - Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。

@@ -17,6 +17,10 @@ devflow/projects/YYYY-MM-DD-{slug}/
 - `decisions.md`
 - `acceptance.md`

+同时维护仓库级索引：
+
+- `devflow/index.md`
+
 按需创建以下扩展文件：

 - `prd.md`
@@ -49,6 +53,24 @@ devflow/projects/YYYY-MM-DD-{slug}/
 | diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
 | 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
 | 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
+
+## 索引维护规则
+
+`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
+
+最小字段：
+
+| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
+| --- | --- | --- | --- | --- | --- |
+
+规则：
+
+- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
+- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
+- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
+- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
+- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。

 ## 验收记录规则

@@ -99,6 +121,7 @@ OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 de
 Phase 4 结束时告诉用户：

 - 创建或更新了哪些档案文件。
+- `devflow/index.md` 是否已更新。
 - 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
 - 还剩哪些风险或后续事项。
 - 明确询问：是否现在 archive OpenSpec change？
@@ -34,12 +34,20 @@

 1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
 2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
-3. 修改前先检查现有代码。
-4. 一次实现一个 OpenSpec task 的纵向切片。
-5. 用最窄但有效的命令验证每个切片。
-6. 只有验证通过或明确记录原因后，才更新 task 状态。
-7. 如果失败原因不确定，停止并进入 diagnose。
-8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
+3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
+4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
+5. 修改前先检查现有代码。
+6. 一次实现一个 OpenSpec task 的纵向切片。
+7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
+   - 实现偏差：OpenSpec 正确，代码偏离；修代码。
+   - 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
+   - 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
+   - 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
+8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
+9. 用最窄但有效的命令验证每个切片。
+10. 只有验证通过或明确记录原因后，才更新 task 状态。
+11. 如果失败原因不确定，停止并进入 diagnose。
+12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。

 ## PRD fallback

@@ -28,6 +28,8 @@
 **进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。

 **动作**：
+- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
+- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
 - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
@@ -36,6 +38,7 @@

 **退出条件**：
 - 已形成“OpenSpec 输入上下文摘要”。
+- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
 - 已列出相关 ADR 和不能违反的历史决策。
 - 已列出需要写入或修正 OpenSpec 的上下文点。

@@ -46,7 +49,7 @@

 **进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。

-**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
+**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。

 **动作**：
 - 优先调用 `openspec-propose`。
@@ -64,7 +67,7 @@
 - 关键假设已显式记录在 OpenSpec 或 research 中。

 **输出**：
- OpenSpec proposal、design、specs 和 task list。
+- Draft OpenSpec proposal、design、specs 和 task list。

 **Human checkpoint**：
 - 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
@@ -85,11 +88,16 @@
  - OpenSpec 是否遵守相关 ADR。
  - specs 是否能表达可观察行为。
  - tasks 是否能驱动实现，而不是泛泛描述。
+- 检查是否涉及接口影响：
+  - 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
+  - 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
+  - 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
 - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。

 **退出条件**：
 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
 - OpenSpec 与 PRD/devflow 上下文没有已知冲突。
+- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
 - 所有已知冲突已修正或等待用户决策。

 **输出**：
@@ -110,6 +118,10 @@
  - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
 - 至少覆盖三个维度：术语、边界、验收。
 - 一次只问一个 `user-interview` 问题。
+- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
+- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
+- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
+- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
 - 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
 - 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
 - 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
@@ -118,6 +130,8 @@
 - 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
 - 所有 evidence-driven 结论已向用户汇报。
 - 所有 user-interview 决策已获得用户确认。
+- 没有未解决或代理代确认的 user-interview 问题。
+- 没有未判级或未确认的接口影响问题。
 - 影响实现的结论已回写 OpenSpec。

 **输出**：
@@ -148,14 +162,46 @@

 **Human checkpoint**：
 - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
+- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
+
+## Phase 2.9 — Commit OpenSpec
+
+**进入条件**：
+- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
+- 所有 `user-interview` 问题都已获得用户显式确认。
+- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
+- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
+
+**动作**：
+- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
+- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
+- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
+- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
+- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
+- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
+- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
+
+**退出条件**：
+- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
+- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
+- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
+
+**输出**：
+- Committed OpenSpec 状态说明。
+- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
+
+**Human checkpoint**：
+- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
+- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
+- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。

 ## Phase 3 — OpenSpec apply

 **进入条件**：
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
+- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
+- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
 - devflow 与 OpenSpec 没有未解决冲突。
+- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。

 **显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。

@@ -163,6 +209,12 @@
 - 优先调用 `openspec-apply-change`。
 - 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
 - 按 OpenSpec tasks 的纵向切片实现。
+- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
+  - 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
+  - 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
+  - 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
+  - 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
+- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
 - 当用户要求、行为复杂或回归风险高时使用 TDD。
 - 当测试失败、行为意外或原因不确定时使用 diagnose。
 - 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
@@ -170,6 +222,7 @@

 **退出条件**：
 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
+- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
 - 已运行验证，或记录了未验证原因。
 - 已列出已知限制。

@@ -188,10 +241,12 @@
 - 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
 - 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
 - 如果本次流程产生可复用经验，写入 compound knowledge。
+- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
 - 询问用户是否要 archive OpenSpec change；不要默认执行归档。

 **退出条件**：
 - `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
+- `devflow/index.md` 已包含或更新本项目条目。
 - 用户已被询问是否 archive OpenSpec change。

 **输出**：
@@ -65,6 +65,68 @@
  - 风险接受：{accepted by whom/when}
 ```

+## 接口影响记录模板
+
+```markdown
+# {标题} 接口影响记录
+
+## 分级
+
+- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
+- 判级原因：{why this level}
+- 是否需要独立接口文档：是 / 否
+
+## 变更对象
+
+- 接口/字段/DTO/事件/回调/数据库契约：
+- 判断逻辑变化：
+- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
+
+## 影响范围
+
+- 调用方/消费者：
+- 是否跨模块/跨服务/跨团队：
+- 旧调用方是否需要改动：
+
+## 兼容与迁移
+
+- 是否向后兼容：
+- 迁移/灰度/回滚要求：
+- 风险接受：
+
+## 验收方式
+
+- 如何证明新行为正确：
+- 如何证明旧行为未破坏：
+- 需要用户确认的问题：
+```
+
+## 实现期冲突记录模板
+
+```markdown
+# {标题} 实现期冲突记录
+
+## 冲突摘要
+
+- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
+- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
+- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
+
+## 证据
+
+- OpenSpec 依据：
+- 代码或测试证据：
+- 用户反馈：
+
+## 处理
+
+- 决策：
+- 是否需要用户确认：是 / 否
+- OpenSpec 回写：不需要 / 已回写 / 待回写
+- 代码处理：
+- 验证方式：
+```
+
 ## PRD 模板

 ```markdown
@@ -1,259 +0,0 @@
---
-name: essence
-description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
-metadata:
-  version: "0.5.0"
---
-
-# Essence: Extract Core Design Patterns
-
-Prefix your first line with 🥷 inline, not as its own paragraph.
-
-You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
-
-**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
-
-## Mode Selection
-
-First, check whether an `/explore` result exists:
-
- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
- No `/explore` result → this is an independent launch, default to **Auto-detect**.
-
-Always confirm before proceeding:
-
-| Mode | When | Entry |
-|---|---|---|
-| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
-| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
-| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
-
-### Lens definitions
-
-| Lens | Core question | Guided behavior |
-|---|---|---|
-| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
-| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
-| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
-
-A lens shapes which sources to read and how to frame the output, but does not add separate phases.
-
-### Auto-detect signals
-
-A design is "essence" if it passes 2 or more of these signals:
-
-| Signal | Evidence |
-|---|---|
-| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
-| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
-| Heavily discussed in Issues/PRs | Design decisions debated by community |
-| Unique among similar projects | Competitors don't do it this way |
-| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
-| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
-| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
-| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
-
-**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
-
-If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
-
-## Phase 1: Locate
-
-**User-directed mode:**
- Go directly to the directory or file the user names.
- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
-
-**Auto-detect mode:**
- Scan README, CLAUDE.md, and top-level docs for architecture claims.
- Identify 1-2 standout design directions.
- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
- If user doesn't choose, pick the strongest one and state why.
-
-**Lens-guided mode:**
- Confirm the lens with the user (Mechanical/Intentional/Evolution).
- Frame the search in terms of the lens.
- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
-
-**Output:** 1-2 design directions to analyze + lens confirmation.
-
-**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
-
-## Phase 2: Deep Dive
-
-Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
-
-**For each file:**
- What role does it play in this design?
- What interfaces does it expose?
- How does it connect to other parts of the system?
-
-**Trace the call chain:**
- Start from the entry point that uses this design.
- Follow the flow until you understand the full pattern.
- Stop when you hit boilerplate, config, or test files.
-
-**Output:** Core file list (≤10) + call chain + lens-specific annotations.
-
-**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
-
-## Phase 3: Extract Pattern
-
-Analyze the design at a higher level. Let the lens shape the analysis angle:
- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
-
-**Universal analysis dimensions** (all lenses):
-
- **Problem:** What specific problem does this design solve? What was the pain before?
- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
- **Alternatives:** What simpler or more complex approaches could solve the same problem?
- **Tradeoffs:** Why did the author choose this? What does it give up?
- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
-
-**Output:** Design pattern card (lens-framed).
-
-**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
-
-## Phase 4: Migrate
-
-Make the learning actionable. Let the lens tailor the output:
- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
- **Intentional** → decision framework (checklist for evaluating tradeoffs)
- **Evolution** → migration path (step-by-step refactor plan)
-
-**Universal deliverables** (all lenses):
-
- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
-
-**Output:** Migration example + pitfall list (lens-tailored).
-
-**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
-
-## Phase 5: Self-review
-
-Check the report is honest:
-
-**All modes:**
- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
- [ ] The analysis is deep enough that you could explain it out loud.
- [ ] The migration example captures the core idea, not surface syntax.
- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
-
-**Stall signals (any one → return to relevant phase):**
- Cannot name a file that proves the pattern → back to Phase 2
- Cannot explain why it's better than alternatives → back to Phase 3
- Migration example is over 20 lines → simplify, back to Phase 4
- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
-
-**Output:** Essence report with lens annotation.
-
-## Optional: HTML Card
-
-**Only when the user explicitly requests it.**
-
-Generate an HTML visualization card as a shareable deliverable.
-
-### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
-
-```html
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8">
-  <title>{Project Name} - Essence Report</title>
-  <script src="https://cdn.tailwindcss.com"></script>
-  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
-  <style>
-    /* Same glassmorphism styles as /explore */
-    :root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
-    [data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
-    .glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
-    .pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
-  </style>
-</head>
-<body class="p-8">
-  <nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
-    <span class="font-bold text-xl">💎 {Project Name} 精华</span>
-    <span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
-  </nav>
-  
-  <main class="max-w-4xl mx-auto mt-24 space-y-6">
-    <section class="glass-panel p-6">
-      <h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
-      <p>{one-line description}</p>
-    </section>
-    
-    <section class="glass-panel p-6">
-      <h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
-      <!-- Lens-framed pattern card -->
-    </section>
-    
-    <section class="glass-panel p-6">
-      <h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
-      <pre class="mermaid">{diagram}</pre>
-    </section>
-    
-    <section class="glass-panel p-6">
-      <h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
-      <pre class="pattern-diagram"><code>{code_example}</code></pre>
-      <p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
-    </section>
-  </main>
-  
-  <script>mermaid.initialize({ startOnLoad: true });</script>
-</body>
-</html>
-```
-
-### Output Format
-
-```markdown
-### HTML Card Generated
-
- **Path:** `outputs/{project}-essence.html`
- **Theme:** {modern/ink}
- **Accent Color:** Purple (essence = jewel)
-```
-
-**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
-
---
-
-## Hard Rules
-
- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
- **Stop after the report.** Do not modify the user's project or the target project.
- **HTML is optional.** Do not block analysis on HTML generation.
-
-## Gotchas
-
-| What happened | Rule |
-|---|---|
-| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
-| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
-| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
-| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
-| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
-| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
-| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
-| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
-| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
-
-## Outcome
-
-```
-Essence Report: {project name}
-Lens: mechanical / intentional / evolution
-Design analyzed: {one-line description}
-Files examined: {count}
-Pattern: {pattern name or custom description}
-Migration: {steal-it example, ≤20 lines}
-HTML generated: yes / no
-Status: complete
-```
-
-After the report, stop. No modifications. No follow-ups.
@@ -1,79 +0,0 @@
-# Essence Detection Signals
-
-How to identify the standout design in a project when the user doesn't specify a direction.
-
-## Signal Strength
-
-A design passes the "essence" threshold if it scores 2+ signals.
-
-### Strong Signals (score = 1 each)
-
-| Signal | How to detect | Example |
-|---|---|---|
-| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
-| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
-| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
-| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
-| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
-
-### Objective Signals (score = 1 each, no subjective judgment needed)
-
-| Signal | How to detect | Example |
-|---|---|---|
-| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
-| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
-| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
-
-### Weak Signals (score = 0.5 each)
-
-| Signal | How to detect | Example |
-|---|---|---|
-| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
-| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
-| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
-| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
-
-## Not Signals
-
-These do NOT count as essence:
-
- "Clean code" or "well organized" — that's quality, not design
- "Uses TypeScript" — that's a language choice, not architecture
- "Has good tests" — that's engineering discipline, not design
- "Many stars on the repo" — popularity ≠ design quality
- "Uses the latest framework" — following trends ≠ standing out
- Utility functions — even well-written ones are tools, not designs
-
-## Auto-detect Procedure
-
-When the user says "find the essence":
-
-1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
-2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
-3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
-4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
-5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
-6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
-
-### Example Output Format
-
-```
-Standout designs in {project}:
-
-A) {Design A name} — evidenced by {README claim / file / doc}
-   What it does: {one sentence}
-
-B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
-   What it does: {one sentence}
-
-Which should we dive into? (or I can pick the strongest)
-```
-
-## Failure Modes
-
-| Situation | Response |
-|---|---|
-| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
-| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
-| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
-| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |
@@ -1,87 +0,0 @@
---
-name: explore
-description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching.
-metadata:
-  version: "0.5.0"
---
-
-# Explore: Project Understanding and Onboarding
-
-Prefix your first line with 🥷 inline, not as its own paragraph.
-
-You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start.
-
-`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching.
-
-## Project Type Detection
-
-After the initial scan, classify the target before continuing:
-
-| Type | Signals | What changes |
-|---|---|---|
-| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases |
-| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) |
-| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal |
-
-State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type.
-
-## Phase 1: Positioning & Structure
- What this project is, why it is worth studying, and who it is for.
- Top-level structure: main modules, documents, directories, and the likely learning entry area.
- Tradeoffs vs alternatives when evidence exists.
-
-## Phase 2: Flow
-**Code repositories only.**
- Skip for non-code and template repositories.
- Trace the main runtime or request flow.
- Produce at least one architecture or core-flow diagram.
- Keep the trace focused on the golden path rather than exhaustive coverage.
-
-## Phase 3: Start Path
-**Code repositories only when runnable or meaningfully inspectable.**
- Provide the minimal path to start learning or running the project.
- Give the first command or first inspection step.
- Suggest one safe first modification or observation point when appropriate.
-
-## Phase 4: Core Designs
- Summarize 2-3 core implementations or ideas.
- Keep this at overview depth.
- For each item, include what it is, where it lives, and why it matters.
-
-## Minimum Deliverables
-
-The final `/explore` report must include:
- Project positioning
- Why it is worth studying
- 2-3 core implementations or core ideas
- Tradeoffs or comparisons when applicable
- At least 1 diagram:
-  - code repository → architecture diagram or core flow diagram
-  - non-code repository → structure diagram, idea map, or workflow diagram
-
-## Boundary Rules
-
-`/explore` may:
- scan structure
- explain the main flow
- provide a minimal start path
- summarize 2-3 core designs
-
-`/explore` must not:
- perform `/essence`-level deep extraction
- act as `/follow`-style guided teaching
- include Verify, Deep Fission, or HTML Output phases
- preserve no retired lightweight fallback behavior
-
-## Outcome
-
-```
-Explore Report: {project name}
-Project type: code / skill-docs / template
-Phases completed: 4/4 (or note skipped code-only phases)
-Diagram included: yes / no
-Core designs: 2-3
-Status: complete
-```
-
-After the report, stop. Do not proceed to `/essence` or `/follow` automatically.
@@ -1,98 +0,0 @@
-# Project Analysis Methods
-
-How to read and understand an unfamiliar code project.
-
-## 1. Identify the Entry Point
-
-Every project has a door. Find it first.
-
-### By Language
-
-| Language | Look for |
-|---|---|
-| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
-| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
-| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
-| **Rust** | `src/main.rs` or `src/bin/*.rs` |
-| **Java** | Class with `public static void main(String[] args)` |
-| **C/C++** | `main()` function, conventionally in `src/main.c` |
-| **Swift** | `main.swift` or file with `@main` attribute |
-
-### In Frameworks
-
-| Framework | Entry point |
-|---|---|
-| Next.js | `app/` or `pages/` directory, `next.config.js` |
-| React (Vite) | `src/main.tsx` or `src/main.jsx` |
-| Vue (Vite) | `src/main.ts` or `src/main.js` |
-| Express | File that calls `app.listen()` |
-| FastAPI | File that creates `FastAPI()` instance |
-| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
-| Flask | `app.py` or `app/__init__.py` |
-| Spring Boot | `*Application.java` with `@SpringBootApplication` |
-
-## 2. Judge Project Complexity
-
-Don't over-engineer simple projects. Don't under-analyze complex ones.
-
-### Simple (<50 files, single language)
- Read every source file.
- No need for flow diagrams beyond a simple sequence.
- A light `/explore` pass is probably enough.
-
-### Standard (50-500 files, 1-2 languages)
- Read entry point + core modules + 1-2 feature files.
- Build 1-2 flow diagrams.
- `/explore` is the right level.
-
-### Complex (>500 files, multi-language, monorepo)
- Read entry point + architecture docs + one representative module.
- Use `/essence` to find standout designs, or `/explore` for one package at a time.
- Do NOT try to understand the whole project in one pass.
-
-## 3. Separate Core Code from Scaffolding
-
-Not all files are worth reading.
-
-### Ignore (scaffolding)
- `*.config.js`, `*.config.ts` — configuration, not logic
- `dist/`, `build/`, `out/` — generated output
- `node_modules/`, `vendor/`, `.venv/` — dependencies
- `*.lock`, `yarn.lock`, `go.sum` — lock files
- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
- `test/fixtures/`, `test/data/` — test data
-
-### Read (core)
- Entry point file
- Router/middleware/config handlers
- Model/entity/schema definitions
- Core algorithm or business logic files
- Files referenced most in imports
-
-### Hint: Follow imports
-
-```
-entry file → import A → import B → core logic
-```
-
-Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
-
-## 4. Read Unfamiliar Framework Code
-
-You don't know every framework. That's fine.
-
-### Strategy
-
-1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
-
-2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
-
-3. **Identify the framework's conventions.** Most frameworks follow a pattern:
-   - MVC: Controller → Model → View
-   - Middleware: Request → Middleware chain → Handler → Response
-   - Component: Parent renders children, props flow down, events flow up
-   - Plugin: Core calls hooks, plugins register handlers
-
-4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
-
-5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.
@@ -1,173 +0,0 @@
-# Flow Pattern Library
-
-Common architecture patterns and how to identify them in code.
-
-## MVC / MVVM / MVX
-
-### What it is
-Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel).
-
-### File signatures
-| Pattern | Directories/Files |
-|---|---|
-| **MVC** | `controllers/`, `models/`, `views/` |
-| **MVVM** | `viewmodels/`, `views/`, `models/` |
-| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) |
-
-### Flow
-```
-Request → Controller → Model (data) → View (render) → Response
-```
-
-### Key question
-"Does the file handle data, display, or coordination?" If yes → MVC-family.
-
---
-
-## Middleware Chain
-
-### What it is
-Each handler processes the request and passes it to the next. Like an assembly line.
-
-### File signatures
-| Framework | Indicator |
-|---|---|---|
-| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` |
-| **FastAPI** | `@app.middleware("http")`, `Depends()` |
-| **Next.js** | `middleware.ts` at root or in `app/` |
-| **Gin (Go)** | `router.Use(middleware1, middleware2)` |
-| **Koa** | `app.use(async (ctx, next) => { ... })` |
-
-### Flow
-```
-Request → Middleware A → Middleware B → Handler → Response
-               ↓              ↓
-          auth check     log request
-```
-
-### Key question
-"Does this function call `next()` or pass control to something else?" If yes → middleware.
-
-### Common middleware order
-```
-1. CORS / Security headers
-2. Logging / Request ID
-3. Authentication / Authorization
-4. Body parsing / Validation
-5. Rate limiting
-6. Route handler
-7. Error handler (catches everything above)
-```
-
---
-
-## Plugin / Extension System
-
-### What it is
-Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins.
-
-### File signatures
-| Pattern | Indicator |
-|---|---|
-| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` |
-| **Interface-based** | Abstract class or interface that plugins implement |
-| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention |
-| **VSCode-style** | `contributes` in `package.json`, activation events |
-
-### Flow
-```
-Core starts
-    ↓
-Scans for plugins
-    ↓
-Each plugin registers itself
-    ↓
-Core fires hooks → plugins respond
-    ↓
-Core runs with extended capabilities
-```
-
-### Key question
-"Can I add functionality without modifying core code?" If yes → plugin architecture.
-
---
-
-## Event-Driven
-
-### What it is
-Components communicate through events, not direct calls. Publishers emit, subscribers listen.
-
-### File signatures
-| Pattern | Indicator |
-|---|---|
-| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` |
-| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` |
-| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` |
-| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` |
-| **Signals (Python)** | `@signal.connect`, `signal.send()` |
-
-### Flow
-```
-Component A emits "user.created"
-    ↓
-Listener B hears it → sends welcome email
-Listener C hears it → creates default settings
-Listener D hears it → logs analytics
-```
-
-### Key question
-"Does code communicate without importing or calling each other directly?" If yes → event-driven.
-
---
-
-## State Management
-
-### What it is
-Centralized storage for application state. Components read and update through defined interfaces.
-
-### File signatures
-| Pattern | Indicator |
-|---|---|
-| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` |
-| **Zustand** | `create((set) => ({ ... }))` |
-| **Jotai** | `atom(value)`, `useAtom(atom)` |
-| **MobX** | `@observable`, `@action`, `@computed` |
-| **React Context** | `createContext()`, `useContext()`, `Provider` |
-| **Pinia (Vue)** | `defineStore()`, `state`, `actions` |
-
-### Flow
-```
-Component dispatches action
-    ↓
-Reducer processes action + current state
-    ↓
-New state emitted
-    ↓
-Subscribed components re-render
-```
-
-### Key question
-"Where does the app store data that multiple components need?" If it's a single store → state management pattern.
-
---
-
-## Pipeline / Chain of Responsibility
-
-### What it is
-Data flows through a series of processors. Each processor transforms the data and passes it on.
-
-### File signatures
-| Pattern | Indicator |
-|---|---|
-| **Stream processing** | `.pipe(transform1).pipe(transform2)` |
-| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate |
-| **Data pipeline** | `input → transform → validate → output` |
-| **Makefile** | Target depends on prerequisites, each is a step |
-
-### Flow
-```
-Raw input → Tokenizer → Parser → Transformer → Generator → Output
-```
-
-### Key question
-"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline.
@@ -1,120 +0,0 @@
-#!/usr/bin/env bash
-# Collect project structure for /explore analysis.
-# Usage: Run from project root, or pass project path as argument.
-# Output: Structured text with directory tree, file counts, language distribution.
-
-set -euo pipefail
-
-PROJECT_DIR="${1:-.}"
-cd "$PROJECT_DIR"
-
-echo "=== PROJECT STRUCTURE ==="
-echo ""
-
-# Directory tree (depth 3, exclude common noise)
-echo "--- Directory Tree (depth 3) ---"
-if command -v tree &>/dev/null; then
-    tree -L 3 \
-        -I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \
-        --dirsfirst
-elif command -v find &>/dev/null; then
-    find . -maxdepth 3 \
-        -not -path "./.git/*" \
-        -not -path "./node_modules/*" \
-        -not -path "./vendor/*" \
-        -not -path "./dist/*" \
-        -not -path "./build/*" \
-        -not -path "./out/*" \
-        -not -path "./.venv/*" \
-        -not -path "*/__pycache__/*" \
-        -not -path "*/.egg-info/*" \
-        -not -path "*/coverage/*" \
-        -not -path "./.nyc_output/*" \
-        -print | head -100 | sort
-fi
-
-echo ""
-echo "=== FILE COUNTS ==="
-echo ""
-
-# Count files by extension (top 10)
-echo "--- Top 10 File Types ---"
-find . -type f \
-    -not -path "./.git/*" \
-    -not -path "./node_modules/*" \
-    -not -path "./vendor/*" \
-    -not -path "./dist/*" \
-    -not -path "./build/*" \
-    -not -path "./out/*" \
-    -not -path "./.venv/*" \
-    -not -path "*/__pycache__/*" \
-    -printf '%f\n' | \
-    sed 's/.*\.//' | \
-    grep -v '^\.[^/]*$' | \
-    sort | uniq -c | sort -rn | head -10
-
-echo ""
-echo "=== TOTAL FILE COUNT ==="
-echo ""
-
-# Total files (excluding noise)
-total=$(find . -type f \
-    -not -path "./.git/*" \
-    -not -path "./node_modules/*" \
-    -not -path "./vendor/*" \
-    -not -path "./dist/*" \
-    -not -path "./build/*" \
-    -not -path "./out/*" \
-    -not -path "./.venv/*" \
-    | wc -l)
-echo "Total source files: $total"
-
-echo ""
-echo "=== DEPENDENCY FILES ==="
-echo ""
-
-# List dependency declaration files found
-for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do
-    if [ -f "$dep_file" ]; then
-        echo "FOUND: $dep_file"
-    fi
-done
-
-# Check for workspace/monorepo configs
-echo ""
-echo "=== WORKSPACE / MONOREPO ==="
-echo ""
-
-for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do
-    if [ -f "$ws_file" ]; then
-        echo "FOUND: $ws_file"
-    fi
-done
-
-# Check Cargo.toml for workspace
-if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then
-    echo "FOUND: Cargo.toml [workspace]"
-fi
-
-echo ""
-echo "=== ENTRY POINTS ==="
-echo ""
-
-# Try to identify entry points
-if [ -f "package.json" ]; then
-    main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "")
-    bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "")
-    dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "")
-    [ -n "$main" ] && echo "package.json main: $main"
-    [ -n "$bin" ] && echo "package.json bin: $bin"
-    [ -n "$dev" ] && echo "package.json dev/start: $dev"
-fi
-
-for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do
-    if [ -f "$entry" ]; then
-        echo "FOUND: $entry"
-    fi
-done
-
-echo ""
-echo "=== COLLECTED ==="
@@ -1,101 +0,0 @@
---
-name: follow
-description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction.
-metadata:
-  version: "0.5.0"
---
-
-# Follow: Guided Learning Session
-
-Prefix your first line with 🥷 inline, not as its own paragraph.
-
-You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it.
-
-`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result.
-
-## Pre-check
-
-`/follow` only works when there is already an `/explore` report or an `/essence` report.
-
- `/explore` report exists → use it as the main learning path
- `/essence` report exists → use it for design-focused guided study
- Neither exists → refuse clearly
-
-Refusal behavior:
-"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first."
-
-Load the existing report before continuing.
-
-## Mode Selection
-
-After the pre-check, select one mode based on the prerequisite report:
-
- From `/explore` + code repository → default **Runnable**
- From `/explore` + non-code repository → force **Reader**
- From `/essence` → default **Reader** (user is in design-analysis state)
-
-| Mode | When | Entry |
-|---|---|---|
-| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution |
-| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading |
-
-State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide.
-
-## Teaching Interaction Rules
-
-`/follow` must teach by guidance, not by dumping answers:
- explain the purpose of the current step first
- give the user an observation point or action point
- ask the user to predict, try, or explain before revealing the answer
- then reveal, correct, or deepen the explanation
- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to
-
-## Runnable Check
-
-Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project):
- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable.
- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why.
- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists.
- Do not introduce a third mode.
-
-## Runnable Mode Flow
-1. Confirm environment and prerequisites.
-2. Let the user run the project.
-3. Let the user make one safe change.
-4. Walk the main flow together.
-5. Give one small exercise.
-6. Review what they learned.
-
-## Reader Mode Flow
-1. Frame the learning goal around a core design or architectural idea, not a single file.
-2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff.
-3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?").
-4. Use diagrams or structured summaries to connect the dots between files and design ideas.
-5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere.
-6. Review what they learned.
-
-## Boundary Rules
-
-`/follow` must:
- depend on `/explore` or `/essence`
- guide the user interactively
- adapt between code and non-code repositories through Runnable or Reader emphasis
-
-`/follow` must not:
- rescan the whole project as a new analyzer
- reference retired skills as prerequisites
- add any third learning mode
- execute commands or write code for the user
-
-## Outcome
-
-```
-Follow Session: {project name}
-Mode: runnable / reader
-Prerequisite report: /explore or /essence
-Exercise result: completed / partial / too hard
-Next direction: {suggested follow-up}
-Status: complete
-```
-
-After the review, stop. Ask whether the user wants another exercise or wants to end the session.
@@ -1,113 +0,0 @@
-# Environment Detection Rules
-
-How to detect the runtime environment and guide the user through setup in `/follow`.
-
-## Language Detection from Config
-
-Check these files in order. The first match is the primary language.
-
-| Config file | Language | Runtime check | Install command |
-|---|---|---|---|
-| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer |
-| `pyproject.toml` | Python | `python --version` | pyenv or python.org |
-| `go.mod` | Go | `go version` | golang.org/dl |
-| `Cargo.toml` | Rust | `rustc --version` | rustup |
-| `pom.xml` | Java | `java -version` | SDKMAN or official |
-| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN |
-| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv |
-| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK |
-| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager |
-| `swift package.json` | Swift | `swift --version` | Xcode or swift.org |
-
-## Dependency Installation
-
-Once language is detected, guide the user:
-
-### JavaScript/TypeScript
-```bash
-# Check which package manager is used
-if [ -f "yarn.lock" ]; then yarn install
-elif [ -f "pnpm-lock.yaml" ]; then pnpm install
-elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install
-else npm install
-fi
-```
-
-### Python
-```bash
-# Modern Python projects
-pip install -e .
-# Or with requirements
-pip install -r requirements.txt
-# Or with poetry
-poetry install
-# Or with uv
-uv pip install -r requirements.txt
-```
-
-### Go
-```bash
-go mod download
-```
-
-### Rust
-```bash
-cargo build
-```
-
-### Java (Maven)
-```bash
-mvn install
-```
-
-### Java (Gradle)
-```bash
-./gradlew build
-# or
-gradle build
-```
-
-## Run Command Detection
-
-How to start the project:
-
-| Source | Command |
-|---|---|
-| `package.json` → `scripts.dev` | `npm run dev` |
-| `package.json` → `scripts.start` | `npm start` |
-| `Makefile` → `dev` target | `make dev` |
-| `Makefile` → `run` target | `make run` |
-| `pyproject.toml` (Poetry) | `poetry run python main.py` |
-| `go.mod` → `package main` | `go run main.go` |
-| `Cargo.toml` → `[[bin]]` | `cargo run` |
-| `docker-compose.yml` exists | `docker-compose up` |
-| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` |
-
-## Common Environment Issues
-
-| Error | Cause | Fix |
-|---|---|---|
-| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) |
-| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` |
-| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo |
-| `ENOENT: no such file` | Wrong working directory | `cd` to project root first |
-| `port already in use` | Another process on same port | Kill the process or use different port |
-| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` |
-| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` |
-| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement |
-| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` |
-
-## Detection Script for /follow
-
-```bash
-# Quick environment check
-echo "=== Environment ==="
-node --version 2>/dev/null || echo "Node.js: not installed"
-python --version 2>/dev/null || echo "Python: not installed"
-go version 2>/dev/null || echo "Go: not installed"
-rustc --version 2>/dev/null || echo "Rust: not installed"
-java -version 2>/dev/null || echo "Java: not installed"
-echo "PWD: $(pwd)"
-```
-
-Run this at the start of `/follow` Step 1 to understand what's available.
Author	SHA1	Message	Date
zhuyongxin	54741dd6c0	clean obsolete skill workspace files	2026-05-21 20:17:15 +08:00
zhuyongxin	6a5520db33	upgrade sm-flow v3.1 workflow	2026-05-21 19:55:23 +08:00