OPS ► UPDATE — one-command local plugin upgrade

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.

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).

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.