Table of Contents

Upgrade an existing Spec Kitty project

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 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 your project is already current, spec-kitty upgrade is a no-op.

The upgrade flow

From the project root:

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:

spec-kitty upgrade --dry-run

To apply without prompting (useful in CI):

spec-kitty upgrade --yes

For machine-readable output:

spec-kitty upgrade --dry-run --json

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.

Common follow-ups

After a successful project upgrade:

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:

git status
git diff

Commit when you are satisfied:

git add .kittify/ .claude/ .agents/skills/    # whichever directories changed
git commit -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.

Exit codes

Code Meaning What to do
0 Success / nothing to do Continue working.
2 Usage error (e.g. --cli with --project) Fix command-line flags.
4 Project needs migration Run spec-kitty upgrade (this command).
5 Project too new for CLI Upgrade the CLI first (pipx upgrade spec-kitty-cli).
6 Project metadata corrupt Check .kittify/metadata.yaml exists and is valid YAML.

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 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:

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

Then reinstall the previous CLI version:

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

See Uninstall for the full rollback procedure.

Next steps

Edit this page