zhuyongxin
71e0b7f801
- Reposition sm-flow as orchestration harness over OpenSpec lifecycle - Adopt 4 user commands (Actions, Not Phases) instead of phase numbers - Rename all stages to English verbs (clarify through archive) - Reorder execution: grill before specify to eliminate rework loops - Simplify core rules from 19 to 6 hard constraints in SKILL.md - Simplify conflict classification from 4 categories to 2+1 - Switch devflow strategy to decisions.md-only process log during execution - Upgrade micro mode from artifact compression to gate merging - Add observable outputs for quality constraints - Add design review doc and user guide - Append v4.0 changelog to workflow.md
85 lines
5.4 KiB
Markdown
85 lines
5.4 KiB
Markdown
---
|
||
name: sm-flow
|
||
description: OpenSpec-first 的结构化工程开发协议层 harness。编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用。
|
||
---
|
||
|
||
# SM Flow
|
||
|
||
SM Flow 是一个**协议层 harness**——编排 OpenSpec 的完整生命周期。它通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec。
|
||
|
||
sm-flow 会自动维护 `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`。
|
||
|
||
1. **OpenSpec 是唯一执行真理源**。apply 只能基于 Committed OpenSpec 执行。Draft OpenSpec 是讨论对象，不是执行许可。
|
||
2. **不得跳过 context**。生成 OpenSpec 前，必须先读取相关 devflow 上下文（glossary、ADR、历史项目）。
|
||
3. **不得跳过 grill**。即使需求看起来很清楚，至少解决三个高价值澄清或验证问题。
|
||
4. **不得跳过 commit**。进入 apply 前，Draft OpenSpec 必须通过 commit 检查成为 Committed OpenSpec。
|
||
5. **冲突必须先分类再处理**。OpenSpec 不准（规格遗漏）→ 修正 OpenSpec；代码偏离（实现偏差）→ 修正代码；不确定或涉及设计方向 → 暂停并等待用户确认。
|
||
6. **降级执行必须标注**。fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
|
||
|
||
每个阶段的过程约束（question pool、one-at-a-time、cross-artifact 对齐、冲突回写等）和质量约束（可观测产出要求）见 `references/phase-contracts.md` 中对应阶段的退出条件和 checkpoint。
|
||
|
||
## 用户命令
|
||
|
||
| 命令 | 用户意图 | harness 内部行为 |
|
||
|---|---|---|
|
||
| `/sm-flow` | 完整流程 | clarify → context → propose → grill → specify → audit → commit → apply → archive |
|
||
| `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
|
||
| `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
|
||
| `/sm-flow archive` | 收尾 | 回填 devflow + 归档确认 |
|
||
|
||
用户也可以用自然语言指定从某个阶段继续，例如"ops-message-support 的 grill 已经做完了，继续"。harness 识别意图后，自动补做最小前置检查，然后从指定阶段继续。
|
||
|
||
## 首次加载
|
||
|
||
执行前只读取当前任务需要的 reference 文件：
|
||
|
||
- 需要执行阶段时，先读取 `references/phase-contracts.md`；如果当前阶段涉及接口影响分级、分档、启动规则、快速模式或完成标准，再补读 `references/operating-rules.md`。
|
||
- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。
|
||
- archive 阶段或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。
|
||
- 子 skill 无法直接调用时，读取 `references/fallbacks.md`。
|
||
|
||
## 内部阶段
|
||
|
||
9 个内部阶段，按执行顺序：
|
||
|
||
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 或能力来源声明，该阶段不得视为已完成。
|
||
|
||
## 快速模式
|
||
|
||
快速模式的具体约束见 `references/operating-rules.md`。
|
||
|
||
## 完成标准
|
||
|
||
流程完成标准见 `references/operating-rules.md`。
|