项目文件结构

Comet 把需求事实、设计计划、运行状态和用户生成 Skill 分开保存。理解这些文件的位置和职责，有助于你恢复中断的工作、排查状态问题，以及做跨设备/CI 集成。所有恢复相关的状态都在仓库文件里（不依赖对话历史），所以换设备、换平台、上下文压缩后，/comet 都能从文件重建状态。详见恢复中断的工作。

小鱼用小旗标记仓库文件里的需求事实、设计计划、运行状态和项目 Skill 分层

Comet 把可恢复的事实拆到仓库文件里，方便跨设备恢复、排查和协作

经典工作流目录

新建的 Classic 和双工作流项目默认使用文档目录布局：

# .comet/config.yaml
classic:
  artifact_layout: docs

classic.artifact_layout 可配置为 docs 或 legacy：docs 对应 docs/openspec/，legacy 对应仓库根目录的 openspec/。这是两种受支持布局的选择，不接受任意目录路径。

docs/
├── openspec/
│   ├── config.yaml                       # OpenSpec 项目配置
│   ├── changes/
│   │   ├── <name>/                       # 一个活跃 change
│   │   │   ├── .openspec.yaml            # OpenSpec 状态
│   │   │   ├── .comet.yaml               # Comet 工作流状态（用户可读投影 + run_id 链接）
│   │   │   ├── proposal.md               # Why + What
│   │   │   ├── design.md                 # How（高层）
│   │   │   ├── tasks.md                  # 任务清单（- [ ] / - [x]）
│   │   │   ├── specs/<capability>/spec.md   # delta spec
│   │   │   └── .comet/                   # Comet 运行产物（见下）
│   │   └── archive/YYYY-MM-DD-<name>/    # 已归档 change
│   └── specs/<capability>/spec.md        # 当前主规格（归档时由 delta 合并）
└── superpowers/
    ├── specs/YYYY-MM-DD-<topic>-design.md   # 技术设计文档（Design Doc）
    ├── plans/YYYY-MM-DD-<feature>.md        # 实施计划
    └── reports/YYYY-MM-DD-<name>-verify.md  # 验证报告（可选）

已有 Classic 项目不会在升级时自动移动根目录 openspec/。如果想从旧布局迁移到 docs/openspec/，详见迁移 Classic 布局。

change 内的 .comet/ 运行产物

每个 change 目录下还有一个 .comet/ 子目录，存运行期产物（多为 machine-owned，不要手工编辑）：

docs/openspec/changes/<name>/.comet/
├── run-state.json          # Engine Run state（machine-owned）
├── state-events.jsonl      # Classic 状态转换审计日志（append-only）
├── pending-action.json     # 当前等待的 pending action
├── trajectory.jsonl        # append-only 轨迹审计
├── context.md              # 当前 Agent 上下文
├── artifacts.json          # 产出的 artifacts 映射
├── checkpoint.json         # 一致性检查点
├── handoff/                # handoff 交接包（design 阶段生成）
│   ├── design-context.json     # 默认模式机器索引
│   ├── design-context.md       # 默认模式可读摘要
│   ├── spec-context.json       # beta 压缩模式
│   ├── spec-context.md
│   └── brainstorm-summary.md   # brainstorming 恢复检查点
└── subagent-progress.md    # subagent 调度检查点（仅 subagent 模式）

brainstorm-summary.md 和 subagent-progress.md 是 恢复锚点——上下文压缩后 Agent 会重载它们继续。你通常不需要读这些文件，但知道它们在哪有助于排查。

Comet 配置和运行目录

项目根的 .comet/ 目录存放项目级配置和各能力的运行数据：

.comet/
├── config.yaml               # 项目级 Comet 配置（共享入口及 native/classic 默认值）
├── skill-preferences.yaml    # /comet-any 的项目级 Skill 偏好
├── skills/                   # 项目 Skill 池（按名覆盖内置 Skill）
├── runs/<run-id>/            # standalone Engine Run 状态
├── skill-snapshots/<hash>/   # 不可变 Skill 快照
├── bundle-authoring/         # /comet-any 创作状态
├── bundle-drafts/            # Bundle draft
├── bundle-factory-plans/     # Factory plan
├── bundle-evals/             # eval 证据
├── bundles/                  # 已发布 Bundle
└── tmp/                      # 临时文件

不同项目不一定都会出现所有目录——只有使用对应能力后才会创建（例如没用过 /comet-any 就不会有 bundle-* 目录）。

仓库根目录的 .comet.yaml 或 comet.yaml 不是 Comet 配置文件，也不会作为工作流状态读取。项目默认配置只放在 .comet/config.yaml；新项目的 Classic change 状态放在 docs/openspec/changes/<name>/.comet.yaml ，保留旧布局的项目仍使用 openspec/changes/<name>/.comet.yaml。

目录和文件职责

路径	职责	谁读写
`docs/openspec/changes/<name>/.comet.yaml`	Comet 工作流状态（phase、workflow、language、build 决策、verify_result、run_id 链接）	Agent 读写，用户可读
`docs/openspec/changes/<name>/.comet/run-state.json`	Engine Run 细节（currentStep、pending、trajectory、artifacts）	machine-owned，不要手工编辑
`docs/openspec/changes/<name>/.comet/state-events.jsonl`	Classic 阶段转换审计，记录 event、source 和 effects	Comet 追加写入，用户可读
`docs/openspec/changes/`	活跃 change 和归档 change	OpenSpec + Comet
`docs/openspec/specs/`	当前主规格（归档时由 delta 合并进来）	OpenSpec
`docs/superpowers/specs/`	技术设计文档（Design Doc）	Superpowers + Comet
`docs/superpowers/plans/`	实施计划	Superpowers + Comet
`.comet/config.yaml`	项目级 Comet 配置。`native.` 与 `classic.` 分别控制两套工作流默认值	用户编辑
`.comet/skill-preferences.yaml`	`/comet-any` 偏好（advisory/strict、prefer/require）	用户编辑或 `/comet-any` 生成
`.comet/skills/`	项目 Skill 池（按名覆盖内置）	`comet skill add`
`.comet/runs/<run-id>/`	standalone Engine Run 状态	`comet skill run --run-id`
`.comet/bundles/`	已发布 Bundle	`comet publish run`

哪些该提交到 git

应该提交：当前 Classic 产物根（新项目为 docs/openspec/，保留旧布局的项目为 openspec/）、docs/superpowers/、.comet/config.yaml、.comet/skill-preferences.yaml。这些是事实来源，提交后才能跨设备恢复。
看情况：.comet/skills/、.comet/bundles/（团队共享则提交；个人本地则忽略）。
通常忽略：.comet/tmp/、运行期临时文件。

.comet.yaml 和 run-state.json 的边界：.comet.yaml 保存 用户可理解的工作流投影（phase、build_mode、verify_result 等），只通过 run_id 链接到 Engine；完整的 Run 细节在 run-state.json。 state-events.jsonl 只解释成功状态转换的历史，不是当前状态来源。所以你看 .comet.yaml 就能理解当前进度；排查状态为何变化时，再看事件日志。

下一步

恢复中断的工作 — 这些文件如何支撑 /comet 恢复
状态损坏与恢复 — 状态坏了怎么排查
状态与配置 — .comet.yaml 字段详解

入门

理解 Comet

五阶段工作流

轻量预设

恢复与排查

实践场景

经典工作流目录

change 内的 .comet/ 运行产物

Comet 配置和运行目录

目录和文件职责

哪些该提交到 git

下一步

​经典工作流目录

​change 内的 .comet/ 运行产物

​Comet 配置和运行目录

​目录和文件职责

​哪些该提交到 git

​下一步

经典工作流目录

change 内的 .comet/ 运行产物

Comet 配置和运行目录

目录和文件职责

哪些该提交到 git

下一步