gaia: Skill for Claude Code

Contents: Pre-flight: Worktree check; Pre-flight: Branch check (run modes); Step 1: Read baseline version; Step 2: Resolve latest release; Step 3: Compare versions (main checkout, worktree run in place); Pre-flight: Pull check (reads references/pull-mode.md); Pre-flight: Decision log check; Pre-flight: Claim check (reads references/claim-flow.md); Step 3b: Refuse a 1.x baseline; Step 3c: Download and verify the bundles; Step 3d: Select migration notes; Step 4: Show the release notes and confirm (on Proceed: the update worktree, the worktree notice, the stop rule, the claim); Step 4b: Prune prior-run artifacts; Conflict flow (reads references/conflict-flow.md: dispatch, questions, decisions, follow-ups); Step 9b: Follow the after-merge notes; Step 9c: Carry new setup features (machine scope deferred to the post-merge cleanup); Step 9d: Record the update; Quality gate; Review point; Step 11 (orchestrator, after the review-point commit); Step 12: The leftover-file cleanup; Cost record (run end).

Pull the latest GAIA release into this project without clobbering customizations. Does a three-way comparison per file (adopter / baseline / latest) and respects explicit classes in .gaia/manifest.json:

• owned (GAIA-owned, not the adopter's): GAIA controls fully.
• shared: GAIA seeds, you customize.
• wiki-owned (adopter-editable; handled exactly like shared): GAIA-seeded wiki pages.
• adopter-owned (implicit): anything not in the manifest, plus sentinels like wiki/log.md, CHANGELOG.md, .gaia/VERSION, .gaia/manifest.json, .gaia/update-decisions.json. The merge walk never touches them; Step 9d rewrites .gaia/manifest.json and .gaia/VERSION once the merge is done, and the decision steps below write .gaia/update-decisions.json.

The first three take the same Step 7 rows. The class changes only two of them: which status a clean overwrite reports (owned → overwrite, the other two → merge), and what happens when the release newly owns a path the adopter already has (owned backs up and overwrites, the other two fall through to the ordinary rows). Step 7 is authoritative.

Backups land in .gaia-backup/<timestamp>/ in the acting tree, the update worktree. The merge report, its candidate files and the instruction snapshot land in the run directory, <main checkout path>/.gaia/local/cache/shared/update-gaia/run (gitignored, written only through Bash), which the run removes after Step 11.

Who runs what. This file runs the pre-flight through Step 4b, then dispatches the execution agent for Steps 6 to 9 (references/merge-execution.md), which merges and writes a JSON report but asks nothing. Every step after that runs here, in the orchestrator: the questions, applying the answers and recording the decisions, the follow-ups, Steps 9b to 9d, the quality gate, the review point with its single commit confirm, and Steps 11 and 12. Everything from Step 4b on runs inside the update worktree, so the main checkout's branch, files and node_modules stay as the user left them, whichever branch it holds. Every orchestrator step lives in this file or in references/conflict-flow.md, which the orchestrator reads in full before the dispatch, because the merge walk can overwrite this skill's own files partway through the run and the orchestrator keeps following the copy it already read. The draft PR's merge and cleanup run later, through the PR Merge Workflow.

Every command block below is one plain command with each value typed as a literal (written <NAME>), or a call to a tracked script by its literal path: inside a worktree session the runtime refuses a captured command substitution, a shell variable in a path, and a heredoc.

Pre-flight: Worktree check

This wrapper changes .gaia/VERSION and opens a PR, which belong to the main checkout (the clone's primary working directory, on any branch) or to this command's own update worktree, never to a SPEC, debt or feature worktree or to /update-deps's deps/ worktree. Invoked from any other linked worktree, it refuses hard with a message that surfaces the cached version state from main, so the user knows whether a GAIA update is even pending. The "update/" argument admits a worktree on an update/ branch, so a re-run inside this command's own update worktree continues there.