/external-tools

name: external-tools
description: Delegate implementation and review tasks to external AI CLI tools (Codex, Gemini) with cross-model adversarial review
auto_activate: false
triggers:
  - "use external tools"
  - "delegate to codex"
  - "delegate to gemini"
  - "cross-model review"

External Tools Skill

Purpose

This skill delegates implementation and review tasks to external AI CLI tools (OpenAI Codex CLI, Google Gemini CLI), enabling cost savings through cheaper models and cross-model adversarial review that eliminates single-model blind spots. Three core principles govern every interaction: **one job per invocation** (an external tool implements OR reviews, never self-validates), **minimal permissions** (sandboxed execution scoped to the task's working directory with only the tool's own API key), and **the orchestrator verifies independently** (external tools report facts only, the orchestrator judges pass/fail).

---

Prerequisites

Required Tools

| Tool | Install | Auth | |------|---------|------| | OpenAI Codex CLI | `npm i -g @openai/codex` | API key or ChatGPT subscription | | Google Gemini CLI | `npm i -g @google/gemini-cli` | Google login (free 1K req/day) or API key |

Neither tool is strictly required. The skill adapts based on what is available (see Escalation Model below).

Configuration

Per-project config at `.metaswarm/external-tools.yaml` (optional -- if absent, external tools are not used):

adapters:
  codex:
    enabled: true
    model: "gpt-5.3-codex"
    timeout_seconds: 300
    sandbox: docker          # docker | platform | none
  gemini:
    enabled: true
    model: "pro"
    timeout_seconds: 300
    sandbox: docker

routing:
  default_implementer: "cheapest-available"
  escalation_order: ["codex", "gemini", "claude"]

budget:
  per_task_usd: 2.00        # circuit breaker per task
  per_session_usd: 20.00    # circuit breaker per session

Fallback Behavior

• **Both tools available**: Full cross-model delegation and review
• **One tool available**: Reduced chain with mutual review between the tool and Claude
• **No tools available**: Existing metaswarm behavior unchanged; skill is a no-op

---

Quick Reference

Health Check

# Check if Codex is installed, authenticated, and reachable
adapters/codex.sh health

# Check Gemini
adapters/gemini.sh health

Returns JSON with `status: "ready|degraded|unavailable"`.

Implement

adapters/codex.sh implement \
  --worktree "/tmp/ext-codex-task-42" \
  --prompt-file "/private/tmp/xt-abc123/prompt.md" \
  --attempt 1 \
  --timeout 300

Review

adapters/gemini.sh review \
  --worktree "/tmp/ext-codex-task-42" \
  --rubric-file "./rubrics/external-tool-review-rubric.md" \
  --spec-file "/private/tmp/xt-abc123/spec.md" \
  --timeout 300

All commands return a uniform JSON envelope with facts only (exit code, files changed, cost, duration). The orchestrator interprets results -- adapters never self-judge.

---

Workflow: Routing & Dispatch

Phase 0: Tool Discovery (Health Checks)

Before dispatching any task, the orchestrator runs health checks to determine which tools are available:

# Run health checks for all configured adapters
for adapter in adapters/*.sh; do
  result=$("$adapter" health)
  # Parse status: ready | degraded | unavailable
done

Health is checked **per task dispatch**, not just at session start. Auth tokens can expire mid-session, network conditions change, and rate limits reset. A tool that was `ready` five minutes ago may now be `unavailable`.

Build the available tools list:

available_tools = [t for t in adapters if t.health() == "ready"]

Phase 1: IMPLEMENT (External Tool or Claude)

If an external tool is selected as implementer:

1. **Create worktree** -- `git worktree add "$WORKTREE_PATH" -b "external/$TOOL/$TASK_ID"` for isolation 2. **Package context** -- Gather relevant files, spec, acceptance criteria into a prompt file in a secure temp dir (mode 700, trap cleanup). Token-budget the context to fit the model's window. 3. **Invoke** -- `safe_invoke()` with timeout wrapper; capture JSON output 4. **Scope check** -- Verify all file changes are within the declared file scope; revert any out-of-scope changes 5. **Capture output** -- Facts only: exit code, files changed, diff stats, cost, duration

If Claude is selected (escalation or no external tools), use the existing `Task()` mechanism unchanged.

Phase 2: VALIDATE (Always Orchestrator -- Unchanged)

The orchestrator independently runs all quality gates:

• `npm test` / `npx vitest run`
• `npx tsc --noEmit`
• `npx eslint <changed-files>`
• Coverage enforcement via `.coverage-thresholds.json`
• File scope verification via `git diff --name-only`

This phase is identical whether the implementer was an external tool or Claude. **Never trust the implementer's self-report.**

Phase 3: ADVERSARIAL REVIEW (Cross-Model)

The key advantage of external tools: the writer is always reviewed by a **different model**.

| Implementer | Reviewer 1 | Reviewer 2 | |-------------|-----------|-----------| | Codex | Gemini (via adapter) | Claude (via Task) | | Gemini | Codex (via adapter) | Claude (via Task) | | Claude | Codex (via adapter) | Gemini (via adapter) |

Review is invoked via the adapter's `review` command. The orchestrator reads the reviewer's raw log and evaluates it independently -- the adapter never returns a pass/fail verdict.

Phase 4: COMMIT (Unchanged)

After passing adversarial review:

1. Merge the worktree branch into the working branch 2. Clean up the worktree (`git worktree remove`) 3. Log the session for self-reflection 4. Commit with DoD verification in the commit message

---

Escalation Model (Availability-Aware)

The orchestrator adapts its escalation chain based on which tools passed their health checks.

Scenario 1: Two External Tools Available (5 attempts max)

Model A implements (attempt 1)