design-handoff

设计 + 交接流程（发起会话用）

把「想清楚 → 写下来 → 交给下一个会话」固化为三份产物：spec（决策层）、plan（文件级执行）、HANDOFF（新会话入口）。目录不存在就先建（mkdir -p）。

第 0 步：调研与验证（最重要，别跳过）

1. 读项目索引与相关代码（若项目维护了 .local/docs/INDEX.md 或根目录 AGENTS.md / CLAUDE.md，先读它们）。
2. 验证而非猜测：凡涉及 SDK/API/外部依赖行为的关键论断（函数签名、覆盖语义、默认值、扫描范围），必须读 node_modules / 依赖包里的源码或 .d.ts，或官方文档落实，并记录出处（文件:行）。
3. 已有的 UI/基础设施要先盘点——很多时候「半边已经完工」（比如渲染层已有对应组件/解析逻辑），设计只需补缺的那半。
4. 方案对比要有结论：列对比表，说明为什么否掉备选（如「子进程方案在打包态不可用」），不要只列可能性。

第 1 步：写 spec — .local/docs/design/spec/<主题>.md

决策层文档，回答「为什么这么做」，不含文件级任务拆分。结构惯例：

• 背景与现状盘点（已有什么、缺什么、为什么现成方案不可用）
• 目标 / 非目标（非目标写清本期边界，防实施会话膨胀范围）
• 核心决策（对比表 + 一句话机制）
• 架构与代码位置（目录结构、改动点归属哪个模块/包）
• 契约（参数 schema、跨模块/跨进程类型、数据形状——精确到字段）
• 安全清单（输入校验、权限、数据隔离等，按项目情况）
• 里程碑（P1/P2 分期）
• 风险与已验证事实：第 0 步验证的结论逐条列出处；验证不了的标为「待验证」，交给 plan 阶段 0

第 2 步：写 plan — .local/docs/design/plan/<主题>-plan.md

执行层文档，给实施会话照着做。结构惯例：

• 阶段 0 冒烟验证：把 spec 里每个「待验证」变成一个可执行断言脚本（最小可运行脚本 + 明确通过标准）；卡点处理规则写死：失败回 channel 留言，不许绕过（后续决策依赖这些事实）
• 后续阶段按文件拆任务：每个任务写清新建/修改哪个文件、做什么、配什么测试
• 验收清单：项目自带的 lint / typecheck / test 全绿 + 逐项手测步骤 + 收尾纪律（关闭测试过程中起的服务/进程、更新项目索引）
• 「明确不做」清单（与 spec 非目标呼应）
• 引用 spec 而非重复其内容

第 3 步：建沟通频道 — .local/agent-work/channel/<主题>/HANDOFF.md

新会话的唯一入口，自包含、不依赖本次聊天记录。必含：

1. 任务一句话 + 完成定义（= plan 验收清单全过 + 用户 review 通过）
2. 必读文档顺序：HANDOFF → spec → plan → AGENTS.md + 项目索引（如有）
3. 关键约束：项目通用纪律（以仓库根 AGENTS.md / CLAUDE.md 约定为准，如数据隔离、零破坏性变更、代码风格等）+ 本任务特有的硬约束（如递归防护、目录隔离）
4. 已验证事实表（事实 | 出处）——实施会话直接采信，禁止重复考证
5. 待决策点：实施中遇到二选一时自行决策并记录进 IMPL-NOTES
6. 沟通协议（见下）

沟通协议（写进 HANDOFF，跨会话只认文件不认聊天）

• 实施会话：进度/卡点/决策追加写 IMPL-NOTES.md（倒序、每条带日期时间、标注阶段）；完成后写 DONE.md（验收清单逐项打勾 + 改动文件清单 + 自测记录）
• review 方：意见追加写 REVIEW.md；实施会话开工前先读它（存在的话）
• spec/plan 与代码现状冲突 → 停下来在 channel 留言，不要自由发挥

第 4 步：收尾

不要把 spec/plan 文件写进项目索引（如 .local/docs/INDEX.md）——用户会不定期清理过时的 spec/plan，不一定记得同步索引，所以索引只标目录（design/spec/、design/plan/、channel/），不标单个文件。HANDOFF.md 里有完整路径，可发现性靠频道目录本身。

回复用户：交付物清单 + 关键决策摘要 + 「新会话从 channel 的 HANDOFF.md 进」。