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.

This page focuses on the Classic directory structure. Native keeps user-readable artifacts and device-local execution state separately; see Artifacts and state for its directory structure.

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          # Engine Run state (machine-owned)
├── state-events.jsonl      # Classic state-transition audit log (append-only)
├── pending-action.json     # Current pending action
├── trajectory.jsonl        # Append-only trajectory audit
├── context.md              # Current Agent context
├── artifacts.json          # Artifact mapping
├── checkpoint.json          # Consistency checkpoint
├── handoff/                # Handoff package generated during Design
│   ├── design-context.json     # Default mode machine index
│   ├── design-context.md       # Default mode readable summary
│   ├── spec-context.json       # Beta compression mode
│   ├── spec-context.md
│   └── brainstorm-summary.md   # Brainstorming recovery checkpoint
└── subagent-progress.md     # Subagent dispatch checkpoint

Most files in this directory are maintained automatically by Comet (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. After context compaction, an Agent reloads them to continue. You normally do not need to read these files, but knowing where they live helps with troubleshooting.

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`	Classic workflow state: phase, workflow, language, build decisions, verification result, and run-id link	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`	Classic phase-transition audit with event, source, and effects	Comet scripts
`docs/openspec/changes/`	Active and archived changes	OpenSpec + Comet
`docs/openspec/specs/`	Main specifications merged from deltas at archive	OpenSpec
`docs/superpowers/specs/`	Design Docs	Superpowers + Comet
`docs/superpowers/plans/`	Implementation plans	Superpowers + Comet
`.comet/config.yaml`	Project-level Comet configuration; `native.` and `classic.` set workflow defaults	User
`.comet/skill-preferences.yaml`	`/comet-any` preferences (`advisory`/`strict`, `prefer`/`require`)	User or `/comet-any`
`.comet/skills/`	Project Skill pool, with same-named built-in overrides	`comet skill add`

What to commit

Commit: the Classic artifact root (docs/openspec/ for new projects or openspec/ for retained legacy layouts), docs/superpowers/, .comet/config.yaml, and .comet/skill-preferences.yaml. These files are the basis for cross-device recovery and must be committed before you can restore work on a new device. See Artifacts and state for Native artifact commit guidance.
Maybe commit: .comet/skills/, .comet/bundles/ if the team shares them.
Usually ignore: .comet/tmp/ and temporary runtime files.

The boundary between .comet.yaml and run-state.json is important: .comet.yaml stores the user-understandable workflow projection such as phase, build_mode, and verify_result, and links to Engine through run_id. Full Run details live in run-state.json. The append-only event log explains successful state transitions; it is not the current state source. Read .comet.yaml for current progress and the event log when you need to understand why it changed.

Understand Comet Classic

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