lifecycle-innovations-limited / ops-update

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 <ver>" 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 <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.