cos-upgrade
Skill4 starsChanged 4 months agoMITView on GitHub
Upgrade an EXISTING Cos install to the latest code — the post-pull runbook for a machine that already ran cos-setup (a hub) or spoke-setup (a spoke). It takes an on-demand backup, pulls, runs scripts/upgrade-check.mjs (the diff → checklist planner), applies every automatable step in order (npm install, gen-launchd --install, kickstart -k of exactly the bridges/sidecars whose code moved, the production board rebuild), and hands you the manual residue — Cowork bundle uploads, scheduled tasks to create, new config keys, a Cowork restart. The store migrates itself on the next board start (fail-closed the other way); everything ELSE keeps running the old version silently until this skill kicks it. Use when the user says "update Cos", "pull the latest changes", "upgrade my install", "I pulled and things look stale", "the board shows store-newer-than-code", after merging PRs on the hub, or on every spoke after the hub was upgraded. NOT for the first machine (cos-setup) or for joining a machine (spoke-setup).
- Reads credentials
- Installs packages
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- add-an-addonSkill
- backup-recoverySkill
- body-mcp-setupSkill
- cos-setupSkill
- debug-cowork-mcp-issuesSkill
- fitness-mcp-setupSkill
- guard-setupSkill
- hub-handoverSkill
- mcp-bridge-setupSkill
- nutrition-mcp-setupSkill
- openwhispr-mcp-setupSkill
- setup-vaultSkill
- spoke-setupSkill
- voice-operationsSkill
- whatsapp-mcp-setupSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 48
If backup is not set up here, copy board/data/cases.json somewhere safe by hand now — after the first write on the new code, that file is …
- Very specific: line 57
Freeze the production board: before anything is installed or built: launchctl bootout gui/$(id -u)/com.chiefofstaff.mcp-boardapp (and quit …
- Distinctive: line 80
Read it top to bottom. Each step is tagged [auto] (a command), [manual] (only you can do it), or [info].
- Very specific: line 82
STOP: check out a commit whose SCHEMA_VERSION ≥ the store's, or restore the Step 1 snapshot.
- Very specific: line 202
A tool is missing in Cowork / Claude Code: after the upgrade — the server code moved but the client holds the old child: restart Cowork.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cos — upgrade an existing install (the post-pull runbook)
git pull changes files. It does not rebuild the production board, restart a launchd bridge that
still runs the old server code, hand Cowork the rebuilt skill bundle it installed months ago, or create
the scheduled trigger automation.json just gained. Each of those is a silent no-op — the repo is
green, the tests pass, and your sweeps run last month's procedure. Only the store takes care of
itself, and only in one direction: it migrates up on the next read, and refuses every write when
the code is older than the file (503 store-newer-than-code) — see
docs/reference/migration.md.
This skill is the deterministic answer. The planner (scripts/upgrade-check.mjs) turns what your
pull changed into the ordered list of what this machine must do; you apply it. Never re-run
cos-setup to upgrade — it is the first-run path and assumes empty state.
Roles. A hub runs the board, the store, the sidecars and the backup. A spoke runs only the board-facing MCP wrappers. Upgrade the hub first, then every spoke (a wrapper newer than the hub calls routes the hub does not have yet).
Step 0 — preflight (read-only)
source "$(git rev-parse --show-toplevel)/config/load-config.sh" # REPO_ROOT, BOARD_URL, ports, COS_DEVICE_ROLE
cd "$REPO_ROOT"
git status --porcelain # must be EMPTY — a dirty tree makes the pull ambiguous; stash or commit first
git rev-parse --abbrev-ref HEAD # expect main (an upgrade tracks main or a release tag, never a feature branch)
PRE_PULL="$(git rev-parse HEAD)"; echo "running: $PRE_PULL"
echo "role: ${COS_DEVICE_ROLE:-hub}"
[ "${COS_DEVICE_ROLE:-hub}" = hub ] && curl -s "$BOARD_URL/api/healthz" # note appVersion / schemaVersion / diskSchemaVersion BEFORECHECKPOINT: clean tree on main, PRE_PULL captured, healthz answered (hub). On a spoke, also
confirm the hub is already upgraded: curl -s "$BOARD_URL/api/healthz" must report an appVersion /
schemaVersion ≥ what you are about to pull (compare with git show origin/main:package.json and
git show origin/main:board/lib/types.ts | grep SCHEMA_VERSION).
Step 1 — back up, pause, freeze (hub only; ALWAYS before the store can change)
node backup/backup.mjs; echo "backup exit $?" # must be 0 (written AND pushed); 2 = local only (note it), 4 = not the lease-holding hub (STOP)If backup is not set up here, copy board/data/cases.json somewhere safe by hand now — after the
first write on the new code, that file is at the new schema and an older board cannot use it. This
snapshot is the only rollback point (see Rollback below). A spoke has no store: skip.
Then, still on the hub:
- Pause the Cowork scheduled tasks (Cowork → Scheduled Tasks) for the upgrade window. A sweep that fires while the board rebuilds, or runs last month's bundle against the new API, fails halfway — after it has already written something. You resume them in Step 6.
- Freeze the production board before anything is installed or built:
launchctl bootout gui/$(id -u)/com.chiefofstaff.mcp-boardapp(and quit any hand-runnext devon the board port). Nothing lands between the snapshot and the new code,npm installnever runs under a livenext start, and a build attempted before deps land cannot poisonboard/.next/COS_BUILD_FAILEDfor the new commit.tailscale serveanswers 502 until Step 4 brings the board back — expected.
Step 2 — pull
git pull --ff-only # a release tag instead: git fetch --tags && git checkout vX.Y.Z--ff-only refuses a diverged local main instead of creating a merge commit; if it refuses, resolve
that first (git log --oneline origin/main..HEAD shows what is local-only).
Step 3 — plan (read-only)
node scripts/upgrade-check.mjs --from "$PRE_PULL" # the checklist for THIS machine (role-aware)
node scripts/upgrade-check.mjs --from "$PRE_PULL" --json # the same, for an agent to walkRead it top to bottom. Each step is tagged [auto] (a command), [manual] (only you can do it),
or [info]. A BLOCKER line (the store is newer than the code you moved to — a downgrade) means
STOP: check out a commit whose SCHEMA_VERSION ≥ the store's, or restore the Step 1 snapshot.
Step 4 — apply the [auto] steps, in the printed order
The order matters and the planner already sorted it: deps → config keys → services → board.
npm install && (cd board && npm install) # only when a lockfile changed (the plan says which)
node scripts/gen-launchd.mjs --install <installed names> # only when a descriptor / generator changed — the plan names EXACTLY the services installed here; never --all; a non-zero exit means a named service FAILED to load — read the stderr line and fix it before continuing
launchctl kickstart -k gui/$(id -u)/com.chiefofstaff.mcp-<name> # each runner/sidecar/bridge the plan lists — the label is the manifest's
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.chiefofstaff.mcp-boardapp.plist; launchctl kickstart -k gui/$(id -u)/com.chiefofstaff.mcp-boardapp # hub: rebuild (the commit moved) + start
node scripts/gen-cowork-config.mjs # only when the plan says the Cowork config snapshot is staleTwo staleness classes, and why the plan restarts what it restarts:
- Long-lived processes serve the old code until their process restarts — the production board
(
next start), thevaultjobsrunner, theguardsvc/searchuv sidecars (auv runsidecar re-syncs its venv fromuv.lockon start, sokickstart -kis the whole step; the guard MCP fails CLOSED while it restarts).mcp/ensure-bridges.shonly starts what is down (plainkickstart) and never stops anything — it does not refresh code. - A supergateway bridge spawns a fresh child per request, so its next call already runs the pulled
server; the kick only reaps idle pre-pull children. The stale part is the client: an open Claude
Code session caches
tools/list— start a new session (or/mcp→ reconnect) — and Cowork holds one long-lived child per server — ⌘Q + reopen.
The production board: boardapp-run.mjs builds only main — a tree parked on a feature branch keeps
serving whatever was last built and refuses to build anything else. A running supervised board (the
launchd job) notices within about a minute when main has moved and redeploys itself, so on a hub
the git pull in Step 2 is itself what arms the redeploy — Step 1's bootout before pulling is
what keeps the full freeze intact. A moved board/package-lock.json triggers npm ci before the build.
A failed build writes board/.next/COS_BUILD_FAILED
and will not retry on that commit — fix the cause (usually a missed npm install), rm the marker,
kick again; read mcp/logs/boardapp.err.log. Never kickstart -k the scheduled backup job — that
fires a backup (use node backup/backup.mjs when you want one).
Dev machine (no boardapp LaunchAgent): restart your npm run dev. Never run next build in
board/ while a next dev is up — they share .next and the running board 500s until restarted.
Windows hub: node mcp/cos-services.mjs restart respawns every bridge + sidecar from the live
manifest (no render step); uv sync the sidecar venvs by hand (their uvicorn is called directly); stop
the running boardapp-run.mjs and re-run it (same rails — though rail 7 is supervised-only, so a
hand-run wrapper never self-exits; re-running it by hand IS the deploy there); the backup is a Task
Scheduler job (re-read from disk each fire). Stop a cos-services watch supervisor first — it would
respawn the old processes.
Step 5 — the manual residue (the planner lists exactly which apply)
- Cowork skill bundles — for every
board/.claude/skill-bundles/<skill>.zipthe plan names: Cowork → Settings → Capabilities → Skills → upload it (replacing the installed copy). Nothing in the repo can do this and nothing can read it back: until you do, the scheduled sweep runs the previous procedure. Then record it —node scripts/mark-skill-uploaded.mjs <skill>…writes a per-machine receipt (mcp/logs/.cowork-skills-uploaded.json, the sha256 of each zip you uploaded). With a receipt the next plan lists exactly the bundles whose bytes differ from what this machine last uploaded — however many pulls ago they changed — instead of guessing from the git range. First time: upload everything and runnode scripts/mark-skill-uploaded.mjs --all;--listshows the receipt vs the committed zips at any time. - An enabled add-on with no bridge here (the plan's
addon-unwiredline): the board serves its nav + API, but no agent on this machine can reach it — run the named/<addon>-mcp-setup. Classic case: Nutrition or Fitness was enabled beforebodyauto-enabled under them, and/body-mcp-setupnever ran. - Scheduled tasks — for every
CREATE/EDITline: Cowork → Scheduled Tasks → create the trigger string verbatim (the catalog inboard/.claude/skills/README.mdis the source of truth). - New config keys — copy each named key's block from
config/cos.env.exampleintoconfig/cos.env(andsecrets.env.example→secrets.env), then re-run the generator the plan names. Secrets reach Cowork as an inlined copy — a new secret needsgen-cowork-config.mjstoo. - Restart Cowork Desktop whenever server code moved — it holds one long-lived stdio child per
server. Restart Claude Code sessions when
.mcp.jsonchanged.
Step 6 — verify
curl -s "$BOARD_URL/api/healthz" # hub: schemaVersion == the new code's, diskSchemaVersion <= it, degradedRead:false, appVersion == package.json
sh mcp/ensure-bridges.sh # every installed service answers on its port (a DOWN line names the log to read)
node scripts/pack-skills.mjs --check && node scripts/gen-mcp-json.mjs --check # the committed artifacts are in syncThen open the board once: the first read migrates the store; the first write stamps the new
schemaVersion (diskSchemaVersion catches up in healthz). From that moment, never run a board
built from older code against this store, and restore a snapshot only onto a checkout whose
SCHEMA_VERSION ≥ the snapshot's — node backup/restore.mjs --list prints each snapshot's schema;
restore.mjs only WARNs on a newer snapshot, and the board then fails closed until you pull. Resume the
Cowork scheduled tasks you paused in Step 1.
Prove the agent path end-to-end in a new Claude Code session: mcp__board__get_device_status, then
one tool this pull added (the plan's restart lines name them) — a Not found. here means a wrapper is
ahead of the hub.
Rollback
Code rolls back with git; data does not roll back with git. If you must return to the previous
version after a write happened on the new code: git checkout <PRE_PULL>, rebuild/restart, and
restore the Step 1 snapshot (node backup/restore.mjs — see /backup-recovery); the store on disk
is at the newer schema and the old board fails closed on it by design. Writes made between the
upgrade and the rollback are lost — that is the trade the snapshot protects you from forgetting.
Multi-device order
- Hub: Steps 0–6.
Each spoke: Step 0 (confirm the hub is ahead — the one-liner below) → Step 2 → Step 3 → Step 4 (it will list only the spoke-capable bridges —
board,calendar, enabled add-on wrappers) → Step 5 (Cowork bundles + restart apply on a spoke too) →sh mcp/ensure-bridges.sh. A spoke has no store, no backup, no board: no Step 1. If the hub enabled an add-on this spoke has no wrapper for, wire it:node scripts/gen-launchd.mjs --install <addon> && node scripts/gen-cowork-config.mjs <addon>.# spoke parity: the hub must already serve a schema >= what this checkout expects source "$(git rev-parse --show-toplevel)/config/load-config.sh" want=$(grep -oE 'SCHEMA_VERSION = [0-9]+' board/lib/types.ts | grep -oE '[0-9]+') curl -fsS --max-time 5 "$BOARD_URL/api/healthz" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);const w=Number(process.argv[1]);console.log("hub app",j.appVersion,"schema",j.schemaVersion,"— this checkout wants",w);process.exit(j.schemaVersion>=w?0:1)})' "$want" || echo "HUB NOT UPGRADED YET — do not restart this spoke's wrappers"Warm-standby spokes (a backup clone + the recovery key) must reach ≥ the hub's schema promptly: from the hub's first post-upgrade backup on, every snapshot carries the new schema.
- Pure browser viewers: nothing — they load the hub's board.
If something fails
503 store-newer-than-code/ a red banner after the pull — the running board is older than the store: the production board did not rebuild.launchctl kickstart -k gui/$(id -u)/com.chiefofstaff.mcp-boardappand readmcp/logs/boardapp.err.log(a failed build records the commit inboard/.next/COS_BUILD_FAILEDand will not hot-loop; fix the build, kick again).- A tool is missing in Cowork / Claude Code after the upgrade — the server code moved but the client
holds the old child: restart Cowork;
kickstart -kthe bridge;sh mcp/ensure-bridges.sh. Deeper:/debug-cowork-mcp-issues. - A sweep behaves like last month — the bundle was rebuilt but not uploaded (Step 5), or the new scheduled trigger was never created.
upgrade-checkcannot pick--from— you ran it in a fresh session (noORIG_HEAD) and no production build marker exists; pass--from <the commit you were running>(git reflogshows it).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

