Project file structure

Comet keeps requirements facts, design plans, runtime state, and user-generated Skills in separate files. Knowing where each category lives helps you recover interrupted work, debug bad state, and integrate Comet with CI. All recovery state lives in repository files, not chat history. After a device switch, platform switch, or context compaction, /comet can rebuild state from files.

Xiaoyu marks the repository layers that hold requirements facts, design plans, runtime state, and project Skills

Comet splits recoverable facts across repository files so work can resume across devices and sessions.

Classic workflow directories

New Classic and dual-workflow projects use the documentation layout by default:

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

classic.artifact_layout accepts docs or legacy. docs maps to docs/openspec/, while legacy maps to root-level openspec/. These are the two supported layouts; the field does not accept an arbitrary path.

docs/
├── openspec/
│   ├── config.yaml
│   ├── changes/
│   │   ├── <name>/
│   │   │   ├── .openspec.yaml
│   │   │   ├── .comet.yaml
│   │   │   ├── proposal.md
│   │   │   ├── design.md
│   │   │   ├── tasks.md
│   │   │   ├── specs/<capability>/spec.md
│   │   │   └── .comet/
│   │   └── archive/YYYY-MM-DD-<name>/
│   └── specs/<capability>/spec.md
└── superpowers/
    ├── specs/YYYY-MM-DD-<topic>-design.md
    ├── plans/YYYY-MM-DD-<feature>.md
    └── reports/YYYY-MM-DD-<name>-verify.md

Upgrading does not move an existing Classic project’s root-level openspec/. To migrate from the legacy layout to docs/openspec/, see Migrate Classic layout.

Runtime artifacts inside a change

docs/openspec/changes/<name>/.comet/
├── run-state.json
├── state-events.jsonl
├── pending-action.json
├── trajectory.jsonl
├── context.md
├── artifacts.json
├── checkpoint.json
├── handoff/
└── subagent-progress.md

Most files in this directory are machine-owned. Do not edit them manually unless a recovery guide specifically tells you to.

brainstorm-summary.md and subagent-progress.md are recovery anchors. Agents can reload them after context compaction.

Project-level .comet directory

.comet/
├── config.yaml               # Project-level Comet settings (shared entry plus Native/Classic defaults)
├── skill-preferences.yaml
├── skills/
├── runs/<run-id>/
├── skill-snapshots/<hash>/
├── bundle-authoring/
├── bundle-drafts/
├── bundle-factory-plans/
├── bundle-evals/
├── bundles/
└── tmp/

Only directories for features you use will exist. A project that has never used /comet-any will not have bundle directories.

A repository-root .comet.yaml or comet.yaml is not a Comet config file and is not read as workflow state. Project defaults live in .comet/config.yaml. New projects store Classic change state in docs/openspec/changes/<name>/.comet.yaml ; projects that retain the legacy layout continue to use openspec/changes/<name>/.comet.yaml.

Responsibilities

Path	Responsibility	Who writes it
`docs/openspec/changes/<name>/.comet.yaml`	User-readable workflow projection: phase, workflow, language, execution settings, verification result, run id	Agent and Comet scripts
`docs/openspec/changes/<name>/.comet/run-state.json`	Engine Run details	Machine-owned
`docs/openspec/changes/<name>/.comet/state-events.jsonl`	Append-only phase transition audit	Comet scripts
`docs/openspec/changes/`	Active and archived changes	OpenSpec + Comet
`docs/openspec/specs/`	Main specifications after archive	OpenSpec
`docs/superpowers/specs/`	Design Docs	Superpowers + Comet
`docs/superpowers/plans/`	Implementation plans	Superpowers + Comet
`.comet/config.yaml`	Project-level settings; `native.` and `classic.` control their respective workflows	User
`.comet/skill-preferences.yaml`	Skill Creator preferences	User or `/comet-any`
`.comet/skills/`	Project Skill pool	`comet skill add`

What to commit

Commit: the active Classic root (docs/openspec/ for new projects or openspec/ for retained legacy layouts), docs/superpowers/, .comet/config.yaml, and .comet/skill-preferences.yaml.
Maybe commit: .comet/skills/, .comet/bundles/ if the team shares them.
Usually ignore: .comet/tmp/ and temporary runtime files.

.comet.yaml is the user-readable projection. Full machine state lives in run-state.json. Use .comet.yaml to understand progress and event logs to investigate how it changed.

Get started

Understand Comet

Five-phase workflow

Presets

Recovery and troubleshooting

Practical scenarios

Project file structure

Classic workflow directories

Runtime artifacts inside a change

Project-level .comet directory

Responsibilities

What to commit

Next steps

​Classic workflow directories

​Runtime artifacts inside a change

​Project-level .comet directory

​Responsibilities

​What to commit

​Next steps

Classic workflow directories

Runtime artifacts inside a change

Project-level .comet directory

Responsibilities

What to commit

Next steps