@sabaiway/agent-workflow-kit 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.7.0 — Link-only backend auto-setup; bridges bundled in the tarball
+
+The optional execution-backend bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` →
+`agy`) can now be set up from the kit itself, via a new **opt-in, in-agent** mode —
+**`/agent-workflow-kit setup [backend]`** (`tools/setup-backends.mjs`). It owns only the two
+**deterministic, secret-free** steps and **guides** the rest (AD-011):
+
+- **Bridges are bundled in the kit's npm tarball** under `bridges/<name>/` — a **byte-identical
+  mirror** of the repo-root bridges, pinned by `test/bridges-mirror.test.mjs` (the same drift-guard
+  pattern as the methodology mirror). So `setup` places a bridge from local files, with **no network
+  fetch**. `init` (npx) bundles them but still **does not place** them — that stays the opt-in
+  `setup` job (preserving the honest `init` ≠ deploy claim).
+- **`setup` places/refreshes the bundled bridge skill**, but only into a dir that is **absent /
+  empty / proven-managed** (valid manifest, matching `name`+`kind`); a stub/foreign/invalid/
+  unsupported manifest, a marker fs-error, a non-empty unknown dir, or a symlinked dir → **STOP**,
+  never overwritten. Refresh re-runs on a managed dir so re-running `setup` delivers bundled fixes.
+- **It links the wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `PATH` (`~/.local/bin`,
+  override with `--bindir`) via **managed symlinks** — replacing only a symlink already pointing at
+  our source. It **preflights every target first**, so a conflict on one wrapper makes **zero**
+  changes; a non-symlink or a foreign symlink → STOP. Wrapper presence is judged **per-bindir**, not
+  PATH-wide. `--dry-run` prints the plan and changes nothing.
+- **The binary install + the interactive subscription login stay manual** — `setup` prints the exact
+  commands (the detector's axis-aware `guideFor`), never runs a subscription CLI, never commits. On
+  **Windows** it reports *unsupported — use WSL* and mutates nothing (the wrappers are POSIX `.sh`).
+- Internal: the symlink-traversal-safe copy/link primitives are now shared in `tools/fs-safe.mjs`
+  (the npx installer consumes them and gained an `isDirectRun` guard so importing it runs nothing).
+  The per-package publish workflow now gates the kit on its **whole** test suite, not just the
+  shipped enforcement scripts.
+
+No `docs/ai` structural change → the deployment-lineage head stays **`1.3.0`**; no migration.
+
 ## 1.6.0 — Methodology slot reconciliation; engine becomes the canonical methodology home
 
 The workflow methodology now has a **single canonical home** in `agent-workflow-engine`

package/README.md

@@ -216,6 +216,7 @@ command is printed).
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
+| `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -248,17 +249,20 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
    ├─ delegates ─▶ memory substrate   (healthy copy, else bundled fallback)
    ├─ injects   ─▶ workflow methodology  (engine = future supplier; stub)
    ├─ deploys   ─▶ AGENTS.md + docs/ai/ + Node scripts + pre-commit hook
-   └─ detects   ─▶ optional backends     (codex / agy — not by init)
+   ├─ detects   ─▶ optional backends   (codex / agy, read-only)
+   └─ sets up   ─▶ a bridge (opt-in)   (place skill + link wrappers)
 ```
 
 - **Delegates** substrate deployment to **`@sabaiway/agent-workflow-memory`** when a healthy
   standalone copy is present, else uses its **bundled fallback** — same `docs/ai/` either way.
 - **Injects** the bounded workflow methodology into the deployed `AGENTS.md`. Its *future* home is
   **`agent-workflow-engine`** — today an `available: false` stub, never one of the shipped backends.
-- **Detects** the optional `codex` / `agy` **bridges** — agent skills with a manual once-per-machine
-  setup (not npm, not installed by `init`); `/agent-workflow-kit backends` reports readiness
-  read-only. A bridge reads the deployed memory only if it wins that tool's context-file priority,
-  and the bridges call third-party services (so "no telemetry" covers family code, not those).
+- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
+  installed by `init`). `/agent-workflow-kit backends` reports readiness **read-only**;
+  `/agent-workflow-kit setup` does the **link-only** part (place the bundled bridge skill + link its
+  wrappers), while the binary install + the subscription login stay manual. A bridge reads the deployed
+  memory only if it wins that tool's context-file priority, and the bridges call third-party services
+  (so "no telemetry" covers family code, not those).
 
 > Full member-by-member map + the whole-family story: the
 > **[family front door](https://github.com/sabaiway/agent-workflow#readme)** — this page stays the
@@ -295,7 +299,10 @@ agent-workflow-kit/
 │   ├── delegation.mjs        ← detect substrate · delegate-or-fall-back
 │   ├── inject-methodology.mjs ← write the methodology slot
 │   ├── detect-backends.mjs    ← read-only backend detector
+│   ├── setup-backends.mjs     ← link-only backend setup
+│   ├── fs-safe.mjs            ← symlink-safe copy/link
 │   └── release-scan.mjs       ← attribution / release gate
+├── bridges/         ← bundled bridge skill mirrors (codex / antigravity)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.6.0'
+  version: '1.7.0'
 ---
 
 # agent-workflow-kit
@@ -83,6 +83,7 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 
 ### Mode: bootstrap
 
@@ -145,6 +146,26 @@ Read-only. Answers *"which optional execution-backends are set up vs missing, an
    - **"credentials present"** means the credential-marker **file** exists — it is **not** a live login check. The detector never runs `codex login status` / `agy` (that would spawn a paid, slow, networked subscription CLI).
    - The bridges' wrappers are **POSIX `.sh`** scripts. On Windows the detector still works, but the bridges themselves are **not promised to run** — say so rather than implying they will.
 
+### Mode: setup
+
+The **only writer** among the backend modes, and **opt-in / in-agent only** — it is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011). `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <path>] [--dry-run]`:
+
+- `<backend>` — `codex` | `agy` | `antigravity` | `codex-cli-bridge` | `antigravity-cli-bridge`; omit for **all**.
+- `--bindir <path>` — where to link the wrappers (default `~/.local/bin`).
+- `--dry-run` — print the per-backend plan and change **nothing** (run this first).
+- `--help`, `-h` — usage.
+
+For each backend it:
+1. **Places / refreshes the bundled bridge skill** (from the kit's `bridges/<name>/` mirror) into its canonical dir — but only when that dir is **absent / empty / proven-managed** (valid manifest, matching `name`+`kind`). A `stub` / `foreign` / `invalid` / `unsupported` dir, a marker fs-error, or a symlinked dir → **STOP**, never overwritten. Refresh re-runs on a proven-managed dir so re-running `setup` delivers bundled fixes.
+2. **Links its wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `--bindir` via **managed symlinks** — replacing only a symlink that already points at our source. A non-symlink or a foreign symlink → **STOP**; it **preflights every target first**, so a conflict on one wrapper makes **zero** changes. If `--bindir` is not on `PATH`, it prints the one-line `export PATH=…` to add — it never edits a shell rc.
+3. **Guides the manual, secret-bearing steps it will NOT automate** — the binary install (each bridge's `setup/README.md` §1) and the one-time interactive subscription login (`codex login` / `agy`) — printing the exact command for whichever axis is still missing (axis-aware: it can ask for both the CLI and the login at once).
+
+**Windows:** the wrappers are POSIX `.sh`; on `win32` it reports *unsupported — use WSL* and mutates nothing.
+
+**Exit codes:** `0` = done / already set up / only manual steps remain (guidance is never a failure); **non-zero** = a STOP (a dir/symlink it refuses to clobber), a bad argument, a missing bundle, or a native fs error (the underlying reason is preserved in the message).
+
 ---
 
 ## Gotchas
@@ -214,6 +235,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link primitives both `setup-backends` and the npx installer use), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -18,19 +18,22 @@
 //
 // Dependency-free, Node >= 18.
 
-import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { readFile, mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync } from 'node:fs';
-import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { copyTreeRefresh } from '../tools/fs-safe.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 // The deployable skill = everything except the npm wrapper (package.json, bin/).
 // capability.json (the family manifest) + tools/ (the family schema + validator the kit runs
-// as the memory detector) must land in the installed skill dir too.
+// as the memory detector) must land in the installed skill dir too. bridges/ carries the
+// byte-identical execution-backend skill mirrors (codex/antigravity) so `setup` can place a bridge
+// from the installed kit, with no network fetch (Plan B / AD-011).
 const PAYLOAD = [
   'SKILL.md',
   'README.md',
@@ -40,6 +43,7 @@ const PAYLOAD = [
   'launchers',
   'migrations',
   'tools',
+  'bridges',
 ];
 
 const tildify = (path) => path.replace(homedir(), '~');
@@ -64,42 +68,10 @@ const lstatNoFollow = (path) => {
   }
 };
 
-// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest` within
-// `root` (root / intermediate dir / leaf, including a dangling one), or to a dest outside `root`.
-const assertContainedRealPath = (root, dest) => {
-  const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
-    throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
-  }
-  if (lstatNoFollow(root)?.isSymbolicLink()) {
-    throw new Error(`[agent-workflow-kit] refusing to install into a symlinked target dir: ${root}`);
-  }
-  const walk = (acc, part) => {
-    const cur = join(acc, part);
-    if (lstatNoFollow(cur)?.isSymbolicLink()) {
-      throw new Error(`[agent-workflow-kit] refusing to write through a symlink at ${cur} (would escape ${root}).`);
-    }
-    return cur;
-  };
-  rel.split(sep).filter(Boolean).reduce(walk, root);
-};
-
-const copyRecursive = async (src, dest, root) => {
-  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
-  const stat = await lstat(src);
-  if (stat.isSymbolicLink()) {
-    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
-    const linkTarget = await readlink(src);
-    await symlink(linkTarget, dest);
-  } else if (stat.isDirectory()) {
-    await mkdir(dest, { recursive: true });
-    const entries = await readdir(src);
-    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
-  } else {
-    await mkdir(dirname(dest), { recursive: true });
-    await copyFile(src, dest);
-  }
-};
+// The symlink-traversal guard + the recursive refresh copy now live in tools/fs-safe.mjs (shared,
+// dependency-injectable, unit-tested in isolation). install.mjs consumes copyTreeRefresh, which guards
+// every dest via assertContainedRealPath internally. The local lstatNoFollow above stays for the
+// pre-flight check on the target root itself (a nicer error than letting the copy throw).
 
 const parseArgs = (argv) => {
   const dirFlag = argv.indexOf('--dir');
@@ -150,7 +122,15 @@ const main = async () => {
 
   // Critical payload must be present, or the install would silently ship a kit that can't run
   // its own detector (tools/) or family contract (capability.json). Fail loudly, don't filter away.
-  const REQUIRED = ['SKILL.md', 'capability.json', 'references', 'tools', 'migrations'];
+  const REQUIRED = [
+    'SKILL.md',
+    'capability.json',
+    'references',
+    'tools',
+    'migrations',
+    'bridges/codex-cli-bridge',
+    'bridges/antigravity-cli-bridge',
+  ];
   const missing = REQUIRED.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
   if (missing.length > 0) {
     console.error(`[agent-workflow-kit] package payload incomplete — missing: ${missing.join(', ')} (corrupt install?)`);
@@ -164,11 +144,9 @@ const main = async () => {
     process.exit(1);
   }
   await mkdir(target, { recursive: true });
-  await Promise.all(
-    PAYLOAD.filter((entry) => existsSync(resolve(PKG_ROOT, entry))).map((entry) =>
-      copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target),
-    ),
-  );
+  for (const entry of PAYLOAD.filter((e) => existsSync(resolve(PKG_ROOT, e)))) {
+    copyTreeRefresh(resolve(PKG_ROOT, entry), resolve(target, entry), target);
+  }
   console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
 
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
@@ -198,7 +176,12 @@ This command only installs/updates the kit itself (in ${tildify(target)}).
 To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`);
 };
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests
+// can import this module to assert it has no side effects. Same idiom as tools/detect-backends.mjs.
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/bin/install.test.mjs

@@ -5,9 +5,10 @@ import { mkdtemp, rm, mkdir, symlink, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
+const KIT_ROOT = dirname(dirname(INSTALLER));
 // --no-launchers so the test never wires Codex/Devin on the host.
 const runInstaller = (target) =>
   spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
@@ -64,3 +65,31 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
     assert.deepEqual(await readdir(real), []);
   });
 });
+
+describe('kit installer — module hygiene', () => {
+  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
+    // `node -e` has no argv[1], so isDirectRun is false → importing must not run main()
+    // (no FS writes, no exit). A child process keeps the assertion off the test runner's own state.
+    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
+    const res = spawnSync(
+      process.execPath,
+      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
+      { encoding: 'utf8' },
+    );
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /IMPORT_OK/);
+    assert.doesNotMatch(res.stdout, /installed v|updated the kit/);
+  });
+});
+
+describe('kit installer — published tarball bundles the bridges', () => {
+  it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
+    // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source
+    // tree, so a dropped `bridges/` entry in package.json fails here (not silently at install time).
+    const res = spawnSync('npm', ['pack', '--dry-run', '--json'], { cwd: KIT_ROOT, encoding: 'utf8' });
+    assert.equal(res.status, 0, res.stderr || res.error?.message);
+    const paths = JSON.parse(res.stdout)[0].files.map((f) => f.path);
+    assert.ok(paths.includes('bridges/codex-cli-bridge/SKILL.md'), 'codex bridge SKILL.md not packed');
+    assert.ok(paths.includes('bridges/antigravity-cli-bridge/bin/agy.sh'), 'antigravity agy.sh not packed');
+  });
+});

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 init`, then `/agent-workflow-memory` in the project — or
+  bootstrap the whole family via the **`agent-workflow-kit`** orchestrator
+  (`npx @sabaiway/agent-workflow-kit 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