@sabaiway/agent-workflow-kit 1.6.0 → 1.8.0

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: antigravity-cli-bridge
+description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
+metadata:
+  version: '1.0.0'
+---
+
+# antigravity-cli-bridge
+
+Bridges the main agent to **Antigravity CLI** (`agy`), Google's successor to Gemini CLI. As of
+2026-06-18 the old Gemini CLI stopped serving Google AI Pro / Ultra / free tiers; terminal access to
+Google's models moved to `agy`. This is a **delegated-execution backend** beside Codex: the main
+agent stays the orchestrator — owning decisions, edits, verification, and user-facing claims — and
+hands `agy` a bounded, self-contained sub-task answered from the **subscription** quota (no
+pay-as-you-go billing). `agy` reaches Gemini, Claude, and GPT-OSS through one subscription, so it
+serves as both a cheap probe engine (Flash) and a strong second opinion (Pro / Claude Thinking).
+
+## Overview / when to use
+
+Use this skill when the user wants to:
+
+- Delegate a focused prompt to `agy` in headless mode.
+- Use Gemini, Claude, or GPT-OSS access available through a Google AI Pro/Ultra subscription.
+- Ask a second model to review a plan, summarise project context, or critique a diff supplied in the
+  prompt.
+- Install, authenticate, smoke-test, or troubleshoot `agy`, or understand its models/flags/quota.
+
+Do **not** use it to bundle secrets, bypass subscription auth, or hand uncontrolled repository
+mutations to `agy`.
+
+## Install
+
+Clean-machine setup is in [`setup/README.md`](setup/README.md). In short: the binary is **`agy`**
+(not `antigravity`), installs to `~/.local/bin/agy`, and must be on `PATH`; expose this skill's
+wrapper [`bin/agy.sh`](bin/agy.sh) on `PATH` as `agy-run`.
+
+## Auth — subscription only (invariant)
+
+`agy` authenticates with a cached **OAuth token** from a **Google AI Pro/Ultra** sign-in:
+
+```text
+~/.gemini/antigravity-cli/antigravity-oauth-token
+```
+
+Never read, print, copy, commit, or package that token — it is personal and is **never bundled** with
+this skill. The wrapper [`bin/agy.sh`](bin/agy.sh) **unsets every `*_API_KEY`** (`ANTIGRAVITY_API_KEY`,
+`GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_GENAI_API_KEY`) before invoking `agy`, so a stray key can
+never silently switch you to pay-as-you-go billing.
+
+**Caveat:** the subscription has a finite quota. Prefer the cheapest model that fits the task, and
+keep probes short (see *How the main agent drives agy*).
+
+## Models
+
+Pass the **exact display string** to `--model` (or set `AGY_MODEL`). The wrapper defaults to
+`Gemini 3.1 Pro (High)`. Run `agy models` for the live list — if it differs from this table, the live
+list wins.
+
+| Model string | Use it for |
+|---|---|
+| `Gemini 3.5 Flash (Low)` | cheapest; reachability checks, smoke tests, simple transforms |
+| `Gemini 3.5 Flash (Medium)` | cheap probes, context-reachability checks, quick summaries |
+| `Gemini 3.5 Flash (High)` | fast drafting / review when a little more effort helps |
+| `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
+| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Claude Sonnet 4.6 (Thinking)` | a Claude second opinion through the same subscription |
+| `Claude Opus 4.6 (Thinking)` | strongest Claude reasoning available via `agy` |
+| `GPT-OSS 120B (Medium)` | an open-weights cross-check / diversity pass |
+
+## Usage
+
+Drive `agy` only through the wrapper [`bin/agy.sh`](bin/agy.sh) (installed on `PATH` as `agy-run`):
+
+```bash
+agy-run "your prompt"                         # prompt as an argument
+echo "your prompt" | agy-run -                # prompt from stdin
+agy-run @path/to/prompt.md                    # prompt from a file
+AGY_MODEL="Claude Opus 4.6 (Thinking)" agy-run "..."   # pick a model
+AGY_TIMEOUT=10m agy-run "..."                 # agy's soft --print-timeout
+AGY_HARD_TIMEOUT=8m agy-run "..."             # hard wall-clock cap via timeout(1)
+agy-run "..." -- --add-dir . --dangerously-skip-permissions   # passthrough agy flags
+```
+
+`agy` is **headless-only** here (`-p`/`--print`) and there is **no JSON output mode** in v1.0.10 — you
+get plain text. If you need structure, ask for Markdown with explicit headings and validate it
+yourself. Wrapper inputs: first argument is the prompt (`text`, `-` for stdin, or `@file`);
+`AGY_MODEL` (default `Gemini 3.1 Pro (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
+`AGY_HARD_TIMEOUT` → hard `timeout(1)` wall-clock cap (default = `AGY_TIMEOUT`); extra `agy` flags
+after `--`. Full detail: [`references/models-and-flags.md`](references/models-and-flags.md).
+
+## Project context (how `agy` sees the repo)
+
+From its **current working directory** `agy` reads one root context file by priority, plus
+per-workspace skills:
+
+```text
+.antigravity.md > GEMINI.md > AGENTS.md
+.agents/skills/
+```
+
+So when you run `agy-run` from a project root, `agy` loads the **highest-priority context file that
+exists** — in most repos that is `AGENTS.md`, so its Hard Constraints are available — plus the
+project's `.agents/skills/`, with no wiring needed. **A `.antigravity.md` or `GEMINI.md`, if present,
+shadows `AGENTS.md`** (only the winning file is read), so put cross-cutting rules in whichever file
+wins, or include them in the prompt. Probe results in a real repo confirmed `agy` read the root
+`AGENTS.md` (returning the dialogue language + a Hard Constraint) and cited
+`.agents/skills/<skill>/SKILL.md` by path.
+
+**Honest scope:** these probes prove *reachability* — `agy` surfaces the cwd context file and
+per-workspace skills by directory scan. In testing it also **named a project-specific skill without
+being pointed at any file** (auto-discovery), but that is `agy`'s own mechanism, not a guaranteed
+Claude-style description-dispatch engine; don't promise more than the probe shows in a given repo.
+Re-runnable from a project root (use a cheap model):
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Read the cwd context file and state the dialogue language plus one Hard Constraint, in two lines."
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Without me pointing you at any file, name a project-specific skill under .agents/skills/ here and cite its path."
+```
+
+## How the main agent drives `agy` efficiently
+
+See [`references/driving-agy.md`](references/driving-agy.md) for the full playbook (delegation
+checklist, prompt templates, output handling). Essentials:
+
+- **Pick the cheapest model that fits.** Flash (Low/Medium) for reachability/probes; Pro (High) for
+  reasoning; `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)`
+  for a different engine's opinion (exact strings — see the Models table) — all on the same
+  subscription. Quota is finite, so don't reach for Pro by reflex.
+- **Hand `agy` a self-contained prompt.** It cannot see your conversation — embed the goal,
+  constraints, relevant excerpts, and the expected output shape; nothing more.
+- **Continue a thread** with `-- --continue` (most recent) or `-- --conversation <id>` (by id) instead
+  of re-sending context.
+- **Treat output as advisory** and verify before acting — check claims against local files, re-run
+  tests/linters yourself, reject advice that conflicts with user instructions or repo rules.
+- **Escalations are done by hand, not by `agy`.** The wrapper passes no `--add-dir`, no
+  `--dangerously-skip-permissions`, and no `--sandbox` — but that is a **policy boundary you state in
+  the prompt, not an enforced sandbox**. Keep repo edits, new dependencies/network installs, and git
+  writes (branch/add/commit/stash/reset/rewrite) with the orchestrator, and tell `agy` in the prompt
+  to return findings only. Add `-- --sandbox` when delegating anything that could trigger
+  terminal/tool work; opt into `-- --add-dir . --dangerously-skip-permissions` only for a flow that
+  genuinely needs writes, then review the diff afterwards.
+
+## Complementary skills (optional, standalone-first)
+
+`agy-run` works in any directory where `agy` is installed and authenticated. The two skills below are
+**not required** to use `agy` — surface them only when they actually help.
+
+- **`agent-workflow-memory`** (family **context provider**) — if the current project has **no**
+  `AGENTS.md` + `docs/ai/`, `agy` has no per-workspace context to read. The memory substrate creates
+  it. Soft-recommend it (only when the user wants the memory workflow):
+  `npx @sabaiway/agent-workflow-memory@latest init`, then `/agent-workflow-memory` in the project — or
+  bootstrap the whole family via the **`agent-workflow-kit`** orchestrator
+  (`npx @sabaiway/agent-workflow-kit@latest init`), which delegates substrate deployment to memory. Never a
+  prerequisite for using `agy`.
+- **`codex-cli-bridge`** (sibling backend, OpenAI Codex) — recommend **by actual presence**: if
+  `~/.claude/skills/codex-cli-bridge/` exists you have a **second delegated engine** (Codex for
+  sandboxed repo edits with gates; `agy` for subscription-quota Gemini/Claude reasoning). If it is
+  **not** installed, treat it as a **planned sibling** — don't assume it exists.
+
+## Known limitations
+
+- Subdirectory `CLAUDE.md` files are **not** auto-loaded by `agy` (only the cwd context file +
+  `.agents/skills/`). Put cross-cutting rules in the root context file, or include local rules in the
+  prompt when they matter.
+- **No JSON output** and **no `agy inspect`** in v1.0.10 — parse text; there is no machine-readable
+  introspection.
+- Model names must match the `agy models` display strings **exactly**.
+- **Quota is finite.** Heavy use of Pro/Claude models can exhaust the subscription; prefer Flash for
+  cheap work.
+- **A run can't hang forever.** The wrapper caps `agy` with `timeout(1)` (`AGY_HARD_TIMEOUT`,
+  default = `AGY_TIMEOUT`) because `agy`'s own `--print-timeout` is **not** a reliable wall-clock
+  kill (a run was seen surviving 32 min past a 10m `--print-timeout`). A heavy `--add-dir` agentic
+  prompt on the slowest model (`Gemini 3.1 Pro (High)`) can run unbounded — prefer a faster model or
+  a **self-contained prompt** (no `--add-dir`); an "exceeded the hard cap" error is the guard firing.
+- `agy` output is plain text and may be incomplete or out of date — treat it as advisory until the
+  main agent verifies it.

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Universal, neutral wrapper around Google's Antigravity CLI (`agy`).
+#
+# Antigravity CLI is the successor to Gemini CLI: as of 2026-06-18 the old
+# Gemini CLI stopped serving Google AI Pro / Ultra / free tiers, and access to
+# Google's models from the terminal moved to `agy`. This wrapper is the single
+# entry point so callers never have to remember the flag spelling.
+#
+# Auth: SUBSCRIPTION ONLY. We use the cached OAuth token at
+# ~/.gemini/antigravity-cli/antigravity-oauth-token (Google AI Pro) and the
+# quota that comes with it. To make that guarantee hard, the wrapper unsets any
+# API-key env var so a stray key can never silently switch us to paid
+# pay-as-you-go billing.
+#
+# This is a THIN, FLOW-AGNOSTIC wrapper on purpose: it just runs one headless
+# prompt and prints the text response. It does NOT encode any orchestration
+# policy (no plan contract, no auto-approve, no workspace edits) — that is left
+# to whatever flow we design later, which can opt in via passthrough flags.
+#
+# Models (pass the exact display string from `agy models`, or set AGY_MODEL):
+#   Gemini 3.5 Flash (Low|Medium|High), Gemini 3.1 Pro (Low|High),
+#   Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium)
+#
+# Usage (installed on PATH as `agy-run`):
+#   agy-run "your prompt"                    # prompt as an argument
+#   echo "your prompt" | agy-run -           # prompt from stdin
+#   agy-run @path/to/prompt.md               # prompt from a file
+#   AGY_MODEL="Claude Opus 4.6 (Thinking)" agy-run "..."   # pick a model
+#   AGY_TIMEOUT=10m agy-run "..."            # override print timeout (agy's soft bound)
+#   AGY_HARD_TIMEOUT=8m agy-run "..."        # override the hard wall-clock cap (timeout(1))
+#   agy-run "..." -- --add-dir . --dangerously-skip-permissions
+#                                            # passthrough agy flags (future flows)
+set -euo pipefail
+
+# 1. Make `agy` findable even when ~/.bashrc was not sourced.
+export PATH="$HOME/.local/bin:$PATH"
+
+# 2. Force the subscription path: never let an API key hijack billing. Unset EVERY *_API_KEY for the
+#    agy subprocess — the explicit Google/Antigravity ones first, then any other *_API_KEY that may
+#    have been added later (`compgen` is a bash builtin; the shebang guarantees bash).
+unset ANTIGRAVITY_API_KEY GEMINI_API_KEY GOOGLE_API_KEY GOOGLE_GENAI_API_KEY 2>/dev/null || true
+while IFS= read -r _api_key_var; do
+  unset "$_api_key_var" 2>/dev/null || true
+done < <(compgen -v 2>/dev/null | grep '_API_KEY$' || true)
+
+if ! command -v agy >/dev/null 2>&1; then
+  echo "error: 'agy' (Antigravity CLI) not found on PATH. Install it and run 'agy' once to sign in." >&2
+  exit 127
+fi
+
+# `-` (empty) => skip --model and let agy use settings.json; default to Pro.
+AGY_MODEL="${AGY_MODEL-Gemini 3.1 Pro (High)}"
+AGY_TIMEOUT="${AGY_TIMEOUT:-5m}"
+# Hard wall-clock cap (defaults to AGY_TIMEOUT). agy's own --print-timeout is NOT a reliable
+# wall-clock kill — a run was observed surviving 32 min past a 10m --print-timeout — so we also wrap
+# agy in timeout(1). A heavy `--add-dir` agentic prompt on the slowest model can otherwise run
+# unbounded, and once a caller backgrounds it nothing kills it. Raise only for a known-healthy run.
+AGY_HARD_TIMEOUT="${AGY_HARD_TIMEOUT:-$AGY_TIMEOUT}"
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <prompt | - | @file> [-- extra agy flags...]" >&2
+  exit 2
+fi
+
+prompt_src="$1"; shift
+
+# Split off any passthrough flags after a literal `--`. Extra args WITHOUT the `--` separator are a
+# mistake — they would be silently dropped, so fail loudly instead (no silent failures).
+passthrough=()
+if [[ $# -gt 0 ]]; then
+  if [[ "$1" == "--" ]]; then
+    shift
+    passthrough=("$@")
+  else
+    echo "error: unexpected argument '$1'. Pass extra agy flags after a literal '--':" >&2
+    echo "       $0 <prompt | - | @file> -- <agy flags...>" >&2
+    exit 2
+  fi
+fi
+
+if [[ "$prompt_src" == "-" ]]; then
+  prompt="$(cat)"
+elif [[ "${prompt_src:0:1}" == "@" ]]; then
+  file="${prompt_src:1}"
+  if [[ ! -f "$file" ]]; then
+    echo "error: prompt file '$file' not found" >&2
+    exit 2
+  fi
+  prompt="$(cat "$file")"
+else
+  prompt="$prompt_src"
+fi
+
+if [[ -z "${prompt// }" ]]; then
+  echo "error: empty prompt" >&2
+  exit 2
+fi
+
+model_flag=()
+if [[ -n "$AGY_MODEL" ]]; then
+  model_flag=(--model "$AGY_MODEL")
+fi
+
+agy_cmd=(agy "${model_flag[@]}" --print-timeout "$AGY_TIMEOUT" "${passthrough[@]}" -p "$prompt")
+
+# Hard wall-clock cap via timeout(1) (GNU `timeout` on Linux, `gtimeout` from coreutils on macOS).
+# This is the real guard — a backgrounded, hung agy survives its own --print-timeout otherwise.
+timeout_bin=""
+if command -v timeout >/dev/null 2>&1; then
+  timeout_bin="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then
+  timeout_bin="gtimeout"
+fi
+
+if [[ -z "$timeout_bin" ]]; then
+  echo "warning: no 'timeout'/'gtimeout' on PATH — running agy WITHOUT a hard wall-clock cap" >&2
+  echo "         (install coreutils to enable AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT)." >&2
+  exec "${agy_cmd[@]}"
+fi
+
+# --kill-after: if agy ignores the initial TERM, SIGKILL it 10s later. Capture rc (don't `exec`) so
+# we can turn a timeout into an explicit, actionable error instead of a silent non-zero.
+set +e
+"$timeout_bin" --kill-after=10s "$AGY_HARD_TIMEOUT" "${agy_cmd[@]}"
+rc=$?
+set -e
+if [[ $rc -eq 124 || $rc -eq 137 ]]; then
+  echo "error: agy exceeded the hard cap AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT and was terminated." >&2
+  echo "       This usually means a heavy '--add-dir' agentic run, or the slowest model looping." >&2
+  echo "       Retry with a faster model (e.g. AGY_MODEL='Gemini 3.5 Flash (High)') or a" >&2
+  echo "       self-contained prompt without --add-dir. Raise AGY_HARD_TIMEOUT only if the run is healthy." >&2
+fi
+exit $rc

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -0,0 +1,59 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WRAPPER = join(HERE, 'agy.sh');
+
+// Build a sandbox HOME whose ~/.local/bin holds a STUB `agy`. The wrapper prepends
+// "$HOME/.local/bin" to PATH, so it resolves our stub instead of the real binary — no network,
+// no real subscription CLI, fully hermetic.
+const makeSandbox = (stubBody) => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-wrapper-test-'));
+  const bin = join(home, '.local', 'bin');
+  mkdirSync(bin, { recursive: true });
+  const stub = join(bin, 'agy');
+  writeFileSync(stub, stubBody, { mode: 0o755 });
+  chmodSync(stub, 0o755);
+  return home;
+};
+
+const runWrapper = (home, env, prompt = 'hello') =>
+  spawnSync('bash', [WRAPPER, prompt], {
+    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, ...env },
+    encoding: 'utf8',
+    timeout: 20000,
+  });
+
+describe('agy.sh — hard wall-clock cap (timeout(1))', () => {
+  it('kills a hung agy at AGY_HARD_TIMEOUT and reports it (non-zero + actionable guidance)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 30\n');
+    const started = Date.now();
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    const elapsed = Date.now() - started;
+    rmSync(home, { recursive: true, force: true });
+    assert.ok(elapsed < 13000, `wrapper must return well under the kill-after window, took ${elapsed}ms`);
+    assert.notEqual(r.status, 0, 'a timed-out run must exit non-zero');
+    assert.match(r.stderr, /exceeded the hard cap/, 'must explain the hard-cap kill');
+  });
+
+  it('passes a fast agy run through unchanged (exit 0, stdout preserved)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "OK reply"\nexit 0\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `expected clean exit, got ${r.status}; stderr=${r.stderr}`);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('propagates a non-timeout agy failure code verbatim (no false hard-cap message)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "boom" >&2\nexit 3\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 3, 'a genuine agy failure code must pass through');
+    assert.doesNotMatch(r.stderr, /exceeded the hard cap/, 'must not mislabel a non-timeout failure');
+  });
+});

package/bridges/antigravity-cli-bridge/capability.json

@@ -0,0 +1,22 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "antigravity-cli-bridge",
+  "kind": "execution-backend",
+  "version": "1.0.0",
+  "provides": ["review", "probe"],
+  "roles": {
+    "review": { "cmd": "agy-run", "source": "bin/agy.sh", "template": "references/review-prompt.md", "output": "advisory" },
+    "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
+  },
+  "detect": {
+    "installed": {
+      "env": "ANTIGRAVITY_CLI_BRIDGE_DIR",
+      "default": "~/.claude/skills/antigravity-cli-bridge",
+      "file": "SKILL.md"
+    }
+  },
+  "cost": "subscription",
+  "quota": { "kind": "subscription", "finite": true },
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -0,0 +1,108 @@
+# How the main agent drives `agy`
+
+`agy` is a **delegated-execution backend**: the main agent stays the orchestrator and hands `agy` a
+bounded, self-contained sub-task. `agy` answers from the **subscription** quota, so the goal is
+maximum useful output per token of that quota. Treat its output as **advisory** — the main agent owns
+edits, verification, and final judgment.
+
+## Delegation checklist
+
+1. Pick the narrowest useful question.
+2. Choose the cheapest model that can answer it.
+3. Include only the relevant excerpts, paths, constraints, and the expected output shape.
+4. State permission boundaries in the prompt (no edits, no git writes).
+5. Run `agy-run` headlessly.
+6. Treat the response as advisory and verify before acting.
+
+## Model selection
+
+| Task | Model |
+|---|---|
+| Reachability / smoke / "is it wired?" | `Gemini 3.5 Flash (Low)` |
+| Cheap probes, summaries | `Gemini 3.5 Flash (Medium)` |
+| Quick review with a little more effort | `Gemini 3.5 Flash (High)` |
+| Reasoning, plan critique, careful drafting | `Gemini 3.1 Pro (High)` (wrapper default) |
+| Same reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
+| A different engine's opinion | `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)` |
+
+Don't reach for Pro by reflex — Flash answers most reachability/probe questions for a fraction of the
+quota.
+
+## Quota economy
+
+Subscription quota is finite. Prefer:
+
+- A short probe on Flash before a large Pro run.
+- One sharp question over broad "review everything" prompts.
+- Prompt files with trimmed excerpts instead of whole repositories.
+- `AGY_TIMEOUT=2m` for probes, longer timeouts only for deep reviews.
+- Reusing a conversation with `--continue` when the context is already loaded.
+
+## Continue vs. fresh
+
+```bash
+# Continue the most recent conversation (cheaper than re-sending context):
+agy-run "Given your previous review, list only the top three risks." -- --continue
+
+# Resume a specific conversation by id:
+agy-run "Continue from the prior architecture critique; focus on test gaps." -- --conversation <id>
+```
+
+Use conversation state only when it saves quota or preserves useful context. For auditable decisions,
+prefer self-contained prompts.
+
+## Escalation policy (edits, network, git)
+
+The wrapper passes no `--add-dir`, no `--dangerously-skip-permissions`, and no `--sandbox`. Treat this
+as a **policy boundary you enforce in the prompt, not an enforced sandbox** — so prompt `agy` as a
+read-only reviewer, and reach for `-- --sandbox` for anything that might trigger terminal/tool work:
+
+```text
+Do not edit files. Do not run git write commands. Do not branch, add, commit, stash, reset, or
+rewrite history. Return findings and suggested changes only.
+```
+
+- **Repo edits** stay with the orchestrator. If a flow truly needs `agy` to write files, opt in
+  explicitly — `agy-run "..." -- --add-dir . --dangerously-skip-permissions` — and review the diff.
+- **New dependencies / network installs** are done by hand, not by `agy`.
+- **Git writes** (branch/commit) are never delegated — the orchestrator commits after review.
+- Prefer `-- --sandbox` for any prompt that might trigger terminal work.
+
+## Project-context prompts
+
+Probe reachability from a project root (cheap model):
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Read the cwd context file and report the dialogue language plus one Hard Constraint."
+AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+  "Without using a file pointer, is there a project-specific planning skill in this repo? Name it and cite its path."
+```
+
+Plan-review prompt shape:
+
+```text
+You are reviewing the plan below from the current repository root.
+Use the root context file and per-workspace skills if they are reachable.
+Do not edit files. Do not run git write commands.
+Return: 1) blocking issues  2) non-blocking risks  3) missing verification  4) a concise recommendation.
+The implementation plan text follows in this same prompt.
+```
+
+Diff/code-review prompt shape (provide the diff as text):
+
+```text
+Review this diff against the stated constraints.
+Focus on bugs, behavioural regressions, missing tests, and violations of the project rules.
+Cite file paths and line hints from the diff where possible. Do not summarise unless there are no findings.
+The project constraints and diff text follow in this same prompt.
+```
+
+## Handling output
+
+`agy` returns plain text. Do not assume it is complete, current, or machine-valid. Before acting:
+
+- Check claims against local files or primary sources available to the main agent.
+- Re-run local tests and linters yourself.
+- Reject advice that conflicts with user instructions, repository rules, or security boundaries.
+- Summarise uncertainty clearly when reporting back to the user.

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -0,0 +1,93 @@
+# `agy` models & flags (reference)
+
+The source of truth is the live binary: `agy --version`, `agy --help`, `agy models`. The tables below
+were captured from **v1.0.10**; if the binary disagrees, the binary wins. The wrapper command is
+`agy-run`, backed by `bin/agy.sh`.
+
+## Headless behaviour
+
+Use `-p`, `--print`, or `--prompt` to run one non-interactive prompt and print the text response. The
+wrapper always uses headless `-p`. **There is no JSON output mode in v1.0.10** — ask for Markdown,
+bullets, tables, or fenced blocks when the caller needs structure, then validate the text yourself.
+
+## Wrapper contract
+
+```bash
+agy-run <prompt | - | @file> [-- extra agy flags...]
+```
+
+Inputs:
+
+- Prompt text: `agy-run "say OK"`.
+- Stdin: `echo "say OK" | agy-run -`.
+- Prompt file: `agy-run @prompt.md`.
+- Extra `agy` flags after `--`: `agy-run @prompt.md -- --add-dir . --continue`. Extra args **without**
+  the `--` separator are rejected with a usage error (they are never silently dropped).
+- A literal prompt that **begins with `@`** is read as a file path. Pass such prompts via stdin
+  instead: `printf '%s' '@handle, review this' | agy-run -`.
+
+Environment:
+
+| Var | Default | Effect |
+|---|---|---|
+| `AGY_MODEL` | `Gemini 3.1 Pro (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
+| `AGY_TIMEOUT` | `5m` | value passed to `--print-timeout` |
+
+Subscription invariant: the wrapper prepends `$HOME/.local/bin` to `PATH` and clears
+`ANTIGRAVITY_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENAI_API_KEY` before execution.
+Auth comes from the user's cached OAuth token, never from bundled credentials.
+
+## Models
+
+Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
+
+| Model string | Practical use |
+|---|---|
+| `Gemini 3.5 Flash (Low)` | lowest-cost smoke tests and simple rewrites |
+| `Gemini 3.5 Flash (Medium)` | cheap probes, fast summaries, context-reachability checks |
+| `Gemini 3.5 Flash (High)` | fast review when a little more reasoning effort is useful |
+| `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
+| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Claude Sonnet 4.6 (Thinking)` | cross-vendor reasoning comparison |
+| `Claude Opus 4.6 (Thinking)` | expensive deep critique when the user wants another high-end pass |
+| `GPT-OSS 120B (Medium)` | open-weights-style comparison / diversity pass |
+
+Examples:
+
+```bash
+AGY_MODEL="Gemini 3.5 Flash (Medium)" agy-run "Read AGENTS.md and report one Hard Constraint."
+AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.md
+```
+
+## Flags (from `agy --help`, v1.0.10)
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `-p`, `--print`, `--prompt` | run one headless prompt and print the text response | the wrapper uses `-p` |
+| `--print-timeout <dur>` | cap headless wait time | CLI default `5m0s`; wrapper default `5m` via `AGY_TIMEOUT` |
+| `--model <string>` | select a model | must match an `agy models` display string exactly |
+| `-i`, `--prompt-interactive` | run an initial prompt, then continue interactively | not used by the wrapper |
+| `-c`, `--continue` | continue the most recent conversation | pass after the wrapper's `--` |
+| `--conversation <id>` | resume a specific conversation by id | use only when the user provides/records the id |
+| `--add-dir <dir>` | add a directory to the workspace | repeatable; for explicit extra context |
+| `--dangerously-skip-permissions` | auto-approve all tool permissions | avoid by default; use only with explicit user approval |
+| `--sandbox` | run with terminal restrictions enabled | prefer when delegating a prompt that might trigger tool/terminal work |
+| `--log-file <path>` | override the CLI log-file path | keep logs secret-free and out of committed artifacts |
+
+## Subcommands (v1.0.10)
+
+`changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
+
+**Not available in v1.0.10:** any JSON output mode, and any `agy inspect`. Output is plain text.
+
+## Project-context flags
+
+`agy` reads context from its current working directory:
+
+```text
+.antigravity.md > GEMINI.md > AGENTS.md
+.agents/skills/
+```
+
+Use `--add-dir` for extra directories not already reachable from cwd. Subdirectory `CLAUDE.md` files
+are **not** auto-loaded — include those local rules manually in the prompt when they matter.

package/bridges/antigravity-cli-bridge/references/review-prompt.md

@@ -0,0 +1,51 @@
+# Review prompt template — `agy-run` (review role)
+
+The `review` role of `antigravity-cli-bridge` delegates a **read-only second opinion** to `agy`.
+`agy` cannot see the conversation and (in v1.0.10) has no JSON output, so the prompt must be
+**self-contained** and ask for **plain-Markdown findings only** — no repo edits, no git writes.
+Fill the `{{…}}` slots, pipe it to `agy-run`, then verify every finding locally before acting.
+
+```text
+You are a meticulous staff-level reviewer giving a SECOND OPINION. You are read-only:
+do not propose to edit files, run commands, or make git changes — return findings only.
+
+## What to review
+{{TARGET}}   # e.g. "the implementation plan below" or "the working-tree diff below"
+
+## Project rules
+Read the repo's root AGENTS.md (your cwd) and obey its Hard Constraints and conventions.
+If AGENTS.md declares a verification/gate set, judge the change against it; if it declares
+none, say so — do NOT invent checks.
+
+## Material
+{{CONTENT}}  # paste the plan text, or the unified diff, or the file excerpts under review
+
+## Focus (optional)
+{{FOCUS}}    # e.g. "correctness of the new reducer", "backward-compat of the stamp takeover"
+
+## Output — Markdown, this exact shape, nothing else
+### Verdict
+One line: SHIP / SHIP WITH NITS / REWORK, plus a one-sentence reason.
+### Blocking
+Numbered. Correctness bugs, contract violations, data loss, security. Cite file:line.
+Empty? write "none".
+### Non-blocking
+Numbered. Simplifications, reuse, naming, missing tests. Cite file:line.
+### Questions
+Anything ambiguous that changes your verdict if answered.
+```
+
+## Usage
+
+```bash
+# critique a plan
+AGY_MODEL="Gemini 3.1 Pro (High)" agy-run @/tmp/review-prompt.filled.md
+
+# critique the current diff (build the prompt with the diff pasted into {{CONTENT}})
+git diff | ...  # assemble the filled prompt, then:
+agy-run @/tmp/review-prompt.filled.md
+```
+
+Treat the result as **advisory** — `agy` output may be incomplete or out of date. The orchestrator
+re-runs the project's real gates and owns every accepted change. See
+[`driving-agy.md`](./driving-agy.md).