Upgrades and releases
Maintainers release, consumers upgrade, and the CHANGELOG is the contract between them.
A plugin update replaces files in the plugin directory. Your home was copied out of templates/ once at init and has been yours to edit ever since, so a code update cannot safely overwrite it. The home is reconciled separately, on your terms.
Detecting "behind", locally
The home records its template version in .kevin/version.json (git-tracked, so it survives a clone). Compared against the installed plugin.json, that yields three states, shown on the SessionStart banner and the dashboard badge:
| State | Meaning | Signal |
|---|---|---|
current | baseline equals installed | nothing |
pending | baseline behind installed; migrations await | amber badge "upgrade available · N" |
onboard | no version.json yet | "enable update tracking" |
The consumer flow
.kevin/updates/<from>-to-<to>/.deps runs bun install; settings merges missing permission entries and never removes yours; file copies new files only if absent; template/<file> section-merges AGENTS.md, SOUL.md, and friends: new sections added, changed ones updated, sections you added preserved. Optional changes ask first, with a diff.Guarantees: always backs up first, never overwrites a file wholesale, never deletes a section it does not recognize, only auto-applies what the release marked mandatory or additive, idempotent.
Renaming survives upgrades: the skill resolves the agent's name from your IDENTITY.md before diffing, so template changes arrive phrased in your agent's name.
The maintainer flow
release diffs everything since the last tag, groups it into Added / Changed / Fixed, detects what consumers need by inspecting the diff (dependency changes, touched templates, new skills or tools needing permissions), writes the Upgrade block, bumps the version, prepends the CHANGELOG entry, and stages a commit and tag for approval. It never commits or pushes on its own.
The Upgrade-block format
Each release carries an ### Upgrade section. Every actionable line is a backticked tag plus a note:
- `<kind>: <severity>` — <note>| kind | severity | what the upgrade does |
|---|---|---|
deps | required | runs bun install |
settings | mandatory | adds the named permission, hook, or env entries |
file | additive | copies a new file if absent |
template/<f> | mandatory | section-merges, applied automatically |
template/<f> | optional | section-merges, asks first with a diff |
script | required | runs a one-time migration at skills/upgrade/scripts/<version>.ts through the run_upgrade tool, outside the sandbox |
manual | any | a step only you can do; surfaced, never silent |
A code-only release writes one line: None — code-only, no bun install or HOME changes.