OPS ► UPDATE — one-command local plugin upgrade

Load ops-rules before acting. Public repo (no personal data). Outbound: one draft → one approval → one send. If AskUserQuestion / Workflow are missing, follow Rule 10 in ops-rules (Hermes: numbered options / two-turn Telegram card; delegate_task).

Upgrades the local claude-ops plugin to the newest version published in the ops-marketplace catalogue, then leaves the box clean: no stale cache dirs, no dangling version-pinned paths.

Automatic daily check (detect only, never auto-installs)

bin/ops-update-check runs daily from the ops daemon (update-check service) and answers one question: is a newer version published? It writes the verdict to ~/.claude/state/ops-update/update-available.json and exits 3 when an update exists, 0 when current.

It never installs anything. Detection and application are deliberately split: a background job that swapped the plugin out mid-session would break a working install at the worst possible moment. Applying is always ops-update, run on the user's word.

When you see that an update is available — because the state file says so, or because the user asks — surface it once and offer to apply it:

"${CLAUDE_PLUGIN_ROOT}/bin/ops-update-check" --json    # current verdict, throttled to daily
"${CLAUDE_PLUGIN_ROOT}/bin/ops-update-check" --force   # recheck now, ignoring the throttle

Then a single AskUserQuestion: [Update now] [Show what changed] [Not now]. Only on Update now do you run bin/ops-update. Never chain the two, and never apply an update the user has not just agreed to in that exchange.

Checking on every skill call

The daily cron is the only thing that ever ran the check, so a box without the daemon (Linux, or launchd never set up) heard about a new version exactly never. bin/ops-pretool-skill-update closes that: a PreToolUse hook on ^Skill$ re-uses the same throttled check whenever an ops skill is invoked, so the first skill call of the day says what the daily cron would have said.

Behaviour is set by auto_update in preferences.json (or $OPS_AUTO_UPDATE):

auto is the one exception to the split above, and it stays opt-in for the reason stated there: the running session keeps the old version until it reloads, so the upgrade lands detached, behind a lock, and never prunes the tree the session is rooted in. Turning it on is the user's decision, not yours — never switch a box to auto on your own initiative.

Flags: --json (verdict on stdout), --no-fetch (compare against the catalogue already on disk, no network), --force (ignore the once-a-day throttle), --quiet (write state, print nothing — how the daemon runs it). Override the cadence with $OPS_UPDATE_CHECK_INTERVAL in seconds.

The workhorse is ${CLAUDE_PLUGIN_ROOT}/bin/ops-update. It runs a 9-step loop:

1. Refresh catalogue — claude plugin marketplace update ops-marketplace (git-pulls the clone).
2. Resolve target — newest version from the refreshed marketplace.json (or --to X.Y.Z).
3. Update plugin — claude plugin update ops@ops-marketplace, with a force-reinstall fallback (rm cache + claude plugin install) for the Claude Code bug where update reports "already latest" while the cache stays stale (anthropics/claude-code#61954).
4. Reapply patches — runs idempotent scripts in scripts/cache-patches/ against the new cache (empty when all fixes are upstream — the desired state).
5. Prune — deletes every old cache/ops-marketplace/ops/<ver>/ except the new one.
6. Rewrite — fixes stale cache/.../ops/<oldver>/ paths in live configs/scripts/systemd units only (never logs, memory, or transcripts — those use ${CLAUDE_PLUGIN_ROOT} at runtime so they self-resolve).
7. Migrate — runs ops-post-update-migrate (idempotent, per-version). It also maintains a stable cache/.../ops/current/ directory (rsynced from the new version and repointed in installed_plugins.json) so Claude Code GC'ing the old versioned dir mid-session never causes "Plugin directory does not exist" hook errors.
8. Local sync — if a linked local source checkout of this repo is present under ~/Projects, fast-forwards its main to origin/main so a dev clone never silently drifts behind the published release. Acts only on a clean main (never clobbers uncommitted WIP, a feature branch, or unpushed commits); a no-op when no checkout exists. Skip with --no-localsync.
9. Report — old→new, what changed, and that a restart / /reload-plugins is needed to load it.
10. Companions — bin/ops-update step 9 runs scripts/install-companions.sh against plugin-dependencies.json. Every companion with required: true is co-installed when missing and updated on every ops-update:
    • desktop-act — /ops:desktop + captcha cascade
    • gsd — /ops:flow project mode, /ops:projects, /ops:go
    • gstack — skills clone for /ops:flow ad-hoc (/spec /review /qa /ship)
    • superpowers — merge / orchestrate / triage checkpoints
    • feature-dev — /ops:ops-feature-dev Skip only with --no-companions or OPS_SKIP_COMPANIONS=1.

# manual companion pass
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install-companions.sh"
bash "${CLAUDE_PLUGIN_ROOT}/scripts/install-companions.sh --status"
# skip from ops-update:
${CLAUDE_PLUGIN_ROOT}/bin/ops-update --no-companions

How to run it

Steps 5–6 are destructive (prune + rewrite), so always dry-run first, show the plan, confirm, then apply (Rule 5).

1. Dry-run and show the plan

${CLAUDE_PLUGIN_ROOT}/bin/ops-update --dry-run

Present the output: current → target version, which cache versions would be pruned, which files would be rewritten. If the dry-run shows already on <ver> and nothing to prune/rewrite, tell the user the box is already current and stop (offer --force only if they suspect a stale cache).

"already on " is a lie when the marketplace clone is stuck. Step 1 prints ✓ marketplace catalogue refreshed even when the underlying git pull silently did nothing, so step 2 resolves a stale target and the whole run no-ops. ~/.claude/plugins/marketplaces/ops-marketplace is a real checkout of this repo; a dirty worktree (a local edit, stray .bak files) blocks the fast-forward. Verified 2026-09-05: it sat 28 commits behind on v3.10.3 while v3.10.5 was published, and the update reported the box current.

Whenever the target version does not match what you just released, check the clone before reaching for --force:

cd ~/.claude/plugins/marketplaces/ops-marketplace
git fetch -q origin
git status -sb                 # ahead/behind AND porcelain lines
grep -o '"version": *"[^"]*"' .claude-plugin/marketplace.json | head -1

Repair: diff each modified file against origin/main first — a local edit that is byte-identical to upstream is safe to drop, anything else is real work that must be salvaged before you touch it. Then clean the tree, git merge --ff-only origin/main, and re-run the dry-run. The target version should now be the published one.

2. Confirm

Use AskUserQuestion before applying:

Upgrade local claude-ops <CUR> → <NEW>?  (prunes N old cache versions, rewrites M files)
  [Apply upgrade]
  [Force re-materialise cache]   ← only if same-version stale-cache is suspected
  [Cancel]

3. Apply

${CLAUDE_PLUGIN_ROOT}/bin/ops-update          # or: --force

Stream the step-by-step output. On success, surface the final line verbatim:

Restart Claude Code (or run /reload-plugins) to load v<NEW>.

The running session will NOT see the new version until reload — this is a Claude Code constraint, not a failure.

Flags

Mobile / SSH (Rule 7)

The bin auto-detects a non-TTY and drops colour; its output is already line-per-fact, so relay it as-is — no tables, no banners.

Notes

• Idempotent. Re-running on an already-current box is a near no-op (resolve → "already on " → nothing to prune/rewrite/migrate).
• Public repo / no secrets (Rule 0): the script reads only $HOME/.claude/plugins state; it writes no personal data.
• To publish a new version first, see ${CLAUDE_PLUGIN_ROOT}/bin/ops-release (bumps plugin.json + marketplace.json + CHANGELOG, opens the release PR, tags). ops-release ships it; ops-update pulls it down locally.