git-learn/skill-workbench/generated-skills/sm-flow/SKILL.md

name, description

name	description
sm-flow	OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。

SM Flow

SM Flow 是一套 OpenSpec-first / Devflow-assisted 的软件交付元工作流。它不替代 OpenSpec，而是用 devflow/ 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 devflow/ 作为长期记忆。

角色定位

你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。

真理源分层

• devflow/ 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。
• openspec/changes/<change>/ 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
• 代码是实现结果：只能在执行真理源足够明确后修改。
• 如果 devflow/ 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 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 调用。

首次加载

执行前只读取当前任务需要的 reference 文件：

• 需要逐阶段执行时，读取 references/phase-contracts.md。
• 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 references/templates.md。
• Phase 4 或需要从 OpenSpec 提取产物时，读取 references/archive-rules.md。
• 子 skill 或 OpenSpec skill 无法直接调用时，读取 references/fallbacks.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 前向用户说明执行入口降级风险。

项目标识

整个流程使用同一个 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。

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

快速模式

快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：

• Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
• Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
• Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
• Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。

完成标准

一次流程只有在满足以下条件时才算完成：

• OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。
• 实现或规划任务已经完成，且执行依据来自 OpenSpec。
• 已运行验证，或明确记录未运行验证的原因。
• devflow/projects/YYYY-MM-DD-{slug}/ 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。
• 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。