Reorganize workspace and archive skill artifacts
This commit is contained in:
zhuyongxin
@@ -0,0 +1,199 @@
|
||||
# 阶段契约
|
||||
|
||||
本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。
|
||||
|
||||
## Phase 0 — 入口澄清
|
||||
|
||||
**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。
|
||||
|
||||
**动作**：
|
||||
- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。
|
||||
- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。
|
||||
- 如果输入过于模糊，最多追加三轮聚焦问题。
|
||||
- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。
|
||||
|
||||
**退出条件**：
|
||||
- 问题可以用 1-2 句话说清楚。
|
||||
- 期望结果可以用 1-2 句话说清楚。
|
||||
- 已列出已知影响代码或模块；如果未知，也明确标记。
|
||||
- 可以生成 OpenSpec change slug。
|
||||
|
||||
**输出**：
|
||||
- 入口摘要。
|
||||
- 初步 slug。
|
||||
- devflow 规模分档：`micro` / `standard` / `complex`。
|
||||
|
||||
## Phase 0.5 — Devflow 上下文收集
|
||||
|
||||
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
|
||||
|
||||
**动作**：
|
||||
- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
|
||||
- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
|
||||
- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
|
||||
- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。
|
||||
- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。
|
||||
|
||||
**退出条件**：
|
||||
- 已形成“OpenSpec 输入上下文摘要”。
|
||||
- 已列出相关 ADR 和不能违反的历史决策。
|
||||
- 已列出需要写入或修正 OpenSpec 的上下文点。
|
||||
|
||||
**输出**：
|
||||
- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。
|
||||
|
||||
## Phase 1 — OpenSpec propose
|
||||
|
||||
**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
|
||||
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-propose`。
|
||||
- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。
|
||||
- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec：
|
||||
- proposal 写清为什么做、做什么、范围和非目标。
|
||||
- design 写入上下文约束、历史 ADR、关键技术决策。
|
||||
- specs 写成可验收的外部行为。
|
||||
- tasks 写成可执行的纵向切片。
|
||||
- 在承诺设计细节前，先检查相关仓库代码。
|
||||
|
||||
**退出条件**：
|
||||
- `openspec/changes/<slug>/proposal.md` 存在。
|
||||
- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。
|
||||
- 关键假设已显式记录在 OpenSpec 或 research 中。
|
||||
|
||||
**输出**：
|
||||
- OpenSpec proposal、design、specs 和 task list。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
|
||||
- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 1.5 — PRD / OpenSpec 对齐
|
||||
|
||||
**进入条件**：Phase 1 已有 OpenSpec 产物。
|
||||
|
||||
**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。
|
||||
|
||||
**动作**：
|
||||
- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。
|
||||
- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。
|
||||
- 检查 PRD、devflow 上下文和 OpenSpec 是否一致：
|
||||
- OpenSpec 是否覆盖 PRD 的用户故事和验收预期。
|
||||
- OpenSpec 是否使用 glossary 中的正确术语。
|
||||
- OpenSpec 是否遵守相关 ADR。
|
||||
- specs 是否能表达可观察行为。
|
||||
- tasks 是否能驱动实现，而不是泛泛描述。
|
||||
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
|
||||
|
||||
**退出条件**：
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
- `brief.md`，以及按需创建的 `prd.md`。
|
||||
- OpenSpec 对齐检查记录。
|
||||
- 必要的 OpenSpec 修正。
|
||||
|
||||
## Phase 2 — Human-in-the-loop 澄清
|
||||
|
||||
**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。
|
||||
|
||||
**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。
|
||||
|
||||
**动作**：
|
||||
- 优先使用 `grill-with-docs`。
|
||||
- 先声明本阶段采用的澄清模式，并逐项标记：
|
||||
- `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
|
||||
- 至少覆盖三个维度：术语、边界、验收。
|
||||
- 一次只问一个 `user-interview` 问题。
|
||||
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
|
||||
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
|
||||
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
|
||||
|
||||
**退出条件**：
|
||||
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
|
||||
- 所有 evidence-driven 结论已向用户汇报。
|
||||
- 所有 user-interview 决策已获得用户确认。
|
||||
- 影响实现的结论已回写 OpenSpec。
|
||||
|
||||
**输出**：
|
||||
- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。
|
||||
- 更新后的 OpenSpec。
|
||||
- 更新后的词汇表和 ADR。
|
||||
|
||||
## Phase 2.5 — 架构审计
|
||||
|
||||
**进入条件**：Phase 2 已解决主要产品、领域和验收问题。
|
||||
|
||||
**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。
|
||||
|
||||
**动作**：
|
||||
- 画出输入 → 处理 → 输出的模块链路。
|
||||
- 识别跨模块依赖、数据所有权、生命周期和耦合风险。
|
||||
- 检查是否与既有架构、ADR、OpenSpec design 冲突。
|
||||
- 用不超过五句话写出架构风险评估。
|
||||
- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。
|
||||
|
||||
**退出条件**：
|
||||
- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。
|
||||
- OpenSpec design/tasks 已反映会影响实现的架构审计结论。
|
||||
|
||||
**输出**：
|
||||
- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。
|
||||
- 必要的 OpenSpec design/tasks 修正。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
|
||||
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
|
||||
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-apply-change`。
|
||||
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
|
||||
- 按 OpenSpec tasks 的纵向切片实现。
|
||||
- 当用户要求、行为复杂或回归风险高时使用 TDD。
|
||||
- 当测试失败、行为意外或原因不确定时使用 diagnose。
|
||||
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
|
||||
- 修改文件前遵守仓库指令，例如 `AGENTS.md`。
|
||||
|
||||
**退出条件**：
|
||||
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
|
||||
- 已运行验证，或记录了未验证原因。
|
||||
- 已列出已知限制。
|
||||
|
||||
**输出**：
|
||||
- 代码变更、必要测试和实现说明。
|
||||
- 更新后的 OpenSpec task 状态。
|
||||
|
||||
## Phase 4 — 回填 Devflow
|
||||
|
||||
**进入条件**：实现或规划工作已经达到可交接状态。
|
||||
|
||||
**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。
|
||||
|
||||
**动作**：
|
||||
- 遵循 `references/archive-rules.md`。
|
||||
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
|
||||
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
|
||||
- 如果本次流程产生可复用经验，写入 compound knowledge。
|
||||
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
|
||||
|
||||
**退出条件**：
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
|
||||
- 用户已被询问是否 archive OpenSpec change。
|
||||
|
||||
**输出**：
|
||||
- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。
|
||||
|
||||
Reference in New Issue
Block a user