跳转到主要内容
Design phase 是 OpenSpec hand off 给 Superpowers 的地方。在你于 Phase 1 确认 change structure 后，/comet-design 会从 Phase 1 artifacts 生成 handoff package，并加载 Superpowers brainstorming skill 来进行深度技术探索，梳理 implementation approaches、risks、trade-offs 和 testing strategy。只有在你明确批准 design proposal 后，它才会写入最终 Design Doc 并推进 workflow。

​
Trigger

直接运行 /comet-design，或在 Phase 1 完成后让 /comet 自动分发。

​
Owner

OpenSpec and Superpowers — OpenSpec 从 Phase 1 artifacts 生成 handoff package；Superpowers brainstorming 驱动技术探索并产出 Design Doc。
Brainstorming 不能跳过。 对于 full-workflow changes，Superpowers brainstorming skill 是强制性的，不能用快速摘要或普通对话替代。唯一例外是 hotfix 和 tweak presets，它们会完全绕过 Phase 2 并直接进入 build。如果 brainstorming skill 不可用，workflow 会停止并提示你安装或启用 Superpowers skills。

​
会发生什么

1

生成 OpenSpec → Superpowers handoff package

在 brainstorming 开始前，comet-handoff.sh 会从 Phase 1 artifacts 生成 deterministic context package。这会产出两个文件，并把它们的路径和 SHA256 hash 写入 .comet.yaml：
  • design-context.json — machine-readable index（change、phase、canonical spec、source paths、hash）
  • design-context.md — Superpowers 在 brainstorming 期间读取的 human-readable context，包含 source path markers、line ranges 和 SHA256 traceability
Handoff 由脚本生成，AI 不能手动写入。这确保 Superpowers 收到的是 OpenSpec 实际内容的、已验证且可追踪的 snapshot。
2

Brainstorming 探索技术问题

AI 会以 handoff package 作为 context 加载 Superpowers brainstorming skill，并开始深度技术探索：
  • Implementation approach：architecture、data flow、key technology choices
  • 每个 option 的 trade-offs 和 risks
  • Testing strategy
  • OpenSpec delta spec 中缺失的任何 acceptance scenarios（作为 Spec Patches 提出，而不是重写 requirements）
Brainstorming 是对话式的。AI 会提出 proposals 并与你迭代。此阶段 尚不会写入 Design Doc file。
3

你确认 design proposal（blocking pause）

Brainstorming 产出 design proposal 后，AI 会暂停并展示简明摘要：
  • 采用的 technical approach
  • 关键 trade-offs 和 risks
  • Testing strategy
  • 需要写回的任何 delta spec changes
在你明确确认前，workflow 不能推进。 如果你要求调整，brainstorming 会继续，直到你确认。
4

写入 Design Doc

你确认后，AI 会在 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 创建 Design Doc。该文件的 frontmatter 设计上保持最小：
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---
这会将 Design Doc 链接回 OpenSpec change，而不会重复 requirements。
5

创建或更新 Delta spec

如果 brainstorming 发现缺失的 acceptance scenarios 或 new capabilities，位于 openspec/changes/<name>/specs/<capability>/spec.md 的 OpenSpec delta spec 会通过 Spec Patches 创建或更新。Handoff hash 会重新生成，以反映更新后的 artifacts。
6

更新 state，并由 guard 推进 workflow

design_doc path 会记录到 .comet.yaml。如果发生 delta spec changes，handoff package 会重新生成以保持 hash 最新。随后 phase guard 会验证所有 exit conditions，包括 handoff_hash 是否匹配当前 artifacts，以及 design-context.md 是否包含脚本生成的 traceability markers，然后自动 transition 到 phase: build。

​
Artifacts

ArtifactPath说明
Design Docdocs/superpowers/specs/YYYY-MM-DD-<topic>-design.mdTechnical RFC：implementation approach、trade-offs、testing strategy
Delta specopenspec/changes/<name>/specs/<capability>/spec.md此 change 的 acceptance scenarios 和 capability spec
Handoff context (JSON)openspec/changes/<name>/.comet/handoff/design-context.json带 SHA256 hash 的 machine-readable handoff index
Handoff context (Markdown)openspec/changes/<name>/.comet/handoff/design-context.md带 source path 和 traceability markers 的 human-readable handoff context

​
The Handoff Package

comet-handoff.sh 用来解决一个具体问题：AI agents 即时总结 context 时，会产生不一致且不可追踪的输出。Comet 通过从实际文件内容 deterministic 生成 handoff，并包含 SHA256 hashes、source path markers 和 line ranges，确保 Superpowers 始终基于 OpenSpec 实际内容的已验证 snapshot 工作。 默认 package 是紧凑且可追踪的 excerpt。如果确实需要所有 source artifacts 的完整内容，可以显式生成 full handoff： 
"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
在 workflow 从 design 推进到 build 前，phase guard 会检查 .comet.yaml 中存储的 handoff_hash。如果 hash 与当前 OpenSpec artifacts 不匹配，guard 会阻止 transition 并报告 mismatch。

​
Context Compaction Recovery

Design phase 可能会在 brainstorming 期间触发 context compaction。如果发生这种情况，运行 recovery command，获取已完成内容和下一步所需操作的结构化摘要： 
"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
该脚本会输出当前 phase、哪些 fields 已完成、哪些仍 pending，以及推荐的 recovery action。按照 recovery action 从正确步骤恢复。