Skip to content

How to sync and bump the built-in and internal packs

Who is this for (1)

packs/built-in/ and packs/internal/ are not committed to this repository. Their source is spec-kitty-open-packs; core holds the pin lockfiles packs/built-in.source.yaml and packs/internal.source.yaml. This page covers fetching the trees and bumping a pin.

Fetch the trees

Run this once in every checkout, including each lane and coordination worktree:

Terminal window
make sync-packs

The command fetches the pinned commit, verifies the clean-tree digest and places the tree. make dev-setup runs it for you. make test-fast does not, so a fresh worktree needs it before tests that read pack content.

Work offline

Fetched trees are cached under the per-user cache directory plus open-packs/<sha>/<subtree>, and shared by all worktrees. That directory is ${XDG_CACHE_HOME:-~/.cache}/spec-kitty on Linux, ~/Library/Caches/spec-kitty on macOS and %LOCALAPPDATA%\spec-kitty\Cache on Windows (one authority since #6488: kernel.user_dirs.user_cache_dir()). To use only the cache:

Terminal window
uv run --frozen python scripts/sync_packs.py --pack all --offline

To verify placed trees against the pins without changing anything, add --check.

Change pack content

  1. Author the change in spec-kitty-open-packs (packs/built-in or packs/internal) and merge it there.

  2. Bump the pin in core:

    Terminal window
    spec-kitty charter pack vendor --pack built-in --ref <sha>

    --ref accepts a commit SHA or a branch; only the resolved SHA is written. The command enforces the pin’s requires_core range and rewrites only the lockfile.

  3. Run make sync-packs to place the new tree, then commit the lockfile.

  4. Verify offline with spec-kitty charter pack vendor --pack built-in --check.

Never edit files under packs/built-in/ or packs/internal/ in core: the next sync overwrites them. Command templates under .claude/ and the other agent directories are generated copies and are not edited either.

Error codes

CodeMeaningFix
PACK_PIN_INVALIDLockfile missing, malformed, or still the all-zero placeholder commitBump the pin to a real open-packs commit
PACK_COMMIT_UNRESOLVABLEThe commit or ref cannot be found upstream, or the pinned commit lacks the pack subtreeCheck the SHA exists in spec-kitty-open-packs and contains packs/<pack>
PACK_SYNC_UNAVAILABLENo network and no cache entryRun once online, then --offline works
PACK_DIGEST_MISMATCHFetched tree does not match the pinned digest, a cached tree was tampered with, or the fetched tree contains a symlinkClear that cache entry (<cache dir>/open-packs/<sha>, where <cache dir> is the per-user cache directory named above) and re-run make sync-packs; re-bump the pin only if the upstream content changed. Do not edit the digest by hand
PACK_TREE_STALEPlaced tree differs from the pinRun make sync-packs

A source checkout whose built-in tree was never fetched raises BuiltInPackMissing, which points to make sync-packs. An installed wheel is never affected.

What does not change

packs/internal/ is still excluded from the wheel and sdist, and built-in content ships unchanged to every consumer. See ADR 2026-08-16-3.