agent-plus-upgrade

name	agent-plus-upgrade
description	agent-plus | Trigger doctrine for Claude Code — when to proactively probe for and offer agent-plus framework upgrades. Pure markdown skill; the runtime is the existing `agent-plus-meta upgrade-check` / `agent-plus-meta upgrade` subcommands (frozen v0.13.5 contract) — snooze ladder, `update_check`/`silent_upgrade` config, `.bak` rollback, and a post-upgrade doctor gate are already built. Probes at most once per session, only surfaces an offer on `upgrade_available` with no active snooze, and never mutates without an explicit user choice.
when_to_use	Two trigger paths — explicit (always wins, no cap) and ambient (soft, once per session): **Explicit** — the user directly asks. Trigger immediately, regardless of AGENT_PLUS_UPGRADE_CHECKED, on: "is agent-plus up to date", "check for agent-plus updates", "update agent-plus", "upgrade agent-plus", "am I on the latest agent-plus version", or equivalent phrasing naming the framework itself (not a sibling plugin like vercel-remote). Add `--force` if an earlier ambient probe this session may have cached a stale result. **Ambient** — once per session, after the FIRST agent-plus skill/tool call in the session has finished its own work (don't delay the user's actual ask to run an upgrade probe first). Trigger the probe when ALL hold: (a) an agent-plus skill has been invoked this session (agent-plus-meta, repo-analyze, diff-summary, skill-feedback, skill-plus, or a marketplace-installed skill), AND (b) this skill has not already probed this session via the ambient path (AGENT_PLUS_UPGRADE_CHECKED flag in conversation memory — explicit requests are exempt from this cap), AND (c) the environment is not CI/ephemeral ($CI, $GITHUB_ACTIONS, $CODESPACES unset; cwd not under /tmp). After probing on either path, only surface an unsolicited offer when the envelope shows ALL of: `verdict == "upgrade_available"`, `config.update_check != false`, and `snooze.active != true`. On the ambient path, anything short of that means stay silent — don't mention the probe happened at all. On the explicit path, always answer the question asked (e.g. plainly report `up_to_date`) even when there's nothing to offer.
allowed-tools	Bash(agent-plus-meta:*)

agent-plus-upgrade

Trigger doctrine for when to check whether the agent-plus framework itself is out of date, and how to offer the fix — same shape as agent-plus-installer, but for the upgrade path instead of the install path. No new mechanism: agent-plus-meta upgrade-check and agent-plus-meta upgrade already exist, fully built, with a frozen v0.13.5 JSON contract (snooze ladder, .bak rollback, migrations, in-process post-upgrade doctor gate).

This skill exists because, until 2026-07-07, nothing ever called upgrade-check — it wasn't wired into any nextSteps chain and no skill triggered it, so every installed user silently drifted from the latest release with no signal. Since then, envcheck's clean-path nextSteps also appends upgrade-check as a suggested command (see the root README's funnel table) — that closes reach for sessions that run the standard bootstrap, but a nextSteps entry is only ever a suggested string, never an automatic action, and it only fires when envcheck itself runs with nothing missing. This skill still owns the judgment neither the funnel nor the CLI provides on its own: deciding whether an upgrade is actually worth surfacing (verdict / config.update_check / snooze.active gating), presenting the right one of the four choices, and driving the silent_upgrade fast path correctly. The two are complementary, not redundant — funnel widens reach, this skill supplies the decision.

The probe

agent-plus-meta upgrade-check

Cheap and safe to run proactively: reads a cache first (TTL 60min when up to date, 720min once an upgrade is already known to be available), falls back to a capped ≤3s network GET of a single-root VERSION file, and fails silently on any network error (never raises, never blocks). Read the JSON envelope's gating fields before deciding whether to say anything:

Field	Meaning	Your action
verdict	up_to_date | upgrade_available | unknown (just_upgraded is reserved in the frozen contract but not currently emitted by cmd_upgrade_check — don't branch on it)	Only upgrade_available is worth surfacing.
config.update_check	false means the user already chose "Never ask again"	If false, stay silent — don't surface anything, don't re-probe later this session either.
snooze.active	true means the user is inside an active 24h/48h/7d/never snooze window	If true, stay silent even when verdict == upgrade_available.
errors	Non-empty on network failure	Stay silent; this probe is best-effort by design.

This table is the authority, not the envelope's own nextSteps field. The JSON agent-plus-meta upgrade-check returns carries a nextSteps suggestion of its own (part of the framework's general funnel convention) — when it says verdict == upgrade_available, that field does now also check config.update_check/snooze.active before suggesting upgrade (fixed 2026-07-07), but decide your own next action from the four rows above regardless of what nextSteps says. Don't chain into a second, redundant agent-plus-meta doctor call just because the envelope's nextSteps mentions one — you already have everything you need from this one probe.

Set AGENT_PLUS_UPGRADE_CHECKED=1 in conversation memory immediately after the probe (regardless of outcome) so this skill does not re-probe again this session.

Offering the upgrade

Only when the table above clears do you act — and the first branch is config.silent_upgrade, not a question:

• config.silent_upgrade == true — the user already chose "Always" in an earlier session. Don't ask again; run agent-plus-meta upgrade --non-interactive --auto directly. The CLI's own --auto logic does the right thing without you computing anything: it applies patch bumps immediately, and still degrades minor/major bumps to snooze even under --auto (it never silently lands those). This is the only case where AskUserQuestion is skipped, and it's skipped because the user already answered — durably, via config, not just this session.

• config.silent_upgrade == false (the default, and true for anyone who has never chosen "Always" through this skill before) — present the same four options the CLI's own interactive prompt (_prompt_choice()) defines, so the user's choice maps 1:1 onto --user-choice:

  Choice	--user-choice	Effect
  Yes — upgrade now	yes	Applies immediately.
  Always — silent on patch bumps	always	Applies immediately (same as "Yes") AND sets silent_upgrade: true; future minor/major bumps still ask.
  Snooze — remind me later	snooze	Advances the ladder (24h → 48h → 7d → never); no upgrade.
  Never ask again	never	Sets update_check: false; no upgrade.

  Present via AskUserQuestion (all four options, not a yes/no). Only after the user picks, run:

  agent-plus-meta upgrade --user-choice <yes|always|snooze|never>
  

Do NOT use this for

• config.update_check == false. The user already said never ask again. Don't re-surface it, don't mention it, don't ask "are you sure" — that's exactly the nagging this flag exists to prevent.
• An active snooze. Even with verdict == upgrade_available, if snooze.active == true stay silent. Snoozing means nothing if the next skill invocation just asks anyway.
• CI or ephemeral environments. If $CI, $GITHUB_ACTIONS, $CODESPACES, or similar are set, or cwd is under /tmp, skip the probe entirely — nothing will persist and it wastes a network call.
• Already probed this session — ambient path only. Honor AGENT_PLUS_UPGRADE_CHECKED for the ambient trigger: one ambient probe per session, not one per skill invocation. An explicit user request ("is agent-plus up to date?") always re-probes regardless of this flag; add --force if the cached result might be stale.
• --non-interactive --auto without config.silent_upgrade == true. That's the only condition allowed to skip AskUserQuestion (see "Offering the upgrade"). Never take the --auto fast path just because verdict == upgrade_available — that would apply a patch bump without the user ever having consented, even once.

Safety rules

1. Surface, never auto-execute. This skill produces an offer via AskUserQuestion. Claude MUST let the user pick one of the four options before running any mutating Bash call. The Claude Code permission prompt on the upgrade Bash call is a second gate, not the first.
2. Permission-prompt per invocation. The probe and (if chosen) the upgrade are two separate Bash calls, each through Claude Code's normal permission prompt. Never bundle them into one approval.
3. Trust the CLI's own safety net — don't work around it. upgrade already snapshots every primitive to .bak before replacing it, runs an in-process doctor gate afterward, and auto-rolls-back on verdict: "rolled_back" or a broken doctor verdict. Never manually delete .bak snapshots, never pass --rollback without an explicit user ask, never retry a failed upgrade in a loop.
4. The silent_upgrade check is this skill's own gate, not something the CLI enforces for you. agent-plus-meta upgrade --non-interactive --auto applies a patch bump regardless of config.silent_upgrade — that flag only changes which label the CLI records ("always" vs "yes"), not whether the bump lands. This skill is the one that must never invoke --auto except when it has already confirmed config.silent_upgrade == true (per "Offering the upgrade" above) — invoking it "just because verdict == upgrade_available" would apply a patch bump nobody ever consented to. Minor/major bumps are the one thing the CLI itself still refuses to silently land under --auto (degrades to snooze regardless of silent_upgrade) — but don't rely on that as your only guard; the skill's own gate above is what actually protects patch bumps on a first encounter.
5. Report failures verbatim. If upgrade returns verdict: "rolled_back" or "error", paste the envelope's errors[] back to the user exactly. Do not retry silently. Do not paraphrase the error away.

Architecture

The ambient path (the explicit path is simpler — skip straight to the probe, skip the flag checks, always answer):

First agent-plus skill/tool call this session completes its own work
   |
   v
AGENT_PLUS_UPGRADE_CHECKED already set? --yes--> stop
   | no
   v
CI/ephemeral env, or cwd under /tmp? --yes--> stop (don't set the flag; retry next real session)
   | no
   v
Claude runs (permission-gated): agent-plus-meta upgrade-check
   |
   v
Set AGENT_PLUS_UPGRADE_CHECKED=1 regardless of outcome
   |
   v
verdict=="upgrade_available" AND config.update_check!=false AND snooze.active!=true?
   | no                                                            | yes
   v                                                                v
 stay silent, don't mention the probe              config.silent_upgrade == true?
                                                     | yes                    | no
                                                     v                        v
                                    agent-plus-meta upgrade         AskUserQuestion: 4-option prompt
                                      --non-interactive --auto                |
                                    (CLI applies patch bumps    +---------------+-----------+-----------+
                                     silently, still degrades   v               v           v           v
                                     minor/major to snooze)   "yes"         "always"    "snooze"     "never"
                                                     |            |               |           |           |
                                                     |            v               v           v           v
                                                     |  agent-plus-meta upgrade --user-choice <yes|always|snooze|never>
                                                     |            |
                                                     +------------+
                                                                  v
                                        Report the envelope's verdict verbatim.
                                success -> done.  rolled_back / error -> paste errors[] verbatim, don't retry.

Why this lives in a separate skill, not folded into agent-plus-meta's own SKILL.md. Same reasoning agent-plus-installer already documents for the install path: upgrade is its own concern with its own trigger cadence (once per session, conditional on a prior skill call) distinct from agent-plus-meta's session-start bootstrap doctrine (init/envcheck/refresh, run unconditionally at session start). Keeping them separate means declining or snoozing an upgrade offer never touches the bootstrap flow, and vice versa.