/setup-gaia

name: setup-gaia
description: Runs the single post-init onboarding. Detects the situation and runs only the owed phases; safe to re-run. --reconfigure re-asks the sandbox (an admin's answer also sets the team sandbox-recommendation, asked on its own only when that answer cannot), isolation-policy, squash-only-merge, and statusline decisions.
disable-model-invocation: true

Run this once after `/gaia-init`, and re-run it any time. `/setup-gaia` is the single onboarding command for a GAIA project. It detects the situation and runs only the phases this clone actually owes:

• **Per-machine work** every clone needs (tool installs, plugins, statusline bit, `.env`, the sandbox decision, and, for a developer with a global statusline, which statusline draws the left side).
• **GitHub repository provisioning** (create / adopt / manual, private by default), plus branch protection, the `GAIA-Audit` required-check registration, the `Vitest and Playwright` and `Shellcheck and bats` required checks (Phase 5), and squash-only merge settings when the runner is a repo admin.
• **Team settings** in `.gaia/project.json`: the git isolation policy and the sandbox recommendation. Both ship with a default (worktrees always, sandbox not recommended), so a plain run records the default and asks nothing; a repo admin changes either with `--reconfigure`, where the admin's own sandbox answer sets the recommendation.

It is safe for **any developer** to run at any time. A phase is owed when its own gate says so, or when the shipped setup feature list (`.gaia/setup-features.json`) holds its feature with no recorded decision; each decision it makes is recorded. A plain (no-flag) re-run on a provisioned project whose decisions are all recorded prints the already-provisioned line and mutates nothing: it never re-provisions the repo or changes branch protection. The one exception is a repo admin re-running it on a repo whose required checks still lack `GAIA-Audit` (or still carry the stale `code-review-audit` context): that run owes the registration and makes it. Pass `--reconfigure` to re-ask the sandbox decision (Phase 2), whose answer from a repo admin also sets the team sandbox recommendation, the team git isolation policy (Phase 3.5), the squash-only-merge offer (Phase 3.7), and the statusline left-side choice (Phase 4.6).

Contents: Pre-flight: Worktree check; Argument parse; Phase 0: Prerequisites (toolchain floors first); Phase 1: Detect situation; Phase 2: Per-machine setup; Phase 3: GitHub repository; Phase 3.5: Team settings; Phase 3.7: Squash-only merges; Phase 4.5: Label sync; Phase 4.6: Statusline left side; Phase 5: Owed setup features; Phase 5.5: Land setup decisions; Phase 6: Finalize; Idempotence / re-run safety; On failure: re-run.

This command reads these references, all under `.claude/skills/gaia/references/setup/`. Read one only when a "Read ... now" line sends you there, and then read the whole file:

• `setup-decisions.md`: Phase 1, every run, for the owed check and who may record project decisions.
• `sandbox.md`: Phase 2, when the sandbox gate says the decision is owed, or to record a settled decision.
• `per-machine.md`: Phase 0d, every run, for its `## Git hooks` check; Phase 2, when `completed_at` is null or a per-machine id is owed.
• `github-repo.md`: Phase 3, when no repo exists yet or its default branch is not pushed; Phase 3.5, for owed GitHub settings.
• `isolation-question.md`: Phase 3.5, on `--reconfigure` once both gates pass.
• `sandbox-recommendation.md`: Phase 3.5, on `--reconfigure` when Phase 2's sandbox answer did not set the recommendation.
• `squash-only.md`: Phase 3.7, once both gates say the question is owed.
• `statusline-left.md`: Phase 4.6, every invocation for the routing warning, and when a choice or record is owed.
• `standalone-features.md`: Phase 5, every run.
• `migrate-2-machine.md`: Phase 5, when `standalone-features.md` names it as owed.
• `required-ci-checks.md`: Phase 5, when `standalone-features.md` names it as owed.
• `auto-merge.md`: Phase 5, when `standalone-features.md` names it as owed.
• `land-decisions.md`: Phase 5.5, to land project decisions, and Phase 6, for the setup ping and the closing message.

Pre-flight: Worktree check

This command does per-machine and per-clone provisioning, writes `.gaia/local/setup-state.json`, and provisions the GitHub repository. If invoked from a linked worktree, reject hard: `gaia_refuse_if_worktree` (`.gaia/scripts/main-only-lib.sh`) asks the shared resolver which tree this is and refuses out loud, naming the main checkout (the clone's primary working directory, on any branch), when the answer is a worktree.

Detection (run this first, before anything else):

. .gaia/scripts/main-only-lib.sh
gaia_refuse_if_worktree "/setup-gaia" || exit 1

Once the refusal has passed, mark setup as running so the statusline stops telling the user to run the command that is already running. A refused worktree run never reaches this call:

mkdir -p .gaia/local && touch .gaia/local/setup-running

Argument parse

Parse `$ARGUMENTS` for the `--reconfigure` flag. Cache the boolean as `RECONFIGURE`. It re-opens these settled decisions and nothing else: the sandbox decision in Phase 2, whose answer from an admin also sets the sandbox recommendation, the isolation policy in Phase 3.5 (and the sandbox recommendation there, only when Phase 2's answer did not set it), the squash-only-merge offer in Phase 3.7, and the statusline left-side choice in Phase 4.6. When `/gaia-init` reads this file inline at its last step, `$ARGUMENTS` is not substituted: `RECONFIGURE` is false.

Phase 0: Prerequisites (every invocation, never skipped)

These record no setup-state step.

Toolchain floors

Run this first.

bash .gaia/scripts/toolchain-check.sh --scope user

Exit 0: say nothing and continue. Exit 1: read `.claude/skills/gaia/references/toolchain.md` now and run its `## Below a floor` with this comma