Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.
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.
The command reports the resolved layout and paths. artifactLayout: "legacy" means the Classic root is openspec/; artifactLayout: "docs" means it is docs/openspec/.
Current layout
What to do
legacy
Continue to the dry run if you want the new layout.
docs
No migration is needed. Resume or advance the change with /comet.
Command fails
Run comet doctor, repair configuration, installation, or an incomplete migration, then retry.
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.
Migration moves the completeopenspec/ 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:
comet classic root move docs --dry-run
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.
Common blockers and how to handle them:
Preflight result
Cause
What to do
The docs target is non-empty
docs/openspec/ already contains content that cannot be proven to belong to this migration
Preserve and inspect that content; do not overwrite it with the migration command.
A root migration is pending recovery
A previous migration left a transaction record
Complete “Recover an interrupted migration”, then run the dry run again.
Classic is disabled or configuration is incompatible
The project cannot be migrated as a Classic project
Use comet doctor to diagnose configuration and installation; do not create migration records manually.
Conflicts or blockers
The source, target, or configuration does not meet the safety conditions
Resolve the reported conflict, then run the dry run again.
After the preflight succeeds, run this from the same project root:
comet classic root move docs --apply
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:
comet classic root show
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.
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:
comet doctor
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:
comet doctor --repair --strategy continue
To abandon the migration, when diagnostics allow rollback, run:
comet doctor --repair --strategy rollback
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.
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 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 state and artifacts.
Project file structure — See where Classic artifacts, runtime state, and configuration live
Last modified on September 2, 2026
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"Comet Docs","description":"Comet Docs: Agent Skill Harness Phase-Guarded Automation From Idea To Archive","colors":{"primary":"#0063F8","light":"#0063F8","dark":"#0063F8"},"logo":{"light":"https://mintcdn.com/comet-bb5f5294/Xj3ZPGe1ViheLZzP/logo/logo-light-v2.png?fit=max\u0026auto=format\u0026n=Xj3ZPGe1ViheLZzP\u0026q=85\u0026s=76b3e8ed7c70589aec871ad45d4c0a48","dark":"https://mintcdn.com/comet-bb5f5294/Xj3ZPGe1ViheLZzP/logo/logo-dark-v2.png?fit=max\u0026auto=format\u0026n=Xj3ZPGe1ViheLZzP\u0026q=85\u0026s=b60cce62802d3fe0f2640cd794fe2dae","href":"https://docs.comet.rpamis.com/"},"favicon":"https://mintcdn.com/comet-bb5f5294/anG611vGlISWXx6u/logo/favicon.png?fit=max\u0026auto=format\u0026n=anG611vGlISWXx6u\u0026q=85\u0026s=5cc1f88cea1d61472b3594828f256c5a","appearance":{"default":"light","strict":true},"seo":{"metatags":{"og:site_name":"Comet Docs","og:skill":"Comet Skill","og:eval":"Comet Eval","og:agent":"Comet","og:skill_creator":"Comet Any"},"indexing":"all"},"fonts":{"family":"Source Serif 4"},"icons":{"library":"fontawesome"},"metadata":{"timestamp":true},"styling":{"latex":false},"navigation":{"languages":[{"language":"zh","default":true,"footer":{"socials":{"x":"https://x.com/rpamis","github":"https://github.com/rpamis/comet"}},"navbar":{"links":[{"href":"/zh/home","label":"首页"},{"href":"/zh/overview","label":"文档"},{"href":"/zh/changelog","label":"Changelog"},{"href":"/zh/tech-blog","label":"技术博客"},{"href":"/zh/sponsor","label":"赞助"}],"primary":{"type":"button","label":"GitHub","href":"https://github.com/rpamis/comet"}},"href":"zh/home"},{"language":"en","footer":{"socials":{"x":"https://x.com/rpamis","github":"https://github.com/rpamis/comet"}},"navbar":{"links":[{"href":"/en/home","label":"Home"},{"href":"/en/overview","label":"Docs"},{"href":"/en/changelog","label":"Changelog"},{"href":"/en/tech-blog","label":"Tech blog"},{"href":"/en/sponsor","label":"Sponsor"}],"primary":{"type":"button","label":"GitHub","href":"https://github.com/rpamis/comet"}},"href":"en/home"}]}},"deployment":{"deploymentMetadataValue":{"subdomain":"comet-bb5f5294","hasAudioNarration":false,"actualSubdomain":"comet-bb5f5294","customDomains":["docs.comet.rpamis.com"],"gitSource":{"type":"github","owner":"rpamis","repo":"comet-website-docs","deployBranch":"master","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"collectionId":"5e823de5-642d-41a5-925c-5c3d55dcc1ca","liveDeploymentHistoryId":"6ae09f72b64cd9c8a5d3b054","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae09f72b64cd9c8a5d3b054"},"feedback":{"thumbs":true},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ae09f72b64cd9c8a5d3b054","clientVersion":"0.0.4006","searchFilterCounts":[{"language":"en","tag":"Native mode","count":27},{"language":"zh","tag":"Native 模式","count":27},{"language":"en","tag":"Classic Spec mode","count":25},{"language":"zh","tag":"经典Spec模式","count":24},{"language":"en","tag":"CLI","count":22},{"language":"zh","tag":"CLI","count":22},{"language":"en","tag":"SDK","count":18},{"language":"zh","tag":"SDK","count":18},{"language":"en","tag":"Evaluate any Skill","count":16},{"language":"zh","tag":"评估任意Skill","count":15},{"language":"en","tag":"Advanced","count":14},{"language":"en","tag":"Get started","count":10},{"language":"en","tag":"Compose any Skill","count":10},{"language":"zh","tag":"组合任意 Skill","count":10},{"language":"en","tag":"Understand Comet Classic","count":9},{"language":"zh","tag":"理解 Comet Classic","count":9},{"language":"en","tag":"FAQ","count":8},{"language":"zh","tag":"常见问题","count":8},{"language":"zh","tag":"安装和健康检查","count":8},{"language":"zh","tag":"实践场景","count":8}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":false}},"googleFontsInlined":true},"customCss":[{"filePath":"custom.css","href":"/_mintlify/custom/comet-bb5f5294/bd194e706d0722f7/custom.css"}],"page":{"pagePath":"en/guides/classic-layout-migration","slug":"/en/guides/classic-layout-migration","pageMetadata":{"title":"Migrate the Classic layout","description":"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.","href":"/en/guides/classic-layout-migration"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Classic supports two OpenSpec layouts: older projects use root-level `,_jsx(_components.code,{children:`openspec/`}),`, while new projects use `,_jsx(_components.code,{children:`docs/openspec/`}),`. `,_jsx(_components.code,{children:`.comet/config.yaml`}),` selects the layout with `,_jsx(_components.code,{children:`classic.artifact_layout`}),`, but `,_jsx(_components.strong,{children:`changing that field alone does not migrate the directory`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`This page covers Classic layout migration and recovery of its migration transaction. For a normal interrupted session, device switch, or context compaction, run `,_jsx(_components.a,{href:`/en/guides/resuming-workflow`,children:_jsx(_components.code,{children:`/comet`})}),` again.`]}),`\n`,_jsx(Heading,{level:`2`,id:`check-whether-migration-is-needed`,children:`Check whether migration is needed`}),`\n`,_jsx(_components.p,{children:`From the project root, run:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` show`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The command reports the resolved layout and paths. `,_jsx(_components.code,{children:`artifactLayout: \"legacy\"`}),` means the Classic root is `,_jsx(_components.code,{children:`openspec/`}),`; `,_jsx(_components.code,{children:`artifactLayout: \"docs\"`}),` means it is `,_jsx(_components.code,{children:`docs/openspec/`}),`.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Current layout`}),_jsx(_components.th,{children:`What to do`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`legacy`})}),_jsx(_components.td,{children:`Continue to the dry run if you want the new layout.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`docs`})}),_jsxs(_components.td,{children:[`No migration is needed. Resume or advance the change with `,_jsx(_components.code,{children:`/comet`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Command fails`}),_jsxs(_components.td,{children:[`Run `,_jsx(_components.code,{children:`comet doctor`}),`, repair configuration, installation, or an incomplete migration, then retry.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`docs`}),` is the default layout for new Classic projects. Existing projects retain their detected `,_jsx(_components.code,{children:`legacy`}),` layout. Both are supported, so do not interrupt active work only to migrate.`]}),`\n`,_jsx(Heading,{level:`2`,id:`check-before-migrating`,children:`Check before migrating`}),`\n`,_jsxs(_components.p,{children:[`Migration moves the `,_jsx(_components.strong,{children:`complete`}),` `,_jsx(_components.code,{children:`openspec/`}),` tree, including active changes, archived changes, specifications, and configuration. Ask collaborators to stop writing Classic artifacts, then commit or stash the current worktree.`]}),`\n`,_jsx(_components.p,{children:`Run the read-only preflight:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` move`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` docs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dry-run`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`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 `,_jsx(_components.code,{children:`ready to apply: yes`}),`.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Do not edit `,_jsx(`code`,{children:`openspec/`}),`, `,_jsx(`code`,{children:`docs/openspec/`}),`, or`,` `,`\n`,_jsx(`code`,{children:`.comet/config.yaml`}),`\nbetween dry run and apply. The migration checks their identities again and\nstops rather than overwriting new content.`]})}),`\n`,_jsx(_components.p,{children:`Common blockers and how to handle them:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Preflight result`}),_jsx(_components.th,{children:`Cause`}),_jsx(_components.th,{children:`What to do`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`The `,_jsx(_components.code,{children:`docs`}),` target is non-empty`]}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`docs/openspec/`}),` already contains content that cannot be proven to belong to this migration`]}),_jsx(_components.td,{children:`Preserve and inspect that content; do not overwrite it with the migration command.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A root migration is pending recovery`}),_jsx(_components.td,{children:`A previous migration left a transaction record`}),_jsx(_components.td,{children:`Complete “Recover an interrupted migration”, then run the dry run again.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Classic is disabled or configuration is incompatible`}),_jsx(_components.td,{children:`The project cannot be migrated as a Classic project`}),_jsxs(_components.td,{children:[`Use `,_jsx(_components.code,{children:`comet doctor`}),` to diagnose configuration and installation; do not create migration records manually.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Conflicts or blockers`}),_jsx(_components.td,{children:`The source, target, or configuration does not meet the safety conditions`}),_jsx(_components.td,{children:`Resolve the reported conflict, then run the dry run again.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`apply-the-migration`,children:`Apply the migration`}),`\n`,_jsx(_components.p,{children:`After the preflight succeeds, run this from the same project root:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` move`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` docs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --apply`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`In the current release, `,_jsx(_components.code,{children:`--apply`}),` does not take a plan ID. Comet rechecks the preflight boundaries, copies and verifies the complete tree, changes `,_jsx(_components.code,{children:`classic.artifact_layout`}),` to `,_jsx(_components.code,{children:`docs`}),`, and then cleans up the old root. It preserves change runtime state, checkpoints, trajectory, handoffs, and archived evidence pointers.`]}),`\n`,_jsx(_components.p,{children:`After the command reports completion, confirm the new root:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` show`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The output should show `,_jsx(_components.code,{children:`artifactLayout: \"docs\"`}),` and `,_jsx(_components.code,{children:`openSpecRoot: \"docs/openspec\"`}),`. You can now run `,_jsx(_components.code,{children:`/comet`}),` again so Classic discovers and resumes active changes from the new path.`]}),`\n`,_jsx(Heading,{level:`2`,id:`recover-an-interrupted-migration`,children:`Recover an interrupted migration`}),`\n`,_jsxs(_components.p,{children:[`If `,_jsx(_components.code,{children:`--apply`}),` stops because of an interrupted process, changed files, or another error, do not move directories manually, delete `,_jsx(_components.code,{children:`.comet/classic-root-move.json`}),`, or edit `,_jsx(_components.code,{children:`classic.artifact_layout`}),` directly. Doing so removes the evidence Comet uses to determine which tree is trustworthy.`]}),`\n`,_jsx(_components.p,{children:`Diagnose the transaction first:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` doctor`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`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:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` doctor`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --repair`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --strategy`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` continue`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`To abandon the migration, when diagnostics allow rollback, run:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` doctor`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --repair`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --strategy`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` rollback`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`continue`}),` and `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(_components.p,{children:`After recovery, run:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` show`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`comet`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` classic`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` root`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` move`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` docs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dry-run`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The first command confirms the authoritative root. The second explicitly reports that `,_jsx(_components.code,{children:`docs/openspec/`}),` needs no repeat migration when it is already active; otherwise it gives fresh readiness and blockers for the `,_jsx(_components.code,{children:`legacy`}),` layout.`]}),`\n`,_jsx(Heading,{level:`2`,id:`troubleshoot-after-migration`,children:`Troubleshoot after migration`}),`\n`,_jsxs(_components.p,{children:[`If `,_jsx(_components.code,{children:`/comet`}),` does not find the expected change after migration, check in this order:`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Run `,_jsx(_components.code,{children:`comet classic root show`}),` and confirm that `,_jsx(_components.code,{children:`changesRoot`}),` is `,_jsx(_components.code,{children:`docs/openspec/changes/`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Confirm that active changes are in that directory and archived changes are in `,_jsx(_components.code,{children:`docs/openspec/changes/archive/`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Run `,_jsx(_components.code,{children:`comet status`}),` to inspect phase, task progress, and `,_jsx(_components.code,{children:`runtime_eval`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Run `,_jsx(_components.code,{children:`comet doctor`}),` to repair installation, configuration, or evidence findings.`]}),`\n`,_jsxs(_components.li,{children:[`Run `,_jsx(_components.code,{children:`/comet`}),` again so Classic resumes from the current file state.`]}),`\n`]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`classic.artifact_layout`}),` selects only the Classic OpenSpec root. Native uses\nits separate `,_jsx(_components.code,{children:`native.artifact_root`}),`; migrating Classic does not move Native\n`,_jsx(_components.code,{children:`comet/`}),` artifacts.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`do-not-do-this`,children:`Do not do this`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Do not move `,_jsx(_components.code,{children:`openspec/`}),` manually with a file manager or `,_jsx(_components.code,{children:`mv`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Do not change only `,_jsx(_components.code,{children:`classic.artifact_layout`}),` to `,_jsx(_components.code,{children:`docs`}),`.`]}),`\n`,_jsx(_components.li,{children:`Do not create, archive, or edit Classic changes while a migration transaction is unresolved.`}),`\n`,_jsx(_components.li,{children:`Do not delete the migration journal, staging directory, or quarantine directory to “unblock” the migration.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`These directories and configuration fields must switch in one transaction. Use `,_jsx(_components.code,{children:`comet classic root move`}),` and `,_jsx(_components.code,{children:`comet doctor --repair`}),` so recovery can verify and preserve all Classic state and artifacts.`]}),`\n`,_jsx(Heading,{level:`2`,id:`next-steps`,children:`Next steps`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/en/guides/resuming-workflow`,children:`Resuming interrupted work`}),` — Recover a normally interrupted Classic change`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/en/guides/state-recovery`,children:`Broken state and recovery`}),` — Diagnose routing, state, and evidence problems`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/en/guides/project-structure`,children:`Project file structure`}),` — See where Classic artifacts, runtime state, and configuration live`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Migrate the Classic layout","description":"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.","href":"/en/guides/classic-layout-migration"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Check whether migration is needed","slug":"check-whether-migration-is-needed","depth":2,"children":[]},{"title":"Check before migrating","slug":"check-before-migrating","depth":2,"children":[]},{"title":"Apply the migration","slug":"apply-the-migration","depth":2,"children":[]},{"title":"Recover an interrupted migration","slug":"recover-an-interrupted-migration","depth":2,"children":[]},{"title":"Troubleshoot after migration","slug":"troubleshoot-after-migration","depth":2,"children":[]},{"title":"Do not do this","slug":"do-not-do-this","depth":2,"children":[]},{"title":"Next steps","slug":"next-steps","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/comet-bb5f5294/f0132c0024de36f6/homepage-fonts.js"],"subdomain":"comet-bb5f5294","siteName":"Comet Docs","title":"Migrate the Classic layout - Comet Docs","navMaps":{"firstHrefInVersion":{"0.5.1":{"href":"/en/guides/classic-layout-migration","matchLevel":0}},"firstHrefInLanguage":{"zh":{"href":"/zh/guides/classic-layout-migration","matchLevel":1},"en":{"href":"/en/guides/classic-layout-migration","matchLevel":0}}},"lastModified":"2026-09-02T13:30:38.046Z","gitLastModified":"2026-09-02T13:29:34.000Z","originalFileLocation":"en/guides/classic-layout-migration.mdx","locale":"en"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=\"light\";if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Comet Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Migrate the Classic layout - Comet Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Comet Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://comet-bb5f5294.mintlify.app/_mintlify/api/og/v2?division=Recovery+and+troubleshooting\u0026amp;title=Migrate+the+Classic+layout\u0026amp;description=Safely+migrate+openspec%2F+to+docs%2Fopenspec%2F%2C+handle+an+interrupted+migration%2C+and+troubleshoot+recovery+after+migration.\u0026amp;theme=6192ba6a94e856348b304622\u0026amp;signature=fb786f8ac3d7e4171bb371f9749ec2cdf14eb381808c1ca89c8c924c4c633d88\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Migrate the Classic layout - Comet Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://comet-bb5f5294.mintlify.app/_mintlify/api/og/v2?division=Recovery+and+troubleshooting\u0026amp;title=Migrate+the+Classic+layout\u0026amp;description=Safely+migrate+openspec%2F+to+docs%2Fopenspec%2F%2C+handle+an+interrupted+migration%2C+and+troubleshoot+recovery+after+migration.\u0026amp;theme=6192ba6a94e856348b304622\u0026amp;signature=fb786f8ac3d7e4171bb371f9749ec2cdf14eb381808c1ca89c8c924c4c633d88\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/comet-bb5f5294/sj629fg8tNOIueNI/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Comet Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0063F8\">\u003cmeta data-mint-head name=\"og:skill\" content=\"Comet Skill\">\u003cmeta data-mint-head name=\"og:eval\" content=\"Comet Eval\">\u003cmeta data-mint-head name=\"og:agent\" content=\"Comet\">\u003cmeta data-mint-head name=\"og:skill_creator\" content=\"Comet Any\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/en/guides/classic-layout-migration.md\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"en\" href=\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"zh\" href=\"https://docs.comet.rpamis.com/zh/guides/classic-layout-migration\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"x-default\" href=\"https://docs.comet.rpamis.com/zh/guides/classic-layout-migration\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.comet.rpamis.com/#organization\",\"name\":\"Comet Docs\",\"url\":\"https://docs.comet.rpamis.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/comet-bb5f5294/Xj3ZPGe1ViheLZzP/logo/logo-light-v2.png?fit=max\u0026auto=format\u0026n=Xj3ZPGe1ViheLZzP\u0026q=85\u0026s=76b3e8ed7c70589aec871ad45d4c0a48\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.comet.rpamis.com#website\",\"name\":\"Comet Docs\",\"url\":\"https://docs.comet.rpamis.com\",\"publisher\":{\"@id\":\"https://docs.comet.rpamis.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration#webpage\",\"url\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\",\"name\":\"Migrate the Classic layout\",\"description\":\"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\",\"dateModified\":\"2026-09-02T13:29:34.000Z\",\"isPartOf\":{\"@id\":\"https://docs.comet.rpamis.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Recovery and troubleshooting\",\"item\":\"https://docs.comet.rpamis.com/en/guides/resuming-workflow\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Migrate the Classic layout\",\"item\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration#article\",\"headline\":\"Migrate the Classic layout\",\"name\":\"Migrate the Classic layout\",\"description\":\"Safely migrate openspec/ to docs/openspec/, handle an interrupted migration, and troubleshoot recovery after migration.\",\"url\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration\",\"mainEntityOfPage\":{\"@id\":\"https://docs.comet.rpamis.com/en/guides/classic-layout-migration#webpage\"},\"dateModified\":\"2026-09-02T13:29:34.000Z\",\"publisher\":{\"@id\":\"https://docs.comet.rpamis.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.comet.rpamis.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Comet Docs\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Comet Docs","nav":{"global":null,"languages":[{"language":"zh","default":true,"footer":{"socials":{"x":"https://x.com/rpamis","github":"https://github.com/rpamis/comet"}},"navbar":{"links":[{"href":"/zh/home","label":"首页"},{"href":"/zh/overview","label":"文档"},{"href":"/zh/changelog","label":"Changelog"},{"href":"/zh/tech-blog","label":"技术博客"},{"href":"/zh/sponsor","label":"赞助"}],"primary":{"type":"button","label":"GitHub","href":"https://github.com/rpamis/comet"}},"pages":[{"title":"zh","href":"/zh/guides/classic-layout-migration"}]},{"language":"en","footer":{"socials":{"x":"https://x.com/rpamis","github":"https://github.com/rpamis/comet"}},"navbar":{"links":[{"href":"/en/home","label":"Home"},{"href":"/en/overview","label":"Docs"},{"href":"/en/changelog","label":"Changelog"},{"href":"/en/tech-blog","label":"Tech blog"},{"href":"/en/sponsor","label":"Sponsor"}],"primary":{"type":"button","label":"GitHub","href":"https://github.com/rpamis/comet"}},"versions":[{"version":"0.5.1","tabs":[{"tab":"Native mode","icon":"meteor","pages":[{"title":"Native mode","href":"/en/overview"}]},{"tab":"Classic Spec mode","icon":"signature","groups":[{"group":"Understand Comet Classic","pages":[{"title":"Classic Workflow","href":"/en/concepts/workflow"},{"title":"Classic state management and recovery","href":"/en/concepts/state-management"},{"title":"Classic Configuration","href":"/en/classic/configuration"},{"title":"Intent Recognition and Routing","href":"/en/concepts/intent-routing"},{"title":"Auto-transition","href":"/en/concepts/auto-transition"},{"title":"Workflow Intermediate Products","href":"/en/concepts/intermediate-artifacts"},{"title":"Five-Stage Pause Points and User Selection Points","href":"/en/concepts/decision-points"},{"title":"Context Compression Mechanism","href":"/en/concepts/context-compression"},{"title":"Code Review Mechanism","href":"/en/concepts/review-mode"}]},{"group":"Five-phase workflow","pages":[{"title":"open Stage","href":"/en/phases/open"},{"title":"design Stage","href":"/en/phases/design"},{"title":"build Phase","href":"/en/phases/build"},{"title":"Phase 4: Verify","sidebarTitle":"Verify","href":"/en/phases/verify"},{"title":"Phase 5: Archive","sidebarTitle":"Archive","href":"/en/phases/archive"}]},{"group":"Presets","pages":[{"title":"hotfix preset","href":"/en/presets/hotfix"},{"title":"tweak preset","href":"/en/presets/tweak"}]},{"group":"Recovery and troubleshooting","pages":[{"title":"Resuming Interrupted Work","href":"/en/guides/resuming-workflow"},{"title":"State Damage and Recovery","description":"How to diagnose and restore using comet status/comet doctor when the Classic route is incorrect,.comet.yaml is missing or the format is abnormal, or the evidence is missing. ","href":"/en/guides/state-recovery"},{"title":"Migrate the Classic layout","href":"/en/guides/classic-layout-migration"},{"title":"Project file structure","description":"Understand the directories and files Comet creates in a project, and how each category supports recovery and troubleshooting.","href":"/en/guides/project-structure"}]},{"group":"Practical scenarios","pages":[{"title":"Integration of Existing Projects into Classic","href":"/en/guides/existing-project"},{"title":"Large PRD Splitting","href":"/en/guides/prd-splitting"},{"title":"Change Spec or roll back mid-workflow","href":"/en/guides/mid-workflow-changes"},{"title":"CI/CD integration","href":"/en/guides/cicd-integration"}]}]},{"tab":"Compose any Skill","icon":"wand-magic-sparkles","pages":[{"title":"Compose any Skill","href":"/en/skill-creator/getting-started"}]},{"tab":"Evaluate any Skill","icon":"vial-circle-check","pages":[{"title":"Evaluate any Skill","href":"/en/eval/quickstart"}]},{"tab":"Plugin hub","icon":"puzzle-piece","pages":[{"title":"Plugin hub","href":"/en/plugins/agent-learning-loop"}]},{"tab":"CLI","icon":"terminal","pages":[{"title":"CLI","href":"/en/cli/init"}]},{"tab":"SDK","icon":"layer-group","pages":[{"title":"SDK","href":"/en/sdk/overview"}]},{"tab":"FAQ","icon":"circle-question","pages":[{"title":"FAQ","href":"/en/guides/install-and-update"}]}]}]}]},"title":"Migrate the Classic layout - Comet Docs","buildId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","deploymentId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","dynamics":[],"chunks":[]}
