comet-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Comet Phase 2: In-depth Design (Design)

前置条件

Prerequisites

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

An active change exists (proposal.md, design.md, tasks.md)
No Design Doc exists (no corresponding file under
```
docs/superpowers/specs/
```
)

步骤

Steps

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

0. Entry Check

执行入口验证：

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> design

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

Perform entry verification:

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
bash "$COMET_STATE" check <name> design

Proceed to Step 1 after verification passes. The script will output specific failure reasons if verification fails.

1a. 生成 OpenSpec → Superpowers 交接包

1a. Generate OpenSpec → Superpowers Handoff Package

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

bash

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

写入：

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

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

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

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

Must be generated by script; agent-improvised summaries are not allowed.

bash

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

The script will generate and record:

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

And write to

.comet.yaml

yaml

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

The default handoff package is a compact, traceable excerpt, not an agent summary:

```
design-context.json
```
: Machine index containing change, phase, canonical spec, source paths, hash
```
design-context.md
```
: Context for Superpowers reading, including script markers, source path, line range, sha256, deterministic excerpts
Mark
```
[TRUNCATED]
```
when exceeding excerpt budget, and retain the Full source path

If full-text context is truly needed, explicitly run:

bash

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

The handoff package comes from OpenSpec open-phase outputs:

```
proposal.md
```
: Goals, motivations, scope, non-goals
```
design.md
```
: High-level architecture decisions, solution constraints
```
tasks.md
```
: Initial task boundaries
```
specs/*/spec.md
```
: Delta capability specifications

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

1b. Execute Brainstorming (with Context)

立即执行： 使用 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。

Execute immediately: Use the Skill tool to load the

superpowers:brainstorming

skill, with ARGUMENTS including:

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 outputs are upstream factual sources; do not redefine requirements or rewrite proposal/spec.
Your task is to conduct in-depth technical design based on the handoff package: implementation plan, technical risks, testing strategy, boundary conditions.
If you find that the OpenSpec delta spec lacks acceptance scenarios, you can only propose a Spec Patch and write back to the OpenSpec delta spec; do not create a second requirement spec in the Design Doc.

Design Doc frontmatter must be minimal, containing only:
---
comet_change: <change-name>
role: technical-design
canonical_spec: openspec
---

Skip repeated context exploration and directly proceed to design questions.

Skipping this step is prohibited; do not proceed without loading this skill.

superpowers:brainstorming

is unavailable, stop the process and prompt to install or enable the Superpowers skill; do not use regular conversation as a substitute.

After loading the skill, produce the design plan in the form of dialogue as guided:

Technical solution: Architecture, data flow, key technology selection and risks
Testing strategy
If acceptance scenarios need to be supplemented, mark the delta spec changes to be written back

No Design Doc file is written during the brainstorming phase; only the design plan is produced for user confirmation in Step 1c. Only after confirmation is

docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md

created and the delta spec written back.

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

1c. User Confirmation of Design Plan (Blocking Point)

brainstorming 产出设计方案后，必须暂停并等待用户明确确认设计方案。不得在用户确认前创建最终 Design Doc、写入

design_doc

、运行 design guard，或进入

/comet-build

。

暂停时只展示必要摘要：

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

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

After the brainstorming produces the design plan, must pause and wait for explicit user confirmation of the design plan. Do not create the final Design Doc, write to

design_doc

, run the design guard, or enter

/comet-build

before user confirmation.

Only display necessary summaries when pausing:

Adopted technical solution
Key trade-offs and risks
Testing strategy
If there is a Spec Patch, list the delta spec changes to be written back

Proceed to Step 2 only after explicit user confirmation. If the user requests adjustments, continue brainstorming iterations until confirmation is obtained.

2. 更新 Comet 状态

2. Update Comet State

先记录 design_doc 路径。如果 Step 1c 回写了 delta spec（新增或修改了

specs/*/spec.md

），必须重新生成 handoff 以更新 hash：

bash

undefined

First record the design_doc path. If Step 1c wrote back to the delta spec (created or modified

specs/*/spec.md

), the handoff must be regenerated to update the hash:

bash

undefined

记录 design_doc 路径

Record design_doc path

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

如有 delta spec 变更，重新生成 handoff（更新 hash）

If delta spec changed, regenerate handoff (update hash)

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

自动流转到下一阶段

Automatically transition to next phase

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


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

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


If there are no delta spec changes, skip the handoff regeneration step. The state file is updated automatically; no need to manually edit other fields.

退出条件

Exit Conditions

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

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

Design Doc has been created and saved

Design Doc frontmatter contains

comet_change

role: technical-design

canonical_spec: openspec

```
handoff_context
```
and
```
handoff_hash
```
have been written to
```
.comet.yaml
```
(enforced by guard validation)
```
handoff_hash
```
matches the current OpenSpec open-phase outputs (enforced by guard validation)
```
design-context.md
```
must be generated by script and contain traceable markers such as source path, mode, sha256 (enforced by guard validation)
If there are new capabilities or supplementary acceptance scenarios, the OpenSpec delta spec has been created/updated
```
design_doc
```
has been written to
```
.comet.yaml
```
Phase Guard: Run
```
bash "$COMET_GUARD" <change-name> design --apply
```
, and automatically transition to
```
phase: build
```
after all checks PASS

Must use

--apply

before exiting:

bash

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

自动流转

Automatic Transition

退出条件满足后，无需等待用户再次输入，直接执行下一阶段：

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

After meeting the exit conditions, no need to wait for user input again, directly execute the next phase:

REQUIRED NEXT SKILL: Invoke the
comet-build
skill to enter the planning and build phase.