@aibridge/cli 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 
   # aibridge
 
-  **Let your coding agent drive the other AIs on your machine.** Cross-provider agent-to-agent delegation — plan, implement, review, red-team, and generate images across Grok, Gemini, Codex & Claude through the CLIs you already have. No API keys.
+  **Let your coding agent use the other AI CLIs on your machine.** Plan, implement, review, red-team, and generate images with Grok, Gemini, Codex, and Claude. No API keys.
 
   [![skills.sh](https://skills.sh/b/ycmjason/aibridge)](https://skills.sh/ycmjason/aibridge)
   [![npm](https://img.shields.io/npm/v/%40aibridge%2Fcli)](https://www.npmjs.com/package/@aibridge/cli)
@@ -15,38 +15,42 @@
 
 ---
 
-Your agent is one model, from one provider. Your machine probably has several more sitting behind CLIs you already use — `grok`, `agy` (Antigravity), `codex`, `claude`. **aibridge** turns them into seats your agent can drive: a planner that studies your repo, an implementer that edits it and runs your real tests, a reviewer from a *different* model family that cross-checks the diff against the plan, concurrent one-shot delegates — and capabilities your agent's own provider may not offer at all, like real image generation (Codex, Antigravity, or Grok seats).
+Your coding agent uses one model. Your machine may already have others available
+through `grok`, `agy` (Antigravity), `codex`, or `claude`. **aibridge** lets your
+agent use those models as planners, implementers, reviewers, one-shot delegates,
+and image generators. Each model runs through its existing CLI login.
 
 ## Install
 
-One step — install the skill into your agent(s):
+Install the skill into your agent:
 
 ```bash
 npx skills add ycmjason/aibridge
 ```
 
-That's it. The skill runs the CLI on demand via `npx -y @aibridge/cli` — nothing else to install. Ask your agent to "use aibridge", or try it yourself:
+The skill runs the CLI on demand with `npx -y @aibridge/cli`. Ask your agent to
+"use aibridge", or run a command directly:
 
 ```bash
 npx -y @aibridge/cli subagent --model xai-grok/grok-4.6 "summarize the architecture of this repo"
 ```
 
-<sup>Want the `aibridge` command on your PATH for manual use? `npm i -g @aibridge/cli` (optional).</sup>
+<sup>Optional: install `aibridge` on your PATH with `npm i -g @aibridge/cli`.</sup>
 
 ## Commands
 
 | Command | Use when |
 |---|---|
-| `aibridge plan --model xai-grok/grok-4.6 --out plan.md "<task>"` | You want a delegate model to study the repo and expand a task into a detailed, reviewable **plan file** before any code is written |
-| `aibridge implement --model google-antigravity/gemini-3.7-flash <plan.md>` | You have an approved plan file and want it executed in place — with your project's **real typecheck and tests** run until green |
-| `aibridge review --model xai-grok/grok-4.6 --out review.md [--plan <plan.md>]` | You want a **different model** to pressure-test the working-tree diff against the plan contract (over-reach is a finding) — or to review the plan itself before implementing |
-| `aibridge subagent --model xai-grok/grok-4.6 "<task>"` | A self-contained task deserves a concurrent delegate, a cross-model second opinion, or a red-team pass |
-| `aibridge image-gen --model openai-codex/gpt-5.6-sol --out out.png "<prompt>"` | You need a real raster image — on a Codex, Antigravity, or Grok seat, with render verification |
-| `aibridge models [--json]` | You need the exact facts for every registered model seat (accepted efforts, image format, pinned model ID) |
-| `aibridge quota` | Two-second check of every backend's remaining quota before you pipeline work |
-| `aibridge runs` | Inspect or watch past delegation runs (`~/.aibridge/runs`) |
+| `aibridge plan --model xai-grok/grok-4.6 --out plan.md "<task>"` | Study the repo and write a detailed plan file |
+| `aibridge implement --model google-antigravity/gemini-3.7-flash <plan.md>` | Execute an approved plan and run the project's checks |
+| `aibridge review --model xai-grok/grok-4.6 --out review.md [--plan <plan.md>] [--base <ref>]` | Review a diff or, on a clean tree, a plan |
+| `aibridge subagent --model xai-grok/grok-4.6 "<task>"` | Delegate a self-contained task or request a second opinion |
+| `aibridge image-gen --model openai-codex/gpt-5.6-sol --out out.png "<prompt>"` | Generate and verify a raster image |
+| `aibridge models [--json]` | List registered models and their capabilities |
+| `aibridge quota` | Show quota remaining for every backend |
+| `aibridge runs` | Inspect or watch run logs in `~/.aibridge/runs` |
 
-The three verbs compose into an orchestrator-driven loop your agent stays in charge of:
+Use `plan`, `implement`, and `review` as one controlled workflow:
 
 ```
 aibridge plan --model xai-grok/grok-4.6 --out plan.md "add rate limiting to the API"   # delegate writes plan.md
@@ -55,21 +59,26 @@ aibridge implement --model google-antigravity/gemini-3.7-flash plan.md
 aibridge review --model xai-grok/grok-4.6 --out review.md --plan plan.md               # a third seat cross-checks the diff
 ```
 
-Plan files — not their contents — travel between stages, so the loop is nearly free on your agent's context.
+Only the plan path passes between stages, which keeps the plan out of the
+orchestrator's conversation context.
 
 ## How it works
 
-- **The skill carries judgment; the CLI owns execution.** The skill teaches your agent prompt-craft, seat selection, and when to gate; the CLI deterministically drives the backing CLIs, captures their output, verifies results (a "generated image" under 100 KB is a code-drawn fake, an empty answer is a quota death), and logs every run.
-- **Seats stay cross-model by default.** Grok plans and reviews, Gemini implements — a model never reviews its own diff, and independent eyes catch what shared blind spots miss.
-- **No API keys.** Delegation runs on the backing CLIs' existing logins, each spending its own quota. (The skill treats a backend that shares your agent's own quota pool as a last resort.)
-- **Models are canonical slugs**: `<vendor>-<cli>/<model>[-<effort>]` — e.g. `xai-grok/grok-4.6`, `google-antigravity/gemini-3.7-flash`, `openai-codex/gpt-5.6-sol-high`, `anthropic-claude/opus-5`. No aliases — not short ones, and not moving vendor aliases like `opus`: every seat pins an exact model version. `aibridge <command> --help` lists every seat.
+- **The skill decides; the CLI executes.** The skill covers routing and prompt
+  design. The CLI starts the backend, captures output, validates known failure
+  modes, and logs the run.
+- **Review stays cross-model.** The recommended workflow uses Grok to plan and
+  review, and Gemini to implement.
+- **Existing logins, no API keys.** Each backend uses its CLI login and quota.
+- **Every model has a canonical slug:**
+  `<vendor>-<cli>/<model>[-<effort>]`, such as `xai-grok/grok-4.6` or
+  `openai-codex/gpt-5.6-sol-high`. There are no aliases. Run
+  `aibridge <command> --help` for the current list.
 
 ## Tell your agent when to reach for it
 
-aibridge doesn't decide when to delegate — your agent does, and left alone it will
-mostly keep the work for itself. Put the routing rule in whatever instructions file
-your agent already reads at the start of every session (`AGENTS.md`, `CLAUDE.md`,
-`.cursorrules`, …). Something like:
+aibridge does not decide when to delegate. Put a routing rule in the instructions
+file your agent reads (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and so on):
 
 ```markdown
 ## Delegation gate — decide before you implement
@@ -91,21 +100,32 @@ Delegated work is yours to verify: re-run the real gates before trusting a diff.
 Prefer a reviewer from a different model family than whoever implemented.
 ```
 
-Tune the seats and thresholds to your own quotas. The value is that the decision is
-explicit and made *before* the work starts, rather than rationalised afterwards.
+Adjust the models and thresholds for your quotas. Make the routing decision before
+implementation starts.
 
 ## Requirements
 
 - **Node ≥ 24.11**
-- The backing CLIs you want to use, on `PATH` and authed: [`grok`](https://github.com/superagent-ai/grok-cli), `agy` (Antigravity), [`codex`](https://github.com/openai/codex), [`claude`](https://claude.com/claude-code) — any subset works; commands fail fast with install hints for missing ones.
+- At least one authenticated backend CLI on `PATH`:
+  [`grok`](https://github.com/superagent-ai/grok-cli), `agy` (Antigravity),
+  [`codex`](https://github.com/openai/codex), or
+  [`claude`](https://claude.com/claude-code). Missing CLIs produce install hints.
 
 ## Packages
 
-Everything is published under the [`@aibridge`](https://www.npmjs.com/org/aibridge) scope: [`@aibridge/cli`](https://www.npmjs.com/package/@aibridge/cli) (the command), `@aibridge/proc` (spawn/capture), and one driver per backing CLI — `@aibridge/driver-agy`, `@aibridge/driver-grok`, `@aibridge/driver-codex`, `@aibridge/driver-claude` — reusable if you want to drive a single CLI from your own code.
+Packages use the [`@aibridge`](https://www.npmjs.com/org/aibridge) scope:
+[`@aibridge/cli`](https://www.npmjs.com/package/@aibridge/cli),
+`@aibridge/proc`, and one reusable driver for each backend:
+`driver-agy`, `driver-grok`, `driver-codex`, and `driver-claude`.
 
 ## Security
 
-aibridge executes real delegation — that's the product, and security scanners rightly notice: backing CLIs read/write files and run shell in tools mode, **at the same trust level as the agent you already run**. Nothing gains more access than you granted your agent and those CLIs when you installed them. Task content goes to the delegate's provider (use `--no-tools` for untrusted input — reasoning only, no file/shell access). All packages publish from this public repo via OIDC with [SLSA provenance](https://www.npmjs.com/package/@aibridge/cli), with no install-time scripts.
+In tools mode, delegates can read files, write files, and run shell commands with
+the same access as the invoking agent. Task content is sent to the selected
+provider. Use `--no-tools` for untrusted input. Packages are published from this
+public repository through OIDC with
+[SLSA provenance](https://www.npmjs.com/package/@aibridge/cli) and no install-time
+scripts.
 
 ## Contributing & development
 

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as buildContext } from "./context-DJtEcg6f.mjs";
+import { r as runCli, t as buildContext } from "./context-DeJmEXLe.mjs";
 //#region src/cli.ts
 await runCli(buildContext(process), process.argv.slice(2));
 //#endregion

package/dist/{context-DJtEcg6f.mjs → context-DeJmEXLe.mjs}

@@ -312,6 +312,123 @@ function getDriver(backend) {
 	return driver;
 }
 //#endregion
+//#region src/quotaPreflight.ts
+function evaluateAgyPreflight(snapshot, backendModel) {
+	const quota = findModelQuota(snapshot, backendModel);
+	if (!quota) return {
+		ok: true,
+		warning: `model "${backendModel}" not in quota snapshot; proceeding`
+	};
+	if (quota.exhausted) {
+		let resetAt = quota.resetTime;
+		if (!resetAt) {
+			for (const group of snapshot.groups) if (group.displayName.includes("Gemini")) {
+				for (const bucket of group.buckets) if (bucket.resetTime) {
+					if (!resetAt || new Date(bucket.resetTime).getTime() < new Date(resetAt).getTime()) resetAt = bucket.resetTime;
+				}
+			}
+		}
+		return {
+			ok: false,
+			kind: "quota",
+			message: `agy model "${backendModel}" is quota-exhausted`,
+			resetAt
+		};
+	}
+	return { ok: true };
+}
+function evaluateCodexPreflight(snapshot) {
+	if (snapshot.limitReached) return {
+		ok: false,
+		kind: "quota",
+		message: "codex quota limit reached",
+		resetAt: snapshot.windows.find((w) => w.resetAt)?.resetAt
+	};
+	const exhaustedWindow = snapshot.windows.find((w) => w.usedPercent >= 100);
+	if (exhaustedWindow) return {
+		ok: false,
+		kind: "quota",
+		message: "codex quota limit reached",
+		resetAt: exhaustedWindow.resetAt
+	};
+	return { ok: true };
+}
+function evaluateGrokPreflight(snapshot) {
+	if (snapshot.usedPercent !== void 0 && snapshot.usedPercent >= 100) return {
+		ok: false,
+		kind: "quota",
+		message: "grok credit quota exhausted",
+		resetAt: snapshot.periodEnd
+	};
+	return { ok: true };
+}
+async function preflightModel(resolved) {
+	if (resolved.spec.backend === "codex") return preflightCodex();
+	if (resolved.spec.backend === "grok") return preflightGrok();
+	if (resolved.spec.backend !== "agy") return { ok: true };
+	try {
+		return evaluateAgyPreflight(await fetchAgyQuota(), backendModelId(resolved));
+	} catch (err) {
+		if (isAuthExpired(err)) return {
+			ok: false,
+			kind: "auth",
+			message: err.message,
+			resetAt: void 0
+		};
+		return {
+			ok: true,
+			warning: `quota preflight failed (${err.message}); proceeding`
+		};
+	}
+}
+async function preflightCodex() {
+	try {
+		return evaluateCodexPreflight(await fetchCodexQuota());
+	} catch (err) {
+		if (isAuthExpired(err)) return {
+			ok: false,
+			kind: "auth",
+			message: err.message,
+			resetAt: void 0
+		};
+		return {
+			ok: true,
+			warning: `quota preflight failed (${err.message}); proceeding`
+		};
+	}
+}
+async function preflightGrok() {
+	try {
+		return evaluateGrokPreflight(await fetchGrokQuota());
+	} catch (err) {
+		if (isAuthExpired(err)) return {
+			ok: false,
+			kind: "auth",
+			message: err.message,
+			resetAt: void 0
+		};
+		return {
+			ok: true,
+			warning: `quota preflight failed (${err.message}); proceeding`
+		};
+	}
+}
+function formatReset$1(resetTime) {
+	if (!resetTime) return "-";
+	const ms = new Date(resetTime).getTime() - Date.now();
+	if (Number.isNaN(ms)) return resetTime;
+	if (ms <= 0) return "now";
+	const mins = Math.round(ms / 6e4);
+	const rel = mins < 60 ? `${mins}m` : `${Math.floor(mins / 60)}h${mins % 60}m`;
+	return `${new Date(resetTime).toLocaleTimeString()} (in ${rel})`;
+}
+function renderPreflightRefusal(cmd, verdict) {
+	if (verdict.kind === "auth") return `aibridge ${cmd}: refusing — ${verdict.message}. Running with --no-preflight would only fail unauthenticated later. Or use a different --model.`;
+	const resetClause = verdict.resetAt ? ` Resets ${formatReset$1(verdict.resetAt)}.` : "";
+	const fallback = cmd === "image-gen" ? "Use --no-preflight to override, or another image seat (--model openai-codex/gpt-5.6-sol | google-antigravity/gemini-3.7-flash | xai-grok/grok-4.6)." : "Use --no-preflight to override, or a claude-backend fallback (subagent --model sonnet|opus — bills the Claude subscription).";
+	return `aibridge ${cmd}: refusing — ${verdict.message}.${resetClause} ${fallback}`;
+}
+//#endregion
 //#region src/transparency.ts
 const CHROMA_CLAUSE = "The entire background must be a perfectly flat solid #00ff00 chroma-key green. The background must be one uniform colour with no shadows, gradients, texture, reflections, or lighting variation. Keep the subject fully separated from the background with crisp edges. Do not use #00ff00 or any similar green anywhere on the subject. No cast shadow, no contact shadow, no reflection.";
 const NATIVE_ALPHA_CLAUSE = "Render the subject on a fully transparent background — PNG with a real alpha channel, no backdrop, no canvas colour, no cast shadow.";
@@ -419,6 +536,15 @@ async function imageGen$1(flags, prompt) {
 	}
 	const driver = getDriver(model.spec.backend);
 	if (!driver.generateImage) return fail(formatImageGenModelError(inputSlug, model));
+	if (flags.preflight) {
+		const verdict = await preflightModel(model);
+		if (!verdict.ok) {
+			this.process.stderr.write(`${renderPreflightRefusal("image-gen", verdict)}\n`);
+			this.process.exitCode = 3;
+			return;
+		}
+		if (verdict.warning) this.process.stderr.write(`aibridge image-gen: ${verdict.warning}\n`);
+	}
 	const minBytes = model.spec.backend === "codex" ? MIN_REAL_BYTES_CODEX : MIN_REAL_BYTES_TOOL;
 	const work = mkdtempSync(join(tmpdir(), "aibridge-imagegen-"));
 	const effectivePrompt = flags.transparent ? `${prompt} ${alpha === "chroma" ? CHROMA_CLAUSE : NATIVE_ALPHA_CLAUSE}` : prompt;
@@ -585,6 +711,11 @@ const imageGen = buildCommand({
 				optional: true,
 				brief: "Max seconds to wait for the render (default: 600)"
 			},
+			preflight: {
+				kind: "boolean",
+				default: true,
+				brief: "Check model quota before rendering (use --no-preflight to skip)"
+			},
 			json: {
 				kind: "boolean",
 				withNegated: false,
@@ -626,122 +757,6 @@ async function delegate(opts, driver = getDriver(opts.model.spec.backend)) {
 	return result;
 }
 //#endregion
-//#region src/quotaPreflight.ts
-function evaluateAgyPreflight(snapshot, backendModel) {
-	const quota = findModelQuota(snapshot, backendModel);
-	if (!quota) return {
-		ok: true,
-		warning: `model "${backendModel}" not in quota snapshot; proceeding`
-	};
-	if (quota.exhausted) {
-		let resetAt = quota.resetTime;
-		if (!resetAt) {
-			for (const group of snapshot.groups) if (group.displayName.includes("Gemini")) {
-				for (const bucket of group.buckets) if (bucket.resetTime) {
-					if (!resetAt || new Date(bucket.resetTime).getTime() < new Date(resetAt).getTime()) resetAt = bucket.resetTime;
-				}
-			}
-		}
-		return {
-			ok: false,
-			kind: "quota",
-			message: `agy model "${backendModel}" is quota-exhausted`,
-			resetAt
-		};
-	}
-	return { ok: true };
-}
-function evaluateCodexPreflight(snapshot) {
-	if (snapshot.limitReached) return {
-		ok: false,
-		kind: "quota",
-		message: "codex quota limit reached",
-		resetAt: snapshot.windows.find((w) => w.resetAt)?.resetAt
-	};
-	const exhaustedWindow = snapshot.windows.find((w) => w.usedPercent >= 100);
-	if (exhaustedWindow) return {
-		ok: false,
-		kind: "quota",
-		message: "codex quota limit reached",
-		resetAt: exhaustedWindow.resetAt
-	};
-	return { ok: true };
-}
-function evaluateGrokPreflight(snapshot) {
-	if (snapshot.usedPercent !== void 0 && snapshot.usedPercent >= 100) return {
-		ok: false,
-		kind: "quota",
-		message: "grok credit quota exhausted",
-		resetAt: snapshot.periodEnd
-	};
-	return { ok: true };
-}
-async function preflightModel(resolved) {
-	if (resolved.spec.backend === "codex") return preflightCodex();
-	if (resolved.spec.backend === "grok") return preflightGrok();
-	if (resolved.spec.backend !== "agy") return { ok: true };
-	try {
-		return evaluateAgyPreflight(await fetchAgyQuota(), backendModelId(resolved));
-	} catch (err) {
-		if (isAuthExpired(err)) return {
-			ok: false,
-			kind: "auth",
-			message: err.message,
-			resetAt: void 0
-		};
-		return {
-			ok: true,
-			warning: `quota preflight failed (${err.message}); proceeding`
-		};
-	}
-}
-async function preflightCodex() {
-	try {
-		return evaluateCodexPreflight(await fetchCodexQuota());
-	} catch (err) {
-		if (isAuthExpired(err)) return {
-			ok: false,
-			kind: "auth",
-			message: err.message,
-			resetAt: void 0
-		};
-		return {
-			ok: true,
-			warning: `quota preflight failed (${err.message}); proceeding`
-		};
-	}
-}
-async function preflightGrok() {
-	try {
-		return evaluateGrokPreflight(await fetchGrokQuota());
-	} catch (err) {
-		if (isAuthExpired(err)) return {
-			ok: false,
-			kind: "auth",
-			message: err.message,
-			resetAt: void 0
-		};
-		return {
-			ok: true,
-			warning: `quota preflight failed (${err.message}); proceeding`
-		};
-	}
-}
-function formatReset$1(resetTime) {
-	if (!resetTime) return "-";
-	const ms = new Date(resetTime).getTime() - Date.now();
-	if (Number.isNaN(ms)) return resetTime;
-	if (ms <= 0) return "now";
-	const mins = Math.round(ms / 6e4);
-	const rel = mins < 60 ? `${mins}m` : `${Math.floor(mins / 60)}h${mins % 60}m`;
-	return `${new Date(resetTime).toLocaleTimeString()} (in ${rel})`;
-}
-function renderPreflightRefusal(cmd, verdict) {
-	if (verdict.kind === "auth") return `aibridge ${cmd}: refusing — ${verdict.message}. Running with --no-preflight would only send the delegate in unauthenticated. Or use a different --model.`;
-	const resetClause = verdict.resetAt ? ` Resets ${formatReset$1(verdict.resetAt)}.` : "";
-	return `aibridge ${cmd}: refusing — ${verdict.message}.${resetClause} Use --no-preflight to override, or a claude-backend fallback (subagent --model sonnet|opus — bills the Claude subscription).`;
-}
-//#endregion
 //#region src/runlog.ts
 function getTimestamp() {
 	const d = /* @__PURE__ */ new Date();
@@ -1385,7 +1400,7 @@ async function review$1(flags) {
 	const run = startRun("review", `${model.spec.slug}: ${modeDetail}`);
 	const absOutPath = isAbsolute(flags.out) ? flags.out : resolve(cwd, flags.out);
 	let reviewPrompt;
-	if (isDirty) reviewPrompt = `You are an expert code reviewer. Inspect the working tree diff against base '${baseRef}' and untracked files at ${cwd}.\n` + (absPlanPath ? `Compare the implementation against the plan contract at ${absPlanPath}. Any file modified or feature added outside the plan contract counts as over-reach (severity: major unless harmful, then critical).\n` : "") + `Write your detailed review report to the file ${absOutPath}. For each finding, include file:line, severity (critical|major|minor), and rationale.\nYour final answer (last message) must consist of EXACTLY ONE VERDICT LINE:\nEither: "PASS"\nOr: "FINDINGS: <c> critical, <m> major, <n> minor"`;
+	if (isDirty) reviewPrompt = `You are an expert code reviewer. Inspect the diff produced by \`git diff ${baseRef}\` (this covers committed and uncommitted changes) plus any untracked files at ${cwd}.\n` + (absPlanPath ? `Compare the implementation against the plan contract at ${absPlanPath}. Any file modified or feature added outside the plan contract counts as over-reach (severity: major unless harmful, then critical).\n` : "") + `Write your detailed review report to the file ${absOutPath}. For each finding, include file:line, severity (critical|major|minor), and rationale.\nYour final answer (last message) must consist of EXACTLY ONE VERDICT LINE:\nEither: "PASS"\nOr: "FINDINGS: <c> critical, <m> major, <n> minor"`;
 	else reviewPrompt = `You are an expert architecture reviewer. Inspect the plan contract file at ${absPlanPath}.\nReview the plan for soundness, missing edge cases, safety, and feasibility.\nWrite your detailed review report to the file ${absOutPath}. For each finding, include severity (critical|major|minor) and rationale.\nYour final answer (last message) must consist of EXACTLY ONE VERDICT LINE:\nEither: "PASS"\nOr: "FINDINGS: <c> critical, <m> major, <n> minor"`;
 	const outcome = await delegate({
 		model,
@@ -1447,7 +1462,7 @@ const review = buildCommand({
 			kind: "parsed",
 			parse: String,
 			optional: true,
-			brief: "Base git ref to diff against (default: HEAD)"
+			brief: "Base git ref or range to diff against, e.g. HEAD~3 or main (default: HEAD)"
 		},
 		out: {
 			kind: "parsed",
@@ -1467,7 +1482,7 @@ const review = buildCommand({
 		}
 	} },
 	docs: {
-		brief: "Review working tree diff or plan contract",
+		brief: "Review a diff (working tree, or any commit range via --base) or a plan contract",
 		fullDescription: fullDescription$2
 	}
 });
@@ -1641,6 +1656,62 @@ const runs = buildCommand({
 		fullDescription: fullDescription$1
 	}
 });
+const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version;
+//#endregion
+//#region src/commands/skill/impl.ts
+const TOPICS = {
+	plan: "reference/plan.md",
+	implement: "reference/implement.md",
+	review: "reference/review.md",
+	subagent: "reference/subagent.md",
+	"image-gen": "reference/image-gen.md",
+	why: "reference/why.md"
+};
+function instructionPath(relativePath) {
+	const found = [new URL(`../instructions/${relativePath}`, import.meta.url), new URL(`../../../instructions/${relativePath}`, import.meta.url)].find((candidate) => existsSync(candidate));
+	if (!found) throw new Error(`bundled instruction file is missing: ${relativePath}`);
+	return found;
+}
+function readInstruction(relativePath) {
+	return readFileSync(instructionPath(relativePath), "utf8").trimEnd();
+}
+function skillImpl(topic) {
+	if (topic !== void 0 && !(topic in TOPICS)) {
+		this.process.stderr.write(`aibridge skill: unknown topic ${JSON.stringify(topic)}; expected one of: ${Object.keys(TOPICS).join(", ")}\n`);
+		this.process.exitCode = 2;
+		return;
+	}
+	try {
+		const sections = [`Command runner for these instructions: \`${`npx -y @aibridge/cli@${PACKAGE_VERSION}`}\`\nUse that exact prefix for every aibridge command below; do not substitute a global binary.`, readInstruction("SKILL.md")];
+		if (topic !== void 0) sections.push(readInstruction(TOPICS[topic]));
+		this.process.stdout.write(`${sections.join("\n\n---\n\n")}\n`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		this.process.stderr.write(`aibridge skill: ${message}\n`);
+		this.process.exitCode = 1;
+	}
+}
+//#endregion
+//#region src/commands/skill/command.ts
+function skillCommand(_flags, topic) {
+	skillImpl.call(this, topic);
+}
+const skill = buildCommand({
+	func: skillCommand,
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				brief: "Command-specific instructions to append to the router",
+				parse: String,
+				placeholder: "topic",
+				optional: true
+			}]
+		}
+	},
+	docs: { brief: "Print the canonical agent instructions bundled with this CLI" }
+});
 //#endregion
 //#region src/commands/subagent/impl.ts
 async function subagent$1(flags, prompt) {
@@ -1762,9 +1833,6 @@ function normalizeExitCode(ctx) {
 	}
 	if (code !== 0 && code !== 1 && code !== 2 && code !== 3) ctx.process.exitCode = 1;
 }
-//#endregion
-//#region src/app.ts
-const { version } = createRequire(import.meta.url)("../package.json");
 const app = buildApplication(buildRouteMap({
 	routes: {
 		plan,
@@ -1774,12 +1842,13 @@ const app = buildApplication(buildRouteMap({
 		"image-gen": imageGen,
 		runs,
 		quota,
-		models
+		models,
+		skill
 	},
 	docs: { brief: "Bridge tasks to the other AI CLIs on this machine — a plan → implement → review workflow, task delegation, and image generation (codex / agy / grok seats)." }
 }), {
 	name: "aibridge",
-	versionInfo: { currentVersion: version },
+	versionInfo: { currentVersion: PACKAGE_VERSION },
 	scanner: { caseStyle: "allow-kebab-for-camel" }
 });
 /** Public entry used by cli.ts and index.ts — preserves runCli(ctx, argv) surface. */
@@ -1793,4 +1862,4 @@ function buildContext(process) {
 	return { process };
 }
 //#endregion
-export { supportsImageGen as S, backendModelId as _, readRunLogs as a, listModelHelpLines as b, evaluateCodexPreflight as c, renderPreflightRefusal as d, delegate as f, MODELS as g, positiveIntSeconds as h, listRuns as i, preflightCodex as l, nonEmptyPrompt as m, app as n, startRun as o, getDriver as p, runCli as r, evaluateAgyPreflight as s, buildContext as t, preflightModel as u, formatImageGenModelError as v, resolveModel as x, formatUnknownModelError as y };
+export { supportsImageGen as S, backendModelId as _, readRunLogs as a, listModelHelpLines as b, evaluateAgyPreflight as c, preflightModel as d, renderPreflightRefusal as f, MODELS as g, positiveIntSeconds as h, listRuns as i, evaluateCodexPreflight as l, nonEmptyPrompt as m, app as n, startRun as o, getDriver as p, runCli as r, delegate as s, buildContext as t, preflightCodex as u, formatImageGenModelError as v, resolveModel as x, formatUnknownModelError as y };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateCodexPreflight, d as renderPreflightRefusal, f as delegate, g as MODELS, h as positiveIntSeconds, i as listRuns, l as preflightCodex, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as evaluateAgyPreflight, t as buildContext, u as preflightModel, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-DJtEcg6f.mjs";
+import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateAgyPreflight, d as preflightModel, f as renderPreflightRefusal, g as MODELS, h as positiveIntSeconds, i as listRuns, l as evaluateCodexPreflight, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as delegate, t as buildContext, u as preflightCodex, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-DeJmEXLe.mjs";
 export { MODELS, app, backendModelId, buildContext, delegate, evaluateAgyPreflight, evaluateCodexPreflight, formatImageGenModelError, formatUnknownModelError, getDriver, listModelHelpLines, listRuns, nonEmptyPrompt, positiveIntSeconds, preflightCodex, preflightModel, readRunLogs, renderPreflightRefusal, resolveModel, runCli, startRun, supportsImageGen };

package/instructions/SKILL.md

@@ -0,0 +1,115 @@
+# aibridge
+
+Use other providers' authenticated AI CLIs as delegates. You choose the task,
+model, and prompt; aibridge runs the backend and validates its output. Each run
+spends the selected backend's quota.
+
+Load the `why` topic only when a rule appears unsuitable.
+
+## Running it
+
+The output header defines the exact command runner for this instruction set.
+Examples below abbreviate that runner as `aibridge`; always substitute the exact
+runner. This keeps instructions and executable behavior on the same version.
+
+Requires Node 24.11 or later. If Node is older, ask the user to upgrade with
+`nvm install 24` or `mise use node@24`. Ask before any global install.
+
+Backing CLIs must be on `PATH` and authed: `grok`, `agy` (Antigravity), `codex`,
+`claude`. Any subset works; commands fail fast with install hints.
+
+## Where `--out` goes
+
+- Put permanent project assets in their final location, such as
+  `--out public/icons/settings.png`.
+- Put plans, reviews, and drafts in `<repo root>/.aibridge/`. Outside a
+  repository, use `.aibridge/` under the current directory.
+- Name files by topic. Promote a draft to its real path once it is the keeper.
+- Once per session, before the first write: `git check-ignore -q .aibridge/`
+  Keep the trailing slash so a directory-only rule matches before the directory
+  exists. If the command fails, ask to add `.aibridge/` to `.gitignore`.
+- An explicit path from the user wins over all of this.
+
+## Subcommands
+
+| Command | Description |
+|---|---|
+| `plan` | Expand a task into a detailed implementation plan file |
+| `implement` | Implement a plan file in place and run the real checks |
+| `review` | Review a diff, commit range, or plan contract |
+| `subagent` | Delegate a self-contained task to another model |
+| `image-gen` | Generate a raster image with a Codex, Antigravity, or Grok seat |
+| `runs` | Monitor and inspect execution runs |
+| `quota` | Show backend quota and reset times |
+| `models` | List registered model seats and capabilities |
+
+`plan`, `review` and `image-gen` require `--out` and print only a verdict/path
+line. `subagent` and `implement` have no `--out`; they print the delegate's
+answer to stdout, and `subagent --out foo.md` exits 2 with
+`No flag registered for --out`. Redirect if you want that answer in a file.
+
+## Routing
+
+1. **First word is a subcommand** → use the command-specific section appended
+   to this output. If it is missing, run `aibridge skill <subcommand>` before
+   taking action.
+2. **No subcommand** → infer:
+   - an image, icon or graphic to make → `image-gen`;
+   - a self-contained task, cross-model second opinion, or red-team → `subagent`;
+   - sizeable or risky implementation work → `plan` → *you read, edit and
+     approve the plan file* → `implement` → `review --plan <file>`. For
+     high-risk designs only, add a gate before any code is written:
+     `review --plan` on a clean tree.
+
+   If genuinely ambiguous, show the table above and ask.
+3. **Unsure of the current flags?** Run `aibridge <command> --help`.
+
+## Model seats
+
+`--model` is required on every command that spends a delegate (`plan`,
+`implement`, `review`, `subagent`, `image-gen`); nothing is chosen for you.
+`quota`, `models` and `runs` take no `--model`. Starting points, not
+benchmarks:
+
+| slug | plan | implement | review | image-gen |
+|---|---|---|---|---|
+| `xai-grok/grok-4.6` | ✅ small–mid, well-scoped | ○ | ✅ | ○ JPEG |
+| `xai-grok/grok-4.5` | ○ | ✅ any fidelity | ○ | ○ JPEG |
+| `openai-codex/gpt-5.6-sol` | ✅ mid–big, ambiguous | ○ | ✅ | ✅ PNG |
+| `anthropic-claude/opus-5` | ✅ mid–big, ambiguous | ○ | ✅ | ✗ |
+| `google-antigravity/gemini-3.7-flash` | ○ | ✅ needs high–xhigh detail | ○ | ○ JPEG |
+| `anthropic-claude/sonnet-5` | ○ | ✅ needs high detail | ○ | ✗ |
+
+✅ recommended · ○ supported · ✗ unsupported. For `plan`, the qualifier describes
+how much ambiguity the model can resolve. For `implement`, it describes how
+detailed the plan must be.
+**If the task fits no row, or the user has said how they want work routed, ask
+rather than guess.**
+
+Also registered: `openai-codex/gpt-5.6-terra` / `-luna` (cheaper coding tiers),
+`anthropic-claude/fable-5` (hardest, longest-running work),
+`anthropic-claude/haiku-4-5` (quick answers),
+`google-antigravity/gemini-3.6-flash`, `google-antigravity/gemini-3.1-pro`
+(`-high`/`-low` only), and agy's `claude-sonnet-4-6` /
+`claude-opus-4-6-thinking` / `gpt-oss-120b-medium`. Run `aibridge models
+[--json]` for exact per-seat facts, or `aibridge <command> --help` for the list.
+
+- **One grok stage at a time.** ~30 req/min, ~1k msgs/day, and both tiers share
+  that budget.
+- **`grok-4.6` plans and reviews, `grok-4.5` implements.** They are different
+  seats, not old and new.
+- **The reviewer must be a different model family from whoever implemented**,
+  including when that was you.
+- **A backend that shares YOUR quota is a last resort**: `anthropic-claude/*`
+  for Claude-based agents, `google-antigravity/*` for Antigravity-based agents.
+  Say so when you reach for it.
+- **Swap on quota**: `openai-codex/gpt-5.6-sol[-<effort>]` is the usual alternate.
+- Preflight runs before every delegation. `aibridge quota` is the manual check
+  before you pipeline several stages.
+
+## Trust
+
+In tools mode, delegates can read files, write files, and run shell commands at
+your trust level. The selected provider receives the prompt and any content the
+delegate reads. Use `--no-tools` for untrusted input; it disables file and shell
+access.