State and configuration

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.

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.

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:

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

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

Changing default_workflow changes only the /comet entry and never migrates a change. Classic defaults are snapshotted into new changes; later edits do not rewrite existing changes.

Editing classic.artifact_layout changes where Comet reads artifacts but does not move existing files. To switch 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. The dry run does not issue a plan ID.

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

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

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:

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.

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

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:

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:

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

build_command and verify_command 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 withcomet state record-check <change> <build|verify> —command ”…” —exit-code 0. Recorded evidence cannot replace actual execution.

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:

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:

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:

export COMET_LANGUAGE=zh-CN
export COMET_AUTO_TRANSITION=false

Get started

Understand Comet

Five-phase workflow

Presets

Recovery and troubleshooting

Practical scenarios

State and configuration

Where to look first

Current change selection

Project defaults: `.comet/config.yaml`

Shared and Classic fields

Artifact language versus Skill language

Configuration precedence

Change state: `.comet.yaml`

State-machine constraints

Boundary between workflow state and run state

Environment overrides

How to configure

​Where to look first

​Current change selection

​Project defaults: .comet/config.yaml

​Shared and Classic fields

​Artifact language versus Skill language

​Configuration precedence

​Change state: .comet.yaml

​State-machine constraints

​Boundary between workflow state and run state

​Environment overrides

​How to configure

Where to look first

Current change selection

Project defaults: `.comet/config.yaml`

Shared and Classic fields

Artifact language versus Skill language

Configuration precedence

Change state: `.comet.yaml`

State-machine constraints

Boundary between workflow state and run state

Environment overrides

How to configure