<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/from-charter-2x/">
  <id>https://docs.spec-kitty.ai/migrations/from-charter-2x/</id>
  <title>Migrating from 2.x / Early 3.x Charter Projects</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/from-charter-2x/"/>
  <summary>What changed when upgrading from Spec Kitty 2.x or early 3.x to current Charter-era 3.x, migration steps, and known failure modes.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;migrating-from-2x--early-3x-charter-projects&quot;&gt;&lt;/span&gt;
&lt;p&gt;This guide covers what changed when upgrading a project from Spec Kitty 2.x (or early 3.x before
the Charter era) to the current Charter-era 3.x.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;what-changed&quot;&gt;What changed&lt;/h2&gt;






































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Area&lt;/th&gt;&lt;th&gt;2.x behavior&lt;/th&gt;&lt;th&gt;3.x Charter behavior&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Governance file location&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; — same location, but no DRG-backed synthesis&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; — same file, now drives the full synthesis pipeline&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Governance artifacts&lt;/td&gt;&lt;td&gt;Repository-native doctrine artifacts in &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; (directives, tactics, styleguides)&lt;/td&gt;&lt;td&gt;Project layer in &lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/&lt;/code&gt; promoted by &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt;; the built-in Charter Pack in &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; is the fallback&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Synthesis command&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; (sync only — charter.md to YAML config)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; (full DRG-backed doctrine promotion) + &lt;code dir=&quot;auto&quot;&gt;charter bundle validate&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Partial synthesis&lt;/td&gt;&lt;td&gt;Not available&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter resynthesize --topic &amp;#x3C;selector&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Bundle validation&lt;/td&gt;&lt;td&gt;Not available&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter bundle validate&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Graph-native decay&lt;/td&gt;&lt;td&gt;Not available&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter lint&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Synthesis status&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter status&lt;/code&gt; (sync status only)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter status&lt;/code&gt; (sync status + synthesis/operator state + optional provenance)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;CLI structure&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter &amp;#x3C;subcommand&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Same — &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter &amp;#x3C;subcommand&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Mission execution&lt;/td&gt;&lt;td&gt;Direct workflow commands: &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.plan&lt;/code&gt;, etc.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;name&gt; --mission &amp;#x3C;slug&gt;&lt;/code&gt; with automatic Charter context injection&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Retrospective&lt;/td&gt;&lt;td&gt;Not available in 2.x&lt;/td&gt;&lt;td&gt;Default-on in 3.2.0+: &lt;code dir=&quot;auto&quot;&gt;retrospective.yaml&lt;/code&gt; is authored automatically at mission completion. &lt;code dir=&quot;auto&quot;&gt;spec-kitty retrospect create --mission &amp;#x3C;slug&gt;&lt;/code&gt; authors on demand; &lt;code dir=&quot;auto&quot;&gt;retrospect summary&lt;/code&gt; aggregates (read-only); &lt;code dir=&quot;auto&quot;&gt;agent retrospect synthesize --mission &amp;#x3C;slug&gt;&lt;/code&gt; previews/applies proposals. See &lt;a href=&quot;/guides/how-to/governance/use-retrospective-learning/&quot;&gt;How to Use Retrospective Learning&lt;/a&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Profile invocation&lt;/td&gt;&lt;td&gt;Not available in 2.x&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty dispatch &quot;&amp;#x3C;request&gt;&quot;&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;profile-invocation complete&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Governance context injection&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;charter context --action &amp;#x3C;action&gt;&lt;/code&gt; (available; used by runtime)&lt;/td&gt;&lt;td&gt;Same command available for debugging; automatic injection via &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Note on &lt;code dir=&quot;auto&quot;&gt;constitution&lt;/code&gt;&lt;/strong&gt;: In early 3.x, the governance command was &lt;code dir=&quot;auto&quot;&gt;spec-kitty constitution&lt;/code&gt;.
As of 3.1.0 (mission 063), &lt;code dir=&quot;auto&quot;&gt;spec-kitty constitution&lt;/code&gt; has been removed. All references must
be updated to &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Note on public constitutions&lt;/strong&gt;: Some projects have both a public file such as
&lt;code dir=&quot;auto&quot;&gt;spec/constitution.md&lt;/code&gt; and the Spec Kitty runtime file &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt;. In current
3.x, &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; is the runtime doctrine source consumed by &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;charter context&lt;/code&gt;, and governed mission prompts. The public constitution can remain the long-form
human-facing governance document, but it is not automatically synced into the runtime charter.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;migration-steps&quot;&gt;Migration steps&lt;/h2&gt;
&lt;p&gt;Follow these steps after upgrading the Spec Kitty CLI to the current Charter-era version:&lt;/p&gt;
&lt;h3 id=&quot;step-1-update-cli-invocations&quot;&gt;Step 1: Update CLI invocations&lt;/h3&gt;
&lt;p&gt;If any scripts or CI pipelines reference &lt;code dir=&quot;auto&quot;&gt;spec-kitty constitution&lt;/code&gt;, replace every occurrence
with &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter&lt;/code&gt;:&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:#919F9F;--1:#5F636F&quot;&gt;# Old (no longer works)&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;constitution&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;interview&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;constitution&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;generate&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;/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:#919F9F;--1:#5F636F&quot;&gt;# New&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;uv&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;run&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&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;charter&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;interview&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;uv&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;run&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&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;charter&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;generate&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;step-2-re-run-the-interview-if-chartermd-format-changed&quot;&gt;Step 2: Re-run the interview if charter.md format changed&lt;/h3&gt;
&lt;p&gt;If the charter format changed between your old CLI version and the current one:&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;uv&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;run&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&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;charter&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;interview&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;--profile&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;minimal&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;--defaults&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;uv&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;run&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&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;charter&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;generate&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;--from-interview&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;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;step-3-run-the-full-synthesis-flow&quot;&gt;Step 3: Run the full synthesis flow&lt;/h3&gt;
&lt;p&gt;Run synthesis to populate &lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/&lt;/code&gt; for the first time:&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:#919F9F;--1:#5F636F&quot;&gt;# Check current 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;uv&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;run&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&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;charter&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Lint for decay&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;uv&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;run&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&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;charter&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;lint&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Synthesize (dry-run first)&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;uv&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;run&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&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;charter&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;synthesize&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;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&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;run&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&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;charter&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;synthesize&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Validate the bundle&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;uv&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;run&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&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;charter&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;bundle&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;validate&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;/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:#919F9F;--1:#5F636F&quot;&gt;# Confirm&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;uv&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;run&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&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;charter&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;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;step-4-verify-no-drift&quot;&gt;Step 4: Verify no drift&lt;/h3&gt;
&lt;p&gt;After synthesis, confirm &lt;code dir=&quot;auto&quot;&gt;charter status&lt;/code&gt; reports no drift between &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; and the bundle.
If drift is reported, re-run &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; followed by &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;step-4a-resolve-duplicate-constitutions&quot;&gt;Step 4a: Resolve duplicate constitutions&lt;/h3&gt;
&lt;p&gt;If an upgraded project now has both a public constitution and &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt;,
choose an explicit ownership model:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Model&lt;/th&gt;&lt;th&gt;Use when&lt;/th&gt;&lt;th&gt;Migration step&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Runtime summary with external authority&lt;/td&gt;&lt;td&gt;The public constitution is long-form or public-facing, and agents only need concise binding directives.&lt;/td&gt;&lt;td&gt;Keep &lt;code dir=&quot;auto&quot;&gt;spec/constitution.md&lt;/code&gt;; edit &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; to summarize operative rules and reference the public document. Add the containing directory, such as &lt;code dir=&quot;auto&quot;&gt;spec/&lt;/code&gt;, to &lt;code dir=&quot;auto&quot;&gt;authority_paths&lt;/code&gt; if agents should inspect it.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Committed mirror&lt;/td&gt;&lt;td&gt;The project deliberately wants the public constitution and runtime charter to match.&lt;/td&gt;&lt;td&gt;Keep an explicit copy/sync process outside &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt;, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter sync&lt;/code&gt; after the mirror has been refreshed.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Symlink&lt;/td&gt;&lt;td&gt;The project can rely on symlink support in every checkout and wants sync-only extraction from one physical markdown file. Avoid this for Windows or mixed-platform projects unless native Windows CI proves symlink support.&lt;/td&gt;&lt;td&gt;Point &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; at the chosen source file. &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; follows the symlink for reads and writes generated YAML into &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt; refuses to overwrite a symlinked charter before compilation or generated-file writes.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Do not leave this implicit. Equality checks between &lt;code dir=&quot;auto&quot;&gt;spec/constitution.md&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt; should exist only for projects that intentionally picked the
committed-mirror model.&lt;/p&gt;
&lt;h3 id=&quot;step-5-update-mission-execution-patterns&quot;&gt;Step 5: Update mission execution patterns&lt;/h3&gt;
&lt;p&gt;If your scripts run missions using direct command invocations (e.g., calling specific slash
commands in a loop), update them to use &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;:&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:#919F9F;--1:#5F636F&quot;&gt;# Old pattern (2.x direct invocations)&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:#919F9F;--1:#5F636F&quot;&gt;# /spec-kitty.specify, /spec-kitty.plan, /spec-kitty.implement ...&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;/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:#919F9F;--1:#5F636F&quot;&gt;# New pattern (Charter era)&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;uv&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;run&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&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;next&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;--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;claude&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;--mission&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;my-feature-slug&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;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&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;run&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&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;next&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;--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;claude&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;--mission&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;my-feature-slug&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;--result&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;success&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;hr&gt;
&lt;h2 id=&quot;known-migration-failures-and-fixes&quot;&gt;Known migration failures and fixes&lt;/h2&gt;
&lt;h3 id=&quot;1-taskclierror-chartermd-must-exist&quot;&gt;1. “TaskCliError: charter.md must exist”&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; requires &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; to exist. If your project predates the charter
generation step, create it:&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;uv&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;run&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&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;charter&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;interview&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;--profile&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;minimal&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;--defaults&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;uv&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;run&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&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;charter&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;generate&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;--from-interview&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;2-no-such-command-constitution&quot;&gt;2. “No such command: constitution”&lt;/h3&gt;
&lt;p&gt;You are calling &lt;code dir=&quot;auto&quot;&gt;spec-kitty constitution&lt;/code&gt; which was removed in 3.1.0. Replace all occurrences
with &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;3-bundle-validate-fails-after-upgrading&quot;&gt;3. Bundle validate fails after upgrading&lt;/h3&gt;
&lt;p&gt;If &lt;code dir=&quot;auto&quot;&gt;charter bundle validate&lt;/code&gt; reports schema errors after upgrading, the bundle was generated by
an older CLI version and may not conform to CharterBundleManifest v1.0.0. Force regenerate:&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;uv&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;run&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&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;charter&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;generate&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;--from-interview&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;/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;uv&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;run&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&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;charter&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;synthesize&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;uv&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;run&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&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;charter&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;bundle&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;validate&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;4-doctrine-files-missing-after-migration&quot;&gt;4. Doctrine files missing after migration&lt;/h3&gt;
&lt;p&gt;On first migration, &lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/&lt;/code&gt; may be empty because &lt;code dir=&quot;auto&quot;&gt;charter synthesize&lt;/code&gt; was never run.
Run it once to populate:&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;uv&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;run&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&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;charter&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;synthesize&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/generated/&lt;/code&gt; is also empty (no agent-generated artifacts), synthesize will
create only the minimal artifact set. The runtime falls back to the built-in Charter Pack until you run
a full synthesis with agent-generated content.&lt;/p&gt;
&lt;h3 id=&quot;5-compact-context-warnings-in-agent-prompts&quot;&gt;5. compact-context warnings in agent prompts&lt;/h3&gt;
&lt;p&gt;After migrating, agents may receive compact-context mode warnings if your governance layer is
large. This is expected — see &lt;a href=&quot;/guides/how-to/governance/troubleshoot-charter/&quot;&gt;Troubleshooting Charter Failures&lt;/a&gt;
for workarounds.&lt;/p&gt;
&lt;h3 id=&quot;6-duplicate-public-constitution-and-runtime-charter-drift&quot;&gt;6. Duplicate public constitution and runtime charter drift&lt;/h3&gt;
&lt;p&gt;If governance checks fail because &lt;code dir=&quot;auto&quot;&gt;spec/constitution.md&lt;/code&gt; differs from
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt;, first decide whether the project wants a mirror. Current Spec Kitty
does not require duplication. The recommended current model is a concise runtime charter that
references the public constitution and extracts cleanly with &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter sync&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;getting-help&quot;&gt;Getting help&lt;/h2&gt;
&lt;p&gt;If you encounter issues not covered here, see
&lt;a href=&quot;/guides/how-to/governance/troubleshoot-charter/&quot;&gt;Troubleshooting Charter Failures&lt;/a&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/governance/setup-governance/&quot;&gt;How to Set Up Project Governance&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/governance/synthesize-doctrine/&quot;&gt;How to Synthesize and Maintain Doctrine&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/governance/troubleshoot-charter/&quot;&gt;Troubleshooting Charter Failures&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/context/&quot;&gt;Spec Kitty 3.x — Charter Era&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/changelog/2x/&quot;&gt;Spec Kitty 2.x Docs (archived)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
