Skip to content

Upgrade an existing Spec Kitty project

Who is this for (1)

After upgrading the CLI, existing projects may need a one-time migration to match the new schema. This page walks through the project upgrade flow.

For upgrading the spec-kitty binary itself, see Upgrade the CLI.

When do I need this?

Run a project upgrade when:

  • You just upgraded the CLI (pipx upgrade --pip-args=--pre spec-kitty-cli or equivalent).
  • A spec-kitty command exits with code 4 and says This project needs Spec Kitty project migrations.
  • You opened an older project on a newer CLI for the first time.

If migrations are current, upgrade can still repair missing managed surfaces or provision missing activation metadata. A second successful run is a no-op only after those owners are current too.

The upgrade flow

From the project root:

Terminal window
cd /path/to/your/project
spec-kitty upgrade

You will see a summary of pending migrations and be asked to confirm. To preview without applying anything:

Terminal window
spec-kitty upgrade --dry-run

The preview heads its migration list Migrations that would be applied: and marks each entry with →, and its closing line repeats that nothing was written. A real run heads the same list Migrations applied: with ✓.

To apply without prompting (useful in CI):

Terminal window
spec-kitty upgrade --yes

For machine-readable output:

Terminal window
spec-kitty upgrade --dry-run --json

That command preserves the legacy compatibility schema. For the complete, preview-only owner plan use:

Terminal window
spec-kitty upgrade --plan-json

The full plan reports roots, exact physical effects, preserved dispositions, diagnostics, apply-only temporary artifacts, and commit policy. It cannot be replayed or used as consent. --yes and --force never make a preview write.

What spec-kitty upgrade does

The project upgrade runs config-aware migrations that bring your .kittify/ scaffold and agent surfaces in sync with the installed CLI. Specifically, it:

  1. Reads .kittify/config.yaml to learn which agents you have configured.
  2. Walks pending migrations in version order.
  3. Updates agent command directories for configured agents only (.claude/commands/, .agents/skills/spec-kitty-<command>/, .amazonq/prompts/, etc.). Agents you removed stay removed — migrations never recreate them.
  4. Refreshes templates and skill packages under those agent directories from the CLI’s bundled source templates.
  5. Bumps .kittify/metadata.yaml to record the new schema version.
  6. Leaves your data alone: kitty-specs/, architecture/, and any other content you authored is not touched.

Migrations are idempotent — running spec-kitty upgrade twice on the same project is safe.

If your project uses an Agent Skills harness (Codex, Vibe, Pi, Letta or Antigravity), the upgrade to 4.0.0rc8 renames the command skills from spec-kitty.<command> to spec-kitty-<command> and archives Antigravity’s old .agent/workflows/ files. Run it in every clone. See Command skills renamed for the Agent Skills specification.

Common follow-ups

After a successful project upgrade:

Terminal window
spec-kitty agent config sync # Reconcile filesystem with config.yaml
spec-kitty doctor # Health check

agent config sync is useful if you removed or added agents and want spec-kitty to ensure the filesystem matches your config.yaml. doctor surfaces any post-upgrade warnings.

Reviewing the changes

Project upgrades modify tracked files (agent command directories, metadata.yaml, sometimes templates). Review before committing:

Terminal window
git status
git diff

spec-kitty upgrade commits the files it changed itself when auto_commit is enabled (the default), and only those files; your own uncommitted work is left alone. If it reports that its changes were left uncommitted (auto-commit disabled, a hook rejected the commit, or files held for manual review), commit when you are satisfied by staging the listed files by name:

Terminal window
git add -- .kittify/metadata.yaml <other files git status lists>
git commit -m "chore: upgrade Spec Kitty project to <version>"

Or use spec-kitty safe-commit <those files> -m "chore: upgrade Spec Kitty project to <version>".

Files under kitty-specs/ are version-controlled and contain your mission history. Migrations should not touch them; if git diff shows changes there, stop and investigate.

If a Mission’s meta.json is missing

Each Mission’s kitty-specs/<slug>/meta.json carries its immutable mission_id. If git tracks that file but it is missing from your working tree — an accidental delete, or a partial/sparse checkout that excludes it — the upgrade rebuilds it from the copy git holds, so the Mission keeps the identity its history uses. A working-tree copy that has lost its mission_id takes the tracked one back. Nothing is re-identified.

When the tracked copy cannot be read, the upgrade writes nothing for that Mission and names it, for example:

kitty-specs/<slug>/meta.json: tracked meta.json is missing from the working tree and the committed copy is not a JSON object; no identity was minted — repair the committed copy (`git show HEAD:kitty-specs/<slug>/meta.json` shows it), commit the fix, then restore it with `git checkout -- kitty-specs/<slug>/meta.json`

Run the printed git checkout -- <path> and upgrade again. A meta.json git holds only in the index (staged, never committed) is reported the same way, with a note to commit it: its content is your working copy, not history’s identity.

A Mission folder outside any git checkout gets its identity normally, even when a .git sits above it, as long as that .git is empty or holds only hooks/ and spec-kitty-locks/ (leftovers, not a repository). When Git cannot answer and the .git above is a repository, or is neither a repository nor such leftovers (a lost or dangling HEAD, other contents, an entry that cannot be read), the upgrade refuses with TRACKED_META_UNAVAILABLE and names that .git. No git checkout -- is offered then, because it fails for the same reason. Repair the repository (for example restore its HEAD), or, if it is leftover residue holding nothing you need, remove it; then upgrade again. The same refusal applies while GIT_DIR, GIT_INDEX_FILE or another Git redirect is set: correct or unset it if it is unintended, otherwise repair the repository it selects.

Exit codes

CodeMeaningWhat to do
0Success / nothing to doContinue working.
2Usage error (e.g. --cli with --project)Fix command-line flags.
4Project needs migrationRun spec-kitty upgrade (this command).
5Project too new for CLIUpgrade the CLI first (pipx upgrade --pip-args=--pre spec-kitty-cli).
6Project metadata corruptCheck .kittify/metadata.yaml exists and is valid YAML.

For legacy --dry-run --json, a target refusal has semantic exit code 2 in the document but process code 0; the too-new-project exception remains process code 5. --plan-json reports its process code directly in process_exit_code.

Troubleshooting

spec-kitty upgrade errored after applying some migrations — Migrations commit progress to .kittify/metadata.yaml after each step. Fix the underlying error (often a permissions or PATH issue) and re-run spec-kitty upgrade; it will pick up where it left off.

My agent command directories changed but I want the old templates — Run git diff .claude/ (or the relevant agent path) to inspect. If you maintained local customizations on top of generated files, restore them and consider opening an issue so the upstream templates can incorporate the change.

spec-kitty upgrade says my project schema is too new — The installed CLI is older than the schema in .kittify/metadata.yaml. Upgrade the CLI: pipx upgrade --pip-args=--pre spec-kitty-cli.

I want to skip a specific migration — Migrations are non-optional; they exist because the runtime depends on the new layout. Investigate the root cause instead.

Rollback

A failed upgrade can be rolled back with git, since .kittify/, .claude/, and other agent directories are version-controlled:

Terminal window
git restore .kittify/ .claude/ .agents/skills/

Then reinstall the previous CLI version:

Terminal window
pipx install --force spec-kitty-cli==<previous-version>

See Uninstall for the full rollback procedure.

Next steps