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