# Hv Update

> Check for a newer hv-skills release on GitHub and tell the user how to update — detects install type (plugin, stow, repo clone), compares plugin.json version against the latest release, and prints the exact update command. Read-only; does not run the update itself. Use on "check for updates", "is hv-skills up to date", before long /hv-work sessions.

- Skill: `l4ci/hv-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add l4ci/hv-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l4ci/hv-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: l4ci (https://skillmd.com/u/l4ci)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l4ci/hv-update

---


**Print the banner below verbatim before any other action — skip if dispatched as a subagent.** See `references/banner-preamble.md`.

```
════════════════════════════════════════════════════════════════════════
  🆙  hv-update  ·  check for newer hv-skills release
  triggers: "check for updates"  ·  pairs: —
════════════════════════════════════════════════════════════════════════
```

# hv-update — Check for hv-skills Updates

## When NOT to Use

- You explicitly pinned to an older version → skip this
- Offline / airgapped session → the check will fail gracefully but isn't useful

## Step 1 — Preflight

Requires `gh` on the `PATH`:

```bash
command -v gh >/dev/null 2>&1 || echo "gh not installed"
```

If missing, tell the user the check needs `gh` (or `brew install gh` / equivalent) and stop. Don't try to `curl` the GitHub API — users with `gh` get auth'd rate limits for free.

```bash
.hv/bin/hv-preflight
```

See `docs/reference/preflight.md` for exit-code handling.

## Step 2 — Run the Check

```bash
.hv/bin/hv-update-check
```

Parses JSON output:

- `installType` — `plugin` | `stow` | `repo` | `override` | `unknown`
- `installRoot` — absolute path to the detected install
- `currentVersion` — semver from `plugin.json`
- `latestVersion` — semver of the latest GitHub release (empty if fetch failed)
- `status` — `behind` | `current` | `ahead` | `unknown`
- `updateCommand` — the exact shell command for the detected install type

## Step 3 — Present Verdict

Emit one compact block keyed by the `status` field from Step 2. Templates live in `references/update-verdicts.md` — substitute the JSON fields verbatim, no editorial massaging.

| `status` | Template in `references/update-verdicts.md` |
|----------|---------------------------------------------|
| `current` | `## current` |
| `behind`  | `## behind`  |
| `ahead`   | `## ahead`   |
| `unknown` | `## unknown` |

Add new status values to both the helper and the reference together.

## Step 4 — Offer to Re-Init

Apply only when Step 2's `status` is `behind`. Skip entirely on `current`, `ahead`, or `unknown` — there's nothing to refresh.

Read `.hv/config.json#autonomy.level` (default `"off"`) and branch:

**`"off"` (default):**

Print one nudge line after the verdict block:

> After running the update command above, re-run `/hv-init` in this project to refresh `.hv/bin/` helpers and clear the drift nudge.

Don't auto-invoke. The user may want to update multiple projects before re-initialising any of them.

**`"auto"`:**

Use `AskUserQuestion`:

- **Header:** `"Re-init"`
- **Question:** *"Plugin update is `<current> → <latest>`. Already ran `claude plugin update hv-skills`? Run `/hv-init` now to refresh `.hv/bin/` helpers in this project?"*
- **Options** (single-select):
  1. *"Yes, run `/hv-init` now (Recommended)"* — *"Refreshes `.hv/bin/` and re-stamps `hvSkills.version` so drift detection clears."*
  2. *"Not yet — I'll run the update first"* — *"Skip; re-invoke `/hv-update` after running the update command."*
  3. *"Skip — I'll run `/hv-init` later"* — *"No-op; the drift nudge will keep firing on every preflight until then."*
- Plain-text fallback: ask once textually — *"Already ran `claude plugin update hv-skills`? Run `/hv-init` now to refresh helpers? (yes/no)"* — honor yes/no, default off (don't dispatch on ambiguous reply).

On answer 1: **dispatch `hv-init` via `Skill` immediately — no prompt, no confirmation, no "want me to" question.** Pass no args (the skill knows what to do from cwd).

**`"loop"`:**

Skip the question entirely. Print one informational line first so the user sees the pick:

> Loop: dispatching `/hv-init` to refresh helpers (assumes plugin update already ran).

Then **dispatch `hv-init` via `Skill` immediately — no prompt, no confirmation, no "want me to" question.** Pass no args.

If the plugin actually wasn't updated, `/hv-init`'s STALE migration just re-stamps the same version and is a no-op for everything else — the loop contract trades that edge case for full chaining.

---

Across projects: each project tracks its own `hvSkills.version`. Updating the plugin once leaves all projects drifted; re-run `/hv-init` per project to clear them.

## Rules

- **Read-only.** Never invoke the update command yourself. Surface it, let the user run it.
- **Network-dependent.** If `gh` can't reach the API, report `unknown` and stop — don't retry on a loop.
- **Honor dev builds.** An `ahead` status is not an error; contributors run that way.
- **Helpers refresh is separate.** Upgrading the plugin does not rewrite `.hv/bin/` in existing projects. Step 4 nudges (off), asks (auto), or auto-dispatches `/hv-init` (loop) — but per project. Multi-project users still re-run `/hv-init` in each project explicitly.

## References

- [`references/banner-preamble.md`](../references/banner-preamble.md) — Banner-print rule shared by every skill.
- [`references/update-verdicts.md`](../references/update-verdicts.md) — Update-check verdicts and routing for `/hv-update`.