Classic supports two OpenSpec layouts: older projects use root-level openspec/, while new projects use docs/openspec/. .comet/config.yaml selects the layout with classic.artifact_layout, but changing that field alone does not migrate the directory.
This page covers Classic layout migration and recovery of its migration transaction. For a normal interrupted session, device switch, or context compaction, run /comet again.
Check whether migration is needed
From the project root, run:
The command reports the resolved layout and paths. artifactLayout: "legacy" means the Classic root is openspec/; artifactLayout: "docs" means it is docs/openspec/.
docs is the default layout for new Classic projects. Existing projects retain their detected legacy layout. Both are supported, so do not interrupt active work only to migrate.
Check before migrating
Migration moves the complete openspec/ tree, including active changes, archived changes, specifications, and configuration. Ask collaborators to stop writing Classic artifacts, then commit or stash the current worktree.
Run the read-only preflight:
The preflight does not change files. It reports the source and target, file summary, configuration change, conflicts, blockers, and available recovery strategies. Continue only when it reports ready to apply: yes.
Do not edit openspec/, docs/openspec/, or
.comet/config.yaml
between dry run and apply. The migration checks their identities again and
stops rather than overwriting new content.
Apply the migration
After the preflight succeeds, run this from the same project root:
In the current release, --apply does not take a plan ID. Comet rechecks the preflight boundaries, copies and verifies the complete tree, changes classic.artifact_layout to docs, and then cleans up the old root. It preserves change runtime state, checkpoints, trajectory, handoffs, and archived evidence pointers.
After the command reports completion, confirm the new root:
The output should show artifactLayout: "docs" and openSpecRoot: "docs/openspec". You can now run /comet again so Classic discovers and resumes active changes from the new path.
Recover an interrupted migration
If --apply stops because of an interrupted process, changed files, or another error, do not move directories manually, delete .comet/classic-root-move.json, or edit classic.artifact_layout directly. Doing so removes the evidence Comet uses to determine which tree is trustworthy.
Diagnose the transaction first:
The diagnostic reports the migration stage, the source and target state, and the recovery strategies that are currently allowed. To finish the original migration, run:
To abandon the migration, when diagnostics allow rollback, run:
continue and rollback are not interchangeable. Comet accepts only a strategy that is still safe for the transaction stage. For example, it cannot roll back after configuration has switched. If a strategy is rejected, preserve the current files, resolve the reported conflict or restore from a trusted backup, and do not force-clean directories.
After recovery, run:
The first command confirms the authoritative root. The second explicitly reports that docs/openspec/ needs no repeat migration when it is already active; otherwise it gives fresh readiness and blockers for the legacy layout.
Troubleshoot after migration
If /comet does not find the expected change after migration, check in this order:
- Run
comet classic root show and confirm that changesRoot is docs/openspec/changes/.
- Confirm that active changes are in that directory and archived changes are in
docs/openspec/changes/archive/.
- Run
comet status to inspect phase, task progress, and runtime_eval.
- Run
comet doctor to repair installation, configuration, or evidence findings.
- Run
/comet again so Classic resumes from the current file state.
classic.artifact_layout selects only the Classic OpenSpec root. Native uses
its separate native.artifact_root; migrating Classic does not move Native
comet/ artifacts.
Do not do this
- Do not move
openspec/ manually with a file manager or mv.
- Do not change only
classic.artifact_layout to docs.
- Do not create, archive, or edit Classic changes while a migration transaction is unresolved.
- Do not delete the migration journal, staging directory, or quarantine directory to “unblock” the migration.
These directories and configuration fields must switch in one transaction. Use comet classic root move and comet doctor --repair so recovery can verify and preserve all Classic facts.
Next steps
