<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/guides/how-to/installation/upgrade-project/">
  <id>https://docs.spec-kitty.ai/guides/how-to/installation/upgrade-project/</id>
  <title>Upgrade an existing Spec Kitty project</title>
  <updated>2026-11-06T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/guides/how-to/installation/upgrade-project/"/>
  <summary>Upgrade an existing project to the Spec Kitty 3.2 schema after installing the current CLI, with validation and recovery steps.</summary>
  <content type="html">&lt;span id=&quot;upgrade-an-existing-spec-kitty-project&quot;&gt;&lt;/span&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;For upgrading the &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; binary itself, see &lt;a href=&quot;/guides/how-to/installation/upgrade-cli/&quot;&gt;Upgrade the CLI&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;when-do-i-need-this&quot;&gt;When do I need this?&lt;/h2&gt;
&lt;p&gt;Run a project upgrade when:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You just upgraded the CLI (&lt;code dir=&quot;auto&quot;&gt;pipx upgrade --pip-args=--pre spec-kitty-cli&lt;/code&gt; or equivalent).&lt;/li&gt;
&lt;li&gt;A spec-kitty command exits with code &lt;strong&gt;4&lt;/strong&gt; and says &lt;code dir=&quot;auto&quot;&gt;This project needs Spec Kitty project migrations&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;You opened an older project on a newer CLI for the first time.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h2 id=&quot;the-upgrade-flow&quot;&gt;The upgrade flow&lt;/h2&gt;
&lt;p&gt;From the project root:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/path/to/your/project&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;You will see a summary of pending migrations and be asked to confirm. To preview without applying anything:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The preview heads its migration list &lt;code dir=&quot;auto&quot;&gt;Migrations that would be applied:&lt;/code&gt; and marks each entry
with &lt;code dir=&quot;auto&quot;&gt;→&lt;/code&gt;, and its closing line repeats that nothing was written. A real run heads the same
list &lt;code dir=&quot;auto&quot;&gt;Migrations applied:&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;✓&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;To apply without prompting (useful in CI):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--yes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;For machine-readable output:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;That command preserves the legacy compatibility schema. For the complete,
preview-only owner plan use:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--plan-json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;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. &lt;code dir=&quot;auto&quot;&gt;--yes&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; never make a preview write.&lt;/p&gt;
&lt;h2 id=&quot;what-spec-kitty-upgrade-does&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; does&lt;/h2&gt;
&lt;p&gt;The project upgrade runs &lt;strong&gt;config-aware migrations&lt;/strong&gt; that bring your &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; scaffold and agent surfaces in sync with the installed CLI. Specifically, it:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Reads &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; to learn which agents you have configured.&lt;/li&gt;
&lt;li&gt;Walks pending migrations in version order.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Updates agent command directories&lt;/strong&gt; for configured agents only (&lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty-&amp;#x3C;command&gt;/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.amazonq/prompts/&lt;/code&gt;, etc.). Agents you removed stay removed — migrations never recreate them.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refreshes templates and skill packages&lt;/strong&gt; under those agent directories from the CLI’s bundled source templates.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bumps &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt;&lt;/strong&gt; to record the new schema version.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Leaves your data alone&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt;, and any other content you authored is not touched.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Migrations are idempotent — running &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; twice on the same project is safe.&lt;/p&gt;
&lt;p&gt;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 &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt; and archives Antigravity’s old &lt;code dir=&quot;auto&quot;&gt;.agent/workflows/&lt;/code&gt; files. Run it in every clone. See &lt;a href=&quot;/migrations/command-skill-hyphen-names/&quot;&gt;Command skills renamed for the Agent Skills specification&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;common-follow-ups&quot;&gt;Common follow-ups&lt;/h2&gt;
&lt;p&gt;After a successful project upgrade:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;config&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;sync&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Reconcile filesystem with config.yaml&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;              &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Health check&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;agent config sync&lt;/code&gt; is useful if you removed or added agents and want spec-kitty to ensure the filesystem matches your &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; surfaces any post-upgrade warnings.&lt;/p&gt;
&lt;h2 id=&quot;reviewing-the-changes&quot;&gt;Reviewing the changes&lt;/h2&gt;
&lt;p&gt;Project upgrades modify tracked files (agent command directories, &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;, sometimes templates). Review before committing:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;diff&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; commits the files it changed itself when &lt;code dir=&quot;auto&quot;&gt;auto_commit&lt;/code&gt; 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:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.kittify/metadata.yaml&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;other&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;files&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;lists&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;commit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;chore: upgrade Spec Kitty project to &amp;#x3C;version&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Or use &lt;code dir=&quot;auto&quot;&gt;spec-kitty safe-commit &amp;#x3C;those files&gt; -m &quot;chore: upgrade Spec Kitty project to &amp;#x3C;version&gt;&quot;&lt;/code&gt;.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Files under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; are version-controlled and contain your mission history. Migrations should not touch them; if &lt;code dir=&quot;auto&quot;&gt;git diff&lt;/code&gt; shows changes there, stop and investigate.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3 id=&quot;if-a-missions-metajson-is-missing&quot;&gt;If a Mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; is missing&lt;/h3&gt;
&lt;p&gt;Each Mission’s &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/meta.json&lt;/code&gt; carries its immutable &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;. 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 &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; takes the tracked one back. Nothing is re-identified.&lt;/p&gt;
&lt;p&gt;When the tracked copy cannot be read, the upgrade writes nothing for that Mission and names it, for example:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/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/&amp;#x3C;slug&gt;/meta.json` shows it), commit the fix, then restore it with `git checkout -- kitty-specs/&amp;#x3C;slug&gt;/meta.json`&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Run the printed &lt;code dir=&quot;auto&quot;&gt;git checkout -- &amp;#x3C;path&gt;&lt;/code&gt; and upgrade again. A &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; 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.&lt;/p&gt;
&lt;p&gt;A Mission folder outside any git checkout gets its identity normally, even when a &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; sits above it, as long as that &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; is empty or holds only &lt;code dir=&quot;auto&quot;&gt;hooks/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-locks/&lt;/code&gt; (leftovers, not a repository). When Git cannot answer and the &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; above is a repository, or is neither a repository nor such leftovers (a lost or dangling &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;, other contents, an entry that cannot be read), the upgrade refuses with &lt;code dir=&quot;auto&quot;&gt;TRACKED_META_UNAVAILABLE&lt;/code&gt; and names that &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt;. No &lt;code dir=&quot;auto&quot;&gt;git checkout --&lt;/code&gt; is offered then, because it fails for the same reason. Repair the repository (for example restore its &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;), or, if it is leftover residue holding nothing you need, remove it; then upgrade again. The same refusal applies while &lt;code dir=&quot;auto&quot;&gt;GIT_DIR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;GIT_INDEX_FILE&lt;/code&gt; or another Git redirect is set: correct or unset it if it is unintended, otherwise repair the repository it selects.&lt;/p&gt;
&lt;h2 id=&quot;exit-codes&quot;&gt;Exit codes&lt;/h2&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Code&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;th&gt;What to do&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;0&lt;/td&gt;&lt;td&gt;Success / nothing to do&lt;/td&gt;&lt;td&gt;Continue working.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Usage error (e.g. &lt;code dir=&quot;auto&quot;&gt;--cli&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;--project&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Fix command-line flags.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;Project needs migration&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; (this command).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;Project too new for CLI&lt;/td&gt;&lt;td&gt;Upgrade the CLI first (&lt;code dir=&quot;auto&quot;&gt;pipx upgrade --pip-args=--pre spec-kitty-cli&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;Project metadata corrupt&lt;/td&gt;&lt;td&gt;Check &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt; exists and is valid YAML.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;For legacy &lt;code dir=&quot;auto&quot;&gt;--dry-run --json&lt;/code&gt;, a target refusal has semantic exit code 2 in the
document but process code 0; the too-new-project exception remains process code
5. &lt;code dir=&quot;auto&quot;&gt;--plan-json&lt;/code&gt; reports its process code directly in &lt;code dir=&quot;auto&quot;&gt;process_exit_code&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; errored after applying some migrations&lt;/strong&gt; — Migrations commit progress to &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt; after each step. Fix the underlying error (often a permissions or PATH issue) and re-run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;; it will pick up where it left off.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;My agent command directories changed but I want the old templates&lt;/strong&gt; — Run &lt;code dir=&quot;auto&quot;&gt;git diff .claude/&lt;/code&gt; (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.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; says my project schema is too new&lt;/strong&gt; — The installed CLI is older than the schema in &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt;. Upgrade the CLI: &lt;code dir=&quot;auto&quot;&gt;pipx upgrade --pip-args=--pre spec-kitty-cli&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;I want to skip a specific migration&lt;/strong&gt; — Migrations are non-optional; they exist because the runtime depends on the new layout. Investigate the root cause instead.&lt;/p&gt;
&lt;h2 id=&quot;rollback&quot;&gt;Rollback&lt;/h2&gt;
&lt;p&gt;A failed upgrade can be rolled back with git, since &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.claude/&lt;/code&gt;, and other agent directories are version-controlled:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;restore&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.kittify/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.claude/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.agents/skills/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Then reinstall the previous CLI version:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;pipx&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;install&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty-cli==&amp;#x3C;previous-version&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;See &lt;a href=&quot;/guides/how-to/installation/uninstall/&quot;&gt;Uninstall&lt;/a&gt; for the full rollback procedure.&lt;/p&gt;
&lt;h2 id=&quot;next-steps&quot;&gt;Next steps&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/upgrade-cli/&quot;&gt;Upgrade the CLI&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/upgrade-lifecycle/&quot;&gt;Upgrade lifecycle reference&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/init-lifecycle/&quot;&gt;Init lifecycle reference&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-and-upgrade/&quot;&gt;Install and upgrade overview&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
