Compare commits
10
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 aruo
|
e4f6e013a5 | ||
 osiman
|
433f7a93a4 | ||
|
zhuyongxin
|
c9a6777340 | ||
|
zhuyongxin
|
b94ee31cb1 | ||
|
zhuyongxin
|
9b44dc1395 | ||
|
zhuyongxin
|
63994b6440 | ||
|
zhuyongxin
|
71e0b7f801 | ||
|
zhuyongxin
|
1f01e30c4e | ||
|
zhuyongxin
|
54741dd6c0 | ||
|
zhuyongxin
|
6a5520db33 |
+78
-103
@@ -1,132 +1,107 @@
|
||||
---
|
||||
---
|
||||
name: sm-flow
|
||||
description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
|
||||
description: OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。
|
||||
---
|
||||
|
||||
# SM Flow
|
||||
|
||||
SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。
|
||||
SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
|
||||
|
||||
## 角色定位
|
||||
sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。
|
||||
|
||||
你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。
|
||||
## 触发规则
|
||||
|
||||
## 真理源分层
|
||||
只在用户显式调用时使用 sm-flow：
|
||||
|
||||
- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
|
||||
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
|
||||
- 代码是实现结果：只能在执行真理源足够明确后修改。
|
||||
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
|
||||
- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
|
||||
- 用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。
|
||||
|
||||
不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
|
||||
|
||||
## 四层架构
|
||||
|
||||
```
|
||||
sm-flow → 编排层（harness）：阶段、门控、产物约束、人类对齐
|
||||
OpenSpec → 执行引擎：propose/apply/archive 的能力提供方
|
||||
devflow/ → 记忆层：为编排层提供上下文，接收执行结果的回填
|
||||
code → 实现结果：apply 的产出
|
||||
```
|
||||
|
||||
- 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 的主要执行依据。
|
||||
- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
|
||||
- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
|
||||
- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
|
||||
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
|
||||
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
|
||||
- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
|
||||
- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
|
||||
- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
|
||||
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
|
||||
以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 `references/phase-contracts.md`。
|
||||
|
||||
1. **OpenSpec 是唯一执行真理源**。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
|
||||
2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
|
||||
3. **不得跳过 grill**。必须按 `references/scales.md` 的当前分档要求完成澄清或验证。
|
||||
4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
|
||||
5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
|
||||
6. **能力来源必须显式声明**。每个阶段先声明使用外部子 skill / OpenSpec CLI / sm-flow 内置协议；外部能力不可用时可使用 `references/fallbacks.md` 的内置协议，但必须标注为 fallback。若外部能力和内置协议都不可用，流程失败。
|
||||
|
||||
每个阶段的过程约束（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 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
|
||||
|
||||
## 可见 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/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`。
|
||||
- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
|
||||
- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。
|
||||
- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
|
||||
|
||||
## 启动检查
|
||||
## 内部阶段
|
||||
|
||||
1. 判断启动模式：
|
||||
- 完整模式：用户提供粗略想法或初始 PRD。
|
||||
- Research 模式：用户已有 research，需要转成或修正 OpenSpec。
|
||||
- PRD 文件模式：用户提供已有 PRD 路径。
|
||||
- 指定阶段模式：用户要求从某个 Phase 恢复。
|
||||
- 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。
|
||||
2. 如果缺少 `devflow/`，初始化：
|
||||
- `devflow/projects/`
|
||||
- `devflow/glossary/CONTEXT.md`
|
||||
- `devflow/compound/`
|
||||
- `devflow/reference/`
|
||||
3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
|
||||
4. 检查 OpenSpec 和子 skill 是否可用：
|
||||
- OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
|
||||
- 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
|
||||
5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
|
||||
9 个内部阶段，按执行顺序：
|
||||
|
||||
## 项目标识
|
||||
|
||||
整个流程使用同一个 slug：
|
||||
|
||||
- 优先使用 OpenSpec change name。
|
||||
- 如果还没有 change name，则从功能标题生成 kebab-case slug。
|
||||
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
|
||||
- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。
|
||||
|
||||
## Devflow 产物分层
|
||||
|
||||
devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。
|
||||
|
||||
**必须产物**：
|
||||
|
||||
- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。
|
||||
- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。
|
||||
- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。
|
||||
- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
|
||||
|
||||
**按需产物**：
|
||||
|
||||
- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。
|
||||
- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。
|
||||
- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。
|
||||
- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
|
||||
- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。
|
||||
- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。
|
||||
|
||||
**规模分档**：
|
||||
|
||||
- `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。
|
||||
|
||||
## 阶段总览
|
||||
|
||||
1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
|
||||
2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
|
||||
4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
|
||||
5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
|
||||
6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
|
||||
7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
|
||||
8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
|
||||
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`。
|
||||
|
||||
关键阶段的完成判断也以 `references/phase-contracts.md` 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。
|
||||
|
||||
## 快速模式
|
||||
|
||||
快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
|
||||
|
||||
- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
|
||||
- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
|
||||
- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
|
||||
- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
|
||||
快速模式的具体约束见 `references/operating-rules.md`。
|
||||
|
||||
## 完成标准
|
||||
|
||||
一次流程只有在满足以下条件时才算完成：
|
||||
|
||||
- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
|
||||
- 实现或规划任务已经完成，且执行依据来自 OpenSpec。
|
||||
- 已运行验证，或明确记录未运行验证的原因。
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
|
||||
- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。
|
||||
|
||||
流程完成标准见 `references/operating-rules.md`。
|
||||
|
||||
@@ -1,6 +1,49 @@
|
||||
# 归档规则
|
||||
# 归档规则
|
||||
|
||||
Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。
|
||||
archive 阶段的目标是把 OpenSpec 产物、实现结果和过程日志转化为持久、可读、可复用的项目记忆。sm-flow 在 clarify → apply 期间只维护 `decisions.md` 作为过程日志，archive 阶段从中提取完整 devflow 档案。
|
||||
|
||||
## Archive 强制执行顺序
|
||||
|
||||
Archive 阶段必须按以下顺序执行，不得跳过或重排：
|
||||
|
||||
### Step 1: 创建 devflow 档案（必需）
|
||||
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
|
||||
（从 proposal.md 提取：背景、目标、范围、非目标）
|
||||
|
||||
- [ ] 按 `references/scales.md` 的当前分档决定是否创建 `devflow/projects/YYYY-MM-DD-{slug}/evidence.md`
|
||||
（创建时从 decisions.md 提取 evidence-driven 记录）
|
||||
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
|
||||
（整理为最终版：关键决策、权衡、风险）
|
||||
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
|
||||
（记录：静态验证、脚本验证、浏览器/人工验证、未验证）
|
||||
|
||||
### Step 2: 更新索引（必需）
|
||||
|
||||
- [ ] 在 `devflow/index.md` 末尾追加或更新一行：
|
||||
`| YYYY-MM-DD | slug | 领域 | 关键词 | openspec/changes/xxx | {status} |`
|
||||
|
||||
### Step 3: 标记 OpenSpec（必需）
|
||||
|
||||
- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
|
||||
|
||||
### Step 4: 向用户汇报（必需）
|
||||
|
||||
- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在于磁盘）
|
||||
- [ ] 汇报验证情况（按静态验证、脚本验证、浏览器/人工验证、未验证分类）
|
||||
- [ ] 列出剩余风险或后续事项
|
||||
- [ ] 询问：**是否现在归档 OpenSpec？**
|
||||
|
||||
### Step 5: 用户确认后执行 OpenSpec Archive（可选）
|
||||
|
||||
- [ ] 调用 `openspec-archive-change`
|
||||
- [ ] 记录 archive 结果
|
||||
|
||||
**自检**：在执行 Step 4 前，检查 Step 1-3 是否都完成。
|
||||
|
||||
---
|
||||
|
||||
## 目录规则
|
||||
|
||||
@@ -10,12 +53,16 @@ Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为
|
||||
devflow/projects/YYYY-MM-DD-{slug}/
|
||||
```
|
||||
|
||||
默认创建以下必要文件：
|
||||
archive 阶段按 `references/scales.md` 的当前分档创建以下文件：
|
||||
|
||||
- `brief.md`
|
||||
- `evidence.md`
|
||||
- `decisions.md`
|
||||
- `acceptance.md`
|
||||
- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
|
||||
- `evidence.md`：从 decisions.md 中的 evidence-driven 记录提取；是否独立创建按 `references/scales.md` 执行。
|
||||
- `decisions.md`：保持为最终版，整理格式。
|
||||
- `acceptance.md`：从实现结果和验证结果提取。
|
||||
|
||||
同时维护仓库级索引：
|
||||
|
||||
- `devflow/index.md`
|
||||
|
||||
按需创建以下扩展文件：
|
||||
|
||||
@@ -30,25 +77,40 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
|
||||
## 产物分档
|
||||
|
||||
| 分档 | 适用场景 | 必须文件 | 扩展文件 |
|
||||
| --- | --- | --- | --- |
|
||||
| `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 阶段的创建顺序、提取映射和索引规则。
|
||||
|
||||
## 提取映射
|
||||
|
||||
| 来源 | 提取内容 | 写入位置 |
|
||||
| --- | --- | --- |
|
||||
| `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` |
|
||||
| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||||
| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
|
||||
|
||||
## 索引维护规则
|
||||
|
||||
`devflow/index.md` 是 context 阶段的默认入口，archive 阶段回填时必须维护。
|
||||
|
||||
最小字段：
|
||||
|
||||
| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
|
||||
规则：
|
||||
|
||||
- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
|
||||
- archive 阶段新建或更新项目档案时，必须新增或更新对应行。
|
||||
- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
|
||||
- 关键词只放能帮助 context 阶段定位的术语，不复制 brief 内容。
|
||||
- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
|
||||
|
||||
## 验收记录规则
|
||||
|
||||
@@ -63,7 +125,7 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
|
||||
- 如果验证通过，记录命令/步骤和覆盖范围。
|
||||
- 如果验证失败，记录失败摘要和是否阻塞验收。
|
||||
- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。
|
||||
- 如果需要人工验证，列出明确步骤，不要用"手动测试一下"这种模糊描述。
|
||||
|
||||
## ADR 规则
|
||||
|
||||
@@ -89,18 +151,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？
|
||||
|
||||
|
||||
|
||||
@@ -1,101 +1,49 @@
|
||||
# Fallback 协议
|
||||
# 内置执行协议
|
||||
|
||||
当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。
|
||||
本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段，而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`，说明能力来源、缺失能力、影响和剩余风险。
|
||||
|
||||
## OpenSpec 提案 fallback
|
||||
## 通用规则
|
||||
|
||||
1. 创建或识别 `openspec/changes/{slug}/`。
|
||||
2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。
|
||||
3. 写入 `proposal.md`，包含：
|
||||
- 问题
|
||||
- 建议方案
|
||||
- 范围
|
||||
- 非目标
|
||||
- 来自 devflow 的上下文约束
|
||||
- 风险
|
||||
4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。
|
||||
5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。
|
||||
6. 只为外部可见行为或发生变化的需求编写 specs。
|
||||
7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。
|
||||
- 优先使用外部能力；只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
|
||||
- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
|
||||
- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
|
||||
- 如果内置协议也无法满足阶段退出条件，暂停并向用户说明阻塞项。
|
||||
|
||||
## OpenSpec 修正 fallback
|
||||
## grill 内置协议
|
||||
|
||||
当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：
|
||||
- 建立 question pool，至少覆盖术语、边界、验收；涉及参考实现或项目基础设施时加入技术实现问题。
|
||||
- 将问题标记为 `evidence-driven` 或 `user-interview`。
|
||||
- 先查证 evidence-driven 问题并汇报结论，再逐个询问 user-interview 问题。
|
||||
- 按 `references/scales.md` 的当前分档满足 grill 要求。
|
||||
- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`；影响实现的结论回写 `proposal.md`。
|
||||
|
||||
1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
|
||||
2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
|
||||
3. 向用户汇报冲突和推荐修正。
|
||||
4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
|
||||
5. 再同步更新 devflow 文档；不要只改 devflow。
|
||||
## openspec 提案内置协议
|
||||
|
||||
## OpenSpec 执行 fallback
|
||||
- 在 `openspec/changes/{slug}/` 创建或更新：
|
||||
- `proposal.md`：问题、方案、范围、非目标、上下文约束、风险。
|
||||
- 设计产物：实现设计、接口影响、关键决策、架构风险；形式按 `references/scales.md` 的当前分档要求执行。
|
||||
- `specs/*/spec.md` 或等价 functional spec：描述用户可观察行为和验收场景。
|
||||
- `tasks.md`：按可执行切片拆分任务，并给每项写可验证验收标准。
|
||||
- 运行 cross-artifact 对齐检查：proposal → 设计产物 → specs → tasks。
|
||||
- 如果发现 gap，先修正 OpenSpec，再进入 commit。
|
||||
|
||||
仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。
|
||||
## audit 内置协议
|
||||
|
||||
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
|
||||
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
|
||||
3. 修改前先检查现有代码。
|
||||
4. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
5. 用最窄但有效的命令验证每个切片。
|
||||
6. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
7. 如果失败原因不确定，停止并进入 diagnose。
|
||||
8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
|
||||
- 如果风险影响实现，修正设计产物或 `tasks.md`。
|
||||
- 将结论写入 `decisions.md`。
|
||||
|
||||
## PRD fallback
|
||||
## openspec apply 内置协议
|
||||
|
||||
优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。
|
||||
- 只依据 Committed OpenSpec 的 specs/tasks 实现；devflow 只作上下文参考。
|
||||
- 开始前检查 `.committed` 文件；缺失则返回 commit。
|
||||
- 如触发 pre-apply checkpoint，先阅读参考实现、grep 项目基础设施模式，并把技术栈清单写入 `decisions.md`。
|
||||
- 按 tasks 的纵向切片实现、验证并更新任务状态。
|
||||
- 发现冲突时按三类处理：OpenSpec 不准则修 OpenSpec，代码偏离则修代码，不确定则暂停等用户确认。
|
||||
|
||||
规则：
|
||||
|
||||
- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
|
||||
- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
|
||||
- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
|
||||
|
||||
## 文档化追问 fallback
|
||||
|
||||
1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
|
||||
2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。
|
||||
3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
|
||||
4. 对 user-interview 问题，一次只问一个并等待用户确认。
|
||||
5. 术语确认后立即更新词汇表。
|
||||
6. 影响实现的澄清必须回写 OpenSpec。
|
||||
7. 只为难以逆转的真实权衡创建 ADR。
|
||||
|
||||
快速模式的最小问题：
|
||||
|
||||
- 术语：这个概念应该使用哪个领域术语？证据是什么？
|
||||
- 边界：哪些内容明确不在范围内？是否需要用户确认？
|
||||
- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？
|
||||
|
||||
## 架构审计 fallback
|
||||
|
||||
产出一份短架构审计：
|
||||
|
||||
1. 画出输入 → 处理 → 输出。
|
||||
2. 列出相关模块和调用方。
|
||||
3. 识别耦合、数据所有权和生命周期风险。
|
||||
4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
|
||||
5. 用不超过五句话总结最大风险。
|
||||
6. 如果影响实现，回写 OpenSpec design/tasks。
|
||||
|
||||
## Diagnose fallback
|
||||
|
||||
1. 复现问题，或捕获准确失败信息。
|
||||
2. 最小化失败案例。
|
||||
3. 生成 3-5 个假设，并按可能性和验证成本排序。
|
||||
4. 修改代码前，先添加仪器化或定向检查。
|
||||
5. 判断根因属于实现问题还是 OpenSpec 规格问题。
|
||||
6. 如果是实现问题，修复被证明的最小原因。
|
||||
7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
|
||||
8. 运行回归验证。
|
||||
|
||||
## TDD fallback
|
||||
|
||||
使用纵向切片，不要水平批量写测试：
|
||||
|
||||
1. 从 OpenSpec specs 中选择一个外部可见行为。
|
||||
2. 写一个失败测试。
|
||||
3. 实现刚好让测试通过的最小代码。
|
||||
4. 只在测试通过时重构。
|
||||
5. 对下一个 OpenSpec 行为重复以上步骤。
|
||||
## openspec archive 内置协议
|
||||
|
||||
- 不删除或移动 OpenSpec change；只标记归档准备状态。
|
||||
- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。
|
||||
- 向用户汇报已创建文件、验证分类、剩余风险，并询问是否需要真实 OpenSpec archive。
|
||||
- 如果外部 archive 能力仍不可用，在 `acceptance.md` 标记 `accepted-unarchived`。
|
||||
|
||||
@@ -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 |
|
||||
@@ -0,0 +1,120 @@
|
||||
# 运行规则
|
||||
|
||||
本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。
|
||||
|
||||
## 接口影响分级
|
||||
|
||||
接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。
|
||||
|
||||
| 级别 | 判断条件 | 产物要求 |
|
||||
| --- | --- | --- |
|
||||
| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
|
||||
| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
|
||||
| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
|
||||
| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
|
||||
|
||||
判断策略：
|
||||
|
||||
- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
|
||||
- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
|
||||
- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
|
||||
- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
|
||||
|
||||
## 启动检查
|
||||
|
||||
1. 识别用户命令意图：
|
||||
- `/sm-flow`（无参数）：完整流程，从 clarify 开始。
|
||||
- `/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；具体分档规则见 `references/scales.md`。
|
||||
3. 如果缺少 `devflow/`，初始化：
|
||||
- `devflow/projects/`
|
||||
- `devflow/glossary/CONTEXT.md`
|
||||
- `devflow/compound/`
|
||||
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 或子 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`；无论分档如何，都不要把内部阶段名当作用户操作入口。
|
||||
|
||||
## 项目标识规则
|
||||
|
||||
- 整个流程使用同一个 slug。
|
||||
- 优先使用 OpenSpec change name。
|
||||
- 如果还没有，则从功能标题生成 kebab-case slug。
|
||||
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
|
||||
- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
|
||||
|
||||
## Devflow 产物分层
|
||||
|
||||
Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。
|
||||
|
||||
**过程日志**（clarify → apply 期间维护）：
|
||||
|
||||
- `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。
|
||||
|
||||
**最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：
|
||||
|
||||
- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
|
||||
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
|
||||
- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
|
||||
|
||||
**按需产物**（archive 阶段按需创建）：
|
||||
|
||||
- `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 / standard / complex` 的唯一规则源是 `references/scales.md`。
|
||||
|
||||
## 快速模式
|
||||
|
||||
快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。
|
||||
|
||||
无论什么模式，以下内容必须保留：
|
||||
|
||||
- context 最小上下文收集：至少检查 glossary 和相关 ADR。
|
||||
- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
|
||||
- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
|
||||
- apply 仍由 OpenSpec tasks/specs 驱动执行。
|
||||
- archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
|
||||
|
||||
## 完成标准
|
||||
|
||||
只有同时满足以下条件，流程才算完成：
|
||||
|
||||
- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
|
||||
- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
|
||||
- 实现或规划工作已完成，且执行依据来自 OpenSpec。
|
||||
- 已运行验证，或已记录未运行验证的原因。
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
|
||||
- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
|
||||
@@ -1,8 +1,22 @@
|
||||
# 阶段契约
|
||||
# 阶段契约
|
||||
|
||||
本文件是 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 — 入口澄清
|
||||
- context — 上下文收集
|
||||
- propose — 轻量 propose
|
||||
- grill — 人类对齐澄清
|
||||
- specify — 细化 + 对齐
|
||||
- audit — 架构审计
|
||||
- commit — Commit OpenSpec
|
||||
- apply — OpenSpec 执行
|
||||
- archive — 回填 + 归档
|
||||
|
||||
## clarify — 入口澄清
|
||||
|
||||
**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
|
||||
|
||||
@@ -11,6 +25,7 @@
|
||||
- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
|
||||
- 如果输入过于模糊，最多追加三轮聚焦问题。
|
||||
- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
|
||||
- 如果需要判断 `micro / standard / complex` 分档，补读 `references/scales.md`。
|
||||
|
||||
**退出条件**：
|
||||
- 问题可以用 1-2 句话说清楚。
|
||||
@@ -23,113 +38,144 @@
|
||||
- 初步 slug。
|
||||
- devflow 规模分档：`micro` / `standard` / `complex`。
|
||||
|
||||
## Phase 0.5 — Devflow 上下文收集
|
||||
## context — 上下文收集
|
||||
|
||||
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
|
||||
**进入条件**：clarify 已经有足够信息定位领域、项目或变更方向。
|
||||
|
||||
**动作**：
|
||||
- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
|
||||
- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
|
||||
- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
|
||||
- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
|
||||
- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
|
||||
- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
|
||||
- 记录哪些上下文会影响 OpenSpec proposal、设计产物、specs 或 tasks。
|
||||
- 如果发现旧根目录 `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 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
|
||||
**执行者**：sm-flow 内置协议。**不调用 openspec-propose**（完整 OpenSpec 产物留待 specify 阶段生成）。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-propose`。
|
||||
- 如果不可用，执行 `references/fallbacks.md#openspec-propose-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/<slug>/proposal.md` 存在。
|
||||
- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
|
||||
- 关键假设已显式记录在 OpenSpec 或 research 中。
|
||||
- `openspec/changes/{slug}/proposal.md` 存在。
|
||||
- 关键假设已显式记录。
|
||||
|
||||
**输出**：
|
||||
- OpenSpec proposal、design、specs 和 task list。
|
||||
- Draft OpenSpec proposal.md（轻量版）。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
|
||||
- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
|
||||
- 向用户简要说明 proposal 范围、关键假设、主要风险、devflow 上下文如何影响方案。
|
||||
- 作为 Discover checkpoint 的中间状态汇报；询问是否继续完成 Discover 的人类澄清部分。用户明确要求"全自动执行"时可跳过等待。
|
||||
|
||||
## 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`。
|
||||
- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
|
||||
- OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
|
||||
- OpenSpec 是否使用 glossary 中的正确术语。
|
||||
- OpenSpec 是否遵守相关 ADR。
|
||||
- specs 是否能表达可观察行为。
|
||||
- tasks 是否能驱动实现，而不是泛泛描述。
|
||||
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
|
||||
|
||||
**退出条件**：
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
- `brief.md`，以及按需创建的 `prd.md`。
|
||||
- OpenSpec 对齐检查记录。
|
||||
- 必要的 OpenSpec 修正。
|
||||
|
||||
## Phase 2 — Human-in-the-loop 澄清
|
||||
|
||||
**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
|
||||
|
||||
**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
|
||||
**能力来源**：优先使用 `grill-with-docs`；不可用时使用 `references/fallbacks.md#grill-内置协议`，并在 `decisions.md` 标注 fallback。
|
||||
|
||||
**动作**：
|
||||
- 优先使用 `grill-with-docs`。
|
||||
- 先声明本阶段采用的澄清模式，并逐项标记：
|
||||
- 进入 grill 时先建立一个 question pool，并记录到 `decisions.md`：
|
||||
- 默认至少覆盖术语、边界、验收三个维度。
|
||||
- **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
|
||||
- 参考实现的具体文件路径是什么？
|
||||
- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
|
||||
- 有哪些技术点需要先调研或新建？
|
||||
- 如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，先把这些维度补进问题池。
|
||||
- 逐项标记每个问题的模式：
|
||||
- `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
|
||||
- 至少覆盖三个维度：术语、边界、验收。
|
||||
- evidence-driven 和 user-interview 的推进节奏：先批量查证 evidence-driven 并一次性汇报结论，再逐个处理 user-interview 问题。不要把所有问题攒到最后一起问。
|
||||
- 一次只问一个 `user-interview` 问题。
|
||||
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
|
||||
- 每个 `user-interview` 问题必须等待用户显式回答，并在 decisions.md 中记录：问题原文、用户原话、确认状态（已确认/未确认）。未确认的问题不能从 question pool 移除。
|
||||
- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 apply 或修改执行目标文件的授权。
|
||||
- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
|
||||
- 如果澄清结果影响实现，必须回写 proposal.md。
|
||||
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
|
||||
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
|
||||
|
||||
**退出条件**：
|
||||
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
|
||||
- question pool 已建立并覆盖当前 change 所需维度。
|
||||
- 已满足 `references/scales.md` 中当前分档的 grill 要求。每个问题都必须记录属于 `evidence-driven` 还是 `user-interview`。
|
||||
- 所有 evidence-driven 结论已向用户汇报。
|
||||
- 所有 user-interview 决策已获得用户确认。
|
||||
- 影响实现的结论已回写 OpenSpec。
|
||||
- 没有未解决或代理代确认的 user-interview 问题。
|
||||
- 没有未判级或未确认的接口影响问题。
|
||||
- 影响实现的结论已回写 proposal.md。
|
||||
- 单个 grill 决策确认不等于 apply 授权；grill 完成后必须停在 commit，等待用户明确要求进入 apply。
|
||||
- question pool、evidence-driven 结论、user-interview 确认必须写入 `decisions.md` 文件，不能只记录在对话中。
|
||||
|
||||
**输出**：
|
||||
- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
|
||||
- 更新后的 OpenSpec。
|
||||
- 更新后的 proposal.md。
|
||||
- 澄清记录：写入 `decisions.md`。包含 question pool、evidence-driven 汇报状态、user-interview 确认状态。
|
||||
- 更新后的词汇表和 ADR。
|
||||
|
||||
## Phase 2.5 — 架构审计
|
||||
**Human checkpoint**：
|
||||
- 汇报已解决和未解决的问题、proposal 变更、术语和 ADR 更新。
|
||||
- 汇报 Discover checkpoint 完成情况，并询问是否继续进入 Commit checkpoint。
|
||||
|
||||
**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
|
||||
## specify — 细化 + 对齐
|
||||
|
||||
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
|
||||
**进入条件**：grill 已退出，需求已通过澄清稳定下来。
|
||||
|
||||
**能力来源**：优先使用 `openspec-propose`（基于已稳定的 proposal 补全完整 OpenSpec）；按需使用 `to-prd`。进入本阶段必须先声明调用方式；外部能力不可用时使用 `references/fallbacks.md#openspec-提案-内置协议`，并在 `decisions.md` 标注 fallback。
|
||||
|
||||
**动作**：
|
||||
- 基于已稳定的 proposal.md 补全设计产物、specs/、tasks.md：
|
||||
- 优先调用 `openspec-propose`，输入中明确说明"proposal.md 已存在，本次只需按当前分档补全设计产物/specs/tasks"。
|
||||
- 如果不可用，执行 `references/fallbacks.md#openspec-提案-内置协议`。
|
||||
- 如果没有结构化 PRD，按需按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
|
||||
- 独立 PRD 是否需要按 `references/scales.md` 的当前分档和用户要求判断。
|
||||
- 用 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 文档。
|
||||
|
||||
**退出条件**：
|
||||
- OpenSpec 细化产物存在且与 proposal 对齐；产物形态按 `references/scales.md` 的当前分档要求执行。
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- cross-artifact 对齐检查表已生成（4 行，每行标记已对齐/存在 gap），没有未处理 gap。
|
||||
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已标记。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
- Draft OpenSpec：按 `references/scales.md` 的当前分档要求生成 proposal、设计、specs 和 tasks。
|
||||
- `brief.md`，以及按需创建的 `prd.md`。
|
||||
- cross-artifact 对齐检查表（写入 checkpoint 或 decisions.md）。
|
||||
- 必要的 OpenSpec 修正。
|
||||
|
||||
## audit — 架构审计
|
||||
|
||||
**进入条件**：specify 已退出，完整 OpenSpec 产物已存在。
|
||||
|
||||
**能力来源**：优先使用 `zoom-out`；不可用时使用 `references/fallbacks.md#audit-内置协议`，并在 `decisions.md` 标注 fallback。
|
||||
|
||||
**动作**：
|
||||
- 画出输入 → 处理 → 输出的模块链路。
|
||||
@@ -137,63 +183,170 @@
|
||||
- 检查是否与既有架构、ADR、OpenSpec design 冲突。
|
||||
- 用不超过五句话写出架构风险评估。
|
||||
- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
|
||||
- 审计结论写入 `decisions.md`。
|
||||
|
||||
**退出条件**：
|
||||
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
|
||||
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
|
||||
- 架构风险已被接受，或流程返回 grill/specify 修正 OpenSpec。
|
||||
- OpenSpec 设计产物/tasks 已反映会影响实现的架构审计结论。
|
||||
|
||||
**输出**：
|
||||
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
|
||||
- 必要的 OpenSpec design/tasks 修正。
|
||||
- 架构审计记录，写入 `decisions.md`；复杂架构审计可拆出 `design.md`。
|
||||
- 必要的 OpenSpec 设计产物/tasks 修正。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
|
||||
- 作为 Commit checkpoint 的中间状态汇报；询问是否继续完成 commit gate。
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
## commit — Commit OpenSpec
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
|
||||
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
|
||||
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
|
||||
- grill 已满足 `references/scales.md` 中当前分档要求。
|
||||
- 所有 `user-interview` 问题都已获得用户显式确认。
|
||||
- audit 已经完成，或快速模式下已记录跳过原因；快速模式定义见 `references/operating-rules.md#快速模式`。
|
||||
- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
|
||||
|
||||
**动作**：
|
||||
- 检查 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 是否有独立接口文档或等价独立章节。
|
||||
- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
|
||||
- 如果检查失败，返回 propose、grill、specify 或 audit 修正 Draft OpenSpec。
|
||||
|
||||
**退出条件**：
|
||||
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
|
||||
- **文件完整性检查**（按 `references/scales.md` 的当前分档要求执行）：
|
||||
- [ ] proposal 存在，且足以说明问题、建议方案、范围和非目标。
|
||||
- [ ] 设计产物存在，形式符合当前分档要求。
|
||||
- [ ] specs 存在，且表达用户可观察行为。
|
||||
- [ ] tasks 存在，且任务可执行、验收标准可验证。
|
||||
- **一致性检查**（必须通过）：
|
||||
- [ ] proposal 中的核心概念在设计产物中有对应设计
|
||||
- [ ] 设计产物中的关键决策在 tasks 中有对应实现任务
|
||||
- [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
|
||||
- **标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
|
||||
- 所有 preflight 风险已消除或明确记录为已接受。
|
||||
|
||||
**输出**：
|
||||
- Committed OpenSpec 状态说明。
|
||||
- preflight 检查结果，写入 `decisions.md` 或 `acceptance.md`。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
|
||||
- 汇报 Commit checkpoint 完成情况，并询问是否进入 Apply checkpoint；除非用户在启动时明确要求"全自动执行"，必须等待用户明确说出进入 apply、开始实现、执行修改或等价授权。
|
||||
- 不得把 grill 的单个决策确认当作本 checkpoint 的授权。
|
||||
|
||||
## apply — OpenSpec 执行
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/{slug}/` 中 proposal、设计产物、specs、tasks 已通过 commit，成为 Committed OpenSpec。
|
||||
- **前置门控检查**（硬约束）：
|
||||
- 检查 `openspec/changes/{slug}/.committed` 文件是否存在
|
||||
- 如不存在，执行以下流程：
|
||||
1. 汇报：Draft OpenSpec 未通过 commit 检查
|
||||
2. 列出缺失的 checkpoint 项（文件完整性、一致性检查）
|
||||
3. 询问用户：是否补做 commit 检查；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`，且本次流程不得视为合规 sm-flow apply
|
||||
- commit 后已获得用户明确的 apply 授权，除非用户在启动时要求"全自动执行"。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
|
||||
|
||||
**能力来源**：优先使用 `openspec-apply-change`；不可用时使用 `references/fallbacks.md#openspec-apply-内置协议`，并在 `decisions.md` 标注 fallback。遇到 bug/不确定行为时优先使用 `diagnose`；需要测试驱动时优先使用 `tdd`。不可用时执行对应最小协议并记录原因，不得静默跳过。
|
||||
|
||||
**动作**：
|
||||
|
||||
### Pre-apply Checkpoint
|
||||
|
||||
**触发条件**：当 OpenSpec 涉及以下任一情况时必须执行
|
||||
- design 或 tasks 中提到"参考 XXX 实现"
|
||||
- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
|
||||
- 技术栈不熟悉或第一次在该项目实现类似功能
|
||||
|
||||
**执行步骤**：
|
||||
1. **阅读所有参考实现**
|
||||
- 从 OpenSpec design 或 tasks 中定位参考实现文件
|
||||
- 如果路径不明确，通过 Grep 搜索关键类名或模式
|
||||
- 理解关键逻辑，提取可复用代码片段和模式
|
||||
|
||||
2. **Grep 关键技术栈**
|
||||
- 请求/响应结构模式（如 `RequestMsg`、`ResponseMsg`、DTO 规范）
|
||||
- 消息队列模式（如 `@KafkaListener`、`@YkMsg`、发送模板）
|
||||
- 统一工具类（如 `XxxUtil`、`XxxHelper`、加密/验签工具）
|
||||
- 异常处理和日志记录标准
|
||||
|
||||
3. **形成技术栈清单并写入 decisions.md**
|
||||
- 项目使用的请求/响应结构标准
|
||||
- MQ 消息定义和发送标准
|
||||
- Consumer 标准位置和写法
|
||||
- 加密/验签/工具类的标准用法
|
||||
- 识别需要新建的工具类或基础设施
|
||||
|
||||
**输出要求**：
|
||||
- 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节。
|
||||
- 已列出所有参考实现的文件路径。
|
||||
- 已识别需要新建的工具类/基础设施。
|
||||
|
||||
**按风险执行**：执行深度按 `references/scales.md` 的当前分档和实现风险决定；退出判断以清单是否足以指导实现为准。
|
||||
|
||||
### 实现过程
|
||||
|
||||
- 优先调用 `openspec-apply-change`。
|
||||
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
|
||||
- 按 OpenSpec tasks 的纵向切片实现。
|
||||
- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
|
||||
- 进入实现前先汇报本阶段的 capability 来源、当前 task 进度和本轮要推进的切片；否则 apply 不算真正开始。
|
||||
- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
|
||||
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，做三类判断：
|
||||
- OpenSpec 不准（规格遗漏、边界未覆盖、验收口径缺失）→ 暂停 apply，修正 OpenSpec 后重新提交。
|
||||
- 代码偏离（实现没按 OpenSpec 做）→ 修正代码，不改 OpenSpec。
|
||||
- 不确定根因、涉及设计方向、用户改变目标或范围 → 暂停并等待用户确认。
|
||||
- 判断结果、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md`。
|
||||
- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
|
||||
- 当用户要求、行为复杂或回归风险高时使用 TDD。
|
||||
- 当测试失败、行为意外或原因不确定时使用 diagnose。
|
||||
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
|
||||
- 修改文件前遵守仓库指令，例如 `AGENTS.md`。
|
||||
|
||||
**退出条件**：
|
||||
- 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`。
|
||||
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
|
||||
- 核心功能已实现或明确标注"待联调"，无纯 TODO 占位。
|
||||
- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
|
||||
- 已运行验证，或记录了未验证原因。
|
||||
- 已列出已知限制。
|
||||
|
||||
**输出**：
|
||||
- 代码变更、必要测试和实现说明。
|
||||
- 更新后的 OpenSpec task 状态。
|
||||
- 冲突记录写入 `decisions.md`。
|
||||
|
||||
## Phase 4 — 回填 Devflow
|
||||
## archive — 回填 + 归档
|
||||
|
||||
**进入条件**：实现或规划工作已经达到可交接状态。
|
||||
|
||||
**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
|
||||
**能力来源**：`openspec-archive-change` 在用户确认 archive 后优先调用；不可用时使用 `references/fallbacks.md#openspec-archive-内置协议`，并在 `acceptance.md` 标注 fallback。archive 回填由 `sm-flow` 执行。
|
||||
|
||||
**动作**：
|
||||
- 遵循 `references/archive-rules.md`。
|
||||
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
|
||||
- 从 `decisions.md`（过程日志）+ OpenSpec 产物提炼完整 devflow 档案：
|
||||
- `brief.md`：从 proposal.md 提取背景、目标、范围、非目标。
|
||||
- `evidence.md`：按 `references/scales.md` 和 `references/archive-rules.md` 的当前分档要求处理。
|
||||
- `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}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案；archive checkpoint 必须列出所有已创建的文件路径，验证文件实际存在于磁盘。
|
||||
- `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。
|
||||
|
||||
@@ -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。
|
||||
@@ -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 回写 |
|
||||
| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
|
||||
|---|---|---|---|
|
||||
| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 |
|
||||
| {question} | {user's exact words} | 已确认 / 未确认 | 已回写 / 不影响 / 待回写 |
|
||||
|
||||
## 关键取舍
|
||||
|
||||
@@ -65,6 +79,68 @@
|
||||
- 风险接受：{accepted by whom/when}
|
||||
```
|
||||
|
||||
## 接口影响记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 接口影响记录
|
||||
|
||||
## 分级
|
||||
|
||||
- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
|
||||
- 判级原因：{why this level}
|
||||
- 是否需要独立接口文档：是 / 否
|
||||
|
||||
## 变更对象
|
||||
|
||||
- 接口/字段/DTO/事件/回调/数据库契约：
|
||||
- 判断逻辑变化：
|
||||
- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
|
||||
|
||||
## 影响范围
|
||||
|
||||
- 调用方/消费者：
|
||||
- 是否跨模块/跨服务/跨团队：
|
||||
- 旧调用方是否需要改动：
|
||||
|
||||
## 兼容与迁移
|
||||
|
||||
- 是否向后兼容：
|
||||
- 迁移/灰度/回滚要求：
|
||||
- 风险接受：
|
||||
|
||||
## 验收方式
|
||||
|
||||
- 如何证明新行为正确：
|
||||
- 如何证明旧行为未破坏：
|
||||
- 需要用户确认的问题：
|
||||
```
|
||||
|
||||
## 实现期冲突记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 实现期冲突记录
|
||||
|
||||
## 冲突摘要
|
||||
|
||||
- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
|
||||
- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
|
||||
- 分类：OpenSpec 不准 / 代码偏离 / 不确定
|
||||
|
||||
## 证据
|
||||
|
||||
- OpenSpec 依据：
|
||||
- 代码或测试证据：
|
||||
- 用户反馈：
|
||||
|
||||
## 处理
|
||||
|
||||
- 决策：
|
||||
- 是否需要用户确认：是 / 否
|
||||
- OpenSpec 回写：不需要 / 已回写 / 待回写 / 等待用户确认
|
||||
- 代码处理：
|
||||
- 验证方式：
|
||||
```
|
||||
|
||||
## PRD 模板
|
||||
|
||||
```markdown
|
||||
@@ -267,6 +343,26 @@
|
||||
- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用}
|
||||
```
|
||||
|
||||
## Cross-Artifact 对齐检查表模板
|
||||
|
||||
specify 阶段的 checkpoint 必须包含此检查表。每项标记"已对齐"或"存在 gap"。
|
||||
|
||||
```markdown
|
||||
## Cross-Artifact 对齐检查
|
||||
|
||||
| 上游 → 下游 | 检查内容 | 状态 |
|
||||
|---|---|---|
|
||||
| brief/prd → proposal | 目标、范围、非目标、验收预期是否进入 proposal | 已对齐 / 存在 gap |
|
||||
| proposal → 设计产物 | 范围、约束、关键承诺是否进入 design.md 或等价设计小节 | 已对齐 / 存在 gap |
|
||||
| 设计产物 → specs/tasks | 影响实现的约束、接口影响、架构结论是否进入 specs 或 tasks | 已对齐 / 存在 gap |
|
||||
| specs → tasks | 可观察行为是否被 tasks 覆盖为可执行切片 | 已对齐 / 存在 gap |
|
||||
|
||||
### Gap 详情（如有）
|
||||
|
||||
- gap 1：{描述哪个字段/约束/行为/切片只停留在上游，未进入下游}
|
||||
- 修复：{如何修正 OpenSpec}
|
||||
```
|
||||
|
||||
## 复合知识模板
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
skill-workbench/validation/project/
|
||||
superpowers/
|
||||
.claude/
|
||||
.codex/
|
||||
*.stackdump
|
||||
|
||||
@@ -1,136 +0,0 @@
|
||||
# Skills v0.5.0 整合修复记录
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致
|
||||
|
||||
---
|
||||
|
||||
## 一句话摘要
|
||||
|
||||
在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。
|
||||
|
||||
---
|
||||
|
||||
## 已完成的改动
|
||||
|
||||
### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏）
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| 版本号 | `0.3.0` → `0.5.0` |
|
||||
| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 |
|
||||
| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point |
|
||||
| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` |
|
||||
| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 |
|
||||
| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect |
|
||||
| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） |
|
||||
|
||||
### 2. `/follow` — 消除旧引用和设计偏差
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader |
|
||||
| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） |
|
||||
| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" |
|
||||
| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 |
|
||||
|
||||
### 3. `/explore` — 合并冗余阶段
|
||||
|
||||
| 位置 | 修改内容 |
|
||||
|---|---|
|
||||
| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` |
|
||||
| 阶段总数 | 5 Phase → 4 Phase |
|
||||
| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 |
|
||||
| Outcome 模板 | `5/5` → `4/4` |
|
||||
|
||||
### 4. References 清理
|
||||
|
||||
| 文件 | 操作 |
|
||||
|---|---|
|
||||
| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 |
|
||||
| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 |
|
||||
|
||||
### 5. docs 存档清理
|
||||
|
||||
| 文件 | 操作 | 原因 |
|
||||
|---|---|---|
|
||||
| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 |
|
||||
| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 |
|
||||
| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 |
|
||||
| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 |
|
||||
|
||||
---
|
||||
|
||||
## docs 存档最终结构
|
||||
|
||||
```
|
||||
docs/superpowers/
|
||||
├── specs/
|
||||
│ ├── issue.md # 原始需求
|
||||
│ ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md
|
||||
│ └── 2026-04-21-skills-v0.5.0-changelog-design.md
|
||||
└── changelog/
|
||||
├── 2026-04-21-skills-v0.5.0-slim-architecture.md # 第一次改造 changelog
|
||||
├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令
|
||||
└── 2026-04-30-skills-v0.5.0-consolidation.md # 本次整合（本文件）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 当前 skill 状态
|
||||
|
||||
| 技能 | 版本 | Phase/Mode | 备注 |
|
||||
|---|---|---|---|
|
||||
| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure |
|
||||
| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection |
|
||||
| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 |
|
||||
|
||||
---
|
||||
|
||||
## 实践验证结果
|
||||
|
||||
**日期：** 2026-04-30
|
||||
**测试目标仓库：**
|
||||
- 非代码仓库：explore-skill-family（自身）
|
||||
- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent）
|
||||
|
||||
| # | 验证路径 | 目标 | 结果 |
|
||||
|---|---|---|---|
|
||||
| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ |
|
||||
| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start |
|
||||
| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 |
|
||||
| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 |
|
||||
| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 |
|
||||
| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 |
|
||||
| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 |
|
||||
|
||||
### 验证发现的额外修复
|
||||
|
||||
验证过程中对 SKILL.md 的追加修改（已在代码中反映）：
|
||||
- `/essence` Phase 6 → Optional: HTML Card
|
||||
- `/essence` Mode Selection 上下文感知
|
||||
- `/essence` Most imported file → Cross-module contract
|
||||
- `/follow` Mode Selection 来源感知
|
||||
- `/follow` Runnable Check 不再重扫，引用前置报告
|
||||
- `/follow` Reader Mode Flow 提升到设计层
|
||||
- `/follow` Teaching Interaction Rules 收紧
|
||||
- `/explore` Phase 1+2 合并，5→4 Phase
|
||||
- `/explore` Project Type Detection 信号改为后端导向
|
||||
- 删除 `skills/explore/references/deep-fission.md`
|
||||
|
||||
### handoff 10 条检查清单逐项结论
|
||||
|
||||
| # | 问题 | 结论 |
|
||||
|---|---|---|
|
||||
| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 |
|
||||
| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 |
|
||||
| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 |
|
||||
| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 |
|
||||
| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 |
|
||||
| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 |
|
||||
| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 |
|
||||
| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 |
|
||||
| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 |
|
||||
| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 |
|
||||
|
||||
**总体验收结论：通过。** 文档、边界、行为三者一致。
|
||||
@@ -0,0 +1,14 @@
|
||||
# Devflow Index
|
||||
|
||||
`devflow/index.md` 是 Phase 0.5 的默认上下文入口。每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认维护一行，帮助代理先定位相关项目，再读取具体 brief、acceptance、ADR 或 compound knowledge。
|
||||
|
||||
| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-05-18 | knowledge-index-panel | knowledge-index | knowledge-index, search, tags, static-html | `openspec/changes/knowledge-index-panel/` | active |
|
||||
| 2026-05-19 | add-clear-filters | knowledge-index | clear-filters, search, tags, year-filter | `openspec/changes/archive/2026-05-19-add-clear-filters/` | archived |
|
||||
| 2026-05-19 | add-year-filter | knowledge-index | year-filter, index-panel, frontmatter | `openspec/changes/add-year-filter/` | active |
|
||||
| 2026-05-19 | dev-flow-skill-evaluation | sm-flow | dev-flow, sm-flow, skill-evaluation, fallback, phase-contracts | 未关联 | accepted-unarchived |
|
||||
| 2026-05-21 | sm-flow-v3-1-upgrade | sm-flow | interface-impact, commit-gate, devflow-index, apply-conflict, skill-compatibility | `openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/` | archived |
|
||||
| 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 |
|
||||
@@ -0,0 +1,59 @@
|
||||
# SM Flow v3.1 Upgrade Acceptance
|
||||
|
||||
## 结果
|
||||
|
||||
已接受。
|
||||
|
||||
## 验证
|
||||
|
||||
### 静态验证
|
||||
|
||||
- 命令/检查：`openspec status --change "sm-flow-v3-1-upgrade"`
|
||||
- 结果：passed
|
||||
- 备注：proposal、design、specs、tasks 均为 complete。
|
||||
|
||||
- 命令/检查：`rg -n "Draft OpenSpec|Committed OpenSpec|Phase 2.9|devflow/index.md|接口影响|实现期冲突|能力契约|平台原生 skill|user-interview" ...`
|
||||
- 结果：passed
|
||||
- 备注：关键术语已覆盖 `.agents/skills/sm-flow/`、OpenSpec change、workflow 文档和 devflow 项目档案。
|
||||
|
||||
### 脚本验证
|
||||
|
||||
- 命令：`openspec instructions apply --change "sm-flow-v3-1-upgrade" --json`
|
||||
- 结果：passed
|
||||
- 备注：所有 17 个 OpenSpec tasks 已完成。
|
||||
|
||||
### 浏览器/人工验证
|
||||
|
||||
- 步骤：不适用，本次是流程文档和 OpenSpec 规则改造。
|
||||
- 结果：not run
|
||||
- 备注：无 UI 行为。
|
||||
|
||||
## 已完成范围
|
||||
|
||||
- 增加 Draft OpenSpec / Committed OpenSpec / Phase 2.9 commit gate。
|
||||
- 强化 Phase 2 grill 的显式人工确认约束。
|
||||
- 增加“单个 grill 决策确认不等于 Phase 3 apply 授权”的硬约束。
|
||||
- 增加接口影响 L1-L4 分级和接口影响记录模板。
|
||||
- 增加 `devflow/index.md` 和 Phase 0.5 / Phase 4 索引维护规则。
|
||||
- 增加 Phase 3 实现期冲突四分类和 fallback 执行规则。
|
||||
- 将子 skill 兼容规则改为能力契约优先、路径其次。
|
||||
- 更新 `skill-workbench/docs/sm-flow/workflow.md` 的 v3.1 说明。
|
||||
|
||||
## 已知限制
|
||||
|
||||
- `openspec/config.yaml` 由 OpenSpec CLI 创建并保持未跟踪状态。
|
||||
- 工作区存在与本次无关的已删除文件，未处理。
|
||||
|
||||
## 流程偏差记录
|
||||
|
||||
- 偏差：本次执行中，Phase 2 grill 决策确认后曾直接进入执行文件修改，没有显式停在 Phase 2.9 checkpoint 等待 Phase 3 apply 授权。
|
||||
- 分类：实现偏差。v3.1 规格方向正确，但执行过程没有严格遵守“grill 确认 ≠ apply 授权”的门禁。
|
||||
- 修正：已回写 OpenSpec，新增 requirement 和 task，要求 Phase 2/2.5 回写后必须停在 Phase 2.9，并等待明确 Phase 3 apply 授权。
|
||||
- 当前状态：用户已明确授权“执行apply”，该新增 requirement 已应用到 `.agents/skills/sm-flow/*` 和 workflow 文档。
|
||||
|
||||
## 交接
|
||||
|
||||
- 下一步：已归档，后续可从 devflow 档案和 OpenSpec archive 回溯。
|
||||
- OpenSpec 归档确认：用户已确认归档。
|
||||
- OpenSpec 归档位置：`openspec/changes/archive/2026-05-21-sm-flow-v3-1-upgrade/`
|
||||
- Specs 同步：未执行；本仓库 `openspec/specs/` 当前无主 spec 文件，本次保留 delta specs 于 archive 中。
|
||||
@@ -0,0 +1,30 @@
|
||||
# SM Flow v3.1 Upgrade Brief
|
||||
|
||||
## 背景
|
||||
|
||||
- 用户目标：把 `sm-flow` v3 使用中暴露的接口文档、流程顺序、上下文定位、子 skill 兼容和实现期冲突问题固化为 v3.1 协议。
|
||||
- 当前问题：v3 已经确立 OpenSpec-first，但缺少接口影响分级、Draft/Committed OpenSpec gate、devflow 索引和 Phase 3 冲突沟通规则。
|
||||
- 关联 OpenSpec：`openspec/changes/sm-flow-v3-1-upgrade/`
|
||||
- devflow 分档：standard
|
||||
|
||||
## 范围
|
||||
|
||||
- 本次要做：更新 `sm-flow` skill 本体、phase contracts、fallbacks、templates、workflow 说明，并创建/维护 devflow 索引。
|
||||
- 本次不做：修改业务代码、重写 OpenSpec CLI、把 devflow 变成执行真理源、强制所有接口变更都独立产出接口文档。
|
||||
- 影响区域：
|
||||
- `.agents/skills/sm-flow/SKILL.md`
|
||||
- `.agents/skills/sm-flow/references/*.md`
|
||||
- `skill-workbench/docs/sm-flow/workflow.md`
|
||||
- `devflow/index.md`
|
||||
|
||||
## OpenSpec 对齐
|
||||
|
||||
- proposal 覆盖状态：已覆盖
|
||||
- specs 覆盖状态：已覆盖
|
||||
- tasks 覆盖状态：已覆盖
|
||||
|
||||
## OpenSpec 输入上下文摘要
|
||||
|
||||
- v3 历史决策：`devflow/` 是上下文真理源，OpenSpec 是执行真理源，代码是实现结果。
|
||||
- 用户问题来源：`skill-workbench/docs/sm-flow/使用问题.md`，共 6 个问题，集中在接口产物、流程顺序、上下文检索、子 skill 兼容和实现期冲突。
|
||||
- 历史评估来源：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`，已确认子 skill fallback、quick 模式、Phase 退出条件和 OpenSpec-first 是 v3 的关键设计。
|
||||
@@ -0,0 +1,39 @@
|
||||
# SM Flow v3.1 Upgrade Decisions
|
||||
|
||||
## User-interview
|
||||
|
||||
| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
|
||||
| --- | --- | --- | --- |
|
||||
| 是否启动 v3.1 改造？ | “开始这次的v3.1改造” | 创建 `sm-flow-v3-1-upgrade` OpenSpec change 并进入改造。 | 已回写 |
|
||||
| grill 过程中是否必须人工确认？ | 用户要求“如果 skill 里并没有强调 grill 的过程中一定要人工确认的话，加上这个约束”。 | Phase 2 的 user-interview 问题必须一问一答等待用户显式确认；未确认不能进入 Phase 2.9 / Phase 3。 | 已回写 |
|
||||
| 接口变更是否需要记录影响范围？ | 用户要求“只要涉及接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中”。 | 所有接口变更必须有影响记录。 | 已回写 |
|
||||
| 接口影响采用什么分级策略？ | 用户确认“可以，先按照分级来实现”。 | 采用 L1-L4 分级：L1 内部实现、L2 内部接口、L3 协作接口、L4 破坏性接口；接口内部判断逻辑按可观察行为评估。 | 已回写 |
|
||||
| devflow 上下文索引是否强制维护？ | 用户确认“可以”。 | 强制维护轻量 `devflow/index.md`；Phase 0.5 先查 index，Phase 4 回填时必须更新 index。 | 已回写 |
|
||||
| 实现阶段遇到与原设计冲突的质疑或修改时如何处理？ | 用户确认“可以”。 | Phase 3 采用四类实现期冲突分类：实现偏差、规格遗漏、设计冲突、用户变更；先分类和确认，再继续代码或 OpenSpec 修正。 | 已回写 |
|
||||
| 子 skill 兼容规则是否采用能力优先？ | 用户确认“可以”。 | 子 skill 绑定能力契约，不绑定单一平台路径；调用优先级为平台原生 skill、本地 `SKILL.md`、sm-flow fallback。 | 已回写 |
|
||||
| 单个 grill 决策确认是否等于 apply 授权？ | 用户确认“可以”。 | 单个 `user-interview` 的“可以”只确认该决策；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，等待明确 Phase 3 apply 授权。 | 已回写 |
|
||||
|
||||
## Evidence-driven 澄清
|
||||
|
||||
| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 术语 | evidence-driven | “接口影响范围文档”和“接口文档”是否同一产物？ | 用户分别列为两个问题；流程需要降低文档重复。 | 区分“接口影响记录”和“独立接口文档”。 | 是 |
|
||||
| 边界 | evidence-driven | v3.1 是否要改变 OpenSpec-first 主轴？ | v3 skill 本体和历史评估都把 OpenSpec 定义为执行真理源。 | 不改变主轴，只补 gate。 | 是 |
|
||||
| 验收 | evidence-driven | 如何证明 v3.1 改造完成？ | OpenSpec specs 已覆盖接口影响、commit gate、上下文索引和 apply 冲突处理。 | 验收以文档规则可检索、OpenSpec status 完成、tasks 勾选为准。 | 是 |
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- 决策：采用 Draft / Committed OpenSpec，而不是把 grill 移到 propose 前。
|
||||
- 原因：Draft 给澄清提供结构化对象，Committed 防止草稿直接执行。
|
||||
- 影响：新增 Phase 2.9，但减少 Phase 3 规格漂移。
|
||||
- 风险接受：本次 v3.1 接受。
|
||||
|
||||
- 决策：接口变更采用 L1-L4 分级。
|
||||
- 原因：所有接口影响都需要追踪，但只有高影响变更需要独立接口文档。
|
||||
- 影响：templates 和 phase contracts 需要增加接口影响记录。
|
||||
- 风险接受：本次 v3.1 接受。
|
||||
|
||||
- 决策：为 devflow 增加 `devflow/index.md`。
|
||||
- 原因：项目档案增长后，需要索引而不是每次全量翻阅。
|
||||
- 影响：Phase 0.5 和 Phase 4 都需要维护索引。
|
||||
- 风险接受：本次 v3.1 接受。
|
||||
@@ -0,0 +1,28 @@
|
||||
# SM Flow v3.1 Upgrade Evidence
|
||||
|
||||
## 证据
|
||||
|
||||
| 来源 | 证据 | 结论 | 是否已汇报 |
|
||||
| --- | --- | --- | --- |
|
||||
| `skill-workbench/docs/sm-flow/使用问题.md` | 用户列出 6 个实践问题，包含接口文档、propose/grill 顺序、devflow 检索、子 skill 兼容、Phase 3 设计冲突。 | v3.1 应围绕这些使用摩擦改协议，而不是重写整个流程。 | 是 |
|
||||
| `.agents/skills/sm-flow/SKILL.md` | 当前核心规则已要求 Phase 0.5、Phase 2、Phase 2.5、Phase 3、Phase 4，但没有 Draft/Committed OpenSpec 和接口影响分级。 | 新规则应补 gate，不应推翻 v3 的 OpenSpec-first 主从关系。 | 是 |
|
||||
| `.agents/skills/sm-flow/references/phase-contracts.md` | Phase 1 生成 OpenSpec 后进入 Phase 1.5/2/2.5，Phase 3 以 OpenSpec 执行；缺少 Phase 2.9 提交检查。 | “propose 后 grill 返工”应通过草稿/提交分离解释和治理。 | 是 |
|
||||
| `.agents/skills/sm-flow/references/fallbacks.md` | 执行 fallback 已要求失败原因不确定时 diagnose，规格不准先修 OpenSpec。 | 可扩展为 Phase 3 实现期冲突分类，不需要新建完全独立流程。 | 是 |
|
||||
| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 Claude 工具耦合、子 skill 调用方式不稳、Phase 退出条件不足。 | v3.1 的兼容规则应绑定能力契约，而不是绑定具体平台路径。 | 是 |
|
||||
|
||||
## Evidence-driven 结论
|
||||
|
||||
- 结论：v3.1 应保留 v3 主轴，只增加 gate 和分级规则。
|
||||
- 证据：当前 skill 文件和 phase contracts 已经清楚表达 OpenSpec-first。
|
||||
- 风险：如果重写阶段顺序，容易引入新的执行歧义。
|
||||
- 用户确认：已通过“开始这次的 v3.1 改造”确认推进。
|
||||
|
||||
- 结论：接口文档应分级，不应一刀切。
|
||||
- 证据：用户同时提出“接口影响范围文档”和“接口文档”，说明需要区分影响记录与独立文档。
|
||||
- 风险：分级阈值不清会导致代理低估外部契约风险。
|
||||
- 用户确认：需要在实现时以不确定则确认为规则。
|
||||
|
||||
- 结论：Phase 3 应增加实现期沟通规则，而不是让代码建议直接覆盖 OpenSpec。
|
||||
- 证据：用户明确要求“不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到”。
|
||||
- 风险：沟通 gate 会暂停执行，但能保护规格真理源。
|
||||
- 用户确认：已确认这是 v3.1 重点。
|
||||
@@ -0,0 +1,40 @@
|
||||
# SM Flow Execution Hardening Acceptance
|
||||
|
||||
## Result
|
||||
|
||||
Implemented `sm-flow-execution-hardening` as protocol/document changes only.
|
||||
|
||||
Updated artifacts:
|
||||
|
||||
- `.agents/skills/sm-flow/SKILL.md`
|
||||
- `.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
- `.agents/skills/sm-flow/references/fallbacks.md`
|
||||
- `skill-workbench/docs/sm-flow/workflow.md`
|
||||
- `openspec/changes/sm-flow-execution-hardening/tasks.md`
|
||||
|
||||
## Verification
|
||||
|
||||
- Static verification:
|
||||
- Confirmed explicit phase checkpoint and stage-completion rules exist in `SKILL.md`.
|
||||
- Confirmed Phase 2 question-pool behavior and Phase 1.5 / 2.9 cross-artifact checks exist in `phase-contracts.md`.
|
||||
- Confirmed fallback declaration and recording requirements exist in `fallbacks.md`.
|
||||
- Confirmed `workflow.md` explains the same execution-hardening model without introducing mandatory output templates.
|
||||
- OpenSpec verification:
|
||||
- Implementation/documentation tasks `1.1` to `3.2` are complete.
|
||||
- Validation tasks `4.1` to `4.4` are complete.
|
||||
|
||||
## Acceptance Scope Check
|
||||
|
||||
- Satisfied by protocol/document changes alone: yes
|
||||
- Requires standardized phase-report output format: no
|
||||
- Requires fixed checkpoint/alignment templates: no
|
||||
|
||||
## Unverified
|
||||
|
||||
- OpenSpec CLI validation passed: `openspec validate sm-flow-execution-hardening`.
|
||||
- No automated tests were needed because this change only modifies protocol and documentation artifacts.
|
||||
|
||||
## Archive Status
|
||||
|
||||
- OpenSpec change is not archived.
|
||||
- User still needs to be asked whether to archive after validation is complete.
|
||||
@@ -0,0 +1,31 @@
|
||||
# SM Flow Execution Hardening Brief
|
||||
|
||||
## 背景
|
||||
|
||||
- 用户目标：把 `sm-flow` 在真实项目执行中暴露出的流程失真问题，提炼为下一轮协议硬化需求。
|
||||
- 当前问题：`sm-flow` 已经具备完整阶段规则，但实际执行时仍会出现跳过检查点、弱化显式声明、问题池不足、Cross-artifact 一致性检查不充分等情况。
|
||||
- 关联 OpenSpec：`openspec/changes/sm-flow-execution-hardening/`
|
||||
- devflow 分档：complex
|
||||
|
||||
## 范围
|
||||
|
||||
- 本次要做：把复盘中的执行问题整理为结构化需求，明确目标、非目标、用户故事、验收口径和建议改进方向。
|
||||
- 本次不做：立即修改 `sm-flow` 协议、直接创建 OpenSpec change、重写 `sm-flow` 主设计。
|
||||
- 影响区域：
|
||||
- `.agents/skills/sm-flow/SKILL.md`
|
||||
- `.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
- `.agents/skills/sm-flow/references/fallbacks.md`
|
||||
- `.agents/skills/sm-flow/references/templates.md`
|
||||
- `skill-workbench/docs/sm-flow/workflow.md`
|
||||
- `skill-workbench/docs/sm-flow/retrospective.md`
|
||||
|
||||
## OpenSpec 对齐
|
||||
|
||||
- proposal 覆盖状态：已覆盖
|
||||
- specs 覆盖状态：已覆盖
|
||||
- tasks 覆盖状态：已覆盖
|
||||
|
||||
## 入口摘要
|
||||
|
||||
- 这次需求关注的不是 `sm-flow` 的理念是否成立，而是它在真实执行中为什么仍然会“按代码习惯行动”，而不是“按 phase gate 行动”。
|
||||
- 目标是把这些问题固化为更强的执行约束，让后续代理在 `micro` 或 `standard` 模式下也不再轻易跳过关键阶段。
|
||||
@@ -0,0 +1,76 @@
|
||||
# SM Flow Execution Hardening Decisions
|
||||
|
||||
## User-interview
|
||||
|
||||
| 问题 | 用户回答 | 决策 | OpenSpec 回写 |
|
||||
| --- | --- | --- | --- |
|
||||
| 这次是否将复盘问题提炼为正式需求？ | “[$sm-flow] 提炼成需求” | 创建 `sm-flow-execution-hardening` 需求档案，先收敛需求，再决定是否进入 OpenSpec。 | 不影响 |
|
||||
| 是否必须产出固定 checkpoint / alignment 模板？ | “确认 1” | 不强制固定模板；协议只要求必填字段和检查动作。 | 已回写 |
|
||||
| 验收是否要求统一阶段汇报格式？ | “确认1” | 验收停在协议明确 gate、问题池和对齐规则，不要求统一阶段汇报格式。 | 已回写 |
|
||||
|
||||
## Phase 2 Tracking
|
||||
|
||||
| 问题池项 | 模式 | 状态 | 备注 |
|
||||
| --- | --- | --- | --- |
|
||||
| Q1：是否必须产出固定 checkpoint / alignment 模板 | user-interview | 待确认 | 会影响 templates.md 与 tasks 范围 |
|
||||
| Q2：协议主术语采用 checkpoint 还是 checklist | evidence-driven | 待整理 | 优先由现有文档术语一致性决定 |
|
||||
| Q3：验收是否要求统一阶段汇报格式 | user-interview | 已确认 | 验收停在规则层，不扩到统一输出格式 |
|
||||
| Q4：workflow 是否需要保留复盘案例示例 | evidence-driven | 待整理 | 主要影响 workflow 文档粒度 |
|
||||
|
||||
## Phase 2.5 审计结论
|
||||
|
||||
- 决策：主术语采用 `checkpoint`，`checklist` 作为内部核对动作描述。
|
||||
- 原因：仓库现有 `phase-contracts.md` 已使用 `Human checkpoint`，继续沿用能减少术语漂移。
|
||||
- 影响：后续协议修改应优先写“phase checkpoint”，避免在规则层混用主术语。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：`workflow.md` 不扩成案例手册，继续保留规则抽象和演进说明；具体复盘案例留在 `retrospective.md`。
|
||||
- 原因：如果把案例并入 workflow，规则与示例会双份维护，后续更容易漂移。
|
||||
- 影响：执行真理源继续留在 `SKILL.md` / `phase-contracts.md` / OpenSpec，而不是 workflow 长文。
|
||||
- 风险接受：当前接受
|
||||
|
||||
## Phase 2.9 Commit Result
|
||||
|
||||
- 决策：`sm-flow-execution-hardening` 当前 Draft OpenSpec 通过 commit gate，视为 Committed OpenSpec。
|
||||
- 原因：proposal、design、specs、tasks 已完整；user-interview 已确认；evidence-driven 结论已汇报；未发现 devflow/OpenSpec 冲突。
|
||||
- 影响：可以进入 Phase 3 修改协议文件，但仍需单独的 apply 授权。
|
||||
- 风险接受：当前接受
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- 决策：将本轮定位为 `complex` 分档。
|
||||
- 原因：虽然不涉及业务代码，但它影响 `sm-flow` 的多个核心文件、阶段协议和验收方式，且包含多处跨文档一致性约束。
|
||||
- 影响：使用 `brief.md`、`prd.md`、`evidence.md`、`decisions.md` 四类产物，而不是只写简短 brief。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：不复用 `sm-flow-v3-1-upgrade` 项目，而是新开需求档案。
|
||||
- 原因：`v3.1` 已归档且目标不同；本轮关注的是执行稳定性，不宜混入已完成升级项目。
|
||||
- 影响：后续若进入 OpenSpec，可独立创建新 change。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：将“规则存在但执行不稳”定义为首要问题。
|
||||
- 原因：复盘中的多个现象都能收敛到这一点，能避免后续需求继续发散。
|
||||
- 影响：后续需求改造应优先考虑 checklist、阶段 gate、显式声明和一致性检查。
|
||||
- 风险接受：当前接受
|
||||
|
||||
## Phase 3 Implementation Record
|
||||
|
||||
- 决策：Phase 3 以本地 `openspec-apply-change` `SKILL.md` 作为 capability 来源继续执行。
|
||||
- 原因：当前环境可读取对应 skill 协议，且用户已通过“apply”明确授权进入 Phase 3。
|
||||
- 影响：本轮实现按 committed OpenSpec 的 task 切片直接修改协议与工作流文档。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：本轮不修改 `templates.md`。
|
||||
- 原因：用户已确认不要求固定 checkpoint / alignment 模板，也不要求统一阶段汇报格式；OpenSpec task 2.4 的目标是保持模板可选。
|
||||
- 影响：实现集中在 `SKILL.md`、`phase-contracts.md`、`fallbacks.md`、`workflow.md`，避免把协议硬化扩大成模板标准化。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：把“checkpoint 缺失则阶段不算完成”写入顶层协议和阶段契约，而不是只放在说明文档。
|
||||
- 原因：这是决定阶段能否前进的硬 gate，必须落在执行真理源。
|
||||
- 影响：Phase 0、0.5、1、2、2.5、2.9 现在都需要显式 checkpoint 和 capability 声明。
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：将 Phase 2 question pool、Phase 1.5/2.9 cross-artifact 对齐、`micro` gate 保留和 fallback 记录要求同步落在协议正文与 workflow 说明。
|
||||
- 原因：这些规则既要可执行，又要便于人类理解；单独放在一处容易再次漂移。
|
||||
- 影响：OpenSpec、协议正文和 workflow 解释层的关键术语已收敛到同一套执行规则。
|
||||
- 风险接受：当前接受
|
||||
@@ -0,0 +1,106 @@
|
||||
# SM Flow Execution Hardening Evidence
|
||||
|
||||
## 证据
|
||||
|
||||
| 来源 | 证据 | 结论 | 是否已汇报 |
|
||||
| --- | --- | --- | --- |
|
||||
| `skill-workbench/docs/sm-flow/retrospective.md` | 逐 Phase 复盘了一次真实执行，明确记录了 Phase 0、0.5、1.5、2、2.5、2.9、4 的实际偏差。 | 当前主要问题是执行偏差和自检不足，不是流程理念方向错误。 | 是 |
|
||||
| `skill-workbench/docs/sm-flow/workflow.md` | v3.1 已经补入 Draft/Committed OpenSpec、接口影响分级、Phase 2.9、Phase 3 冲突分类等规则。 | 新一轮需求不应继续扩展原则，而应硬化执行协议。 | 是 |
|
||||
| `.agents/skills/sm-flow/SKILL.md` | 已明确 Phase 0.5、2、2.9 不可跳过，且要求显式 skill/fallback 声明。 | 当前缺口在于代理执行时没有被强制逐项核对这些规则。 | 是 |
|
||||
| `.agents/skills/sm-flow/references/phase-contracts.md` | 每个 Phase 已有进入条件、动作、退出条件和 checkpoint。 | 还缺一个更短、更高频的执行时 checklist 机制。 | 是 |
|
||||
| `.agents/skills/grill-with-docs/SKILL.md` | 明确要求 one-at-a-time 提问，并在可探索时优先查代码。 | Phase 2 的问题不是缺规则，而是没有把“问题池 + 单题推进”落成稳定动作。 | 是 |
|
||||
| `devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md` | 历史评估已指出 `SKILL.md` 更像设计说明书，缺少执行时检查点。 | 本轮需求与历史评估一致，属于同一产品化方向的继续深化。 | 是 |
|
||||
| `openspec/changes/sm-flow-execution-hardening/proposal.md` | Draft proposal 已将变更范围收敛到 phase checkpoint、问题池、cross-artifact alignment、micro gate preservation。 | Phase 1.5 已完成大方向对齐，未决问题主要落在“是否要求固定记录格式”这一类实现边界。 | 是 |
|
||||
| `openspec/changes/sm-flow-execution-hardening/design.md` | Draft design 已明确 checkpoint、问题池、cross-artifact 检查链路和 devflow 过程内同步更新。 | Phase 2 需要确认的重点不再是方向，而是边界和验收粒度。 | 是 |
|
||||
|
||||
## Evidence-driven 结论
|
||||
|
||||
- 结论：`sm-flow` 当前最需要的是“执行硬化”，不是“设计重构”。
|
||||
- 证据：v3.1 已经把主从关系、gate 和冲突分类写清楚，但真实执行仍偏离。
|
||||
- 风险：如果继续增加理念说明，可能让文档更长，但不提升执行稳定性。
|
||||
- 用户确认：不需要
|
||||
|
||||
- 结论：Phase 1.5 和 2.9 的 cross-artifact 检查应成为优先增强点。
|
||||
- 证据：复盘里 `proposal` 漏字段未被代理提前发现，直到用户 review 才暴露。
|
||||
- 风险：如果这两层不稳，Phase 2 即使问得更全，问题仍会漏到 apply 前后。
|
||||
- 用户确认：不需要
|
||||
|
||||
- 结论：`micro` 模式的误用是本次偏差的重要诱因。
|
||||
- 证据：复盘根因明确指出“高估了小改动判断，误以为 micro 可以跳检查”。
|
||||
- 风险：若不把这点写得更硬，后续类似问题会重复出现。
|
||||
- 用户确认：不需要
|
||||
|
||||
## Phase 1.5 对齐检查
|
||||
|
||||
- `brief/prd` -> `proposal`：已对齐
|
||||
- 覆盖了执行硬化而非主设计重构、影响文件范围、非目标边界。
|
||||
- `proposal` -> `design`：已对齐
|
||||
- 设计已展开 checkpoint、问题池、cross-artifact alignment、micro gate preservation 和 devflow 过程内更新。
|
||||
- `design` -> `specs`：已对齐
|
||||
- 已拆出 `sm-flow-phase-checkpoints`、`sm-flow-question-pool`、`sm-flow-cross-artifact-alignment`、`sm-flow-micro-gate-preservation` 四个 capability spec。
|
||||
- `specs` -> `tasks`：部分对齐，仍有一个边界待确认
|
||||
- 当前 tasks 写了“如有需要则更新模板”，但是否必须定义固定记录格式，尚未明确。
|
||||
- `specs` -> `tasks`：现已对齐
|
||||
- 用户已确认这轮不强制固定模板，也不把统一阶段汇报格式纳入验收，因此 tasks 保持“协议强化优先，模板仅按需微调”。
|
||||
|
||||
## Phase 2 Question Pool
|
||||
|
||||
- Q1 `user-interview` / 范围：
|
||||
- 这次 change 是否必须产出固定的 checkpoint / alignment 记录模板，还是只要求协议定义必填字段即可。
|
||||
- 状态：已确认为后者。
|
||||
- Q2 `evidence-driven` / 术语：
|
||||
- `phase checkpoint`、`phase checklist`、`stage-completion rule` 三个说法里，哪个作为协议中的主术语最稳。
|
||||
- Q3 `user-interview` / 验收：
|
||||
- 验收是以“文档明确要求这些门禁”为准，还是要进一步要求代理输出统一格式的阶段汇报。
|
||||
- 状态：已确认采用前者。
|
||||
- Q4 `evidence-driven` / 边界：
|
||||
- 这次是否需要把 retrospective 中的具体案例映射到 workflow 文档中的示例，还是只保留规则层抽象。
|
||||
|
||||
## Phase 2.5 架构审计
|
||||
|
||||
- 输入 -> 处理 -> 输出链路
|
||||
- `retrospective.md` / 现有 `sm-flow` 协议 / 已归档 OpenSpec change
|
||||
- -> `SKILL.md` 核心规则、`phase-contracts.md` 阶段契约、`fallbacks.md` 降级协议、按需 `templates.md`
|
||||
- -> `workflow.md` 设计说明、`devflow` 过程记录、最终可提交的 OpenSpec
|
||||
|
||||
- 模块职责
|
||||
- `.agents/skills/sm-flow/SKILL.md`：放短而硬的总规则、gate 和主从关系。
|
||||
- `.agents/skills/sm-flow/references/phase-contracts.md`：放逐阶段的进入/动作/退出条件与 checkpoint。
|
||||
- `.agents/skills/sm-flow/references/fallbacks.md`：放 capability 不可用时的降级协议和记录要求。
|
||||
- `.agents/skills/sm-flow/references/templates.md`：只放稳定模板，不承载这轮的主逻辑。
|
||||
- `skill-workbench/docs/sm-flow/workflow.md`：保留设计说明和演进脉络，不承载执行真理源。
|
||||
|
||||
- 架构风险评估
|
||||
- 当前最大风险不是规则缺失，而是把同一条规则分散到 `SKILL.md`、`phase-contracts.md`、`workflow.md` 后出现漂移。
|
||||
- 这轮 change 如果把“checkpoint”同时做成规则、模板和示例，容易再次扩大维护面。
|
||||
- 更稳的做法是让 `SKILL.md` 和 `phase-contracts.md` 成为主落点，`workflow.md` 只解释，不重复列执行细则。
|
||||
- `templates.md` 应保持可选和轻量，否则会把“协议硬化”扩成“输出格式标准化”。
|
||||
- 审计结论与当前 Draft OpenSpec 一致，不需要新增 capability，只需要在实现时严格控制规则落点。
|
||||
|
||||
## Phase 2.9 Commit Gate
|
||||
|
||||
- proposal：通过
|
||||
- 已覆盖变更原因、范围、非目标、关键边界，以及“不强制固定模板 / 不要求统一阶段汇报格式”的范围约束。
|
||||
- design：通过
|
||||
- 已覆盖 checkpoint、问题池、cross-artifact alignment、micro gate preservation、devflow 过程内更新和规则落点分层。
|
||||
- specs：通过
|
||||
- 已覆盖四个新增 capability，且行为描述集中在可观察的协议要求。
|
||||
- tasks：通过
|
||||
- 已覆盖协议修改、workflow 更新、校验和验收边界验证。
|
||||
- user-interview：通过
|
||||
- 两个需要用户确认的问题均已确认并回写。
|
||||
- evidence-driven：通过
|
||||
- 术语与 workflow 粒度问题已通过现有文档证据收束。
|
||||
- devflow / OpenSpec 冲突：未发现
|
||||
|
||||
结论：当前 Draft OpenSpec 已达到可执行状态，可视为 Committed OpenSpec，进入 Phase 3 前仅缺明确 apply 授权。
|
||||
|
||||
## Phase 3 Apply Evidence
|
||||
|
||||
| 来源 | 证据 | 结论 | 是否已汇报 |
|
||||
| --- | --- | --- | --- |
|
||||
| `.agents/skills/sm-flow/SKILL.md` | 已新增显式 checkpoint 完成规则、question pool 规则、cross-artifact 对齐规则、`micro` gate 保留规则和 devflow 分阶段更新规则。 | 顶层协议已把执行硬化从“建议”提升为阶段完成条件。 | 是 |
|
||||
| `.agents/skills/sm-flow/references/phase-contracts.md` | 已新增 Phase 1.5 对齐链检查、Phase 2 问题池建立、Phase 2.9 闭环复核、Phase 3 capability 启动汇报和 Phase 4 consolidation 约束。 | 逐阶段执行契约已经覆盖 committed OpenSpec 的核心要求。 | 是 |
|
||||
| `.agents/skills/sm-flow/references/fallbacks.md` | 已新增统一 fallback 记录要求，并在各 fallback 协议中补入记录动作。 | 降级执行现在是可见、可审计的协议事件。 | 是 |
|
||||
| `skill-workbench/docs/sm-flow/workflow.md` | 已新增 question pool、Phase Checkpoint、Cross-Artifact Alignment、Micro 不是 Skip、fallback 记录要求等说明。 | retrospective 中的经验已被提升为稳定规则，而不是仅停留在叙述层。 | 是 |
|
||||
| `openspec/changes/sm-flow-execution-hardening/tasks.md` | 已完成 1.1-3.2，文档实现范围已落地。 | Phase 3 的协议/文档实现部分已完成，剩余工作转入验证与验收。 | 是 |
|
||||
@@ -0,0 +1,67 @@
|
||||
# SM Flow Execution Hardening PRD
|
||||
|
||||
## 问题陈述
|
||||
|
||||
`sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
|
||||
|
||||
- Phase 0 没有形成入口摘要和已知影响区域。
|
||||
- Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
|
||||
- Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
|
||||
- Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
|
||||
- Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
|
||||
- Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
|
||||
- Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
|
||||
|
||||
这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
|
||||
|
||||
## 解决方案
|
||||
|
||||
为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
|
||||
|
||||
- 每个阶段结束必须有简短 checklist / checkpoint。
|
||||
- 未显式声明 skill 或 fallback 视为该阶段未完成。
|
||||
- Phase 2 先生成问题池，再按 one-at-a-time 消费。
|
||||
- Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
|
||||
- `micro` 明确只能压缩产物，不得跳过关键 gate。
|
||||
- devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
|
||||
|
||||
## 用户故事
|
||||
|
||||
1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
|
||||
2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
|
||||
3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
|
||||
4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
|
||||
|
||||
## 实现决策
|
||||
|
||||
- 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
|
||||
- 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
|
||||
- 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
|
||||
|
||||
- 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
|
||||
- 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
|
||||
- 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
|
||||
|
||||
## 测试决策
|
||||
|
||||
- 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
|
||||
- 必须覆盖：
|
||||
- `micro` 模式下 gate 不可跳过
|
||||
- Phase 2 问题池与 one-at-a-time 提问
|
||||
- skill/fallback 显式声明要求
|
||||
- Phase 1.5 / 2.9 cross-artifact 检查
|
||||
- devflow 过程内同步更新
|
||||
- 不测试：
|
||||
- 业务代码实现结果
|
||||
- OpenSpec CLI 本身的功能正确性
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不在本轮定义新的业务流程。
|
||||
- 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
|
||||
- 不要求为所有小改动增加更重的文档负担。
|
||||
|
||||
## 补充说明
|
||||
|
||||
- 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
|
||||
- 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。
|
||||
@@ -0,0 +1,52 @@
|
||||
# knowledge-index-sort Acceptance
|
||||
|
||||
## 结果
|
||||
|
||||
已接受。
|
||||
|
||||
## 验证
|
||||
|
||||
### 静态验证
|
||||
|
||||
- 检查项：knowledge-index.html 和 scripts/update-knowledge-index.sh 内容一致性
|
||||
- 结果：passed
|
||||
- 备注：两个文件的排序 UI、排序逻辑、事件绑定、清空筛选重置逻辑完全一致
|
||||
|
||||
### 脚本验证
|
||||
|
||||
- 命令：未运行（纯前端静态页面，无测试框架）
|
||||
- 结果：not run
|
||||
- 备注：不适用
|
||||
|
||||
### 浏览器/人工验证
|
||||
|
||||
- 步骤：
|
||||
1. 打开 knowledge-index.html
|
||||
2. 切换排序下拉框的 4 种模式，验证条目顺序
|
||||
3. 组合排序与标签筛选/搜索/年份筛选
|
||||
4. 点击"清空筛选"验证排序重置
|
||||
- 结果：passed
|
||||
- 备注：用户确认验证通过
|
||||
|
||||
## 已完成范围
|
||||
|
||||
- 排序下拉框 UI（4 种模式：日期新→旧、旧→新、标签多→少、少→多）
|
||||
- applyFilters() 中排序逻辑（过滤后、渲染前）
|
||||
- bindSortSelect() 事件绑定
|
||||
- clearFilters() 重置排序为默认值
|
||||
- scripts/update-knowledge-index.sh 同步修改
|
||||
- OpenSpec 产物（proposal/design/specs/tasks）
|
||||
|
||||
## 已知限制
|
||||
|
||||
- 排序状态不持久化，刷新页面后恢复默认（date-desc）
|
||||
- 不做多列排序
|
||||
|
||||
## Bug 修复和诊断
|
||||
|
||||
- 无
|
||||
|
||||
## 交接
|
||||
|
||||
- 下一步：可选归档 OpenSpec change，功能已完整可用
|
||||
- OpenSpec 归档确认：待询问
|
||||
@@ -0,0 +1,30 @@
|
||||
# knowledge-index-sort Brief
|
||||
|
||||
## 背景
|
||||
|
||||
- 用户目标：给 knowledge-index-panel 添加排序功能，支持按日期和标签数量排序
|
||||
- 当前问题：条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看
|
||||
- 关联 OpenSpec：`openspec/changes/knowledge-index-sort/`
|
||||
- devflow 分档：micro
|
||||
|
||||
## 范围
|
||||
|
||||
- 本次要做：在 filter-row 中添加排序下拉框，支持 4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
|
||||
- 本次不做：多列排序、拖拽排序、修改 ENTRIES 数据结构、分页
|
||||
- 影响区域：`knowledge-index.html`、`scripts/update-knowledge-index.sh`
|
||||
|
||||
## OpenSpec 对齐
|
||||
|
||||
- proposal 覆盖状态：已覆盖
|
||||
- specs 覆盖状态：已覆盖
|
||||
- tasks 覆盖状态：已覆盖
|
||||
|
||||
## 关键决策
|
||||
|
||||
- "按标签排序"指按标签数量排序（用户确认）
|
||||
- 排序在 applyFilters() 中执行，位于过滤之后、渲染之前
|
||||
- 排序与搜索、标签筛选、年份筛选取交集，即时响应
|
||||
|
||||
## 执行偏差
|
||||
|
||||
apply 阶段先实现了代码，后补写 OpenSpec 产物。已在 decisions.md 中记录并分析根因。此偏差推动了 sm-flow 协议本身的改进（commit gate 文件存在性检查、grill 退出条件 decisions.md 强制写入、archive 退出条件文件验证）。
|
||||
@@ -0,0 +1,42 @@
|
||||
# knowledge-index-sort Decisions
|
||||
|
||||
## Question Pool
|
||||
|
||||
| # | 维度 | 问题 | 模式 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| Q1 | 术语 | "按标签排序"具体指什么？按第一个标签字母序？按标签数量？ | user-interview | 已解决 |
|
||||
| Q2 | 边界 | 排序是否只影响当前过滤后的可见条目（不影响过滤逻辑本身）？ | evidence-driven | 已解决 |
|
||||
| Q3 | 验收 | 排序变化后，页面应如何响应？即时重排还是需要点击"应用"？ | evidence-driven | 已解决 |
|
||||
|
||||
## User-interview
|
||||
|
||||
| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
|
||||
|---|---|---|---|
|
||||
| "按标签排序"具体指什么？ | "按数量" | 已确认 | 已回写 |
|
||||
|
||||
## Evidence-driven
|
||||
|
||||
| 结论 | 证据来源 | 是否已汇报用户 |
|
||||
|---|---|---|
|
||||
| 排序只作用于过滤后的结果 | knowledge-index.html applyFilters() 代码 | 已汇报 |
|
||||
| 排序应即时响应（change 事件） | 与 year-filter/标签/搜索控件行为一致 | 已汇报 |
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- 决策：排序位置放在 applyFilters() 中，过滤之后、渲染之前
|
||||
- 原因：排序只影响可见条目，不影响过滤逻辑
|
||||
- 影响：renderEntries 保持纯渲染职责
|
||||
- 风险接受：当前接受
|
||||
|
||||
- 决策：4 种排序模式（日期新→旧、旧→新、标签多→少、少→多）
|
||||
- 原因：覆盖最常见排序需求
|
||||
- 影响：UI 简洁，不需要复杂的多列排序
|
||||
- 风险接受：当前接受
|
||||
|
||||
## 执行偏差记录
|
||||
|
||||
- 偏差：apply 阶段先实现了代码，后补写 OpenSpec 产物（proposal/design/specs/tasks）
|
||||
- 分类：实现偏差（违反 sm-flow 协议——specify 阶段应先产出完整 OpenSpec）
|
||||
- 原因：micro 模式下跳过了 specify 阶段的文件产出，直接进入 apply
|
||||
- 修正：补写所有 OpenSpec 产物到 openspec/changes/knowledge-index-sort/
|
||||
- 教训：即使是 micro 模式，OpenSpec 产物也不能跳过——这是 apply 的执行依据
|
||||
@@ -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.
|
||||
@@ -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/`.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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/`
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-21
|
||||
@@ -0,0 +1,54 @@
|
||||
## Context
|
||||
|
||||
SM Flow v3 已经把 `devflow/` 定位为上下文真理源，把 `openspec/changes/<change>/` 定位为执行真理源。当前摩擦来自执行细节：一些需要人类判断的规则没有形成 gate，导致代理可能过早把 Draft OpenSpec 当成最终规格，或者在 Phase 3 中用代码侧发现直接覆盖原设计。
|
||||
|
||||
本次改造的对象是 skill 协议本身，主要文件位于 `.agents/skills/sm-flow/`，历史说明位于 `skill-workbench/docs/sm-flow/workflow.md`。用户提供的问题记录位于 `skill-workbench/docs/sm-flow/使用问题.md`。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 让 v3.1 明确“文档不是越多越好”：devflow 记录上下文、证据、决策和验收，OpenSpec 记录执行依据。
|
||||
- 对接口变更建立分级规则，避免“所有接口变更都独立成文档”和“接口影响没人记录”两个极端。
|
||||
- 引入 Draft / Committed OpenSpec，允许 Phase 1 先形成讨论对象，但禁止未提交的草稿直接进入 Phase 3。
|
||||
- 为 devflow 增加索引入口和固定检索顺序，解决项目档案增长后的定位问题。
|
||||
- 在 Phase 3 增加实现期沟通和冲突分类规则，避免把用户质疑、测试失败或代码建议直接当作新规格。
|
||||
|
||||
**Non-Goals:**
|
||||
- 不重写 OpenSpec CLI 或 `.claude/skills/openspec-*`。
|
||||
- 不改业务代码或知识索引功能。
|
||||
- 不把 devflow 重新提升为执行真理源。
|
||||
- 不强制每次接口变更都创建独立接口文档。
|
||||
|
||||
## Decisions
|
||||
|
||||
1. **Draft / Committed OpenSpec 分离**
|
||||
- 决策：Phase 1 产物称为 Draft OpenSpec；Phase 2 和 Phase 2.5 后进入新增的 Phase 2.9 Commit OpenSpec，只有通过提交检查的 OpenSpec 才能进入 Phase 3。
|
||||
- 原因：完全推迟 OpenSpec 会缺少讨论对象；完全信任 Phase 1 初稿又会让 grill 后返工显得像异常。草稿/提交分离把返工变成正常流程。
|
||||
- 替代方案：把 grill 放到 propose 前。拒绝原因是缺少结构化规格草稿时，澄清容易停留在对话层，难以精确回写 proposal/specs/tasks。
|
||||
|
||||
2. **接口影响分级，而不是固定独立文档**
|
||||
- 决策：所有接口变更都必须有接口影响记录；只有 L3/L4 级别才必须独立产出接口文档。
|
||||
- 原因：接口变更需要可追踪，但低风险内部接口不应制造额外文档负担。
|
||||
- 替代方案：凡接口变更都新增接口文档。拒绝原因是会让 micro/standard 变更过重，增加文档重复和漂移。
|
||||
|
||||
3. **devflow 通过索引和检索顺序控制增长**
|
||||
- 决策：新增或维护 `devflow/index.md`，并规定 Phase 0.5 的检索顺序为 `devflow/index.md`、`devflow/glossary/CONTEXT.md`、相关项目 brief/acceptance/ADR、compound knowledge。
|
||||
- 原因：devflow 的长期价值来自可回溯；没有索引时，文档越多越像一片温柔但很黏的沼泽。
|
||||
- 替代方案：每次用全文搜索全量扫。拒绝原因是成本随项目数增长，且容易抓到无关历史。
|
||||
|
||||
4. **Phase 3 冲突先分类，再执行**
|
||||
- 决策：实现阶段遇到用户质疑、代码建议、测试失败或新事实与 OpenSpec 冲突时，必须分类为实现偏差、规格遗漏、设计冲突或用户变更。
|
||||
- 原因：Phase 3 的职责是执行已提交规格，不是把所有新输入立即吸收成代码改动。
|
||||
- 替代方案：让代理自行判断并继续。拒绝原因是会破坏 OpenSpec 的执行真理源地位。
|
||||
|
||||
5. **子 skill 绑定能力契约**
|
||||
- 决策：文档应表达 `openspec-propose`、`openspec-apply-change` 等能力名和调用优先级；`.claude/skills/...` 是一个实现路径，不是唯一前提。
|
||||
- 原因：同一流程应能迁移到 Codex、Claude 或其他代理环境。
|
||||
- 替代方案：固定 Claude 路径。拒绝原因是兼容性弱，且与当前 `.agents/skills/` 运行方式不匹配。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Draft / Committed OpenSpec 增加一个 Phase 2.9 gate → 用固定检查清单控制成本，避免变成新一轮大文档。
|
||||
- 接口影响分级可能被代理误判 → 把分级阈值写成可观察条件，并要求不确定时向用户确认。
|
||||
- `devflow/index.md` 需要维护 → Phase 4 回填时把索引更新列为默认动作，减少遗忘。
|
||||
- Phase 3 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
SM Flow v3 已经确立了 OpenSpec-first / Devflow-assisted 的主从关系，但实际使用中仍存在四类摩擦：接口变更文档粒度不清、propose 后再 grill 导致返工、devflow 增长后上下文定位变慢、实现阶段发现设计冲突时容易被代码建议牵着走。
|
||||
|
||||
这次 v3.1 改造要把这些摩擦固化为可执行规则，让代理在生成规格、澄清需求、执行 apply 和回填 devflow 时有明确 gate，而不是靠临场判断。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 增加接口影响分级规则：所有接口变更都必须记录影响，只有达到跨团队、外部契约或破坏性变更阈值时才独立产出接口文档。
|
||||
- 增加 OpenSpec 草稿/提交分离：Phase 1 生成 Draft OpenSpec，Phase 2/2.5 澄清和审计后通过 Phase 2.9 提交为 Phase 3 的执行依据。
|
||||
- 增加 devflow 上下文定位规则：通过 `devflow/index.md`、项目 `brief.md` 和固定检索顺序减少全量翻阅。
|
||||
- 增加实现期冲突处理规则：Phase 3 中用户质疑、测试失败、代码发现和 OpenSpec 冲突时，必须先分类再继续执行。
|
||||
- 增加 Phase 3 前 OpenSpec 可执行性检查，确保 proposal/design/specs/tasks、接口影响、未解决用户问题和 devflow 冲突都达标。
|
||||
- 调整子 skill 兼容规则：把流程绑定到能力契约，而不是绑定到 Claude 路径；Claude skill 文件只是一个可用实现。
|
||||
- 更新 sm-flow skill 本体、phase contracts、fallbacks、templates 和工作流说明文档。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `sm-flow-interface-impact`: 定义接口影响分级、接口影响记录和独立接口文档的触发条件。
|
||||
- `sm-flow-commit-gate`: 定义 Draft OpenSpec、Committed OpenSpec、Phase 2.9 提交检查和 Phase 3 前可执行性 gate。
|
||||
- `sm-flow-context-indexing`: 定义 devflow 上下文索引和固定检索顺序。
|
||||
- `sm-flow-apply-conflict-handling`: 定义 Phase 3 实现期冲突分类、用户确认和 OpenSpec 回写规则。
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- 没有已归档的 openspec/specs 需要修改；当前仓库尚未建立全局 specs 目录。 -->
|
||||
|
||||
## Impact
|
||||
|
||||
- 修改 `.agents/skills/sm-flow/SKILL.md`。
|
||||
- 修改 `.agents/skills/sm-flow/references/phase-contracts.md`、`fallbacks.md`、`templates.md`。
|
||||
- 可能新增 `devflow/index.md` 作为长期上下文索引入口。
|
||||
- 更新 `skill-workbench/docs/sm-flow/workflow.md`，记录 v3.1 的最终设计。
|
||||
- 不修改业务代码，不改变 `knowledge/` 索引功能。
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Phase 3 classifies implementation-time conflicts
|
||||
SM Flow SHALL classify implementation-time conflicts before changing code or OpenSpec.
|
||||
|
||||
#### Scenario: User challenges implementation during apply
|
||||
- **WHEN** the user questions or changes implementation behavior during Phase 3 and the request conflicts with Committed OpenSpec
|
||||
- **THEN** the flow classifies the issue as implementation deviation, spec omission, design conflict, or user scope change before continuing
|
||||
|
||||
#### Scenario: Code suggests a different approach
|
||||
- **WHEN** code inspection, tests, or runtime behavior suggests a different approach than Committed OpenSpec
|
||||
- **THEN** the flow reports the evidence and classification instead of silently accepting the code-side suggestion
|
||||
|
||||
#### Scenario: Conflict is implementation deviation
|
||||
- **WHEN** Committed OpenSpec remains correct and implementation diverges from proposal, design, specs, or tasks
|
||||
- **THEN** the flow classifies the issue as implementation deviation and fixes the code without changing executable OpenSpec except task status or acceptance notes
|
||||
|
||||
#### Scenario: Conflict is spec omission
|
||||
- **WHEN** Committed OpenSpec lacks a real boundary, behavior, validation rule, interface impact, or acceptance case discovered during implementation
|
||||
- **THEN** the flow classifies the issue as spec omission and returns to OpenSpec repair before continuing apply
|
||||
|
||||
#### Scenario: Conflict is design conflict
|
||||
- **WHEN** Committed OpenSpec conflicts with architecture, ADR, historical acceptance, data ownership, lifecycle, or module boundaries
|
||||
- **THEN** the flow classifies the issue as design conflict, pauses implementation, reports the conflict, and asks the user to confirm the design direction
|
||||
|
||||
#### Scenario: Conflict is user scope change
|
||||
- **WHEN** the user changes the goal, scope, priority, acceptance expectation, or risk tolerance during implementation
|
||||
- **THEN** the flow classifies the issue as user scope change and updates proposal, specs, and tasks before continuing
|
||||
|
||||
### Requirement: Spec-affecting conflicts return to OpenSpec repair
|
||||
SM Flow SHALL repair OpenSpec before continuing when implementation-time conflicts affect the executable specification.
|
||||
|
||||
#### Scenario: Conflict is a spec omission or design conflict
|
||||
- **WHEN** a Phase 3 conflict changes scope, externally observable behavior, interface compatibility, architecture decisions, or task slicing
|
||||
- **THEN** the flow pauses apply, obtains required user confirmation, updates proposal/design/specs/tasks, reruns the commit gate, and only then resumes Phase 3
|
||||
|
||||
#### Scenario: Conflict is implementation deviation
|
||||
- **WHEN** the committed specification is still correct and the code diverges from it
|
||||
- **THEN** the flow fixes the implementation without changing OpenSpec except for task status or acceptance notes
|
||||
@@ -0,0 +1,49 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: OpenSpec drafts are not executable
|
||||
SM Flow SHALL distinguish Draft OpenSpec from Committed OpenSpec.
|
||||
|
||||
#### Scenario: Phase 1 proposal created
|
||||
- **WHEN** Phase 1 creates or updates proposal, design, specs, and tasks
|
||||
- **THEN** the flow treats those artifacts as Draft OpenSpec until Phase 2, Phase 2.5, and Phase 2.9 checks are complete
|
||||
|
||||
#### Scenario: Draft has unresolved questions
|
||||
- **WHEN** Draft OpenSpec contains unresolved user-interview questions, unreported evidence-driven conclusions, architecture conflicts, or unrecorded interface impact
|
||||
- **THEN** the flow SHALL NOT enter Phase 3
|
||||
|
||||
### Requirement: Phase 2.9 commits executable OpenSpec
|
||||
SM Flow SHALL include a Phase 2.9 Commit OpenSpec gate before Phase 3.
|
||||
|
||||
#### Scenario: Commit gate passes
|
||||
- **WHEN** proposal explains scope and non-goals, design captures implementation constraints, specs describe observable behavior, tasks are executable vertical slices, interface impact is recorded, and devflow conflicts are resolved
|
||||
- **THEN** the flow marks the OpenSpec change as Committed OpenSpec and may ask the user to proceed to Phase 3
|
||||
|
||||
#### Scenario: Commit gate fails
|
||||
- **WHEN** any required executable OpenSpec condition is missing
|
||||
- **THEN** the flow returns to Phase 1, Phase 2, or Phase 2.5 to repair the missing artifact before implementation
|
||||
|
||||
### Requirement: Grill questions require explicit human confirmation
|
||||
SM Flow SHALL treat Phase 2 grill as a human-in-the-loop process that requires explicit user confirmation for user-interview questions.
|
||||
|
||||
#### Scenario: User-interview grill question is asked
|
||||
- **WHEN** Phase 2 raises a user-interview question about terminology, scope, acceptance, risk, priority, or product preference
|
||||
- **THEN** the flow asks exactly one question, waits for the user's answer, records the answer, and only then continues to the next user-interview question
|
||||
|
||||
#### Scenario: Grill confirmation is missing
|
||||
- **WHEN** a user-interview question has no explicit user answer
|
||||
- **THEN** the flow SHALL NOT mark the question resolved, SHALL NOT commit OpenSpec, and SHALL NOT enter Phase 3
|
||||
|
||||
### Requirement: Grill confirmation does not authorize apply
|
||||
SM Flow SHALL distinguish confirmation of an individual grill decision from authorization to enter Phase 3.
|
||||
|
||||
#### Scenario: User confirms a grill decision
|
||||
- **WHEN** the user answers a Phase 2 user-interview question with confirmation such as "可以", "确认", or equivalent
|
||||
- **THEN** the flow records that decision and updates OpenSpec/devflow, but SHALL NOT treat the answer as authorization to modify execution target files
|
||||
|
||||
#### Scenario: OpenSpec has been updated after grill
|
||||
- **WHEN** Phase 2 or Phase 2.5 findings have been written back to proposal, design, specs, or tasks
|
||||
- **THEN** the flow stops at Phase 2.9, reports the Committed OpenSpec check result, and waits for explicit user authorization to enter Phase 3
|
||||
|
||||
#### Scenario: Apply authorization is missing
|
||||
- **WHEN** the user has not explicitly said to enter apply, start implementation, execute the changes, continue Phase 3, or equivalent
|
||||
- **THEN** the flow may update OpenSpec and devflow decision records, but SHALL NOT modify execution target files
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Devflow context lookup uses an index-first strategy
|
||||
SM Flow SHALL use a stable index-first devflow lookup order to find relevant context.
|
||||
|
||||
#### Scenario: Phase 0.5 starts
|
||||
- **WHEN** Phase 0.5 collects devflow context
|
||||
- **THEN** the flow checks `devflow/index.md` first, then `devflow/glossary/CONTEXT.md`, then related project brief/acceptance/ADR files, then `devflow/compound/`
|
||||
|
||||
#### Scenario: Index is missing during lookup
|
||||
- **WHEN** `devflow/index.md` does not exist
|
||||
- **THEN** the flow initializes a lightweight index from known project directories, falls back to targeted search for the current lookup, and records that the index was bootstrapped
|
||||
|
||||
### Requirement: Phase 4 maintains devflow index
|
||||
SM Flow SHALL update devflow index metadata during Phase 4 when a project archive is created or updated.
|
||||
|
||||
#### Scenario: Project is backfilled
|
||||
- **WHEN** Phase 4 creates or updates `devflow/projects/YYYY-MM-DD-{slug}/`
|
||||
- **THEN** the flow updates `devflow/index.md` with date, slug, domain, keywords, related OpenSpec change, and status
|
||||
|
||||
#### Scenario: Phase 4 completes without index update
|
||||
- **WHEN** Phase 4 has created or updated project backfill files but has not updated `devflow/index.md`
|
||||
- **THEN** the flow is incomplete and must update the index before reporting completion
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Interface changes have impact records
|
||||
SM Flow SHALL require every interface-related change to record interface impact before Phase 3.
|
||||
|
||||
#### Scenario: Internal interface field changes
|
||||
- **WHEN** a change adds, removes, renames, or changes the semantics of a field, DTO, service method, event, API, callback, database contract, or command contract
|
||||
- **THEN** the flow records the affected interface, affected consumers, compatibility expectation, and validation method in OpenSpec design/specs/tasks or devflow evidence/decisions
|
||||
|
||||
#### Scenario: Interface uncertainty
|
||||
- **WHEN** the agent cannot determine whether a change affects an interface contract
|
||||
- **THEN** the flow treats it as an interface-impact question and asks for confirmation before Phase 3
|
||||
|
||||
#### Scenario: Internal decision logic changes observable behavior
|
||||
- **WHEN** a change modifies internal decision logic inside an interface and the result can change returned data, status, error code, permission result, validation result, ordering, filtering, idempotency, timing, or side effects
|
||||
- **THEN** the flow treats the change as interface impact even if the interface shape and field names are unchanged
|
||||
|
||||
### Requirement: Interface documentation is level-gated
|
||||
SM Flow SHALL create an independent interface document only when the interface impact level requires it.
|
||||
|
||||
#### Scenario: Low-risk internal interface change
|
||||
- **WHEN** an interface change is limited to internal implementation or an internal module boundary and has no external consumers
|
||||
- **THEN** the flow records the interface impact inline without requiring a standalone interface document
|
||||
|
||||
#### Scenario: External or breaking interface change
|
||||
- **WHEN** an interface change affects external APIs, SDKs, callbacks, events, database contracts, cross-team consumers, or breaks backward compatibility
|
||||
- **THEN** the flow requires a standalone interface document or equivalent explicit section covering consumers, compatibility, migration, rollback, and validation
|
||||
|
||||
### Requirement: Interface impact levels use risk-based classification
|
||||
SM Flow SHALL classify interface impact by consumer boundary, contract semantics, and compatibility risk.
|
||||
|
||||
#### Scenario: L1 internal implementation
|
||||
- **WHEN** a change does not alter any consumer-visible interface shape, field, status, error, data range, ordering, permission result, state transition, side effect, or documented behavior
|
||||
- **THEN** the flow classifies it as L1 and records validation in tasks or acceptance without requiring interface impact documentation
|
||||
|
||||
#### Scenario: L2 internal interface
|
||||
- **WHEN** a change affects internal DTOs, service methods, internal events, internal RPC, or internal decision logic and all consumers are inside the same implementation scope
|
||||
- **THEN** the flow classifies it as L2 and records interface impact inline
|
||||
|
||||
#### Scenario: L3 collaboration interface
|
||||
- **WHEN** a change affects other modules, services, frontend callers, external systems, cross-team consumers, database contracts, events, callbacks, or SDK users
|
||||
- **THEN** the flow classifies it as L3 and requires a standalone interface document or equivalent explicit section
|
||||
|
||||
#### Scenario: L4 breaking interface
|
||||
- **WHEN** old consumers can fail, receive less data, receive more data, observe different statuses or errors, require migration, require rollback, or lose backward compatibility
|
||||
- **THEN** the flow classifies it as L4 and requires standalone interface documentation plus migration and rollback notes
|
||||
@@ -0,0 +1,31 @@
|
||||
## 1. OpenSpec Commit Gate
|
||||
|
||||
- [x] 1.1 Update `.agents/skills/sm-flow/SKILL.md` to describe Draft OpenSpec, Committed OpenSpec, Phase 2.9, and the Phase 3 executable gate.
|
||||
- [x] 1.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with Phase 2.9 entry/action/output/exit criteria.
|
||||
- [x] 1.3 Add Phase 3 preflight checks for unresolved user-interview questions, interface impact, devflow conflicts, and executable task/spec quality.
|
||||
- [x] 1.4 Require Phase 2 grill user-interview questions to wait for explicit user confirmation before they can be marked resolved.
|
||||
- [x] 1.5 Require explicit Phase 3 apply authorization after Phase 2.9; individual grill confirmations must not authorize execution target file changes.
|
||||
|
||||
## 2. Interface Impact Rules
|
||||
|
||||
- [x] 2.1 Add interface impact level definitions and inline-vs-standalone documentation rules to the sm-flow protocol.
|
||||
- [x] 2.2 Add an interface impact template to `.agents/skills/sm-flow/references/templates.md`.
|
||||
- [x] 2.3 Update Phase 1.5 / Phase 2 checks so interface changes are identified before Phase 3.
|
||||
|
||||
## 3. Devflow Context Indexing
|
||||
|
||||
- [x] 3.1 Add devflow index lookup order to Phase 0.5.
|
||||
- [x] 3.2 Create or update `devflow/index.md` with existing project entries.
|
||||
- [x] 3.3 Update Phase 4 rules so future project backfills maintain the index.
|
||||
|
||||
## 4. Apply Conflict Handling
|
||||
|
||||
- [x] 4.1 Add Phase 3 implementation-time conflict classification rules.
|
||||
- [x] 4.2 Update `.agents/skills/sm-flow/references/fallbacks.md` so execution fallback pauses and repairs OpenSpec for spec-affecting conflicts.
|
||||
- [x] 4.3 Ensure conflict classifications are recorded in devflow decisions or acceptance notes.
|
||||
|
||||
## 5. Compatibility and Documentation
|
||||
|
||||
- [x] 5.1 Reword sub-skill compatibility rules to bind to capability contracts first and implementation paths second.
|
||||
- [x] 5.2 Update `skill-workbench/docs/sm-flow/workflow.md` with the final v3.1 design.
|
||||
- [x] 5.3 Run OpenSpec status checks and text searches to verify the new terms are consistently documented.
|
||||
@@ -0,0 +1 @@
|
||||
Devflow archive files are ready for validate-sm-flow-explicit-trigger.
|
||||
@@ -0,0 +1 @@
|
||||
Committed OpenSpec for validate-sm-flow-explicit-trigger.
|
||||
@@ -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.
|
||||
+53
@@ -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
|
||||
@@ -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.
|
||||
@@ -0,0 +1 @@
|
||||
Devflow archive files are ready for validate-sm-flow-standard-change.
|
||||
@@ -0,0 +1 @@
|
||||
Committed OpenSpec for validate-sm-flow-standard-change.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+36
@@ -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
|
||||
@@ -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`.
|
||||
@@ -0,0 +1,67 @@
|
||||
# knowledge-index-sort Design
|
||||
|
||||
## 架构摘要
|
||||
|
||||
排序功能集成到现有的 `applyFilters()` 函数中，形成完整的过滤→排序→渲染管道：
|
||||
|
||||
```
|
||||
用户操作（搜索/标签/年份/排序）
|
||||
↓
|
||||
applyFilters()
|
||||
├─ 年份过滤（year-filter）
|
||||
├─ 标签过滤（tag-badge.active）
|
||||
├─ 搜索过滤（search-input）
|
||||
├─ 排序（sort-select）← 新增
|
||||
└─ renderEntries(filtered)
|
||||
├─ 高亮匹配（highlightMatches）
|
||||
└─ 高亮标签（highlightMatchingTags）
|
||||
```
|
||||
|
||||
## 关键技术决策
|
||||
|
||||
### 排序位置：过滤之后、渲染之前
|
||||
|
||||
排序逻辑放在 `applyFilters()` 中，位于所有过滤操作之后、`renderEntries()` 调用之前。
|
||||
|
||||
- 原因：排序只影响当前可见条目，不影响过滤逻辑本身
|
||||
- 替代方案：在 `renderEntries()` 内部排序 → 被否决，因为 renderEntries 应该只负责渲染，不负责排序
|
||||
|
||||
### 排序模式：4 种预设
|
||||
|
||||
| 模式 | 值 | 排序规则 |
|
||||
|---|---|---|
|
||||
| 日期 新→旧 | `date-desc` | `b.date.localeCompare(a.date)`（默认） |
|
||||
| 日期 旧→新 | `date-asc` | `a.date.localeCompare(b.date)` |
|
||||
| 标签 多→少 | `tags-desc` | `b.tags.length - a.tags.length` |
|
||||
| 标签 少→多 | `tags-asc` | `a.tags.length - b.tags.length` |
|
||||
|
||||
- 原因：覆盖最常见的排序需求（时间顺序 + 内容丰富度）
|
||||
- 用户确认：Q1 确认"按标签排序"指按标签数量
|
||||
|
||||
### 数据结构：复用现有字段
|
||||
|
||||
排序直接使用 ENTRIES 数组中的 `date`（YYYYMMDD 字符串）和 `tags`（数组），无需修改数据结构。
|
||||
|
||||
- 原因：字段已存在，排序逻辑简单
|
||||
- 风险：无
|
||||
|
||||
### UI 位置：filter-row 中，年份筛选之后
|
||||
|
||||
排序下拉框放在年份筛选（year-filter）之后、清空按钮（clear-filters）之前。
|
||||
|
||||
- 原因：与现有控件保持一致的视觉层级
|
||||
- 替代方案：单独一行 → 被否决，增加垂直空间占用
|
||||
|
||||
## 模块地图
|
||||
|
||||
| 模块 | 职责 | 备注 |
|
||||
|---|---|---|
|
||||
| sort-select HTML | 排序 UI 控件 | 4 个 option |
|
||||
| bindSortSelect() | 绑定 change 事件 | 触发 applyFilters() |
|
||||
| applyFilters() 排序段 | 执行排序逻辑 | 过滤后、渲染前 |
|
||||
| clearFilters() | 重置排序为默认值 | `date-desc` |
|
||||
|
||||
## 架构审计
|
||||
|
||||
- **风险**：无跨模块依赖，纯前端改动
|
||||
- **缓解**：不适用
|
||||
@@ -0,0 +1,46 @@
|
||||
# knowledge-index-sort Proposal
|
||||
|
||||
## 问题
|
||||
|
||||
knowledge-index-panel 当前条目按 ENTRIES 数组原始顺序渲染，用户无法按日期或标签排序查看。
|
||||
|
||||
## 建议方案
|
||||
|
||||
在筛选栏（filter-row）中添加排序下拉框，支持按日期（新→旧/旧→新）和标签数量（多→少/少→多）排序。
|
||||
|
||||
## 范围
|
||||
|
||||
### 本次要做
|
||||
- 在 filter-row 中添加排序下拉框（sort-select）
|
||||
- 在 applyFilters() 中实现排序逻辑（过滤后、渲染前）
|
||||
- 绑定 change 事件即时重排
|
||||
- 清空筛选时重置排序为默认值
|
||||
- 同步修改 scripts/update-knowledge-index.sh
|
||||
|
||||
### 本次不做
|
||||
- 多列排序
|
||||
- 拖拽排序
|
||||
- 修改 ENTRIES 数据结构
|
||||
- 分页
|
||||
|
||||
### 影响区域
|
||||
- `knowledge-index.html`（HTML + CSS + JS）
|
||||
- `scripts/update-knowledge-index.sh`（同步修改）
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不做服务端排序（纯前端客户端改动）
|
||||
- 不做排序状态持久化（刷新后恢复默认）
|
||||
- 不修改知识条目数据结构
|
||||
|
||||
## 风险
|
||||
|
||||
- **低风险**：纯前端改动，单文件 + 生成脚本
|
||||
- **兼容性**：已有 3 个条目，排序逻辑简单（日期字符串比较 + 数组长度比较）
|
||||
- **性能**：3 条目的排序开销可忽略，即使未来增长到 50 条也无压力
|
||||
|
||||
## 上下文约束
|
||||
|
||||
- 排序必须在过滤后生效（与年份筛选、标签筛选、搜索取交集）
|
||||
- 与其他控件保持一致的即时响应模式（change 事件）
|
||||
- 清空筛选时重置所有控件（包括排序）
|
||||
@@ -0,0 +1,47 @@
|
||||
# 排序功能规格
|
||||
|
||||
## Scenario: 用户按日期新→旧排序
|
||||
|
||||
**Given** 知识库索引面板已加载，显示 3 个条目
|
||||
**When** 用户选择排序下拉框的"日期 新→旧"
|
||||
**Then** 条目按日期降序排列（最新的在前）
|
||||
**And** 排序与当前激活的过滤条件（搜索、标签、年份）取交集
|
||||
|
||||
## Scenario: 用户按日期旧→新排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"日期 旧→新"
|
||||
**Then** 条目按日期升序排列（最旧的在前）
|
||||
|
||||
## Scenario: 用户按标签数量多→少排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"标签 多→少"
|
||||
**Then** 条目按标签数组长度降序排列（标签多的在前）
|
||||
|
||||
## Scenario: 用户按标签数量少→多排序
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户选择排序下拉框的"标签 少→多"
|
||||
**Then** 条目按标签数组长度升序排列（标签少的在前）
|
||||
|
||||
## Scenario: 排序与过滤组合
|
||||
|
||||
**Given** 用户已激活标签筛选（如"Claude Code"）
|
||||
**When** 用户切换排序模式
|
||||
**Then** 只有匹配的条目被排序显示
|
||||
**And** 排序不影响过滤逻辑本身
|
||||
|
||||
## Scenario: 清空筛选重置排序
|
||||
|
||||
**Given** 用户已选择非默认排序模式
|
||||
**When** 用户点击"清空筛选"按钮
|
||||
**Then** 排序重置为默认值"日期 新→旧"
|
||||
**And** 所有过滤条件也被清空
|
||||
|
||||
## Scenario: 排序即时响应
|
||||
|
||||
**Given** 知识库索引面板已加载
|
||||
**When** 用户切换排序下拉框
|
||||
**Then** 条目列表立即重新排列
|
||||
**And** 不需要点击"应用"按钮
|
||||
@@ -0,0 +1,25 @@
|
||||
# knowledge-index-sort Tasks
|
||||
|
||||
## 需求追踪
|
||||
|
||||
| 需求 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| 排序 UI 控件 | 已完成 | sort-select 下拉框 |
|
||||
| 排序逻辑实现 | 已完成 | applyFilters() 中排序段 |
|
||||
| 事件绑定 | 已完成 | bindSortSelect() |
|
||||
| 清空筛选重置 | 已完成 | clearFilters() 重置 sort-select |
|
||||
| 脚本同步 | 已完成 | update-knowledge-index.sh |
|
||||
| 浏览器验证 | 已完成 | 用户确认通过 |
|
||||
|
||||
## 实现任务
|
||||
|
||||
- [x] 在 filter-row 中添加 sort-select HTML（4 个 option）
|
||||
- [x] 在 applyFilters() 中添加排序逻辑（过滤后、渲染前）
|
||||
- [x] 实现 4 种排序模式（date-desc/date-asc/tags-desc/tags-asc）
|
||||
- [x] 添加 bindSortSelect() 函数绑定 change 事件
|
||||
- [x] 在 init 中调用 bindSortSelect()
|
||||
- [x] 在 clearFilters() 中重置 sort-select 为 date-desc
|
||||
- [x] 同步修改 scripts/update-knowledge-index.sh（HTML 模板 + JS 代码）
|
||||
- [x] 浏览器验证：测试 4 种排序模式
|
||||
- [x] 浏览器验证：测试排序与过滤组合
|
||||
- [x] 浏览器验证：测试清空筛选重置排序
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-22
|
||||
@@ -0,0 +1,115 @@
|
||||
## Context
|
||||
|
||||
这次 change 处理的是 `sm-flow` 的执行稳定性，而不是流程理念重构。已有文档已经定义了阶段顺序、Phase 2.9、接口影响、实现期冲突分类和 devflow 索引，但真实使用表明，规则如果没有变成“阶段切换前必须显式满足的条件”，就会在执行中被代理惯性绕开。
|
||||
|
||||
受影响的主要文件位于：
|
||||
|
||||
- `.agents/skills/sm-flow/SKILL.md`
|
||||
- `.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
- `.agents/skills/sm-flow/references/fallbacks.md`
|
||||
- `.agents/skills/sm-flow/references/templates.md`
|
||||
- `skill-workbench/docs/sm-flow/workflow.md`
|
||||
|
||||
这次改造的规则落点也需要明确分层：
|
||||
|
||||
- `SKILL.md` 承载短而硬的总规则和 gate。
|
||||
- `phase-contracts.md` 承载逐阶段进入、动作、退出和 checkpoint。
|
||||
- `fallbacks.md` 承载 capability 不可用时的降级协议与记录要求。
|
||||
- `templates.md` 只在确有必要时提供轻量字段提示，不承载主逻辑。
|
||||
- `workflow.md` 只解释设计与演进背景，不重复执行细则或承担执行真理源职责。
|
||||
|
||||
## Design
|
||||
|
||||
### 1. Phase checkpoints as executable gates
|
||||
|
||||
为每个关键阶段引入最小 checkpoint，要求代理在阶段结束时显式汇报：
|
||||
|
||||
1. 当前阶段名称。
|
||||
2. 本阶段调用的 skill / 本地 `SKILL.md` / fallback。
|
||||
3. 本阶段产物。
|
||||
4. 已满足的退出条件。
|
||||
5. 未满足但仍阻塞下一阶段的问题。
|
||||
|
||||
这个 checkpoint 不是替代现有 `phase-contracts.md`，而是把长契约压缩成执行中更容易遵守的门禁动作。
|
||||
本次设计只要求这些 checkpoint 具备明确字段和动作，不要求新增统一模板或统一展示格式。
|
||||
|
||||
### 2. Skill/fallback declaration becomes a completion condition
|
||||
|
||||
现有规则要求进入某些阶段时说明 skill 或 fallback，但执行中容易被忽略。硬化后：
|
||||
|
||||
- 若本阶段未显式声明使用的能力来源，则阶段不得视为完成。
|
||||
- 若发生 fallback，必须同时记录：目标 skill、不可用原因、采用的 fallback 协议、降级风险。
|
||||
|
||||
### 3. Phase 2 uses a question pool
|
||||
|
||||
现有规则强调 one-at-a-time，但没有约束问题覆盖面。硬化后，Phase 2 先生成问题池，再逐个消费：
|
||||
|
||||
- 问题池至少覆盖术语、边界、验收。
|
||||
- 对复杂任务，可继续覆盖权限、上下游触发、前端返回结构、兼容性、生命周期等。
|
||||
- `user-interview` 问题仍然一次只问一个，但问题池必须先暴露计划覆盖面。
|
||||
|
||||
这样既保留 human-in-the-loop 约束，也降低“只问了几个问题就误以为够了”的风险。
|
||||
|
||||
### 4. Cross-artifact alignment becomes explicit
|
||||
|
||||
Phase 1.5 和 2.9 需要明确检查的对齐关系：
|
||||
|
||||
- `brief/prd` -> `proposal`
|
||||
- `proposal` -> `design`
|
||||
- `design` -> `specs`
|
||||
- `specs` -> `tasks`
|
||||
- `evidence/decisions` -> OpenSpec 回写状态
|
||||
|
||||
如果任何链路出现信息缺失、术语不一致、能力未落到 spec、spec 未落到 task，都必须在进入下一阶段前暴露。
|
||||
|
||||
### 5. Micro mode preserves gates
|
||||
|
||||
`micro` 继续允许合并产物，但明确禁止跳过：
|
||||
|
||||
- Phase 0.5 最小上下文检查
|
||||
- Phase 2 最小澄清
|
||||
- Phase 2.9 commit gate
|
||||
- Phase 4 轻量归档
|
||||
|
||||
这次 change 不增加 `micro` 的文档负担，而是把“不能跳哪些 gate”写得更硬。
|
||||
|
||||
### 6. Devflow updates happen during the flow
|
||||
|
||||
`devflow` 不再被视为“最后补文档”。设计上要求：
|
||||
|
||||
- Phase 0 写入口摘要到 `brief.md`
|
||||
- Phase 2 写 evidence / decisions
|
||||
- Phase 2.5 写架构审计摘要
|
||||
- Phase 2.9 写 commit gate 结果
|
||||
- Phase 4 只做汇总和归档收尾
|
||||
|
||||
这样 Phase 4 变成收敛，而不是返工。
|
||||
|
||||
### 7. Rule placement avoids duplication drift
|
||||
|
||||
本次 change 的一个隐含架构约束是避免同一规则在多个层面双份维护：
|
||||
|
||||
- 如果某条规则属于执行门禁，应优先落在 `SKILL.md` 或 `phase-contracts.md`。
|
||||
- 如果某条规则属于 capability 降级，应优先落在 `fallbacks.md`。
|
||||
- `workflow.md` 可以解释为什么这样设计，但不应再逐条复制执行细则。
|
||||
- `templates.md` 保持可选和轻量，否则会把“协议硬化”扩大成“格式标准化”。
|
||||
|
||||
这能降低 v3.1 之后再次出现“规则已经写了，但代理仍然执行漂移”的维护风险。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 更强的 checkpoint 会增加少量流程显式成本，但可以换来更低的遗漏率。
|
||||
- 问题池可能让 Phase 2 看起来更正式，但如果不先暴露覆盖面，one-at-a-time 容易退化成随机追问。
|
||||
- 更硬的 cross-artifact 检查会让 change 前期更慢，但比在 apply 前后由用户兜底更可靠。
|
||||
- 如果把同一规则同时写进协议、模板和案例说明，后续维护面会再次变大，因此这轮需要严格控制规则落点。
|
||||
|
||||
## Validation
|
||||
|
||||
需要通过文档与 OpenSpec 产物验证以下结果：
|
||||
|
||||
- `sm-flow` 明确要求阶段 checkpoint。
|
||||
- `micro` 明确禁止跳过关键 gate。
|
||||
- Phase 2 明确先形成问题池，再一次一问推进。
|
||||
- Phase 1.5 / 2.9 明确 cross-artifact 检查链路。
|
||||
- devflow 的过程内同步更新要求被写入协议。
|
||||
- 不要求代理额外输出统一格式的阶段汇报示例。
|
||||
@@ -0,0 +1,47 @@
|
||||
## Why
|
||||
|
||||
`sm-flow` 已经建立了 `OpenSpec-first / Devflow-assisted` 的主从关系，也补入了 Draft/Committed OpenSpec、接口影响分级、Phase 2.9 和实现期冲突分类等关键规则。但真实项目复盘显示，代理仍然会按“先读代码、先形成方案、尽快推进实现”的习惯行动，而不是稳定经过 phase gate、自检和一致性检查。
|
||||
|
||||
当前问题不是主设计方向错误，而是执行协议还不够“硬”：
|
||||
|
||||
- `micro` 模式容易被误解为可以跳过关键阶段。
|
||||
- skill/fallback 声明存在规则，但没有成为阶段完成条件。
|
||||
- Phase 2 有 one-at-a-time 约束，但没有先形成问题池，导致问题覆盖不足。
|
||||
- Phase 1.5 和 2.9 的 cross-artifact 检查缺少更明确的执行清单，遗漏只能等用户 review 才暴露。
|
||||
- devflow 产物容易被拖到 Phase 4 补写，而不是在过程内同步更新。
|
||||
|
||||
因此需要新增一轮“执行硬化”改造，把现有规则收敛成更明确的阶段检查点、问题池机制和一致性检查要求。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 为 `sm-flow` 增加更短、更高频的 phase checklist / checkpoint 规则。
|
||||
- 明确“未显式声明 skill 或 fallback = 本阶段未完成”。
|
||||
- 为 Phase 2 增加“先形成问题池，再一次一问推进”的要求。
|
||||
- 强化 Phase 1.5 / 2.9 的 cross-artifact diff 检查，覆盖 proposal、design、specs、tasks、brief、evidence、decisions 的一致性。
|
||||
- 明确 `micro` 只能压缩产物，不能跳过 Phase 0.5、Phase 2、Phase 2.9 等关键 gate。
|
||||
- 明确 devflow 默认在各阶段同步更新，而不是拖到 Phase 4 统一补写。
|
||||
- 明确本次改造不强制固定 checkpoint / alignment 模板，也不把统一阶段汇报格式纳入验收范围。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `sm-flow-phase-checkpoints`: 定义各阶段的最小检查点和阶段完成条件。
|
||||
- `sm-flow-question-pool`: 定义 Phase 2 的问题池生成与单题推进规则。
|
||||
- `sm-flow-cross-artifact-alignment`: 定义 Phase 1.5 / 2.9 的跨产物一致性检查要求。
|
||||
- `sm-flow-micro-gate-preservation`: 定义 `micro` 模式下不可跳过的关键 gate。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `sm-flow-commit-gate`: 增强提交前检查，补充 cross-artifact diff 和阶段状态显式确认。
|
||||
- `sm-flow-context-indexing`: 补充 devflow 过程内同步更新要求。
|
||||
|
||||
## Impact
|
||||
|
||||
- 修改 `.agents/skills/sm-flow/SKILL.md`
|
||||
- 修改 `.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
- 修改 `.agents/skills/sm-flow/references/fallbacks.md`
|
||||
- 可能修改 `.agents/skills/sm-flow/references/templates.md`
|
||||
- 修改 `skill-workbench/docs/sm-flow/workflow.md`
|
||||
- 不修改业务代码
|
||||
- 不改变 `OpenSpec-first / Devflow-assisted` 主设计
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
|
||||
|
||||
SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
|
||||
|
||||
#### Scenario: Alignment check runs
|
||||
|
||||
- **WHEN** Phase 1.5 reviews the current Draft OpenSpec
|
||||
- **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
|
||||
|
||||
#### Scenario: Alignment gap is found
|
||||
|
||||
- **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
|
||||
- **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
|
||||
|
||||
### Requirement: Phase 2.9 validates cross-artifact closure
|
||||
|
||||
SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
|
||||
|
||||
#### Scenario: Commit gate runs
|
||||
|
||||
- **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
|
||||
- **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
|
||||
|
||||
#### Scenario: User review would otherwise catch the gap
|
||||
|
||||
- **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
|
||||
- **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Micro mode compresses artifacts but preserves critical gates
|
||||
|
||||
SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
|
||||
|
||||
#### Scenario: Micro mode starts
|
||||
|
||||
- **WHEN** a change is classified as `micro`
|
||||
- **THEN** the flow may merge or simplify devflow artifacts
|
||||
- **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
|
||||
|
||||
#### Scenario: Micro mode is treated as skip permission
|
||||
|
||||
- **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
|
||||
- **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
|
||||
|
||||
### Requirement: Devflow updates happen during the flow
|
||||
|
||||
SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
|
||||
|
||||
#### Scenario: Phase-local information is produced
|
||||
|
||||
- **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
|
||||
- **THEN** the corresponding devflow artifact is updated in or near that phase
|
||||
|
||||
#### Scenario: Phase 4 begins
|
||||
|
||||
- **WHEN** the flow enters Phase 4
|
||||
- **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written
|
||||
@@ -0,0 +1,34 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Each critical phase has an explicit checkpoint
|
||||
|
||||
SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
|
||||
|
||||
#### Scenario: Phase completes normally
|
||||
|
||||
- **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
|
||||
- **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
|
||||
|
||||
#### Scenario: Checkpoint is missing
|
||||
|
||||
- **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
|
||||
- **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
|
||||
|
||||
### Requirement: Capability declaration is part of phase completion
|
||||
|
||||
SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
|
||||
|
||||
#### Scenario: Native skill or local protocol is used
|
||||
|
||||
- **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
|
||||
- **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
|
||||
|
||||
#### Scenario: Fallback is used
|
||||
|
||||
- **WHEN** a phase falls back from a named capability
|
||||
- **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
|
||||
|
||||
#### Scenario: Declaration is omitted
|
||||
|
||||
- **WHEN** no capability source is declared for a phase that requires one
|
||||
- **THEN** that phase SHALL NOT be considered complete
|
||||
@@ -0,0 +1,29 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Phase 2 builds a question pool before interviewing
|
||||
|
||||
SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
|
||||
|
||||
#### Scenario: Phase 2 starts
|
||||
|
||||
- **WHEN** the flow enters Phase 2
|
||||
- **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
|
||||
|
||||
#### Scenario: Complex change needs deeper coverage
|
||||
|
||||
- **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
|
||||
- **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
|
||||
|
||||
### Requirement: User-interview questions remain one-at-a-time
|
||||
|
||||
SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
|
||||
|
||||
#### Scenario: User-interview question is asked
|
||||
|
||||
- **WHEN** the next unresolved `user-interview` item is selected from the question pool
|
||||
- **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
|
||||
|
||||
#### Scenario: Question pool exists but answer is missing
|
||||
|
||||
- **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
|
||||
- **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved
|
||||
@@ -0,0 +1,24 @@
|
||||
## 1. OpenSpec artifacts
|
||||
|
||||
- [x] 1.1 Write proposal for `sm-flow-execution-hardening`
|
||||
- [x] 1.2 Write design for execution hardening rules
|
||||
- [x] 1.3 Add specs for checkpoints, question pool, cross-artifact alignment, and micro gate preservation
|
||||
|
||||
## 2. Protocol hardening
|
||||
|
||||
- [x] 2.1 Update `.agents/skills/sm-flow/SKILL.md` with explicit phase checkpoint and stage-completion rules
|
||||
- [x] 2.2 Update `.agents/skills/sm-flow/references/phase-contracts.md` with question pool, cross-artifact alignment, and micro gate preservation rules
|
||||
- [x] 2.3 Update `.agents/skills/sm-flow/references/fallbacks.md` so fallback declaration is mandatory and recorded
|
||||
- [x] 2.4 Keep templates optional; only adjust them if existing references need minimal field hints rather than mandatory fixed formats
|
||||
|
||||
## 3. Workflow documentation
|
||||
|
||||
- [x] 3.1 Update `skill-workbench/docs/sm-flow/workflow.md` with the execution-hardening model
|
||||
- [x] 3.2 Ensure retrospective learnings are reflected as protocol rules rather than only narrative notes
|
||||
|
||||
## 4. Validation
|
||||
|
||||
- [x] 4.1 Validate the OpenSpec change
|
||||
- [x] 4.2 Verify key terms are consistently documented across skill, references, and workflow docs
|
||||
- [x] 4.3 Backfill devflow records after implementation if the change proceeds beyond Draft
|
||||
- [x] 4.4 Verify acceptance is satisfied by protocol/document changes alone, without requiring a standardized phase-report output format
|
||||
@@ -0,0 +1,20 @@
|
||||
schema: spec-driven
|
||||
|
||||
# Project context (optional)
|
||||
# This is shown to AI when creating artifacts.
|
||||
# Add your tech stack, conventions, style guides, domain knowledge, etc.
|
||||
# Example:
|
||||
# context: |
|
||||
# Tech stack: TypeScript, React, Node.js
|
||||
# We use conventional commits
|
||||
# Domain: e-commerce platform
|
||||
|
||||
# Per-artifact rules (optional)
|
||||
# Add custom rules for specific artifacts.
|
||||
# Example:
|
||||
# rules:
|
||||
# proposal:
|
||||
# - Keep proposals under 500 words
|
||||
# - Always include a "Non-goals" section
|
||||
# tasks:
|
||||
# - Break tasks into chunks of max 2 hours
|
||||
@@ -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"，降低执行复杂度同时保留核心约束。
|
||||
@@ -0,0 +1,216 @@
|
||||
# SM Flow Phase Contracts v4.1 更新日志
|
||||
|
||||
> 更新日期: 2026-06-23
|
||||
> 更新原因: 基于"山东商客意向单同步接口"执行复盘
|
||||
> 更新方案: 方案 B（简化版）
|
||||
|
||||
---
|
||||
|
||||
## 更新概览
|
||||
|
||||
**核心目标**: 减少 apply 阶段的返工次数（从 4-5 次降低到 0-1 次）
|
||||
|
||||
**更新范围**:
|
||||
- ✅ grill 阶段：增加技术实现维度
|
||||
- ✅ apply 阶段：增加 Pre-apply Checkpoint
|
||||
|
||||
**文本增量**: +55 行（从 281 行 → 336 行，+20%）
|
||||
|
||||
---
|
||||
|
||||
## 详细修改
|
||||
|
||||
### 1. grill 阶段 — 增加技术实现维度
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 85-88 行
|
||||
|
||||
**新增内容**:
|
||||
```markdown
|
||||
- **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
|
||||
- 参考实现的具体文件路径是什么？
|
||||
- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
|
||||
- 有哪些技术点需要先调研或新建？
|
||||
```
|
||||
|
||||
**目的**: 在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
|
||||
|
||||
---
|
||||
|
||||
### 2. apply 阶段 — 增加 Pre-apply Checkpoint
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 234-265 行
|
||||
|
||||
**新增章节**: Pre-apply Checkpoint（15-20 分钟）
|
||||
|
||||
#### 触发条件（3 条）
|
||||
- design 或 tasks 中提到"参考 XXX 实现"
|
||||
- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
|
||||
- 技术栈不熟悉或第一次在该项目实现类似功能
|
||||
|
||||
#### 执行步骤（3 步）
|
||||
1. **完整阅读所有参考实现**（约 10 分钟）
|
||||
- 从 OpenSpec design 或 tasks 中定位参考实现文件
|
||||
- 如果路径不明确，通过 Grep 搜索关键类名或模式
|
||||
- 逐行理解关键逻辑，提取可复用代码片段和模式
|
||||
|
||||
2. **Grep 关键技术栈**（约 5 分钟）
|
||||
- 请求/响应结构模式
|
||||
- 消息队列模式
|
||||
- 统一工具类
|
||||
- 异常处理和日志记录标准
|
||||
|
||||
3. **形成技术栈清单并写入 decisions.md**
|
||||
- 项目使用的请求/响应结构标准
|
||||
- MQ 消息定义和发送标准
|
||||
- Consumer 标准位置和写法
|
||||
- 加密/验签/工具类的标准用法
|
||||
- 识别需要新建的工具类或基础设施
|
||||
|
||||
#### 输出要求（3 条）
|
||||
- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
|
||||
- ✅ 已列出所有参考实现的文件路径
|
||||
- ✅ 已识别需要新建的工具类/基础设施
|
||||
|
||||
#### 快速模式支持
|
||||
- micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单
|
||||
|
||||
---
|
||||
|
||||
### 3. apply 阶段 — 实现过程增强
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 267-284 行
|
||||
|
||||
**新增要求**:
|
||||
- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序
|
||||
- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能不允许空实现或纯 TODO 注释
|
||||
- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报
|
||||
|
||||
---
|
||||
|
||||
### 4. apply 阶段 — 退出条件增强
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 286-292 行
|
||||
|
||||
**新增退出条件**:
|
||||
- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
|
||||
- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
|
||||
|
||||
---
|
||||
|
||||
## 简化对比
|
||||
|
||||
### 与完整方案对比
|
||||
|
||||
| 维度 | 完整方案 | 简化方案 B | 差异 |
|
||||
|------|----------|-----------|------|
|
||||
| 文本增量 | +100 行 | +55 行 | -45% |
|
||||
| 子阶段数 | 3 个（Phase 1/2/3） | 1 个（Pre-apply Checkpoint） | -67% |
|
||||
| 强制规则 | 9 条 | 5 条 | -44% |
|
||||
| 检查清单 | 2 个详细清单 | 1 个简化清单 | -50% |
|
||||
| 时间分档 | 3 档（15/20/30 分钟） | 1 档（15-20 分钟） | -67% |
|
||||
|
||||
### 保留核心价值
|
||||
|
||||
✅ **保留**（解决返工问题）:
|
||||
- 前置调研（最重要）
|
||||
- 技术栈清单（防止想当然）
|
||||
- 核心功能不能空实现（保证质量）
|
||||
- 快速失败机制
|
||||
|
||||
❌ **简化**（去掉过度约束）:
|
||||
- 严格的执行顺序
|
||||
- 频繁的检查点
|
||||
- 详细的操作指南模板
|
||||
|
||||
---
|
||||
|
||||
## 预期效果
|
||||
|
||||
### 量化指标
|
||||
|
||||
| 指标 | 当前 | 目标 | 改善 |
|
||||
|------|------|------|------|
|
||||
| 返工次数 | 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%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
### ✅ 强烈推荐
|
||||
|
||||
- 中等及以上规模需求（3+ 接口或涉及多模块）
|
||||
- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
|
||||
- 第一次在该项目实现类似功能
|
||||
- 设计文档提到"参考 XXX 实现"
|
||||
|
||||
### 🟡 可选执行
|
||||
|
||||
- micro 分档的简单需求（可缩短为 5-10 分钟）
|
||||
- 纯数据处理或工具脚本（技术栈熟悉）
|
||||
|
||||
### ❌ 不推荐
|
||||
|
||||
- 紧急热修复（时间紧急）
|
||||
- 一次性脚本（不涉及项目标准）
|
||||
|
||||
---
|
||||
|
||||
## 后续优化方向
|
||||
|
||||
### 短期（1-2 个需求后）
|
||||
|
||||
- 收集数据：实际调研时间、返工次数、遗漏率
|
||||
- 验证效果：是否达到预期 ROI
|
||||
- 调整参数：时间要求、触发条件
|
||||
|
||||
### 中期（观察 5+ 个需求后）
|
||||
|
||||
如果效果显著，考虑升级为完整方案：
|
||||
- 增加 Alignment Checkpoint（每模块对齐检查）
|
||||
- 增加详细的技术栈清单模板
|
||||
- 增加分步实现的每步验证要求
|
||||
|
||||
### 长期（跨项目验证后）
|
||||
|
||||
- 提取通用技术栈清单模板（Java/Go/Python 等）
|
||||
- 建立参考实现库（常见模式的最佳实践）
|
||||
- 自动化部分调研步骤（Grep 脚本、清单生成）
|
||||
|
||||
---
|
||||
|
||||
## 实施检查清单
|
||||
|
||||
### 立即验证
|
||||
|
||||
- [ ] `phase-contracts.md` 文件已更新
|
||||
- [ ] grill 阶段增加了技术实现维度
|
||||
- [ ] apply 阶段增加了 Pre-apply Checkpoint
|
||||
- [ ] apply 退出条件增加了 2 条新检查
|
||||
- [ ] 文件语法无误，可以正常解析
|
||||
|
||||
### 下次执行验证
|
||||
|
||||
- [ ] agent 是否正确识别触发条件
|
||||
- [ ] agent 是否执行了完整的 3 步调研
|
||||
- [ ] 技术栈清单是否写入 decisions.md
|
||||
- [ ] 是否有效减少了返工次数
|
||||
- [ ] 核心功能是否避免了空实现
|
||||
|
||||
---
|
||||
|
||||
## 附录：复盘案例链接
|
||||
|
||||
- 原始复盘文档: `skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
|
||||
- 修改前版本: phase-contracts.md (commit: 待补充)
|
||||
- 修改后版本: phase-contracts.md (commit: 待补充)
|
||||
@@ -0,0 +1,307 @@
|
||||
# SM Flow Phase Contracts v4.2 更新日志
|
||||
|
||||
> 更新日期: 2026-06-24
|
||||
> 更新原因: 基于"lookup-knowledge-integration"执行复盘
|
||||
> 更新方案: 增强执行机制，引入可验证 checkpoint
|
||||
|
||||
---
|
||||
|
||||
## 更新概览
|
||||
|
||||
**核心目标**: 解决"约束是软性的"问题，增加可执行的检查机制
|
||||
|
||||
**更新范围**:
|
||||
- ✅ commit 阶段：增加文件完整性和一致性检查清单
|
||||
- ✅ apply 阶段：增加前置门控（.committed 文件检查）
|
||||
- ✅ archive 阶段：增加强制执行顺序（5 步 checklist）
|
||||
|
||||
**文本增量**: +80 行
|
||||
|
||||
---
|
||||
|
||||
## 核心问题诊断
|
||||
|
||||
### 问题根源：约束是"软性"的，缺少执行机制
|
||||
|
||||
| 问题 | 现象 | 影响 | 根本原因 |
|
||||
|------|------|------|----------|
|
||||
| **Commit 检查缺标准** | 不知道如何判断"通过 commit 检查" | agent 跳过 commit 直接进入 apply | 只说"检查是否可执行"，没说具体检查什么 |
|
||||
| **Apply 缺前置门控** | 用户说"修复"就直接开始实现 | 可能基于不完整的 OpenSpec | 进入条件是软性描述，没有文件检查 |
|
||||
| **Archive 无 Checklist** | 先创建 handoff，忘记 devflow | 归档流程不完整 | 没有强制执行顺序 |
|
||||
|
||||
---
|
||||
|
||||
## 详细修改
|
||||
|
||||
### 1. Commit 阶段 — 增加可验证 Checkpoint
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 208-221 行
|
||||
|
||||
**新增内容**:
|
||||
|
||||
#### 文件完整性检查（必须全部通过）
|
||||
|
||||
- [ ] `proposal.md` 存在，包含问题描述（至少 50 字）、建议方案（至少 100 字）、范围/非目标
|
||||
- [ ] `design.md` 存在，包含架构设计（文字或图）、数据结构定义（至少 1 个）、关键决策记录（至少 2 条）
|
||||
- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
|
||||
- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
|
||||
|
||||
#### 一致性检查（必须通过）
|
||||
|
||||
- [ ] proposal 中的核心概念在 design 中有对应设计
|
||||
- [ ] design 中的关键决策在 tasks 中有对应实现任务
|
||||
- [ ] tasks 的验收标准可验证（不是"正确实现""完成功能"这类模糊描述）
|
||||
|
||||
#### 标记文件
|
||||
|
||||
检查通过后，创建 `openspec/changes/{slug}/.committed` 文件标记为 Committed OpenSpec
|
||||
|
||||
**目的**:
|
||||
- 提供明确的"可执行状态"判断标准
|
||||
- 强制 agent 完成所有检查项
|
||||
- 通过 `.committed` 文件提供下游门控依据
|
||||
|
||||
---
|
||||
|
||||
### 2. Apply 阶段 — 增加前置门控检查
|
||||
|
||||
**修改位置**: `phase-contracts.md` 第 233-244 行
|
||||
|
||||
**新增内容**:
|
||||
|
||||
#### 前置门控检查（硬约束）
|
||||
|
||||
1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
|
||||
2. 如不存在，执行以下流程：
|
||||
- 汇报：Draft OpenSpec 未通过 commit 检查
|
||||
- 列出缺失的 checkpoint 项（文件完整性、一致性检查）
|
||||
- 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
|
||||
|
||||
**目的**:
|
||||
- 强制 apply 依赖 Committed OpenSpec
|
||||
- 阻止基于不完整 OpenSpec 的实现
|
||||
- 提供补救路径（补做 commit 或显式跳过）
|
||||
|
||||
---
|
||||
|
||||
### 3. Archive 阶段 — 增加强制执行顺序
|
||||
|
||||
**修改位置**: `archive-rules.md` 第 5-41 行
|
||||
|
||||
**新增章节**: Archive 强制执行顺序
|
||||
|
||||
#### Step 1: 创建 devflow 档案（必需）
|
||||
|
||||
- [ ] 创建 `brief.md`（从 proposal.md 提取）
|
||||
- [ ] 创建 `evidence.md`（从 decisions.md 提取）
|
||||
- [ ] 创建 `decisions.md`（整理为最终版）
|
||||
- [ ] 创建 `acceptance.md`（记录验证情况）
|
||||
|
||||
#### Step 2: 更新索引（必需）
|
||||
|
||||
- [ ] 在 `devflow/index.md` 末尾追加或更新一行
|
||||
|
||||
#### Step 3: 标记 OpenSpec（必需）
|
||||
|
||||
- [ ] 创建 `openspec/changes/{slug}/.archive-ready` 文件
|
||||
|
||||
#### Step 4: 向用户汇报（必需）
|
||||
|
||||
- [ ] 列出创建的 devflow 档案文件路径（验证文件实际存在）
|
||||
- [ ] 汇报验证情况（按类型分类）
|
||||
- [ ] 列出剩余风险
|
||||
- [ ] 询问：**是否现在归档 OpenSpec？**
|
||||
|
||||
#### Step 5: 用户确认后执行 OpenSpec Archive（可选）
|
||||
|
||||
- [ ] 调用 `openspec-archive-change`
|
||||
- [ ] 记录 archive 结果
|
||||
|
||||
**自检**: 在执行 Step 4 前，检查 Step 1-3 是否都完成。
|
||||
|
||||
**目的**:
|
||||
- 强制 devflow 档案优先（不再先创建 handoff）
|
||||
- 提供明确的执行顺序，避免遗漏
|
||||
- 通过 `.archive-ready` 文件标记完成状态
|
||||
|
||||
---
|
||||
|
||||
## 新增门控文件
|
||||
|
||||
| 文件 | 创建时机 | 用途 |
|
||||
|------|----------|------|
|
||||
| `.committed` | commit 阶段退出时 | apply 阶段前置门控 |
|
||||
| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
|
||||
|
||||
---
|
||||
|
||||
## 预期效果
|
||||
|
||||
### 量化指标
|
||||
|
||||
| 指标 | v4.1 | v4.2 目标 | 改善 |
|
||||
|------|------|-----------|------|
|
||||
| Commit 阶段跳过率 | 高（无明确标准） | 0%（有 checklist） | -100% |
|
||||
| Apply 基于不完整 OpenSpec | 可能发生 | 0%（门控阻止） | -100% |
|
||||
| Archive 遗漏 devflow | 可能发生 | 0%（强制顺序） | -100% |
|
||||
|
||||
### 质量提升
|
||||
|
||||
**Commit 阶段**:
|
||||
- ✅ 明确什么叫"可执行状态"
|
||||
- ✅ agent 无法跳过检查清单
|
||||
- ✅ 提供 `.committed` 文件作为凭证
|
||||
|
||||
**Apply 阶段**:
|
||||
- ✅ 强制检查 `.committed` 文件存在
|
||||
- ✅ 阻止基于不完整 OpenSpec 的实现
|
||||
- ✅ 提供补救路径
|
||||
|
||||
**Archive 阶段**:
|
||||
- ✅ 强制 devflow 优先（不再先创建 handoff）
|
||||
- ✅ 5 步 checklist 避免遗漏
|
||||
- ✅ 自检机制确保完整性
|
||||
|
||||
---
|
||||
|
||||
## 与 v4.1 的关系
|
||||
|
||||
| 版本 | 核心改进 | 解决问题 |
|
||||
|------|----------|----------|
|
||||
| v4.1 | Pre-apply Research Checkpoint | apply 阶段前置调研不足，导致返工 |
|
||||
| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
|
||||
|
||||
**互补关系**:
|
||||
- v4.1 解决"调研不充分导致返工"
|
||||
- v4.2 解决"缺少执行机制导致跳过阶段"
|
||||
|
||||
---
|
||||
|
||||
## 设计原则
|
||||
|
||||
### 1. 可验证性
|
||||
|
||||
**Before**: "检查 OpenSpec 是否可执行"（模糊）
|
||||
**After**: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"（具体）
|
||||
|
||||
### 2. 门控文件
|
||||
|
||||
**Before**: 软性描述"已通过 commit"
|
||||
**After**: 硬性检查 `.committed` 文件存在
|
||||
|
||||
### 3. 强制顺序
|
||||
|
||||
**Before**: 建议性"应该先 devflow 后 handoff"
|
||||
**After**: 5 步 checklist，不得跳过或重排
|
||||
|
||||
---
|
||||
|
||||
## 复杂度评估
|
||||
|
||||
**本次修改复杂度**: 低-中等
|
||||
- 文本增量: +80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
|
||||
- 概念增加: 2 个门控文件（.committed, .archive-ready）
|
||||
- 规则增强: 3 个阶段的检查清单
|
||||
|
||||
**整体复杂度**: 高（但更可靠）
|
||||
- 总行数: ~700 行 → ~780 行（+11%）
|
||||
- 门控数: 6 个 → 8 个（+commit 文件完整性 + apply 前置门控）
|
||||
- 强制清单: +3 个（commit 文件完整性、commit 一致性、archive 5 步）
|
||||
|
||||
**权衡**:
|
||||
- ✅ 收益: 彻底解决"跳过阶段"问题
|
||||
- ⚠️ 成本: 增加 80 行文本，agent 需检查更多项
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
### ✅ 所有场景（无例外）
|
||||
|
||||
v4.2 的改进是**执行机制**层面的，不涉及业务逻辑：
|
||||
- 无论 micro/standard/complex，都需要 commit 检查
|
||||
- 无论需求大小，都需要 apply 前置门控
|
||||
- 无论项目规模，都需要 archive 强制顺序
|
||||
|
||||
### 快速模式
|
||||
|
||||
快速模式可以简化产物（如 tasks 只需 3 个子任务），但**不能跳过门控**：
|
||||
- ✅ 仍需 commit 检查（即使 tasks 数量少）
|
||||
- ✅ 仍需 apply 前置门控
|
||||
- ✅ 仍需 archive 强制顺序
|
||||
|
||||
---
|
||||
|
||||
## 实施验证
|
||||
|
||||
### 验证计划
|
||||
|
||||
下次完整执行 sm-flow 时，检查：
|
||||
|
||||
1. **Commit 阶段**:
|
||||
- [ ] agent 是否执行了文件完整性检查？
|
||||
- [ ] agent 是否执行了一致性检查？
|
||||
- [ ] agent 是否创建了 `.committed` 文件？
|
||||
|
||||
2. **Apply 阶段**:
|
||||
- [ ] agent 是否检查了 `.committed` 文件存在？
|
||||
- [ ] 如不存在，agent 是否汇报并询问用户？
|
||||
|
||||
3. **Archive 阶段**:
|
||||
- [ ] agent 是否按 5 步顺序执行？
|
||||
- [ ] agent 是否在 Step 4 前自检了 Step 1-3？
|
||||
- [ ] agent 是否创建了 `.archive-ready` 文件？
|
||||
|
||||
### 成功标准
|
||||
|
||||
- ✅ 无未经检查的 commit → apply 跳转
|
||||
- ✅ 无基于不完整 OpenSpec 的实现
|
||||
- ✅ 无先创建 handoff 后补 devflow 的情况
|
||||
|
||||
---
|
||||
|
||||
## 后续演进方向
|
||||
|
||||
### v5.0 候选特性（观察 3+ 次执行后决定）
|
||||
|
||||
如果 v4.2 执行良好，但仍有问题，考虑：
|
||||
|
||||
1. **流程状态文件** `.sm-flow-state`
|
||||
- 记录当前阶段、已完成阶段、时间戳
|
||||
- 支持断点续做
|
||||
|
||||
2. **更多门控文件**
|
||||
- `.context-done`（context 阶段完成）
|
||||
- `.grill-done`（grill 阶段完成）
|
||||
- `.apply-done`（apply 阶段完成）
|
||||
|
||||
3. **违规自检机制**
|
||||
- 每个阶段退出前，自动检查是否违反 6 条硬约束
|
||||
|
||||
4. **进度可视化**
|
||||
- 每次开始时，汇报进度条（9 个阶段的完成情况）
|
||||
|
||||
**判断依据**: 如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 执行复盘: `skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
|
||||
- 修改文件:
|
||||
- `.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
- `.agents/skills/sm-flow/references/archive-rules.md`
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
**v4.2 的核心理念**: 把"软性约束"变成"硬性检查"
|
||||
|
||||
| 改进点 | Before | After |
|
||||
|--------|--------|-------|
|
||||
| Commit 标准 | "可执行状态"（模糊） | 文件完整性 + 一致性检查清单 |
|
||||
| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
|
||||
| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检 |
|
||||
|
||||
**预期效果**: 彻底解决"agent 跳过阶段"问题，提升流程可靠性。
|
||||
@@ -0,0 +1,208 @@
|
||||
# SM Flow 首次执行回顾
|
||||
|
||||
**日期**：2026-05-21
|
||||
**变更**：[ops-message-support](projects/2026-05-21-ops-message-support/) — 站内消息新增 OMC 支持
|
||||
**目的**：以本次交互为例，逐阶段复盘实际执行与 SM Flow 预期的差距，作为后续执行的改进依据。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — 入口澄清
|
||||
|
||||
### 应该做的
|
||||
- 收集问题、期望结果、目标用户、涉及代码区域、约束条件
|
||||
- 输出入口摘要、slug、规模分档
|
||||
|
||||
### 实际做的
|
||||
- 用户输入需求后，直接开始读代码和查数据库
|
||||
- 输出了 slug（`ops-message-support`）和分档（micro）
|
||||
|
||||
### 没做到的
|
||||
- 没有输出入口摘要（清晰的 1-2 句话问题 + 1-2 句话期望结果）
|
||||
- 没有列已知影响代码或模块清单
|
||||
|
||||
### 改进建议
|
||||
- Phase 0 结束时花 1 分钟写 3-5 行入口摘要到 `brief.md`，而不是等用户问再补
|
||||
|
||||
---
|
||||
|
||||
## Phase 0.5 — Devflow 上下文收集
|
||||
|
||||
### 应该做的
|
||||
- 初始化 devflow 目录结构
|
||||
- 读取 glossary、ADR、历史项目
|
||||
- 形成上下文摘要写入 brief.md
|
||||
|
||||
### 实际做的
|
||||
- 等用户质疑 devflow 无产物时才在 Phase 2.9 补创建
|
||||
|
||||
### 没做到的
|
||||
- ❌ **没有在 Phase 0.5 创建 devflow 项目目录和任何文件**
|
||||
- 没检查 glossary（当时为空也正常，但应该初始化和告知）
|
||||
|
||||
### 改进建议
|
||||
- 进入 Phase 0.5 就执行 `mkdir devflow/projects/{slug}/` 并创建 `brief.md` 骨架
|
||||
- Devflow 是"思考记录"不是"文档任务"，哪怕只写 3 行也比事后补强
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — OpenSpec propose
|
||||
|
||||
### 应该做的
|
||||
- 声明"本阶段调用 openspec-propose skill"
|
||||
- 如果不可用，降级为 fallback 并说明原因
|
||||
- 产出 proposal / design / specs / tasks
|
||||
|
||||
### 实际做的
|
||||
- 调用了 `openspec new change` 创建了 change 目录
|
||||
- openspec CLI 模板不匹配时报错，**没有声明降级**，直接手动创建文件
|
||||
- 手动创建了 research、proposal、design、specs、tasks
|
||||
|
||||
### 没做到的
|
||||
- ❌ **没有声明"openspec CLI 模板不匹配，降级为 manual fallback"**
|
||||
- ❌ **没有区分 Draft OpenSpec 和 Committed OpenSpec**（两者在流程中意义不同）
|
||||
- 产出顺序按了 research-first schema，但未验证 artifacts 间的依赖一致性
|
||||
|
||||
### 改进建议
|
||||
- Skill 不可用时必须说清楚：什么 skill + 什么原因不可用 + 降级方式
|
||||
- Draft OpenSpec 阶段标记为 draft，和 Committed OpenSpec 区分
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5 — PRD / OpenSpec 对齐
|
||||
|
||||
### 应该做的
|
||||
- 检查 proposal 是否覆盖 research 范围
|
||||
- 检查 design 是否满足 proposal 承诺的能力
|
||||
- 检查接口影响等级（L1-L4）
|
||||
|
||||
### 实际做的
|
||||
- **直接跳过**，没有做任何 formal 的对齐检查
|
||||
|
||||
### 没做到的
|
||||
- ❌ 对齐检查完全缺失
|
||||
- 后果：proposal.md 漏了 type 字段，design.md 和 research.md 都已包含但 proposal 没更新，直到用户 review 才发现
|
||||
|
||||
### 改进建议
|
||||
- 即使 micro 模式，至少做一次快速交叉检查：research 范围 ↔ proposal 变更 ↔ design 决策 ↔ specs 场景
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Human-in-the-loop 澄清
|
||||
|
||||
### 应该做的
|
||||
- 声明"本阶段调用 grill-with-docs skill"，按结构化方式追问
|
||||
- 至少覆盖术语、边界、验收三个维度
|
||||
- evidence-driven 的先查证再汇报
|
||||
- user-interview 的**一次只问一个问题**，等用户确认后再问下一个
|
||||
- 用户确认后回写 OpenSpec
|
||||
- 对模糊的术语（如"运管"）通过 grill 确认其准确定义
|
||||
|
||||
### 实际做的
|
||||
- **没有调用 grill-with-docs** ❌
|
||||
- **一次问了 3 个 user-interview 问题**，违反规则 ❌
|
||||
- 收集了充分的 evidence（代码和数据库分析到位）✓
|
||||
- 用户确认后及时回写了 OpenSpec ✓
|
||||
|
||||
### 没做到的
|
||||
- ❌ 没有使用 grill 或任何结构化追问工具，自己随意问了几个问题
|
||||
- ❌ 一次多问被用户 reject
|
||||
- 问题数量太少：只用了 3 个问题（编码、子分类、字段范围），远不足以覆盖所有盲区
|
||||
- 以下该问但没有问的问题：
|
||||
- OMC 消息从哪里发送？通过什么 identifier/messageCode 触发投递？
|
||||
- OMC 用户侧的权限体系是怎样的？和 APP 用户在同一张权限表吗？
|
||||
- OMC 前端需要怎样的响应结构？只要总数还是要子分类列表？
|
||||
- 现有 APP 端有 hasUnread/readAll 等功能，OMC 端是否也需要？
|
||||
- OMC 消息的创建时间和保留策略？
|
||||
- "运管"这个概念从一开始就模棱两可，没有通过 grilling 追根究底，到用户主动纠正为 OMC 时才明确
|
||||
|
||||
### 改进建议
|
||||
- 必须调用 grill-with-docs，不调用就是跳过
|
||||
- 问题数量下限：至少 5-8 个尝试性提问，覆盖：术语定义、发送来源、权限模型、前端需求、功能对标
|
||||
- 一次一问，等回复后再继续
|
||||
- 在 Phase 2 开始时创建 Task 跟踪 grill 进度："Q1[术语]...→Q2[边界]...→Q3[验收]..."，每问一个更新一次
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.5 — 架构审计
|
||||
|
||||
### 应该做的
|
||||
- 画出输入 → 处理 → 输出的模块链路
|
||||
- 识别跨模块依赖、数据所有权、生命周期和耦合风险
|
||||
- 用不超过五句话写出架构风险评估
|
||||
- 影响实现的结论回写 OpenSpec design/tasks
|
||||
|
||||
### 实际做的
|
||||
- **直接跳过**
|
||||
- 做了代码分析但未输出正式的架构审计记录
|
||||
|
||||
### 没做到的
|
||||
- ❌ 模块链路图缺失
|
||||
- ❌ 接口影响分析表是用户追问后才补的
|
||||
- ❌ listMessageCategory 泄漏 OMC 的问题在架构审计中本应发现，但跳过后留到了用户 review 才发现
|
||||
|
||||
### 改进建议
|
||||
- Phase 2.5 至少画一张文本链路图：`User → Controller → Service → Mapper → DB`
|
||||
- 然后问自己：新增的 type 字段会影响哪些链路节点？
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.9 — Commit OpenSpec
|
||||
|
||||
### 应该做的
|
||||
- 检查所有 artifacts 的一致性
|
||||
- 检查所有 user-interview 都已确认
|
||||
- 检查接口影响已记录
|
||||
- 向用户汇报并请求 Phase 3 授权
|
||||
|
||||
### 实际做的
|
||||
- 做了检查，但不够彻底（proposal 漏了 type）
|
||||
- 接口影响分析是补的
|
||||
- 汇报了，但用户先发现了 type 字段问题
|
||||
|
||||
### 没做到的
|
||||
- 没能在用户发现问题前自己找出 proposal 遗漏
|
||||
- 自检清单没有对照执行
|
||||
|
||||
### 改进建议
|
||||
- Phase 2.9 不能光靠头脑检查，要逐行对比 research ↔ proposal ↔ design ↔ specs ↔ tasks 的关键断言
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
|
||||
尚未开始
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — 回填 Devflow
|
||||
|
||||
### 应该做的
|
||||
- 验收记录
|
||||
- 更新 devflow/index.md
|
||||
- 询问是否归档 OpenSpec change
|
||||
|
||||
### 实际做的
|
||||
- devflow 产物在用户要求下补创建
|
||||
- index.md 在用户质疑后创建
|
||||
|
||||
### 改进建议
|
||||
- Phase 4 的 devflow 产物应该是最轻松的，因为内容已经在各阶段产出过，只需要汇总
|
||||
|
||||
---
|
||||
|
||||
## 根因总结
|
||||
|
||||
### 约束是否到位？
|
||||
|
||||
SM Flow 的 rules 在 SKILL.md 和 reference 中写得很清楚。问题**不是约束不到位**，而是：
|
||||
|
||||
1. **高估了小改动的判断** — micro 分档让我误以为"可以跳过检查"，实际 micro 只合并产物不跳过阶段
|
||||
2. **按代码习惯而非按流程执行** — 作为习惯于输出代码的 agent，对流程节点的重视度天然低于代码
|
||||
3. **缺少执行中的自检机制** — rules 只在加载时读一次，被上下文冲走后就没有对照检查
|
||||
|
||||
### 核心教训
|
||||
|
||||
- **Devflow 是思考过程，不是文档任务** — 写文档的过程就是做架构审计和一致性检查的过程
|
||||
- **Micro 不等于跳过** — 产物可以合并，但检查点不能省略
|
||||
- **声明即约束** — 把"本阶段调用 X / 降级为 Y"说出来，是对自己的提醒也是对用户的透明
|
||||
- **Devflow 和 OpenSpec 同步更新** — 更新 OpenSpec 时同步更新 devflow，不要把 devflow 留到 Phase 4 一次性补。两者是同一件事的两面，不是先后关系
|
||||
@@ -0,0 +1,293 @@
|
||||
# SM Flow 执行复盘 - 山东商客意向单同步接口
|
||||
|
||||
> 项目: yingke-platform
|
||||
> 需求: 385 山东公司商机信息同步接口
|
||||
> 执行日期: 2026-06-23
|
||||
> 复盘人: Claude Code
|
||||
|
||||
---
|
||||
|
||||
## 执行概况
|
||||
|
||||
- **需求规模**: 中等（3个接口 + Kafka消费 + 数据库变更）
|
||||
- **总耗时**: 约 2 小时（含多次返工）
|
||||
- **返工次数**: 4-5 次重大返工
|
||||
- **最终状态**: 核心代码完成，但验签/解密/查询接口未实现
|
||||
|
||||
---
|
||||
|
||||
## 发现的问题
|
||||
|
||||
### 1. 前置调研不足，导致多次返工
|
||||
|
||||
#### 问题表现
|
||||
|
||||
| 返工点 | 初次实现（错误） | 返工后（正确） | 浪费时间 |
|
||||
|--------|------------------|----------------|----------|
|
||||
| RequestMsg 结构 | 自创 `SyncIntentOrderReq/Resp` | 使用项目标准 `RequestMsg<T>` | 15 分钟 |
|
||||
| Kafka 发送方式 | `SendMessageTunnel` + `TaskTypeEnum` | `ykMqTemplate` + `@YkMsg` | 20 分钟 |
|
||||
| Consumer 模块位置 | order-service 模块 | web 模块（参考案例位置） | 10 分钟 |
|
||||
| 透传字段结构 | Map → DTO → 最终平铺 | 应一次到位平铺到 Msg | 15 分钟 |
|
||||
|
||||
**根本原因**: apply 阶段直接开始写代码，没有充分调研现有代码模式。
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**在 apply 阶段前增加强制调研步骤**（pre-apply research checkpoint）：
|
||||
|
||||
1. **阅读所有参考实现**（设计文档中明确提到的）
|
||||
- 完整阅读参考代码，而不是凭想象
|
||||
- 提取关键模式：请求结构、Kafka 使用、模块划分
|
||||
|
||||
2. **Grep 关键技术栈**
|
||||
```bash
|
||||
grep -r "@YkMsg" --include="*.java"
|
||||
grep -r "ykMqTemplate" --include="*.java"
|
||||
grep -r "RequestMsg<" --include="*.java"
|
||||
```
|
||||
|
||||
3. **形成"技术栈清单"文档**（临时产物）
|
||||
```markdown
|
||||
- 项目使用 RequestMsg<T> 作为统一请求包装
|
||||
- Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
|
||||
- Consumer 统一放在 web 模块的 manager/stream/consumer
|
||||
```
|
||||
|
||||
4. **调研时间要求**: 不少于 15 分钟，复杂需求可延长至 30 分钟
|
||||
|
||||
---
|
||||
|
||||
### 2. 设计文档与实现偏离，缺少一致性检查
|
||||
|
||||
#### 问题表现
|
||||
|
||||
| 设计文档要求 | 实际实现 | 偏离程度 |
|
||||
|--------------|----------|----------|
|
||||
| Controller 层 SM3 验签 | 只有 TODO 注释 | ❌ 核心功能缺失 |
|
||||
| Service 层 AES256-GCM 解密 | 只有 TODO 注释 | ❌ 核心功能缺失 |
|
||||
| queryIntentOrder 调用一体化客服 | 空实现 | ❌ 核心功能缺失 |
|
||||
| syncIntentOrder 同步调用 | 改为 Kafka 异步 | ⚠️ 架构差异（可能合理） |
|
||||
|
||||
**根本原因**: apply 阶段没有"设计-实现对齐检查点"。
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**在 apply 阶段中增加对齐检查点**（alignment checkpoint）：
|
||||
|
||||
1. **每完成 1 个接口/模块，立即对比设计文档**
|
||||
- 逐条核对设计文档的任务清单
|
||||
- 标记"已完成/部分完成/TODO"
|
||||
|
||||
2. **核心功能不允许"TODO 占位"直接通过**
|
||||
- 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
|
||||
- 区分"框架完整但待联调"（✅） vs "空实现"（❌）
|
||||
|
||||
3. **架构差异必须显式记录并询问用户**
|
||||
- 设计说同步，实现改异步 → 必须记录原因并确认
|
||||
- 创建 `decisions.md` 记录所有偏离设计的架构决策
|
||||
|
||||
---
|
||||
|
||||
### 3. 分步验证不足，一次写太多代码
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
|
||||
- 没有"写一点 → 编译 → 确认方向"的小步迭代
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**强制分步验证**（incremental validation）：
|
||||
|
||||
1. **Controller 层先行**
|
||||
- 只写 Controller + 最小 Service 骨架
|
||||
- 确认请求/响应结构正确
|
||||
- 编译通过后再继续
|
||||
|
||||
2. **Kafka 发送独立验证**
|
||||
- 写完发送逻辑，先打印 JSON 确认消息格式
|
||||
- 再写 Consumer
|
||||
|
||||
3. **Consumer 最后实现**
|
||||
- 基于已确认的消息格式实现
|
||||
|
||||
---
|
||||
|
||||
### 4. 参考案例利用不充分
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
|
||||
- 但实际执行时，直到用户提醒才去看参考实现
|
||||
- 之前都在凭想象写，导致返工
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**强制参考案例优先**（reference-first approach）：
|
||||
|
||||
1. **grill 阶段就应该找出所有参考案例**
|
||||
- 不要只记录"参考 XXX"，而是实际阅读并提取模式
|
||||
|
||||
2. **apply 前必须完整阅读参考实现**
|
||||
- 不是"扫一眼"，而是逐行理解关键逻辑
|
||||
- 提取可复用的代码片段
|
||||
|
||||
3. **参考案例模式提取清单**（临时文档）
|
||||
```markdown
|
||||
## AddIntentOrderOutSystemDealTunnel 关键模式
|
||||
|
||||
1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
|
||||
2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
|
||||
3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
|
||||
4. 成功判断: isSyncSuccess() 三层校验
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. grill 阶段澄清不够深入
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
|
||||
- 导致后续实现时才发现技术栈不熟悉
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**grill 阶段增加技术实现澄清**：
|
||||
|
||||
除了业务澄清，还应该包括：
|
||||
|
||||
1. **技术栈确认问题**
|
||||
- "项目现有的 Kafka 消息怎么定义和发送？"
|
||||
- "RequestMsg/ResponseMsg 的标准用法是什么？"
|
||||
- "类似接口的 Controller/Service 是怎么写的？"
|
||||
|
||||
2. **参考实现确认**
|
||||
- "设计文档提到的参考实现是哪些文件？"
|
||||
- "这些参考实现的核心模式是什么？"
|
||||
|
||||
3. **技术风险识别**
|
||||
- "有哪些技术点我不熟悉，需要先调研？"
|
||||
|
||||
---
|
||||
|
||||
## 改造建议汇总
|
||||
|
||||
### 方案 A: 在现有 9 阶段中增强（保守）
|
||||
|
||||
```
|
||||
clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
|
||||
↑ ↑ ↑
|
||||
增加技术澄清 增加调研 增加检查点
|
||||
```
|
||||
|
||||
**修改点**：
|
||||
|
||||
1. **grill 阶段**：增加技术实现澄清问题模板
|
||||
2. **apply 阶段前**：增加 pre-apply research checkpoint（15-30分钟）
|
||||
3. **apply 阶段中**：增加 alignment checkpoint（每完成1个模块对比设计文档）
|
||||
|
||||
### 方案 B: 新增独立调研阶段（激进）
|
||||
|
||||
```
|
||||
clarify → context → propose → grill → research → specify → audit → commit → apply → archive
|
||||
↑
|
||||
新增独立调研阶段
|
||||
```
|
||||
|
||||
**新阶段 research**：
|
||||
|
||||
- **输入**: proposal + 参考实现列表
|
||||
- **输出**: 技术栈清单 + 参考模式提取 + 风险评估
|
||||
- **时间**: 15-30 分钟
|
||||
- **产物**: `research.md`（临时文档，archive 时删除）
|
||||
|
||||
**research.md 结构**：
|
||||
|
||||
```markdown
|
||||
# 技术调研 - [需求名称]
|
||||
|
||||
## 参考实现分析
|
||||
|
||||
### AddIntentOrderOutSystemDealTunnel
|
||||
- 文件位置: web/manager/stream/consumer/...
|
||||
- 关键模式:
|
||||
- Consumer 定义: @YkMqConsumer + MsgData 子类
|
||||
- 调用链: ...
|
||||
|
||||
## 技术栈清单
|
||||
|
||||
- 请求结构: RequestMsg<T> / ResponseMsg<T>
|
||||
- Kafka: @YkMsg + ykMqTemplate.sendAsync()
|
||||
- 加密: AESUtil.encryptAES() (AES-128 ECB)
|
||||
|
||||
## 风险点
|
||||
|
||||
- AES256-GCM 工具类不存在，需要新建
|
||||
- 验签逻辑没有现成拦截器，需要在 Service 层实现
|
||||
```
|
||||
|
||||
### 推荐方案
|
||||
|
||||
**方案 A**（渐进增强）：
|
||||
|
||||
1. 对现有流程影响小
|
||||
2. 实施成本低
|
||||
3. 可以立即生效
|
||||
|
||||
**具体实施**：
|
||||
|
||||
- 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范
|
||||
- 增加 checkpoint 描述
|
||||
- 更新 question pool 增加技术澄清问题
|
||||
|
||||
---
|
||||
|
||||
## 其他建议
|
||||
|
||||
### 1. 增加"快速失败"机制
|
||||
|
||||
当发现以下情况，立即暂停并询问用户：
|
||||
|
||||
- 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
|
||||
- 实现方式与设计文档明显偏离
|
||||
- 连续返工超过 2 次（说明方向可能错了）
|
||||
|
||||
### 2. 产物可观测性增强
|
||||
|
||||
在 apply 阶段，定期输出：
|
||||
|
||||
```markdown
|
||||
## 实现进度（每 30 分钟更新）
|
||||
|
||||
✅ Controller 层（已完成）
|
||||
- ShandongSyncController.syncIntentOrder
|
||||
- 请求结构使用 RequestMsg<ShandongIntentOrderData>
|
||||
|
||||
🚧 Service 层（进行中）
|
||||
- ShandongSyncService 接口完成
|
||||
- 实现类 70% 完成
|
||||
- ⚠️ 验签解密未实现（TODO）
|
||||
|
||||
⏳ Kafka 层（待开始）
|
||||
```
|
||||
|
||||
### 3. 设计文档质量要求
|
||||
|
||||
设计文档应该包含：
|
||||
|
||||
- ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
|
||||
- ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
|
||||
- ✅ 数据流图（清晰展示同步/异步边界）
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
**核心问题**: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。
|
||||
|
||||
**解决方向**: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。
|
||||
|
||||
**预期效果**: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。
|
||||
|
||||
**立即可做**: 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范即可生效。
|
||||
@@ -0,0 +1,504 @@
|
||||
# SM Flow Skill - 使用情况分析与优化建议
|
||||
|
||||
## 执行概况
|
||||
|
||||
**项目**: lookup-knowledge-integration
|
||||
**执行日期**: 2026-06-24
|
||||
**执行模式**: 手动跳阶段（用户直接要求"修复问题"）
|
||||
|
||||
### 实际执行的阶段
|
||||
|
||||
1. ❌ **Clarify** - 跳过（用户直接给了 handoff 文档）
|
||||
2. ❌ **Context** - 跳过（未读取 devflow 历史）
|
||||
3. ❌ **Propose** - 跳过（OpenSpec 已存在）
|
||||
4. ❌ **Grill** - 跳过（未进行澄清）
|
||||
5. ❌ **Specify** - 跳过（OpenSpec 已完整）
|
||||
6. ❌ **Audit** - 跳过（未进行架构审计）
|
||||
7. ❌ **Commit** - **跳过（关键遗漏）**
|
||||
8. ✅ **Apply** - 执行（实现代码）
|
||||
9. ⚠️ **Archive** - 部分执行（先创建 handoff，后补 devflow）
|
||||
|
||||
---
|
||||
|
||||
## 做得好的地方 ✅
|
||||
|
||||
### 1. Archive 规则详细且可执行
|
||||
|
||||
**优点**：
|
||||
- `archive-rules.md` 提供了清晰的提取映射表
|
||||
- 目录结构规范（devflow/projects/YYYY-MM-DD-{slug}/）
|
||||
- 产物分档（micro/standard/complex）明确
|
||||
- 索引维护规则具体
|
||||
|
||||
**证据**：被提醒后，我能快速创建符合规范的 devflow 档案
|
||||
|
||||
### 2. 硬约束明确
|
||||
|
||||
**优点**：
|
||||
- 6 条核心规则写在 SKILL.md 顶部，醒目
|
||||
- 规则表述清晰（不得跳过 context/grill/commit）
|
||||
|
||||
**问题**：虽然规则清晰，但缺少执行机制（见后续建议）
|
||||
|
||||
### 3. Phase 契约结构清晰
|
||||
|
||||
**优点**：
|
||||
- `phase-contracts.md` 定义了进入/退出条件
|
||||
- 每个阶段的职责明确
|
||||
|
||||
---
|
||||
|
||||
## 关键问题 ❌
|
||||
|
||||
### 问题 1: Commit 检查缺少可执行标准
|
||||
|
||||
**现象**：
|
||||
- 我不知道如何判断"通过 commit 检查"
|
||||
- phase-contracts.md 说了要做 commit，但没说具体怎么判断
|
||||
|
||||
**影响**：
|
||||
- 我直接跳过 commit，进入 apply
|
||||
- 违反了硬约束规则 4："不得跳过 commit"
|
||||
|
||||
**根本原因**：
|
||||
```
|
||||
phase-contracts.md:
|
||||
"Commit 阶段：检查 Draft OpenSpec 是否达到可执行状态"
|
||||
|
||||
但没有说：
|
||||
- 什么叫"可执行状态"？
|
||||
- 需要检查哪些文件？
|
||||
- 每个文件的必需内容是什么？
|
||||
- 如何标记"已通过"？
|
||||
```
|
||||
|
||||
### 问题 2: Apply 阶段缺少前置门控
|
||||
|
||||
**现象**：
|
||||
- 用户说"修复问题"，我直接开始实现
|
||||
- 没有检查是否存在 Committed OpenSpec
|
||||
|
||||
**影响**：
|
||||
- 可能基于不完整的 OpenSpec 执行
|
||||
- 违反了 "apply 必须基于 Committed OpenSpec" 的约束
|
||||
|
||||
**根本原因**：
|
||||
- Apply 阶段的"进入条件"是软性描述
|
||||
- 没有强制的文件检查机制（如 `.committed` 文件）
|
||||
|
||||
### 问题 3: Archive 阶段缺少 Checklist
|
||||
|
||||
**现象**：
|
||||
- 我先创建了 handoff 文档
|
||||
- 忘记了 devflow 才是核心记忆层
|
||||
- 被提醒后才补创建 devflow 档案
|
||||
|
||||
**影响**：
|
||||
- 归档流程不完整
|
||||
- 需要用户纠正
|
||||
|
||||
**根本原因**：
|
||||
- archive-rules.md 有详细说明，但没有强制执行顺序
|
||||
- 我容易按"直觉"操作，而不是按"规范"操作
|
||||
|
||||
### 问题 4: 缺少流程状态追踪
|
||||
|
||||
**现象**：
|
||||
- 我不知道当前在哪个阶段
|
||||
- 每次执行都像"全新开始"
|
||||
|
||||
**影响**：
|
||||
- 容易跳过中间阶段
|
||||
- 无法断点续做
|
||||
|
||||
---
|
||||
|
||||
## 优化建议（按优先级）
|
||||
|
||||
### High Priority（立即修复）
|
||||
|
||||
#### 建议 1: Commit 检查增加可执行 Checkpoint
|
||||
|
||||
**位置**：`references/phase-contracts.md` - Commit 阶段
|
||||
|
||||
**增加内容**：
|
||||
```markdown
|
||||
## Commit 阶段退出条件
|
||||
|
||||
必须完成以下 checkpoint：
|
||||
|
||||
### 文件完整性检查
|
||||
- [ ] `proposal.md` 存在且包含：
|
||||
- 问题描述（至少 50 字）
|
||||
- 建议方案（至少 100 字）
|
||||
- 范围/非范围
|
||||
|
||||
- [ ] `design.md` 存在且包含：
|
||||
- 架构设计（文字或图）
|
||||
- 数据结构定义（至少 1 个）
|
||||
- 关键决策记录（至少 2 条）
|
||||
|
||||
- [ ] `specs/functional-specs.md` 存在且包含：
|
||||
- 至少 3 个 requirement
|
||||
- 每个 requirement 有 scenario
|
||||
|
||||
- [ ] `tasks.md` 存在且包含：
|
||||
- 至少 5 个可执行子任务
|
||||
- 每个任务有验收标准
|
||||
|
||||
### 一致性检查
|
||||
- [ ] proposal 中的核心概念在 design 中有对应设计
|
||||
- [ ] design 中的关键决策在 tasks 中有对应实现任务
|
||||
- [ ] tasks 的验收标准可验证（不是"正确实现"这种模糊描述）
|
||||
|
||||
### 标记
|
||||
通过后创建 `.committed` 文件：
|
||||
```bash
|
||||
echo "committed at $(date)" > openspec/changes/{slug}/.committed
|
||||
```
|
||||
|
||||
**执行指令**：
|
||||
在 apply 阶段入口，必须先执行此检查。
|
||||
```
|
||||
|
||||
#### 建议 2: Apply 阶段增加前置门控
|
||||
|
||||
**位置**：`references/phase-contracts.md` - Apply 阶段
|
||||
|
||||
**修改"进入条件"**：
|
||||
```markdown
|
||||
## Apply 阶段进入条件
|
||||
|
||||
**硬约束**：
|
||||
1. 必须存在 `.committed` 文件
|
||||
2. 如果不存在，执行以下流程：
|
||||
a. 汇报：Draft OpenSpec 未通过 commit 检查
|
||||
b. 列出缺失的 checkpoint
|
||||
c. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）
|
||||
|
||||
**检查代码**：
|
||||
```bash
|
||||
if [ ! -f "openspec/changes/{slug}/.committed" ]; then
|
||||
echo "错误：Draft OpenSpec 未通过 commit 检查"
|
||||
echo "请先完成 commit 阶段，或显式确认跳过"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
```
|
||||
|
||||
#### 建议 3: Archive 阶段增加强制 Checklist
|
||||
|
||||
**位置**：`references/archive-rules.md` 顶部
|
||||
|
||||
**增加内容**：
|
||||
```markdown
|
||||
## Archive 阶段强制执行顺序
|
||||
|
||||
**按以下顺序执行，不得跳过或重排**：
|
||||
|
||||
### Step 1: 创建 devflow 档案（必需）
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
|
||||
（从 proposal.md 提取：背景、目标、范围、非目标）
|
||||
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
|
||||
（从 decisions.md 整理：关键决策、权衡、风险）
|
||||
|
||||
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
|
||||
（记录：静态验证、脚本验证、人工验证、未验证）
|
||||
|
||||
### Step 2: 更新索引（必需）
|
||||
- [ ] 在 `devflow/index.md` 末尾追加一行：
|
||||
`| YYYY-MM-DD | slug | 领域 | 关键词 | OpenSpec路径 | archived |`
|
||||
|
||||
### Step 3: 标记 OpenSpec（必需）
|
||||
- [ ] 创建 `openspec/changes/{slug}/.completed` 文件
|
||||
|
||||
### Step 4: 创建 Handoff（可选）
|
||||
- [ ] 创建 `handoff/YYYY-MM-DD-{slug}.md`
|
||||
（运维交接文档，给未来开发者）
|
||||
|
||||
### Step 5: 向用户汇报
|
||||
- [ ] 列出创建的 devflow 档案
|
||||
- [ ] 汇报验证情况（按类型分类）
|
||||
- [ ] 列出剩余风险
|
||||
- [ ] 询问：**是否现在归档 OpenSpec？**
|
||||
|
||||
**自检**：在执行 Step 5 前，检查 Step 1-4 是否都完成。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Medium Priority（下个版本）
|
||||
|
||||
#### 建议 4: 增加流程状态文件
|
||||
|
||||
**目标**：让我知道当前在哪个阶段
|
||||
|
||||
**实现**：在 OpenSpec 目录维护 `.sm-flow-state` 文件
|
||||
|
||||
```json
|
||||
{
|
||||
"change": "lookup-knowledge-integration",
|
||||
"currentPhase": "apply",
|
||||
"completed": ["clarify", "context", "propose", "grill", "specify", "audit", "commit"],
|
||||
"nextPhase": "archive",
|
||||
"committed": true,
|
||||
"timestamps": {
|
||||
"commit": "2026-06-24T10:00:00Z",
|
||||
"apply_start": "2026-06-24T10:05:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**使用方式**：
|
||||
- 每个阶段开始时：读取此文件，确认前置阶段已完成
|
||||
- 每个阶段结束时：更新此文件，标记当前阶段完成
|
||||
- 用户下次调用时：直接从 `nextPhase` 继续
|
||||
|
||||
**集成到 SKILL.md**：
|
||||
```markdown
|
||||
## 执行前检查
|
||||
|
||||
1. 读取 `.sm-flow-state` 文件
|
||||
2. 确认当前阶段的前置阶段已完成
|
||||
3. 如有缺失，汇报并询问是否补做
|
||||
```
|
||||
|
||||
#### 建议 5: Context 阶段增加必读清单
|
||||
|
||||
**位置**：`references/phase-contracts.md` - Context 阶段
|
||||
|
||||
**增加内容**：
|
||||
```markdown
|
||||
## Context 阶段必读文件
|
||||
|
||||
按顺序读取（即使文件不存在也要尝试）：
|
||||
|
||||
1. **devflow/index.md** - 项目索引
|
||||
- 查找相关领域的历史项目
|
||||
- 识别可能相关的关键词
|
||||
|
||||
2. **devflow/glossary/CONTEXT.md** - 术语表
|
||||
- 提取项目术语和业务规则
|
||||
|
||||
3. **相关项目的 decisions.md** - 历史决策
|
||||
- 从 index.md 中识别的相关项目
|
||||
- 读取其决策，避免重复或冲突
|
||||
|
||||
4. **devflow/compound/*.md** - 可复用知识
|
||||
- 查找可复用的设计模式、经验
|
||||
|
||||
**如果文件不存在**：
|
||||
- 记录"无历史上下文"
|
||||
- 在 proposal.md 中标注"首次相关实现"
|
||||
- 继续执行
|
||||
```
|
||||
|
||||
#### 建议 6: 增加"违规自检"机制
|
||||
|
||||
**目标**：每个阶段结束前，自动检查是否违反硬约束
|
||||
|
||||
**实现**：在每个阶段的退出条件后增加"自检清单"
|
||||
|
||||
```markdown
|
||||
## [阶段名] 退出前自检
|
||||
|
||||
检查以下硬约束是否违反：
|
||||
|
||||
- [ ] 是否跳过了 context？
|
||||
检查：是否读取了 devflow/index.md？
|
||||
|
||||
- [ ] 是否跳过了 grill？
|
||||
检查：decisions.md 中是否记录了至少 3 个澄清问题？
|
||||
|
||||
- [ ] 是否跳过了 commit？
|
||||
检查：是否存在 .committed 文件？
|
||||
|
||||
- [ ] apply 是否基于 Committed OpenSpec？
|
||||
检查：apply 开始前是否读取了 OpenSpec 文件？
|
||||
|
||||
- [ ] 遇到冲突是否先分类？
|
||||
检查：冲突记录是否标记了类型（规格遗漏/实现偏差）？
|
||||
|
||||
- [ ] 是否调用了所有必需的子 skill？
|
||||
检查：阶段定义中要求的 skill 是否都调用了？
|
||||
|
||||
如有违规项，停止执行并汇报。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Low Priority（可选增强）
|
||||
|
||||
#### 建议 7: Grill 阶段增加 Question Pool 模板
|
||||
|
||||
**目标**：帮助我提出高质量的澄清问题
|
||||
|
||||
**位置**：`references/phase-contracts.md` - Grill 阶段
|
||||
|
||||
**增加内容**：
|
||||
```markdown
|
||||
## Grill Question Pool 模板
|
||||
|
||||
必须覆盖至少 3 个维度：
|
||||
|
||||
### 维度 1: 范围边界
|
||||
模板问题：
|
||||
- "Out of scope 里的 X 功能，为什么不在这次做？有什么依赖或风险？"
|
||||
- "如果用户要求 Y，这个方案能扩展支持吗？需要改动多少？"
|
||||
- "边界场景 Z 应该怎么处理？报错还是降级？"
|
||||
|
||||
### 维度 2: 技术风险
|
||||
模板问题：
|
||||
- "如果依赖的 A 服务挂了，这个方案有降级策略吗？"
|
||||
- "为什么选择技术方案 B 而不是 C？主要考虑什么？"
|
||||
- "数据量增长到 N 倍，性能瓶颈在哪里？"
|
||||
|
||||
### 维度 3: 用户验证
|
||||
模板问题：
|
||||
- "这个方案解决的核心痛点是什么？有真实场景吗？"
|
||||
- "有没有现成的替代方案？为什么不用？"
|
||||
- "如果上线后发现不符合预期，回滚成本多大？"
|
||||
|
||||
### 维度 4: 实现可行性
|
||||
模板问题：
|
||||
- "最复杂的部分是什么？有没有技术预研？"
|
||||
- "需要改动哪些核心模块？影响面多大？"
|
||||
- "有没有类似的历史实现可以参考？"
|
||||
```
|
||||
|
||||
#### 建议 8: 增加"快速模式"明确定义
|
||||
|
||||
**当前问题**：`operating-rules.md` 提到快速模式，但没说具体怎么做
|
||||
|
||||
**建议**：明确快速模式的简化规则
|
||||
|
||||
```markdown
|
||||
## 快速模式
|
||||
|
||||
### 触发条件
|
||||
满足以下所有条件时，可使用快速模式：
|
||||
- 变更小于 5 个文件
|
||||
- 无架构变更
|
||||
- 无数据库迁移
|
||||
- 用户明确要求"快速"
|
||||
|
||||
### 简化规则
|
||||
1. Grill 阶段：至少 1 个问题（而非 3 个）
|
||||
2. Specify 阶段：tasks.md 可简化为 3 个子任务
|
||||
3. Audit 阶段：可跳过（标注"快速模式跳过审计"）
|
||||
4. Archive 阶段：使用 micro 分档（brief/decisions/acceptance）
|
||||
|
||||
### 不得简化
|
||||
- Context 阶段：仍需读取 devflow
|
||||
- Commit 阶段：仍需检查 OpenSpec 完整性
|
||||
- Apply 阶段：仍需基于 Committed OpenSpec
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 执行机制优化建议
|
||||
|
||||
### 当前问题：约束是"软性"的
|
||||
|
||||
**现象**：
|
||||
- 规则写得很清楚："不得跳过 commit"
|
||||
- 但我仍然能跳过，没有强制机制
|
||||
|
||||
**根本原因**：
|
||||
- 规则是"描述性"的（说应该做什么）
|
||||
- 缺少"执行性"的机制（强制检查、文件依赖）
|
||||
|
||||
### 解决方案：引入"门控文件"
|
||||
|
||||
**设计**：
|
||||
```
|
||||
每个阶段完成后，创建一个标记文件：
|
||||
- .context-done
|
||||
- .grill-done
|
||||
- .commit-done (即 .committed)
|
||||
- .apply-done
|
||||
- .archive-done
|
||||
|
||||
下一个阶段开始前，检查前置文件是否存在。
|
||||
```
|
||||
|
||||
**示例**：Apply 阶段入口检查
|
||||
```bash
|
||||
if [ ! -f ".committed" ]; then
|
||||
echo "错误：Commit 阶段未完成"
|
||||
echo "缺失文件：.committed"
|
||||
echo "请先完成 commit 阶段，或显式跳过（需用户确认）"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**好处**：
|
||||
1. 强制执行顺序（无法跳过）
|
||||
2. 可视化进度（ls 就能看到哪些阶段完成了）
|
||||
3. 支持断点续做（下次执行自动识别位置）
|
||||
|
||||
---
|
||||
|
||||
## 用户体验优化
|
||||
|
||||
### 当前问题：用户不知道"现在在哪"
|
||||
|
||||
**场景**：
|
||||
- 用户说"继续"
|
||||
- 我不知道该从哪个阶段继续
|
||||
|
||||
**建议**：每次开始时，主动汇报状态
|
||||
|
||||
```
|
||||
开始执行 SM Flow...
|
||||
|
||||
当前状态：
|
||||
✅ Context 已完成
|
||||
✅ Propose 已完成
|
||||
⏸️ Grill 未开始 ← 当前阶段
|
||||
|
||||
下一步：执行 Grill 阶段（人类对齐澄清）
|
||||
预计耗时：5-10 分钟
|
||||
```
|
||||
|
||||
### 建议：增加"进度条"
|
||||
|
||||
```
|
||||
SM Flow 进度：
|
||||
[✅] Clarify
|
||||
[✅] Context
|
||||
[✅] Propose
|
||||
[⏸️] Grill ← 当前
|
||||
[ ] Specify
|
||||
[ ] Audit
|
||||
[ ] Commit
|
||||
[ ] Apply
|
||||
[ ] Archive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
### 核心问题
|
||||
1. **Commit 检查缺少可执行标准**（导致容易跳过）
|
||||
2. **Apply 阶段缺少前置门控**（没有强制检查 .committed）
|
||||
3. **Archive 阶段缺少 Checklist**（容易遗漏 devflow）
|
||||
4. **缺少流程状态追踪**（不知道当前在哪）
|
||||
|
||||
### 优先修复（High Priority）
|
||||
- ✅ Commit 检查增加 Checkpoint
|
||||
- ✅ Apply 增加前置门控
|
||||
- ✅ Archive 增加 Checklist
|
||||
|
||||
这三个修复后，绝大多数"跳过阶段"问题都能解决。
|
||||
|
||||
### 框架本身很好
|
||||
- 架构清晰（9 个阶段、4 层架构）
|
||||
- 规则明确（6 条硬约束）
|
||||
- 文档详细（phase-contracts, archive-rules）
|
||||
|
||||
**问题不是"约束不够"，而是"执行机制不够明确"。**
|
||||
|
||||
增加可验证的 checkpoint 和门控文件后，我就很难"偷懒"了。
|
||||
@@ -1,4 +1,73 @@
|
||||
# 增强版工作流总结
|
||||
# SM-Flow 工作流
|
||||
|
||||
## 当前设计理念（v4.3）
|
||||
|
||||
**核心定位**：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 + 归档确认） |
|
||||
|
||||
**触发边界**：
|
||||
|
||||
sm-flow 只在用户显式调用时使用：
|
||||
|
||||
- 用户输入 `/sm-flow`、`/sm-flow explore`、`/sm-flow apply`、`/sm-flow archive`。
|
||||
- 用户用自然语言明确要求“使用 sm-flow”“走 sm-flow 流程”或等价表达。
|
||||
|
||||
不要根据任务类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。
|
||||
|
||||
**内部阶段（9 个，英文动词命名）**：
|
||||
|
||||
```
|
||||
clarify → context → propose → grill → specify → audit → commit → apply → archive
|
||||
入口澄清 上下文 轻量提案 澄清 细化 审计 提交 执行 归档
|
||||
```
|
||||
|
||||
阶段名是 harness 的内部协议词汇，不是用户 API。面向用户默认只暴露 4 个可见 checkpoint：Discover、Commit、Apply、Archive；内部阶段仍按顺序执行。
|
||||
|
||||
**关键设计决策**：
|
||||
|
||||
- **真理源分层**：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**：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 检查），否则不是约束而是建议。
|
||||
|
||||
**使用方式**：
|
||||
|
||||
详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
|
||||
|
||||
- 4 个用户命令的典型场景
|
||||
- 完整规划 → 执行 → 归档的分次调用示例
|
||||
- 自然语言交互方式
|
||||
- 规模分档（micro / standard / complex）
|
||||
- devflow 自动维护机制
|
||||
- OpenSpec 集成与 Draft/Committed 分离
|
||||
- 常见问题解答
|
||||
|
||||
---
|
||||
|
||||
## 演进历史
|
||||
|
||||
以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
|
||||
|
||||
## 旧工作流 vs 新工作流
|
||||
|
||||
@@ -34,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
|
||||
|
||||
@@ -378,6 +447,789 @@ Phase 4 回填 devflow，并确认是否 archive
|
||||
|
||||
`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。
|
||||
|
||||
## v3.1：可执行 gate 与使用摩擦修正
|
||||
|
||||
v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。
|
||||
|
||||
v3.1 不改变 v3 的主轴：
|
||||
|
||||
> `devflow/` 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。
|
||||
|
||||
### Draft / Committed OpenSpec
|
||||
|
||||
Phase 1 产出的 OpenSpec 统一视为 **Draft OpenSpec**。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。
|
||||
|
||||
Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：
|
||||
|
||||
```text
|
||||
Phase 2.9 Commit OpenSpec
|
||||
```
|
||||
|
||||
Phase 2.9 检查：
|
||||
|
||||
- proposal 是否说明范围、非目标和原因。
|
||||
- design 是否记录关键约束、架构风险和接口影响。
|
||||
- specs 是否覆盖可观察行为和验收口径。
|
||||
- tasks 是否是可执行的纵向切片。
|
||||
- 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。
|
||||
|
||||
只有通过 Phase 2.9 的 OpenSpec 才是 **Committed OpenSpec**，Phase 3 只能执行 Committed OpenSpec。
|
||||
|
||||
### Grill 必须人工确认
|
||||
|
||||
Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题必须一次只问一个，等待用户显式回答，并记录到 `decisions.md`。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。
|
||||
|
||||
`evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
|
||||
|
||||
Phase 2 在开始追问前，还应该先建立一个 question pool。最小问题池至少覆盖：
|
||||
|
||||
- 术语
|
||||
- 范围边界
|
||||
- 验收口径
|
||||
|
||||
如果变更涉及多模块、接口、权限、下游消费者、响应结构或生命周期规则，再把这些维度补进问题池。问题池的作用是先把风险面列全，再继续保持 one-at-a-time 的 `user-interview` 消费节奏，而不是一次把所有问题都抛给用户。
|
||||
|
||||
单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
|
||||
|
||||
### Phase Checkpoint
|
||||
|
||||
v3.1 的另一个收紧点是：关键阶段不再靠“看起来做完了”判断完成，而是靠显式 checkpoint。
|
||||
|
||||
关键阶段至少包括：
|
||||
|
||||
- Phase 0
|
||||
- Phase 0.5
|
||||
- Phase 1
|
||||
- Phase 2
|
||||
- Phase 2.5
|
||||
- Phase 2.9
|
||||
|
||||
每个 checkpoint 至少说明：
|
||||
|
||||
- 当前阶段
|
||||
- 调用的 capability 来源
|
||||
- 产出的关键 artifact
|
||||
- 已满足的退出条件
|
||||
- 尚未解决的 blocker
|
||||
|
||||
如果没有这些信息，就不应该把阶段视为已完成，更不应该直接进入下一阶段。
|
||||
|
||||
### Cross-Artifact Alignment
|
||||
|
||||
v3.1 之后，Phase 1.5 和 Phase 2.9 不只是“看看文档差不多”，而是要显式检查一条对齐链：
|
||||
|
||||
```text
|
||||
brief/prd -> proposal -> design -> specs -> tasks
|
||||
```
|
||||
|
||||
检查重点不是格式，而是下游产物有没有把上游已经确定的内容接住，例如：
|
||||
|
||||
- `brief/prd` 里的范围和非目标有没有进入 `proposal`
|
||||
- `proposal` 的关键承诺有没有进入 `design`
|
||||
- `design` 里的实现约束和接口影响有没有进入 `specs` 或 `tasks`
|
||||
- `specs` 里的可观察行为有没有被 `tasks` 切成可执行工作
|
||||
|
||||
如果字段、术语、约束、行为或切片只停留在上游文档里，就应该视为对齐缺口，先修 OpenSpec，再继续流程。
|
||||
|
||||
### 接口影响分级
|
||||
|
||||
v3.1 区分“接口影响记录”和“独立接口文档”：
|
||||
|
||||
- 所有接口变更都必须记录影响范围。
|
||||
- 只有 L3/L4 才强制独立接口文档或等价独立章节。
|
||||
|
||||
分级规则：
|
||||
|
||||
| 级别 | 判断条件 | 产物要求 |
|
||||
| --- | --- | --- |
|
||||
| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
|
||||
| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
|
||||
| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
|
||||
| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |
|
||||
|
||||
接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。
|
||||
|
||||
### Devflow Index
|
||||
|
||||
`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：
|
||||
|
||||
```text
|
||||
devflow/index.md
|
||||
devflow/glossary/CONTEXT.md
|
||||
相关项目 brief / acceptance / ADR
|
||||
devflow/compound/
|
||||
```
|
||||
|
||||
Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
|
||||
|
||||
另外，v3.1 也把一个实践经验写成硬规则：devflow 不是等到 Phase 4 才第一次补写。`brief.md`、`evidence.md`、`decisions.md` 这类过程内档案应该随阶段就近更新，Phase 4 主要负责 consolidation 和归档口径收束。
|
||||
|
||||
### Micro 不是 Skip
|
||||
|
||||
`micro` 的目标是降低文档重量，不是给代理发放“可以跳 gate”的许可证。
|
||||
|
||||
因此即使是 `micro` 变更，也仍然要保留：
|
||||
|
||||
- Phase 0.5 最小上下文收集
|
||||
- Phase 2 最小澄清
|
||||
- Phase 2.9 commit gate
|
||||
- Phase 4 轻量回填
|
||||
|
||||
如果因为“改动很小”就跳过这些 gate，应该视为协议偏差，而不是合法优化。
|
||||
|
||||
### 实现期冲突处理
|
||||
|
||||
Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
|
||||
|
||||
| 分类 | 含义 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| 实现偏差 | OpenSpec 正确，代码没有按规格做 | 修代码，不改 OpenSpec |
|
||||
| 规格遗漏 | OpenSpec 没覆盖真实边界、接口影响、验收或外部行为 | 暂停 apply，修正 OpenSpec，重新 commit |
|
||||
| 设计冲突 | OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突 | 暂停并请用户确认设计方向 |
|
||||
| 用户变更 | 用户改变目标、范围、验收或风险接受度 | 更新 proposal/specs/tasks 后继续 |
|
||||
|
||||
冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 `decisions.md` 或 `acceptance.md`。
|
||||
|
||||
### 子 skill 兼容
|
||||
|
||||
v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `openspec-propose`、`openspec-apply-change`、`to-prd`、`grill-with-docs` 都是能力契约。
|
||||
|
||||
调用优先级：
|
||||
|
||||
1. 平台原生 skill。
|
||||
2. 本地 `SKILL.md`，例如 `.claude/skills/...` 或 `.agents/skills/...`。
|
||||
3. `sm-flow` 的 fallback 协议。
|
||||
|
||||
这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。
|
||||
|
||||
一旦进入 fallback，代理还必须把这次降级本身记录下来。也就是说，fallback 不只是“内部换个做法”，而是一个需要显式声明 capability 缺失、降级原因和风险的协议事件。
|
||||
|
||||
## v3.1 后续收口：协议瘦身与 review 修正
|
||||
|
||||
在执行硬化规则落地后，又做了一轮非常实际的收口：不是再增加新规则，而是把已经确认的规则放到更稳定、可维护的位置，并修掉瘦身过程中暴露的引用问题。
|
||||
|
||||
### 顶层 skill 瘦身
|
||||
|
||||
`SKILL.md` 不再同时承担“入口协议”和“大段运行手册”两种职责，而是收敛为：
|
||||
|
||||
- 工作流定位
|
||||
- 真理源分层
|
||||
- 核心硬规则
|
||||
- reference 加载入口
|
||||
- 阶段总览
|
||||
|
||||
原来放在顶层但更适合按需读取的内容，被下沉到新的：
|
||||
|
||||
```text
|
||||
references/operating-rules.md
|
||||
```
|
||||
|
||||
这里集中放：
|
||||
|
||||
- 接口影响分级
|
||||
- 启动检查
|
||||
- 项目标识规则
|
||||
- devflow 产物分层
|
||||
- 快速模式细则
|
||||
- 完成标准
|
||||
|
||||
这样做的目标不是减少规则，而是减少“启动时一次读太多”和“顶层协议与 reference 抢职责”的问题。
|
||||
|
||||
### Fallback 去重复
|
||||
|
||||
`fallbacks.md` 也做了第二轮整理：
|
||||
|
||||
- 顶部统一定义 fallback 通用记录要求
|
||||
- 各 fallback 小节只保留自己的额外记录义务
|
||||
|
||||
这样可以避免每个 fallback 都重复写一遍“要声明 fallback、要记录 fallback”，同时不丢失协议要求。
|
||||
|
||||
### Review 驱动的自洽性修正
|
||||
|
||||
瘦身后又发现了一类很典型的问题：**规则本身没错，但 cross-reference 可能断掉**。因此又补了一轮 review 驱动修正，重点包括：
|
||||
|
||||
- `phase-contracts.md` 在首次使用接口分级、分档、快速模式时，显式指向 `operating-rules.md`
|
||||
- 修正 fallback 锚点，避免 skill 指向不存在的章节名
|
||||
- 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
|
||||
|
||||
这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、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） |
|
||||
|
||||
## v4.0 验证执行复盘（2026-05-25）
|
||||
|
||||
用 entry-expand-collapse 需求跑了一轮完整 sm-flow 流程，验证 v4.0 协议的可执行性。功能变更已回滚，仅保留验证发现。
|
||||
|
||||
### 暴露的问题
|
||||
|
||||
| # | 问题 | 具体表现 | 分析结论 |
|
||||
|---|------|----------|----------|
|
||||
| 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 应描述用户可观察的结果而非实现方式 |
|
||||
|
||||
### 做对的部分
|
||||
|
||||
- clarify + context 合并执行正确（micro 模式）
|
||||
- grill 的 evidence-driven / user-interview 分类和 one-at-a-time 节奏执行到位
|
||||
- commit gate 的文件存在性检查生效
|
||||
- apply 阶段的冲突分类（代码偏离）处理正确
|
||||
- devflow 延迟写入（只维护 decisions.md）降低了维护成本
|
||||
|
||||
### 后续观察项
|
||||
|
||||
问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。
|
||||
|
||||
## v4.1：Apply 阶段前置调研增强（2026-06-23）
|
||||
|
||||
### 背景
|
||||
|
||||
基于"山东商客意向单同步接口"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`），发现 apply 阶段存在严重的返工问题：
|
||||
|
||||
- **返工次数**：4-5 次重大返工
|
||||
- **核心问题**：apply 阶段"想当然"开始写代码，缺少充分调研和分步验证
|
||||
- **主要表现**：
|
||||
- 参考实现利用不充分（设计文档提到参考实现，但直到用户提醒才去看）
|
||||
- 技术栈不熟悉（RequestMsg 结构、Kafka 发送方式、Consumer 位置全部返工）
|
||||
- 设计-实现偏离（验签/解密/查询接口只有 TODO 注释）
|
||||
|
||||
### 核心改进：Pre-apply Checkpoint
|
||||
|
||||
在 apply 阶段开始前增加强制性调研检查点（方案 B 简化版）：
|
||||
|
||||
#### 修改 1：grill 阶段增加技术实现维度
|
||||
|
||||
在 question pool 中新增"技术实现维度"：
|
||||
|
||||
```markdown
|
||||
**技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
|
||||
- 参考实现的具体文件路径是什么？
|
||||
- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
|
||||
- 有哪些技术点需要先调研或新建？
|
||||
```
|
||||
|
||||
**目的**：在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
|
||||
|
||||
#### 修改 2：apply 阶段增加 Pre-apply Checkpoint
|
||||
|
||||
在 apply 阶段开始前增加强制调研步骤：
|
||||
|
||||
**触发条件**（3 条）：
|
||||
- design 或 tasks 中提到"参考 XXX 实现"
|
||||
- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
|
||||
- 技术栈不熟悉或第一次在该项目实现类似功能
|
||||
|
||||
**执行步骤**（3 步）：
|
||||
1. **完整阅读所有参考实现**
|
||||
- 从 OpenSpec design 或 tasks 中定位参考实现文件
|
||||
- 如果路径不明确，通过 Grep 搜索关键类名或模式
|
||||
- 逐行理解关键逻辑，提取可复用代码片段和模式
|
||||
|
||||
2. **Grep 关键技术栈**
|
||||
- 请求/响应结构模式
|
||||
- 消息队列模式
|
||||
- 统一工具类
|
||||
- 异常处理和日志记录标准
|
||||
|
||||
3. **形成技术栈清单并写入 decisions.md**
|
||||
- 项目使用的请求/响应结构标准
|
||||
- MQ 消息定义和发送标准
|
||||
- Consumer 标准位置和写法
|
||||
- 加密/验签/工具类的标准用法
|
||||
- 识别需要新建的工具类或基础设施
|
||||
|
||||
**输出要求**（3 条）：
|
||||
- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
|
||||
- ✅ 已列出所有参考实现的文件路径
|
||||
- ✅ 已识别需要新建的工具类/基础设施
|
||||
|
||||
**快速模式支持**：micro 分档可按风险缩小调研范围，但仍需形成清单。
|
||||
|
||||
#### 修改 3：apply 实现过程增强
|
||||
|
||||
**分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
|
||||
|
||||
**首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
|
||||
|
||||
**快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
|
||||
|
||||
#### 修改 4：apply 退出条件增强
|
||||
|
||||
新增退出条件：
|
||||
- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
|
||||
- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
|
||||
|
||||
### 预期效果
|
||||
|
||||
| 指标 | 当前 | 目标 | 改善 |
|
||||
|------|------|------|------|
|
||||
| 返工次数 | 4-5 次 | 0-1 次 | -80% |
|
||||
| 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
|
||||
|
||||
**ROI 分析**：
|
||||
|
||||
前置调研的收益来自减少返工和避免核心功能遗漏。v4.3 之后不再用固定投入指标定义投入或收益，改按风险和实现复杂度决定调研深度。
|
||||
|
||||
### 复杂度评估
|
||||
|
||||
**本次修改复杂度**：中等
|
||||
- 文本增量：+55 行（从 281 行 → 336 行，+20%）
|
||||
- 概念层级：+1 层（apply 内部增加 Pre-apply Checkpoint 子阶段）
|
||||
- 强制规则：+5 条（pre-apply 触发条件、执行步骤、输出要求）
|
||||
|
||||
**整体复杂度**：高（但合理）
|
||||
- 总行数：606 行 → ~700 行（+15%）
|
||||
- 阶段数：9 个（不变）
|
||||
- 门控数：4 个 → 6 个（+propose checkpoint, +pre-apply checkpoint）
|
||||
|
||||
**简化设计**：
|
||||
- 采用方案 B（简化版），相比完整方案减少 45% 文本量和 44% 规则数
|
||||
- 保留核心价值（前置调研、技术栈清单、核心功能质量保证）
|
||||
- 去掉过度约束（严格执行顺序、频繁检查点、详细操作模板）
|
||||
|
||||
### 适用场景
|
||||
|
||||
✅ **强烈推荐**：
|
||||
- 中等及以上规模需求（3+ 接口或涉及多模块）
|
||||
- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
|
||||
- 第一次在该项目实现类似功能
|
||||
- 设计文档提到"参考 XXX 实现"
|
||||
|
||||
🟡 **可选执行**：
|
||||
- micro 分档的简单需求（可按风险缩小范围）
|
||||
- 纯数据处理或工具脚本（技术栈熟悉）
|
||||
|
||||
❌ **不推荐**：
|
||||
- 紧急热修复（时间紧急）
|
||||
- 一次性脚本（不涉及项目标准）
|
||||
|
||||
### 相关文档
|
||||
|
||||
- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
|
||||
- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md`
|
||||
- 修改文件：`.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
|
||||
## v4.2：可验证 Checkpoint 与执行机制增强（2026-06-24）
|
||||
|
||||
### 背景
|
||||
|
||||
基于"lookup-knowledge-integration"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`），发现一个结构性问题：
|
||||
|
||||
**约束是"软性"的，缺少执行机制**
|
||||
|
||||
- **规则清楚但可绕过**：6 条硬约束写得很清楚"不得跳过 commit"，但 agent 仍然能跳过
|
||||
- **标准模糊无法判断**：commit 阶段说"检查是否可执行"，但不知道具体检查什么
|
||||
- **流程无强制顺序**：archive 建议"先 devflow 后 handoff"，但 agent 可能先创建 handoff
|
||||
|
||||
**核心认知**：规则是"描述性"的（说应该做什么），缺少"执行性"的机制（强制检查、文件依赖）。
|
||||
|
||||
### 核心改进：从软性约束到硬性检查
|
||||
|
||||
v4.2 不增加新阶段或新规则，而是**把现有约束变成可验证的 checkpoint**：
|
||||
|
||||
| 改进点 | Before（v4.1） | After（v4.2） |
|
||||
|--------|---------------|--------------|
|
||||
| Commit 标准 | "检查是否可执行"（模糊） | 文件完整性 + 一致性检查清单（具体） |
|
||||
| Apply 门控 | "已通过 commit"（软性） | 检查 `.committed` 文件存在（硬性） |
|
||||
| Archive 顺序 | "应该先 devflow"（建议） | 5 步强制顺序 + 自检（必须） |
|
||||
|
||||
### 详细修改
|
||||
|
||||
#### 修改 1：Commit 阶段增加可验证 Checkpoint
|
||||
|
||||
**文件完整性检查**（必须全部通过）：
|
||||
- [ ] `proposal.md` 存在，包含问题描述（≥50字）、建议方案（≥100字）、范围/非目标
|
||||
- [ ] `design.md` 存在，包含架构设计、数据结构（≥1个）、关键决策（≥2条）
|
||||
- [ ] `specs/` 目录存在，至少 1 个 functional-spec.md 包含 ≥3 个 requirement
|
||||
- [ ] `tasks.md` 存在，包含 ≥5 个可执行子任务，每个任务有验收标准
|
||||
|
||||
**一致性检查**（必须通过）：
|
||||
- [ ] proposal 核心概念 → design 有对应设计
|
||||
- [ ] design 关键决策 → tasks 有对应实现
|
||||
- [ ] tasks 验收标准可验证（非"正确实现"这类模糊描述）
|
||||
|
||||
**标记文件**：检查通过后，创建 `openspec/changes/{slug}/.committed` 文件
|
||||
|
||||
#### 修改 2：Apply 阶段增加前置门控
|
||||
|
||||
**前置门控检查**（硬约束）：
|
||||
1. 检查 `openspec/changes/{slug}/.committed` 文件是否存在
|
||||
2. 如不存在：
|
||||
- 汇报：Draft OpenSpec 未通过 commit 检查
|
||||
- 列出缺失的 checkpoint 项
|
||||
- 询问用户：是否补做 commit；如用户要求不补做，则中止 apply 或标记为 `emergency-bypass`
|
||||
|
||||
#### 修改 3：Archive 阶段增加强制执行顺序
|
||||
|
||||
**5 步 Checklist**（不得跳过或重排）：
|
||||
1. **创建 devflow 档案**（必需）：brief.md + evidence.md + decisions.md + acceptance.md
|
||||
2. **更新索引**（必需）：在 `devflow/index.md` 追加一行
|
||||
3. **标记 OpenSpec**（必需）：创建 `.archive-ready` 文件
|
||||
4. **向用户汇报**（必需）：列出文件、验证分类、剩余风险，询问是否归档
|
||||
5. **执行 OpenSpec Archive**（可选）：用户确认后调用 `openspec-archive-change`
|
||||
|
||||
**自检**：Step 4 前检查 Step 1-3 是否都完成
|
||||
|
||||
### 新增门控文件
|
||||
|
||||
| 文件 | 创建时机 | 用途 |
|
||||
|------|----------|------|
|
||||
| `.committed` | commit 阶段退出时 | apply 阶段前置门控依据 |
|
||||
| `.archive-ready` | archive Step 3 | 标记归档准备就绪 |
|
||||
|
||||
### 预期效果
|
||||
|
||||
**解决的问题**：
|
||||
- ❌ Commit 标准不明确 → ✅ 有具体检查清单，无法模糊通过
|
||||
- ❌ Apply 可能基于不完整 OpenSpec → ✅ 门控文件强制阻止
|
||||
- ❌ Archive 容易遗漏 devflow → ✅ 强制顺序确保完整
|
||||
|
||||
**量化指标**：
|
||||
- Commit 阶段跳过率：-100%（有 checklist 无法跳过）
|
||||
- Apply 基于不完整 OpenSpec：-100%（门控阻止）
|
||||
- Archive 遗漏 devflow：-100%（强制顺序）
|
||||
|
||||
### 设计原则
|
||||
|
||||
#### 1. 可验证性
|
||||
将模糊标准转为可测量的具体要求：
|
||||
- Before: "检查 OpenSpec 是否可执行"
|
||||
- After: "proposal ≥50字、design ≥1个数据结构、specs ≥3个 requirement"
|
||||
|
||||
#### 2. 门控文件
|
||||
用文件存在性替代软性判断：
|
||||
- Before: 描述"已通过 commit"
|
||||
- After: 检查 `.committed` 文件存在
|
||||
|
||||
#### 3. 强制顺序
|
||||
用 checklist 替代建议性描述：
|
||||
- Before: "应该先创建 devflow"
|
||||
- After: "Step 1 devflow → Step 2 索引 → Step 3 标记 → Step 4 汇报"
|
||||
|
||||
### 复杂度评估
|
||||
|
||||
**本次修改复杂度**：低-中等
|
||||
- 文本增量：+80 行（phase-contracts.md +40 行，archive-rules.md +40 行）
|
||||
- 概念增加：2 个门控文件
|
||||
- 规则增强：3 个阶段的检查清单
|
||||
|
||||
**整体复杂度**：高（但更可靠）
|
||||
- 总行数：~700 行 → ~780 行（+11%）
|
||||
- 门控数：6 个 → 8 个
|
||||
|
||||
**权衡**：
|
||||
- ✅ 收益：彻底解决"跳过阶段"问题
|
||||
- ⚠️ 成本：增加 80 行文本，更多检查项
|
||||
|
||||
### 与 v4.1 的关系
|
||||
|
||||
| 版本 | 核心改进 | 解决问题 |
|
||||
|------|----------|----------|
|
||||
| v4.1 | Pre-apply Research Checkpoint | apply 前置调研不足，导致返工（4-5次 → 0-1次） |
|
||||
| v4.2 | 可验证 Checkpoint + 门控文件 | 约束是软性的，agent 容易跳过阶段 |
|
||||
|
||||
**互补关系**：
|
||||
- v4.1 解决"调研不充分导致返工"（质量问题）
|
||||
- v4.2 解决"缺少执行机制导致跳过阶段"（流程问题）
|
||||
|
||||
### 适用场景
|
||||
|
||||
**✅ 所有场景（无例外）**
|
||||
|
||||
v4.2 的改进是执行机制层面的，不涉及业务逻辑：
|
||||
- 无论 micro/standard/complex，都需要 commit 检查
|
||||
- 无论需求大小，都需要 apply 前置门控
|
||||
- 无论项目规模，都需要 archive 强制顺序
|
||||
|
||||
**快速模式**：可以简化产物（如 tasks 只需 3 个），但**不能跳过门控**。
|
||||
|
||||
### 后续演进方向（v5.0 候选）
|
||||
|
||||
如果 v4.2 执行良好但仍有问题，考虑：
|
||||
|
||||
1. **流程状态文件** `.sm-flow-state`
|
||||
- 记录当前阶段、已完成阶段、时间戳
|
||||
- 支持断点续做
|
||||
|
||||
2. **更多门控文件**
|
||||
- `.context-done`、`.grill-done`、`.apply-done`
|
||||
- 形成完整的阶段间依赖链
|
||||
|
||||
3. **违规自检机制**
|
||||
- 每个阶段退出前，自动检查 6 条硬约束
|
||||
|
||||
4. **进度可视化**
|
||||
- 每次开始时，汇报进度条
|
||||
|
||||
**判断依据**：如果 v4.2 后仍频繁出现跳过阶段，再引入更重的机制。
|
||||
|
||||
### 相关文档
|
||||
|
||||
- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md`
|
||||
- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.2-changelog.md`
|
||||
- 修改文件：
|
||||
- `.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/`
|
||||
|
||||
@@ -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) — 真实痛点收集
|
||||
@@ -0,0 +1,8 @@
|
||||
1. 如果涉及接口，需要额外产出一份影响接口范围文档
|
||||
1. ❯ 只要涉及到接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中
|
||||
2. 涉及接口变更，需要产出一份接口文档
|
||||
3. 顺序问题，目前的顺序是propose之后在，生成了task、design之后，再用grill去澄清需求，这样当澄清完需求后，又得回去更新task、design、proposal等文档，现在的流程，是propose之后，再通过to-prd，生成devflow的产物，然后再grill来更新，哪种设计更合理？
|
||||
4. 如果devflow数量多了，如何快速定位需要的上下文
|
||||
5. 子skill现在是固定了claude，要考虑兼容情况
|
||||
6. 当在开发阶段，我发起质疑或者修改，和原来设计冲突时，不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到，要提出反馈
|
||||
1. 可能需要加多一个步骤，apply实施过程中的沟通？
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
name: sm-flow
|
||||
description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
|
||||
---
|
||||
@@ -17,6 +17,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
|
||||
- 代码是实现结果：只能在执行真理源足够明确后修改。
|
||||
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
|
||||
- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
|
||||
- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
|
||||
|
||||
## 核心规则
|
||||
|
||||
@@ -25,16 +27,39 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
|
||||
- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
|
||||
- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
|
||||
- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
|
||||
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
|
||||
- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
|
||||
- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
|
||||
- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
|
||||
- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
|
||||
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
|
||||
- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
|
||||
- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
|
||||
- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
|
||||
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
|
||||
|
||||
## 接口影响分级
|
||||
|
||||
接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
|
||||
|
||||
| 级别 | 判断条件 | 产物要求 |
|
||||
| --- | --- | --- |
|
||||
| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
|
||||
| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
|
||||
| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
|
||||
| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
|
||||
|
||||
判断策略：
|
||||
|
||||
- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
|
||||
- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
|
||||
- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
|
||||
- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
|
||||
|
||||
## 首次加载
|
||||
|
||||
执行前只读取当前任务需要的 reference 文件：
|
||||
@@ -59,8 +84,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- `devflow/reference/`
|
||||
3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
|
||||
4. 检查 OpenSpec 和子 skill 是否可用：
|
||||
- OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
|
||||
- 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
|
||||
- OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
|
||||
- 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
|
||||
5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
|
||||
|
||||
## 项目标识
|
||||
@@ -101,13 +126,14 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
|
||||
## 阶段总览
|
||||
|
||||
1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
|
||||
2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
|
||||
2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
|
||||
4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
|
||||
5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
|
||||
6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
|
||||
7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
|
||||
8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
|
||||
7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
|
||||
8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
|
||||
9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。
|
||||
|
||||
每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
|
||||
|
||||
@@ -117,6 +143,7 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
|
||||
|
||||
- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
|
||||
- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
|
||||
- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
|
||||
- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
|
||||
- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
|
||||
|
||||
|
||||
@@ -17,6 +17,10 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
- `decisions.md`
|
||||
- `acceptance.md`
|
||||
|
||||
同时维护仓库级索引：
|
||||
|
||||
- `devflow/index.md`
|
||||
|
||||
按需创建以下扩展文件：
|
||||
|
||||
- `prd.md`
|
||||
@@ -49,6 +53,24 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
|
||||
| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
|
||||
| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||||
| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
|
||||
|
||||
## 索引维护规则
|
||||
|
||||
`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
|
||||
|
||||
最小字段：
|
||||
|
||||
| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
|
||||
规则：
|
||||
|
||||
- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
|
||||
- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
|
||||
- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
|
||||
- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
|
||||
- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
|
||||
|
||||
## 验收记录规则
|
||||
|
||||
@@ -99,6 +121,7 @@ OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 de
|
||||
Phase 4 结束时告诉用户：
|
||||
|
||||
- 创建或更新了哪些档案文件。
|
||||
- `devflow/index.md` 是否已更新。
|
||||
- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
|
||||
- 还剩哪些风险或后续事项。
|
||||
- 明确询问：是否现在 archive OpenSpec change？
|
||||
|
||||
@@ -34,12 +34,20 @@
|
||||
|
||||
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
|
||||
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
|
||||
3. 修改前先检查现有代码。
|
||||
4. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
5. 用最窄但有效的命令验证每个切片。
|
||||
6. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
7. 如果失败原因不确定，停止并进入 diagnose。
|
||||
8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
|
||||
4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
|
||||
5. 修改前先检查现有代码。
|
||||
6. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
|
||||
- 实现偏差：OpenSpec 正确，代码偏离；修代码。
|
||||
- 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
|
||||
- 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
|
||||
- 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
|
||||
8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
|
||||
9. 用最窄但有效的命令验证每个切片。
|
||||
10. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
11. 如果失败原因不确定，停止并进入 diagnose。
|
||||
12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
|
||||
## PRD fallback
|
||||
|
||||
|
||||
@@ -28,6 +28,8 @@
|
||||
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
|
||||
|
||||
**动作**：
|
||||
- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
|
||||
- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
|
||||
- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
|
||||
- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
|
||||
- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
|
||||
@@ -36,6 +38,7 @@
|
||||
|
||||
**退出条件**：
|
||||
- 已形成“OpenSpec 输入上下文摘要”。
|
||||
- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
|
||||
- 已列出相关 ADR 和不能违反的历史决策。
|
||||
- 已列出需要写入或修正 OpenSpec 的上下文点。
|
||||
|
||||
@@ -46,7 +49,7 @@
|
||||
|
||||
**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
|
||||
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-propose`。
|
||||
@@ -64,7 +67,7 @@
|
||||
- 关键假设已显式记录在 OpenSpec 或 research 中。
|
||||
|
||||
**输出**：
|
||||
- OpenSpec proposal、design、specs 和 task list。
|
||||
- Draft OpenSpec proposal、design、specs 和 task list。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
|
||||
@@ -85,11 +88,16 @@
|
||||
- OpenSpec 是否遵守相关 ADR。
|
||||
- specs 是否能表达可观察行为。
|
||||
- tasks 是否能驱动实现，而不是泛泛描述。
|
||||
- 检查是否涉及接口影响：
|
||||
- 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
|
||||
- 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
|
||||
- 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
|
||||
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
|
||||
|
||||
**退出条件**：
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
|
||||
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
@@ -110,6 +118,10 @@
|
||||
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
|
||||
- 至少覆盖三个维度：术语、边界、验收。
|
||||
- 一次只问一个 `user-interview` 问题。
|
||||
- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
|
||||
- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
|
||||
- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
|
||||
- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
|
||||
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
|
||||
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
|
||||
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
|
||||
@@ -118,6 +130,8 @@
|
||||
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
|
||||
- 所有 evidence-driven 结论已向用户汇报。
|
||||
- 所有 user-interview 决策已获得用户确认。
|
||||
- 没有未解决或代理代确认的 user-interview 问题。
|
||||
- 没有未判级或未确认的接口影响问题。
|
||||
- 影响实现的结论已回写 OpenSpec。
|
||||
|
||||
**输出**：
|
||||
@@ -148,14 +162,46 @@
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
|
||||
- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 2.9 — Commit OpenSpec
|
||||
|
||||
**进入条件**：
|
||||
- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
|
||||
- 所有 `user-interview` 问题都已获得用户显式确认。
|
||||
- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
|
||||
- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
|
||||
|
||||
**动作**：
|
||||
- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
|
||||
- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
|
||||
- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
|
||||
- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
|
||||
- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
|
||||
- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
|
||||
- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
|
||||
|
||||
**退出条件**：
|
||||
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
|
||||
- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
|
||||
- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
|
||||
|
||||
**输出**：
|
||||
- Committed OpenSpec 状态说明。
|
||||
- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
|
||||
- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
|
||||
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
|
||||
- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
|
||||
|
||||
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
|
||||
|
||||
@@ -163,6 +209,12 @@
|
||||
- 优先调用 `openspec-apply-change`。
|
||||
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
|
||||
- 按 OpenSpec tasks 的纵向切片实现。
|
||||
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
|
||||
- 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
|
||||
- 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
|
||||
- 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
|
||||
- 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
|
||||
- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
|
||||
- 当用户要求、行为复杂或回归风险高时使用 TDD。
|
||||
- 当测试失败、行为意外或原因不确定时使用 diagnose。
|
||||
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
|
||||
@@ -170,6 +222,7 @@
|
||||
|
||||
**退出条件**：
|
||||
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
|
||||
- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
|
||||
- 已运行验证，或记录了未验证原因。
|
||||
- 已列出已知限制。
|
||||
|
||||
@@ -188,10 +241,12 @@
|
||||
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
|
||||
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
|
||||
- 如果本次流程产生可复用经验，写入 compound knowledge。
|
||||
- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
|
||||
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
|
||||
|
||||
**退出条件**：
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
|
||||
- `devflow/index.md` 已包含或更新本项目条目。
|
||||
- 用户已被询问是否 archive OpenSpec change。
|
||||
|
||||
**输出**：
|
||||
|
||||
@@ -65,6 +65,68 @@
|
||||
- 风险接受：{accepted by whom/when}
|
||||
```
|
||||
|
||||
## 接口影响记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 接口影响记录
|
||||
|
||||
## 分级
|
||||
|
||||
- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
|
||||
- 判级原因：{why this level}
|
||||
- 是否需要独立接口文档：是 / 否
|
||||
|
||||
## 变更对象
|
||||
|
||||
- 接口/字段/DTO/事件/回调/数据库契约：
|
||||
- 判断逻辑变化：
|
||||
- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
|
||||
|
||||
## 影响范围
|
||||
|
||||
- 调用方/消费者：
|
||||
- 是否跨模块/跨服务/跨团队：
|
||||
- 旧调用方是否需要改动：
|
||||
|
||||
## 兼容与迁移
|
||||
|
||||
- 是否向后兼容：
|
||||
- 迁移/灰度/回滚要求：
|
||||
- 风险接受：
|
||||
|
||||
## 验收方式
|
||||
|
||||
- 如何证明新行为正确：
|
||||
- 如何证明旧行为未破坏：
|
||||
- 需要用户确认的问题：
|
||||
```
|
||||
|
||||
## 实现期冲突记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 实现期冲突记录
|
||||
|
||||
## 冲突摘要
|
||||
|
||||
- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
|
||||
- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
|
||||
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
|
||||
|
||||
## 证据
|
||||
|
||||
- OpenSpec 依据：
|
||||
- 代码或测试证据：
|
||||
- 用户反馈：
|
||||
|
||||
## 处理
|
||||
|
||||
- 决策：
|
||||
- 是否需要用户确认：是 / 否
|
||||
- OpenSpec 回写：不需要 / 已回写 / 待回写
|
||||
- 代码处理：
|
||||
- 验证方式：
|
||||
```
|
||||
|
||||
## PRD 模板
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -1,259 +0,0 @@
|
||||
---
|
||||
name: essence
|
||||
description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Essence: Extract Core Design Patterns
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
|
||||
|
||||
**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
First, check whether an `/explore` result exists:
|
||||
|
||||
- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
|
||||
- No `/explore` result → this is an independent launch, default to **Auto-detect**.
|
||||
|
||||
Always confirm before proceeding:
|
||||
|
||||
| Mode | When | Entry |
|
||||
|---|---|---|
|
||||
| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
|
||||
| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
|
||||
| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
|
||||
|
||||
### Lens definitions
|
||||
|
||||
| Lens | Core question | Guided behavior |
|
||||
|---|---|---|
|
||||
| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
|
||||
| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
|
||||
| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
|
||||
|
||||
A lens shapes which sources to read and how to frame the output, but does not add separate phases.
|
||||
|
||||
### Auto-detect signals
|
||||
|
||||
A design is "essence" if it passes 2 or more of these signals:
|
||||
|
||||
| Signal | Evidence |
|
||||
|---|---|
|
||||
| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
|
||||
| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
|
||||
| Heavily discussed in Issues/PRs | Design decisions debated by community |
|
||||
| Unique among similar projects | Competitors don't do it this way |
|
||||
| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
|
||||
| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
|
||||
| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
|
||||
| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
|
||||
|
||||
**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
|
||||
|
||||
If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
|
||||
|
||||
## Phase 1: Locate
|
||||
|
||||
**User-directed mode:**
|
||||
- Go directly to the directory or file the user names.
|
||||
- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
|
||||
|
||||
**Auto-detect mode:**
|
||||
- Scan README, CLAUDE.md, and top-level docs for architecture claims.
|
||||
- Identify 1-2 standout design directions.
|
||||
- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
|
||||
- If user doesn't choose, pick the strongest one and state why.
|
||||
|
||||
**Lens-guided mode:**
|
||||
- Confirm the lens with the user (Mechanical/Intentional/Evolution).
|
||||
- Frame the search in terms of the lens.
|
||||
- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
|
||||
|
||||
**Output:** 1-2 design directions to analyze + lens confirmation.
|
||||
|
||||
**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
|
||||
|
||||
## Phase 2: Deep Dive
|
||||
|
||||
Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
|
||||
|
||||
**For each file:**
|
||||
- What role does it play in this design?
|
||||
- What interfaces does it expose?
|
||||
- How does it connect to other parts of the system?
|
||||
|
||||
**Trace the call chain:**
|
||||
- Start from the entry point that uses this design.
|
||||
- Follow the flow until you understand the full pattern.
|
||||
- Stop when you hit boilerplate, config, or test files.
|
||||
|
||||
**Output:** Core file list (≤10) + call chain + lens-specific annotations.
|
||||
|
||||
**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
|
||||
|
||||
## Phase 3: Extract Pattern
|
||||
|
||||
Analyze the design at a higher level. Let the lens shape the analysis angle:
|
||||
- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
|
||||
- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
|
||||
- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
|
||||
|
||||
**Universal analysis dimensions** (all lenses):
|
||||
|
||||
- **Problem:** What specific problem does this design solve? What was the pain before?
|
||||
- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
|
||||
- **Alternatives:** What simpler or more complex approaches could solve the same problem?
|
||||
- **Tradeoffs:** Why did the author choose this? What does it give up?
|
||||
- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
|
||||
|
||||
**Output:** Design pattern card (lens-framed).
|
||||
|
||||
**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
|
||||
|
||||
## Phase 4: Migrate
|
||||
|
||||
Make the learning actionable. Let the lens tailor the output:
|
||||
- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
|
||||
- **Intentional** → decision framework (checklist for evaluating tradeoffs)
|
||||
- **Evolution** → migration path (step-by-step refactor plan)
|
||||
|
||||
**Universal deliverables** (all lenses):
|
||||
|
||||
- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
|
||||
- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
|
||||
- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
|
||||
|
||||
**Output:** Migration example + pitfall list (lens-tailored).
|
||||
|
||||
**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
|
||||
|
||||
## Phase 5: Self-review
|
||||
|
||||
Check the report is honest:
|
||||
|
||||
**All modes:**
|
||||
- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
|
||||
- [ ] The analysis is deep enough that you could explain it out loud.
|
||||
- [ ] The migration example captures the core idea, not surface syntax.
|
||||
- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
|
||||
|
||||
**Stall signals (any one → return to relevant phase):**
|
||||
- Cannot name a file that proves the pattern → back to Phase 2
|
||||
- Cannot explain why it's better than alternatives → back to Phase 3
|
||||
- Migration example is over 20 lines → simplify, back to Phase 4
|
||||
- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
|
||||
|
||||
**Output:** Essence report with lens annotation.
|
||||
|
||||
## Optional: HTML Card
|
||||
|
||||
**Only when the user explicitly requests it.**
|
||||
|
||||
Generate an HTML visualization card as a shareable deliverable.
|
||||
|
||||
### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>{Project Name} - Essence Report</title>
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
/* Same glassmorphism styles as /explore */
|
||||
:root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
|
||||
[data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
|
||||
.glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
|
||||
.pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
|
||||
</style>
|
||||
</head>
|
||||
<body class="p-8">
|
||||
<nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
|
||||
<span class="font-bold text-xl">💎 {Project Name} 精华</span>
|
||||
<span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
|
||||
</nav>
|
||||
|
||||
<main class="max-w-4xl mx-auto mt-24 space-y-6">
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
|
||||
<p>{one-line description}</p>
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
|
||||
<!-- Lens-framed pattern card -->
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
|
||||
<pre class="mermaid">{diagram}</pre>
|
||||
</section>
|
||||
|
||||
<section class="glass-panel p-6">
|
||||
<h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
|
||||
<pre class="pattern-diagram"><code>{code_example}</code></pre>
|
||||
<p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
|
||||
</section>
|
||||
</main>
|
||||
|
||||
<script>mermaid.initialize({ startOnLoad: true });</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
```markdown
|
||||
### HTML Card Generated
|
||||
|
||||
- **Path:** `outputs/{project}-essence.html`
|
||||
- **Theme:** {modern/ink}
|
||||
- **Accent Color:** Purple (essence = jewel)
|
||||
```
|
||||
|
||||
**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
|
||||
- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
|
||||
- **Stop after the report.** Do not modify the user's project or the target project.
|
||||
- **HTML is optional.** Do not block analysis on HTML generation.
|
||||
|
||||
## Gotchas
|
||||
|
||||
| What happened | Rule |
|
||||
|---|---|
|
||||
| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
|
||||
| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
|
||||
| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
|
||||
| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
|
||||
| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
|
||||
| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
|
||||
| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
|
||||
| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
|
||||
| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Essence Report: {project name}
|
||||
Lens: mechanical / intentional / evolution
|
||||
Design analyzed: {one-line description}
|
||||
Files examined: {count}
|
||||
Pattern: {pattern name or custom description}
|
||||
Migration: {steal-it example, ≤20 lines}
|
||||
HTML generated: yes / no
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the report, stop. No modifications. No follow-ups.
|
||||
@@ -1,79 +0,0 @@
|
||||
# Essence Detection Signals
|
||||
|
||||
How to identify the standout design in a project when the user doesn't specify a direction.
|
||||
|
||||
## Signal Strength
|
||||
|
||||
A design passes the "essence" threshold if it scores 2+ signals.
|
||||
|
||||
### Strong Signals (score = 1 each)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
|
||||
| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
|
||||
| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
|
||||
| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
|
||||
| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
|
||||
|
||||
### Objective Signals (score = 1 each, no subjective judgment needed)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
|
||||
| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
|
||||
| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
|
||||
|
||||
### Weak Signals (score = 0.5 each)
|
||||
|
||||
| Signal | How to detect | Example |
|
||||
|---|---|---|
|
||||
| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
|
||||
| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
|
||||
| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
|
||||
| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
|
||||
|
||||
## Not Signals
|
||||
|
||||
These do NOT count as essence:
|
||||
|
||||
- "Clean code" or "well organized" — that's quality, not design
|
||||
- "Uses TypeScript" — that's a language choice, not architecture
|
||||
- "Has good tests" — that's engineering discipline, not design
|
||||
- "Many stars on the repo" — popularity ≠ design quality
|
||||
- "Uses the latest framework" — following trends ≠ standing out
|
||||
- Utility functions — even well-written ones are tools, not designs
|
||||
|
||||
## Auto-detect Procedure
|
||||
|
||||
When the user says "find the essence":
|
||||
|
||||
1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
|
||||
2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
|
||||
3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
|
||||
4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
|
||||
5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
|
||||
6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
|
||||
|
||||
### Example Output Format
|
||||
|
||||
```
|
||||
Standout designs in {project}:
|
||||
|
||||
A) {Design A name} — evidenced by {README claim / file / doc}
|
||||
What it does: {one sentence}
|
||||
|
||||
B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
|
||||
What it does: {one sentence}
|
||||
|
||||
Which should we dive into? (or I can pick the strongest)
|
||||
```
|
||||
|
||||
## Failure Modes
|
||||
|
||||
| Situation | Response |
|
||||
|---|---|
|
||||
| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
|
||||
| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
|
||||
| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
|
||||
| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
name: explore
|
||||
description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Explore: Project Understanding and Onboarding
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start.
|
||||
|
||||
`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching.
|
||||
|
||||
## Project Type Detection
|
||||
|
||||
After the initial scan, classify the target before continuing:
|
||||
|
||||
| Type | Signals | What changes |
|
||||
|---|---|---|
|
||||
| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases |
|
||||
| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) |
|
||||
| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal |
|
||||
|
||||
State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type.
|
||||
|
||||
## Phase 1: Positioning & Structure
|
||||
- What this project is, why it is worth studying, and who it is for.
|
||||
- Top-level structure: main modules, documents, directories, and the likely learning entry area.
|
||||
- Tradeoffs vs alternatives when evidence exists.
|
||||
|
||||
## Phase 2: Flow
|
||||
**Code repositories only.**
|
||||
- Skip for non-code and template repositories.
|
||||
- Trace the main runtime or request flow.
|
||||
- Produce at least one architecture or core-flow diagram.
|
||||
- Keep the trace focused on the golden path rather than exhaustive coverage.
|
||||
|
||||
## Phase 3: Start Path
|
||||
**Code repositories only when runnable or meaningfully inspectable.**
|
||||
- Provide the minimal path to start learning or running the project.
|
||||
- Give the first command or first inspection step.
|
||||
- Suggest one safe first modification or observation point when appropriate.
|
||||
|
||||
## Phase 4: Core Designs
|
||||
- Summarize 2-3 core implementations or ideas.
|
||||
- Keep this at overview depth.
|
||||
- For each item, include what it is, where it lives, and why it matters.
|
||||
|
||||
## Minimum Deliverables
|
||||
|
||||
The final `/explore` report must include:
|
||||
- Project positioning
|
||||
- Why it is worth studying
|
||||
- 2-3 core implementations or core ideas
|
||||
- Tradeoffs or comparisons when applicable
|
||||
- At least 1 diagram:
|
||||
- code repository → architecture diagram or core flow diagram
|
||||
- non-code repository → structure diagram, idea map, or workflow diagram
|
||||
|
||||
## Boundary Rules
|
||||
|
||||
`/explore` may:
|
||||
- scan structure
|
||||
- explain the main flow
|
||||
- provide a minimal start path
|
||||
- summarize 2-3 core designs
|
||||
|
||||
`/explore` must not:
|
||||
- perform `/essence`-level deep extraction
|
||||
- act as `/follow`-style guided teaching
|
||||
- include Verify, Deep Fission, or HTML Output phases
|
||||
- preserve no retired lightweight fallback behavior
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Explore Report: {project name}
|
||||
Project type: code / skill-docs / template
|
||||
Phases completed: 4/4 (or note skipped code-only phases)
|
||||
Diagram included: yes / no
|
||||
Core designs: 2-3
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the report, stop. Do not proceed to `/essence` or `/follow` automatically.
|
||||
@@ -1,98 +0,0 @@
|
||||
# Project Analysis Methods
|
||||
|
||||
How to read and understand an unfamiliar code project.
|
||||
|
||||
## 1. Identify the Entry Point
|
||||
|
||||
Every project has a door. Find it first.
|
||||
|
||||
### By Language
|
||||
|
||||
| Language | Look for |
|
||||
|---|---|
|
||||
| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
|
||||
| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
|
||||
| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
|
||||
| **Rust** | `src/main.rs` or `src/bin/*.rs` |
|
||||
| **Java** | Class with `public static void main(String[] args)` |
|
||||
| **C/C++** | `main()` function, conventionally in `src/main.c` |
|
||||
| **Swift** | `main.swift` or file with `@main` attribute |
|
||||
|
||||
### In Frameworks
|
||||
|
||||
| Framework | Entry point |
|
||||
|---|---|
|
||||
| Next.js | `app/` or `pages/` directory, `next.config.js` |
|
||||
| React (Vite) | `src/main.tsx` or `src/main.jsx` |
|
||||
| Vue (Vite) | `src/main.ts` or `src/main.js` |
|
||||
| Express | File that calls `app.listen()` |
|
||||
| FastAPI | File that creates `FastAPI()` instance |
|
||||
| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
|
||||
| Flask | `app.py` or `app/__init__.py` |
|
||||
| Spring Boot | `*Application.java` with `@SpringBootApplication` |
|
||||
|
||||
## 2. Judge Project Complexity
|
||||
|
||||
Don't over-engineer simple projects. Don't under-analyze complex ones.
|
||||
|
||||
### Simple (<50 files, single language)
|
||||
- Read every source file.
|
||||
- No need for flow diagrams beyond a simple sequence.
|
||||
- A light `/explore` pass is probably enough.
|
||||
|
||||
### Standard (50-500 files, 1-2 languages)
|
||||
- Read entry point + core modules + 1-2 feature files.
|
||||
- Build 1-2 flow diagrams.
|
||||
- `/explore` is the right level.
|
||||
|
||||
### Complex (>500 files, multi-language, monorepo)
|
||||
- Read entry point + architecture docs + one representative module.
|
||||
- Use `/essence` to find standout designs, or `/explore` for one package at a time.
|
||||
- Do NOT try to understand the whole project in one pass.
|
||||
|
||||
## 3. Separate Core Code from Scaffolding
|
||||
|
||||
Not all files are worth reading.
|
||||
|
||||
### Ignore (scaffolding)
|
||||
- `*.config.js`, `*.config.ts` — configuration, not logic
|
||||
- `dist/`, `build/`, `out/` — generated output
|
||||
- `node_modules/`, `vendor/`, `.venv/` — dependencies
|
||||
- `*.lock`, `yarn.lock`, `go.sum` — lock files
|
||||
- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
|
||||
- `test/fixtures/`, `test/data/` — test data
|
||||
|
||||
### Read (core)
|
||||
- Entry point file
|
||||
- Router/middleware/config handlers
|
||||
- Model/entity/schema definitions
|
||||
- Core algorithm or business logic files
|
||||
- Files referenced most in imports
|
||||
|
||||
### Hint: Follow imports
|
||||
|
||||
```
|
||||
entry file → import A → import B → core logic
|
||||
```
|
||||
|
||||
Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.
|
||||
|
||||
## 4. Read Unfamiliar Framework Code
|
||||
|
||||
You don't know every framework. That's fine.
|
||||
|
||||
### Strategy
|
||||
|
||||
1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.
|
||||
|
||||
2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.
|
||||
|
||||
3. **Identify the framework's conventions.** Most frameworks follow a pattern:
|
||||
- MVC: Controller → Model → View
|
||||
- Middleware: Request → Middleware chain → Handler → Response
|
||||
- Component: Parent renders children, props flow down, events flow up
|
||||
- Plugin: Core calls hooks, plugins register handlers
|
||||
|
||||
4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.
|
||||
|
||||
5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.
|
||||
@@ -1,173 +0,0 @@
|
||||
# Flow Pattern Library
|
||||
|
||||
Common architecture patterns and how to identify them in code.
|
||||
|
||||
## MVC / MVVM / MVX
|
||||
|
||||
### What it is
|
||||
Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel).
|
||||
|
||||
### File signatures
|
||||
| Pattern | Directories/Files |
|
||||
|---|---|
|
||||
| **MVC** | `controllers/`, `models/`, `views/` |
|
||||
| **MVVM** | `viewmodels/`, `views/`, `models/` |
|
||||
| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Request → Controller → Model (data) → View (render) → Response
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does the file handle data, display, or coordination?" If yes → MVC-family.
|
||||
|
||||
---
|
||||
|
||||
## Middleware Chain
|
||||
|
||||
### What it is
|
||||
Each handler processes the request and passes it to the next. Like an assembly line.
|
||||
|
||||
### File signatures
|
||||
| Framework | Indicator |
|
||||
|---|---|---|
|
||||
| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` |
|
||||
| **FastAPI** | `@app.middleware("http")`, `Depends()` |
|
||||
| **Next.js** | `middleware.ts` at root or in `app/` |
|
||||
| **Gin (Go)** | `router.Use(middleware1, middleware2)` |
|
||||
| **Koa** | `app.use(async (ctx, next) => { ... })` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Request → Middleware A → Middleware B → Handler → Response
|
||||
↓ ↓
|
||||
auth check log request
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does this function call `next()` or pass control to something else?" If yes → middleware.
|
||||
|
||||
### Common middleware order
|
||||
```
|
||||
1. CORS / Security headers
|
||||
2. Logging / Request ID
|
||||
3. Authentication / Authorization
|
||||
4. Body parsing / Validation
|
||||
5. Rate limiting
|
||||
6. Route handler
|
||||
7. Error handler (catches everything above)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin / Extension System
|
||||
|
||||
### What it is
|
||||
Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` |
|
||||
| **Interface-based** | Abstract class or interface that plugins implement |
|
||||
| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention |
|
||||
| **VSCode-style** | `contributes` in `package.json`, activation events |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Core starts
|
||||
↓
|
||||
Scans for plugins
|
||||
↓
|
||||
Each plugin registers itself
|
||||
↓
|
||||
Core fires hooks → plugins respond
|
||||
↓
|
||||
Core runs with extended capabilities
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Can I add functionality without modifying core code?" If yes → plugin architecture.
|
||||
|
||||
---
|
||||
|
||||
## Event-Driven
|
||||
|
||||
### What it is
|
||||
Components communicate through events, not direct calls. Publishers emit, subscribers listen.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` |
|
||||
| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` |
|
||||
| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` |
|
||||
| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` |
|
||||
| **Signals (Python)** | `@signal.connect`, `signal.send()` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Component A emits "user.created"
|
||||
↓
|
||||
Listener B hears it → sends welcome email
|
||||
Listener C hears it → creates default settings
|
||||
Listener D hears it → logs analytics
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does code communicate without importing or calling each other directly?" If yes → event-driven.
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
### What it is
|
||||
Centralized storage for application state. Components read and update through defined interfaces.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` |
|
||||
| **Zustand** | `create((set) => ({ ... }))` |
|
||||
| **Jotai** | `atom(value)`, `useAtom(atom)` |
|
||||
| **MobX** | `@observable`, `@action`, `@computed` |
|
||||
| **React Context** | `createContext()`, `useContext()`, `Provider` |
|
||||
| **Pinia (Vue)** | `defineStore()`, `state`, `actions` |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Component dispatches action
|
||||
↓
|
||||
Reducer processes action + current state
|
||||
↓
|
||||
New state emitted
|
||||
↓
|
||||
Subscribed components re-render
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Where does the app store data that multiple components need?" If it's a single store → state management pattern.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline / Chain of Responsibility
|
||||
|
||||
### What it is
|
||||
Data flows through a series of processors. Each processor transforms the data and passes it on.
|
||||
|
||||
### File signatures
|
||||
| Pattern | Indicator |
|
||||
|---|---|
|
||||
| **Stream processing** | `.pipe(transform1).pipe(transform2)` |
|
||||
| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate |
|
||||
| **Data pipeline** | `input → transform → validate → output` |
|
||||
| **Makefile** | Target depends on prerequisites, each is a step |
|
||||
|
||||
### Flow
|
||||
```
|
||||
Raw input → Tokenizer → Parser → Transformer → Generator → Output
|
||||
```
|
||||
|
||||
### Key question
|
||||
"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline.
|
||||
@@ -1,120 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Collect project structure for /explore analysis.
|
||||
# Usage: Run from project root, or pass project path as argument.
|
||||
# Output: Structured text with directory tree, file counts, language distribution.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
PROJECT_DIR="${1:-.}"
|
||||
cd "$PROJECT_DIR"
|
||||
|
||||
echo "=== PROJECT STRUCTURE ==="
|
||||
echo ""
|
||||
|
||||
# Directory tree (depth 3, exclude common noise)
|
||||
echo "--- Directory Tree (depth 3) ---"
|
||||
if command -v tree &>/dev/null; then
|
||||
tree -L 3 \
|
||||
-I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \
|
||||
--dirsfirst
|
||||
elif command -v find &>/dev/null; then
|
||||
find . -maxdepth 3 \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
-not -path "*/__pycache__/*" \
|
||||
-not -path "*/.egg-info/*" \
|
||||
-not -path "*/coverage/*" \
|
||||
-not -path "./.nyc_output/*" \
|
||||
-print | head -100 | sort
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== FILE COUNTS ==="
|
||||
echo ""
|
||||
|
||||
# Count files by extension (top 10)
|
||||
echo "--- Top 10 File Types ---"
|
||||
find . -type f \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
-not -path "*/__pycache__/*" \
|
||||
-printf '%f\n' | \
|
||||
sed 's/.*\.//' | \
|
||||
grep -v '^\.[^/]*$' | \
|
||||
sort | uniq -c | sort -rn | head -10
|
||||
|
||||
echo ""
|
||||
echo "=== TOTAL FILE COUNT ==="
|
||||
echo ""
|
||||
|
||||
# Total files (excluding noise)
|
||||
total=$(find . -type f \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./vendor/*" \
|
||||
-not -path "./dist/*" \
|
||||
-not -path "./build/*" \
|
||||
-not -path "./out/*" \
|
||||
-not -path "./.venv/*" \
|
||||
| wc -l)
|
||||
echo "Total source files: $total"
|
||||
|
||||
echo ""
|
||||
echo "=== DEPENDENCY FILES ==="
|
||||
echo ""
|
||||
|
||||
# List dependency declaration files found
|
||||
for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do
|
||||
if [ -f "$dep_file" ]; then
|
||||
echo "FOUND: $dep_file"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check for workspace/monorepo configs
|
||||
echo ""
|
||||
echo "=== WORKSPACE / MONOREPO ==="
|
||||
echo ""
|
||||
|
||||
for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do
|
||||
if [ -f "$ws_file" ]; then
|
||||
echo "FOUND: $ws_file"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check Cargo.toml for workspace
|
||||
if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then
|
||||
echo "FOUND: Cargo.toml [workspace]"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== ENTRY POINTS ==="
|
||||
echo ""
|
||||
|
||||
# Try to identify entry points
|
||||
if [ -f "package.json" ]; then
|
||||
main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "")
|
||||
bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "")
|
||||
dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "")
|
||||
[ -n "$main" ] && echo "package.json main: $main"
|
||||
[ -n "$bin" ] && echo "package.json bin: $bin"
|
||||
[ -n "$dev" ] && echo "package.json dev/start: $dev"
|
||||
fi
|
||||
|
||||
for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do
|
||||
if [ -f "$entry" ]; then
|
||||
echo "FOUND: $entry"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== COLLECTED ==="
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
name: follow
|
||||
description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction.
|
||||
metadata:
|
||||
version: "0.5.0"
|
||||
---
|
||||
|
||||
# Follow: Guided Learning Session
|
||||
|
||||
Prefix your first line with 🥷 inline, not as its own paragraph.
|
||||
|
||||
You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it.
|
||||
|
||||
`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result.
|
||||
|
||||
## Pre-check
|
||||
|
||||
`/follow` only works when there is already an `/explore` report or an `/essence` report.
|
||||
|
||||
- `/explore` report exists → use it as the main learning path
|
||||
- `/essence` report exists → use it for design-focused guided study
|
||||
- Neither exists → refuse clearly
|
||||
|
||||
Refusal behavior:
|
||||
"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first."
|
||||
|
||||
Load the existing report before continuing.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
After the pre-check, select one mode based on the prerequisite report:
|
||||
|
||||
- From `/explore` + code repository → default **Runnable**
|
||||
- From `/explore` + non-code repository → force **Reader**
|
||||
- From `/essence` → default **Reader** (user is in design-analysis state)
|
||||
|
||||
| Mode | When | Entry |
|
||||
|---|---|---|
|
||||
| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution |
|
||||
| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading |
|
||||
|
||||
State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide.
|
||||
|
||||
## Teaching Interaction Rules
|
||||
|
||||
`/follow` must teach by guidance, not by dumping answers:
|
||||
- explain the purpose of the current step first
|
||||
- give the user an observation point or action point
|
||||
- ask the user to predict, try, or explain before revealing the answer
|
||||
- then reveal, correct, or deepen the explanation
|
||||
- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to
|
||||
|
||||
## Runnable Check
|
||||
|
||||
Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project):
|
||||
- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable.
|
||||
- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why.
|
||||
- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists.
|
||||
- Do not introduce a third mode.
|
||||
|
||||
## Runnable Mode Flow
|
||||
1. Confirm environment and prerequisites.
|
||||
2. Let the user run the project.
|
||||
3. Let the user make one safe change.
|
||||
4. Walk the main flow together.
|
||||
5. Give one small exercise.
|
||||
6. Review what they learned.
|
||||
|
||||
## Reader Mode Flow
|
||||
1. Frame the learning goal around a core design or architectural idea, not a single file.
|
||||
2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff.
|
||||
3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?").
|
||||
4. Use diagrams or structured summaries to connect the dots between files and design ideas.
|
||||
5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere.
|
||||
6. Review what they learned.
|
||||
|
||||
## Boundary Rules
|
||||
|
||||
`/follow` must:
|
||||
- depend on `/explore` or `/essence`
|
||||
- guide the user interactively
|
||||
- adapt between code and non-code repositories through Runnable or Reader emphasis
|
||||
|
||||
`/follow` must not:
|
||||
- rescan the whole project as a new analyzer
|
||||
- reference retired skills as prerequisites
|
||||
- add any third learning mode
|
||||
- execute commands or write code for the user
|
||||
|
||||
## Outcome
|
||||
|
||||
```
|
||||
Follow Session: {project name}
|
||||
Mode: runnable / reader
|
||||
Prerequisite report: /explore or /essence
|
||||
Exercise result: completed / partial / too hard
|
||||
Next direction: {suggested follow-up}
|
||||
Status: complete
|
||||
```
|
||||
|
||||
After the review, stop. Ask whether the user wants another exercise or wants to end the session.
|
||||
@@ -1,113 +0,0 @@
|
||||
# Environment Detection Rules
|
||||
|
||||
How to detect the runtime environment and guide the user through setup in `/follow`.
|
||||
|
||||
## Language Detection from Config
|
||||
|
||||
Check these files in order. The first match is the primary language.
|
||||
|
||||
| Config file | Language | Runtime check | Install command |
|
||||
|---|---|---|---|
|
||||
| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer |
|
||||
| `pyproject.toml` | Python | `python --version` | pyenv or python.org |
|
||||
| `go.mod` | Go | `go version` | golang.org/dl |
|
||||
| `Cargo.toml` | Rust | `rustc --version` | rustup |
|
||||
| `pom.xml` | Java | `java -version` | SDKMAN or official |
|
||||
| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN |
|
||||
| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv |
|
||||
| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK |
|
||||
| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager |
|
||||
| `swift package.json` | Swift | `swift --version` | Xcode or swift.org |
|
||||
|
||||
## Dependency Installation
|
||||
|
||||
Once language is detected, guide the user:
|
||||
|
||||
### JavaScript/TypeScript
|
||||
```bash
|
||||
# Check which package manager is used
|
||||
if [ -f "yarn.lock" ]; then yarn install
|
||||
elif [ -f "pnpm-lock.yaml" ]; then pnpm install
|
||||
elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install
|
||||
else npm install
|
||||
fi
|
||||
```
|
||||
|
||||
### Python
|
||||
```bash
|
||||
# Modern Python projects
|
||||
pip install -e .
|
||||
# Or with requirements
|
||||
pip install -r requirements.txt
|
||||
# Or with poetry
|
||||
poetry install
|
||||
# Or with uv
|
||||
uv pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Go
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
### Rust
|
||||
```bash
|
||||
cargo build
|
||||
```
|
||||
|
||||
### Java (Maven)
|
||||
```bash
|
||||
mvn install
|
||||
```
|
||||
|
||||
### Java (Gradle)
|
||||
```bash
|
||||
./gradlew build
|
||||
# or
|
||||
gradle build
|
||||
```
|
||||
|
||||
## Run Command Detection
|
||||
|
||||
How to start the project:
|
||||
|
||||
| Source | Command |
|
||||
|---|---|
|
||||
| `package.json` → `scripts.dev` | `npm run dev` |
|
||||
| `package.json` → `scripts.start` | `npm start` |
|
||||
| `Makefile` → `dev` target | `make dev` |
|
||||
| `Makefile` → `run` target | `make run` |
|
||||
| `pyproject.toml` (Poetry) | `poetry run python main.py` |
|
||||
| `go.mod` → `package main` | `go run main.go` |
|
||||
| `Cargo.toml` → `[[bin]]` | `cargo run` |
|
||||
| `docker-compose.yml` exists | `docker-compose up` |
|
||||
| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` |
|
||||
|
||||
## Common Environment Issues
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|---|---|---|
|
||||
| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) |
|
||||
| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` |
|
||||
| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo |
|
||||
| `ENOENT: no such file` | Wrong working directory | `cd` to project root first |
|
||||
| `port already in use` | Another process on same port | Kill the process or use different port |
|
||||
| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` |
|
||||
| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` |
|
||||
| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement |
|
||||
| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` |
|
||||
|
||||
## Detection Script for /follow
|
||||
|
||||
```bash
|
||||
# Quick environment check
|
||||
echo "=== Environment ==="
|
||||
node --version 2>/dev/null || echo "Node.js: not installed"
|
||||
python --version 2>/dev/null || echo "Python: not installed"
|
||||
go version 2>/dev/null || echo "Go: not installed"
|
||||
rustc --version 2>/dev/null || echo "Rust: not installed"
|
||||
java -version 2>/dev/null || echo "Java: not installed"
|
||||
echo "PWD: $(pwd)"
|
||||
```
|
||||
|
||||
Run this at the start of `/follow` Step 1 to understand what's available.
|
||||
Reference in New Issue
Block a user