Migration Guide

Use this guide when you are moving an existing repo or team workflow onto the current SpecFact CLI model.

This page is intentionally focused on the active 0.4x.y line. It does not try to preserve every historical transition. If you are running a very old install, treat that as a staged migration: first get onto the modern grouped command surface, then validate your repo and bundle state.

What this guide covers

• Upgrading the core CLI to the current release line
• Moving from removed flat commands to grouped commands
• Importing existing work from external toolchains such as Spec-Kit or OpenSpec
• Revalidating bundles, sync flows, and docs links after the migration

Start here

Choose the path that matches your situation:

1. You already use modern grouped commands such as specfact project, specfact backlog, specfact code, specfact spec, and specfact govern. Upgrade the CLI, check installed modules, and run validation.
2. Your scripts still use older flat commands such as specfact plan, specfact import, specfact sync, specfact validate, or specfact enforce. Update those scripts to the grouped command surface before rolling the change out.
3. You are moving from another structured workflow tool such as Spec-Kit or OpenSpec. Import first, review the generated project state, then enable ongoing bridge sync only after the imported state looks correct.

1. Upgrade the active CLI

Check the current version first:

specfact --version
specfact upgrade --check-only

If an update is available:

specfact upgrade

After the upgrade:

specfact module list
specfact module search

Use those commands to confirm the CLI still sees the installed workflow modules and registries you expect.

2. Move to the grouped command surface

The current CLI is lean core plus mounted command groups. Core-owned commands stay at the root:

• specfact init
• specfact module
• specfact upgrade

Workflow capabilities are mounted under grouped families:

• specfact project ...
• specfact backlog ...
• specfact code ...
• specfact spec ...
• specfact govern ...

If your automation still uses older flat command paths, update them now.

Common replacements

Use the canonical mapping in the Command Reference when updating shell scripts, CI jobs, IDE prompts, or internal docs.

3. Rebaseline the project after the upgrade

Once the command surface is current, refresh the repo state you depend on:

specfact project health-check
specfact project regenerate

If you operate specific bundles directly:

specfact project snapshot --bundle my-bundle
specfact project version --bundle my-bundle

This is the point where you should catch stale bundle metadata, missing generated assets, or drift between the project state and the current CLI expectations.

4. Migrate from external toolchains

From Spec-Kit

If your repo still starts from Spec-Kit assets, import first and keep sync optional until you trust the imported state:

specfact code import from-bridge --adapter speckit --repo . --dry-run
specfact code import from-bridge --adapter speckit --repo . --write
specfact project devops-flow --stage develop --bundle my-bundle

Only enable ongoing sync after review:

specfact project sync bridge --adapter speckit --bundle my-bundle --repo . --bidirectional

For the fuller walkthrough, see Spec-Kit Journey Guide.

From OpenSpec

If you are moving existing OpenSpec project context into SpecFact-backed workflows:

specfact project sync bridge --adapter openspec --mode read-only --bundle my-bundle --repo .
specfact project devops-flow --stage develop --bundle my-bundle

Keep the first pass read-only until the imported state is reviewed. Then enable the sync mode you actually want.

For OpenSpec-specific context changes, see OpenSpec OPSX Migration.

5. Validate the migrated state

After any migration, run the checks that prove the new setup is usable:

specfact module list
specfact project health-check
specfact govern enforce sdd --bundle my-bundle
specfact spec validate --bundle my-bundle

Pick the bundle that matters most first. Once one representative bundle passes, roll the same checks across the rest of the repo.

6. Update team-facing surfaces

Do not stop at the CLI invocation itself. Migration is incomplete if these still point to the old world:

• CI workflows
• local shell scripts
• AI IDE prompt packs
• onboarding docs
• internal runbooks

The most common failure mode is that the repo has already migrated, but prompts and automation still tell people to use removed flat commands.

Historical note

Older version-specific migrations such as the 0.16 -> 0.19 transition are historical only. They should not be used as the primary upgrade path for teams already operating on the 0.4x.y line.

If you discover a repo that still depends on those assumptions, first update its command surface to the grouped model, then follow this guide.

See also

• specfact upgrade
• Command Reference
• CLI Reorganization Migration
• OpenSpec OPSX Migration
• Spec-Kit Journey Guide
• Troubleshooting Guide