comet-design - SKILL.md Agent Skill

name: comet-design description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"

Comet 阶段 2：深度设计（Design）

前置条件

活跃 change 已存在（proposal.md、design.md、tasks.md）
无 Design Doc（docs/superpowers/specs/ 下无对应文件）

步骤

0. 入口状态验证（Entry Check）

执行入口验证：

COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
if [ -z "$COMET_ENV" ]; then
  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
  return 1
fi
. "$COMET_ENV"
bash "$COMET_STATE" check <name> design

验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。

幂等性：所有 design 阶段操作可以安全重试。如果 handoff_context 和 handoff_hash 已存在，先确认它们与当前产物一致再决定是否重新生成。

1a. 生成 OpenSpec → Superpowers 交接包

必须由脚本生成，不允许 agent 临场手写 summary 代替。

bash "$COMET_HANDOFF" <change-name> design --write

脚本会生成并记录：

openspec/changes/<name>/.comet/handoff/design-context.json
openspec/changes/<name>/.comet/handoff/design-context.md

并在 .comet.yaml 写入：

handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256>

默认交接包是 compact 可追溯摘录，不是 agent summary：

design-context.json：机器索引，包含 change、phase、canonical spec、source paths、hash
design-context.md：供 Superpowers 阅读的上下文，包含脚本标记、source path、line range、sha256、确定性摘录
超出摘录预算时标记 [TRUNCATED]，并保留 Full source 路径

如确实需要全文上下文，可显式运行：

bash "$COMET_HANDOFF" <change-name> design --write --full

交接包来源来自 OpenSpec open 阶段产物：

proposal.md：目标、动机、范围、非目标
design.md：高层架构决策、方案约束
tasks.md：初始任务边界
specs/*/spec.md：delta 能力规格

1b. 执行 Brainstorming（带上下文）

立即执行： 使用 Skill 工具加载 superpowers:brainstorming 技能，ARGUMENTS 包含：

Change: <change-name>
OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json

OpenSpec 产物是上游事实源，不要重新定义需求，不要重写 proposal/spec。
你的任务是基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
如发现 OpenSpec delta spec 缺少验收场景，只能提出 Spec Patch，并回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。

Design Doc frontmatter 必须最小化，只包含：
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---

跳过重复上下文探索，直接进入设计提问。

禁止跳过此步骤，禁止在未加载该技能的情况下继续。

如 superpowers:brainstorming 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。

技能加载后，按其指引产出设计方案（以对话形式呈现）：

技术方案：架构、数据流、关键技术选型与风险
测试策略
如需补充验收场景，标明将回写的 delta spec 变更

brainstorming 阶段不写入 Design Doc 文件，仅产出设计方案供 Step 1c 用户确认。确认后才创建 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并回写 delta spec。

1c. 用户确认设计方案（阻塞点）

brainstorming 产出设计方案后，必须使用 AskUserQuestion 工具暂停并等待用户明确确认设计方案。不得在用户确认前创建最终 Design Doc、写入 design_doc、运行 design guard，或进入 /comet-build。也不得仅输出文字提示后继续执行。

暂停时只展示必要摘要：

采用的技术方案
关键取舍与风险
测试策略
如有 Spec Patch，列出将回写的 delta spec 变更

用户明确确认后，才继续 Step 2。若用户要求调整，继续 brainstorming 迭代，直到用户确认。

2. 更新 Comet 状态

先记录 design_doc 路径。如果 Step 1c 回写了 delta spec（新增或修改了 specs/*/spec.md），必须重新生成 handoff 以更新 hash：

# 记录 design_doc 路径
bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md

# 如有 delta spec 变更，重新生成 handoff（更新 hash）
bash "$COMET_HANDOFF" <change-name> design --write

# 自动流转到下一阶段
bash "$COMET_GUARD" <change-name> design --apply

如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。

退出条件

Design Doc 已创建并保存
Design Doc frontmatter 包含 comet_change、role: technical-design、canonical_spec: openspec
handoff_context 和 handoff_hash 已写入 .comet.yaml（由 guard 强制校验）
handoff_hash 与当前 OpenSpec open 阶段产物一致（由 guard 强制校验）
design-context.md 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
如有新能力或补充验收场景，OpenSpec delta spec 已创建/更新
design_doc 已写入 .comet.yaml
阶段守卫：运行 bash "$COMET_GUARD" <change-name> design --apply，全部 PASS 后自动流转到 phase: build

退出前必须使用 --apply：

bash "$COMET_GUARD" <change-name> design --apply

上下文压缩恢复

design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：

bash "$COMET_STATE" check <change-name> design --recover

脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。

自动流转

退出条件满足后（包括用户确认设计方案），自动流转到下一阶段：

REQUIRED NEXT SKILL: 调用 comet-build skill 进入计划与构建阶段。