<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/sync-packs/">
  <id>https://docs.spec-kitty.ai/development/how-to/sync-packs/</id>
  <title>How to sync and bump the built-in and internal packs</title>
  <updated>2026-10-19T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/sync-packs/"/>
  <summary>Fetch the pinned built-in and internal pack trees into a checkout, work offline from the cache, and bump a pin after changing pack content upstream.</summary>
  <content type="html">&lt;span id=&quot;how-to-sync-and-bump-the-built-in-and-internal-packs&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; are not committed to this repository. Their source
is &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt;; core holds the pin lockfiles &lt;code dir=&quot;auto&quot;&gt;packs/built-in.source.yaml&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;packs/internal.source.yaml&lt;/code&gt;. This page covers fetching the trees and bumping a pin.&lt;/p&gt;
&lt;h2 id=&quot;fetch-the-trees&quot;&gt;Fetch the trees&lt;/h2&gt;
&lt;p&gt;Run this once in every checkout, including each lane and coordination worktree:&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;make&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-packs&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 command fetches the pinned commit, verifies the clean-tree digest and places the tree.
&lt;code dir=&quot;auto&quot;&gt;make dev-setup&lt;/code&gt; runs it for you. &lt;code dir=&quot;auto&quot;&gt;make test-fast&lt;/code&gt; does not, so a fresh worktree needs it
before tests that read pack content.&lt;/p&gt;
&lt;h2 id=&quot;work-offline&quot;&gt;Work offline&lt;/h2&gt;
&lt;p&gt;Fetched trees are cached under the per-user cache directory plus &lt;code dir=&quot;auto&quot;&gt;open-packs/&amp;#x3C;sha&gt;/&amp;#x3C;subtree&gt;&lt;/code&gt;,
and shared by all worktrees. That directory is &lt;code dir=&quot;auto&quot;&gt;${XDG_CACHE_HOME:-~/.cache}/spec-kitty&lt;/code&gt; on
Linux, &lt;code dir=&quot;auto&quot;&gt;~/Library/Caches/spec-kitty&lt;/code&gt; on macOS and &lt;code dir=&quot;auto&quot;&gt;%LOCALAPPDATA%\spec-kitty\Cache&lt;/code&gt; on
Windows (one authority since #6488: &lt;code dir=&quot;auto&quot;&gt;kernel.user_dirs.user_cache_dir()&lt;/code&gt;). To use only the cache:&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:#82AAFF;--1:#3B61B0&quot;&gt;--frozen&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;python&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;scripts/sync_packs.py&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;--pack&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;all&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;--offline&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;To verify placed trees against the pins without changing anything, add &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;change-pack-content&quot;&gt;Change pack content&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;Author the change in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;packs/built-in&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;packs/internal&lt;/code&gt;) and
merge it there.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Bump the pin in core:&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;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;pack&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;vendor&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;--pack&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;built-in&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;--ref&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;sha&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;&lt;code dir=&quot;auto&quot;&gt;--ref&lt;/code&gt; accepts a commit SHA or a branch; only the resolved SHA is written. The command
enforces the pin’s &lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt; range and rewrites only the lockfile.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Run &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt; to place the new tree, then commit the lockfile.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Verify offline with &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter pack vendor --pack built-in --check&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Never edit files under &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; in core: the next sync
overwrites them. Command templates under &lt;code dir=&quot;auto&quot;&gt;.claude/&lt;/code&gt; and the other agent directories are
generated copies and are not edited either.&lt;/p&gt;
&lt;h2 id=&quot;error-codes&quot;&gt;Error 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;Fix&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PACK_PIN_INVALID&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Lockfile missing, malformed, or still the all-zero placeholder commit&lt;/td&gt;&lt;td&gt;Bump the pin to a real open-packs commit&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PACK_COMMIT_UNRESOLVABLE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The commit or ref cannot be found upstream, or the pinned commit lacks the pack subtree&lt;/td&gt;&lt;td&gt;Check the SHA exists in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt; and contains &lt;code dir=&quot;auto&quot;&gt;packs/&amp;#x3C;pack&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PACK_SYNC_UNAVAILABLE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No network and no cache entry&lt;/td&gt;&lt;td&gt;Run once online, then &lt;code dir=&quot;auto&quot;&gt;--offline&lt;/code&gt; works&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PACK_DIGEST_MISMATCH&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Fetched tree does not match the pinned digest, a cached tree was tampered with, or the fetched tree contains a symlink&lt;/td&gt;&lt;td&gt;Clear that cache entry (&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;cache dir&gt;/open-packs/&amp;#x3C;sha&gt;&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;cache dir&gt;&lt;/code&gt; is the per-user cache directory named above) and re-run &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt;; re-bump the pin only if the upstream content changed. Do not edit the digest by hand&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;PACK_TREE_STALE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Placed tree differs from the pin&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A source checkout whose built-in tree was never fetched raises &lt;code dir=&quot;auto&quot;&gt;BuiltInPackMissing&lt;/code&gt;, which
points to &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt;. An installed wheel is never affected.&lt;/p&gt;
&lt;h2 id=&quot;what-does-not-change&quot;&gt;What does not change&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; is still excluded from the wheel and sdist, and built-in content ships
unchanged to every consumer. See ADR &lt;code dir=&quot;auto&quot;&gt;2026-08-16-3&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
