> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project file structure

> Understand the directories and files Comet creates in a project, and how each category supports recovery and troubleshooting.

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.

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/sd_slIArmm0kHnD4/assets/project-structure-illustrations/01-repo-evidence-layers.png?fit=max&auto=format&n=sd_slIArmm0kHnD4&q=85&s=786d46b33f382b9eebd4cb1c96dcbb8b" alt="Xiaoyu marks the repository layers that hold requirements facts, design plans, runtime state, and project Skills" width="800" data-path="assets/project-structure-illustrations/01-repo-evidence-layers.png" />
</p>

<p align="center">
  Comet splits recoverable facts across repository files so work can resume across devices and
  sessions.
</p>

## Classic workflow directories

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

```yaml theme={null}
# .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.

```text theme={null}
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](/en/guides/classic-layout-migration).

## Runtime artifacts inside a change

```text theme={null}
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.

<Tip>
  <code>brainstorm-summary.md</code> and <code>subagent-progress.md</code> are recovery anchors.
  Agents can reload them after context compaction.
</Tip>

## Project-level .comet directory

```text theme={null}
.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.

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

## 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.

<Note>
  <code>.comet.yaml</code> is the user-readable projection. Full machine state lives in{' '}
  <code>run-state.json</code>. Use <code>.comet.yaml</code> to understand progress and event logs to
  investigate how it changed.
</Note>

## Next steps

* [Resuming interrupted work](/en/guides/resuming-workflow)
* [Broken state and recovery](/en/guides/state-recovery)
* [State and configuration](/en/concepts/state-management)