osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

redesign sm-flow v4.0 as protocol-layer harness

Browse Source 
- 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
This commit is contained in:
zhuyongxin
2026-05-25 17:28:15 +08:00
parent 1f01e30c4e
commit 71e0b7f801
9 changed files with 1170 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skill-workbench/docs/sm-flow/workflow.md
+209 -2
View File
@@ -1,4 +1,62 @@
# 增强版工作流总结
# SM-Flow 工作流
## 当前设计理念（v4 方向）
**核心定位**：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 + 归档确认） |
**内部阶段（9 个，英文动词命名）**：
```
clarify → context → propose → grill → specify → audit → commit → apply → archive
入口澄清 上下文 轻量提案 澄清 细化 审计 提交 执行 归档
```
阶段名是 harness 的内部协议词汇（用于 checkpoint 汇报和进度通知），不是用户 API。用户只需知道 4 个命令，其余通过自然语言交互，由 harness 识别意图后编排。
**关键设计决策**：
- **真理源分层**：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**：快速模式合并 gate（clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill 最少 1 个问题 → commit 简化检查），但保留最关键的门控。
- **质量约束可观测**：质量约束必须转化为可观测产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
**使用方式**：
详细的使用说明见 [使用方式.md](./使用方式.md)，包括：
- 4 个用户命令的典型场景
- 完整规划 → 执行 → 归档的分次调用示例
- 自然语言交互方式
- 规模分档（micro / standard / complex）
- devflow 自动维护机制
- OpenSpec 集成与 Draft/Committed 分离
- 常见问题解答
---
## 演进历史
以下是 sm-flow 工作流的历史演进记录，从 v1 到当前 v4 方向。每一版都从真实执行失败中提炼，不是理论推演。
## 旧工作流 vs 新工作流
@@ -583,8 +641,157 @@ references/operating-rules.md
- 修正 fallback 锚点，避免 skill 指向不存在的章节名
- 统一 `operating-rules.md` 的语言风格，避免在主协议是中文时夹着一整份英文运行规则
这轮修正说明一件事：协议产品化不只是“把规则写出来”，还要保证**入口、逐阶段契约、fallback 和运行规则之间的导航关系始终自洽**。
这轮修正说明一件事：协议产品化不只是”把规则写出来”，还要保证**入口、逐阶段契约、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） |