---
name: check-version
description: Compares the locally installed version of a skill or subagent against its upstream source (sha or semver) and reports whether an update is available. Cache-aware (1-hour TTL). Used by `orchestrate` before dispatching a subagent or invoking a skill, to guarantee the components are fresh.
when_to_use: |
  Called by `orchestrate` in step 4 for each component about to be used.
  Also invocable directly: "verifique versão de react-specialist",
  "/maxvision-orchestration:check-version anthropic-skills",
  "/maxvision-orchestration:check-version --force frontend-design".
disable-model-invocation: false
allowed-tools: Read Bash(test *) Bash(jq *) Bash(gh api *) Bash(gh auth status) Bash(date *) Bash(mkdir -p *) Bash(cat *)
---

# Check version

Argument: $ARGUMENTS — component id (skill or subagent name) and optional `--force-check` flag.

## Cache layout

- File: `~/.claude/cache/maxv-orchestration/version-check.json`
- Schema:
  ```json
  {
    "$schema_version": "1.0.0",
    "entries": {
      "<component_id>": {
        "kind": "plugin|skill|agent",
        "local_sha": "abc...",
        "remote_sha": "def...",
        "last_check_iso": "2026-04-28T14:32:11Z",
        "ttl_seconds": 3600,
        "source_repo": "owner/repo",
        "source_branch": "main",
        "status": "up_to_date|stale|missing"
      }
    }
  }
  ```

## Workflow

### 1. Parse args

- Extract the component id (first non-flag token).
- Detect `--force-check` flag (ignores cache).

### 2. Cache lookup (skip if `--force-check`)

```bash
mkdir -p ~/.claude/cache/maxv-orchestration
test -f ~/.claude/cache/maxv-orchestration/version-check.json || echo '{"$schema_version":"1.0.0","entries":{}}' > ~/.claude/cache/maxv-orchestration/version-check.json
```

Read the entry. If `last_check_iso` is within `ttl_seconds` from now, **return cached result** with note `(from cache, age=<N>min)`.

### 3. Resolve component → source

Determine `kind` and `source_repo`:

- **Plugin install:** look up `~/.claude/plugins/installed_plugins.json` for `<plugin>@<marketplace>` entries. The `gitCommitSha` is the local sha. The marketplace's `extraKnownMarketplaces[<marketplace>].source.repo` from `~/.claude/settings.json` is the upstream repo.
- **Manually-cloned skill:** look for `~/.claude/skills/<name>/.maxv-source.json`. Read `repo`, `commit_sha`, `branch` (default `main`).
- **Agent inside a plugin:** same as plugin install (the agent file lives under the plugin's `gitCommitSha`).
- **Catalog source not yet installed:** mark `status: missing` and skip remote check.

### 4. Fetch remote sha

```bash
gh api repos/<owner>/<repo>/commits/<branch> --jq .sha
```

If `gh auth status` fails, abort with an actionable error: "gh CLI not authenticated. Run `gh auth login`."

### 5. Compare and classify

- `local_sha == remote_sha` → `up_to_date`.
- `local_sha != remote_sha` → `stale`.
- No local install → `missing`.

### 6. Update cache

Rewrite the cache entry with new `last_check_iso = now()` and the result.

### 7. Output

Return a single-line per component (when batched) or a structured block (when invoked alone):

```
Component: anthropic-skills (frontend-design)
Kind: plugin
Source: anthropics/skills @ main
Local sha:  abc1234...
Remote sha: def5678...
Status: ⚠ stale (update available)
Cache: refreshed just now
```

## Batch mode

When called with multiple component ids (space-separated), produce a table:

```
Component                          | Kind   | Local        | Remote       | Status
voltagent-lang (react-specialist)  | plugin | 1.0.4        | 1.0.4        | ✓ up-to-date
anthropic-skills (frontend-design) | plugin | sha:abc      | sha:def      | ⚠ stale
shadcn/ui (skill)                  | skill  | —            | sha:xyz      | ✗ missing
```

## Guardrails

- **Never write outside `~/.claude/cache/maxv-orchestration/`.**
- **Never call `gh api` for components that are not in the catalog or in `installed_plugins.json`** — abort with "unknown component" instead.
- If the user is offline (`gh api` fails with network error), serve from cache regardless of TTL and append `(cache served — offline)`.
- Never auto-update from this skill. Only report. The user (via `orchestrate` or directly) invokes `update-component` if needed.