Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00
parent 0e0275d46a
commit f45122dafb
83 changed files with 9733 additions and 15 deletions
@@ -0,0 +1,270 @@
+# Explore / Essence / Follow 最新设计总结
+
+**版本基线**：v0.5.0  
+**对应 skill 本体**：`skill-workbench/generated-skills/skills/`  
+**历史来源**：
+
+- `skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md`
+- `skill-workbench/history/docs/superpowers/specs/`
+- `skill-workbench/history/docs/superpowers/changelog/`
+
+## 一句话定位
+
+`explore`、`essence`、`follow` 是一组学习型 skill family：
+
+- `explore` 负责项目级理解。
+- `essence` 负责深挖 1-2 个最值得迁移的核心设计。
+- `follow` 负责基于已有报告做交互式跟学。
+
+三者不是“深浅不同的同一个技能”，而是学习链路中的三个不同角色。
+
+## 设计背景
+
+早期 superpowers 设计试图覆盖完整学习过程，但在实践中出现了几个问题：
+
+1. 阶段过多，`explore` 同时承担项目理解、深度分析、教学输出，边界不清。
+2. `/essence` 曾被误设计成 `/explore` 的轻量版，导致无法稳定聚焦“值得偷走的设计”。
+3. `/follow` 曾倾向重新扫描项目，削弱了它“基于已有报告教学”的定位。
+4. HTML、Deep Fission、Verify 等输出阶段让 skill 变重，增加上下文和执行成本。
+5. 历史 docs 中存在过时 proposal、plan 和已删除技能引用，需要收敛为当前真实实现。
+
+v0.5.0 的核心改造是：**拆清职责，减少阶段，只保留能稳定触发、稳定产出的学习动作。**
+
+## 三技能职责边界
+
+| Skill | 核心问题 | 输入 | 输出 | 不做什么 |
+| --- | --- | --- | --- | --- |
+| `explore` | 这个项目是什么，为什么值得学，从哪里开始？ | 新项目、代码仓库、文档仓库、skill 仓库 | 项目学习报告、结构图、2-3 个核心设计概览 | 不做深度模式提取，不做互动教学 |
+| `essence` | 这个项目最值得偷走的设计是什么？ | 明确设计目标，或需要自动找 standout design | 设计模式卡、证据链、迁移示例 | 不做全项目概览，不做普通代码讲解 |
+| `follow` | 如何基于已有报告一步步学会？ | 已有 `/explore` 或 `/essence` 报告 | Runnable 或 Reader 跟学会话 | 不重新扫描项目，不替用户执行代码 |
+
+## 推荐学习链路
+
+```text
+第一次接触项目
+  ↓
+/explore
+  产出项目定位、结构、主流程、核心设计候选
+  ↓
+/essence
+  选择一个核心设计做深挖，提炼可迁移模式
+  ↓
+/follow
+  基于 explore/essence 报告做交互式学习
+```
+
+也可以单独使用：
+
+- 只想快速建立全局认知：只用 `explore`。
+- 已经知道要研究哪个设计：直接用 `essence` 的 User-directed 模式。
+- 已经有报告，想按教程学：直接用 `follow`。
+
+## Explore 最新设计
+
+### 定位
+
+`explore` 是项目地图绘制器。它回答：
+
+- 这个项目是什么？
+- 为什么值得研究？
+- 顶层结构如何组织？
+- 学习入口在哪里？
+- 有哪 2-3 个核心设计值得后续深挖？
+
+### 当前阶段
+
+v0.5.0 将原来的 5 Phase 收敛为 4 Phase：
+
+1. **Positioning & Structure**
+   - 合并早期 Positioning 和 Structure。
+   - 输出项目定位、学习价值、顶层结构、入口区域。
+2. **Flow**
+   - 仅代码仓库执行。
+   - 追踪主运行流或请求流，聚焦 golden path。
+3. **Start Path**
+   - 仅代码仓库且可运行/可观察时执行。
+   - 给出最小启动路径、第一条命令或第一处观察点。
+4. **Core Designs**
+   - 总结 2-3 个核心设计或核心想法。
+   - 保持概览深度，为 `essence` 提供候选对象。
+
+### 类型分流
+
+`explore` 必须先识别项目类型：
+
+- **Code repository**：执行完整 4 Phase。
+- **Skill / docs / knowledge repository**：跳过 Flow 和 Start Path，改用结构图、概念图或 workflow 图。
+- **Template / scaffold repository**：Flow 和 Start Path 可以保持轻量。
+
+### 关键约束
+
+- 不做 `/essence` 级别深挖。
+- 不做 `/follow` 式互动教学。
+- 不保留 Verify、Deep Fission、HTML Output 等已退休阶段。
+- 最终必须至少包含一个图：代码仓库用架构/流程图，非代码仓库用结构/想法/workflow 图。
+
+## Essence 最新设计
+
+### 定位
+
+`essence` 是“宝石检查器”。它不是 `/explore` 的轻量版，而是专门回答：
+
+> 这个项目里哪 1-2 个设计最值得迁移到我自己的工程里？
+
+### 模式
+
+| Mode | 触发场景 | 行为 |
+| --- | --- | --- |
+| User-directed | 用户已有目标，或来自 `/explore` 的核心设计候选 | 直接深挖用户指定设计 |
+| Auto-detect | 独立启动，用户希望 AI 自动找亮点 | 扫 README、docs、结构和信号，提出 1-2 个候选 |
+| Lens-guided | 用户指定 mechanical / intentional / evolution 视角 | 按透镜选择证据来源和输出框架 |
+
+### 透镜
+
+- **Mechanical**：它如何工作？读代码、接口、调用链。
+- **Intentional**：为什么这样设计？读设计文档、RFC、PR、权衡。
+- **Evolution**：它如何演化到这里？读 changelog、git 历史、迁移记录。
+
+### 当前阶段
+
+1. **Locate**
+   - 找到 1-2 个候选设计方向。
+   - 自动模式要求 standout design 至少满足 2 个信号。
+2. **Deep Dive**
+   - 最多读 10 个核心文件。
+   - 追踪调用链或证据链，避免扩散成全项目分析。
+3. **Extract Pattern**
+   - 提炼问题、模式、替代方案、权衡和证据。
+4. **Migrate**
+   - 给出可迁移方式和最小示例。
+   - 示例必须足够小，避免复制生产代码。
+5. **Self-review**
+   - 检查是否有证据、是否解释了权衡、是否能迁移。
+
+### 关键约束
+
+- “代码干净”不是 essence 信号。
+- 如果没有 standout design，应明确建议改用 `explore`。
+- 如果设计边界超过 10 个文件且无法收敛，应改用 `explore`。
+- HTML Card 只是显式请求时的可选输出，不是默认阶段。
+
+## Follow 最新设计
+
+### 定位
+
+`follow` 是跟学教练。它不做新分析，只基于已有 `/explore` 或 `/essence` 报告，带用户一步步学习。
+
+### 前置条件
+
+必须存在以下之一：
+
+- `/explore` 报告
+- `/essence` 报告
+
+如果没有，必须拒绝并引导用户先运行 `explore` 或 `essence`。
+
+### 模式
+
+| Mode | 来源 | 行为 |
+| --- | --- | --- |
+| Runnable | `/explore` 报告确认是可运行代码仓库 | 从环境、启动、观察和安全修改开始 |
+| Reader | 非代码仓库，或来自 `/essence`，或用户专注设计学习 | 围绕核心设计做分层阅读和推理练习 |
+
+### 当前流程
+
+**Runnable**：
+
+1. 确认环境和依赖。
+2. 让用户运行项目。
+3. 让用户做一个安全小改动。
+4. 一起走主流程。
+5. 给一个小练习。
+6. 回顾学习结果。
+
+**Reader**：
+
+1. 围绕设计或架构想法设定学习目标。
+2. 按“问题 → 方法 → 实现 → 权衡”讲解。
+3. 通过问题检查理解。
+4. 用图或结构总结连接文件和设计。
+5. 给一个迁移/推理练习。
+6. 回顾学习结果。
+
+### 关键约束
+
+- 不重新扫描项目。
+- 不执行命令或替用户写代码。
+- 不新增第三种模式。
+- 不只说“去读这个文件”，必须说明这个文件体现什么设计、为什么重要、看什么。
+
+## v0.5.0 最重要的收敛
+
+### 1. Explore 从 5 Phase 收敛到 4 Phase
+
+早期 Positioning 和 Structure 拆开导致报告啰嗦。v0.5.0 合并为 `Positioning & Structure`，让 `explore` 更像项目地图，而不是流水账。
+
+### 2. Essence 补齐上下文感知
+
+`essence` 会先判断是否已有 `/explore` 结果：
+
+- 有结果：默认 User-directed，让用户从候选设计中选择。
+- 无结果：默认 Auto-detect，自行寻找 standout design。
+
+这避免了 `essence` 在已有上下文时重复扫描。
+
+### 3. Follow 不再重扫
+
+`follow` 的核心价值是“基于报告教学”。如果它重新扫描项目，就会变成另一个 explore。v0.5.0 明确它必须读取前置报告，按报告决定 Runnable 或 Reader。
+
+### 4. Reader 模式从文件级提升到设计级
+
+早期 Reader 容易变成“带你读一个文件”。v0.5.0 改成围绕设计概念学习：问题、方法、实现、权衡。
+
+### 5. 删除过期阶段和死引用
+
+已退休内容包括：
+
+- Deep Fission
+- Verify 阶段
+- 默认 HTML Output
+- 旧 `/map`、`/fission` 等已不存在技能引用
+
+## 当前产物边界
+
+```text
+skill-workbench/
+├── generated-skills/
+│   └── skills/
+│       ├── explore/
+│       ├── essence/
+│       └── follow/
+├── docs/
+│   └── explore-essence-follow/
+│       └── latest-design.md
+└── history/
+    ├── changelog/
+    └── docs/superpowers/
+```
+
+- `generated-skills/skills/` 只放可安装 skill 本体。
+- `docs/explore-essence-follow/latest-design.md` 保存最新设计总结。
+- `history/` 保留旧设计、changelog、handoff 和过时 specs，作为考古来源。
+
+## 何时修改哪一层
+
+| 变更类型 | 修改位置 |
+| --- | --- |
+| skill 行为变更 | `skill-workbench/generated-skills/skills/{skill}/SKILL.md` |
+| 最新设计说明变更 | `skill-workbench/docs/explore-essence-follow/latest-design.md` |
+| 历史记录 | `skill-workbench/history/`，不要覆盖 |
+| 验证材料 | `skill-workbench/validation/` |
+
+## 当前结论
+
+这组三技能已经形成清晰分工：
+
+- `explore` 是入口：建立项目级地图。
+- `essence` 是深挖：提炼可迁移设计。
+- `follow` 是教学：基于报告引导用户学会。
+
+后续改进应避免把三者重新合并。最重要的维护原则是：**保持边界比增加功能更重要。**
@@ -0,0 +1,383 @@
+# 增强版工作流总结
+
+## 旧工作流 vs 新工作流
+
+```
+旧：                       新：
+Phase 1  手动整理PRD        Phase 0   手动初始PRD（入口，保留人的判断）
+Phase 2  openspec:explore   Phase 1    openspec:propose → research
+Phase 3  grill-me           Phase 1.5  to-prd → 结构化PRD（替代初始PRD）
+Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
+                            Phase 2.5  zoom-out → 架构审计
+                            Phase 3    openspec:apply → 执行
+                                       diagnose → bug排查
+                                       tdd → 质量闭环
+横切：                     横切：
+       无                            git-guardrails → 安全锁
+```
+
+关键变化：**手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"**——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。
+
+## 旧工作流的三个关键缺口
+
+1. **需求澄清后缺少可行性验证**
+   - 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现
+   - 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行"
+
+2. **openspec 产出不能沉淀到长期记忆**
+   - 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢
+   - 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文
+
+3. **apply 完成后缺少验证闭环**
+   - 旧：apply → 完成。功能对不对取决于人肉测试
+   - 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor）
+
+## 新增技能的投入产出
+
+| 技能 | 学多久 | 一次省多少 | 什么时候用 |
+|------|--------|-----------|-----------|
+| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 |
+| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 |
+| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 |
+| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 |
+| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 |
+| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 |
+
+## 为什么这套组合优于单纯依赖 openspec
+
+openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题：
+
+- **领域知识沉淀**：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐
+- **质量验证**：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环  
+- **流程安全**：openspec 不管 AI 误操作 → git-guardrails 补齐安全层
+
+一句话：**openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。**
+
+## v2.0：devflow/ 产物聚合层
+
+### 问题
+
+v1.0 一次完整流程的产物散落在 **5 个位置**：
+
+```
+CONTEXT.md                 ← Phase 2 (根目录)
+docs/adr/                  ← Phase 2 (docs/)
+docs/agents/               ← Phase 1.5 (docs/)
+openspec/changes/          ← Phase 1+3 (openspec/)
+knowledge/entries/         ← /knowledge-absorber
+```
+
+三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按**工具来源**组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按**项目本身**组织。
+
+### 借鉴 CodeStable 的单一聚合根设计
+
+CodeStable 的核心设计决策：所有产物集中在 `codestable/` 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。
+
+dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个**人类可读的档案层**：
+
+```
+devflow/                              ← 单一入口
+├── projects/YYYY-MM-DD-{slug}/       ← 一个 PRD→实现 闭环
+│   ├── {slug}-prd.md                 # Phase 0+1.5 需求文档
+│   ├── {slug}-research.md            # Phase 1 技术方案（从 openspec 提取）
+│   ├── {slug}-design.md              # Phase 1+2.5 设计 + 架构审计
+│   ├── {slug}-tasks.md               # Phase 1 任务清单（从 openspec 提取）
+│   ├── {slug}-acceptance.md          # Phase 3+4 验收报告
+│   └── adr/                          # Phase 2 架构决策
+├── glossary/
+│   └── CONTEXT.md                    # 跨项目领域词汇表
+├── compound/                         # 跨项目知识沉淀
+│   └── YYYY-MM-DD-{type}-{slug}.md   # type ∈ {learning, trick, decision, explore}
+└── reference/                        # 共享模板/规范
+```
+
+### 两层架构
+
+| | openspec/changes/ | devflow/projects/ |
+|------|-----------|-------------------|
+| 角色 | 工具工作区（WAL） | 人类档案层（Tables） |
+| 谁读 | 机器 | 人 |
+| 生命周期 | 活跃变更期 → Archive 后清空 | 永久保留 |
+| 组织方式 | 按变更名 | 按日期 + 项目 |
+
+**关键**：openspec archive 后 `openspec/changes/` 清空，但 `devflow/projects/` 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。
+
+### 各 Phase 产物路径变化
+
+| Phase | v1.0 | v2.0 |
+|-------|------|------|
+| 1.5 PRD | `docs/agents/<name>-prd.md` | `devflow/projects/{date}-{slug}/{slug}-prd.md` |
+| 2 CONTEXT | 根目录 `CONTEXT.md` | `devflow/glossary/CONTEXT.md` |
+| 2 ADR | `docs/adr/` | `devflow/projects/{slug}/adr/` |
+| 2.5 架构审计 | 对话中，丢失 | `devflow/projects/{slug}/{slug}-design.md` |
+| 4 验收 | `docs/agents/lessons/` | `devflow/projects/{slug}/{slug}-acceptance.md` |
+| 4 经验沉淀 | 无 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
+| 4 从 openspec 提取 | 无 | 提炼到 `{slug}-research.md` + `{slug}-tasks.md` |
+
+## 一键启动
+
+已固化为 skill：**`/dev-flow`**
+
+```
+/dev-flow                     # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程
+/dev-flow --prd docs/my-idea.md  # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1
+/dev-flow --from phase2       # 已有 research，从 grill 开始
+/dev-flow --from apply        # 已有 PRD + 文档，直接执行
+/dev-flow --quick             # 小需求，跳 PRD 精化 + zoom-out
+```
+
+Skill 位置：`.claude/skills/dev-flow/SKILL.md`
+
+## Skill 评估结论（2026-05-19）
+
+详细评估报告见：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`。
+
+### 总体判断
+
+`dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。
+
+最有价值的设计是 `devflow/` 产物聚合层：
+
+- `openspec/changes/` 负责机器可执行的变更工作区。
+- `devflow/projects/` 负责人类可回溯的项目档案。
+- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。
+- `devflow/compound/` 负责沉淀可复用工程知识。
+
+评估中发现的核心问题是：早期 `SKILL.md` 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。
+
+### 已确认的亮点
+
+1. **产物聚合层设计清晰**
+   - `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。
+   - 工具工作区和人类档案层分离，职责边界明确。
+
+2. **阶段顺序合理**
+   - Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。
+
+3. **Phase 4 很有价值**
+   - 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
+   - 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。
+
+4. **文档化追问方向正确**
+   - Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。
+   - 这符合“边澄清边沉淀”的工作方式。
+
+5. **质量闭环意识强**
+   - Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
+   - TDD 被设计为可选增强，避免对所有任务强制套用重流程。
+
+### 主要改进点
+
+| 问题 | 改进方向 |
+| --- | --- |
+| 触发描述不够完整 | 明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景 |
+| Claude 工具耦合较强 | 保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback |
+| 依赖安装状态写死 | 改为启动时检查 required / optional / fallback |
+| 子 skill 调用方式不稳 | 优先调用子 skill；不可调用时读取对应 `SKILL.md`；不存在时执行最小协议 |
+| 缺少初始化算法 | 明确 `devflow/` 目录骨架、slug 生成、重名处理和旧 `CONTEXT.md` 迁移规则 |
+| 缺少模板 | 拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板 |
+| quick 模式与约束冲突 | quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档 |
+| Phase 退出条件不足 | 为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径 |
+
+### 产品化方向
+
+评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”：
+
+- `SKILL.md` 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。
+- `references/` 承载长内容：Phase 契约、模板、归档规则、fallback 协议。
+- 每个 Phase 都要有明确的进入条件和退出条件。
+- quick 模式、fallback、归档确认、人类检查点必须写成硬规则。
+- `devflow/` 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。
+
+### 后续演进：sm-flow 产品化
+
+基于这次评估，`dev-flow` 的设计被重构为 `.agents/skills/sm-flow/`。这一步仍属于 **v2 产品化**：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。
+
+```
+.agents/skills/sm-flow/
+├── SKILL.md                         # 短执行协议
+└── references/
+    ├── phase-contracts.md           # Phase 输入/动作/输出/退出条件
+    ├── templates.md                 # PRD/ADR/验收等模板
+    ├── archive-rules.md             # 从 openspec 提取到 devflow 的规则
+    └── fallbacks.md                 # 子 skill 不可用时的最小协议
+```
+
+v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 `devflow/` 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。
+
+## v3.0：OpenSpec-first / Devflow-assisted
+
+### 背景
+
+v2 跑通后暴露出一个更深的问题：`devflow/` 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。
+
+这会导致两套“执行依据”并存：
+
+```
+devflow/projects/{slug}/...     # 人类档案层，也包含 PRD/design/tasks
+openspec/changes/{change}/...    # 工具工作区，也包含 proposal/design/specs/tasks
+```
+
+如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。
+
+### v3 的核心判断
+
+v3 不重新设计一套替代 openspec 的工作流，而是明确：
+
+> **devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。**
+
+职责分层变为：
+
+| 层 | 角色 | 负责回答 |
+| --- | --- | --- |
+| `devflow/` | 上下文真理源 / 长期记忆 | 为什么这样做？术语是什么？历史决策是什么？之前怎么验收？ |
+| `openspec/changes/` | 执行真理源 / 当前变更规格 | 这次到底改什么？验收标准是什么？任务是否完成？ |
+| code | 实现结果 | OpenSpec apply 后实际落地的代码 |
+
+### v2 vs v3
+
+| 维度 | v2：devflow 聚合层 | v3：OpenSpec-first / Devflow-assisted |
+| --- | --- | --- |
+| 核心目标 | 防止 openspec archive 后上下文丢失 | 防止 devflow 与 openspec 成为并列执行源 |
+| devflow 角色 | 人类可读档案层 | 上下文增强层 + 归档层 |
+| openspec 角色 | 工具工作区 | 当前变更的唯一默认执行真理源 |
+| Phase 1 | openspec propose 产出 research | 基于 devflow 上下文生成/修正 OpenSpec 产物 |
+| Phase 2 | grill-with-docs 更新 glossary/ADR | human-in-the-loop 澄清后必须回写 OpenSpec |
+| Phase 2.5 | zoom-out 产出架构审计 | 架构审计若影响实现，必须回写 OpenSpec design/tasks |
+| Phase 3 | openspec apply + diagnose/tdd | 默认只能依赖 OpenSpec apply；devflow 只作参考上下文 |
+| Phase 4 | 从 openspec 提炼到 devflow | 轻量回填 devflow 必要档案，避免重复 OpenSpec |
+
+### v3.1：Devflow 产物瘦身
+
+v3 继续跑完整流程后，又暴露出一个实践问题：`devflow` 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。
+
+因此 v3.1 明确：**devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。**
+
+默认必要产物收敛为：
+
+```text
+devflow/projects/YYYY-MM-DD-{slug}/
+├── brief.md        # 背景、目标、范围、非目标、关联 OpenSpec
+├── evidence.md     # 代码/文档证据、evidence-driven 结论和汇报状态
+├── decisions.md    # user-interview 确认、关键取舍、OpenSpec 回写记录
+└── acceptance.md   # 实现结果、验证、未验证项、archive 状态
+```
+
+扩展产物只在有明确理由时创建：
+
+- `prd.md`：复杂需求、对外协作或用户明确要求。
+- `research.md`：真实调研、代码考古、竞品/API 对比或复杂方案比较。
+- `design.md`：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。
+- `tasks.md`：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
+- `alignment.md` / `clarifications.md`：冲突或澄清问题很多时拆出；否则并入 `decisions.md`。
+
+规模分档：
+
+| 分档 | 适用场景 | devflow 默认产物 |
+| --- | --- | --- |
+| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md` |
+| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` |
+| `complex` | 高风险、跨模块、需求不清、多人协作 | standard + 按需 PRD/research/design/tasks/alignment |
+
+### v3 新增 Phase 0.5
+
+v3 在 Phase 0 和 Phase 1 之间增加：
+
+```
+Phase 0.5  Devflow Context Harvest
+```
+
+读取：
+
+- `devflow/glossary/CONTEXT.md`
+- 相关项目 PRD/design/tasks/acceptance
+- 相关 ADR
+- `devflow/compound/` 中的 learning、trick、decision、explore
+
+目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。
+
+
+### v3 中各 skill 的参与方式
+
+这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”：
+
+| 阶段 | 主要 skill / 工具 | 作用 | 产物去向 |
+| --- | --- | --- | --- |
+| Phase 0 初始需求 / PRD / research | `sm-flow` | 收集原始需求、已有 PRD 或 research，判断启动模式 | 入口摘要、初步 slug |
+| Phase 0.5 Devflow Context Harvest | `sm-flow` | 读取 `devflow/` 的 glossary、ADR、历史 PRD、acceptance、compound knowledge | 作为 Phase 1 的 OpenSpec 输入上下文 |
+| Phase 1 OpenSpec propose | `openspec-propose` | 生成或修正 `proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md` | `openspec/changes/<change>/` |
+| Phase 1.5 PRD / OpenSpec 对齐 | `to-prd` + `sm-flow` | 检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD | `brief.md` / 按需 `prd.md`；冲突回写 OpenSpec |
+| Phase 2 Human-in-the-loop 澄清 | `grill-with-docs` | 追问术语、边界、验收；区分 `evidence-driven` 和 `user-interview` | `evidence.md` / `decisions.md`；影响实现的结论回写 OpenSpec |
+| Phase 2.5 架构审计 | `zoom-out` | 拉高视角审查模块、数据流、耦合、架构风险 | 默认写入 decisions/evidence；复杂审计才拆 `design.md`；影响实现则回写 OpenSpec |
+| Phase 3 OpenSpec apply | `openspec-apply-change` | 按 OpenSpec specs/tasks 执行实现 | 代码变更、OpenSpec task 状态 |
+| Phase 3 bug/不确定行为 | `diagnose` | 复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归 | 根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance |
+| Phase 3 高风险/复杂行为 | `tdd` | 按 OpenSpec specs 做纵向切片测试驱动 | 测试与实现代码 |
+| Phase 4 回填 devflow | `sm-flow` + `openspec-archive-change` | 从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive | `devflow/projects/`、`devflow/compound/`；用户确认后 archive |
+
+说明：`grill-me` 在 v3 中不再作为主要入口，已被 `grill-with-docs` 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。
+
+### v3 的执行规则
+
+1. **OpenSpec 是执行真理源**
+   - Phase 3 默认必须依赖 `openspec/changes/<change>/proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md`。
+   - 不允许直接基于 `devflow/projects/...` 绕过 OpenSpec 写代码。
+
+2. **Devflow 是上下文真理源**
+   - 术语、历史决策、项目背景、踩坑记录来自 `devflow/`。
+   - 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。
+
+3. **冲突先修 OpenSpec**
+   - 如果 devflow 和 OpenSpec 冲突，不能直接执行。
+   - 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。
+
+4. **evidence-driven 也必须汇报**
+   - 证据驱动不是“AI 自己确认完就继续”。
+   - 代理必须汇报查了什么、得出什么结论、是否需要用户确认。
+
+5. **user-interview 必须等待确认**
+   - 涉及范围、偏好、验收口径、风险接受度时，必须问用户。
+
+6. **归档仍回到 devflow**
+   - OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。
+   - Phase 4 询问是否 archive OpenSpec change，不默认执行。
+
+7. **devflow 产物按需生成**
+   - 默认只生成 brief、evidence、decisions、acceptance。
+   - PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。
+   - 小需求走 `micro`，不能让文档成本超过实现成本。
+
+### v3 流程图
+
+```
+Phase 0    初始需求 / PRD / research
+           skill: sm-flow
+   ↓
+Phase 0.5  读取 devflow 上下文
+           skill: sm-flow
+   ↓
+Phase 1    生成或修正 OpenSpec proposal/design/specs/tasks
+           skill: openspec-propose
+   ↓
+Phase 1.5  PRD / Devflow / OpenSpec 对齐检查
+           skill: to-prd + sm-flow
+   ↓
+Phase 2    human-in-the-loop 澄清，并回写 OpenSpec
+           skill: grill-with-docs
+   ↓
+Phase 2.5  架构审计；影响实现则回写 OpenSpec
+           skill: zoom-out
+   ↓
+Phase 3    OpenSpec apply 执行
+           skill: openspec-apply-change；按需 diagnose / tdd
+   ↓
+Phase 4    回填 devflow，并确认是否 archive
+           skill: sm-flow；用户确认后 openspec-archive-change
+```
+
+### v3 一句话定位
+
+`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。
+
+
+
+