Classic configuration

.comet/config.yaml is the single project-level configuration file. This page covers the shared entry fields and the classic.* defaults. See Native configuration for native.* fields. 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.

Complete example

When both workflows are enabled and the project uses English, an installation can generate a configuration like this. From the Classic perspective, the shared fields and the classic: block are the relevant parts:

schema: comet.project.v1
default_workflow: classic
workflows:
  - native
  - classic
ambient_resume: true

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

Shared entry fields

Field	Allowed values	Meaning
`schema`	`comet.project.v1`	Current structured project configuration version managed by Comet
`default_workflow`	`native` \| `classic`	Which permanent Skill `/comet` enters by default
`workflows`	`native`, `classic`, or both	Workflows enabled for the project; must include the default workflow
`ambient_resume`	`true` \| `false`	Whether the Agent may run the read-only recovery probe for ordinary natural-language continuation requests
`hook.allow_paths`	Project-relative directory list, empty by default	Project-relative directories the Agent may write during guarded phases; matching is by prefix and protected areas cannot be allowed. See Hook write allowlist

Changing default_workflow changes only the /comet entry. It does not migrate any existing change.

Hook write allowlist

hook.allow_paths is a shared write policy. When it is empty, writes inside the project outside artifact areas follow each workflow’s phase and Guard rules. Once configured, writes to matching directories and their subdirectories pass through directly. A typical use is allowing implementation directories such as src/ to be modified during any phase, avoiding blocks outside Build.

hook:
  allow_paths:
    - src
    - apps/web

The .comet Runtime state directory and Classic’s OpenSpec and Superpowers artifact roots are always protected and cannot be allowed through this setting. Out-of-bounds or malformed paths are reported by comet doctor.

Classic fields

artifact_layout selects the project-level directory; the other four fields are snapshotted into a new Classic change’s .comet.yaml:

Field	Allowed values	Default	Meaning
`classic.artifact_layout`	`legacy` \| `docs`	`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 reports, and archive notes
`classic.context_compression`	`off` \| `beta`	`off`	Controls context compression during the design-to-build handoff. See Context compression
`classic.review_mode`	`off` \| `standard` \| `thorough`	`standard` for full workflow	Controls code review strength. See Review mode
`classic.auto_transition`	`true` \| `false`	`true`	Controls whether Comet invokes the next phase Skill after phase advancement. See Automatic progression

Classic project defaults are snapshotted into .comet.yaml when a new change is created. Later edits do not rewrite existing changes.

Editing classic.artifact_layout changes where Comet reads artifacts but does not move existing files. To migrate an existing project, run comet classic root move docs —dry-run to inspect current state, conflicts, and blockers, then run comet classic root move docs —apply.

Artifact language versus Skill language

The Skill language selected by comet init determines whether the English or Chinese Comet Skills are installed. Classic artifact language is stored in classic.language:

Init selection	Installed Skill	`classic.language`
`English` / `--language en`	English Skills	`en`
`Chinese` / `--language zh`	Chinese Skills	`zh-CN`

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

Project-level and change-level language values accept only en or zh-CN. zh is only the CLI selection value for comet init —language zh; it is not valid inside .comet/config.yaml.

Configuration precedence

The following precedence applies only to Classic language, context_compression, review_mode, and auto_transition:

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

auto_transition in detail

auto_transition controls whether Comet invokes the next Skill after a phase advances.

Value	Behavior
`true` (default)	After Guard advances `phase`, it outputs `NEXT: auto` and invokes the next phase Skill automatically.
`false`	After Guard advances `phase`, it outputs `NEXT: manual` and prints a HINT for you to run the next Skill.

Phase advancement still happens. Guard’s —apply always updates the phase field regardless of auto_transition. The setting controls only whether the next Skill is invoked automatically. User decision points, such as approving a proposal or choosing an execution mode, block in either setting.

Environment variables

Environment variable	Purpose	Typical use
`COMET_LANGUAGE`	Overrides `language` when the change-level field is empty	CI/CD or temporary artifact language for a new change
`COMET_AUTO_TRANSITION`	Overrides `auto_transition` when the change-level field is empty	Temporary override
`COMET_CONTEXT_COMPRESSION`	Overrides `context_compression` when the change-level field is empty	Temporary compression-mode testing
`COMET_REVIEW_MODE`	Overrides default `review_mode` resolution	Temporary review-mode selection
`COMET_FORCE_PHASE`	Allows direct `set phase` when `=1` (repair escape hatch)	State repair and troubleshooting
`COMET_OPENSPEC`	Sets the OpenSpec CLI path; defaults to `openspec`	Custom OpenSpec installation

COMET_LANGUAGE, COMET_AUTO_TRANSITION, COMET_FORCE_PHASE, and COMET_OPENSPEC are user-facing environment variables. COMET_CONTEXT_COMPRESSION and COMET_REVIEW_MODE exist in the resolver layer but are not formally documented for general use; they are mainly for internal and test use.

How to configure

Configure project defaults

Edit .comet/config.yaml:

schema: comet.project.v1
default_workflow: classic
workflows:
  - native
  - classic
ambient_resume: true
classic:
  language: en
  context_compression: beta
  review_mode: thorough
  auto_transition: true

Commit the file so new changes created by teammates use the same defaults.

Temporary overrides with environment variables

export COMET_LANGUAGE=en
export COMET_AUTO_TRANSITION=false

These affect the current session without changing the file.

Next steps

State management — .comet.yaml field reference and state-machine constraints
Context compression — the off and beta modes
Review mode — the off, standard, and thorough modes
Automatic progression — how auto_transition behaves
Project file structure — where configuration and artifacts live

Understand Comet Classic

Five-phase workflow

Presets

Recovery and troubleshooting

Practical scenarios

Classic configuration

Complete example

Shared entry fields

Hook write allowlist

Classic fields

Artifact language versus Skill language

Configuration precedence

auto_transition in detail

Environment variables

How to configure

Configure project defaults

Temporary overrides with environment variables

Next steps

​Complete example

​Shared entry fields

​Hook write allowlist

​Classic fields

​Artifact language versus Skill language

​Configuration precedence

​auto_transition in detail

​Environment variables

​How to configure

​Configure project defaults

​Temporary overrides with environment variables

​Next steps

Complete example

Shared entry fields

Hook write allowlist

Classic fields

Artifact language versus Skill language

Configuration precedence

auto_transition in detail

Environment variables

How to configure

Configure project defaults

Temporary overrides with environment variables

Next steps