@aibridge/cli 0.9.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 a diff against the plan contract, where over-reach is a finding. `--base <ref>` reviews any commit range, not just the working tree. On a clean tree it reviews the plan itself |
-| `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-BQgclUqy.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-BQgclUqy.mjs → context-DeJmEXLe.mjs}

@@ -1656,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) {
@@ -1777,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,
@@ -1789,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. */

package/dist/index.mjs

@@ -1,2 +1,2 @@
-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-BQgclUqy.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.

package/instructions/reference/image-gen.md

@@ -0,0 +1,107 @@
+# image-gen — generate an image via a model seat
+
+Part A covers the command. Part B covers prompt design, which applies even when
+you only need to return a prompt.
+
+## A. Calling it
+
+```bash
+aibridge image-gen --model <slug> --out <file.png> "<full prompt — see part B>" \
+  [--aspect-ratio 16:9] [--image ref.png] [--transparent] \
+  [--timeout 600] [--no-preflight] [--json]
+```
+
+| slug | renders via | format |
+|---|---|---|
+| `openai-codex/gpt-5.6-sol` (recommended) | Codex CLI | PNG |
+| `google-antigravity/gemini-3.7-flash` | Antigravity CLI (`agy`) | JPEG |
+| `xai-grok/grok-4.6` | `api.x.ai` directly, on `~/.grok/auth.json` | JPEG |
+
+Other seats fail fast with a list of capable models. The grok seat renders
+without `grok` on `PATH`; the CLI is spawned only to refresh the token, before a
+request when `expires_at` is close and again as a backstop if one comes back
+401. `grok login` is still what sets the seat up.
+
+- `--out` is required and its extension must match the seat's format above
+  (`.png` for any `--transparent` run). A mismatch is rejected before anything
+  runs. The file holds the model's own bytes verbatim, except on a
+  chroma-keyed `--transparent` run, which writes the locally keyed PNG.
+- **Render into the asset's real home** (`public/icons/settings.png`) when the
+  project keeps it. Drafts go to `.aibridge/`; see [SKILL.md](../SKILL.md).
+- `--aspect-ratio N:M` sets geometry. Exact pixels are whatever the model
+  renders; resize downstream.
+- `--image a.png,b.png` attaches references and routes to the seat's edit path.
+- `--json` prints `{ out, bytes, width, height, aspectRatio, model, backend, transparency, real }`.
+- Preflight is on by default: an exhausted seat exits 3 and names the
+  alternatives instead of spending a paid render. Argument checks run first, so
+  bad flags still cost no network call.
+
+### Transparency
+
+- `--transparent` works on every image seat and always writes PNG. Codex gives
+  native alpha; grok and gemini are chroma-keyed with binary edges. Fine for
+  flat icons, logos and stickers; not for hair, smoke or glass.
+- **Say nothing about the background in the prompt when using it.** The CLI
+  writes the backdrop instruction per seat, and a colour of your own overrides
+  it: the key then finds nothing and the paid render comes back opaque. Writing
+  "transparent background" into the prompt without the flag is refused on
+  chroma seats.
+- **A green subject is keyed away with the backdrop** on chroma seats. Anything
+  that must be green needs `openai-codex/*`.
+- Both surfaces report the path taken: the result line says
+  `transparency: native` / `chroma-keyed`, `--json` carries
+  `"native" | "chroma" | null`. Quote it when the edges matter. Keying under 2%
+  of the image warns: the model likely ignored the backdrop instruction.
+
+### Reference images
+
+```bash
+aibridge image-gen --model openai-codex/gpt-5.6-sol \
+  "the same woman, now in a denim shirt in a bright kitchen, waist-up" \
+  --out avatar2.png --image avatar.png --aspect-ratio 9:16
+```
+
+With a reference, write the prompt as a **diff**: say only what changes. The
+reference carries identity, framing and style.
+
+## B. Writing the prompt
+
+1. **Never state the image's purpose** (no "app icon", "hero banner"). Describe
+   how it looks, not its job.
+2. **Give the aspect ratio** via `--aspect-ratio` and/or the prompt text.
+3. **Always specify the background**: a hex colour, or `opaque`/`auto`. Except
+   on a `--transparent` run, where you say nothing about it.
+4. **Specify** subject, composition, palette, style/medium, mood, lighting.
+5. **Lock the critical, free the rest.** Lock verbatim text in straight quotes,
+   brand hex, required layout, the hero subject, and every "no X". Over-specified
+   incidental detail flattens the result.
+
+### Worked example
+
+> `Square 1:1 aspect ratio. Solid warm cream #F7F1EA background. A single flat-design
+> fanned stack of three rounded-corner cards in coral orange #FF5A1F, centered,
+> ~55% of the frame, soft drop shadow. Calm, minimal, modern. No text, no border,
+> no gradient.`
+
+Locked: ratio, background hex, subject, brand orange, the no-text/border/gradient
+constraints. Free: fan angle, shadow softness, spacing. On a `--transparent` run,
+drop the background sentence and the drop shadow: a soft shadow has no flat
+backdrop colour to key against and survives as a pale halo.
+
+### Edits and retries
+
+1. **Describe the desired result.** State what the finished image contains,
+   rather than only what to remove or correct.
+2. **Name the visual criterion first.** Phrases such as "the near plane" or
+   "everyone waiting" often work better than an object inventory. Enumerate
+   objects only if the criterion fails.
+3. **Rewrite failed prompts; do not append to them.** Simplify the request. For
+   a near-correct render, make the next instruction as short as possible.
+4. **Change strategy after the same failure occurs twice.** Try a different
+   reference, composition, or fresh generation instead of another rewording.
+5. **Retry from the original reference.** Chaining generated outputs causes
+   unrequested details to drift.
+6. **Check your terminology.** A near-miss word can produce a coherent image of
+   the wrong concept.
+7. **Verify unchanged details in context.** Inspect the asset in its final
+   placement and, when relevant, in motion.

package/instructions/reference/implement.md

@@ -0,0 +1,51 @@
+# implement — execute a plan file
+
+An implementer edits the working tree and runs the project's checks. This is the
+third step in **`plan` → read and approve → `implement` → `review`**.
+
+Run this only after reading and approving the plan. If the implementer would
+need to make a product or architecture decision, fix the plan first.
+
+## Usage
+
+```bash
+aibridge implement --model <slug> <plan-file>
+  --model <slug>       implementer model (required, e.g. google-antigravity/gemini-3.7-flash)
+  --timeout <secs>     max seconds (default: 1800)
+  --no-preflight       skip the quota preflight
+```
+
+## Behaviour
+
+The delegate runs with full tools at the repository root. It must follow the
+plan, edit only named files, run the specified checks until they pass, and avoid
+commits, pushes, and unrelated deletions.
+
+## Output
+
+```
+<delegate's short summary>
+
+ <git diff --stat>
+untracked files: <count>
+run: <run id>
+```
+
+Exit 0: completed with tree changes. Exit 1: delegate failed, timed out, gave no
+usable answer, or changed nothing (a no-op implement is a failure). Exit 2: bad
+args or missing plan file. Exit 3: quota preflight refusal.
+
+## After it returns
+
+1. **Re-run the checks yourself.** The summary reports the delegate's claim.
+2. Then `aibridge review --model xai-grok/grok-4.6 --plan <plan-file> --out .aibridge/review.md`.
+
+## Gotchas
+
+- Keep the implementer a different model family from the reviewer. The
+  recommended seats (gemini implements, grok reviews) comply; if you override
+  one, check the other.
+- agy quota is shared by model group. Two concurrent agy-heavy runs drain
+  the same window. Run `aibridge quota` before pipelining.
+- The timeout covers the whole run including gate-fixing loops. Raise it for big
+  plans rather than letting a near-done run get killed.

package/instructions/reference/plan.md

@@ -0,0 +1,69 @@
+# plan — write a detailed implementation plan file
+
+A planner studies the codebase and writes a detailed plan to a file. This is the
+first step in **`plan` → read and approve → `implement` → `review`**. Pass the
+file path—not its contents—between stages.
+
+Use it for sizeable or risky work. For small, fully-specified chunks use
+`subagent`, or just do them.
+
+## Usage
+
+```bash
+aibridge plan --model <slug> --out <file> "<task prompt>"
+  --model <slug>       planner model (required, e.g. xai-grok/grok-4.6)
+  --out <file>         where to write the plan (required)
+  --timeout <secs>     max seconds (default: 1800)
+  --no-preflight       skip the quota preflight
+```
+
+The positional argument is the task prompt, not a file path.
+
+## Writing the task prompt
+
+The planner can read the code. Do not paste file contents. Provide only what it
+cannot infer:
+
+- the goal and the user-visible behaviour change;
+- hard constraints (APIs to keep stable, zero-dep rules, style conventions);
+- scope boundaries and non-goals;
+- architectural calls you have already made, since the planner details your
+  design rather than overruling it;
+- starting files, if the repo is large.
+
+## Behaviour
+
+- The planner writes exactly one file (`--out`). Any other change to the working
+  tree fails the run (exit 1, paths listed). An `--out` inside the repo is
+  exempt.
+- The plan must end with `## Open questions` (`None.` when confident). The count
+  prints on stdout.
+
+## Output
+
+```
+plan: /abs/path/to/plan.md
+open questions: 2
+run: <run id>
+```
+
+Exit 0 even with open questions. Exit 1: plan missing, empty, no open-questions
+section, tree dirtied, delegate failure or timeout. Exit 2: bad arguments.
+Exit 3: quota preflight refusal.
+
+## After it returns
+
+1. **Read the plan file.** It is the implementation contract.
+2. Resolve every open question: edit the file directly, or re-run `plan` with a
+   sharpened prompt.
+3. High-risk design? Gate it first:
+   `aibridge review --model xai-grok/grok-4.6 --plan <file> --out .aibridge/review.md`
+   on a clean tree.
+4. Then `aibridge implement --model google-antigravity/gemini-3.7-flash <file>`.
+
+## Gotchas
+
+- `--out` belongs in `.aibridge/` (see [SKILL.md](../SKILL.md)); check it is
+  gitignored once per session.
+- grok is capped at ~30 req/min, ~1k msgs/day, one run at a time. Never run two
+  grok stages concurrently.

package/instructions/reference/review.md

@@ -0,0 +1,75 @@
+# review — cross-model review of a diff or a plan
+
+A reviewer inspects a diff, optionally against a plan contract, and writes its
+report to a file. Standard output contains only the verdict and paths.
+
+## Usage
+
+```bash
+aibridge review --model <slug> --out <file> [options]
+  --model <slug>       reviewer model (required, e.g. xai-grok/grok-4.6)
+  --plan <file>        plan contract; over-reach against it is a finding
+  --base <ref>         any git ref or range to diff against (default: HEAD)
+  --out <file>         full report destination (required)
+  --timeout <secs>     max seconds (default: 1200)
+  --no-preflight       skip the quota preflight
+```
+
+## Picking the diff
+
+`--base` is passed straight to `git diff`, so any ref or range git accepts
+works: `HEAD~3`, a branch, a SHA, a tag, `v1.2.0..HEAD`.
+
+```bash
+# uncommitted work only (the default base, HEAD)
+aibridge review --model xai-grok/grok-4.6 --out .aibridge/review.md
+
+# the 3 commits you just made
+aibridge review --model xai-grok/grok-4.6 --base HEAD~3 --out .aibridge/review.md
+
+# the whole branch, against the plan contract
+aibridge review --model xai-grok/grok-4.6 --base main \
+  --plan .aibridge/plan.md --out .aibridge/review.md
+```
+
+Use `--base` to review committed work. Do not copy a diff into a file for
+`subagent`. Uncommitted changes are included unless the range fixes both ends.
+
+## Modes (detected before any model spend)
+
+1. **Diff review:** changes or untracked files exist relative to `--base`. With
+   `--plan`, unrequested changes count as over-reach.
+2. **Plan review:** nothing differs from `--base` and `--plan` is given.
+   Reviews the plan for soundness, edge cases, safety, feasibility. Use it as a
+   pre-implementation gate on high-risk designs.
+3. **No input:** nothing differs and no `--plan` is given. Exits 2.
+
+## Output & exit codes
+
+```
+PASS                                  | FINDINGS: 1 critical, 0 major, 3 minor
+review: /abs/path/to/review.md
+run: <run id>
+```
+
+- `0`: PASS, or minor-only findings.
+- `1`: critical or major findings; unparseable verdict (raw answer + paths still
+  print); missing or empty report file; delegate failure or timeout.
+- `2`: bad flags, missing plan file, nothing to review, bad base ref.
+- `3`: quota preflight refusal.
+
+## After it returns
+
+- `PASS` → proceed (commit, or report done).
+- Findings → read the report, then judge. Over-reach findings can be scope you
+  added deliberately: the reviewer flags, you decide. Fix what is real, re-run.
+- Never let a model review its own diff. The recommended seats (grok reviews,
+  gemini implements) already comply; if you override one, check the other.
+
+## Gotchas
+
+- The report file is required even for PASS. Missing or empty fails the run.
+- Verdict parsing accepts the line first, last, or at the end of a narration
+  blob (grok concatenates progress prose). If it still fails, you get exit 1
+  with the raw answer plus the report path on stdout.
+- A bad `--base` ref is a hard error (exit 2), not a silent dirty-tree fallback.

package/instructions/reference/subagent.md

@@ -0,0 +1,48 @@
+# subagent — delegate a task to another model
+
+Delegate one self-contained task to another provider's model. Use this for a
+second opinion, red-team review, long-context analysis, or a clearly specified
+piece of work.
+
+## Usage
+
+```bash
+aibridge subagent --model <slug> "<self-contained prompt>" [options]
+  --model <slug>       required, canonical slug (no short aliases)
+  --timeout <secs>     max seconds (default: 600)
+  --no-tools           reasoning only: no file or shell access
+  --no-preflight       skip the quota preflight
+  --json               machine-readable, e.g. {"model": "grok-4.6", "slug": "xai-grok/grok-4.6", ...}
+```
+
+The answer prints to stdout. There is no `--out`; redirect if you want a file.
+
+Effort suffixes work on seats that support them
+(`xai-grok/grok-4.6-medium`, `google-antigravity/gemini-3.7-flash-low`,
+`anthropic-claude/sonnet-5-max`). The seat table is in [SKILL.md](../SKILL.md);
+`aibridge subagent --help` prints the live list.
+
+**Tools are ON by default** — the delegate reads/writes files and runs shell.
+
+## Writing the prompt
+
+Write for a capable model with no conversation context:
+
+1. **Self-contained.** Paste the code or spec to act on. Never reference "what
+   we discussed".
+2. **Specify the approach.** Include design decisions, interfaces, files, and
+   constraints without prescribing every line of code.
+3. **State the constraints.** Run the real typecheck and tests until green;
+   write code only, no commit/push/deploy/delete; reply with a short summary.
+4. **Verify the result.** Re-run the real gates yourself.
+
+## When to stay native instead
+
+- The task needs session-specific tools, skills, or MCP servers.
+- It needs conversational context or live user guidance.
+- It needs strict schema validation or guaranteed retry orchestration.
+
+## Scaling up
+
+For large or multi-file work, use the three verbs instead of raw subagent calls:
+[plan](plan.md) → you approve → [implement](implement.md) → [review](review.md).

package/instructions/reference/why.md

@@ -0,0 +1,54 @@
+# why — the reasoning behind the rules
+
+This page explains rules that the command guides state without rationale. Read
+it when a rule appears unsuitable for your case.
+
+**Paths travel between stages, not contents.** A plan re-emitted into your
+context costs you the tokens the split was meant to save. `plan` writes a file,
+`implement` reads that path, `review` takes it as `--plan`. Nothing round-trips
+through you except your judgment.
+
+**You read the plan file.** That sign-off is the entire point of splitting plan
+from implement. Skip it and you have an unreviewed contract that a second model
+will now execute literally.
+
+**The implementer is a pure do-er.** It executes a fully-designed plan and does
+not hold the surrounding vision. When a plan turns out to need that vision, the
+design work upstream was insufficient. Fix the plan rather than briefing the
+implementer.
+
+**Reviewers are cross-model on purpose.** A model reviewing its own diff shares
+its own blind spots and will wave through the thing it just failed to see. This
+applies to you too: prefer a reviewer outside your own model family for code you
+wrote yourself.
+
+**Over-reach is a finding.** A delegate that also refactors three neighbouring
+files has left the contract, and the diff you now have to verify is bigger than
+the one you asked for. The reviewer flags it; you decide whether it was scope
+you wanted.
+
+**Quota is relative to whoever runs the skill.** Every backend spends its own
+CLI's login. A backend on the same provider as you (`anthropic-claude/*` for a
+Claude-based agent) drains the pool you are already burning, so it buys no extra
+capacity and no independent perspective. That is why it is a last resort rather
+than merely a choice.
+
+**Seats pin exact model versions.** A vendor alias like `opus` moves under you
+when a release lands, silently changing what a documented pipeline does.
+
+**Some commands write files, some print.** `plan`, `review` and `image-gen`
+produce artifacts worth keeping and re-reading, so they take `--out` and keep
+stdout to a verdict line. `subagent` returns an answer you consume immediately,
+and `implement`'s output IS the working tree.
+
+**The CLI catches fake successes, not bad work.** Backends fail in ways that
+look like success: an agy model with no quota returns an empty answer and exit 0;
+codex sometimes draws a tiny image in code instead of rendering one. So a
+too-small render is rejected as fake, an empty answer is an error, and an
+`implement` that changed nothing exits 1. A review with no report file fails as
+well, because a verdict without evidence is not a review. None of that judges
+the work itself, which is why you still re-run the real gates on a diff.
+
+**Chroma keying is a fallback, not a feature.** Only codex renders true alpha.
+On the JPEG seats aibridge asks for a flat backdrop and removes it locally,
+which gives binary edges and eats any subject the same colour as the backdrop.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aibridge/cli",
-  "version": "0.9.0",
-  "description": "CLI that bridges tasks to AI CLIs on your machine (plan / implement / review / subagent / image-gen)",
+  "version": "0.10.0",
+  "description": "Agent instructions and CLI for delegating work to authenticated AI CLIs",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -31,16 +31,17 @@
   },
   "files": [
     "dist",
+    "instructions",
     "src"
   ],
   "dependencies": {
     "@stricli/core": "1.3.0",
     "sharp": "^0.35.3",
+    "@aibridge/driver-agy": "0.9.0",
     "@aibridge/proc": "0.9.0",
-    "@aibridge/driver-grok": "0.9.0",
     "@aibridge/driver-codex": "0.9.0",
-    "@aibridge/driver-agy": "0.9.0",
-    "@aibridge/driver-claude": "0.9.0"
+    "@aibridge/driver-claude": "0.9.0",
+    "@aibridge/driver-grok": "0.9.0"
   },
   "devDependencies": {
     "tsdown": "0.22.14"

package/src/app.exit-code.test.ts

@@ -84,7 +84,16 @@ describe('stricli exit-code lock & routing', () => {
     const ctx = fakeCtx();
     await runCli(ctx, ['--help']);
     const output = ctx._stdout.join('');
-    for (const cmd of ['plan', 'implement', 'review', 'subagent', 'image-gen', 'runs', 'quota']) {
+    for (const cmd of [
+      'plan',
+      'implement',
+      'review',
+      'subagent',
+      'image-gen',
+      'runs',
+      'quota',
+      'skill',
+    ]) {
       expect(output).toContain(cmd);
     }
   });

package/src/app.ts

@@ -1,4 +1,3 @@
-import { createRequire } from 'node:module';
 import { buildApplication, buildRouteMap, run } from '@stricli/core';
 import { imageGen } from './commands/image-gen/command.ts';
 import { implement } from './commands/implement/command.ts';
@@ -7,12 +6,11 @@ import { plan } from './commands/plan/command.ts';
 import { quota } from './commands/quota/command.ts';
 import { review } from './commands/review/command.ts';
 import { runs } from './commands/runs/command.ts';
+import { skill } from './commands/skill/command.ts';
 import { subagent } from './commands/subagent/command.ts';
 import type { LocalContext } from './context.ts';
 import { normalizeExitCode } from './exitCode.ts';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../package.json') as { version: string };
+import { PACKAGE_VERSION } from './package.ts';
 
 const 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).';
@@ -27,6 +25,7 @@ const routes = buildRouteMap({
     runs,
     quota,
     models,
+    skill,
   },
   docs: {
     brief: BRIEF,
@@ -36,7 +35,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: 'aibridge',
   versionInfo: {
-    currentVersion: version,
+    currentVersion: PACKAGE_VERSION,
   },
   scanner: {
     // Accept --no-preflight / --no-tools while flag keys stay camelCase in TS

package/src/commands/skill/command.ts

@@ -0,0 +1,28 @@
+import { buildCommand } from '@stricli/core';
+import type { LocalContext } from '../../context.ts';
+import skillImpl from './impl.ts';
+
+function skillCommand(this: LocalContext, _flags: Record<never, never>, topic?: string): void {
+  skillImpl.call(this, topic);
+}
+
+export 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',
+  },
+});

package/src/commands/skill/impl.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import type { LocalContext } from '../../context.ts';
+import { PACKAGE_VERSION } from '../../package.ts';
+import skillImpl from './impl.ts';
+
+function fakeCtx(): LocalContext & { stdout: string[]; stderr: string[] } {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  return {
+    process: {
+      stdout: {
+        write: (value: string) => {
+          stdout.push(value);
+          return true;
+        },
+      },
+      stderr: {
+        write: (value: string) => {
+          stderr.push(value);
+          return true;
+        },
+      },
+      exitCode: undefined,
+    } as unknown as NodeJS.Process,
+    stdout,
+    stderr,
+  };
+}
+
+describe('skill command', () => {
+  it('prints the router with an exact-version runner', () => {
+    const ctx = fakeCtx();
+    skillImpl.call(ctx);
+    const output = ctx.stdout.join('');
+
+    expect(output).toContain(`npx -y @aibridge/cli@${PACKAGE_VERSION}`);
+    expect(output).toContain('# aibridge');
+    expect(output).not.toContain('# plan —');
+    expect(ctx.process.exitCode).toBeUndefined();
+  });
+
+  it('appends command-specific instructions', () => {
+    const ctx = fakeCtx();
+    skillImpl.call(ctx, 'plan');
+    const output = ctx.stdout.join('');
+
+    expect(output).toContain('# aibridge');
+    expect(output).toContain('# plan — write a detailed implementation plan file');
+  });
+
+  it('rejects an unknown topic', () => {
+    const ctx = fakeCtx();
+    skillImpl.call(ctx, 'nope');
+
+    expect(ctx.process.exitCode).toBe(2);
+    expect(ctx.stderr.join('')).toContain('unknown topic "nope"');
+    expect(ctx.stdout).toEqual([]);
+  });
+});

package/src/commands/skill/impl.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import type { LocalContext } from '../../context.ts';
+import { PACKAGE_VERSION } from '../../package.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',
+} as const;
+
+export type SkillTopic = keyof typeof TOPICS;
+
+function instructionPath(relativePath: string): URL {
+  const candidates = [
+    // Built package: dist/cli.mjs -> instructions/
+    new URL(`../instructions/${relativePath}`, import.meta.url),
+    // Source tree: src/commands/skill/impl.ts -> instructions/
+    new URL(`../../../instructions/${relativePath}`, import.meta.url),
+  ];
+  const found = candidates.find(candidate => existsSync(candidate));
+  if (!found) {
+    throw new Error(`bundled instruction file is missing: ${relativePath}`);
+  }
+  return found;
+}
+
+function readInstruction(relativePath: string): string {
+  return readFileSync(instructionPath(relativePath), 'utf8').trimEnd();
+}
+
+export default function skillImpl(this: LocalContext, topic?: string): void {
+  if (topic !== undefined && !(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 runner = `npx -y @aibridge/cli@${PACKAGE_VERSION}`;
+    const sections = [
+      `Command runner for these instructions: \`${runner}\`\nUse that exact prefix for every aibridge command below; do not substitute a global binary.`,
+      readInstruction('SKILL.md'),
+    ];
+
+    if (topic !== undefined) {
+      sections.push(readInstruction(TOPICS[topic as SkillTopic]));
+    }
+
+    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;
+  }
+}

package/src/package.ts

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const PACKAGE_VERSION = (require('../package.json') as { version: string }).version;