/gaia-verify

name: gaia-verify
description: Use when the user wants to verify a Gaia installation -- "probemos la instalación", "verifiquemos que Gaia funcione", "verify", "test installation", "gaia-verify"

Gaia Verify

Confirm that a Gaia installation actually works. Given an install folder and a delivery surface, run the checks that match that surface and report PASS/FAIL. This skill owns the definition of "a healthy install" -- the wire-up checklist and the per-surface checks. It is the check that `gaia-release` calls at the close of every layer; here it stands alone so the user can invoke it directly against whatever they just installed.

Gaia ships as one tree reaching an install folder through two surfaces -- npm/pnpm (the npm package `@jaguilar87/gaia`: symlinks + `settings.local.json`) and the Claude Code plugin (`source: "."` -- `.claude-plugin/marketplace.json` advertises the repository root as the plugin, so `/plugin marketplace add metraton/gaia#<ref>` + `/plugin install` load the code of that ref into CC's plugin cache and load hooks from the repo root's `hooks/hooks.json`; the root `.claude-plugin/plugin.json` is metadata-only, and there is no `dist/` bundle). A change can pass on one surface and break on the other, so the mode you pick must match the surface you are validating.

Decision tree

"probemos" / "verify" / "test installation"
├─ Already installed in an install folder (npm/pnpm), edited source? -> live
├─ Proving the npm tarball before a release?                        -> npm-sandbox
├─ Proving the npm tarball as a plugin before a release?           -> plugin
└─ Confirming a version already published to npm?                   -> registry

If the user does not name a mode, ask: "Which mode -- live, npm-sandbox, plugin, or registry?"

Mode: live

Validates an install folder that is already wired (npm/pnpm surface). No build, no temp dir, no cleanup.

Run against the install folder: `gaia doctor` then `gaia status`, then the **wire-up checklist** below. This is the mode `gaia-release` Layer 1 and Layer 3 call after installing into the target (via `gaia dev --channel <channel> --workspace <TARGET>`, the one-command install).

Mode: npm-sandbox

Validates the npm surface of exactly what a registry publish would ship -- pack, install into a clean sandbox, run the harness, clean up. No accumulated install-folder state.

Primary path: `gaia release check` runs this gate (as gate 2, `gaia:verify-install:local`) inside the full Layer 2 sequence. To run just this surface in isolation, `npm run gaia:verify-install:local` (packs, installs into `/tmp/gaia-sandbox-<ts>-<pid>/`, runs the harness, cleans up) is what `gaia release check` wraps -- manual step-by-step in `reference.md`. This is the mode `gaia-release` Layer 2 gate 2 calls.

Mode: plugin

Validates the Claude Code plugin surface -- the exact npm tarball, extracted, with its root mounted as a plugin. This is the only mode that exercises the root `plugin.json` (metadata-only) / `hooks/hooks.json`, the packaged agents/skills, and `bin/gaia` on PATH; the npm surface never touches any of it.

Primary path: `gaia release check` runs this gate (as gate 3, `gaia:plugin-dryrun`) inside the full Layer 2 sequence, and SKIPs it gracefully when the `claude` binary is absent. To run just this surface, `npm run gaia:plugin-dryrun` (`bin/plugin-dryrun.sh`, what `gaia release check` wraps) packs the tarball, extracts it to a throwaway temp dir, and runs a headless, offline gate -- filesystem asserts (root `plugin.json` present with NO inline `hooks` block, `hooks/hooks.json`, `bin/gaia`, `agents/`, `skills/`, and NO `dist/`) + `claude plugin validate`. It touches no real install folder and spawns no session; the temps are trap-cleaned. Add `gaia release check --functional` (or `npm run gaia:plugin-dryrun -- --functional`) for an optional live functional probe that starts the host on the extracted plugin (needs Claude auth/tokens). This is the mode `gaia-release` Layer 2 gate 3 calls. Do NOT publish or install to the real registry to run this.

Mode: registry

Validates a version already published to npm -- fresh temp dir, install from the registry tag, verify, clean up.

Core flow: `npm run gaia:verify-install:rc` (the `@rc` tag) or `npm run gaia:verify-install:latest` (the `@latest` / stable tag). Step-by-step in `reference.md`. This is the mode `gaia-release` Layer 3 step (h) calls after the pipeline publishes.

Wire-up checklist (live / after any install)

After wiring an install folder, these checks catch what `gaia doctor` cannot reach when the wire-up is so broken that doctor cannot resolve the install folder at all. If any check fails, jump to `gaia-release/reference.md` -> "Diagnostic guide".

Checks 1-3 are the npm channel's. A plugin-only install folder has none of them: its `.claude/` holds only the `hooks` link and `settings.local.json`, and doctor judges `Symlinks`, `Identity`, `Agent routing`, `Workspace initialized` and `Plugin registered` against the plugin install itself (`CLAUDE_PLUGIN_ROOT`, else the install recorded in `~/.claude/plugins/installed_plugins.json`) -- `_plugin_tree` in `bin/cli/doctor.py`.

1. `ls -la <install-folder>/.claude/` -- **6 directory symlinks** (`agents`, `tools`, `hooks`, `config`, `skills`, `opencode`) + a `CHANGELOG.md` link, plus `logs/`, `approvals/`, `plugin-registry.json`, `settings.local.json`. (`_SYMLINK_NAMES` + `_SYMLINK_FILES` in `bin/cli/_install_helpers.py`.) 2. `cat <install-folder>/.claude/plugin-registry.json` -- `installed[].name` at the expected version. **Decided:** the canonical registry identity is `gaia` (`_read_plugin_name` in `_install_helpers.py` strips the npm scope from `@jaguilar87/gaia` and falls back to `"gaia"`). A fresh install always writes `gaia`; fail the check if the name is anything other than `gaia`. 3. `cat <install-folder>/.claude/settings.local.json | jq '.hooks | keys'` -- hook events registered (npm surface only; the plugi