multi-model-dispatch

What this skill does

# Multi-Model Dispatch

This skill teaches Claude Code how to correctly invoke Codex and Gemini CLIs for independent review of artifacts. Use this whenever a pipeline step needs multi-model validation at depth 4-5.

## When This Skill Activates

- A review or validation step is running at depth 4+ and wants independent model validation
- User asks to "run multi-model review" or "get a second opinion from Codex/Gemini"
- The `automated-pr-review` step is using local CLI review mode
- The `implementation-plan-review` step dispatches to external CLIs at depth 4+

## CLI Detection & Auth Verification

Before attempting any dispatch, detect what's available AND verify authentication. A CLI that's installed but not authenticated is useless in headless mode — it will hang on an interactive auth prompt or fail silently.

### Step 1: Check CLI Installation

```bash
command -v codex && echo "codex installed" || echo "codex not found"
command -v gemini && echo "gemini installed" || echo "gemini not found"
```

### Step 2: Verify Authentication

**CRITICAL: Do not skip this step.** Auth tokens expire mid-session. A CLI that worked 30 minutes ago may fail now.

**CRITICAL: Previous auth failures do NOT exempt subsequent dispatches.** Auth tokens refresh — a CLI that failed auth during user story review may work fine for domain modeling review. Always re-check auth before EACH review step, not once per session.

**Codex auth check** (has a built-in status command):
```bash
codex login status 2>/dev/null && echo "codex authenticated" || echo "codex NOT authenticated"
```

**Gemini auth check** (no built-in status command — use a minimal prompt):
```bash
GEMINI_AUTH_CHECK=$(NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1)
GEMINI_EXIT=$?
if [ "$GEMINI_EXIT" -eq 0 ]; then
  echo "gemini authenticated"
elif [ "$GEMINI_EXIT" -eq 41 ]; then
  echo "gemini NOT authenticated (exit 41: auth error)"
else
  echo "gemini auth unknown (exit $GEMINI_EXIT)"
fi
```

**Why `NO_BROWSER=true`?** Gemini CLI relaunches itself as a child process for memory management. During the relaunch, it shows a "Do you want to continue? [Y/n]" consent prompt that hangs when stdin is not a TTY (as in Claude Code's Bash tool). `NO_BROWSER=true` suppresses this prompt and uses cached credentials directly.

### Step 3: Handle Auth Failures

**If a CLI fails auth, do NOT silently fall back.** Instead:

1. **Tell the user** which CLI failed auth and why
2. **Offer interactive recovery**: Ask the user to run the auth command in their terminal:
   - **Codex**: `! codex login` (opens browser for OAuth) or set `CODEX_API_KEY` env var
   - **Gemini**: `! gemini -p "hello"` (triggers OAuth flow) or set `GEMINI_API_KEY` env var
3. **After recovery**: Re-run the auth check. If it passes, proceed with dispatch.
4. **If user declines**: Fall back to the other CLI or Claude-only review, but **document the auth failure** in the review summary.

The `!` prefix runs the command in the user's terminal session, allowing interactive auth flows (browser OAuth, Y/n prompts) that can't work in headless mode.

**If neither CLI is available or authenticated**: Queue a compensating Claude pass focused on the failed channel's strength area. Document this as "single-model review (no external CLIs available)."

## Correct Invocation Patterns

### Codex CLI (`codex exec`)

**CRITICAL: Use `codex exec`, NOT `codex` directly.** The bare `codex` command launches an interactive TUI that requires a TTY and will fail with "stdin is not a terminal" when run from Claude Code.

**CRITICAL: Always include `--skip-git-repo-check`.** Without this flag, Codex fails with "Not inside a trusted directory" when the project hasn't initialized git yet (common early in the pipeline).

```bash
# Basic review dispatch
codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT_HERE" 2>/dev/null

# With specific model and reasoning effort
codex exec --skip-git-repo-check -m o4-mini -s read-only -c model_reasoning_effort=high --ephemeral "REVIEW_PROMPT_HERE" 2>/dev/null

# Reading prompt from stdin (use - flag)
echo "$REVIEW_PROMPT" | codex exec --skip-git-repo-check -s read-only --ephemeral - 2>/dev/null

# With JSON schema enforcement
codex exec --skip-git-repo-check -s read-only --ephemeral --output-schema schema.json "REVIEW_PROMPT_HERE" 2>/dev/null
```

**Key flags:**
| Flag | Purpose |
|------|---------|
| `exec` | **Required** — headless mode, no TUI, no TTY needed |
| `--skip-git-repo-check` | **Required** — allows running outside a git repo or untrusted directory |
| `-s read-only` | Sandbox: reviewer cannot write files (read-only analysis) |
| `--ephemeral` | Don't persist session (one-shot review) |
| `2>/dev/null` | Suppress thinking tokens on stderr (keeps Claude Code context clean) |
| `--output-schema` | Enforce structured JSON output against a schema file |
| `-c model_reasoning_effort=high` | Increase reasoning depth for complex reviews |

**Output**: Progress streams to stderr (suppressed by `2>/dev/null`). Final answer prints to stdout.

### Gemini CLI (`gemini -p`)

**Use `-p` / `--prompt` for headless mode.** Without this flag, Gemini launches interactive mode.

**CRITICAL: Always prepend `NO_BROWSER=true`.** Without this, Gemini's child process relaunch shows a consent prompt ("Do you want to continue? [Y/n]") that hangs when stdin is not a TTY. This affects ALL non-interactive contexts including Claude Code's Bash tool.

```bash
# Basic review dispatch
NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" --output-format json --approval-mode yolo 2>/dev/null

# With specific model
NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" -m pro --output-format json --approval-mode yolo 2>/dev/null

# Reading context from stdin
cat artifact.md | NO_BROWSER=true gemini -p "Review this artifact for issues" --output-format json --approval-mode yolo 2>/dev/null

# With sandbox (no file writes)
NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" --output-format json -s --approval-mode yolo 2>/dev/null
```

**Key flags:**
| Flag | Purpose |
|------|---------|
| `NO_BROWSER=true` | **Required** — suppresses consent prompt that hangs in non-TTY shells |
| `-p "prompt"` | **Required** — headless mode, no interactive UI |
| `--output-format json` | Structured JSON output for parsing |
| `--approval-mode yolo` | Auto-approve all tool calls (reviewer doesn't need to write) |
| `-s` | Sandbox mode (extra safety for read-only review) |
| `-m pro` | Use Gemini Pro model (default is auto) |
| `2>/dev/null` | Suppress progress output |

**Output**: JSON on stdout with `{ response, stats, error }` structure.

## Foreground-Only Execution

Always run Codex and Gemini CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`. Background execution produces empty or truncated output from both CLIs. Multiple foreground calls in a single message are fine — the tool runner supports parallel invocations.

This means: when dispatching reviews, make each CLI call a separate foreground Bash tool invocation. Do NOT use shell `&` or background subshells.

## Context Bundling

When dispatching a review, bundle all relevant context into the prompt. Each CLI gets the same bundle — do NOT share one model's review with the other.

### Template for Artifact Review

```
You are reviewing a project artifact for quality issues. Report all P0, P1, P2, and P3 findings; the project's fix threshold is applied downstream.

## Severity Definitions
- P0: Will cause implementation failure, data loss, security vulnerability, or fundamental architectural flaw
- P1: Will cause bugs in normal usage, inconsistency across documents, or blocks downstream work
- P2: Improvement opportunity — style, naming, documentation, minor optimization
- P3: Personal preference, trivial nits — included so a strict project (`fix_threshold: P3`) can act on them; otherwise advisory

## Review Standards
[paste contents of docs/review-standards.md if it exists, otherwise use