Files

T

zhuyongxin 37083fc92a chore: add agent skills

2026-07-06 10:18:10 +08:00

7.0 KiB

Raw Permalink Blame History

name, description

name	description
sm-flow	OpenSpec-first 工程流程 harness。仅在用户显式调用 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive，或明确要求使用 sm-flow 流程时使用；不要根据需求类型自动触发。

SM Flow

SM Flow 是一个协议层 harness——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。

sm-flow 会自动维护 devflow/ 目录作为项目长期记忆。用户不需要手动管理它，sm-flow 会在流程中自动读取和回填。

触发规则

只在用户显式调用时使用 sm-flow：

用户输入 /sm-flow、/sm-flow explore、/sm-flow apply、/sm-flow archive。
用户用自然语言明确要求"使用 sm-flow"、"走 sm-flow 流程"或等价表达。

不要根据需求类型自动触发 sm-flow。即使任务涉及 OpenSpec、跨模块、接口契约、需求澄清或 devflow 归档，只要用户没有显式要求 sm-flow，就按普通工程任务处理。

四层架构

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。

核心规则

以下 6 条是硬约束，违反即流程失败。其余约束按阶段定义在 references/phase-contracts.md。

OpenSpec 是唯一执行真理源。apply 阶段必须读取 Committed OpenSpec 文件作为执行依据；对话中的描述不等于产物。Draft OpenSpec 是讨论对象，不是执行许可。
不得跳过 context。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
不得跳过 grill。必须按 references/scales.md 的当前分档要求完成澄清或验证。
不得跳过 commit。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
冲突必须先分类再处理。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
能力来源必须显式声明。每个阶段先声明使用外部子 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/operating-rules.md；如果外部 OpenSpec 能力或子 skill 不可用，再补读 references/fallbacks.md。
判断或执行 micro / standard / complex 分档时，读取 references/scales.md；其它文件不得重复定义分档细节。
当 checkpoint / gate / fallback / Draft / Committed 等术语含义不清，或需要统一对用户说明时，读取 references/glossary.md。
创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 references/templates.md。
archive 阶段或需要从 OpenSpec 提取产物时，读取 references/archive-rules.md。

内部阶段

9 个内部阶段，按执行顺序：

clarify — 入口澄清：接收初始需求，澄清到可生成轻量 proposal。
context — 上下文收集：读取 devflow 的 glossary、ADR、历史项目、compound knowledge。
propose — 轻量 propose：只生成 proposal.md，不调用 openspec-propose。
grill — 人类对齐澄清：evidence-driven 查证 + user-interview one-at-a-time，回写 proposal。
specify — 细化 + 对齐：基于已稳定的 proposal 补全 design/specs/tasks，做 cross-artifact 对齐。
audit — 架构审计：审计结果如果影响实现，回写 OpenSpec design/tasks。
commit — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
apply — OpenSpec 执行：基于 Committed OpenSpec 实现代码。
archive — 回填 + 归档：从 OpenSpec 产物和 decisions.md 提炼长期档案，询问是否归档。

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

关键阶段的完成判断也以 references/phase-contracts.md 为准；如果缺少显式 checkpoint 或能力来源声明，该阶段不得视为已完成。

快速模式

快速模式的具体约束见 references/operating-rules.md。

完成标准

流程完成标准见 references/operating-rules.md。

7.0 KiB Raw Permalink Blame History Unescape Escape