/orbit-upgrade

Upgrade the orbit plugin and show what's new. This updates the plugin/scaffolder only — it never touches the CLAUDE.md, roles, or loop files a previous run already scaffolded into a product repo (those are that project's files).

Inline upgrade flow

This section is referenced by the /orbit preamble when it detects UPGRADE_AVAILABLE <old> <new>. Run the steps in order.

Step 0: resolve the install (one deterministic call — no candidate loop)

Run the trusted resolver. It ALWAYS names the active install (it runs from it), and reports version, commit, how many commits behind origin, dirty tracked files, and any stale copies — so there is no narrated search and no "standard paths didn't resolve." The executable is literal (./orbit-resolve), the variable is only a cd argument — same style as the /orbit preamble, so the guard never prompts.

_CC="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
if   [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -x "$CLAUDE_PLUGIN_ROOT/bin/orbit-resolve" ]; then ( cd "$CLAUDE_PLUGIN_ROOT/bin" && ./orbit-resolve --upgrade-check )
elif [ -x "$_CC/skills/orbit/bin/orbit-resolve" ];          then ( cd "$_CC/skills/orbit/bin" && ./orbit-resolve --upgrade-check )
elif [ -x "$HOME/.claude/skills/orbit/bin/orbit-resolve" ]; then ( cd "$HOME/.claude/skills/orbit/bin" && ./orbit-resolve --upgrade-check )
elif [ -x ".claude/skills/orbit/bin/orbit-resolve" ];       then ( cd .claude/skills/orbit/bin && ./orbit-resolve --upgrade-check )
fi

Read the JSON it prints:

• active_install → INSTALL_DIR for the rest of these steps; is_git → IS_GIT.
• behind > 0 → an upgrade is available (proceed). behind == 0 → already current (tell the user the version and stop, unless they explicitly asked to re-pull).
• dirty == true → mention dirty_files before Step 3 (they'll be stashed).
• other_installs non-empty → note the stale copy (e.g. an old plugin-cache …/orbit/orbit/0.4.0) so the user can remove it; it is NOT the active install and won't be touched.

(Only if the resolver produced no output — a broken/very old install without bin/orbit-resolve — fall back to: read VERSION from ${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/orbit} and treat IS_GIT from whether that dir has .git.)

Step 1: ask once, then honor the choice (consent-once, opt-out default)

The posture is auto-upgrade recommended, but a user should get one say in it — not silent auto-updates forever, and not a prompt on every release. So: the first time an upgrade is offered and auto_upgrade is unset, ask once; persist the answer; honor it silently ever after.

STATE_DIR="${ORBIT_HOME:-$HOME/.orbit}"; mkdir -p "$STATE_DIR" 2>/dev/null || true
_auto="$(grep -E '^auto_upgrade=' "$STATE_DIR/config" 2>/dev/null | tail -1 | cut -d= -f2-)"
[ "${ORBIT_AUTO_UPGRADE:-}" = "1" ] && _auto="true"
[ "${ORBIT_AUTO_UPGRADE:-}" = "0" ] && _auto="false"
echo "AUTO_UPGRADE=${_auto:-unset}"

If AUTO_UPGRADE=unset (first upgrade, no choice recorded yet): ask once with the AskUserQuestion tool — "Keep Orbit auto-updated?" with the Recommended option first:

• Yes, auto-update (Recommended) — stay current hands-off; each upgrade is announced, never silent.
• No, ask me each time — I'll tell you when a version is available and wait for /orbit-upgrade.

Then persist the choice with _set auto_upgrade true|false (below) and proceed by the matching branch. This is the only time you ask; every later upgrade honors the saved value silently.

If AUTO_UPGRADE=true: skip the question. Say "⬆️ Auto-upgrading orbit v{old} → v{new}…" and go to Step 2. (Announced + shows what's new in Step 5 — auto, never silent. Opt out anytime with auto_upgrade=false.)

If AUTO_UPGRADE=false (opted out): don't upgrade and don't nag — just one line: "orbit v{new} is available (you're on v{old}). Run /orbit-upgrade when you want it." Then continue the original skill.

To write a config key (create the file if missing):

_set() { mkdir -p "$STATE_DIR"; touch "$STATE_DIR/config"; grep -v -E "^$1=" "$STATE_DIR/config" > "$STATE_DIR/config.tmp" 2>/dev/null || true; echo "$1=$2" >> "$STATE_DIR/config.tmp"; mv "$STATE_DIR/config.tmp" "$STATE_DIR/config"; }
# usage: _set auto_upgrade true   |   _set update_check false

Step 2: save the old version

OLD_VERSION="$(tr -d '[:space:]' < "$INSTALL_DIR/VERSION" 2>/dev/null || echo unknown)"
echo "OLD_VERSION=$OLD_VERSION"

Step 3: upgrade

Git install (IS_GIT=yes) — the normal case:

cd "$INSTALL_DIR"
_STASH="$(git stash 2>&1)"
git fetch origin
_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo main)"
git reset --hard "origin/$_BRANCH"
echo "$_STASH" | grep -q "Saved working directory" && echo "NOTE: local changes were stashed — run 'git stash pop' in $INSTALL_DIR to restore."
_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
echo "Now at commit $_SHA on $_BRANCH — this is a floating-branch install, not a signed release;
this is the checkable record of exactly what code is now running."

Skills-dir install (IS_GIT=no and $INSTALL_DIR/.install-method says method=skills-dir, or $INSTALL_DIR is under ~/.claude/skills/) — the default install: re-run the installer, which re-downloads the latest and overwrites in place (no restart needed):

_BR="$(grep -E '^branch=' "$INSTALL_DIR/.install-method" 2>/dev/null | cut -d= -f2-)"; _BR="${_BR:-main}"
ORBIT_BRANCH="$_BR" bash -c 'curl -fsSL "https://raw.githubusercontent.com/Abdulaziz-almoshen/orbit/'"$_BR"'/install.sh" | bash'

Plugin-cache install (IS_GIT=no and $INSTALL_DIR is under ~/.claude/plugins/): prefer the platform updater — tell the user to run /plugin update orbit@orbit (or /plugin marketplace update orbit), since Claude Code owns that cache. Do not git-clone over a managed cache.

Step 4: mark + clear caches

echo "$OLD_VERSION" > "$STATE_DIR/just-upgraded-from"
rm -f "$STATE_DIR/last-update-check" "$STATE_DIR/update-snoozed" 2>/dev/null || true
NEW_VERSION="$(tr -d '[:space:]' < "$INSTALL_DIR/VERSION" 2>/dev/null || echo unknown)"
echo "Upgraded $OLD_VERSION -> $NEW_VERSION"

Step 5: show what's new

Read $INSTALL_DIR/CHANGELOG.md. Summarize the entries between OLD_VERSION and the new version as 3–6 user-facing bullets (skip internal refactors). Format:

orbit v{new} — upgraded from v{old}! (commit {sha})

What's new:
- …

⚠️ This upgraded the PLUGIN only — your already-scaffolded projects still run their OLD local
scaffold (that's a separate freshness). To see if a project is behind, run `orbit-doctor` inside
it (read-only: scaffold drift + a safe-refresh plan; underneath, `scaffold.py --check-drift` +
`--plan-refresh`). To refresh it: re-run /orbit inside it for the full merge (adds missing
files/hooks + re-stamps the version), or `orbit-doctor --fix` for just the safe managed-hook
changes — either way it hash-gates and **never clobbers** a customized guard.py.

Include {sha} (from Step 3's $_SHA, when the install is a git checkout) — it's the concrete, checkable record of what's now running, since this is a floating-branch install, not a signed release.

Step 6: continue

Resume whatever the user originally invoked. If this was triggered from the /orbit preamble, go back into that workflow. The upgrade is done.

Standalone usage (/orbit-upgrade invoked directly)

1. Force a fresh check (bypass the 24h throttle):

   # literal executable (`./orbit-update-check`); the variable is only a `cd` argument → no guard prompt
   _CC="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
   if   [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -x "$CLAUDE_PLUGIN_ROOT/bin/orbit-update-check" ]; then ( cd "$CLAUDE_PLUGIN_ROOT/bin" && ./orbit-update-check --force )
   elif [ -x "$_CC/skills/orbit/bin/orbit-update-check" ];          then ( cd "$_CC/skills/orbit/bin" && ./orbit-update-check --force )
   elif [ -x "$HOME/.claude/skills/orbit/bin/orbit-update-check" ]; then ( cd "$HOME/.claude/skills/orbit/bin" && ./orbit-update-check --force )
   fi

2. If it prints UPGRADE_AVAILABLE <old> <new> → run Steps 0–6 above.
3. If it prints nothing → run Step 0 to find INSTALL_DIR, read VERSION, and tell the user "You're already on the latest version (v{version})."