| name | consulting-codex |
| description | Use when deciding whether a question warrants spawning a Codex turn or you can answer locally — covers the cost/value matrix and which subagent or command is the right entry point for each kind of consultation. |
| effort | high |
| allowed-tools | Bash(autopilot-codex:*), Read |
When to consult Codex (and how)
Every Codex turn costs tokens. Per the May 2026 rate card, a single
gpt-5.4 call on autopilot averages 25–40k input + 5–10k output =
$0.10–$0.30. Multiply by 30 iterations and a runaway loop is real money.
This skill is the cost/value matrix for deciding "do I ask Codex, or do
I just answer the user".
Don't consult Codex when
- The question is trivial — a typo fix, a one-line change, a
rename. Just edit. The autopilot loop is for goals, not chores.
- The user asked a factual question about the repo — read the file
yourself, don't burn a Codex turn paraphrasing.
- The answer is already in state.json —
current_task, plan,
last_review, last_verdict are local. Use /codex-status or
/codex-next first.
- You'd be second-guessing a verdict — if the last review was
approve and you want to "double-check", don't. The verdict is the
contract.
Consult Codex (manager / architect role) when
| Kind of question | Entry point |
|---|
| "Decompose this engineering goal into tasks." | codex-manager subagent → mcp__autopilot-bridge__plan |
| "Does this diff meet the current task's acceptance contract?" | codex-reviewer subagent → mcp__autopilot-bridge__review |
| "Is the goal achieved? If not, what next?" | Stop hook (automatic) → mcp__autopilot-bridge__verdict |
| "Should I use library X or Y for this?" (one-shot architectural) | codex-planner subagent (haiku, no state mutation) |
| "Re-plan from scratch — original plan exhausted but goal not met." | /codex-plan <revised goal> |
How to ask well
Codex's prompts (in lib/prompts.mjs) embed:
- The user's goal
- CLAUDE.md, AGENTS.md, README head, repo listing
- Schema constraints (plan / review / verdict)
That's already enough for most calls. Don't add to the prompt unless
you're sure — extra context is extra tokens, and Codex's role-specific
prompts are tuned to deny shell / MCP / file I/O. Adding hints can break
that framing.
Cost-aware patterns
- Use
gpt-5.4 (default) for plan / review / verdict. gpt-5.5 is
twice the price for marginal quality on these structured tasks.
- Use
gpt-5.4-mini or haiku for codex-planner one-shot questions
— they're $0.50/$2 per 1M tokens; an architectural opinion costs
pennies.
- Set
--budget USD on /autopilot to cap a session. The
budget-guard.mjs check hook flips status to stopped_budget once
spend ≥ cap. See safety-rails skill.
What Codex must NOT do
The bridge prompts explicitly forbid Codex from:
- Executing shell commands.
- Calling MCP tools.
- Reading or writing files via tools.
Codex's only output is the structured JSON for plan / review / verdict.
If a Codex response includes shell commands or "I'll just run X" — that's
prompt drift; the bridge's validateXxxShape will reject the output and
the autopilot will surface a clean error to the user.
Conversation continuity
The bridge does not use codex-reply or --resume. Each call
spawns a fresh codex exec process. Continuity is achieved by embedding
state.json in the prompt — Codex sees the running plan, last_review,
last_verdict, recent commits in every prompt. This trades token cost
for reproducibility: every turn is replayable from the prompt log.
