跳转到主要内容
Comet 在 /comet 五阶段流程中会创建一系列中间产物。它们不是最终交付物（proposal、design、tasks、代码），而是 Comet 用来做上下文压缩、状态恢复、证据记录和阶段交接的工作文件。 理解这些产物能帮你：在上下文压缩后快速恢复、在排障时知道该看哪个文件、以及在归档时确认生命周期完整。

​
产物总览

​
.comet.yaml：贯穿全程的状态文件

属性说明
位置openspec/changes/<name>/.comet.yaml
创建阶段open（comet-state init）
更新阶段每个阶段都更新对应字段
管理machine-managed（脚本写、guard 校验）
这是 Comet 唯一的跨阶段状态文件。它不是目录，是一个 YAML 文件，字段随阶段推进逐步填写。详见状态与配置。
Comet 的经典工作流刻意避免创建一堆内部 JSON 状态文件。跨会话恢复靠的是 .comet.yaml + handoff 文件 + 检查点 markdown，而不是一批 machine-owned JSON。.comet/run-state.json、trajectory.jsonl 这些是 Skill Engine（comet skill run）的内部文件，经典 /comet 工作流不用。

​
design 阶段产物

design 阶段是中间产物最丰富的阶段，主要服务于上下文压缩和 OpenSpec→Superpowers 交接。

​
handoff 交接包

属性说明
位置openspec/changes/<name>/.comet/handoff/
创建comet-handoff.mjs <change> design --write
作用把 open 阶段的 OpenSpec artifacts 整理成 Superpowers brainstorming 能读懂的上下文
管理machine-generated（guard 校验脚本标记和 hash）
交接包根据 context_compression 配置有两种形态：
模式产出文件内容
off（默认）design-context.json + design-context.md完整 artifacts 摘要，每文件带源路径、行范围、sha256。超 80 行截断。
betaspec-context.json + spec-context.mddelta spec verbatim 投影，proposal/design/tasks 只存 hash 引用。节省约 25–30% token。
交接包还把 handoff_context 和 handoff_hash 写入 .comet.yaml。guard 在离开 design 时重算 hash 检测漂移。详见上下文压缩机制和comet-handoff。

​
brainstorm-summary.md

属性说明
位置openspec/changes/<name>/.comet/handoff/brainstorm-summary.md
创建design 阶段 brainstorming 过程中增量写入
作用上下文压缩的恢复检查点——压缩发生后从这里恢复已确认的设计决策
管理Agent 维护（结构和位置由 Skill 规定）
它记录：
  • 已确认的技术方案
  • 关键权衡和风险
  • 测试策略
  • Spec Patch（如果有）
  • 未确认项标记为 pending/candidate
brainstorm-summary.md 是 design 阶段最重要的恢复锚点。上下文压缩后，Agent 从这里恢复已确认决策，而不是重新 brainstorming。它在 brainstorming 过程中增量更新，在用户确认方案后定稿。

​
build 阶段产物

build 阶段的中间产物主要服务于子代理调度恢复和任务跟踪。

​
实施计划（plan）

属性说明
位置docs/superpowers/plans/YYYY-MM-DD-<feature>.md
创建build 阶段（由子代理加载 writing-plans 生成）
作用实施计划；frontmatter 是 verify 阶段的关键证据
管理Agent-written
计划的 frontmatter 是验证阶段依赖的证据： 
---
change: <openspec-change-name>
design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
base-ref: <实现前的 git HEAD>
---
base-ref 是实现开始前的 commit SHA，verify 用它重新计算变更规模。plan 路径写入 .comet.yaml。

​
subagent-progress.md

属性说明
位置openspec/changes/<name>/.comet/subagent-progress.md
创建build 阶段（仅 build_mode: subagent-driven-development 时）
作用子代理调度检查点——brainstorm-summary.md 在 build 阶段的对应物
管理协调会话（main session）维护
它记录当前任务的调度状态：
  • 当前 plan 任务文本 + 对应的 OpenSpec 任务文本
  • 当前阶段（implementing/spec-review/quality-review/checkoff/done/blocked/final-review/final-fix）
  • 实现的 commit hash、改动文件、RED/GREEN 证据
  • 选定的 review_mode
  • 已通过的审查阶段 + 未解决的 reviewer 反馈
  • 当前 review-fix 轮数
subagent-progress.md 每个任务替换一次。子代理（implementer/reviewer）不能编辑它——只有协调会话能写。实现者只能写代码，审查者只能写反馈，协调会话负责推进检查点。这避免子代理擅自标记任务完成。

​
tasks.md 勾选状态

属性说明
位置openspec/changes/<name>/tasks.md
作用任务完成跟踪（- [ ] → - [x]）
管理协调会话编辑
Comet 没有单独的任务勾选文件——勾选状态就在 tasks.md 内。用 grep -c '\- \[ \]' tasks.md 统计未完成项，用 comet-state task-checkoff <file> <text> 验证特定任务已勾选。 子代理模式下，实现者不能勾选任务——只有协调会话在双审查通过后才勾选。

​
verify 阶段产物

​
验证报告

属性说明
位置docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
创建verify 阶段，写盘后才标记 pass
作用验证证据——6 项（light）或 7 项（full）检查结果、PASS/FAIL、接受原因
管理Agent-written
verification_report 路径写入 .comet.yaml。guard 要求 verify-pass 转换时这个文件必须存在。

​
Implementation Divergence 注记（可选）

属性说明
位置追加到 Design Doc（docs/superpowers/specs/...-design.md）
触发full verify 发现 delta spec 和 Design Doc 矛盾，用户选择接受偏差时
作用记录实现和设计文档的差异
如果用户选择接受偏差，归档时 Design Doc 会被标记 status: superseded-by-main-spec。

​
archive 阶段产物

archive 阶段不创建新文件，而是给已有产物加标注并移动目录。

​
frontmatter 标注

文件标注含义
Design Docarchived-with: <archiveName> + status: final归档归属 + 最终状态
Design Doc（如有偏差）status: superseded-by-main-spec实现已偏离，主 spec 为准
Planarchived-with: <archiveName>归档归属

​
归档目录

整个 change 目录移动到 openspec/changes/archive/YYYY-MM-DD-<name>/，包括 .comet.yaml、.comet/handoff/、.comet/subagent-progress.md 和 delta spec。归档后 .comet.yaml 设 archived: true。

​
按目的分类

目的产物
上下文压缩handoff 交接包（design-context/spec-context）、brainstorm-summary.md
状态恢复.comet.yaml、subagent-progress.md、brainstorm-summary.md
阶段交接handoff 交接包（OpenSpec→Superpowers）、plan base-ref（build→verify）
证据验证报告、plan frontmatter、tasks.md 勾选、Implementation Divergence 注记
生命周期标注archived-with、status、archived: true

​
排障时看哪个文件

你想知道的看哪个产物
当前阶段和执行方式.comet.yaml
design 交接的 OpenSpec 上下文.comet/handoff/design-context.md 或 spec-context.md
brainstorming 确认了什么.comet/handoff/brainstorm-summary.md
子代理做到哪个任务的哪一步.comet/subagent-progress.md
任务完成进度tasks.md 的勾选状态
验证结果docs/superpowers/reports/...-verify.md
handoff 是否漂移.comet.yaml 的 handoff_hash + 重新算 hash 对比

​
下一步