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

# State and configuration

> Understand .comet.yaml, .comet/config.yaml, configuration precedence, environment overrides, and what users can safely edit.

Comet's recovery model comes from file-based state. Understanding user-readable state, machine-managed runtime evidence, and project defaults helps you recover interrupted work without relying on chat memory.

This page uses `<classic-root>` for the configured Classic OpenSpec root: `docs/openspec/` for new projects and `openspec/` for projects that retain the legacy layout. The location is selected by `classic.artifact_layout`; see [Project file structure](/en/guides/project-structure).

## Where to look first

| Goal                                                        | Look at                                               | Recommendation                                            |
| ----------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| Set the workflow entered by `/comet`                        | `default_workflow` in `.comet/config.yaml`            | Must also appear in `workflows`                           |
| Control automatic probing for natural-language continuation | `ambient_resume` in `.comet/config.yaml`              | Defaults to `true`; explicit `/comet` is unaffected       |
| Set Native artifact language                                | `native.language` in `.comet/config.yaml`             | Only `en` or `zh-CN`; affects new Native changes          |
| Set Native clarification mode                               | `native.clarification_mode` in `.comet/config.yaml`   | `sequential` or `batch`                                   |
| Set the Classic artifact layout                             | `classic.artifact_layout` in `.comet/config.yaml`     | `legacy` or `docs`; project-level path selection          |
| Set Classic artifact language                               | `classic.language` in `.comet/config.yaml`            | Only `en` or `zh-CN`; affects new Classic changes         |
| Set default context compression                             | `classic.context_compression` in `.comet/config.yaml` | Project default; affects new Classic changes              |
| Set default review strength                                 | `classic.review_mode` in `.comet/config.yaml`         | Full workflow defaults to `standard`                      |
| Set whether the next phase runs automatically               | `classic.auto_transition` in `.comet/config.yaml`     | Set to `false` when you want manual Classic phase control |
| Check current change progress                               | `<classic-root>/changes/<name>/.comet.yaml`           | Human-readable; safe to inspect                           |
| Diagnose abnormal progress                                  | `comet status` / `comet doctor`                       | Prefer commands over hand-editing state                   |

## Current change selection

`.comet/current-change.json` stores the explicitly selected workflow and change. It removes write ambiguity when multiple active changes exist; it does not replace Classic `.comet.yaml` or Native `comet-state.yaml`.

```bash theme={null}
comet state select <change-name>
comet state current
comet state clear-selection
# Native: comet native select <change-name>
```

A single active change may be attributed automatically. Multiple active changes require explicit selection. An archived target, invalid selection, or workflow mismatch fails closed. Once `isolation` is `current`, `branch`, or `worktree`, a Classic change is also pinned to the branch recorded in `bound_branch`. On drift, switch back to the original branch; run `comet state rebind <change-name>` only after explicitly confirming that the current branch should take over. Do not hand-edit the selection file.

## Project defaults: `.comet/config.yaml`

Native and Classic share one project-level file. Shared entry fields remain at the top level, while Native and Classic defaults live under separate `native:` and `classic:` blocks. With both workflows enabled, an English installation can generate:

<Warning>
  Comet no longer reads a repository-root <code>.comet.yaml</code> or <code>comet.yaml</code>.
  Project defaults live only in <code>.comet/config.yaml</code>; workflow state lives only in{' '}
  <code>\<classic-root>/changes/\<name>/.comet.yaml</code>.
</Warning>

```yaml theme={null}
schema: comet.project.v1
default_workflow: classic
workflows:
  - native
  - classic
ambient_resume: true

native:
  artifact_root: docs
  language: en
  clarification_mode: sequential

classic:
  artifact_layout: docs
  language: en
  context_compression: off
  review_mode: standard
  auto_transition: true
```

### Shared and Classic fields

| Field              | Values                       | Meaning                                                                                |
| ------------------ | ---------------------------- | -------------------------------------------------------------------------------------- |
| `schema`           | `comet.project.v1`           | Structured project configuration version managed by Comet                              |
| `default_workflow` | `native` \| `classic`        | Permanent Skill entered by `/comet`                                                    |
| `workflows`        | `native`, `classic`, or both | Enabled workflows; must include the default                                            |
| `ambient_resume`   | `true` \| `false`            | Whether the agent automatically probes ordinary natural-language continuation requests |

The following `classic.*` fields belong only to Classic. `artifact_layout` is a project-level directory selection; the other four fields are snapshotted into new Classic changes:

| Field                         | Allowed values                    | Default                                                                                               | Meaning                                                                                            |
| ----------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `classic.artifact_layout`     | `legacy` \| `docs`                | Defaults to `docs`; update backfills `legacy` only when an existing root `openspec/` must be retained | Selects `openspec/` or `docs/openspec/` as the OpenSpec root                                       |
| `classic.language`            | `en` \| `zh-CN`                   | Mapped from the Skill language selected during `comet init`; `--yes` defaults to `en`                 | Controls the primary language of OpenSpec, Superpowers, verification report, and archive artifacts |
| `classic.context_compression` | `off` \| `beta`                   | `off`                                                                                                 | Controls context compression during the design-to-build handoff                                    |
| `classic.review_mode`         | `off` \| `standard` \| `thorough` | `standard` for full workflow                                                                          | Controls code review strength                                                                      |
| `classic.auto_transition`     | `true` \| `false`                 | `true`                                                                                                | Controls whether Comet invokes the next phase Skill automatically after phase advancement          |

<Note>
  Changing <code>default\_workflow</code> changes only the <code>/comet</code> entry and never
  migrates a change. Classic defaults are snapshotted into new changes; later edits do not rewrite
  existing changes.
</Note>

<Warning>
  Editing <code>classic.artifact\_layout</code> changes where Comet reads artifacts but does not move
  existing files. To switch an existing project, run{' '}
  <code>comet classic root move docs --dry-run</code> to inspect current state, conflicts, and
  blockers, then run <code>comet classic root move docs --apply</code>. The dry run does not issue a
  plan ID.
</Warning>

See [Native configuration](/en/native/configuration) for `native.artifact_root`, `native.language`, `native.clarification_mode`, migration commands, and complete examples. Native does not read Classic `context_compression`, `review_mode`, or `auto_transition`.

<Info>
  Legacy flat Classic configuration still lets <code>/comet</code> enter Classic through the legacy
  fallback, but Classic Runtime reads project defaults only from the <code>classic:</code> block.
  Run <code>comet init</code> or <code>comet update</code> to migrate old values into the new block
  and fill missing managed Native and Classic fields.
</Info>

### Artifact language versus Skill language

The Skill language selected by `comet init` determines which localized Skills are installed. Classic artifact language is stored in `classic.language`; Native artifact language is stored in `native.language`:

| Init selection              | Installed Skill | Classic                   | Native                   |
| --------------------------- | --------------- | ------------------------- | ------------------------ |
| `English` / `--language en` | English Skills  | `classic.language: en`    | `native.language: en`    |
| `中文` / `--language zh`      | Chinese Skills  | `classic.language: zh-CN` | `native.language: zh-CN` |

When a new Classic change is created, Comet snapshots project-level `classic.language` into `<classic-root>/changes/<name>/.comet.yaml`. OpenSpec proposal, design, tasks, Superpowers design/plan artifacts, verification reports, and archive notes follow this configured language instead of guessing from whichever request triggered the workflow.

If you continue the same change in a mixed English/Chinese session, Comet reads the change-level `language` and keeps artifacts stable. To switch an existing change's artifact language, change the change-level field:

```bash theme={null}
comet state set <change-name> language en
comet state set <change-name> language zh-CN
```

Global `comet init` and `comet update` persist the selected artifact language in `~/.comet/config.yaml`. New Classic changes prefer project `classic.language` and fall back to the global default only when it is absent. Native uses its separate `native.language` and does not read this Classic global fallback.

<Warning>
  Project-level and change-level language values only accept <code>en</code> or <code>zh-CN</code>.{' '}
  <code>zh</code> is only a <code>comet init --language zh</code> CLI selection value; it is not
  valid inside <code>.comet/config.yaml</code>.
</Warning>

Comet guard checks the dominant language of key workflow artifacts. If the configured value is `en` but `proposal.md`, `tasks.md`, or `design.md` are clearly Chinese-dominant, guard blocks phase advancement. The reverse is also true for `zh-CN`. Fenced code blocks are ignored, so commands, paths, hashes, or logs do not skew the check.

## Configuration precedence

The following precedence applies only to Classic `language`, `context_compression`, `review_mode`, and `auto_transition`. Shared entry fields and `native.*` do not use Classic change-level overrides:

```text theme={null}
change-level .comet.yaml field > environment variable > project-level .comet/config.yaml > global language default > built-in default
```

| Layer                              | Description                                                                                                         | Set by                                                              |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Change-level `.comet.yaml`         | Highest priority. Snapshotted from project config when the change is created, then updated by `/comet` phase Skills | Comet                                                               |
| Environment variables              | Used only when the change-level field is empty; useful for CI/CD overrides                                          | `export COMET_AUTO_TRANSITION=true` / `export COMET_LANGUAGE=zh-CN` |
| Project-level `.comet/config.yaml` | Fallback when no change-level field or environment override exists                                                  | User or init                                                        |
| Global `~/.comet/config.yaml`      | Cross-project fallback for `language` only; project config wins                                                     | Global init/update                                                  |
| Default                            | Last fallback                                                                                                       | See the table above                                                 |

## Change state: `.comet.yaml`

Each active OpenSpec change has one:

```text theme={null}
<classic-root>/changes/<name>/.comet.yaml
```

Important user-visible fields include:

| Field                  | Type / values                                          | Meaning                                                                                                                                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow`             | `full` \| `hotfix` \| `tweak`                          | Workflow preset                                                                                                                                                                                                                                                            |
| `language`             | `en` \| `zh-CN`                                        | Primary artifact language, snapshotted from `.comet/config.yaml` when the change is created                                                                                                                                                                                |
| `phase`                | `open` \| `design` \| `build` \| `verify` \| `archive` | Current phase                                                                                                                                                                                                                                                              |
| `auto_transition`      | `true` \| `false`                                      | Whether the next Skill is called automatically                                                                                                                                                                                                                             |
| `isolation`            | `current` \| `branch` \| `worktree`                    | Workspace isolation. All three modes require an explicit user choice and bind the current Git branch of the directory where the setting command runs                                                                                                                       |
| `bound_branch`         | Git branch name or `null` (machine-owned)              | Branch bound to the workspace mode. Entry checks and the source-write guard block accidental drift; do not modify it with `set`                                                                                                                                            |
| `tdd_mode`             | `tdd` \| `direct`                                      | `tdd` enforces a failing test first per task; `direct` skips Red-Green-Refactor but still requires relevant tests and regression evidence                                                                                                                                  |
| `verify_mode`          | `light` \| `full`                                      | Verification depth                                                                                                                                                                                                                                                         |
| `verify_result`        | `pending` \| `pass` \| `fail`                          | Verification result                                                                                                                                                                                                                                                        |
| `verify_failures`      | integer (machine-owned)                                | Consecutive verification failure count. `verify-fail` increments it; `verify-pass` or `archive-reopen` resets it to `0`. At 3, the next failure requires the retry-limit strategy decision                                                                                 |
| `branch_status`        | `pending` \| `handled`                                 | Remote-delivery confirmation state. It stays `pending` through Verify. After the user confirms an immediate push or push plus PR before archiving, Archive writes `handled` before the one archive commit. It does not mean that push or PR creation has already succeeded |
| `archive_confirmation` | `null` \| `pending` \| `confirmed`                     | Machine-owned final approval; a mutating archive requires `confirmed`                                                                                                                                                                                                      |

<Warning>
  <code>build\_command</code> and <code>verify\_command</code> have been removed. The build guard
  detects npm, Maven, or Cargo commands. When it cannot infer an entrypoint, run the real command
  and record it with{' '}

  <code>
    comet state record-check \<change> \<build|verify> --command "..." --exit-code 0
  </code>

  . Recorded evidence cannot replace actual execution.
</Warning>

## State-machine constraints

Comet does not treat phase as a free-form note. Transitions must follow allowed events such as proposal approval, design approval, build completion, verify failure, or archive completion.

Before build can advance, `isolation` must be `current`, `branch`, or `worktree`, and the current Git branch must match `bound_branch`. If an entry check reports drift, prefer switching back. Only after explicitly deciding that the current branch should take over should you run:

```bash theme={null}
comet state rebind <change-name>
```

Rebinding appends an audit event and is rejected before the first binding or on a detached HEAD.

`verify-pass` requires an existing `verification_report`, advances to Archive, and leaves `branch_status: pending`. After archive confirmation and the archive operation, Comet writes `branch_status: handled`, runs the archive guard, and includes both `handled` and `archived: true` in the same commit before pushing.

## Boundary between workflow state and run state

`.comet.yaml` should stay readable and useful to humans. Detailed checkpoint data belongs in run state, where the runtime can manage it without polluting the main workflow file.

## Environment overrides

| Environment variable    | Purpose                                                         | Typical use                                                         |
| ----------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| `COMET_LANGUAGE`        | Overrides language when the change-level field is empty         | CI/CD or temporarily setting the artifact language for a new change |
| `COMET_AUTO_TRANSITION` | Overrides auto\_transition when the change-level field is empty | CI/CD or temporary manual control                                   |
| `COMET_FORCE_PHASE`     | Repair-only escape hatch for phase correction                   | Recovery with explicit human intent                                 |
| `COMET_OPENSPEC`        | Sets the OpenSpec CLI path                                      | Custom OpenSpec install location                                    |

## How to configure

Edit `.comet/config.yaml`:

```yaml theme={null}
schema: comet.project.v1
default_workflow: classic
workflows:
  - native
  - classic
ambient_resume: true
native:
  artifact_root: docs
  language: en
  clarification_mode: sequential
classic:
  language: en
  context_compression: beta
  review_mode: thorough
  auto_transition: true
```

For a temporary override:

```bash theme={null}
export COMET_LANGUAGE=zh-CN
export COMET_AUTO_TRANSITION=false
```