Skip to main content
Native places the content that users need to read and synchronize in the “change” directory and the execution process at the project-level Runtime. You usually only need to look at the brief, Spec, comet-state.yaml and verification.md;

​
Project layout

The default layout is as follows:
<project>/
.comet/
config.yaml
current-change.json
runtime/native/
changes/<change-name>/
state.json
logs/
locks/
transactions/
docs/comet/
specs/
changes/
<change-name>/
brief.md
comet-state.yaml
specs/<capability>/
spec.md
verification.md
archive/
YYYY-MM-DD-<change-name>/
native.artifact_root can be changed to other relative directories within the project, such as artifacts/comet/. .comet/config.yaml and .comet/current-change.json are bound to the project. .comet/runtime/native/ is managed by the Runtime and is added to .gitignore and ignored by default; it is not copied to the change directory or committed as user documentation.

​
Three types of user-readable files

​
brief.md

The brief explains the objectives, scope, non-objectives, confirmed user decisions, unresolved issues, acceptance examples, and validation expectations. It is the working description of the Shape stage, and users can directly read and modify the requirements. When hand-editing the brief or a Spec, note where acceptance items come from: the Runtime generates acceptance items from only two places — the acceptance examples at the top level of the brief and the complete scenarios in a Spec whose headings start with Scenario:. Descriptive paragraphs, plain lists, and standalone WHEN/THEN lines are not recognized as acceptance items. So, to adjust the acceptance scope, you can only modify content in these two formats.

​
specs/<capability>/spec.md

A capability is a standalone feature of the project, such as “avatar upload” or “session timeout”. Specs are organized by feature, one directory per capability, and the spec.md in the directory describes the complete behavior of that feature after archiving. When archiving, the Runtime will execute create, modify or remove as declared: create, completely replace, or delete within the controlled path. To declare the removal of a capability, run comet native spec remove to express the removal intent — simply deleting the Spec file is not treated as a removal declaration, and that Spec is still handled as existing when archiving. When parallel changes try to modify the same capability, they will first stop to request a determination of the archiving sequence and will not automatically overwrite files.

​
comet-state.yaml

This is the stable state of cross-device recovery. It records the following:
  • the current stage and status;
  • Loop progress: iteration is the implementation round, incremented each time the Builder submits a new candidate implementation; attempt is the number of acceptance attempts on the same candidate implementation;
  • the complete acceptance items and results;
  • the Builder handoff: the handoff note the Builder writes when submitting a candidate implementation, describing this round of changes and declaring the affected acceptance items;
  • necessary check summaries, Verifier conclusions, and blocking causes;
  • the last 50 execution records and the next action.
After a session switch, device switch, or flow interruption, the Agent taking over has no previous conversation history. It first reads this file and then continues with the next action recorded in it (the continuation; for the complete field descriptions, see Task progress and interruption recovery).

​
verification.md

This is the user report generated by the Runtime based on the status, including actual checks, item-by-item acceptance, risks, limitations, and conclusions. It is a reconfigurable display file, not an input for the advancement stage. When missing or lagging, the Runtime can be rebuilt from comet-state.yaml.

​
Local Runtime

.comet/runtime/native/ only saves four kinds of local files: execution state files (overlays), logs, operation locks, and recoverable transactions. An operation lock is held only while a single operation runs, prevents two concurrent operations from modifying the same change at once, and is released when the operation ends. This directory may be missing due to equipment replacement or cleaning. The Runtime will rebuild based on the synchronized YAML and will not treat the local execution state as a cross-device fact. Logs are suitable for troubleshooting command output and cannot replace verification.md. For which components write these files, see Inside the Native Runtime. .comet/current-change.json only indicates which workflow/change the next write belongs to, and there is no restriction that a project can only have one active change. Status viewing is read-only. When it is necessary to clarify the ownership, use comet native select <change-name>.

​
Cross-device recovery

You don’t need to manually execute the recovery command. After pulling or synchronizing the project code on the target device, just tell the Agent to continue with the current requirements as usual. Comet will first attempt to find the active change through environment-aware recovery, and then the Agent will automatically complete the status reading, change selection and process advancement based on the workspace returned by the Runtime and the next action. What needs to be synchronized are the project code, .comet/config.yaml, brief.md, Specs and comet-state.yaml. If verification.md has already been generated, they can be synchronized together. Even if it is missing, the Runtime can rebuild it based on comet-state.yaml without preventing Shape or Build restoration. .comet/runtime/native/ is in the local execution state and does not require cross-device replication. When the target device lacks Runtime or the local execution status has expired, the Runtime will automatically rebuild based on the stable boundary recorded in comet-state.yaml. A check that is halfway through will be treated as an interrupt. Checks that need to be re-run will be executed again, and Verifier or archive-ready results that cannot be safely reused will be re-verified. The recovery will not rely on the state.json of the old device, nor will it directly archive the old Runtime file just because it has been copied. Comet will only stop to ask you to select or correct when the code is not synchronized, the current branch or worktree does not match the change, there are multiple workspaces that match the same, or there is a conflict between the active/archive directories. The following two commands are only used when you want to check the progress or troubleshoot problems. You can also open Comet Dashboard to check the progress:

​
Archive and delivery

The delivery choices when archiving — keep the workspace, merge locally, push, create a PR, or defer — are described in Archive and delivery.

​
After archiving

The successfully archived change only retains user-readable content such as brief, Specs, comet-state.yaml and verification.md. The local execution directory of this change in .comet/runtime/native/ will be cleared. The machine files left over from the old version are only processed through migration or read-only adapters and will not become input for the new Native process. Continue reading: Verification and Repair , Task progress and interruption recovery and Recovery Manual .
Last modified on September 4, 2026