agent-orchestration-skill 0.0.0-stage → 1.0.0

package/bin/cli.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * bin/cli.mjs — Zero-dependency NPX installer, doctor & CLI runner for `agent-orchestration`.
+ *
+ * Supports:
+ *   npx github:haulth/agent-orchestration [install] [--dry-run] [--no-backup] [--home <dir>]
+ *   npx github:haulth/agent-orchestration doctor
+ *   npx github:haulth/agent-orchestration uninstall
+ *   npx github:haulth/agent-orchestration <route|anatomy|run|batch|verdict|stats|sandbox|discover> [args...]
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT_DIR = path.resolve(path.dirname(__filename), "..");
+
+const COPY_ITEMS = [
+  "SKILL.md",
+  "CATALOG.md",
+  "README.md",
+  "LICENSE",
+  "package.json",
+  ".npmignore",
+  "bin",
+  "install",
+  "assets",
+  "references",
+  "scripts",
+];
+
+function defaultTargets(homeDir) {
+  return [
+    path.join(homeDir, ".claude", "skills", "agent-orchestration"),
+    path.join(homeDir, ".agents", "skills", "agent-orchestration"),
+    path.join(homeDir, ".codex", "skills", "agent-orchestration"),
+    path.join(homeDir, ".gemini", "config", "skills", "agent-orchestration"),
+  ];
+}
+
+function findPython() {
+  const candidates =
+    process.platform === "win32"
+      ? [
+          ["python", ["-c", "import sys; assert sys.version_info >= (3, 8)"]],
+          ["py", ["-3", "-c", "import sys; assert sys.version_info >= (3, 8)"]],
+          ["python3", ["-c", "import sys; assert sys.version_info >= (3, 8)"]],
+        ]
+      : [
+          ["python3", ["-c", "import sys; assert sys.version_info >= (3, 8)"]],
+          ["python", ["-c", "import sys; assert sys.version_info >= (3, 8)"]],
+        ];
+
+  for (const [cmd, testArgs] of candidates) {
+    const res = spawnSync(cmd, testArgs, { stdio: "ignore", windowsHide: true });
+    if (res.status === 0) {
+      const prefixArgs = cmd === "py" ? ["-3"] : [];
+      const verRes = spawnSync(cmd, [...prefixArgs, "--version"], {
+        encoding: "utf-8",
+        windowsHide: true,
+      });
+      const ver = ((verRes.stdout || "") + (verRes.stderr || "")).trim();
+      return { cmd, prefixArgs, version: ver };
+    }
+  }
+  return null;
+}
+
+function copyTreeClean(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const item of COPY_ITEMS) {
+    const s = path.join(srcDir, item);
+    const d = path.join(destDir, item);
+    if (!fs.existsSync(s)) continue;
+    fs.cpSync(s, d, {
+      recursive: true,
+      force: true,
+      filter: (srcPath) => {
+        const base = path.basename(srcPath);
+        if (base === "__pycache__" || base === ".orch" || base === ".sandbox-skills") {
+          return false;
+        }
+        if (base.endsWith(".pyc")) return false;
+        return true;
+      },
+    });
+  }
+}
+
+function stamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function cmdInstall(args) {
+  let homeDir = os.homedir();
+  let dryRun = false;
+  let noBackup = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--dry-run") dryRun = true;
+    else if (args[i] === "--no-backup") noBackup = true;
+    else if (args[i] === "--home" && args[i + 1]) {
+      homeDir = path.resolve(args[++i]);
+    }
+  }
+
+  const py = findPython();
+  if (!py) {
+    console.error("[agent-orchestration] ERROR: Python >= 3.8 is required on PATH.");
+    process.exit(1);
+  }
+
+  const targets = defaultTargets(homeDir);
+  const backupRoot = path.join(homeDir, ".agent-orchestration-backups");
+  const stateDir = process.env.AO_HOME || path.join(homeDir, ".agent-orchestration");
+  const ts = stamp();
+
+  for (const t of targets) {
+    if (fs.existsSync(t) && !noBackup) {
+      const relSlug = path
+        .relative(homeDir, t)
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/^_|_$/g, "");
+      const bdest = path.join(backupRoot, `${relSlug}-${ts}`);
+      console.log(`backup  ${t} -> ${bdest}`);
+      if (!dryRun) {
+        fs.mkdirSync(backupRoot, { recursive: true });
+        fs.cpSync(t, bdest, { recursive: true, force: true });
+      }
+    }
+    console.log(`install ${t}`);
+    if (!dryRun) {
+      fs.rmSync(t, { recursive: true, force: true });
+      copyTreeClean(ROOT_DIR, t);
+    }
+  }
+
+  console.log(`state   ${stateDir}`);
+  if (!dryRun) {
+    fs.mkdirSync(stateDir, { recursive: true });
+    const discoverScript = path.join(targets[1], "scripts", "discover.py");
+    if (fs.existsSync(discoverScript)) {
+      spawnSync(py.cmd, [...py.prefixArgs, discoverScript, "--quick"], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    }
+  }
+  console.log("Done. Restart Claude Code, Codex CLI, and Antigravity (agy) to reload the skill.");
+}
+
+function cmdUninstall(args) {
+  let homeDir = os.homedir();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--home" && args[i + 1]) {
+      homeDir = path.resolve(args[++i]);
+    }
+  }
+  for (const t of defaultTargets(homeDir)) {
+    if (fs.existsSync(t)) {
+      fs.rmSync(t, { recursive: true, force: true });
+      console.log(`removed ${t}`);
+    }
+  }
+}
+
+function cmdDoctor() {
+  console.log("=== agent-orchestration Doctor ===");
+  console.log(`Node.js : ${process.version} (${process.platform}/${process.arch})`);
+  const py = findPython();
+  console.log(`Python  : ${py ? `${py.version} (${py.cmd})` : "NOT FOUND"}`);
+
+  const homeDir = os.homedir();
+  console.log("\nSkill Install Targets:");
+  for (const t of defaultTargets(homeDir)) {
+    const ok = fs.existsSync(path.join(t, "SKILL.md"));
+    console.log(`  [${ok ? "OK" : "--"}] ${t}`);
+  }
+
+  if (py) {
+    console.log("\nLive Models & Hardware Probe:");
+    const routeScript = path.join(ROOT_DIR, "scripts", "route.py");
+    spawnSync(py.cmd, [...py.prefixArgs, routeScript, "--list-models"], {
+      stdio: "inherit",
+      windowsHide: true,
+    });
+  }
+}
+
+function forwardPython(scriptName, prefixScriptArgs, passArgs) {
+  const py = findPython();
+  if (!py) {
+    console.error("[agent-orchestration] ERROR: Python >= 3.8 is required.");
+    process.exit(1);
+  }
+  const scriptPath = path.join(ROOT_DIR, "scripts", scriptName);
+  const res = spawnSync(py.cmd, [...py.prefixArgs, scriptPath, ...prefixScriptArgs, ...passArgs], {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  process.exit(res.status ?? 1);
+}
+
+function printHelp() {
+  console.log(`agent-orchestration — Multi-Agent Orchestration Skill & CLI Engine
+
+Usage:
+  npx github:haulth/agent-orchestration [install] [--dry-run] [--no-backup] [--home <dir>]
+  npx github:haulth/agent-orchestration doctor
+  npx github:haulth/agent-orchestration uninstall
+  npx github:haulth/agent-orchestration route [args...]
+  npx github:haulth/agent-orchestration anatomy <init|settle|audit|amend|inspect> [args...]
+  npx github:haulth/agent-orchestration <run|batch|verdict|stats> [args...]
+  npx github:haulth/agent-orchestration sandbox <check|search|install|list|remove|purge> [args...]
+  npx github:haulth/agent-orchestration discover [--quick]
+
+Also compatible with Agent Skills CLI:
+  npx skills add haulth/agent-orchestration`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv[0] || "install";
+const rest = argv.slice(1);
+
+if (sub === "-h" || sub === "--help" || sub === "help") {
+  printHelp();
+} else if (sub === "install" || sub.startsWith("--")) {
+  cmdInstall(sub === "install" ? rest : argv);
+} else if (sub === "uninstall") {
+  cmdUninstall(rest);
+} else if (sub === "doctor") {
+  cmdDoctor();
+} else if (sub === "route") {
+  forwardPython("route.py", [], rest);
+} else if (sub === "anatomy") {
+  forwardPython("anatomy.py", [], rest);
+} else if (sub === "sandbox") {
+  forwardPython("skill_sandbox.py", [], rest);
+} else if (sub === "discover") {
+  forwardPython("discover.py", [], rest);
+} else if (["run", "batch", "verdict", "stats"].includes(sub)) {
+  forwardPython("agent_run.py", [sub], rest);
+} else {
+  printHelp();
+  process.exit(1);
+}

package/install/CAI-DAT.md

@@ -0,0 +1,51 @@
+# Cài đặt skill agent-orchestration (v2)
+
+## Yêu cầu
+- Python 3 (chỉ dùng thư viện chuẩn). Cần cho `agent_run.py`, `route.py`, `discover.py`.
+- Các CLI bạn muốn dùng làm worker: `codex`, `agy`, `claude`. Không có cái nào thì `route.py` tự bỏ qua vendor đó.
+  - `claude` đi kèm ứng dụng Claude desktop, có thể không nằm trong PATH; runner tự tìm ở `%APPDATA%\Claude\claude-code\<phiên bản>\claude.exe`.
+
+## Cài
+Windows (PowerShell), từ thư mục skill:
+```powershell
+.\install\install.ps1 -DryRun    # xem trước
+.\install\install.ps1            # cài thật
+```
+macOS / Linux: `./install/install.sh [--dry-run]`.
+
+Script sẽ:
+1. sao lưu bản cũ (nếu có) vào `~/.agent-orchestration-backups/`;
+2. chép skill (không kèm `install/`, `tests/`) vào:
+   - `~/.claude/skills/agent-orchestration` (Claude Code),
+   - `~/.agents/skills/agent-orchestration` (Codex, Windsurf/Devin),
+   - `~/.gemini/config/skills/agent-orchestration` (agy);
+3. tạo `~/.agent-orchestration/` (thư mục trạng thái dùng chung, vô hại nếu đã có);
+4. cảnh báo nếu thiếu Python.
+
+Sau đó **khởi động lại Claude Code, Codex và agy** để chúng nạp lại skill.
+
+## Thư mục trạng thái `~/.agent-orchestration/`
+| File | Nội dung |
+|---|---|
+| `ledger.jsonl` | mỗi lần chạy và mỗi phán quyết của manager (dữ liệu cho tự chủ theo thành tích) |
+| `capabilities.json` / `capabilities.md` | ảnh chụp khả năng từng agent / bản đọc nhanh |
+| `changes.md` | nhật ký thay đổi (chỉ thêm vào cuối) |
+| `candidates.json` | model mới phát hiện, chưa được duyệt |
+| `state.json` | lần kiểm tra nhanh gần nhất |
+
+Đổi vị trí bằng biến môi trường `AO_HOME`.
+
+## Cập nhật bảng model
+1. Sửa `assets/models.json` (bậc `fast/standard/frontier/frontier_max` cho từng vendor, và bảng `tasks`).
+2. Cập nhật bảng phản chiếu trong `references/gates-and-routing.md`.
+3. Chạy lại `install.ps1` để đồng bộ sang 3 bản cài.
+
+Model mới do `discover.py` phát hiện nằm ở `candidates.json`; chỉ đưa vào bước 1 sau khi bạn đồng ý hoặc sau một lần chạy thử có đo đạc.
+
+## Kiểm tra nhanh sau khi cài
+```powershell
+python scripts\route.py --list-models
+python scripts\route.py --task-type review --builder codex
+python scripts\route.py --task-type design --manager agy --same-model
+```
+Các lệnh kiểm tra chạy hoàn toàn cục bộ, không tốn token.

package/install/install.ps1

@@ -0,0 +1,63 @@
+# Installs the skill into the four places the harnesses read, backing up old copies first.
+#   .\install.ps1              install for real
+#   .\install.ps1 -DryRun      show what would happen
+#   .\install.ps1 -HomeDir X   use X instead of %USERPROFILE% (for testing)
+param([switch]$DryRun, [string]$HomeDir = $env:USERPROFILE)
+$ErrorActionPreference = "Stop"
+$HomeDir = $HomeDir.TrimEnd('\', '/')
+$src = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+if (-not (Test-Path (Join-Path $src "SKILL.md"))) { throw "SKILL.md not found in $src" }
+$name = "agent-orchestration"
+$targets = @(
+  (Join-Path $HomeDir ".claude\skills\$name"),          # Claude Code
+  (Join-Path $HomeDir ".agents\skills\$name"),          # Codex CLI, Cursor, Windsurf, portable Agent Skills root
+  (Join-Path $HomeDir ".codex\skills\$name"),           # Codex CLI legacy/native root
+  (Join-Path $HomeDir ".gemini\config\skills\$name")    # Antigravity CLI (agy)
+)
+$backupRoot = Join-Path $HomeDir ".agent-orchestration-backups"
+$state = Join-Path $HomeDir ".agent-orchestration"
+$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+
+$pyCmd = $null
+foreach ($cand in @("python", "py", "python3")) {
+  if (Get-Command $cand -ErrorAction SilentlyContinue) {
+    $argsCheck = if ($cand -eq "py") { @("-3", "-c", "import sys; assert sys.version_info >= (3,8)") } else { @("-c", "import sys; assert sys.version_info >= (3,8)") }
+    & $cand @argsCheck 2>$null
+    if ($LASTEXITCODE -eq 0) { $pyCmd = $cand; break }
+  }
+}
+if (-not $pyCmd) {
+  Write-Warning "Working Python >= 3.8 was not found on PATH. agent_run.py, route.py, anatomy.py and discover.py need Python 3 (stdlib only)."
+}
+
+foreach ($t in $targets) {
+  if (Test-Path $t) {
+    $tag = ($t.Substring($HomeDir.Length) -replace '[^A-Za-z0-9]+','_').Trim('_')
+    $b = Join-Path $backupRoot "$tag-$stamp"
+    Write-Host "backup  $t -> $b"
+    if (-not $DryRun) {
+      New-Item -ItemType Directory -Force $backupRoot | Out-Null
+      Copy-Item $t $b -Recurse -Force
+    }
+  }
+  Write-Host "install $t"
+  if (-not $DryRun) {
+    New-Item -ItemType Directory -Force $t | Out-Null
+    # Use /MIR so even if the target directory is a shell's current working directory on Windows, contents sync cleanly
+    robocopy $src $t /MIR /XD tests node_modules __pycache__ .orch .sandbox-skills .git /XF *.pyc .gitignore package-lock.json /NFL /NDL /NJH /NJS /NP | Out-Null
+    if ($LASTEXITCODE -ge 8) { throw "robocopy failed ($LASTEXITCODE) for $t" }
+  }
+}
+Write-Host "state   $state"
+if (-not $DryRun) {
+  New-Item -ItemType Directory -Force $state | Out-Null
+  if ($pyCmd) {
+    $disc = Join-Path $targets[1] "scripts\discover.py"
+    if (Test-Path $disc) {
+      if ($pyCmd -eq "py") { & py -3 $disc --quick 2>$null | Out-Null }
+      else { & $pyCmd $disc --quick 2>$null | Out-Null }
+    }
+  }
+}
+Write-Host "Done. Restart Claude Code, Codex and agy so they reload the skill."
+$global:LASTEXITCODE = 0

package/install/install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Installs the skill into the four places the harnesses read, backing up old copies first.
+#   ./install.sh [--dry-run] [--home DIR]
+set -euo pipefail
+DRY=0; HOME_DIR="${HOME%/}"
+while [ $# -gt 0 ]; do case "$1" in --dry-run) DRY=1;; --home) HOME_DIR="${2%/}"; shift;; *) echo "unknown arg $1"; exit 2;; esac; shift; done
+SRC="$(cd "$(dirname "$0")/.." && pwd)"; NAME=agent-orchestration
+[ -f "$SRC/SKILL.md" ] || { echo "SKILL.md not found in $SRC"; exit 1; }
+STAMP="$(date +%Y%m%d-%H%M%S)"; BK="$HOME_DIR/.agent-orchestration-backups"
+PY=""
+for C in python3 python; do
+  if command -v "$C" >/dev/null 2>&1 && "$C" -c "import sys; assert sys.version_info >= (3,8)" >/dev/null 2>&1; then
+    PY="$C"; break
+  fi
+done
+[ -n "$PY" ] || echo "warning: Python >= 3.8 not found; the scripts need Python 3 (stdlib only)"
+for T in "$HOME_DIR/.claude/skills/$NAME" "$HOME_DIR/.agents/skills/$NAME" "$HOME_DIR/.codex/skills/$NAME" "$HOME_DIR/.gemini/config/skills/$NAME"; do
+  if [ -e "$T" ]; then
+    TAG="$(echo "${T#$HOME_DIR}" | tr -c 'A-Za-z0-9' '_' | sed -E 's/^_+//; s/_+$//')"
+    B="$BK/$TAG-$STAMP"; echo "backup  $T -> $B"
+    [ $DRY = 1 ] || { mkdir -p "$BK"; cp -R "$T" "$B"; rm -rf "$T"; }
+  fi
+  echo "install $T"
+  if [ $DRY = 0 ]; then
+    mkdir -p "$T"
+    (cd "$SRC" && tar --exclude='tests' --exclude='node_modules' --exclude='__pycache__' --exclude='.orch' --exclude='.sandbox-skills' --exclude='.git' --exclude='package-lock.json' --exclude='.gitignore' --exclude='*.pyc' -cf - .) | (cd "$T" && tar -xf -)
+  fi
+done
+if [ $DRY = 0 ]; then
+  mkdir -p "$HOME_DIR/.agent-orchestration"
+  if [ -n "$PY" ] && [ -f "$HOME_DIR/.agents/skills/$NAME/scripts/discover.py" ]; then
+    "$PY" "$HOME_DIR/.agents/skills/$NAME/scripts/discover.py" --quick >/dev/null 2>&1 || true
+  fi
+fi
+echo "Done. Restart Claude Code, Codex and agy so they reload the skill."

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "agent-orchestration-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Multi-agent orchestration skill & CLI engine for Claude Code, Codex CLI, and Antigravity (agy) with Orchestration Anatomy, Keyhole Interlocks, Dynamic Model Routing, and Ephemeral Skill Sandbox.",
+  "license": "MIT",
+  "author": "haulth",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haulth/agent-orchestration.git"
+  },
+  "homepage": "https://github.com/haulth/agent-orchestration#readme",
+  "bugs": {
+    "url": "https://github.com/haulth/agent-orchestration/issues"
+  },
+  "bin": {
+    "agent-orchestration-skill": "bin/cli.mjs",
+    "agent-orchestration": "bin/cli.mjs",
+    "ao-skill": "bin/cli.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "CATALOG.md",
+    "README.md",
+    "LICENSE",
+    "bin/*.mjs",
+    "scripts/*.py",
+    "references/**/*.md",
+    "assets/*.json",
+    "install/*"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "codex",
+    "antigravity",
+    "agy",
+    "multi-agent",
+    "orchestration",
+    "anatomy"
+  ]
+}

package/references/adapters/antigravity-cli.md

@@ -0,0 +1,32 @@
+# Adapter: Antigravity (`agy` CLI & Native Subagents)
+
+## Quick card
+- **Native subagents (preferred when Antigravity is the manager or the ONLY agent on the machine):**
+  - Use `define_subagent(Name="...", Description="...", SystemPrompt="...", EnableWriteTools=False)` to create specialized domain lenses (e.g., `First-Principles Architect`, `Adversarial Red-Team Falsifier`, `Pragmatic Minimalist`, `Runtime Engineer`).
+  - Call `invoke_subagent(TypeName="self"|"research"|"<custom>", Role="...", Prompt="<Zero-Prior Brief>", Model="inherit"|"flash"|"pro", Workspace="inherit"|"branch"|"share")` in parallel (2–4 sub-agents in one turn) so each explores the problem with a **clean KV-cache (0 prior conversation bias)**.
+  - Use `send_message(Recipient="<conversationId>", Message="...")` to continue a subagent or let agents exchange targeted follow-ups with zero cold-start overhead.
+  - Use `Workspace: "branch"` or `"share"` when running parallel writers/prototypes so each sub-agent works in an isolated branch/worktree without conflicting!
+- **Single-Host Routing (`--single-host`):**
+  - `python <skill>/scripts/route.py --task-type design --manager agy --single-host`
+  - `python <skill>/scripts/route.py --task-type review --builder agy --manager agy --single-host` (automatically switches from Google `gemini-4-argon-high` to Anthropic `claude-opus-5-5-high` hosted inside `agy`!).
+- **External CLI read-only:** `python <skill>/scripts/agent_run.py run --agent agy --brief brief.md --mode read --model gemini-4-argon-high`
+- **External CLI write, with scope:** add `--mode write --may-write src/foo/ docs/x.md`. Anything changed outside that list is reported in `meta.json` `violations`.
+- **Direct artifact handoff:** add `--context-file <upstream_artifact_path>` so the worker reads upstream findings first-hand.
+- **Resume:** `--resume <conversation_id>` (from `meta.json` `session_id`).
+- **Measured overhead (CLI):** a trivial CLI call costs about 19.5–22k tokens. Use native `invoke_subagent` for small in-session tasks, and `agent_run.py --agent agy` when calling from Codex/Claude or when you want headless schema-checked runs.
+
+## Models on this machine (`agy models`, updated 2026-10-24, `agy 1.4.4`)
+- **Google family:**
+  - Frontier: `gemini-4-argon-high`
+  - Standard: `gemini-4-argon-medium`, `gemini-3.8-flash-high`
+  - Fast: `gemini-3.8-flash-low`, `gemini-4-argon-low`
+- **Anthropic family (hosted on `agy`):**
+  - Frontier Max / Frontier: `claude-opus-5-5-high`, `claude-opus-5-5-medium`, `claude-sonnet-5-5-high`
+  - Standard: `claude-sonnet-5-5-medium`
+- **Open-weights:** `gpt-oss-120b-medium`
+- Note: `gemini-3.1-pro-*` and `gemini-3.6/3.7-*` were retired in `agy 1.4.4`. `assets/models.json` maps `standard` → `gemini-4-argon-medium`, `frontier` → `gemini-4-argon-high`, and `frontier_max` → `claude-opus-5-5-high`.
+
+## Headless CLI permissions & pitfalls
+- Headless print mode (`agy -p`) cannot prompt, so any tool that needs confirmation is auto-denied. `agent_run.py` counts `auto-denied` in stderr and maps empty responses with denials to `permission`.
+- Name exact absolute file paths in the brief (or pass `--context-file <path>`), as `agent_run.py` automatically passes `--add-dir` for the attempt folder.
+- With `--json-schema`, `agy` returns `structured_output` alongside `response`. `agent_run.py` prefers `structured_output` and strips injected `toolAction`/`toolSummary` keys automatically.

package/references/adapters/claude-code.md

@@ -0,0 +1,60 @@
+# Adapter: Claude Code (Native Subagents & `claude` CLI 2.1.308+)
+
+## Quick card
+### 1. Calling Claude CLI (`claude -p`) as a Worker from ANY Manager (Codex, Antigravity, or Shell)
+- **Read-only audit / review / architecture consult:**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent claude --brief brief.md --name arch-review \
+         --task-type review --tier frontier --mode read [--context-file .orch/spec.md]
+  ```
+- **Fast cold-start mode (`--bare`) & hard USD budget cap (`--max-budget-usd`):**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent claude --brief brief.md --name fast-check \
+         --task-type lookup --tier fast --mode read --bare --max-budget-usd 0.25
+  ```
+- **Scoped write (or isolated Git Worktree `--worktree`):**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent claude --brief brief.md --name impl-ui \
+         --task-type implement --tier standard --mode write --may-write src/ui/ [--worktree]
+  ```
+- **Resume an existing session:**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent claude --brief delta.md --resume <session_id>
+  ```
+
+### 2. Claude Code as the In-Session Manager
+- **Read-only worker:** `Agent(subagent_type: "Explore" | "general-purpose", model: "haiku"|"sonnet"|"opus", prompt: <brief>)`
+- **Isolated write worker:** `Agent(subagent_type: "general-purpose", model: "sonnet", isolation: "worktree", prompt: <brief>)`
+- **Resume / Direct Follow-up:** `SendMessage(to: "<agent_id>", message: "<delta>")`
+
+---
+
+## Dynamic Model Discovery (`discover.py` & `route.py`)
+`discover.py` automatically discovers all models available to your Claude Code installation without spending tokens by scanning:
+1. **`~/.claude/settings.json` (`env`):** Custom gateway/proxy models such as `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL` (`nghi/claude-opus-5[1m]`), `ANTHROPIC_DEFAULT_SONNET_MODEL` (`nghi/claude-sonnet-5[1m]`), `ANTHROPIC_SMALL_FAST_MODEL` (`claude-haiku-5-5`).
+2. **`~/.claude/cache/gateway-models.json`:** All models advertised by your configured gateway (`nghi/claude-opus-5[1m]`, `nghi/claude-sonnet-5[1m]`, `nghi/claude-opus-4.8[1m]`, `nghi/claude-haiku-4.5[1m]`, etc.).
+3. **`~/.claude/cache/model-catalog/*-ccd.json`:** Official Claude Code catalog (`claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-1`, `claude-haiku-5-5` with 1M context window metadata and effort levels `low|medium|high|xhigh|max`).
+
+`route.py` scores these live discovered models (`ao_common.dynamic_tier_config`) and automatically selects the best model per tier (`fast`, `standard`, `frontier`, `frontier_max`), falling back to `assets/models.json` only if no local cache exists.
+
+---
+
+## Power Native Claude CLI Commands (2.1.308+)
+
+| Capability | Command / Flag | When to use |
+|---|---|---|
+| **Fast Minimal Mode (`--bare`)** | `agent_run.py run --agent claude ... --bare`<br>(or `claude -p --bare ...`) | Skips hooks, LSP, plugin sync, auto-memory, and `CLAUDE.md` auto-discovery for ultra-fast, low-overhead worker execution (uses `ANTHROPIC_API_KEY` / settings helper). |
+| **Isolated Git Worktree (`-w`, `--worktree`)** | `agent_run.py run --agent claude ... --worktree`<br>(or `claude -p --worktree <name> ...`) | Runs the worker in a fresh git worktree so parallel writers never collide. |
+| **Hard Cost Cap (`--max-budget-usd`)** | `agent_run.py run --agent claude ... --max-budget-usd 0.50` | Enforces a strict dollar ceiling on API calls in `--print` mode. |
+| **Background Daemon Sessions (`--bg`)** | `claude --bg -p "<prompt>"`<br>`claude agents` / `claude logs <id>` / `claude stop <id>` | Launch long-running background agents, inspect their live logs, attach to them, or stop them. |
+| **Cloud Multi-Agent Review (`ultrareview`)** | `claude ultrareview [PR_or_branch]` | Run a cloud-hosted multi-agent code review on the current branch or a PR. |
+| **Custom Inline Agent Definitions (`--agents`)** | `claude -p --agents '{"auditor": {"description": "...", "prompt": "..."}}' --agent auditor` | Define specialized worker roles on the fly without editing `.claude/agents/`. |
+| **Fork on Resume (`--fork-session`)** | `claude -p --resume <id> --fork-session` | Branch an existing conversation into a new session ID to test an alternative approach without mutating the original thread. |
+
+## Raw Headless Command (`claude -p`)
+```bash
+claude -p --output-format json --permission-mode plan --model "nghi/claude-opus-5[1m]" --effort high \
+       [--bare] [--worktree] [--max-budget-usd 1.00] [--resume <session_id>] \
+       [--add-dir <dir>] [--allowedTools "Read,Grep,Glob"] \
+       --json-schema '<schema_json>' < brief.md
+```

package/references/adapters/codex-cli.md

@@ -0,0 +1,53 @@
+# Adapter: Codex CLI (`codex` 0.154.0+)
+
+## Quick card (Unified Runner — Preferred)
+- **Read-only audit / debug / review:**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent codex --brief brief.md --name audit-core \
+         --task-type review --tier frontier --mode read [--context-file .orch/spec.md] [--search]
+  ```
+- **Write, with scoped attribution (or isolated Git Worktree):**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent codex --brief brief.md --name impl-feature \
+         --task-type implement --tier standard --mode write --may-write src/foo/ [--worktree]
+  ```
+- **Resume an existing session (~1.5k tokens vs ~12.5k cold start):**
+  ```bash
+  python <skill>/scripts/agent_run.py run --agent codex --brief delta.md --resume <session_id>
+  ```
+- **Batch execution (parallel readers first, then sequential writers):**
+  ```bash
+  python <skill>/scripts/agent_run.py batch plan.json --wip 3
+  ```
+
+## Dynamic Model Discovery (`discover.py` & `route.py`)
+Models are **never locked to stale hardcoded strings**. `discover.py` automatically scans:
+1. `~/.codex/.codex-global-state.json` (live `composer-recent-model-configurations-v1` and `seen-model-upgrade-list`, e.g. `gpt-6-astra`, `gpt-6.1-sol`, `gpt-5.6-sol`, `gpt-5.6-terra`),
+2. `~/.codex/models_cache.json`,
+3. `~/.codex/skills/.system/openai-docs/references/latest-model.md` (`gpt-5.6`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.3-codex`, `gpt-5.1-codex-mini`),
+4. `~/.codex/config.toml` (`model = "..."`).
+
+`route.py` scores all live discovered models (`ao_common.dynamic_tier_config`) and automatically picks the strongest fit for `fast`, `standard`, `frontier`, and `frontier_max` (`source: dynamic_discovered`), falling back to `assets/models.json` only if no local state exists.
+
+## Power Native Codex CLI Commands (0.154.0)
+
+| Capability | Command / Flag | When to use |
+|---|---|---|
+| **Built-in Non-Interactive Code Review** | `codex review --uncommitted [PROMPT]`<br>`codex review --base <BRANCH> [PROMPT]`<br>`codex review --commit <SHA> [PROMPT]` | Fast, zero-ceremony second opinion on uncommitted diffs, a feature branch, or a specific commit. |
+| **Isolated Git Worktree** | `agent_run.py run --agent codex ... --worktree`<br>(or raw `codex exec --worktree ...`) | Run parallel writers safely in a managed git worktree without dirtying the main working tree. |
+| **Live Web Search** | `agent_run.py run --agent codex ... --search`<br>(or raw `codex exec --search ...`) | Enable native `web_search` tool without per-call approval prompts during research/explore tasks. |
+| **Multimodal Image Input** | `codex exec -i screenshot.png - < brief.md` | Attach UI screenshots, architecture diagrams, or plots directly to the prompt. |
+| **Apply Latest Agent Diff** | `codex apply` | Apply the latest diff produced by a Codex session via `git apply`. |
+| **Native Subagents** | `spawn_agent` (with roles in `~/.codex/agents/*.toml`) | Cheap in-session delegation when Codex itself is the top-level manager. |
+
+## Raw `codex exec` Reference (when not using `agent_run.py`)
+```bash
+codex exec -m <model> -c 'model_reasoning_effort="high"' \
+  -s read-only -C <repo> [--worktree] [--search] --skip-git-repo-check \
+  --output-schema <skill>/assets/result.schema.json -o result.json - < brief.md
+```
+
+## Parsing & Anti-Hallucination Verification
+- Read `meta.json` first:
+  - Check `ok`, `failure`, `violations`, and **`evidence_warnings`** (automatically populated by `agent_run.py` if the worker's `summary` or `assumptions_challenged` lacks verifiable `file:line` or command output anchors).
+- Then read `result.json`. Every critique or conclusion must cite concrete proof in `evidence[]`.