---
type: "Guide"
title: "Upgrade an existing Spec Kitty project"
description: "Upgrade an existing project to the Spec Kitty 3.2 schema after installing the current CLI, with validation and recovery steps."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-06T00:00:00Z"
---

# 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](/guides/how-to/installation/upgrade-cli.md).

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

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

```bash
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):

```bash
spec-kitty upgrade --yes
```

For machine-readable output:

```bash
spec-kitty upgrade --dry-run --json
```

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

```bash
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](/migrations/command-skill-hyphen-names.md).

## Common follow-ups

After a successful project upgrade:

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

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

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

```text
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

| 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 --pip-args=--pre spec-kitty-cli`). |
| 6    | Project metadata corrupt | Check `.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:

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

Then reinstall the previous CLI version:

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

See [Uninstall](/guides/how-to/installation/uninstall.md) for the full rollback procedure.

## Next steps

- [Upgrade the CLI](/guides/how-to/installation/upgrade-cli.md)
- [Upgrade lifecycle reference](/api/upgrade-lifecycle.md)
- [Init lifecycle reference](/api/init-lifecycle.md)
- [Install and upgrade overview](/guides/how-to/installation/install-and-upgrade.md)

## Related

- [How to Install and Upgrade Spec Kitty](/guides/how-to/installation/install-and-upgrade.md)
- [Uninstall Spec Kitty](/guides/how-to/installation/uninstall.md)
- [Upgrade the Spec Kitty CLI](/guides/how-to/installation/upgrade-cli.md)

## Audience

- [Stakeholder Persona: Project Owner](/context/audience/external/project-owner.md) - Written for the Project Owner reader.
