Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(ops-update): one-command local plugin upgrade with prune + version-rewrite (#450)

Aurora Capital3ef2db680e57
diff --git a/claude-ops/bin/ops-update b/claude-ops/bin/ops-update
new file mode 100755
index 00000000..837a8916
--- /dev/null
+++ b/claude-ops/bin/ops-update
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# ops-update — one-command local upgrade of the claude-ops ("ops") plugin to latest.
+#
+# Runs the entire upgrade loop so the box ends up on the newest published version
+# with NO stale cache dirs and NO dangling version-pinned paths left behind:
+#
+# 1. Refresh the marketplace catalogue clone (claude plugin marketplace update)
+# 2. Resolve the target version from the refreshed marketplace.json
+# 3. Update the installed plugin (claude plugin update ops@ops-marketplace)
+# — with a force-reinstall fallback for the known Claude Code bug where
+# `plugin update` reports "already at latest" while the cache stays stale
+# (anthropics/claude-code#61954): rm the version's cache dir + reinstall.
+# 4. Reapply idempotent local cache patches (scripts/cache-patches/*.sh)
+# 5. Prune EVERY old cache version everywhere (keep only the new one)
+# 6. Rewrite stale version-pinned paths in live configs/scripts (never logs/history)
+# 7. Run per-version idempotent migrations (ops-post-update-migrate)
+# 8. Report old→new + what changed, and how to apply (/reload-plugins or restart)
+#
+# Canonical CLI per Claude Code docs:
+# https://code.claude.com/docs/en/discover-plugins (marketplace update / plugin update)
+# A session restart (or /reload-plugins) is required for the new version to load.
+#
+# Usage:
+# ops-update [--dry-run] [--force] [--to X.Y.Z] [--no-prune] [--no-patches] [--no-rewrite]
+#
+# --dry-run show everything that would happen; change nothing
+# --force force-reinstall even if the CLI says "already at latest" (bug #61954)
+# --to X.Y.Z target a specific version instead of the marketplace's newest
+# --no-prune keep old cache versions
+# --no-patches skip the cache-patch reapply step
+# --no-rewrite skip the stale-version-path rewrite step
+#
+# Public repo: no personal data. All paths derive from $HOME / env. (Rule 0)
+
+set -euo pipefail
+
+MARKETPLACE="ops-marketplace"
+PLUGIN="ops"
+PLUGINS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins"
+CACHE_ROOT="$PLUGINS_DIR/cache/$MARKETPLACE/$PLUGIN"
+MKT_CLONE="$PLUGINS_DIR/marketplaces/$MARKETPLACE"
+MKT_JSON="$MKT_CLONE/.claude-plugin/marketplace.json"
+INSTALLED="$PLUGINS_DIR/installed_plugins.json"
+DATA_DIR="${CLAUDE_PLUGIN_DATA_DIR:-$PLUGINS_DIR/data/ops-${MARKETPLACE}}"
+THIS_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+DRY=0; FORCE=0; PRUNE=1; PATCHES=1; REWRITE=1; TARGET=""
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --dry-run) DRY=1; shift ;;
+ --force) FORCE=1; shift ;;
+ --to) TARGET="$2"; shift 2 ;;
+ --no-prune) PRUNE=0; shift ;;
+ --no-patches) PATCHES=0; shift ;;
+ --no-rewrite) REWRITE=0; shift ;;
+ -h|--help) sed -n '2,33p' "$0"; exit 0 ;;
+ *) echo "ops-update: unknown arg '$1'" >&2; exit 2 ;;
+ esac
+done
+
+c_grn=$'\033[1;32m'; c_red=$'\033[1;31m'; c_ylw=$'\033[1;33m'; c_dim=$'\033[2m'; c_rst=$'\033[0m'
+[[ -t 1 ]] || { c_grn=""; c_red=""; c_ylw=""; c_dim=""; c_rst=""; }
+say() { printf '%s\n' "$*"; }
+ok() { printf '%s✓%s %s\n' "$c_grn" "$c_rst" "$*"; }
+warn() { printf '%s!%s %s\n' "$c_ylw" "$c_rst" "$*"; }
+err() { printf '%s✗%s %s\n' "$c_red" "$c_rst" "$*" >&2; }
+step() { printf '\n%s── %s%s\n' "$c_dim" "$*" "$c_rst"; }
+run() { if [[ "$DRY" -eq 1 ]]; then say " ${c_dim}[dry-run] $*${c_rst}"; else eval "$@"; fi; }
+
+command -v claude >/dev/null 2>&1 || { err "claude CLI not found in PATH"; exit 1; }
+command -v jq >/dev/null 2>&1 || { err "jq not found in PATH"; exit 1; }
+[[ -d "$MKT_CLONE" ]] || { err "marketplace clone missing: $MKT_CLONE (run: claude plugin marketplace add $MARKETPLACE)"; exit 1; }
+
+cur_installed_version() {
+ # newest materialised cache dir = the version currently in effect
+ ls -1 "$CACHE_ROOT" 2>/dev/null | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1
+}
+
+CUR="$(cur_installed_version || true)"
+say "${c_dim}ops-update — claude-ops local upgrade$([[ $DRY -eq 1 ]] && echo ' (DRY RUN)')${c_rst}"
+say "current installed: ${CUR:-<none>}"
+
+# ── 1. Refresh marketplace catalogue ───────────────────────────────────────
+step "1/8 Refresh marketplace catalogue ($MARKETPLACE)"
+if [[ "$DRY" -eq 1 ]]; then
+ say " ${c_dim}[dry-run] claude plugin marketplace update $MARKETPLACE${c_rst}"
+else
+ if claude plugin marketplace update "$MARKETPLACE" >/dev/null 2>&1; then
+ ok "marketplace catalogue refreshed via CLI"
+ else
+ warn "CLI marketplace update failed — falling back to git pull on the clone"
+ git -C "$MKT_CLONE" pull --ff-only >/dev/null 2>&1 && ok "git pull ok" || err "git pull failed (continuing)"
+ fi
+fi
+
+# ── 2. Resolve target version ──────────────────────────────────────────────
+step "2/8 Resolve target version"
+if [[ -n "$TARGET" ]]; then
+ NEW="$TARGET"
+else
+ NEW="$(jq -r --arg n "$PLUGIN" '.plugins[]|select(.name==$n).version' "$MKT_JSON" 2>/dev/null || true)"
+fi
+[[ "$NEW" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { err "could not resolve a semver target (got '$NEW') from $MKT_JSON"; exit 1; }
+say "target version: $NEW"
+if [[ "$CUR" == "$NEW" && "$FORCE" -eq 0 ]]; then
+ warn "already on $NEW. Use --force to re-materialise the cache (bug #61954 stale-cache guard)."
+fi
+
+# ── 3. Update the installed plugin ─────────────────────────────────────────
+step "3/8 Update installed plugin → $NEW"
+if [[ "$DRY" -eq 1 ]]; then
+ say " ${c_dim}[dry-run] claude plugin update $PLUGIN@$MARKETPLACE${c_rst}"
+ [[ "$FORCE" -eq 1 ]] && say " ${c_dim}[dry-run] (force) rm -rf $CACHE_ROOT/$NEW && claude plugin install $PLUGIN@$MARKETPLACE${c_rst}"
+else
+ claude plugin update "$PLUGIN@$MARKETPLACE" >/dev/null 2>&1 || warn "plugin update returned non-zero (will verify cache)"
+ if [[ ! -d "$CACHE_ROOT/$NEW" || "$FORCE" -eq 1 ]]; then
+ warn "cache for $NEW missing or --force set → force-reinstall (workaround for CC#61954)"
+ rm -rf "${CACHE_ROOT:?}/$NEW"
+ claude plugin install "$PLUGIN@$MARKETPLACE" >/dev/null 2>&1 || true
+ fi
+ if [[ -d "$CACHE_ROOT/$NEW" ]]; then ok "cache materialised: $CACHE_ROOT/$NEW"; else err "cache for $NEW not present after update"; fi
+fi
+NEW_CACHE="$CACHE_ROOT/$NEW"
+
+# ── 4. Reapply idempotent local cache patches ──────────────────────────────
+step "4/8 Reapply cache patches"
+PATCH_DIR="$THIS_ROOT/scripts/cache-patches"
+if [[ "$PATCHES" -eq 0 ]]; then
+ say " ${c_dim}(skipped: --no-patches)${c_rst}"
+elif [[ -d "$PATCH_DIR" ]] && compgen -G "$PATCH_DIR/*.sh" >/dev/null 2>&1; then
+ for patch in "$PATCH_DIR"/*.sh; do
+ name="$(basename "$patch")"
+ if [[ "$DRY" -eq 1 ]]; then say " ${c_dim}[dry-run] $name \"$NEW_CACHE\"${c_rst}"; continue; fi
+ if bash "$patch" "$NEW_CACHE" >/dev/null 2>&1; then ok "patch applied: $name"; else warn "patch failed (non-fatal): $name"; fi
+ done
+else
+ say " ${c_dim}no cache patches registered (none currently needed — all fixes upstream)${c_rst}"
+fi
+
+# ── 5. Prune old cache versions everywhere ─────────────────────────────────
+step "5/8 Prune old cache versions"
+if [[ "$PRUNE" -eq 0 ]]; then
+ say " ${c_dim}(skipped: --no-prune)${c_rst}"
+else
+ pruned=0
+ for d in "$CACHE_ROOT"/*/; do
+ [[ -d "$d" ]] || continue
+ v="$(basename "$d")"
+ [[ "$v" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || continue
+ [[ "$v" == "$NEW" ]] && continue
+ run "rm -rf \"$d\""
+ ok "pruned cache $v"; pruned=$((pruned+1))
+ done
+ [[ "$pruned" -eq 0 ]] && say " ${c_dim}no old cache versions to prune${c_rst}"
+fi
+
+# ── 6. Rewrite stale version-pinned paths in LIVE configs/scripts ──────────
+# Only touch live, editable configs that hardcode cache/<mp>/<plugin>/<OLDVER>/.
+# NEVER rewrite logs, memory notes, session transcripts, the cache, or the clone.
+step "6/8 Rewrite stale version-pinned paths → $NEW"
+if [[ "$REWRITE" -eq 0 ]]; then
+ say " ${c_dim}(skipped: --no-rewrite)${c_rst}"
+else
+ SCAN_DIRS=(
+ "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/scripts"
+ "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks"
+ "$HOME/.config/systemd/user"
+ )
+ SCAN_FILES=(
+ "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"
+ )
+ pat="cache/$MARKETPLACE/$PLUGIN/[0-9]\+\.[0-9]\+\.[0-9]\+"
+ rewrote=0
+ scan_one() {
+ local f="$1"
+ [[ -f "$f" && -w "$f" ]] || return 0
+ case "$f" in *.log|*/logs/*|*/.git/*) return 0 ;; esac
+ grep -qE "cache/$MARKETPLACE/$PLUGIN/[0-9]+\.[0-9]+\.[0-9]+" "$f" 2>/dev/null || return 0
+ # collect the distinct old versions referenced (anything != NEW)
+ local olds; olds="$(grep -oE "cache/$MARKETPLACE/$PLUGIN/[0-9]+\.[0-9]+\.[0-9]+" "$f" | sed -E "s#.*/##" | sort -u | grep -v "^$NEW\$" || true)"
+ [[ -z "$olds" ]] && return 0
+ if [[ "$DRY" -eq 1 ]]; then
+ say " ${c_dim}[dry-run] would rewrite $f ($(echo "$olds" | tr '\n' ' ')→ $NEW)${c_rst}"; rewrote=$((rewrote+1)); return 0
+ fi
+ sed -i -E "s#(cache/$MARKETPLACE/$PLUGIN/)[0-9]+\.[0-9]+\.[0-9]+#\1$NEW#g" "$f" \
+ && { ok "rewrote $f → $NEW"; rewrote=$((rewrote+1)); } || warn "rewrite failed: $f"
+ }
+ for d in "${SCAN_DIRS[@]}"; do
+ [[ -d "$d" ]] || continue
+ while IFS= read -r -d '' f; do scan_one "$f"; done \
+ < <(find "$d" -type f \( -name '*.sh' -o -name '*.json' -o -name '*.service' -o -name '*.conf' \) -print0 2>/dev/null)
+ done
+ for f in "${SCAN_FILES[@]}"; do scan_one "$f"; done
+ [[ "$rewrote" -eq 0 ]] && say " ${c_dim}no stale version-pinned paths in live configs (paths use \${CLAUDE_PLUGIN_ROOT})${c_rst}"
+fi
+
+# ── 7. Per-version idempotent migrations ───────────────────────────────────
+step "7/8 Post-update migrations"
+MIGRATE="$NEW_CACHE/bin/ops-post-update-migrate"
+if [[ "$DRY" -eq 1 ]]; then
+ say " ${c_dim}[dry-run] CLAUDE_PLUGIN_ROOT=$NEW_CACHE $MIGRATE${c_rst}"
+elif [[ -x "$MIGRATE" ]]; then
+ CLAUDE_PLUGIN_ROOT="$NEW_CACHE" bash "$MIGRATE" >/dev/null 2>&1 && ok "post-update migrations ran" || warn "post-update-migrate exited non-zero (non-fatal)"
+else
+ say " ${c_dim}no ops-post-update-migrate in new cache (skipped)${c_rst}"
+fi
+
+# ── 8. Report ──────────────────────────────────────────────────────────────
+step "8/8 Summary"
+say " plugin: $PLUGIN@$MARKETPLACE"
+say " version: ${CUR:-<none>} → ${c_grn}$NEW${c_rst}"
+say " cache: $(ls -1 "$CACHE_ROOT" 2>/dev/null | grep -E '^[0-9]+\.' | tr '\n' ' ')"
+if [[ "$DRY" -eq 1 ]]; then
+ warn "DRY RUN — nothing changed. Re-run without --dry-run to apply."
+else
+ ok "upgrade complete."
+ say ""
+ say " ${c_ylw}Restart Claude Code (or run /reload-plugins) to load v$NEW.${c_rst}"
+fi
diff --git a/claude-ops/scripts/cache-patches/README.md b/claude-ops/scripts/cache-patches/README.md
new file mode 100644
index 00000000..ee207dc8
--- /dev/null
+++ b/claude-ops/scripts/cache-patches/README.md
@@ -0,0 +1,33 @@
+# cache-patches — local plugin-cache patch registry
+
+`ops-update` (step 4) runs every `*.sh` in this directory against the freshly
+materialised plugin cache, **in filename order**, after a plugin upgrade.
+
+Use this for fixes that must live on the box *before they are merged upstream*
+— e.g. a hotfix to a `bin/` script or `SKILL.md` that the new cache version
+overwrites on every `claude plugin update`. Once the fix ships in a release,
+delete the patch here (the upstream version supersedes it).
+
+## Contract
+
+Each patch script:
+
+- Receives the new cache dir as `$1` (e.g. `~/.claude/plugins/cache/ops-marketplace/ops/2.19.0`).
+- **MUST be idempotent** — gate every edit on a sentinel string so a re-run is a no-op.
+- Should exit `0` on success; a non-zero exit is logged as a non-fatal warning.
+- Must not touch anything outside the cache dir it is handed.
+
+## Example
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+CACHE="${1:?cache dir required}"
+target="$CACHE/bin/some-script"
+sentinel="# PATCH-XYZ applied"
+grep -qF "$sentinel" "$target" && exit 0 # already patched → no-op
+printf '\n%s\n' "$sentinel" >> "$target" # apply, gated by sentinel
+```
+
+This registry is intentionally empty when every local fix has been released
+upstream — that is the desired steady state.
diff --git a/claude-ops/skills/ops-update/SKILL.md b/claude-ops/skills/ops-update/SKILL.md
new file mode 100644
index 00000000..03697cf8
--- /dev/null
+++ b/claude-ops/skills/ops-update/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: ops-update
+description: Upgrade the local claude-ops ("ops") plugin to the latest published version in one command — refresh the marketplace catalogue, update the installed plugin (with stale-cache force-reinstall fallback), reapply local cache patches, prune every old cache version, rewrite stale version-pinned paths, run per-version migrations, then prompt to reload. Use when the box is on an older plugin version, after a release, or when the cache looks stale.
+argument-hint: "[--dry-run|--force|--to X.Y.Z|--no-prune|--no-patches|--no-rewrite]"
+allowed-tools:
+ - Bash
+ - Read
+ - AskUserQuestion
+---
+
+# 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 an 8-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](https://github.com/anthropics/claude-code/issues/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).
+8. **Report** — old→new, what changed, and that a restart / `/reload-plugins` is needed to load it.
+
+## 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
+
+```bash
+${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
+
+```bash
+${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
+
+| Flag | Effect |
+|------|--------|
+| `--dry-run` | Report only; change nothing. Always run this first. |
+| `--force` | Force-reinstall even when the CLI claims "already latest" (bug #61954). |
+| `--to X.Y.Z` | Target a specific version instead of the catalogue's newest. |
+| `--no-prune` | Keep old cache versions. |
+| `--no-patches` | Skip the cache-patch reapply step. |
+| `--no-rewrite` | Skip the stale-version-path rewrite step. |
+
+## 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 <ver>" → 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.