---
name: gemini-orchestrator
description: >
  Gemini 4 and Antigravity-only orchestration workflow: keeps the main thread on
  a fast, steerable Neon driver as the human communications channel, checks
  whether the user's current model and thinking level match the task, routes
  multi-phase epics through right-sized sub-orchestrators (Carbon for deep
  architecture, Neon/Hydrogen for execution), enforces strict quota caps against
  runaway swarms/workflows, and uses artifact-first handoffs to eliminate token
  duplication and preserve prompt caching. Triggers: gemini-orchestrator, gemini
  orchestrate, orchestrate with gemini, sub-orchestrate, model check, thinking
  level check. Slash: /gemini-orchestrator.
---

# Gemini Orchestrator (`gemini-orchestrator`)

Antigravity / Gemini 4-only orchestration workflow. Keeps the human-facing main
thread thin, responsive, and interruptible while delegating deep reasoning and
parallel execution to right-sized Gemini 4 sub-orchestrators and workers—with
strict token and quota guardrails.

Loading or installing this skill does not by itself spawn workers. For ordinary
small tasks, stay inline (Tier 0). Escalate to subagents or swarm
sub-orchestrators only when task complexity, context size, or parallelism
justifies the startup cost.

---

## 1. Roles, Models & Thinking Levels (Active 3-Tier Lineup)

Route across the active 3-tier Gemini 4 lineup (**Hydrogen → Neon → Carbon**).
*(Do not route new work to `gemini-4-argon`; Neon supersedes Argon on speed,
cost, and steerability.)*

Use exact Gemini 4 model IDs via `swarm` only when Tier 2 sub-orchestration or
exact element pinning is justified (`invoke_subagent` exposes coarse
`inherit`/`flash`/`pro` buckets with lower overhead for Tier 1).

| Role | Default Model ID | Escalation / Alternative | Responsibility |
| :--- | :--- | :--- | :--- |
| **Communications Driver** *(Main Thread)* | `gemini-4-neon-low` | `gemini-4-neon-medium` *(if doing light inline edits)* | Talk with the human, catch voice-to-text/intent issues, manage pre-flight checks, steer/interrupt active workers, present concise summaries. |
| **Research & Architecture Sub-Orchestrator** | `gemini-4-carbon-high` | `gemini-4-neon-xhigh` *(faster back-and-forth, 25% lower token rate)* | Deep analysis, trade-off & threat modeling, greenfield system design. Writes full plan/findings to an artifact; returns only a short summary + decisions. |
| **Execution Sub-Orchestrator** | `gemini-4-neon-medium` | `gemini-4-neon-high` *(cross-layer debugging, auth/infra)* | Reads the plan artifact, splits work into bounded slices, manages Hydrogen workers, integrates and verifies. |
| **Execution Workers** *(Sharded / Scoped)* | `gemini-4-hydrogen-high` | `gemini-4-hydrogen-medium` *(routine edits/tests)* | Fast, quota-efficient implementation, unit/container tests, verification sweeps, and parallel file/module edits. |

---

## 2. Quota & Efficiency Guardrails (Hard Rules)

* **Thinking tokens cost 5x input** (`$7.50` Hydrogen / `$15.00` Neon / `$20.00` Carbon per 1M output tokens). Match thinking level to the turn—never leave `XHigh` or `Carbon High` on as a standing default.
* **Never run uncapped high-burn modes automatically:** Do **not** launch uncapped `swarm` groups, `/teamwork`, `/boost`, `/goal`, or multi-agent `run_workflow` fan-outs without explicit user sign-off and explicit bounds.
* **Concurrency cap:** Cap parallel workers at **≤ 3 concurrent workers** by default unless the user explicitly asks for wider fan-out.
* **Kill finished workers promptly:** As soon as a swarm worker's work is landed or its artifact is written, end it with `swarm(action="kill")` so stale workers and branched workspaces do not linger.
* **Preserve prompt caching (95% input discount) — Clean Switch Rule:**
  * KV caches are strictly tied to a model's weights. **Never advise switching models mid-thread** (e.g., planning on `Carbon` and then switching that same thread to `Neon` or `Hydrogen`), as that triggers a **guaranteed 100% hard cache miss** on the entire prior conversation.
  * **Turn 1 (cold/tiny thread):** Fine to offer a model + thinking-level picker switch before context builds up.
  * **Mid-thread (hot context):** Only recommend a **same-model thinking-level step** (e.g., `Neon High → Neon Medium`) when genuinely needed—never toggle every turn. For any **cross-model transition** (such as finishing a plan on `Carbon` and moving to execution on `Neon`/`Hydrogen`), **never tell the user to switch the current thread's model**. Instead:
    1. Write the complete plan/spec to an **artifact file on disk**.
    2. Either delegate execution to a **fresh worker/sub-orchestrator** on the target model **or** tell the user to **start a brand-new thread** on the target model and provide a **ready-to-paste starter prompt** pointing directly at that artifact file (so the new thread starts clean with zero planning-chatter bloat and no cold cache-miss penalty).

---

## 3. User-Only Pre-Flight Check (Main Thread Only)

Run this gate **only** when acting as the main human-facing thread—**never**
inside subagents or swarm workers.

1. **Model & Thinking-Level Fit Check:**
   * If your current model/thinking level is visible in context (via
     `<USER_SETTINGS_CHANGE>` or `swarm(action="status")`), compare it to the
     task:
     * **Over-provisioned** (e.g., `Carbon High` or `Neon XHigh` on a quick
       lookup, formatting tweak, or simple comms turn): briefly offer to drop to
       `Neon (Low)` or `Hydrogen (Low/Medium)` to preserve quota.
     * **Under-provisioned** (e.g., `Neon Low` or `Hydrogen` on a greenfield
       architecture, security threat model, or gnarly debugging session that
       won't be delegated): offer either to switch the picker to `Neon (High/XHigh)`
       / `Carbon (High)` **or** to keep the main thread on `Neon (Low)` and
       delegate the heavy pass to a `Carbon (High)` sub-orchestrator.
   * If your current model isn't visible on turn 1, only note a recommended
     model/thinking level in one line when the task is clearly heavy or clearly
     light. Never nag on routine turns, and never silently mutate global
     settings.
2. **Voice-to-Text & High-Cost Ambiguity Guard:**
   * Before launching an expensive `Carbon` sub-orchestrator or multi-worker
     run, scan the user's prompt for likely voice-to-text misspellings (domain
     names, repo names, identifiers) or ambiguous scope.
   * If anything looks garbled or could send a worker down the wrong path,
     pause and confirm in 1–2 lines before spawning.

---

## 4. Complexity Router (3 Tiers)

| Tier | Task Shape | Action |
| :--- | :--- | :--- |
| **Tier 0 — Inline** | Quick Q&A, single-file edit, short command, note/todo | Execute directly in the main thread. Do **not** spawn subagents or swarms (startup overhead > task cost). |
| **Tier 1 — Single Worker** | Self-contained research, test run, or single-module change | Spawn one right-sized worker (`invoke_subagent` `research` for read-only exploration, or a single `swarm(action="add")` worker only when exact Gemini 4 element pinning is needed). |
| **Tier 2 — Multi-Phase Epic / Story** | Multi-step feature, research → design → build, multi-repo audit | Run the capped **Comms Driver → Sub-Orchestrator → Workers** pipeline below (≤ 3 concurrent workers). |

### Tier 2 Pipeline (Multi-Phase Epic)
1. **Phase A — Deep Research / Plan (`Carbon High` or `Neon XHigh`):**
   * Spawn a single fresh sub-orchestrator via `swarm(action="add")` with an
     explicit brief and artifact output path.
   * Keep the main thread free while it works so the user can watch its
     thinking and interrupt at any time.
2. **Phase B — Human Checkpoint (Main Thread):**
   * Present the sub-orchestrator's 5–10 line summary, link the artifact file,
     and highlight only open decisions or trade-offs.
   * Wait for the user's steer/approval before starting execution.
3. **Phase C — Execute & Verify (`Neon Medium` → `Hydrogen Medium/High`):**
   * Spawn an execution sub-orchestrator (`gemini-4-neon-medium`) or up to **3**
     sharded `Hydrogen` workers (`tasks: [...]`, `workspace: "share"` for
     parallel authors editing code, `inherit` for readers/verifiers).
   * Pass **only the artifact path + bounded target files**, never the main
     thread's conversation history.
   * Place shared static context first in `brief` and the per-worker slice in
     `tasks` so workers share the leading prompt-cache prefix.
4. **Phase D — Land & Clean Up:**
   * Verify results/tests, merge or land any `share`/`branch` workspaces, then
     `swarm(action="kill")` finished workers immediately.

---

## 5. Artifact-First Handoff Contract (Zero Token Duplication)

Every sub-orchestrator brief **must** include this contract:

* **Write full output to disk:** Save complete plans, research findings, audit
  tables, or specs to `<artifactDir>/<slug>.md` (or `<artifactDir>/scratch/`
  for intermediate working files).
* **Return a compact payload to the main thread:** Reply with **only**:
  1. **Summary** (5–10 lines max)
  2. **Artifact path** (clickable link)
  3. **Decisions / Blockers** requiring human input
* **Never copy full transcripts downstream:** Downstream execution workers
  start fresh (`fork` omitted) and read the artifact file directly. Do not
  paste multi-thousand-token plans into chat messages or worker briefs when a
  file path suffices.

---

## 6. Live Steering & Interruption Protocol

* **Keep the main thread open:** After launching asynchronous workers, stop
  calling tools when waiting so the user can immediately type or dictate
  corrections without fighting a busy turn.
* **Relay deltas, don't restart:** When the user interrupts (e.g., catches a
  misinterpretation, fixes a voice-to-text typo, or adds a constraint), send a
  crisp delta message directly to the active sub-orchestrator/worker via
  `send_message` or a board `@mention` instead of tearing down and restarting
  from scratch.
* **Preserve observability:** Use clear, descriptive worker names (e.g.,
  `arch-plan`, `exec-api`, `verify-tests`), state the exact model pinned for
  each worker, and surface artifact links so the user can inspect thinking and
  progress in the Antigravity UI at any time.
