---
name: spec-update
description: |
  Check whether spec-first is up to date and whether the current host runtime
  assets need refreshing. Use when the user says "update spec-first",
  "check spec-first version", "spec-first update", "is spec-first up to date",
  "update spec-first plugin", or reports issues that might stem from stale
  spec-first plugin, CLI, or generated runtime assets. Supports Claude Code and
  Codex with host-specific update commands.
disable-model-invocation: true
---

# Check Spec-First Version And Runtime Assets

Verify the installed spec-first version and recommend the host-appropriate
update command when it is stale. Also check whether generated runtime assets
should be refreshed for the active host.

## Workflow Contract Summary

### When To Use

Use when checking spec-first version freshness, stale plugin/CLI symptoms, or whether Claude/Codex generated runtime assets should be refreshed from source.

### When Not To Use

Do not use for feature work, graph/provider readiness refresh, MCP setup repair, or hand-editing generated runtime mirrors as source fixes.

### Inputs

Current host signals, package/plugin version probes, startup reminder state, host runtime state, generated runtime drift facts, and optional user update intent.

### Outputs

Version comparison, stale/current classification, host-appropriate update or init command recommendation, and runtime refresh guidance.

### Artifacts

Startup reminder cooldown state may be reset. Source files remain authoritative; generated runtime mirrors are refreshed only through explicit init/update commands.

### Failure Modes

Ambiguous host, version probe failure, non-marketplace Claude plugin layout, npm/registry lookup failure, runtime drift, or user declines the update action.

### Workflow

Detect host, reset explicit-check cooldown, gather host-specific version/runtime facts, compare against upstream/source truth, then recommend the next command without silent mutation.

### Downstream Consumers

Human maintainers, startup reminder routing, setup/update troubleshooting, and `using-spec-first` guidance when runtime assets are stale.

## Scenario Capability

Follows `docs/contracts/workflows/scenario-capability-matrix.md` (default).
Overrides: none

## Host model

- **Claude Code** installs spec-first as a Claude plugin. Version checks use the
  Claude plugin cache path and update via `claude plugin update`.
- **Codex** uses the `spec-first` npm CLI to generate runtime assets into the
  current project. Version checks use the installed CLI and npm registry, then
  refresh runtime assets with `spec-first init` and Codex selected when prompted.

Do not use Claude plugin cache paths to decide Codex state. Do not use npm CLI
version facts to decide Claude marketplace cache state.

Startup version reminders may route users here through `/spec:update` on Claude
Code or `$spec-update` on Codex. Those reminders are advisory only: they do not
install packages, refresh runtime assets, or restart the host. This workflow
remains the single place where the user decides whether to update.

## Claude Code Version Probe Scripts

In Claude Code, gather the marketplace-cache version facts by running these
scripts with the Bash tool. Each script prints one line. Capture the values for
the Claude Code branch below.

`${CLAUDE_SKILL_DIR}` is a Claude Code-documented substitution that resolves
at skill-load time. For a marketplace-cached install it looks like
`~/.claude/plugins/cache/<marketplace>/spec-first/<version>/skills/spec-update`,
so the currently-loaded version is the basename two `dirname` levels up.

The upstream version comes from source `package.json` on `main` rather than
the latest GitHub release tag, because the marketplace installs plugin contents
from `main` HEAD. Comparing against release tags false-positives whenever
`main` is ahead of the last tag (the normal state between releases).

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/upstream-version.sh"
bash "${CLAUDE_SKILL_DIR}/scripts/currently-loaded-version.sh"
bash "${CLAUDE_SKILL_DIR}/scripts/marketplace-name.sh"
```

`scripts/upstream-version.sh` reads source `package.json` on `main` via `gh api`.
It prints the version string, or the sentinel
`__SPEC_UPDATE_VERSION_FAILED__` if the lookup fails.

`scripts/currently-loaded-version.sh` and `scripts/marketplace-name.sh` parse
their own script path against the marketplace-cache layout above. They print the
version segment / marketplace segment, or the sentinel
`__SPEC_UPDATE_NOT_MARKETPLACE__` if the path does not match. That mismatch is
normal for `claude --plugin-dir` local-development sessions.

## Decision Logic

### 1. Detect the active host

Use the first matching signal:

1. If **Skill directory** is populated and looks like a Claude Code skill path,
   use the Claude Code branch.
2. If running in Codex, or if the user invoked `$spec-update`, use the Codex
   branch.
3. If the host is ambiguous, inspect the project:
   - `.codex/spec-first/state.json` or `.agents/skills/spec-update/SKILL.md`
     indicates Codex runtime.
   - `.claude/spec-first/state.json` or `.claude/commands/spec/update.md`
     indicates Claude runtime.
4. If both runtimes exist and the user did not specify one, report both host
   checks separately.

Before checking a branch, clear the startup reminder cooldown for the host being
checked so an explicit user-invoked update check is not hidden by a previous
reminder. Ignore command failures and empty output.

For Claude Code:

```bash
spec-first startup-reminder --claude --reset
```

For Codex:

```bash
spec-first startup-reminder --codex --reset
```

If this workflow is reporting both host checks, run both reset commands before
the branch-specific checks.

### 2. Claude Code branch

If `scripts/upstream-version.sh` printed `__SPEC_UPDATE_VERSION_FAILED__`: tell
the user the upstream version could not be fetched (gh may be unavailable or
rate-limited) and stop.

If `scripts/currently-loaded-version.sh` printed
`__SPEC_UPDATE_NOT_MARKETPLACE__`: this session loaded the skill from outside
the standard marketplace cache. Two cases collapse to the same handling: a
`claude --plugin-dir` local-development session, or a non-Claude-Code platform
that does not use the Claude plugin harness cache. Tell the user:

> "Skill is loaded from outside the marketplace cache at
> `~/.claude/plugins/cache/`. This is normal when using
> `claude --plugin-dir` for local development. No action for this session.
> Your marketplace install (if any) is unaffected — run the update workflow in
> a regular host session (no `--plugin-dir`) to check that cache."

Then stop.

### 3. Compare versions

**Up to date** — `{currently loaded} == {latest upstream}`:

> "spec-first **v{version}** is installed and up to date."

**Out of date** — `{currently loaded} != {latest upstream}`:

> "spec-first is on **v{currently loaded}** but **v{latest upstream}** is available.
>
> Update with:
> ```
> claude plugin update spec-first@{marketplace-name}
> ```
> Then restart Claude Code to apply."

The `claude plugin update` command ships with Claude Code itself and updates
installed plugins to their latest version; it replaces earlier manual cache
sweep / marketplace-refresh workarounds. The marketplace name is derived from
the skill path rather than hardcoded because this plugin is distributed under
multiple marketplace names (for example, `spec-first` for
public installs per the README, or other names for internal/team marketplaces).

After any successful plugin update, tell the user to restart Claude Code, then
run:

```bash
spec-first init
```

from the target project and choose Claude Code if generated runtime assets still look stale.

Also check Claude runtime asset health in the current project:

```bash
spec-first doctor --claude --json
```

If the command is unavailable, say that project runtime asset health could not
be verified and keep the plugin cache recommendation as the primary result. If
`doctor --claude --json` reports missing, stale, drifted, or otherwise unhealthy
Claude runtime assets, recommend:

```bash
spec-first init
```

Tell the user to choose Claude Code when prompted.

If both the plugin cache and Claude runtime assets are current, tell the user:

> "spec-first **v{version}** is installed and Claude runtime assets are up to
> date."

### 4. Codex branch

Gather these facts from the current project shell:

```bash
spec-first --version
```

Parse the current CLI version from the `Spec-First vX.Y.Z` line. If the command
is unavailable, tell the user `spec-first` is not installed or not on `PATH`,
then recommend:

```bash
npm install -g spec-first@latest
```

Next fetch the latest npm version:

```bash
npm view spec-first version --silent
```

If npm lookup fails because the network or registry is unavailable, continue
with the runtime asset check and state that the latest npm version could not be
verified.

Then check Codex runtime asset health in the current project:

```bash
spec-first doctor --codex --json
```

If the command reports that no spec-first Codex runtime is initialized, recommend
initializing it:

```bash
spec-first init
```

Tell the user to choose Codex when prompted.

If the CLI is older than npm latest, tell the user:

> "spec-first CLI is on **v{current}** but **v{latest}** is available.
>
> Update with:
> ```bash
> npm install -g spec-first@latest
> ```
> Then refresh Codex runtime assets in this project:
> ```bash
> spec-first init
> ```
> Choose Codex when prompted, then restart Codex so `$spec-*` entries reload."

If the CLI is current but `doctor --codex --json` reports stale or missing
runtime assets, tell the user:

> "spec-first CLI is current, but Codex runtime assets need refresh.
>
> Refresh with:
> ```bash
> spec-first init
> ```
> Choose Codex when prompted, then restart Codex so `$spec-*` entries reload."

If both the CLI and runtime assets are current, tell the user:

> "spec-first CLI **v{version}** is installed and Codex runtime assets are up to
> date."

## Output Rules

- State which host branch was checked: Claude Code, Codex, or both.
- Separate version status from runtime asset status.
- Give one concrete next command when action is needed.
- Do not recommend `claude plugin update` in Codex.
- Do not recommend `npm install -g spec-first@latest` as the Claude plugin cache
  update path.
