Update sm-flow workflow docs

This commit is contained in:
aruo
2026-07-06 09:15:51 +08:00
parent 6ccfd33ec5
commit 3e5c6a159c
20 changed files with 1645 additions and 61 deletions
@@ -0,0 +1,49 @@
# 内置执行协议
本文件只在外部 OpenSpec CLI 或子 skill 不可用时使用。fallback 不是跳过阶段,而是由 sm-flow 用文件方式完成同等最小产物。每次使用 fallback 都必须写入 `decisions.md` 或 `acceptance.md`,说明能力来源、缺失能力、影响和剩余风险。
## 通用规则
- 优先使用外部能力;只有不可用、不可发现或无法在当前环境调用时才使用内置协议。
- 不得因为使用 fallback 跳过 context、grill、commit、apply 授权或 archive 确认。
- fallback 产物仍写入 `openspec/changes/{slug}/` 和 `devflow/projects/YYYY-MM-DD-{slug}/`。
- 如果内置协议也无法满足阶段退出条件,暂停并向用户说明阻塞项。
## grill 内置协议
- 建立 question pool,至少覆盖术语、边界、验收;涉及参考实现或项目基础设施时加入技术实现问题。
- 将问题标记为 `evidence-driven` 或 `user-interview`。
- 先查证 evidence-driven 问题并汇报结论,再逐个询问 user-interview 问题。
- 按 `references/scales.md` 的当前分档满足 grill 要求。
- 将 question pool、证据结论、用户原话和确认状态写入 `decisions.md`;影响实现的结论回写 `proposal.md`。
## openspec 提案内置协议
- 在 `openspec/changes/{slug}/` 创建或更新:
- `proposal.md`:问题、方案、范围、非目标、上下文约束、风险。
- 设计产物:实现设计、接口影响、关键决策、架构风险;形式按 `references/scales.md` 的当前分档要求执行。
- `specs/*/spec.md` 或等价 functional spec:描述用户可观察行为和验收场景。
- `tasks.md`:按可执行切片拆分任务,并给每项写可验证验收标准。
- 运行 cross-artifact 对齐检查:proposal → 设计产物 → specs → tasks。
- 如果发现 gap,先修正 OpenSpec,再进入 commit。
## audit 内置协议
- 用 5 句话以内说明模块链路、数据所有权、跨模块依赖、架构风险和是否需要回写 OpenSpec。
- 如果风险影响实现,修正设计产物或 `tasks.md`。
- 将结论写入 `decisions.md`。
## openspec apply 内置协议
- 只依据 Committed OpenSpec 的 specs/tasks 实现;devflow 只作上下文参考。
- 开始前检查 `.committed` 文件;缺失则返回 commit。
- 如触发 pre-apply checkpoint,先阅读参考实现、grep 项目基础设施模式,并把技术栈清单写入 `decisions.md`。
- 按 tasks 的纵向切片实现、验证并更新任务状态。
- 发现冲突时按三类处理:OpenSpec 不准则修 OpenSpec,代码偏离则修代码,不确定则暂停等用户确认。
## openspec archive 内置协议
- 不删除或移动 OpenSpec change;只标记归档准备状态。
- 完成 devflow 回填、更新 `devflow/index.md`、创建 `.archive-ready`。
- 向用户汇报已创建文件、验证分类、剩余风险,并询问是否需要真实 OpenSpec archive。
- 如果外部 archive 能力仍不可用,在 `acceptance.md` 标记 `accepted-unarchived`。