/gaia-release

name: gaia-release
description: Use when testing, validating, or publishing Gaia releases -- "install local", "pre-release", "dry-run", "release", RC, stable, plugin dry-run, "instala local", "hagamos un release", "probemos el pre-release", "publiquemos la versión estable"

Gaia Release

The norm for getting Gaia onto a machine and into the registry, organized as three layers of increasing confidence. The user expresses exactly one of three intentions -- **install local** (Layer 1, fast iteration), **pre-release** (Layer 2, the confidence gate), or **release** (Layer 3, the official publish) -- and each maps to a complete, automated sequence the orchestrator runs end-to-end. The user never recalls a sub-step and never runs a release script by hand: the script is a tool the flow invokes, not a command the human must remember. This is the lesson of the sagas that shipped broken -- a release failed because a version source was bumped one file at a time and a forgotten `pyproject.toml` drifted; another needed a force-push to reconcile a tag. Every one of those was a manual step a human was trusted to remember and didn't. The fix is to norm the sequence so the steps cannot be forgotten: they are the flow, not a checklist beside it.

**This skill orchestrates the sequence; it does not define what a healthy install looks like.** Every layer closes by installing into a target install folder and then validating it -- and "how you validate" lives in `gaia-verify`, which owns the wire-up checklist and the per-surface checks. When a layer says "verify," it means "run `gaia-verify` for the matching mode." Keep the two apart: release is the *when and in what order*; verify is the *did it come out right*.

The delivery model: one tree, three channels

Gaia ships as a **single** plugin named `gaia` (`scripts/build-plugin.py` has `VALID_PLUGINS = ("gaia",)`). **The npm package root IS the plugin root, and both are the git repository root** -- there is no `dist/` bundle. That one tree reaches an install folder through three channels, and a change can pass on one while breaking another:

                         one source tree (git repo root = package root)
                                         |
            +----------------------------+----------------------------+
            |                            |                            |
    git ref (branch/tag)        npm registry tarball          npm registry tarball
            |                            |                            |
   Claude Code plugin           package + gaia install         package + gaia install
   gaia@gaia-marketplace        --channel npm                  --channel opencode

• **Package (npm/pnpm + `gaia install`, for Claude Code).** The artifact is the `@jaguilar87/gaia` tarball on npm, published by `publish.yml`. `npm|pnpm install @jaguilar87/gaia` provides the `gaia` CLI (`node_modules/.bin/gaia`, invoked as `npx gaia` / `pnpm exec gaia`), and `gaia install` wires the folder it runs in, declaring no workspace (that is `gaia workspace declare <name> <path>`): it links `.claude/{agents,tools,hooks,config,skills,opencode}` (plus `CHANGELOG.md`) to the installed package and merges permissions and hook registrations into `.claude/settings.local.json` from the package's generated `hooks/hooks.json` (`merge_local_hooks` in `_install_helpers.py`). The DB is bootstrapped **lazily on first `gaia` CLI use** (`_ensure_db_bootstrapped` in `bin/gaia`) -- there is **no npm `postinstall`**, so the install behaves the same under npm and pnpm (pnpm ignores lifecycle scripts by default).
• **Claude Code plugin (`gaia@gaia-marketplace`).** The artifact is the git tree at a ref. `.claude-plugin/marketplace.json` names the marketplace `gaia-marketplace` and gives the `gaia` entry `"source": "."` with no `version`, so `/plugin marketplace add metraton/gaia#<branch-or-tag>` installs that ref's code at the version its `.claude-plugin/plugin.json` declares. Claude Code loads hooks from the root `hooks/hooks.json`, never from `settings.local.json`; the root `plugin.json` is **metadata only** (no inline `hooks` block -- declaring hooks in both places fired every event twice, fixed in `a1b1245`). Both files are **generated from the manifest** (`prepack` / `generate:plugin-root`) and tracked in git, so the fetched tree already carries them. The plugin's sessions merge the permission set and the `attribution` setting into `.claude/settings.local.json` (`setup_project_permissions` in `hooks/modules/core/plugin_setup.py`) and record those writes in `.claude/gaia-manifest.json`; it does not put `gaia` on the terminal's `PATH`.
• **OpenCode (on the package).** The artifact is the same npm tarball. `gaia install --channel opencode` writes `opencode.json` pointing at the packaged `opencode/plugin.ts` instead of touching `.claude/`.

| Channel | Artifact | How an rc reaches it | How a stable reaches it | Updating after a publish | |---------|----------|----------------------|-------------------------|--------------------------| | Package (Claude Code) | `@jaguilar87/gaia` tarball on npm | `gaia release publish x.y.z-rc.N` from the accumulating branch -> `publish.yml` publishes it under the `rc` dist-tag | `gaia release publish x.y.z` from `main` -> `publish.yml` publishes it under `latest` | `npm install @jaguilar87/gaia@latest` (or `@rc`, or `pnpm add ...`), then `npx gaia update` in the install folder, then restart Claude Code | | Claude Code plugin | the git tree at a ref, via `gaia-marketplace` (`source: "."`) | the same publish pushes tag `vx.y.z-rc.N`; `/plugin marketplace add metraton/gaia#vx.y.z-rc.N` installs it | the same publish pushes tag `vx.y.z` to `main` | `claude plugin marketplace update gaia-marketplace`, then `claude plugin update gaia@gaia-marketplace`, then restart. Auto-update is off for third-party marketplaces, and the plugin only updates when the version in the fetched `plugin.json` differs from the installed o