Stay current · Upgrade
Upgrade
The short version lives on Getting started. This page is the longer walkthrough: how to install a new @vibecompass/vibecompass release, preview the catch-up, apply it, and decide when to move the canonical package-version stamp.
How upgrades work
An upgrade has two moving parts. The CLI you installed runs new logic straight away — newer commands, fixed bugs, friendlier prompts. The scaffolded files VibeCompass owns inside your repo (context.md, the workflow guide READMEs, the managed sections of your agent files, and the local state/manifest.json) only catch up when you run refresh-workflow. That split is intentional — it keeps the upgrade explicit and the blast radius visible before anything on disk changes.
Installed CLI
Whichever version you ran last
npx fetches the latest published version on each invocation. A global install pins to whatever you last upgraded to. Every command runs a quick preflight against the local root before doing its job, so a mismatch shows up as Compatibility warnings: at the top of the output without blocking the command.
Scaffolded files in your repo
Refreshed only when you ask
The package-owned scaffolds change at the same cadence as the CLI, but they only move when you run refresh-workflow --apply. The canonical project.yaml.metadata.package_version stamp is even stickier — on a stamped root it only moves when you pass --update-package-stamp. Legacy roots with no stamp get one written automatically on the first apply.
Walkthrough
Five steps, all safe to run in order. Steps 1–3 are read-only or install-only. Steps 4–5 are the explicit writes — and even those touch only files that VibeCompass owns.
Install the newer CLI
Pick whichever install path you used the first time. `npx` always fetches the latest published version, so it is the simplest way to pull a new release without touching anything globally. A global install gives you a shorter command (`vibecompass …` instead of `npx -y @vibecompass/vibecompass …`) at the cost of running the upgrade explicitly.
Either path produces the same CLI. Mixing them is fine — `npx` pulls the latest published version regardless of what is installed globally.
# Option A — always use npx (no install step needed)
npx -y @vibecompass/vibecompass --version
# Option B — upgrade your global install
npm install -g @vibecompass/vibecompass@latest
vibecompass --versionIf `vibecompass --version` still reports the old number after a global upgrade, your shell is likely caching the path — open a new terminal tab and try again.
Run status to see what changed
`status` is strictly read-only. It compares the package version that initialized the root with the CLI you just installed, checks whether the local manifest can still be read, and prints any compatibility warnings the newer CLI has surfaced. Use it as the first move after any upgrade — nothing on disk changes.
npx -y @vibecompass/vibecompass status
# Machine-readable form for scripts
npx -y @vibecompass/vibecompass status --jsonIf you see `Compatibility warnings:` at the top, that is exactly the signal the next two steps catch up on.
Preview the catch-up
`refresh-workflow` defaults to dry-run. It prints the exact set of writes it would make against the package-owned scaffolds — `context.md`, workflow guide READMEs that still match the generated shape, managed sections inside your agent files, and the local `state/manifest.json` — without touching any of them. Hand-written content in `CLAUDE.md`, `AGENTS.md`, your architecture docs, and your decisions are never on this list.
npx -y @vibecompass/vibecompass refresh-workflow --dry-runApply the catch-up
When the dry-run looks right, re-run with `--apply`. The same set of files is rewritten in place. User-authored workflow guide files that have drifted from the generated shape are left alone so your edits are preserved.
Compatibility warnings disappear once the scaffolds match the installed CLI. If they linger, jump to Troubleshooting.
npx -y @vibecompass/vibecompass refresh-workflow --applyDecide whether to move the package-version stamp
The canonical `project.yaml.metadata.package_version` stamp is sticky once it exists: on a stamped root, a routine refresh never silently changes which CLI your project says it is using. The currently observed CLI version lives in machine-local `state/manifest.json` instead, so collaborators on different versions do not fight over the canonical value. Move the stamp explicitly with `--update-package-stamp` once you have verified the refresh looks clean and you want to make the new version official for the project.
Legacy roots with no `metadata.package_version` are a special case — the first `--apply` writes a stamp automatically, since there is nothing yet to be sticky about. See the `legacy / unknown root` scenario in Troubleshooting.
# Verify the refresh first, then make the new version canonical
npx -y @vibecompass/vibecompass refresh-workflow --apply --update-package-stampSkip this on team projects until the rest of the team has installed the same release — the stamp is the version everyone is expected to match.
What gets touched
A refresh is bounded. It rewrites the files VibeCompass owns and leaves everything else — your architecture docs, your decisions, your session notes, the unmarked parts of your agent files — exactly as you left them.
Regenerated from the current project.yaml, architecture docs, and decisions index.
Not authored by hand — always treated as derived output.
Rewritten when the file still matches the generated workflow-guide shape.
If you have customized a guide, refresh leaves your version untouched and prints a note that it skipped.
Only the managed VibeCompass block inside each file is rewritten.
Content outside the managed markers — your own protocol notes, repo rules, custom prompts — is preserved verbatim.
Regenerated to match the installed CLI. Also records the observed package version locally.
Machine-local file; safe to delete and regenerate. Not part of the canonical project memory.
On a stamped root, only changes when you pass --update-package-stamp. Legacy roots with no stamp get a first-time one written automatically on --apply.
The canonical version stamp — sticky by design so the project's official CLI version stays under your control.
Troubleshooting
A handful of scenarios cover most of what comes up after a real-world bump. If something else surfaces, run status first — it usually names the exact command that resolves the drift.
Compatibility warnings keep showing after refresh
Re-run `status` to confirm what is still drifting. If the warning names a file you do not see in the dry-run, you may be running refresh against a different memory root — pass `--root <path>` explicitly to point at the canonical one. If a hand-edited workflow guide (`architecture/README.md`, `decisions/README.md`, or `sessions/README.md`) is keeping the warning alive, refresh deliberately leaves it alone — there is no flag override. The recovery is to back the file up, delete it, then re-run `refresh-workflow --apply` so refresh sees no existing file and regenerates the guide from scratch.
# Diagnose first
npx -y @vibecompass/vibecompass status --root .compass
npx -y @vibecompass/vibecompass refresh-workflow --root .compass --dry-run
# If a hand-edited workflow guide is keeping the warning alive
cp architecture/README.md architecture/README.md.bak
rm architecture/README.md
npx -y @vibecompass/vibecompass refresh-workflow --root .compass --applyStatus reports a legacy / unknown root
That means your `project.yaml` has no `metadata.package_version` stamp yet — common for roots created before the upgrade story shipped. Refresh treats this as a first-time stamp and writes one when you `--apply`. Nothing else is forced; commands keep running against legacy roots without complaint.
npx -y @vibecompass/vibecompass refresh-workflow --applyI am on an older CLI than the stamp expects
If the root is stamped by a newer CLI, refresh refuses to downgrade the templates on its own. Install the newer CLI to match (Step 1), or, when you intentionally need to roll back, pass `--allow-downgrade-templates` to opt into the older shape. Downgrades are rare — usually the cleaner path is to install the right version.
# Preferred: install the matching CLI
npm install -g @vibecompass/vibecompass@<version>
# Or, for an intentional downgrade
npx -y @vibecompass/vibecompass refresh-workflow --apply --allow-downgrade-templatesMy CLAUDE.md or AGENTS.md has no managed markers
Refresh leaves an unmarked file alone — you do not lose hand-written content. To bring it under management, run `sync-agents --adopt-existing` once. That appends the managed VibeCompass block at the bottom of the file, preserving everything above it. After adoption, subsequent refreshes update only the managed block.
npx -y @vibecompass/vibecompass sync-agents --adopt-existingstate/manifest.json is missing, unreadable, or on an unsupported state_version
`state/manifest.json` is machine-local derived state, not canonical project memory — losing it is recoverable. `status` surfaces all three failure modes as compatibility warnings (codes `state-manifest-missing`, `state-manifest-unreadable`, and `state-version-unsupported` when you pass `--json`; the plain `status` output shows the matching human-readable message). The fix in every case is the same: run `refresh-workflow --apply` once. Refresh always regenerates the manifest, so the next command after apply starts from a clean derived state.
npx -y @vibecompass/vibecompass refresh-workflow --applyKeep going
For the short version of this story — the two-command summary plus a quick read on the compatibility-warning block — return to Stay current. For the full surface of every command referenced here, head to the CLI page.