@aibridge/cli 0.8.0 → 0.10.0

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.8.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/proc": "0.8.0",
-    "@aibridge/driver-agy": "0.8.0",
-    "@aibridge/driver-codex": "0.8.0",
-    "@aibridge/driver-claude": "0.8.0",
-    "@aibridge/driver-grok": "0.8.0"
+    "@aibridge/driver-agy": "0.9.0",
+    "@aibridge/proc": "0.9.0",
+    "@aibridge/driver-codex": "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/image-gen/command.ts

@@ -51,6 +51,11 @@ export 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,

package/src/commands/image-gen/impl.test.ts

@@ -30,6 +30,7 @@ const flags = (over: Partial<ImageGenFlags>): ImageGenFlags => ({
   out: '/tmp/out.jpg',
   json: false,
   transparent: false,
+  preflight: false,
   ...over,
 });
 

package/src/commands/image-gen/impl.ts

@@ -25,6 +25,7 @@ import {
   resolveModel,
   supportsImageGen,
 } from '../../models.ts';
+import { preflightModel, renderPreflightRefusal } from '../../quotaPreflight.ts';
 import {
   CHROMA_CLAUSE,
   chromaKeyToPng,
@@ -38,6 +39,7 @@ export interface ImageGenFlags {
   readonly aspectRatio?: string;
   readonly image?: string;
   readonly timeout?: number;
+  readonly preflight: boolean;
   readonly json: boolean;
   readonly transparent: boolean;
 }
@@ -122,6 +124,18 @@ export default async function imageGen(
     return fail(formatImageGenModelError(inputSlug, model));
   }
 
+  // Last gate before a paid render. Every check above is local and must stay
+  // above it, so a bad --out or aspect ratio still fails without a network call.
+  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-'));
 

package/src/commands/review/command.ts

@@ -29,7 +29,7 @@ export 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',
@@ -50,7 +50,7 @@ export 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,
   },
 });

package/src/commands/review/impl.ts

@@ -145,7 +145,7 @@ export default async function review(this: LocalContext, flags: ReviewFlags): Pr
   let reviewPrompt: string;
   if (isDirty) {
     reviewPrompt =
-      `You are an expert code reviewer. Inspect the working tree diff against base '${baseRef}' and untracked files at ${cwd}.\n` +
+      `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`
         : '') +

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([]);
+  });
+});