From 6a5520db336cfdf7c11cd7edd8455d6d7bc097bc Mon Sep 17 00:00:00 2001 From: zhuyongxin Date: Thu, 21 May 2026 19:55:23 +0800 Subject: [PATCH] upgrade sm-flow v3.1 workflow --- .agents/skills/sm-flow/SKILL.md | 45 +++++++-- .../sm-flow/references/archive-rules.md | 23 +++++ .../skills/sm-flow/references/fallbacks.md | 20 ++-- .../sm-flow/references/phase-contracts.md | 65 ++++++++++++- .../skills/sm-flow/references/templates.md | 62 +++++++++++++ devflow/index.md | 11 +++ .../acceptance.md | 59 ++++++++++++ .../2026-05-21-sm-flow-v3-1-upgrade/brief.md | 30 ++++++ .../decisions.md | 39 ++++++++ .../evidence.md | 28 ++++++ .../.openspec.yaml | 2 + .../2026-05-21-sm-flow-v3-1-upgrade/design.md | 54 +++++++++++ .../proposal.md | 34 +++++++ .../sm-flow-apply-conflict-handling/spec.md | 39 ++++++++ .../specs/sm-flow-commit-gate/spec.md | 49 ++++++++++ .../specs/sm-flow-context-indexing/spec.md | 23 +++++ .../specs/sm-flow-interface-impact/spec.md | 46 ++++++++++ .../2026-05-21-sm-flow-v3-1-upgrade/tasks.md | 31 +++++++ openspec/config.yaml | 20 ++++ skill-workbench/docs/sm-flow/workflow.md | 92 +++++++++++++++++++ skill-workbench/docs/sm-flow/使用问题.md | 8 ++ .../generated-skills/sm-flow/SKILL.md | 45 +++++++-- .../sm-flow/references/archive-rules.md | 23 +++++ .../sm-flow/references/fallbacks.md | 20 ++-- .../sm-flow/references/phase-contracts.md | 65 ++++++++++++- .../sm-flow/references/templates.md | 62 +++++++++++++ 26 files changed, 955 insertions(+), 40 deletions(-) create mode 100644 devflow/index.md create mode 100644 devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/acceptance.md create mode 100644 devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/brief.md create mode 100644 devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md create mode 100644 devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/evidence.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/.openspec.yaml create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/design.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/proposal.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-apply-conflict-handling/spec.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-commit-gate/spec.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-context-indexing/spec.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md create mode 100644 openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/tasks.md create mode 100644 openspec/config.yaml create mode 100644 skill-workbench/docs/sm-flow/使用问题.md diff --git a/.agents/skills/sm-flow/SKILL.md b/.agents/skills/sm-flow/SKILL.md index d22e598..b6fdd10 100644 --- a/.agents/skills/sm-flow/SKILL.md +++ b/.agents/skills/sm-flow/SKILL.md @@ -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//` 是执行真理源：当前变更的 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 产物链接和是否归档。 diff --git a/.agents/skills/sm-flow/references/archive-rules.md b/.agents/skills/sm-flow/references/archive-rules.md index a013bfb..4c6f6e5 100644 --- a/.agents/skills/sm-flow/references/archive-rules.md +++ b/.agents/skills/sm-flow/references/archive-rules.md @@ -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？ diff --git a/.agents/skills/sm-flow/references/fallbacks.md b/.agents/skills/sm-flow/references/fallbacks.md index 64000fb..7ef272c 100644 --- a/.agents/skills/sm-flow/references/fallbacks.md +++ b/.agents/skills/sm-flow/references/fallbacks.md @@ -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 diff --git a/.agents/skills/sm-flow/references/phase-contracts.md b/.agents/skills/sm-flow/references/phase-contracts.md index 0b5b7f6..0b04821 100644 --- a/.agents/skills/sm-flow/references/phase-contracts.md +++ b/.agents/skills/sm-flow/references/phase-contracts.md @@ -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//` 中 proposal/design/specs/tasks 已达到可执行状态。 -- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。 +- `openspec/changes//` 中 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。 **输出**： diff --git a/.agents/skills/sm-flow/references/templates.md b/.agents/skills/sm-flow/references/templates.md index e9b6885..74d46ae 100644 --- a/.agents/skills/sm-flow/references/templates.md +++ b/.agents/skills/sm-flow/references/templates.md @@ -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 diff --git a/devflow/index.md b/devflow/index.md new file mode 100644 index 0000000..5462f77 --- /dev/null +++ b/devflow/index.md @@ -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 | diff --git a/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/acceptance.md b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/acceptance.md new file mode 100644 index 0000000..df37e2e --- /dev/null +++ b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/acceptance.md @@ -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 中。 diff --git a/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/brief.md b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/brief.md new file mode 100644 index 0000000..49d0cb9 --- /dev/null +++ b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/brief.md @@ -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 的关键设计。 diff --git a/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md new file mode 100644 index 0000000..9bf503f --- /dev/null +++ b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/decisions.md @@ -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 接受。 diff --git a/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/evidence.md b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/evidence.md new file mode 100644 index 0000000..bafd6e6 --- /dev/null +++ b/devflow/projects/2026-05-21-sm-flow-v3-1-upgrade/evidence.md @@ -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 重点。 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/.openspec.yaml b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/.openspec.yaml new file mode 100644 index 0000000..af43829 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-21 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/design.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/design.md new file mode 100644 index 0000000..92cab19 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/design.md @@ -0,0 +1,54 @@ +## Context + +SM Flow v3 已经把 `devflow/` 定位为上下文真理源，把 `openspec/changes//` 定位为执行真理源。当前摩擦来自执行细节：一些需要人类判断的规则没有形成 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 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/proposal.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/proposal.md new file mode 100644 index 0000000..93a5e39 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/proposal.md @@ -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 + + +## 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/` 索引功能。 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-apply-conflict-handling/spec.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-apply-conflict-handling/spec.md new file mode 100644 index 0000000..4feb2f2 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-apply-conflict-handling/spec.md @@ -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 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-commit-gate/spec.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-commit-gate/spec.md new file mode 100644 index 0000000..e03ebc9 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-commit-gate/spec.md @@ -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 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-context-indexing/spec.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-context-indexing/spec.md new file mode 100644 index 0000000..aebebd1 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-context-indexing/spec.md @@ -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 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md new file mode 100644 index 0000000..9694535 --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/specs/sm-flow-interface-impact/spec.md @@ -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 diff --git a/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/tasks.md b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/tasks.md new file mode 100644 index 0000000..f74196f --- /dev/null +++ b/openspec/archive/2026-05-21-sm-flow-v3-1-upgrade/tasks.md @@ -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. diff --git a/openspec/config.yaml b/openspec/config.yaml new file mode 100644 index 0000000..392946c --- /dev/null +++ b/openspec/config.yaml @@ -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 diff --git a/skill-workbench/docs/sm-flow/workflow.md b/skill-workbench/docs/sm-flow/workflow.md index 5e90818..38b3f17 100644 --- a/skill-workbench/docs/sm-flow/workflow.md +++ b/skill-workbench/docs/sm-flow/workflow.md @@ -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 或其他代理环境中迁移，而不会被某个固定目录锁死。 + diff --git a/skill-workbench/docs/sm-flow/使用问题.md b/skill-workbench/docs/sm-flow/使用问题.md new file mode 100644 index 0000000..54e94da --- /dev/null +++ b/skill-workbench/docs/sm-flow/使用问题.md @@ -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实施过程中的沟通？ \ No newline at end of file diff --git a/skill-workbench/generated-skills/sm-flow/SKILL.md b/skill-workbench/generated-skills/sm-flow/SKILL.md index d22e598..b6fdd10 100644 --- a/skill-workbench/generated-skills/sm-flow/SKILL.md +++ b/skill-workbench/generated-skills/sm-flow/SKILL.md @@ -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//` 是执行真理源：当前变更的 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 产物链接和是否归档。 diff --git a/skill-workbench/generated-skills/sm-flow/references/archive-rules.md b/skill-workbench/generated-skills/sm-flow/references/archive-rules.md index a013bfb..4c6f6e5 100644 --- a/skill-workbench/generated-skills/sm-flow/references/archive-rules.md +++ b/skill-workbench/generated-skills/sm-flow/references/archive-rules.md @@ -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？ diff --git a/skill-workbench/generated-skills/sm-flow/references/fallbacks.md b/skill-workbench/generated-skills/sm-flow/references/fallbacks.md index 64000fb..7ef272c 100644 --- a/skill-workbench/generated-skills/sm-flow/references/fallbacks.md +++ b/skill-workbench/generated-skills/sm-flow/references/fallbacks.md @@ -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 diff --git a/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md b/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md index 0b5b7f6..0b04821 100644 --- a/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md +++ b/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md @@ -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//` 中 proposal/design/specs/tasks 已达到可执行状态。 -- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。 +- `openspec/changes//` 中 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。 **输出**： diff --git a/skill-workbench/generated-skills/sm-flow/references/templates.md b/skill-workbench/generated-skills/sm-flow/references/templates.md index e9b6885..74d46ae 100644 --- a/skill-workbench/generated-skills/sm-flow/references/templates.md +++ b/skill-workbench/generated-skills/sm-flow/references/templates.md @@ -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