/comet flow. These working files support context compression, state recovery, evidence recording, and phase handoff, while proposal/design/tasks/code remain the final deliverables.
Understanding these products can help you: quickly recover after context compression, know which file to look at when troubleshooting, and confirm the completeness of the lifecycle when archiving.
Product Overview
Each type of intermediate artifact supports context, recovery, handoff, or verification evidence.
The following text uses<classic-root> to represent the current Classic OpenSpec root directory: The default for new projects is docs/openspec/, and for projects that retain the old layout, it is openspec/. The actual location is determined by classic.artifact_layout. For details, please refer to Project File structure
.comet.yaml: The status file throughout the entire process
This is the only cross-phase state file of Comet. The fields should be filled in step by step as the stage progresses. For details, please refer to Status Management
Comet’s classic workflow still with
.com et. Yaml as source of the current state.
.comet/ state-events.jsonl is an appended audit log used to explain the history of state transitions;
.com et/run - state. Json and trajectory jsonl belongs to the machine - owned
Operational details. Across sessions recovery mainly by .com et. Yaml, handoff documents and checkpoints
When checking the status changes in markdown, look at the event log.State-events.jsonl (state Transition Audit)
It is not the source of the current state. The current status is still based on
.comet.yaml. The event log is suitable for answering: Was this phase modified through the guard, manual transition, or archive process? Which fields were actually changed?
Product of the design stage
The design stage is the one with the richest intermediate products, mainly serving context compression and the transition from OpenSpec to Superpowers.handoff handover bag
The handover package comes in two forms based on the
context_compression configuration:
The handover package also writes
handoff_context and handoff_hash to .comet.yaml. When guard leaves design, it recalculates the hash to detect drift. For details, please refer to Context Compression Mechanism ] and comet-handoff]
brainstorm-summary.md
It records:
- The confirmed technical solution
- Key trade-offs and risks
- Test strategy
- Spec Patch (if any)
- Unconfirmed items are marked as
pending/candidate
Product of the build stage
The intermediate products in the build stage mainly serve SubAgent scheduling recovery and task tracking.Implementation plan
The planned frontmatter is the evidence relied upon in the verification phase:
base-ref is the commit SHA before the implementation starts, and verify uses it to recalculate the change scale. Write the plan path to .comet.yaml.
subagent-progress.md
It records the scheduling status of the current task:
- The current plan task text + the corresponding OpenSpec task text
- At this stage (
implementing/task-review/checkoff/done/blocked) - The implemented commit hash, modified files, and RED/GREEN evidence
- Selected
review_mode - Passed review stages + unresolved reviewer feedback
- Current number of review-fix rounds
Check the status of tasks.md
Comet does not have a separate task checkbox file - the checkbox status is within
tasks.md. Use grep -c '\- \[ \]' tasks.md to count the unfinished items and comet-state task-checkoff <file> <text> to verify that a specific task has been selected.
In the SubAgent mode, the implementer ** cannot ** select tasks - only the main session selects the task after the task-level review required by review_mode has passed (in off mode there is no reviewer, so check-off relies on self-test evidence).
Product of the verify stage
Verification report
Write the
verification_report path to .comet.yaml. guard requires that this file must exist when verify-pass is converted.
Implementation Divergence Note (optional)
If the user chooses to accept the bias, the acceptance reason and its impact are recorded in the verification artifacts. When archiving, the Design Doc is annotated
archived-with through the normal flow.
Product of the archive stage
During the archive stage, no new files are created. Instead, existing products are annotated and directories are moved.frontmatter annotation
Archived catalogue
The entire change directory is moved to<classic-root>/changes/archive/YYYY-MM-DD-<name>/, including .comet.yaml, .comet/handoff/, .comet/subagent-progress.md and delta spec. After archiving, set .comet.yaml to archived: true.
Classify by purpose
A quick overview of the functions of the document
Next step
- Workflow concept ](/en/concepts/workflow) - The position of these products in the five stages
- Detailed Explanation of the ](/en/concepts/state-management)-
.comet.yamlfield in Status Management - Detailed Explanation of the Context Compression Mechanism ](/en/concepts/context-compression) - handoff handover Package
- comet-handoff](/en/scripts/comet-handoff) - Script details for generating handover packages
- Operation and Maintenance and troubleshooting - Use these products to resume interrupted work