From e4f6e013a5b1c3a81de42ab1d9db968b689a15e4 Mon Sep 17 00:00:00 2001 From: aruo <40362743+zyongxin@users.noreply.github.com> Date: Sun, 5 Jul 2026 14:30:15 +0800 Subject: [PATCH] Refine sm-flow trigger and scale rules --- .agents/skills/sm-flow/SKILL.md | 32 +++- .../sm-flow/references/archive-rules.md | 16 +- .../skills/sm-flow/references/fallbacks.md | 49 ++++++ .agents/skills/sm-flow/references/glossary.md | 21 +++ .../sm-flow/references/operating-rules.md | 49 +++--- .../sm-flow/references/phase-contracts.md | 98 ++++++----- .agents/skills/sm-flow/references/scales.md | 42 +++++ .../skills/sm-flow/references/templates.md | 8 +- devflow/index.md | 2 + .../acceptance.md | 48 +++++ .../brief.md | 29 +++ .../decisions.md | 72 ++++++++ .../acceptance.md | 33 ++++ .../brief.md | 25 +++ .../decisions.md | 52 ++++++ .../evidence.md | 34 ++++ .../.archive-ready | 1 + .../.committed | 1 + .../proposal.md | 44 +++++ .../specs/sm-flow-explicit-trigger/spec.md | 53 ++++++ .../tasks.md | 26 +++ .../.archive-ready | 1 + .../.committed | 1 + .../design.md | 35 ++++ .../proposal.md | 39 ++++ .../specs/sm-flow-standard-change/spec.md | 36 ++++ .../tasks.md | 29 +++ skill-workbench/docs/sm-flow/workflow.md | 166 +++++++++++++++--- 28 files changed, 937 insertions(+), 105 deletions(-) create mode 100644 .agents/skills/sm-flow/references/fallbacks.md create mode 100644 .agents/skills/sm-flow/references/glossary.md create mode 100644 .agents/skills/sm-flow/references/scales.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/acceptance.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/brief.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/decisions.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-standard-change/acceptance.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-standard-change/brief.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-standard-change/decisions.md create mode 100644 devflow/projects/2026-07-05-validate-sm-flow-standard-change/evidence.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.archive-ready create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.committed create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/proposal.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/specs/sm-flow-explicit-trigger/spec.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/tasks.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/.archive-ready create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/.committed create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/design.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/proposal.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md create mode 100644 openspec/archive/2026-07-05-validate-sm-flow-standard-change/tasks.md diff --git a/.agents/skills/sm-flow/SKILL.md b/.agents/skills/sm-flow/SKILL.md index be77fd4..2e79191 100644 --- a/.agents/skills/sm-flow/SKILL.md +++ b/.agents/skills/sm-flow/SKILL.md @@ -1,6 +1,6 @@ --- name: sm-flow -description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。 +description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。 --- # SM Flow @@ -9,6 +9,15 @@ SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周 sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。 +## 触发规则 + +只在用户显式调用时使用 sm-flow： + +- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。 +- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。 + +不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。 + ## 四层架构 ``` @@ -30,10 +39,10 @@ sm-flow → 编排层（harness）：阶段、门控、产物约束、人 1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。 2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。 -3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。 +3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。 4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。 5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。 -6. **子 skill 必须显式调用**。每个阶段指定的子 skill 必须显式调用；如果子 skill 不存在，流程失败，不得静默跳过或降级执行。 +6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。 每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。 @@ -48,11 +57,26 @@ sm-flow → 编排层（harness）：阶段、门控、产物约束、人 用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。 +## 可见 Checkpoint + +内部阶段不是用户 API。对用户汇报进度时，默认只暴露 4 个 checkpoint： + +| Checkpoint | 覆盖内部阶段 | 用户可见含义 | +|---|---|---| +| Discover | clarify + context + propose + grill | 澄清目标、读取 devflow、形成轻量 proposal、解决关键问题 | +| Commit | specify + audit + commit | 补全 OpenSpec、做架构/产物对齐、生成 Committed OpenSpec | +| Apply | apply | 基于 Committed OpenSpec 实现和验证 | +| Archive | archive | 回填 devflow、汇报验收、询问是否归档 OpenSpec | + +除非用户要求看细节，进度汇报、暂停点和恢复提示应使用 checkpoint 名称，而不是逐个暴露 9 个内部阶段。内部阶段仍按顺序执行，并以 `references/phase-contracts.md` 为准。 + ## 首次加载 执行前只读取当前任务需要的 reference 文件： -- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。 +- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`；如果外部 OpenSpec 能力或子 skill 不可用，再补读 `references/fallbacks.md`。 +- 判断或执行 `micro / standard / complex` 分档时，读取 `references/scales.md`；其它文件不得重复定义分档细节。 +- 当 checkpoint / gate / fallback / Draft / Committed 等术语含义不清，或需要统一对用户说明时，读取 `references/glossary.md`。 - 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。 - archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。 diff --git a/.agents/skills/sm-flow/references/archive-rules.md b/.agents/skills/sm-flow/references/archive-rules.md index 0775b09..49b65b7 100644 --- a/.agents/skills/sm-flow/references/archive-rules.md +++ b/.agents/skills/sm-flow/references/archive-rules.md @@ -11,8 +11,8 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排： - [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md` （从 proposal.md 提取：背景、目标、范围、非目标） -- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md` - （从 decisions.md 提取：evidence-driven 记录） +- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md` + （创建时从 decisions.md 提取 evidence-driven 记录） - [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md` （整理为最终版：关键决策、权衡、风险） @@ -23,7 +23,7 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排： ### Step 2: 更新索引（必需） - [ ] 在 `devflow/index.md` 末尾追加或更新一行： - `| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | archived |` + `| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | {status} |` ### Step 3: 标记 OpenSpec（必需） @@ -53,10 +53,10 @@ Archive 阶段必须按以下顺序执行，不得跳过或重排： devflow/projects/YYYY-MM-DD-{slug}/ ``` -archive 阶段创建以下文件： +archive 阶段按 `references/scales.md` 的当前分档创建以下文件： - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。 -- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。 +- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。 - `decisions.md`：保持为最终版，整理格式。 - `acceptance.md`：从实现结果和验证结果提取。 @@ -77,11 +77,7 @@ archive 阶段创建以下文件： ## 产物分档 -| 分档 | 适用场景 | 必须文件 | 扩展文件 | -| --- | --- | --- | --- | -| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` | -| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound | -| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` | +分档的适用场景和必须文件见 `references/scales.md`。本文件只定义 archive 阶段的创建顺序、提取映射和索引规则。 ## 提取映射 diff --git a/.agents/skills/sm-flow/references/fallbacks.md b/.agents/skills/sm-flow/references/fallbacks.md new file mode 100644 index 0000000..63c5e89 --- /dev/null +++ b/.agents/skills/sm-flow/references/fallbacks.md @@ -0,0 +1,49 @@ +# 内置执行协议 + +本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。 + +## 通用规则 + +- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。 +- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。 +- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。 +- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。 + +## grill 内置协议 + +- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。 +- 将问题标记为 `evidence-driven` 或 `user-interview`。 +- 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。 +- 按 `references/scales.md` 的当前分档满足 grill 要求。 +- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。 + +## openspec 提案内置协议 + +- 在 `openspec/changes/{slug}/` 创建或更新： + - `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。 + - 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。 + - `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。 + - `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。 +- 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。 +- 如果发现 gap，先修正 OpenSpec，再进入 commit。 + +## audit 内置协议 + +- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。 +- 如果风险影响实现，修正设计产物或 `tasks.md`。 +- 将结论写入 `decisions.md`。 + +## openspec apply 内置协议 + +- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。 +- 开始前检查 `.committed` 文件；缺失则返回 commit。 +- 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。 +- 按 tasks 的纵向切片实现、验证并更新任务状态。 +- 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。 + +## openspec archive 内置协议 + +- 不删除或移动 OpenSpec change；只标记归档准备状态。 +- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。 +- 向用户汇报已创建文件、验证分类、剩余风险，并询问是否需要真实 OpenSpec archive。 +- 如果外部 archive 能力仍不可用，在 `acceptance.md` 标记 `accepted-unarchived`。 diff --git a/.agents/skills/sm-flow/references/glossary.md b/.agents/skills/sm-flow/references/glossary.md new file mode 100644 index 0000000..9528b40 --- /dev/null +++ b/.agents/skills/sm-flow/references/glossary.md @@ -0,0 +1,21 @@ +# 术语表 + +本文件统一 sm-flow 协议中的核心词。优先使用这些词，避免同一概念多种说法。 + +| 术语 | 含义 | 使用边界 | +| --- | --- | --- | +| sm-flow | 协议层 harness | 编排 OpenSpec 生命周期，不替代 OpenSpec | +| OpenSpec | 当前变更的执行真理源 | apply 只能依据 Committed OpenSpec | +| devflow | 长期记忆和上下文层 | 提供术语、历史决策、验收记录，不直接指挥实现 | +| checkpoint | 用户可见检查点 | 默认只暴露 Discover / Commit / Apply / Archive | +| gate | 硬门控 | 不满足就不能进入下一关键动作，如 commit gate | +| Draft OpenSpec | 讨论和审计对象 | propose/specify 期间产生，不能直接 apply | +| Committed OpenSpec | 已通过 commit gate 的 OpenSpec | apply 的唯一执行依据 | +| fallback | 内置执行协议 | 外部 OpenSpec CLI 或子 skill 不可用时使用，必须标注 | +| decisions.md | 过程日志 | clarify 到 apply 期间记录问题、证据、决策、冲突和回写 | +| .committed | commit gate 标记文件 | 存在才可进入合规 apply | +| .archive-ready | archive 准备标记文件 | 表示 devflow 已回填，等待用户确认是否 archive | +| Discover | 用户可见 checkpoint | 覆盖 clarify + context + propose + grill | +| Commit | 用户可见 checkpoint | 覆盖 specify + audit + commit | +| Apply | 用户可见 checkpoint | 覆盖 apply | +| Archive | 用户可见 checkpoint | 覆盖 archive | diff --git a/.agents/skills/sm-flow/references/operating-rules.md b/.agents/skills/sm-flow/references/operating-rules.md index 3cc5d34..5ce2558 100644 --- a/.agents/skills/sm-flow/references/operating-rules.md +++ b/.agents/skills/sm-flow/references/operating-rules.md @@ -27,13 +27,14 @@ - `/sm-flow apply [change]`：只执行，检查 commit gate → apply。 - `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。 - `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。 + - 明确要求"使用 sm-flow"或"走 sm-flow 流程"：按显式调用处理。 - 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。 2. 判断启动模式： - 完整模式：用户提供粗略想法或初始 PRD。 - Research 模式：用户已有 research，需要转成或修正 OpenSpec。 - PRD 文件模式：用户提供已有 PRD 路径。 - 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。 - - 快速模式：小改动，合并 gate（见下文）。 + - 快速模式：小改动，合并 gate；具体分档规则见 `references/scales.md`。 3. 如果缺少 `devflow/`，初始化： - `devflow/projects/` - `devflow/glossary/CONTEXT.md` @@ -42,7 +43,25 @@ 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 前向用户说明。 +6. 如果 OpenSpec 或子 skill 不可用，不要静默跳过；使用内置执行协议（见 `references/fallbacks.md`），并在当前 checkpoint 说明 fallback 来源、影响和剩余风险。 + +## 进度汇报 + +用户可见进度默认折叠为 4 个 checkpoint： + +| Checkpoint | 内部阶段 | +| --- | --- | +| Discover | clarify + context + propose + grill | +| Commit | specify + audit + commit | +| Apply | apply | +| Archive | archive | + +汇报规则： + +- 面向用户时优先使用 checkpoint 名称，不逐个汇报 9 个内部阶段。 +- 内部阶段只在 checkpoint 摘要中作为证据列出，例如"Discover 已完成：读取了 devflow、生成 proposal、解决 2 个问题"。 +- 只有发生阻塞、冲突、fallback、用户要求继续某个内部阶段，或需要解释恢复位置时，才暴露内部阶段名。 +- 当前分档的汇报压缩规则见 `references/scales.md`；无论分档如何，都不要把内部阶段名当作用户操作入口。 ## 项目标识规则 @@ -63,7 +82,7 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec **最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）： - `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。 -- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态。 +- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。 - `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。 **按需产物**（archive 阶段按需创建）： @@ -75,28 +94,17 @@ Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec - `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。 - `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。 -**规模分档**： - -- `micro`：小且低风险，gate 合并（见快速模式），最终档案同 standard。 -- `standard`：默认模式。 -- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。 +**规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。 ## 快速模式 -快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物： - -``` -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）。 +快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。 无论什么模式，以下内容必须保留： - context 最小上下文收集：至少检查 glossary 和相关 ADR。 -- grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。 -- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。 +- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。 +- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。 - apply 仍由 OpenSpec tasks/specs 驱动执行。 - archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。 @@ -104,8 +112,9 @@ micro 的定位：**gate 变少但保留最关键的**（grill 最小澄清 + co 只有同时满足以下条件，流程才算完成： -- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。 +- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。 +- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。 - 实现或规划工作已完成，且执行依据来自 OpenSpec。 - 已运行验证，或已记录未运行验证的原因。 -- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md。 +- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。 - 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。 diff --git a/.agents/skills/sm-flow/references/phase-contracts.md b/.agents/skills/sm-flow/references/phase-contracts.md index 4406510..423de8e 100644 --- a/.agents/skills/sm-flow/references/phase-contracts.md +++ b/.agents/skills/sm-flow/references/phase-contracts.md @@ -4,6 +4,18 @@ 执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive。 +## 目录 + +- clarify — 入口澄清 +- context — 上下文收集 +- propose — 轻量 propose +- grill — 人类对齐澄清 +- specify — 细化 + 对齐 +- audit — 架构审计 +- commit — Commit OpenSpec +- apply — OpenSpec 执行 +- archive — 回填 + 归档 + ## clarify — 入口澄清 **进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。 @@ -13,7 +25,7 @@ - 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。 - 如果输入过于模糊，最多追加三轮聚焦问题。 - 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。 -- 如果需要判断 `micro / standard / complex` 分档，补读 `references/operating-rules.md`。 +- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。 **退出条件**： - 问题可以用 1-2 句话说清楚。 @@ -36,7 +48,7 @@ - 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。 - 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。 - 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。 -- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。 +- 记录哪些上下文会影响 OpenSpec proposal、设计产物、specs 或 tasks。 - 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。 **退出条件**： @@ -70,13 +82,13 @@ **Human checkpoint**： - 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。 -- 询问是否继续进入 grill 澄清阶段；用户明确要求"全自动执行"时可跳过等待。 +- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。 ## grill — 人类对齐澄清 **进入条件**：propose 已有轻量 proposal.md。 -**显式子 skill**：`grill-with-docs`。进入本阶段必须调用 `.agents/skills/grill-with-docs/SKILL.md`。 +**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。 **动作**： - 优先使用 `grill-with-docs`。 @@ -101,7 +113,7 @@ **退出条件**： - question pool 已建立并覆盖当前 change 所需维度。 -- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。 +- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。 - 所有 evidence-driven 结论已向用户汇报。 - 所有 user-interview 决策已获得用户确认。 - 没有未解决或代理代确认的 user-interview 问题。 @@ -117,20 +129,20 @@ **Human checkpoint**： - 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。 -- 询问是否继续进入 specify 细化阶段。 +- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。 ## specify — 细化 + 对齐 **进入条件**：grill 已退出，需求已通过澄清稳定下来。 -**显式子 skill**：`openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；`to-prd`（按需生成 PRD）。进入本阶段必须先声明调用方式。 +**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。 **动作**： -- 基于已稳定的 proposal.md 补全 design.md、specs/、tasks.md： - - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需补全 design/specs/tasks"。 - - 如果不可用，执行 `references/fallbacks.md#openspec-提案-降级`。 +- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md： + - 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。 + - 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。 - 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。 -- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级。 +- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。 - 用 grill 阶段的 decisions.md 记录增强 OpenSpec 产物：确保 design/specs/tasks 反映所有已确认的决策。 - **显式 cross-artifact 对齐检查**——在 checkpoint 中输出对齐检查表： - `brief/prd` 中的目标、范围、非目标和验收预期 → `proposal` 是否覆盖。 @@ -147,14 +159,14 @@ - 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。 **退出条件**： -- `design.md`、`specs/`、`tasks.md` 存在且与 proposal 对齐。 +- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。 - `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。 - cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。 - 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。 - 所有已知冲突已修正或等待用户决策。 **输出**： -- 完整的 Draft OpenSpec：proposal.md + design.md + specs/ + tasks.md。 +- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。 - `brief.md`，以及按需创建的 `prd.md`。 - cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。 - 必要的 OpenSpec 修正。 @@ -163,7 +175,7 @@ **进入条件**：specify 已退出，完整 OpenSpec 产物已存在。 -**显式子 skill**：`zoom-out`。进入本阶段必须调用 `.agents/skills/zoom-out/SKILL.md`。 +**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。 **动作**： - 画出输入 → 处理 → 输出的模块链路。 @@ -175,20 +187,20 @@ **退出条件**： - 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。 -- OpenSpec design/tasks 已反映会影响实现的架构审计结论。 +- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。 **输出**： - 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。 -- 必要的 OpenSpec design/tasks 修正。 +- 必要的 OpenSpec 设计产物/tasks 修正。 **Human checkpoint**： - 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。 -- 询问是否进入 commit。 +- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。 ## commit — Commit OpenSpec **进入条件**： -- grill 已解决术语、边界、验收三个维度的高价值问题。 +- grill 已满足 `references/scales.md` 中当前分档要求。 - 所有 `user-interview` 问题都已获得用户显式确认。 - audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。 - Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。 @@ -198,7 +210,7 @@ - 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。 - 检查 specs 是否表达外部可观察行为，并覆盖验收口径。 - 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。 -- 复核 cross-artifact 对齐：`brief/prd → proposal → design → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。 +- 复核 cross-artifact 对齐：`brief/prd → proposal → 设计产物 → specs → tasks` 是否闭环，没有把字段、范围项、验收行为或实现切片丢在上游产物里。 - 检查 `decisions.md` 中所有影响实现的发现，是否已回写到 proposal、design、specs 或 tasks。 - 接口影响分级定义见 `references/operating-rules.md#接口影响分级`。 - 检查接口影响是否已按 L1/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。 @@ -207,14 +219,14 @@ **退出条件**： - Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。 -- **文件完整性检查**（必须全部通过）： - - [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标 - - [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条） - - [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement - - [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准 +- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）： + - [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。 + - [ ] 设计产物存在，形式符合当前分档要求。 + - [ ] specs 存在，且表达用户可观察行为。 + - [ ] tasks 存在，且任务可执行、验收标准可验证。 - **一致性检查**（必须通过）： - - [ ] proposal 中的核心概念在 design 中有对应设计 - - [ ] design 中的关键决策在 tasks 中有对应实现任务 + - [ ] proposal 中的核心概念在设计产物中有对应设计 + - [ ] 设计产物中的关键决策在 tasks 中有对应实现任务 - [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述） - **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec - 所有 preflight 风险已消除或明确记录为已接受。 @@ -225,28 +237,28 @@ **Human checkpoint**： - 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。 -- 询问是否进入 apply；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。 +- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。 - 不得把 grill 的单个决策确认当作本 checkpoint 的授权。 ## apply — OpenSpec 执行 **进入条件**： -- `openspec/changes/{slug}/` 中 proposal/design/specs/tasks 已通过 commit，成为 Committed OpenSpec。 +- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。 - **前置门控检查**（硬约束）： - 检查 `openspec/changes/{slug}/.committed` 文件是否存在 - 如不存在，执行以下流程： 1. 汇报：Draft OpenSpec 未通过 commit 检查 2. 列出缺失的 checkpoint 项（文件完整性、一致性检查） - 3. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认） + 3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply - commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。 - devflow 与 OpenSpec 没有未解决冲突。 - 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。 -**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须调用指定子 skill，不得静默跳过。 +**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。 **动作**： -### Pre-apply Checkpoint（15-20 分钟） +### Pre-apply Checkpoint **触发条件**：当 OpenSpec 涉及以下任一情况时必须执行 - design 或 tasks 中提到"参考 XXX 实现" @@ -254,12 +266,12 @@ - 技术栈不熟悉或第一次在该项目实现类似功能 **执行步骤**： -1. **完整阅读所有参考实现**（约 10 分钟） +1. **阅读所有参考实现** - 从 OpenSpec design 或 tasks 中定位参考实现文件 - 如果路径不明确，通过 Grep 搜索关键类名或模式 - - 逐行理解关键逻辑，提取可复用代码片段和模式 + - 理解关键逻辑，提取可复用代码片段和模式 -2. **Grep 关键技术栈**（约 5 分钟） +2. **Grep 关键技术栈** - 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范） - 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板） - 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具） @@ -273,11 +285,11 @@ - 识别需要新建的工具类或基础设施 **输出要求**： -- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节 ✅ -- 已列出所有参考实现的文件路径 ✅ -- 已识别需要新建的工具类/基础设施 ✅ +- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。 +- 已列出所有参考实现的文件路径。 +- 已识别需要新建的工具类/基础设施。 -**快速模式**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。 +**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。 ### 实现过程 @@ -299,9 +311,9 @@ - 修改文件前遵守仓库指令，例如 `AGENTS.md`。 **退出条件**： -- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md` ✅ +- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。 - OpenSpec tasks 已完成，或剩余 tasks 已明确记录。 -- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位 ✅ +- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。 - 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。 - 已运行验证，或记录了未验证原因。 - 已列出已知限制。 @@ -315,13 +327,13 @@ **进入条件**：实现或规划工作已经达到可交接状态。 -**显式子 skill**：`openspec-archive-change` 在用户确认 archive 后调用；archive 回填由 `sm-flow` 执行。必须调用子 skill，不得静默跳过。 +**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。 **动作**： - 遵循 `references/archive-rules.md`。 - 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案： - `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。 - - `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取。 + - `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。 - `decisions.md`：保持为最终版，整理格式。 - `acceptance.md`：从实现结果和验证结果提取。 - 只在复杂场景按需拆出 PRD/research/design/tasks/alignment。 @@ -331,7 +343,7 @@ - 询问用户是否要 archive OpenSpec change；不要默认执行归档。 **退出条件**： -- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 brief.md、evidence.md、decisions.md、acceptance.md；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。 +- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。 - `devflow/index.md` 已包含或更新本项目条目。 - 用户已被询问是否 archive OpenSpec change。 diff --git a/.agents/skills/sm-flow/references/scales.md b/.agents/skills/sm-flow/references/scales.md new file mode 100644 index 0000000..e4bf9f9 --- /dev/null +++ b/.agents/skills/sm-flow/references/scales.md @@ -0,0 +1,42 @@ +# 分档规则 + +本文件是 `micro / standard / complex` 的唯一规则源。其它文件只引用本文件，不重复定义分档细节。 + +## standard 基准 + +standard 是默认分档，适用于普通功能、明确但有一定实现范围的变更。 + +- 用户可见 checkpoint：Discover → Commit → Apply → Archive。 +- OpenSpec 产物：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。 +- grill：解决术语、边界、验收三个维度的高价值问题。 +- commit gate：检查 proposal、design、specs、tasks 的完整性和一致性。 +- devflow 档案：`brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。 + +## micro 覆盖 + +micro 适用于小改动、低风险、需求明确的变更。micro 是 standard 的减法，不是跳过流程。 + +- checkpoint 可合并：Discover + Commit 可在无阻塞时合并汇报。 +- micro 内部流程压缩为：clarify+context 合并 checkpoint → 轻量 propose → grill → specify+commit 合并 checkpoint。 +- context 保留最小收集：至少检查 glossary 和相关 ADR。 +- grill 保留最小澄清：至少解决一个高价值问题，并记录术语、边界、验收三类是否明确；不明确项必须补问或标记风险。 +- OpenSpec 仍需要 `proposal.md`、`specs/`、`tasks.md`。 +- `design.md` 可不独立创建；允许在 `proposal.md` 或 `tasks.md` 中写等价设计小节。 +- `specs/` 和 `tasks.md` 可轻量，但必须表达可观察行为和可执行任务。 +- commit gate 仍必须通过，并创建 `.committed`。 +- devflow 档案至少包含 `brief.md`、`decisions.md`、`acceptance.md`；证据少时可并入 `brief.md` 或 `decisions.md`。 +- apply 仍只能依据 Committed OpenSpec。 +- archive 仍要轻量回填 devflow，并询问是否归档 OpenSpec。 + +micro 不适用于接口影响不清、跨团队消费者、迁移/回滚、复杂状态机、长期架构决策或需求边界不清的变更；遇到这些情况应升级为 standard 或 complex。 + +## complex 增量 + +complex 适用于高风险、跨模块、需求不清、多人协作或长期架构影响明显的变更。complex 是 standard 的加法。 + +- 需要更完整的 Discover：增加需求澄清、证据查证、范围确认和风险接受。 +- checkpoint 内可补充关键内部阶段结果，但不要把内部阶段名当作用户操作入口。 +- 按需创建 `prd.md`、`research.md`、`alignment.md`、接口文档、ADR 或 compound knowledge。 +- 接口影响、迁移、灰度、回滚、兼容性和消费者边界必须显式记录。 +- audit 需要覆盖模块链路、数据所有权、生命周期、耦合风险和 ADR 冲突。 +- archive 在 standard 档案基础上按需提炼长期 design、research、tasks、ADR 和 compound knowledge。 diff --git a/.agents/skills/sm-flow/references/templates.md b/.agents/skills/sm-flow/references/templates.md index b428144..1ac4cb8 100644 --- a/.agents/skills/sm-flow/references/templates.md +++ b/.agents/skills/sm-flow/references/templates.md @@ -124,7 +124,7 @@ - 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为 - 冲突对象：proposal / design / specs / tasks / ADR / 代码行为 -- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更 +- 分类：OpenSpec 不准 / 代码偏离 / 不确定 ## 证据 @@ -136,7 +136,7 @@ - 决策： - 是否需要用户确认：是 / 否 -- OpenSpec 回写：不需要 / 已回写 / 待回写 +- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认 - 代码处理： - 验证方式： ``` @@ -353,8 +353,8 @@ specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐" | 上游 → 下游 | 检查内容 | 状态 | |---|---|---| | brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap | -| proposal → design | 范围、约束、关键承诺是否进入 design | 已对齐 / 存在 gap | -| design → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap | +| proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap | +| 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap | | specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap | ### Gap 详情（如有） diff --git a/devflow/index.md b/devflow/index.md index e05d825..633ca91 100644 --- a/devflow/index.md +++ b/devflow/index.md @@ -10,3 +10,5 @@ | 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 | | 2026-05-22 | sm-flow-execution-hardening | sm-flow | execution-hardening, checklist, phase-gate, cross-artifact, question-pool | 未关联 | active | +| 2026-07-05 | validate-sm-flow-explicit-trigger | sm-flow | explicit-trigger, scale-source, fallback, validation | `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/` | archived | +| 2026-07-05 | validate-sm-flow-standard-change | sm-flow | standard-change, full-artifacts, evidence, validation | `openspec/archive/2026-07-05-validate-sm-flow-standard-change/` | archived | diff --git a/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/acceptance.md b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/acceptance.md new file mode 100644 index 0000000..fcf5cb4 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/acceptance.md @@ -0,0 +1,48 @@ +# Validate SM Flow Explicit Trigger Acceptance + +## Result + +Accepted and archived. + +## Static Validation + +- Trigger rule verification: + - `SKILL.md` frontmatter says sm-flow is only used for explicit `/sm-flow` commands or explicit natural-language requests. + - `SKILL.md` trigger section says task type alone must not auto-trigger sm-flow. + - `operating-rules.md` startup checks now include explicit natural-language requests. + +- Scale source verification: + - Scale definition scan found `standard`, `micro`, and `complex` definition headings and definition phrases only in `references/scales.md`. + - Other files refer to `references/scales.md` instead of redefining the scale rules. + +- Obsolete wording verification: + - No matches for minute/hour/second/timebox metrics. + - No matches for old skip semantics or old fixed `proposal.md + design.md` expression. + - No matches for old conflict wording targeted by this validation. + +## Script Validation + +- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow` +- Passed: reference integrity scan for `references/*.md`. + +## Browser Or Manual Validation + +- Not applicable. This change only modifies skill protocol text and validation records. + +## Unverified + +- Real external OpenSpec CLI integration was not executed because the current tool surface does not expose those child commands. +- Forward-testing with an independent subagent was not run in this pass. + +## Fixed During Apply + +- Replaced remaining hard-coded `design.md` wording in phase/audit fallback rules where the protocol must respect scale-specific design artifacts. +- Added explicit natural-language sm-flow requests to startup checks. + +## OpenSpec Archive + +- `.archive-ready` is present. +- User confirmed archive. +- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`. +- Status: `archived`. +- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface. diff --git a/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/brief.md b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/brief.md new file mode 100644 index 0000000..4e35da5 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/brief.md @@ -0,0 +1,29 @@ +# Validate SM Flow Explicit Trigger Brief + +## Background + +`sm-flow` was simplified so it should only run on explicit user invocation. Related cleanup centralized scale rules, removed time-based metrics, and separated fallback/glossary details into references. + +## Goal + +Validate the current `sm-flow` design by running a real micro OpenSpec change through Discover, Commit, Apply, and Archive. + +## Scope + +- Validate `.agents/skills/sm-flow/SKILL.md`. +- Validate `.agents/skills/sm-flow/references/*.md`. +- Fix any protocol inconsistency found during validation. +- Record fallback capability source because external OpenSpec commands are unavailable in the current tool surface. + +## Non-Goals + +- No business code changes. +- No changes to the four visible checkpoints or nine internal phases. +- No automatic trigger heuristics. +- No historical archive rewrites. + +## Scale + +- Scale: `micro`. +- Evidence is folded into `decisions.md`. +- Linked OpenSpec change: `openspec/changes/validate-sm-flow-explicit-trigger/`. diff --git a/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/decisions.md b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/decisions.md new file mode 100644 index 0000000..44bf404 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/decisions.md @@ -0,0 +1,72 @@ +# Validate SM Flow Explicit Trigger Decisions + +## Capability Source + +- Discover: sm-flow built-in protocol. +- Propose/specify/apply/archive: fallback protocol from `.agents/skills/sm-flow/references/fallbacks.md`. +- Missing external capability: OpenSpec CLI and OpenSpec child skills are not directly callable from the current tool surface. +- Impact: validation is file-based and static; it can verify current protocol text and artifacts but cannot exercise a real external OpenSpec command. +- Remaining risk: future tool availability may require rechecking integration behavior. + +## Context + +- `devflow/index.md` contains related sm-flow history: + - `dev-flow-skill-evaluation` + - `sm-flow-v3-1-upgrade` + - `sm-flow-execution-hardening` +- `devflow/glossary/CONTEXT.md` is project-level glossary and does not define sm-flow protocol terms. +- Current validation change is new: `validate-sm-flow-explicit-trigger`. + +## Scale Decision + +- Scale: `micro`. +- Reason: documentation/protocol validation only, no business code, no external interface contract change. +- Interface impact: L1 internal documentation/protocol validation. +- Micro constraints retained: proposal, specs, tasks, commit gate, apply verification, devflow archive, archive confirmation. + +## Question Pool + +| Question | Mode | Status | Result | +| --- | --- | --- | --- | +| Does top-level trigger text require explicit sm-flow invocation only? | evidence-driven | confirmed | `SKILL.md` frontmatter and trigger section both state explicit invocation only. | +| Are scale definitions centralized in `references/scales.md`? | evidence-driven | confirmed | Scan for scale definition headings and definition phrases only matched `references/scales.md`. | +| Are time/minute metrics absent from skill rules? | evidence-driven | confirmed | Obsolete time metric scan returned no matches. | +| Does fallback usage remain explicit and recorded? | evidence-driven | confirmed | This file records fallback source, impact, and remaining risk. | +| Is user confirmation needed for product scope? | user-interview | not required | User already requested this validation run; no unresolved product preference blocks this micro validation. | + +## Cross-Artifact Alignment + +| Link | Status | Notes | +| --- | --- | --- | +| brief/prd -> proposal | not applicable | Micro validation has no separate brief/prd before archive. | +| proposal -> design artifact | aligned | Proposal contains inline micro design notes. | +| design artifact -> specs | aligned | Specs cover explicit trigger, scale source, no time metrics, and fallback recording. | +| specs -> tasks | aligned | Tasks include scans, validation, patching if needed, and archive handoff. | + +## Commit Gate + +- Passed. +- Proposal explains why, what, scope, non-goals, inline design, and risks. +- Specs describe observable validation behavior. +- Tasks are executable and have validation evidence. +- Cross-artifact alignment has no unresolved gap. +- `.committed` created. + +## Apply Log + +- Validation found one consistency issue: `phase-contracts.md` still hard-coded `design.md` in specify/audit wording even though `scales.md` allows micro changes to use an equivalent inline design section. +- Fix applied: changed those references to "设计产物" where the rule must respect the current scale. +- Fix applied: `fallbacks.md` audit fallback now says to repair the design artifact instead of only `design.md`. +- Fix applied: `operating-rules.md` startup checks now include explicit natural-language requests to use sm-flow. +- Validation commands passed: + - `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow` + - reference integrity scan for `references/*.md` + - obsolete wording scan for time metrics, old skip semantics, old conflict wording, and fixed `design.md` expressions. + - scale definition duplication scan. + +## Archive Log + +- User confirmed OpenSpec archive. +- External `openspec-archive-change` was not directly callable in the current tool surface. +- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/`, matching existing repository archive convention. +- `devflow/index.md` status updated to `archived`. diff --git a/devflow/projects/2026-07-05-validate-sm-flow-standard-change/acceptance.md b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/acceptance.md new file mode 100644 index 0000000..9e8a441 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/acceptance.md @@ -0,0 +1,33 @@ +# Validate SM Flow Standard Change Acceptance + +## Result + +Accepted and archived. + +## Static Validation + +- Scale rule centralization passed. +- Obsolete wording scan passed. +- Standard artifact completeness passed. +- Cross-artifact alignment passed. + +## Script Validation + +- Passed: skill quick validation. +- Passed: reference integrity scan. + +## Browser Or Manual Validation + +- Not applicable. This validation covers skill protocol files and OpenSpec/devflow records. + +## Unverified + +- External OpenSpec CLI integration. +- Independent forward-testing by a separate agent. + +## OpenSpec Archive + +- User confirmed archive. +- Archived location: `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`. +- Status: `archived`. +- Archive method: local filesystem archive following existing repository convention because external `openspec-archive-change` is not directly callable in the current tool surface. diff --git a/devflow/projects/2026-07-05-validate-sm-flow-standard-change/brief.md b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/brief.md new file mode 100644 index 0000000..2ab9b89 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/brief.md @@ -0,0 +1,25 @@ +# Validate SM Flow Standard Change Brief + +## Background + +The micro validation confirmed the reduced path. This record validates the normal standard path, where independent design and separate evidence are required. + +## Goal + +Confirm that the current `sm-flow` skill supports a standard change with complete OpenSpec and devflow artifacts. + +## Scope + +- Validate standard artifact requirements. +- Validate scale rule centralization. +- Validate skill structure and reference integrity. + +## Non-Goals + +- No business code changes. +- No archive move without user confirmation. +- No complex migration, rollback, or cross-team interface test. + +## Linked OpenSpec + +`openspec/changes/validate-sm-flow-standard-change/` diff --git a/devflow/projects/2026-07-05-validate-sm-flow-standard-change/decisions.md b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/decisions.md new file mode 100644 index 0000000..91ad1bf --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/decisions.md @@ -0,0 +1,52 @@ +# Validate SM Flow Standard Change Decisions + +## Capability Source + +- This is an ordinary engineering validation, not an explicit sm-flow invocation. +- External OpenSpec child commands are not directly callable in the current tool surface. +- Validation uses file-based OpenSpec fixtures and static/script checks. + +## Scale Decision + +- Scale: `standard`. +- Reason: this validation intentionally exercises the full normal artifact set: proposal, independent design, specs, tasks, and separate evidence. +- Interface impact: L1 internal documentation/protocol validation. + +## Question Pool + +| Question | Mode | Status | Result | +| --- | --- | --- | --- | +| Does standard require independent `design.md`? | evidence-driven | confirmed | `references/scales.md` defines independent `design.md` for standard. | +| Does standard require separate `evidence.md` in devflow? | evidence-driven | confirmed | `references/scales.md` defines `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`. | +| Are standard scale definitions duplicated outside `scales.md`? | evidence-driven | confirmed | Scale definition scan matched complete scale definitions only in `references/scales.md`. | +| Is user scope confirmation needed? | user-interview | not required | User asked to validate a regular change; no product scope choice is blocked. | + +## Cross-Artifact Alignment + +| Link | Status | Notes | +| --- | --- | --- | +| proposal -> design | aligned | Proposal asks for standard artifact validation; design defines standard artifact model. | +| design -> specs | aligned | Specs require full OpenSpec artifacts, evidence archive, and centralized scale definitions. | +| specs -> tasks | aligned | Tasks include fixture creation, validation scans, commit gate, and devflow records. | + +## Findings + +- Standard OpenSpec artifact completeness passed: `proposal.md`, independent `design.md`, spec file, and `tasks.md` exist. +- Cross-artifact alignment passed: proposal -> design -> specs -> tasks. +- Scale duplication scan passed. +- Obsolete wording scan passed. +- Skill quick validation passed. +- Reference integrity scan passed. + +## Commit Gate + +- `.committed` created. +- Status: committed standard validation fixture. + +## Archive Status + +- Devflow standard records created. +- User confirmed OpenSpec archive. +- External `openspec-archive-change` was not directly callable in the current tool surface. +- Archived by moving the OpenSpec change to `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`, matching existing repository archive convention. +- `devflow/index.md` status updated to `archived`. diff --git a/devflow/projects/2026-07-05-validate-sm-flow-standard-change/evidence.md b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/evidence.md new file mode 100644 index 0000000..f70a657 --- /dev/null +++ b/devflow/projects/2026-07-05-validate-sm-flow-standard-change/evidence.md @@ -0,0 +1,34 @@ +# Validate SM Flow Standard Change Evidence + +## Static Evidence + +- Scale definition scan found complete `standard / micro / complex` definition headings and definition phrases only in `.agents/skills/sm-flow/references/scales.md`. +- Obsolete wording scan returned no matches for: + - minute/hour/second/timebox metrics + - old skip semantics + - old fixed `proposal.md + design.md` expression + - old conflict wording targeted by prior validation + +## Script Evidence + +- Passed: `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow` +- Passed: `references/*.md` integrity scan. + +## Artifact Evidence + +- OpenSpec standard artifacts exist: + - `openspec/changes/validate-sm-flow-standard-change/proposal.md` + - `openspec/changes/validate-sm-flow-standard-change/design.md` + - `openspec/changes/validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md` + - `openspec/changes/validate-sm-flow-standard-change/tasks.md` +- Devflow standard artifacts exist: + - `brief.md` + - `evidence.md` + - `decisions.md` + - `acceptance.md` + +## Limits + +- This validation is static/file-based. +- It does not run a real external OpenSpec CLI command. +- It does not include independent subagent forward-testing. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.archive-ready b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.archive-ready new file mode 100644 index 0000000..90a153d --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.archive-ready @@ -0,0 +1 @@ +Devflow archive files are ready for validate-sm-flow-explicit-trigger. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.committed b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.committed new file mode 100644 index 0000000..e2cbe89 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/.committed @@ -0,0 +1 @@ +Committed OpenSpec for validate-sm-flow-explicit-trigger. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/proposal.md b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/proposal.md new file mode 100644 index 0000000..70494cb --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/proposal.md @@ -0,0 +1,44 @@ +# Validate SM Flow Explicit Trigger + +## Why + +Recent edits simplified `sm-flow` so it should only run when the user explicitly invokes it. The same cleanup also centralized scale rules in `references/scales.md`, removed time-based metrics, and split fallback/glossary concepts out of the top-level skill. + +This change validates those protocol decisions through a real micro `sm-flow` run instead of another informal review. + +## What Changes + +- Verify `sm-flow` only triggers on `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or an explicit natural-language request to use sm-flow. +- Verify task type alone does not trigger `sm-flow`, even when the task mentions OpenSpec, devflow, cross-module work, or clarification. +- Verify `micro / standard / complex` definitions live only in `references/scales.md`. +- Verify the skill has no time/minute-based metrics. +- Verify fallback usage is recorded when external OpenSpec capabilities are unavailable. + +## Design Notes + +- Scale: `micro`. +- Interface impact: L1 internal documentation/protocol validation only. +- No business code changes. +- Independent `design.md` is intentionally omitted; this section is the micro design artifact. +- OpenSpec CLI and external OpenSpec child skills are not directly callable in the current tool surface, so this run uses `references/fallbacks.md` and records that capability source in devflow. + +## Scope + +In scope: + +- `.agents/skills/sm-flow/SKILL.md` +- `.agents/skills/sm-flow/references/*.md` +- Validation OpenSpec and devflow records for this change + +Out of scope: + +- Business code +- Rewriting historical OpenSpec archives +- Changing the four visible checkpoints or nine internal phases +- Adding automatic trigger heuristics + +## Risks + +- A future edit may duplicate scale rules outside `references/scales.md`. +- The frontmatter description may drift from the top-level trigger rule. +- Validation can prove current text consistency, but cannot force future agents to obey it without continued review. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/specs/sm-flow-explicit-trigger/spec.md b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/specs/sm-flow-explicit-trigger/spec.md new file mode 100644 index 0000000..0a477f6 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/specs/sm-flow-explicit-trigger/spec.md @@ -0,0 +1,53 @@ +# sm-flow Explicit Trigger Spec + +## ADDED Requirements + +### Requirement: Explicit Trigger Only + +`sm-flow` SHALL be used only when the user explicitly invokes `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or clearly asks to use the sm-flow process in natural language. + +#### Scenario: Plain engineering request + +- **Given** a user asks for an engineering task that mentions OpenSpec, devflow, cross-module work, or clarification +- **When** the user does not explicitly request sm-flow +- **Then** the agent handles the task as ordinary engineering work +- **And** the agent does not auto-trigger sm-flow based on task type + +#### Scenario: Explicit sm-flow request + +- **Given** a user invokes `/sm-flow` or clearly asks to use sm-flow +- **When** the agent starts the process +- **Then** the agent follows the visible checkpoints Discover, Commit, Apply, and Archive +- **And** the internal phase order remains clarify, context, propose, grill, specify, audit, commit, apply, archive + +### Requirement: Scale Rules Have One Source + +The `micro / standard / complex` scale definitions SHALL be defined in `references/scales.md`; other files may only reference that file instead of redefining scale details. + +#### Scenario: Scale guidance is needed + +- **Given** a phase needs to choose or enforce a scale +- **When** the rule is read +- **Then** it points to `references/scales.md` +- **And** no other reference file carries a competing full definition of the three scales + +### Requirement: No Time-Based Skill Metrics + +The skill SHALL NOT use minute, hour, second, or timebox metrics to define scale, effort, or validation thresholds. + +#### Scenario: Protocol text is scanned + +- **Given** the sm-flow skill files are scanned +- **When** obsolete time metrics are searched +- **Then** no matching scale or effort rule remains + +### Requirement: Fallback Capability Is Explicit + +When OpenSpec CLI or child skill capabilities are unavailable, `sm-flow` SHALL use `references/fallbacks.md` only as an explicit fallback and record the capability source in the current devflow process log. + +#### Scenario: External capability unavailable + +- **Given** OpenSpec child skills are not directly callable +- **When** a change is still executed +- **Then** the decisions log records fallback source, impact, and remaining risk +- **And** the fallback does not skip context, grill, commit, apply, or archive gates diff --git a/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/tasks.md b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/tasks.md new file mode 100644 index 0000000..9b18fa7 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/tasks.md @@ -0,0 +1,26 @@ +# Tasks + +## 1. Discover + +- [x] 1.1 Read current `sm-flow` top-level trigger rule and relevant references. +- [x] 1.2 Read `devflow/index.md` and glossary context for related history. +- [x] 1.3 Classify this validation as `micro` and record capability fallback. + +## 2. Commit + +- [x] 2.1 Create micro OpenSpec proposal with inline design notes. +- [x] 2.2 Create specs that express the observable validation expectations. +- [x] 2.3 Create executable validation tasks. +- [x] 2.4 Run cross-artifact alignment and create `.committed`. + +## 3. Apply + +- [x] 3.1 Scan `sm-flow` files for obsolete trigger, scale, time metric, and fallback wording. +- [x] 3.2 Patch any discovered inconsistency in the skill files. +- [x] 3.3 Run skill validation and reference integrity checks. + +## 4. Archive + +- [x] 4.1 Create micro devflow archive files. +- [x] 4.2 Update `devflow/index.md`. +- [x] 4.3 Create `.archive-ready` and ask whether to archive OpenSpec. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.archive-ready b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.archive-ready new file mode 100644 index 0000000..93586d0 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.archive-ready @@ -0,0 +1 @@ +Devflow archive files are ready for validate-sm-flow-standard-change. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.committed b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.committed new file mode 100644 index 0000000..ae2b604 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/.committed @@ -0,0 +1 @@ +Committed OpenSpec for validate-sm-flow-standard-change. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/design.md b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/design.md new file mode 100644 index 0000000..eab844f --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/design.md @@ -0,0 +1,35 @@ +# Design + +## Scale + +Scale: `standard`. + +Rationale: this validation has a clear target and no business-code risk, but it intentionally exercises the full normal artifact set rather than the reduced micro path. + +## Interface Impact + +Interface impact: L1 internal documentation/protocol validation. + +No API, DTO, database, event, service, or cross-module runtime contract changes are expected. + +## Artifact Model + +Standard validation requires: + +- OpenSpec: `proposal.md`, independent `design.md`, `specs/`, `tasks.md`. +- Devflow archive: `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`. + +The validation checks that current skill rules point to `references/scales.md` for the exact standard artifact requirements instead of redefining them elsewhere. + +## Execution Design + +1. Build the standard OpenSpec fixture. +2. Run static scans for standard artifact wording and duplicated scale definitions. +3. Run skill validation and reference integrity checks. +4. Record evidence separately in `devflow/.../evidence.md`. +5. Mark the fixture as committed only if artifact completeness and alignment pass. + +## Risks + +- The external OpenSpec archive/apply commands are not exposed in the current tool surface; this validation uses file-based checks. +- File presence does not prove independent-agent usability; forward-testing remains a separate optional validation surface. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/proposal.md b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/proposal.md new file mode 100644 index 0000000..2bfde5a --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/proposal.md @@ -0,0 +1,39 @@ +# Validate SM Flow Standard Change + +## Why + +The previous validation covered a micro change. A standard change has stricter expectations: an independent `design.md`, complete OpenSpec artifacts, and a separate `evidence.md` in devflow. + +This validation checks whether the current `sm-flow` skill can still describe and validate a normal standard change after the recent simplification work. + +## What Changes + +- Create a standard-scale validation fixture for `sm-flow`. +- Verify standard OpenSpec artifacts exist and are aligned: `proposal.md`, `design.md`, `specs/`, and `tasks.md`. +- Verify standard devflow archive artifacts exist: `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md`. +- Verify standard still uses the same four visible checkpoints and nine internal phases without exposing phase names as user commands. + +## Scope + +In scope: + +- Standard-scale validation records. +- Static checks over `.agents/skills/sm-flow`. +- Narrow fixes to the skill if standard validation reveals inconsistency. + +Out of scope: + +- Business code changes. +- Reworking archived historical changes. +- Changing the current trigger policy. + +## Non-Goals + +- This change does not test a complex migration, rollback, or cross-team interface change. +- This change does not require independent browser/manual validation. +- This change does not replace the micro validation already archived. + +## Risks + +- A standard validation fixture can become noise if left unarchived; status must be explicit. +- If standard rules are only validated by file presence, semantic drift may still require future forward-testing. diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md new file mode 100644 index 0000000..03fcbd3 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/specs/sm-flow-standard-change/spec.md @@ -0,0 +1,36 @@ +# sm-flow Standard Change Spec + +## ADDED Requirements + +### Requirement: Standard Change Has Full OpenSpec Artifacts + +A standard `sm-flow` change SHALL have `proposal.md`, independent `design.md`, `specs/`, and `tasks.md`. + +#### Scenario: Standard fixture is committed + +- **Given** a change is classified as `standard` +- **When** commit validation runs +- **Then** `proposal.md`, `design.md`, at least one spec file, and `tasks.md` exist +- **And** the artifacts are aligned from proposal to design to specs to tasks + +### Requirement: Standard Archive Has Evidence + +A standard `sm-flow` archive SHALL include `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md` in devflow. + +#### Scenario: Standard fixture is archived or accepted + +- **Given** a standard validation change has completed apply checks +- **When** devflow records are written +- **Then** `evidence.md` exists as a separate file +- **And** it records the static and script validation evidence used for acceptance + +### Requirement: Scale Definitions Remain Centralized + +Standard-specific artifact requirements SHALL be defined by `references/scales.md`; other files may reference those requirements but not carry a competing full definition. + +#### Scenario: Standard wording is scanned + +- **Given** sm-flow references mention standard behavior +- **When** scale definition phrases are scanned +- **Then** complete standard definitions appear only in `references/scales.md` +- **And** operational files defer to the current scale rather than hard-coding alternative standard rules diff --git a/openspec/archive/2026-07-05-validate-sm-flow-standard-change/tasks.md b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/tasks.md new file mode 100644 index 0000000..d3d3c09 --- /dev/null +++ b/openspec/archive/2026-07-05-validate-sm-flow-standard-change/tasks.md @@ -0,0 +1,29 @@ +# Tasks + +## 1. Standard OpenSpec Fixture + +- [x] 1.1 Create `proposal.md`. +- [x] 1.2 Create independent `design.md`. +- [x] 1.3 Create at least one spec under `specs/`. +- [x] 1.4 Create `tasks.md`. + +## 2. Standard Validation + +- [x] 2.1 Run scale duplication scan. +- [x] 2.2 Run obsolete wording scan. +- [x] 2.3 Run skill quick validation. +- [x] 2.4 Run reference integrity scan. + +## 3. Commit Gate + +- [x] 3.1 Confirm OpenSpec artifact completeness. +- [x] 3.2 Confirm proposal -> design -> specs -> tasks alignment. +- [x] 3.3 Create `.committed`. + +## 4. Devflow Records + +- [x] 4.1 Create `brief.md`. +- [x] 4.2 Create separate `evidence.md`. +- [x] 4.3 Create `decisions.md`. +- [x] 4.4 Create `acceptance.md`. +- [x] 4.5 Update `devflow/index.md`. diff --git a/skill-workbench/docs/sm-flow/workflow.md b/skill-workbench/docs/sm-flow/workflow.md index dbb7b4e..422a50c 100644 --- a/skill-workbench/docs/sm-flow/workflow.md +++ b/skill-workbench/docs/sm-flow/workflow.md @@ -1,6 +1,6 @@ # SM-Flow 工作流 -## 当前设计理念（v4 方向） +## 当前设计理念（v4.3） **核心定位**：sm-flow 是一个**用提示词实现的协议层 harness**——编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。 @@ -22,6 +22,15 @@ sm-flow → 编排层（harness）：阶段、门控、产物约束、人 | `/sm-flow apply` | 只执行（已有 Committed OpenSpec） | | `/sm-flow archive` | 收尾（回填 devflow + 归档确认） | +**触发边界**： + +sm-flow 只在用户显式调用时使用： + +- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。 +- 用户用自然语言明确要求“使用 sm-flow”“走 sm-flow 流程”或等价表达。 + +不要根据任务类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。 + **内部阶段（9 个，英文动词命名）**： ``` @@ -29,7 +38,7 @@ clarify → context → propose → grill → specify → audit → commit → a 入口澄清 上下文 轻量提案 澄清 细化 审计 提交 执行 归档 ``` -阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。 +阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。 **关键设计决策**： @@ -37,7 +46,9 @@ clarify → context → propose → grill → specify → audit → commit → a - **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 简化检查），但保留最关键的门控。 +- **micro ≠ skip**：micro 是 standard 的减法，不是跳过流程。它可以合并 checkpoint、减少独立产物，但仍保留 context、grill、commit、apply 和 archive gate。 +- **分档单一来源**：`micro / standard / complex` 的完整定义只放在 `.agents/skills/sm-flow/references/scales.md`，其它文件只引用当前分档要求。 +- **能力来源显式声明**：每个阶段都要说明使用外部子 skill、OpenSpec CLI 还是 sm-flow 内置 fallback；fallback 不是跳过阶段，必须写入 `decisions.md` 或 `acceptance.md`。 - **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。 **使用方式**： @@ -92,14 +103,14 @@ Phase 4 openspec:apply Phase 2 grill-with-docs → CONTEXT.md + ADR ## 新增技能的投入产出 -| 技能 | 学多久 | 一次省多少 | 什么时候用 | +| 技能 | 接入成本 | 主要收益 | 什么时候用 | |------|--------|-----------|-----------| -| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 | -| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 | -| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 | -| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 | -| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 | -| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 | +| to-prd | 自动综合 | 结构化需求 | openspec research 结束后 | +| grill-with-docs | 替换已有 grill-me | 产出文档化澄清 | 需求澄清阶段 | +| zoom-out | 低 | 避免方向性返工 | grill 完成后、apply 前 | +| diagnose | 低 | 减少猜测式 bug 修复 | apply 中遇到问题 | +| tdd | 低 | 减少回归 bug | apply 中写代码 | +| git-guardrails | 被动生效 | 防止灾难性操作 | 全程自动 | ## 为什么这套组合优于单纯依赖 openspec @@ -804,7 +815,7 @@ v4： | # | 问题 | 具体表现 | 分析结论 | |---|------|----------|----------| -| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求小时 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 | +| 1 | propose 阶段越界 | 在 propose 阶段一次性生成了 proposal + design + specs + tasks，跳过 grill 和 specify | 需求较小场景下 agent 本能跳过门控。现有硬约束 #3（不得跳过 grill）和阶段流程顺序已覆盖，属于执行层面问题，不需要改协议 | | 2 | 子 skill 伪调用 | grill 阶段读了 grill-with-docs 的 SKILL.md 后自行执行，audit 阶段跳过了 zoom-out | Skill 工具调用和 Read 后执行效果等价，关键是"不能跳过"而非"用什么工具调用"。硬约束 #6 已覆盖，不需要改协议 | | 3 | spec 遗漏用户行为 | spec 写的是"添加 .expanded class"（实现细节），没有写"展开后显示完整正文"（用户可观察行为） | 导致第一版实现只切换了 CSS class，正文内容仍显示截断文本。spec 应描述用户可观察的结果而非实现方式 | @@ -852,7 +863,7 @@ v4： #### 修改 2：apply 阶段增加 Pre-apply Checkpoint -在 apply 阶段开始前增加 15-20 分钟的强制调研步骤： +在 apply 阶段开始前增加强制调研步骤： **触发条件**（3 条）： - design 或 tasks 中提到"参考 XXX 实现" @@ -860,12 +871,12 @@ v4： - 技术栈不熟悉或第一次在该项目实现类似功能 **执行步骤**（3 步）： -1. **完整阅读所有参考实现**（约 10 分钟） +1. **完整阅读所有参考实现** - 从 OpenSpec design 或 tasks 中定位参考实现文件 - 如果路径不明确，通过 Grep 搜索关键类名或模式 - 逐行理解关键逻辑，提取可复用代码片段和模式 -2. **Grep 关键技术栈**（约 5 分钟） +2. **Grep 关键技术栈** - 请求/响应结构模式 - 消息队列模式 - 统一工具类 @@ -883,7 +894,7 @@ v4： - ✅ 已列出所有参考实现的文件路径 - ✅ 已识别需要新建的工具类/基础设施 -**快速模式支持**：micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单。 +**快速模式支持**：micro 分档可按风险缩小调研范围，但仍需形成清单。 #### 修改 3：apply 实现过程增强 @@ -905,15 +916,10 @@ v4： |------|------|------|------| | 返工次数 | 4-5 次 | 0-1 次 | -80% | | 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% | -| 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% | -| 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 | **ROI 分析**： -``` -投入：15-20 分钟调研 -回报：节省 60 分钟返工 + 避免核心功能遗漏 -ROI = (60 - 20) / 20 = 200% -``` + +前置调研的收益来自减少返工和避免核心功能遗漏。v4.3 之后不再用固定投入指标定义投入或收益，改按风险和实现复杂度决定调研深度。 ### 复杂度评估 @@ -941,7 +947,7 @@ ROI = (60 - 20) / 20 = 200% - 设计文档提到"参考 XXX 实现" 🟡 **可选执行**： -- micro 分档的简单需求（可缩短为 5-10 分钟） +- micro 分档的简单需求（可按风险缩小范围） - 纯数据处理或工具脚本（技术栈熟悉） ❌ **不推荐**： @@ -1002,7 +1008,7 @@ v4.2 不增加新阶段或新规则，而是**把现有约束变成可验证的 2. 如不存在： - 汇报：Draft OpenSpec 未通过 commit 检查 - 列出缺失的 checkpoint 项 - - 询问用户：是否补做 commit，或明确跳过（需显式确认） + - 询问用户：是否补做 commit；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass` #### 修改 3：Archive 阶段增加强制执行顺序 @@ -1115,3 +1121,115 @@ v4.2 的改进是执行机制层面的，不涉及业务逻辑： - 修改文件： - `.agents/skills/sm-flow/references/phase-contracts.md` - `.agents/skills/sm-flow/references/archive-rules.md` + +## v4.3：显式触发、分档单一来源与验证闭环（2026-07-05） + +### 背景 + +v4.2 之后，流程门控更可靠，但 skill 本身开始显得庞大：frontmatter、触发规则、分档规则、fallback、术语解释和阶段契约交织在一起。实际 review 中发现几个风险： + +- 触发范围容易被写宽，导致任务只要涉及 OpenSpec、跨模块或 devflow 就自动触发 sm-flow。 +- `micro / standard / complex` 的规则散落在多个文件里，后续维护容易不一致。 +- `micro`、`standard`、`complex` 的要求同时分布在不同文件中，review 时很难判断哪个是权威。 +- 规则中出现固定投入估算，容易把经验值误读成流程标准。 +- fallback、checkpoint、Draft/Committed 等词缺少统一词条，解释容易漂移。 + +### 核心结论 + +v4.3 保留 v4 的精华，但收紧触发面、降低重复定义，并用真实 change 验证 micro 和 standard 两条路径： + +- **只显式触发**：sm-flow 只在用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`，或自然语言明确要求“使用 sm-flow / 走 sm-flow 流程”时触发。 +- **不按需求类型自动触发**：OpenSpec、跨模块、接口契约、需求澄清、devflow 归档都不是自动触发条件。 +- **4 个用户可见 checkpoint 保留**：Discover、Commit、Apply、Archive。 +- **9 个内部阶段保留**：clarify → context → propose → grill → specify → audit → commit → apply → archive。 +- **分档单一来源**：`references/scales.md` 是 `micro / standard / complex` 的唯一完整规则源。 +- **fallback 独立成文**：外部 OpenSpec 能力或子 skill 不可用时，使用 `references/fallbacks.md`，并记录 capability source、影响和剩余风险。 +- **词条独立成文**：`references/glossary.md` 统一 checkpoint、fallback、Draft、Committed、gate、scale 等术语。 +- **不使用固定投入指标**：skill 规则不再用具体投入单位或时间盒定义分档、努力程度或验证阈值。 + +### 文件结构调整 + +新增 reference： + +```text +.agents/skills/sm-flow/references/ +├── fallbacks.md # 外部 OpenSpec/子 skill 不可用时的内置协议 +├── glossary.md # checkpoint/gate/fallback/Draft/Committed/scale 等术语 +└── scales.md # micro / standard / complex 的唯一完整定义 +``` + +职责调整： + +- `SKILL.md`：只保留触发边界、四层架构、6 条硬约束、4 个用户命令、4 个 checkpoint、9 个内部阶段和首次加载规则。 +- `phase-contracts.md`：保留阶段进入条件、动作、输出和退出条件；涉及分档时只引用 `scales.md`。 +- `operating-rules.md`：保留启动检查、进度汇报、接口影响、devflow 分层和完成标准；不再重复定义分档细节。 +- `archive-rules.md`：只定义归档顺序、提取映射和索引规则；产物分档引用 `scales.md`。 +- `templates.md`：保留模板和检查表，不再作为分档规则来源。 + +### 分档验证 + +#### micro 验证 + +验证 change：`validate-sm-flow-explicit-trigger` + +归档位置： + +```text +openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/ +devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/ +``` + +验证内容： + +- 显式触发规则生效：没有 `/sm-flow` 或明确“使用 sm-flow”时，不自动触发正式 sm-flow。 +- micro 可以使用内联设计小节，但仍需要 `proposal.md`、`specs/`、`tasks.md`、`.committed` 和 devflow 回填。 +- 发现并修复一个真实不一致：部分阶段契约仍硬编码 `design.md`，与 micro 允许等价设计小节冲突；已改为“设计产物”。 +- devflow micro 档案使用 `brief.md`、`decisions.md`、`acceptance.md`；证据并入过程日志。 + +#### standard 验证 + +验证 change：`validate-sm-flow-standard-change` + +归档位置： + +```text +openspec/archive/2026-07-05-validate-sm-flow-standard-change/ +devflow/projects/2026-07-05-validate-sm-flow-standard-change/ +``` + +验证内容： + +- standard 需要完整 OpenSpec 四件套：`proposal.md`、独立 `design.md`、`specs/`、`tasks.md`。 +- standard devflow 档案需要 `brief.md`、独立 `evidence.md`、`decisions.md`、`acceptance.md`。 +- 分档定义扫描只命中 `references/scales.md`，没有发现其它文件重新定义 standard/micro/complex。 +- standard 路径未发现新的规则不一致。 + +### 验证命令与结果 + +本轮验证通过： + +- `python C:/Users/兜/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/sm-flow` +- `references/*.md` 引用完整性扫描 +- 旧问题词扫描：固定投入指标、旧跳过语义、旧 conflict 表达、旧固定设计文件组合表达 +- 分档重复定义扫描 +- micro 和 standard OpenSpec/devflow 文件存在性检查 + +### 当前取舍 + +- 保留 3 个分档：`micro`、`standard`、`complex`。它们不是三套流程，而是同一流程在产物和审查强度上的三档覆盖。 +- 不引入显式状态文件，例如 `.sm-flow-state`。当前只保留 `.committed` 和 `.archive-ready` 两个必要 gate 文件。 +- 不把内部 9 阶段暴露成用户 API。用户交互继续以 4 个 checkpoint 为主。 +- 不默认做 OpenSpec archive；archive 仍是用户确认后的动作。 + +### 对 v4.1/v4.2 的修正 + +v4.1 的 Pre-apply Research 仍然保留，但不再用固定投入指标描述执行深度。当前规则是：按 `references/scales.md` 的当前分档和实现风险决定调研深度，退出判断以技术栈清单是否足以指导实现为准。 + +v4.2 的 `.committed` 和 `.archive-ready` 继续保留。v4.3 只是把文件完整性检查改为“按当前分档要求执行”，避免 standard 的独立 `design.md` 要求误套到 micro。 + +### 相关档案 + +- `devflow/projects/2026-07-05-validate-sm-flow-explicit-trigger/` +- `devflow/projects/2026-07-05-validate-sm-flow-standard-change/` +- `openspec/archive/2026-07-05-validate-sm-flow-explicit-trigger/` +- `openspec/archive/2026-07-05-validate-sm-flow-standard-change/`