Migrate from Compozy v0.2.15 to CompozyOS v0.3

CompozyOS v0.3 is a hard cut, not an in-place compatibility release. It keeps the compozy binary and the .compozy/tasks/ task format, but replaces the workflow runner with a daemon-owned agent operating system. Runtime databases, command names, extension contracts, and review behavior do not carry forward automatically.

This guide uses v0.2.15 (8f8908afd70c731b815e20282bacad05aa026827) as the legacy baseline. Back up your global and workspace .compozy/ directories before changing installations.

1. Command map

Install the v0.3 beta through one of the beta paths. Replace beta.N with the published prerelease number when using the versioned Go command. Homebrew still serves v0.2 during the beta window and is therefore not an upgrade path.

npm install -g @compozy/cli@beta

curl -fsSL https://compozy.com/install.sh | \
  sh -s -- --version v0.3.0-beta.N

go install github.com/compozy/compozy@v0.3.0-beta.N

Workspace-scoped v0.3 commands infer the active workspace in this order: positional workspace ref, --workspace, COMPOZY_WORKSPACE, validated session identity, then the current working directory. Run commands anywhere under a registered workspace root. Use --workspace <id|name|path> only to override that context.

The primary delivery mappings are:

The complete v0.2 flag-family disposition is:

2. Configuration translation contract

The live config migrator is deferred, so this is both the manual mapping and the future Task 14 contract. Apply global and workspace changes separately. v0.3 precedence is per-run value, then workspace [loops.inputs.<loop>], then global input default, then the Loop definition default. Explicit false, 0, and valid empty strings remain present values.

Provider mapping is exact: codex → codex, claude → claude, cursor-agent → cursor, opencode → opencode, pi → pi, gemini → gemini, copilot → copilot, and kiro → kiro. Drop droid, devin, and legacy-only reasoning ultra as unsupported_destination_value; never silently alias or weaken them. The v0.2 schema had no persisted defaults.provider or defaults.pr, so do not fabricate either.

You can manage an input default manually now:

cd /absolute/project/root

compozy config set loops.inputs.software-delivery.auto_commit false \
  --scope workspace

compozy config get loops.inputs.software-delivery.auto_commit

compozy config unset loops.inputs.software-delivery.auto_commit \
  --scope workspace

These commands use cwd discovery. Set COMPOZY_WORKSPACE for a shell-wide override or pass --workspace <id|name|path> for a one-command override.

HTTP and UDS expose exact-scope inspect, replace, set, and delete operations under /api/workspaces/{workspace_id}/loops/{name}/input-defaults. Configured values are checked against the named Loop only during dry-run or submission, because Loops can enroll dynamically.

3. Config migrator status

compozy migrate config does not ship in this task or in the current v0.3 beta. Backup, idempotent rewrite, legacy-state first-boot probing, and the executable translation report are deferred to Task 14. Do not run that command, build automation around it, or assume the daemon will read v0.2 config as a fallback.

Until Task 14 ships:

1. Back up ~/.compozy/ and each <workspace>/.compozy/ directory.
2. Translate the config manually with the table above into a fresh v0.3 config.
3. Move legacy-owned agents/ and extensions/ directories out of the colliding .compozy/ namespace. Do not let v0.3 enroll their old formats.
4. Start v0.3 with clean runtime state; do not copy global.db, daemon sockets, locks, logs, run directories, or other v0.2 state into the new runtime.
5. Keep the backup until the beta journey and required task evidence have been verified.

The old v0.2 compozy migrate command is unrelated. It converts XML-tagged task and review artifacts into frontmatter. If your task tree still contains <task_context> or <review_context>, run the v0.2.15 converter before replacing the CLI. The future migrate config command is not a replacement for that artifact conversion.

4. Where the skills went

The v0.3 dev-cycle extension bundles exactly nine retained process skills:

• cy-create-prd
• cy-create-techspec
• cy-create-tasks
• cy-execute-task
• cy-workflow-memory
• cy-review-round
• cy-fix-reviews
• cy-final-verify
• git-rebase

They are versioned resources of the extension and are exposed through the runtime's skill/resource surfaces. The legacy compozy skill is retired; the new official skills/compozy/ guide is the runtime and contributor manual, not one of the nine dev-cycle process skills.

The v0.2 compozy setup helper copied or symlinked public skills and reusable AGENT.md files into external agent-CLI homes. v0.3 has no equivalent external-CLI installer. Use compozy skill for daemon-managed local or marketplace skills, compozy agent for runtime agent definitions, and compozy extension for versioned extension resources. Copying the old installed files forward does not make them compatible.

Process guidance must not call tasks validate: that command is removed and loop validate checks Loop definitions, not task artifacts. Use the validation gates that the selected Loop and repository actually provide.

5. Deferred and removed surfaces

This table is the exhaustive legacy-surface ledger. “Removed” means no compatibility alias, route, loader, or hidden fallback ships in v0.3.

The web route mapping is a semantic mapping, not a redirect promise. v0.3 intentionally ships no legacy route aliases.

Legacy README anchor disposition

The v0.2 README accumulated inbound links from package registries, search results, and external articles. The v0.3 front door keeps each semantic successor at the matching heading. Removed pipeline-era sections have no empty heading stub; their disposition is explicit here.

6. License metadata correction

Compozy remained MIT-licensed. Some old distribution metadata incorrectly stamped artifacts as BSL-1.1; v0.3 corrects that metadata to match the repository's MIT license. This is a distribution metadata correction, not a relicense.

7. Go library and SDK close-out

v0.3 is distributed as the CompozyOS binary and runtime, not as a compatibility release of the old public Go library. Code importing the root facade, pkg/compozy/events, pkg/compozy/runs, or the old Go extension SDK will not compile against v0.3. Pin the final v0.2.x module while you maintain that integration, or redesign it against v0.3 CLI/HTTP/UDS/tool/extension contracts.

The public npm extension packages remain on their v0.1.x line. They are not overwritten with the API-incompatible v0.3 workspaces. Repository contributors may use sdk/go, sdk/typescript, and sdk/create-extension at the exact repository version; those workspaces are private and are not a registry compatibility promise.

8. Domain, channels, and clean state

https://compozy.com serves the v0.3 site from the single cut. The former domain retires without a redirect layer. Legacy source and release collateral remain on the legacy/v0.2 branch.

During the beta window:

• use @compozy/cli@beta, the hosted installer with an explicit v0.3 beta, or versioned go install;
• do not use Homebrew for v0.3 — the formula remains on the deprecated v0.2 stable line until the post-beta 0.3.0 stable release;
• a beta self-update follows newer v0.3 prereleases, not npm latest or the v0.2 stable line.

Start runtime history clean. Preserve committable task artifacts under .compozy/tasks/, translate configuration manually, and do not carry daemon databases or legacy extension/setup directories into the new runtime. The task schema remains useful; runtime state does not.

For Git, keep authored task/config artifacts according to your repository policy and ignore runtime state inside the shared directory. At minimum, review rules for:

.compozy/compozy.db
.compozy/workspace.toml
.compozy/daemon.sock
.compozy/daemon.lock
.compozy/logs/
.compozy/cache/

Do not ignore the entire .compozy/ directory when the repository commits .compozy/tasks/, Loop definitions, skills, agents, or workspace configuration. After backup and manual translation, run a dry delivery plan first, inspect the reported input origins/runtime provenance, then start the real run and follow the final-line /loop-runs/<id> URL.