gaia-release

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 workspace 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 plugin, two distribution channels

Gaia ships as a single plugin named gaia (scripts/build-plugin.py has VALID_PLUGINS = ("gaia",)). The package root IS the plugin, and it is the same tree as the git repo root -- there is no dist/ bundle. That single tree reaches a workspace through two distribution channels, and a change can pass on one while breaking the other:

• plugin surface (git marketplace source) -- Claude Code consumes the git repository directly: .claude-plugin/marketplace.json advertises the gaia plugin with {"source": "github", "repo": "metraton/gaia"}, so /plugin marketplace add + /plugin install make CC clone the repo into its plugin cache. This is the channel that loads Gaia's agents, skills, and hooks in Claude Code. The git source was adopted (commit a43ef22) precisely because the prior source: npm entry loaded 0 skills on /plugin install -- a confirmed CC gap -- while the identical tree loads all 32 skills via a git/local source. CC loads hooks from the repo root's hooks/hooks.json (the standard plugin convention) -- it does not use settings.local.json for hooks, and the root .claude-plugin/plugin.json is metadata only (no inline hooks block). Hooks are declared in exactly ONE place because CC reads both a plugin.json inline block AND hooks/hooks.json; declaring them in both double-registered every hook and fired every event twice (fixed in a1b1245). Both .claude-plugin/plugin.json and hooks/hooks.json are generated from the manifest (prepack / generate:plugin-root) and tracked in git, so the cloned tree already carries them. Git sources support version pinning by ref/sha, and release:prepare's bumpMarketplace() does exactly that: for github/git sources it sets source.ref = v<version> atomically alongside plugin.version, so /plugin install clones the fixed, reproducible release tag instead of tracking moving default-branch HEAD (npm/local sources carry no ref and are left untouched).
• CLI / npm surface (npm package @jaguilar87/gaia) -- npm|pnpm install @jaguilar87/gaia (and gaia dev) install the npm package; this is what provides the gaia CLI and the workspace wiring. gaia install then wires the workspace: it symlinks .claude/{agents,tools,hooks,config,skills} (plus a CHANGELOG.md link) to the installed package and merges hook events into settings.local.json. The DB is bootstrapped lazily on first gaia CLI use (_ensure_db_bootstrapped in bin/gaia) -- there is no npm postinstall (removed so the install is non-invasive and works identically under npm and pnpm, which ignores lifecycle scripts by default). This surface reads hooks from the package root's generated hooks/hooks.json (via merge_local_hooks in _install_helpers.py), which is regenerated at pack time from the manifest.