Comet Design

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

收到入口返回的 layout 后，按 comet-classic/reference/classic-layout.md 确定各逻辑根对应的目录。当前上下文已有这份协议时，无需重复加载。本文件中的 OpenSpec CLI 调用均通过适配器执行，文件路径均基于已绑定的 <classic-*> 根目录，无需先额外运行 root show。

前置条件

• 活跃 change 已存在，Open 必需产物检查通过
• Runtime 当前的 phase 为 design；已有设计时从已有进度继续，不能因为设计文件存在就跳过用户确认

各文档的用途：proposal 记录目标与范围，spec 记录行为和验收要求，Design Doc 记录技术决策，plan 记录实施步骤，tasks.md 记录任务完成状态。已有 design.md 时，在同一文件中补充必要设计，不另建一份相同的技术方案。正式技术设计以 design_doc 指向的文件为准；旧 change 已记录其他路径时，沿用该路径。其他文件只引用这份设计，不重复维护同一项决策。

步骤

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

按 comet-classic/reference/scripts.md 使用正式支持的 Comet CLI，执行以下入口验证。从任意入口恢复任务时，先按 comet-classic/reference/context-recovery.md 检查恢复状态：

comet state select <change-name>
comet state check <name> design --json

上一阶段 guard 已成功返回本阶段状态信息时，直接使用其中的状态与 agent.continuation 继续，不重复 select/check；恢复任务、工作区变化或外部状态变化时，才执行上述入口验证。验证通过后，使用入口返回的 layout、configuration、nextAction 和协作进度摘要继续，不逐字段查询，也不重复 root show。正常进入本阶段时，只做入口检查；丢失上下文后恢复任务或需要读取详情时，按 context-recovery.md 处理。验证失败时，处理返回的具体原因。

恢复：先核对现有产物和用户确认记录，只补未完成的步骤。无论正常进入还是恢复任务，都要保留已登记且仍然有效的设计，并读取 data.designReadiness、data.issues 和 data.nextAction。补回缺失文件、纠正文件关联的 change，或更新过期 handoff，不清空 design_doc。用户已确认设计后，可以执行返回的 complete-design 动作；该命令会保留已完成的步骤。如果已经进入 Build，则只返回当前阶段的入口信息。

1a. 生成 OpenSpec → Superpowers 交接包

必须由脚本生成，不能由 Agent 手写摘要代替。

comet handoff <change-name> design --write

脚本会根据 change .comet.yaml 的 context_compression 快照生成并记录交接包。

默认 context_compression: off 时生成：

<classic-change-dir>/.comet/handoff/design-context.json
<classic-change-dir>/.comet/handoff/design-context.md

启用 beta（项目 .comet/config.yaml 中 classic.context_compression: beta，创建 change 时快照进入 .comet.yaml）时生成：

<classic-change-dir>/.comet/handoff/spec-context.json
<classic-change-dir>/.comet/handoff/spec-context.md

并在 .comet.yaml 写入：

handoff_context: <classic-change-ref>/.comet/handoff/design-context.json
handoff_hash: <sha256>

默认交接包由脚本摘录源文件，并保留来源信息，不是 Agent 撰写的摘要：

• design-context.json：供程序读取的索引，包含 change、phase、正式规格（canonical spec）、源文件路径（source paths）和 hash
• design-context.md：供 Superpowers 阅读的上下文，包含脚本标记、source path、line range、sha256，以及脚本按固定规则生成的摘录
• 超出摘录长度上限时标记 [TRUNCATED]，并保留 Full source 路径

beta 交接包按固定结构组织规格内容，在减少 OpenSpec 原文 token 占用的同时，保留实现所需的规格依据：

• spec-context.json：供程序读取的索引，包含 change、phase、mode=beta、source paths、context_hash，以及 files 中各文件的角色
• spec-context.md：供 Superpowers 阅读的上下文，逐字保留 delta spec 文件内容，并按 hash 引用相关产物
• 正式规格仍以 OpenSpec delta spec 为准；交接包中的规格内容缺失或过期时，必须重新生成交接包或读取源 spec，不得用 Agent 摘要替代

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

comet handoff <change-name> design --write --full

交接包取自 OpenSpec open 阶段的产物：

• proposal.md：目标、动机、范围、非目标
• design.md（存在时）：已有技术决策、方案约束
• tasks.md：初始任务范围
• specs/**/spec.md：各项功能的增量规格，保留嵌套 capability 的完整路径

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

立即执行： 使用 Skill 工具加载 Superpowers brainstorming 技能。禁止跳过此步骤。

技能加载时，ARGUMENTS 必须包含：

Language: 使用入口 configuration.language 中的 Comet 配置产物语言输出

技能加载后，按其指引使用以下上下文：

Change: <change-name>
OpenSpec Context Pack: <classic-change-dir>/.comet/handoff/design-context.md

如 context_compression: beta，则使用：
OpenSpec Context Pack: <classic-change-dir>/.comet/handoff/spec-context.md

已确认需求以 OpenSpec 产物为准。brainstorming 引用这些需求，只讨论尚未解决的技术选择，不重新询问已经确认的需求。
默认只读取上述一个 Markdown 上下文包；机器 JSON 由 Runtime 校验，只有诊断索引问题才读取。截断或验收条款不足时按 source path/line range 补读相关原文，不同时通读 JSON、Markdown 和全部源文件。
你的任务是基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
如发现目标、范围、非目标、验收场景或关键约束仍不清楚，先澄清缺口；信息已足够时直接形成设计方案，不设置最低问答轮数。
需要提问时，先读取 comet-classic/reference/decision-point.md，逐问给出明确问题、推荐及基于当前约束的理由、各选项影响，优先使用可用的 AskUserQuestion，并等待回答。无法形成真实选项的缺失事实明确请求补充。已有有效确认不重复询问；技术方案唯一不替代 Step 1c 的正式设计确认。
不要重写 proposal/spec。如发现 OpenSpec delta spec 缺少验收场景，只能提出 Spec Patch，并回写 OpenSpec delta spec，不能在 Design Doc 中创建第二份需求规格。Spec Patch 仅限于补充验收场景、修正歧义描述或添加边界条件，不得大幅重写 delta spec 的结构或范围。如需大幅修改，应记录设计阶段发现的需求问题，回到 brainstorming 请用户确认。

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

按风险决定设计深度：存在真实取舍时比较 2-3 个方案；既有架构已决定方案时说明依据，不为凑数编造替代方案。高风险接口、迁移、安全与并发必须说明失败路径及验证策略。
只采用 brainstorming 的探索与设计方法；相邻的设计段落合并展示，统一在 Comet Step 1c 请用户正式确认设计。外部 Skill 不得额外要求用户再次批准整份设计文档，不得自动调用 writing-plans、切换工作区或进入实施。不得提前写入 Design Doc。

禁止在未加载该技能的情况下继续。

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

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

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

brainstorming 阶段先提出候选方案，供用户在 Step 1c 确认，不直接写成正式 Design Doc。确认后，才创建或更新正式设计及 delta spec。保留 Open 阶段已有的 design.md 内容，将待确认的修改先记录到检查点，不能提前覆盖已确认的决策。

为便于上下文压缩后恢复，brainstorming 过程中必须持续更新 brainstorm-summary.md。每轮澄清或方案调整后，只要新增了已确认事实、关键约束、候选方案、取舍与风险、测试策略或 Spec Patch 候选，就更新该文件。未确认的内容必须标注为“待确认”或“候选”。该文件用于恢复讨论进度，不是 Design Doc，也不能代替 Step 1c 的用户确认。

1c. 请用户确认设计方案

brainstorming 产出设计方案后，必须按 comet-classic/reference/decision-point.md 的协议暂停并等待用户明确确认设计方案。不得在用户确认前创建最终 Design Doc、写入 design_doc、运行 design guard，或进入 /comet-build。

暂停时只展示必要摘要：

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

以单选题给出以下三个选项：

• 确认本设计：以该设计继续 Step 2
• 要求调整：继续 brainstorming 迭代，直到用户确认修改后的方案
• 暂缓确认：保留 brainstorming 检查点和方案，不创建最终 Design Doc、不推进阶段，留待后续再确认

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

1d. 保存已确认的设计摘要

用户确认设计方案后、创建 Design Doc 前，创建或更新上述检查点文件，将摘要整理为用户最终确认的方案：

使用文件工具确保 <classic-change-dir>/.comet/handoff/ 存在；不要依赖 POSIX 专用目录命令。

<classic-change-dir>/.comet/handoff/brainstorm-summary.md 结构：

# Brainstorm Summary

- Change: <change-name>
- Date: <YYYY-MM-DD>

## 确认的技术方案

<用户确认的方案摘要>

## 关键取舍与风险

<主要取舍和风险>

## 测试策略

<测试方法概述>

## Spec Patch

<将回写的 delta spec 变更，无则写"无">

上下文压缩说明：brainstorm-summary.md 用于在中断后恢复讨论；主动式压缩应等正式设计、状态和 handoff 都保存到文件后再进行。此前如果上下文已被压缩，按需加载以下文件，再继续 Step 2：

• <classic-change-dir>/.comet/handoff/brainstorm-summary.md
• 按需补读 <classic-change-dir>/.comet/handoff/design-context.md（或 beta 的 spec-context.md）及缺失的原文段落；机器 JSON 不作为必读上下文

1e. 继续创建设计文档，暂不压缩上下文

brainstorm-summary.md 用于恢复进度，但 Design Doc 尚未保存时，不能主动丢弃当前设计上下文。直接进入 Step 2，等 Design Doc、状态和最新 handoff 都保存后，再执行上下文压缩。