Managed files

xiv init and xiv update are the same operation run twice in a lifecycle: they install this repo's managed pack into SMITHERS_HOME and this repo's skills into your agent directories. This page explains what "managed" means, how xiv knows whether you changed a file, and what it will never touch.

Two layers, two destinations

The split is deliberate: the pack is workflow code copied into SMITHERS_HOME and executed by the engine, while skills are prose read by the agent. They have different destinations, different lifecycles, and different failure modes — the skills install needs the network, so it must never be able to fail a pack update (and it can't: a skills failure degrades to a warning after the pack half has already succeeded).

xiv update               # both halves
xiv update --no-skills   # pack only (offline, or keep the agent's current skills)

Both halves install from the working tree, not a commit — xiv update on a dirty repo hands your agent unreleased instructions. The CLI itself needs no install at all: bun link points xiv at this repo, so command and flag changes are live immediately. Only pack changes (workflows, prompts, agent tiers) need an xiv update — or none, when iterating with xiv dev against the in-repo pack (see authoring).

The manifest

Every install writes a manifest recording exactly which files xiv manages and what it shipped:

<SMITHERS_HOME>/.xiv/manifest.json

{
  "version": 1,
  "updatedAt": "2026-08-25T09:14:02.113Z",
  "source": "xiv",
  "files": [
    { "path": "agents.ts", "hash": "9f2b…" },
    { "path": "workflows/linear-implement.tsx", "hash": "41c7…" }
  ]
}

Each entry is a pack-relative path plus the SHA-256 of the file as installed. The manifest is the definition of "managed": a file is managed if and only if it is listed there. It is also how xiv knows it has been initialized at all — commands that need the pack check for a parseable manifest first.

What an update does

For each file in the pack, in order:

1. Hash the file currently in SMITHERS_HOME (if it exists).
2. Compare against the hash the previous manifest recorded for that path.
3. If they differ — you (or something) edited the installed copy since the last install — back it up first, then overwrite. A file that exists but has no previous manifest entry is backed up too, since xiv cannot prove it wrote it.
4. Copy the new version in and record its hash in the new manifest.

Then the new manifest is written, and bun install runs in SMITHERS_HOME so the pack's dependencies match.

Drift backups

Backups land in a per-update timestamped directory, preserving the pack-relative layout:

<SMITHERS_HOME>/.xiv/backups/<timestamp>/<path>

So a locally-tweaked prompt or agent config is never silently destroyed — xiv update reports how many files it backed up, and the previous content sits under .xiv/backups/ for you to diff and re-apply. Local edits to managed files are legal for experimentation, but they are drift: the next update will overwrite them (after backing them up). Changes you want to keep belong in this repo's pack/, followed by xiv update.

What is never touched

SMITHERS_HOME is also where Smithers keeps runtime state, and the manifest walk excludes all of it — these are yours (or the engine's), never hashed, never overwritten, never backed up:

• directories: node_modules/, .git/, .xiv/, executions/, runs/, logs/
• files: accounts.json, smithers.db, smithers.db-shm, smithers.db-wal

Anything else that lives in SMITHERS_HOME but not in pack/ — notably the stack maps under stacks/ and the xiv pr review worktrees under review/ — is simply outside the manifest and untouched by installs.

Skills installation

The skills half shells out to the skills CLI:

npx --yes skills@latest add <this-repo> --skill '*' --global

Three choices in that command are deliberate:

• add, not update — skills update refreshes previously-added packages from their original remote source, whereas xiv always re-adds from this working tree, which may be ahead of every commit.
• --skill '*', but no --agent — every skill in the repo installs (the set is curated here, so there is nothing to choose), but which agents to install into is your call, not the tool's: the CLI prompts interactively rather than silently fanning out to every agent it can find.
• The scan root is the repo root, not skills/ — the CLI auto-discovers SKILL.md files, so a skill added elsewhere in the repo later is still picked up.

If the skills step fails (offline, registry hiccup), the pack update still succeeds and the command prints the one-liner to rerun just the skills half. Pass --no-skills to skip it on purpose.

Related: getting started for the first-time flow, and operations for the surrounding commands.