name: model-forge description: Pick the right model for a task and the right git strategy for the work. Use when about to dispatch a subagent, start a new feature, or unsure whether to use opus/sonnet/haiku/codex, or whether to branch/worktree/work direct. NOT for actually running the work - this only routes. disable-model-invocation: false

Model Forge

Routing reference for picking the right model and the right git strategy. Consult before any subagent dispatch or non-trivial change.

Critical Rule

ALWAYS run subagents in background (run_in_background: true) UNLESS the user explicitly asks for foreground. The main thread stays unblocked, the user can keep working, and long-running dispatches don't freeze the conversation. Foreground subagents are the exception, not the default.

Model Capability Matrix

claude-opus-4-6

Heaviest reasoning, best at multi-file architecture and critical correctness. Slowest and most expensive claude. Speed/cost: ~3-5x slower than sonnet, ~5x cost premium. Use for:

• Deep architecture design and hard refactors
• Security audits requiring full mental model
• Complex math, proofs, algorithmic correctness
• Novel problems with no clear path
• Multi-system integration design
• Critical decisions where being wrong is expensive

claude-sonnet-4-6

Balanced workhorse. Default for ~90% of work and most subagent dispatches. Speed/cost: solid throughput, mid-tier cost. Use for:

• Standard feature coding and debugging
• Research synthesis and writing
• Code review for logic and readability
• Scaffolding new modules from spec
• Most multi-step subagent tasks
• Anything you'd default to without thinking

claude-haiku-4-5

Fastest and cheapest. Capable enough for mechanical work. Speed/cost: near-instant, fraction of sonnet cost. Use for:

• File reads, scans, classification
• Transcription (youtube, audio, OCR)
• Single tool calls with no reasoning
• Grep-style searches across large trees
• Generating structured metadata from raw input
• Bulk context gathering across many files

gpt-5.4 (via codex plugin)

Adversarial engineer with different priors than claude. Mechanically excellent on focused tasks, brittle on vague ones. Extremely slow. Speed/cost: ~30x slower than sonnet (10 min vs 18s in real tests). 3-4x fewer tokens than claude on comparable work. ChatGPT Plus = 30-150 msgs/5hr window. Benchmarks: terminal-bench 77.3% vs claude 65.4%. Debate mode (claude + codex) bug detection jumps 53% → 80%. IMPORTANT: Always pass --model gpt-5.4 (or model: "gpt-5.4" in subagent config). Default model selection is unreliable - lock it explicitly every time. Use for:

• Adversarial code review (highest-ROI use case - independent priors catch what claude misses)
• Focused bug fixes with a clear spec and acceptance criteria
• Mechanical refactors to a defined pattern (85-90% success on bounded scope)
• Test coverage for existing logic (stays in lane, no scope creep)
• Maintenance batch work (deps, doc fixes, webhook changes - queue 3-5 at session start)
• Terminal/CLI workflows
• Second-opinion on completed code

Routing Decision Tree

1. Is the task trivial / single tool call / scan / transcription / classification? → haiku
2. Standard coding / research / writing / debugging / scaffolding? → sonnet (default)
3. Deep architecture / hard multi-file refactor / correctness-critical / novel? → opus
4. Adversarial bug hunt / security audit / can wait 10+ min? → codex (background only)
5. Time-sensitive (need result < 2 min)? → never codex, sonnet or haiku

Parallelism Rules

Dispatch in parallel when:

• Subtasks are independent (different dirs, different topics)
• Multiple haiku scanning unrelated paths
• Multiple sonnet researching separate questions
• Send all dispatches in a single message, collect results

Dispatch in background when:

• Long-running work (codex, opus refactor)
• User can keep working while it runs
• Result doesn't block immediate next step

Keep in main agent when:

• Small fast iterative loops (write -> test -> fix)
• Round-trip overhead exceeds task duration
• You need the tool results in your own context

Always:

• Run subagents in background (run_in_background: true) so the main thread stays unblocked
• Lock codex model explicitly to gpt-5.4 on every invocation
• Send parallel dispatches in a single message, not sequential calls

Never:

• Run parallel agents on the same files without worktrees
• Dispatch codex for anything you're watching live
• Use opus for trivial tool calls
• Run subagents in foreground when background works

Git Strategy

Direct on current branch

• Change is < 50 lines, 1-2 files
• No parallel agents, pure linear flow
• Easily reversible
• Example: fix a typo, add a small util, edit a config

Feature branch (feat/<slug>)

• Diff is large enough to bundle commits
• Single linear workstream, no overlapping agents
• Want to test/review before merging
• Example: git checkout -b feat/auth-refresh for new auth flow

Git worktree

• Multiple subagents touching overlapping files
• Want experiment isolation while main work continues
• Long-running opus/codex shouldn't dirty working tree
• Example:

  git worktree add ../project-feat-api feat/api-layer
  # dispatch sonnet into ../project-feat-api
  # main agent stays unblocked in original tree
  git merge feat/api-layer
  git worktree remove ../project-feat-api
  

Quick Reference

Codex-Specific Failure Modes

Codex is too literal. It will fulfill the exact request and break adjacent things. Real example from HN: asked to "fix compiler warnings", it made a bunch of values nullable to silence the warnings - technically correct, broke data integrity downstream.

Codex will fail at (NEVER use it for):

• UI work of any kind - layouts, components, styling, UX, design judgment. Codex has zero taste and no eye for visual hierarchy. Always claude.
• Anything you need to discuss - "yo i need to talk about this", brainstorming, exploration, "what do you think", trade-off conversations. Codex is a one-shot executor, not a collaborator. Always claude.
• Reading user intent - "make it better" → won't make leaps, will pick the most literal interpretation
• Architecture/product judgment - no sense of tradeoffs beyond what's written
• Obscure libraries - hallucinates rather than admitting unknown
• Multi-file dependency chains - gets stuck in circles
• Continuous conversation context - context degrades fast, not built for back-and-forth

Codex will excel at:

• Tasks where being literal is a feature (test writing, mechanical refactors)
• Clearly-bounded specs with acceptance criteria
• Adversarial passes with explicit focus arguments

Prompt requirements for codex:

• One concern per prompt (don't bundle)
• Explicit scope boundaries (which files, what behavior, what done looks like)
• Structured sections: General → Autonomy → Code Implementation → Editing Constraints → Exploration → Plan Tool
• Use the positional focus argument: /codex:adversarial-review challenge whether this caching design was right
• Heavy XML structure beats prose for multi-step specs

Optimal Codex Workflow

The pattern that works (claude + codex hybrid):

1. Claude builds - architecture, exploration, back-and-forth iteration
2. Codex reviews - dispatch /codex:adversarial-review with a specific focus after a major change. 6-10 min wait, actionable findings
3. Claude filters - triage codex output: "which are real issues vs noise, which need design decisions"
4. Codex fixes - confirmed bugs with clear specs get delegated back to codex
5. Batch maintenance - queue codex with 3-5 P2 tasks at session start, work on real stuff while it churns

What doesn't work:

• Letting codex drive architecture decisions
• Vague task descriptions
• Auto-running codex on every claude response (drains usage fast)

Anti-patterns

1. Codex for time-sensitive work - 10+ min latency kills interactive flow
2. Codex with vague prompts - it will interpret literally and break things
3. Opus for trivial tool calls - haiku does it at 5% cost
4. Worktrees for non-overlapping single-agent work - merge overhead with no upside
5. Big refactors on main - hard rollback, polluted history
6. Parallel agents on same files without worktrees - concurrent write conflicts
7. Dispatching codex synchronously - always background, never wait
8. Forgetting --model gpt-5.4 - default selection is unreliable
9. Codex for UI work - zero taste, no visual judgment, will produce bricks
10. Codex when you need to discuss/brainstorm - it's a one-shot executor, not a collaborator

Examples

Bulk context gathering: 5 independent file reads → 5 haiku in parallel, single message dispatch.

New feature scaffolding (small): sonnet, current branch, no subagents.

New feature scaffolding (big, multi-file): sonnet, feat/<slug> branch, optional sonnet subagents for independent modules.

Security audit before launch: codex in background on feat/audit worktree, you keep building on main.

Hard refactor across 20 files: opus in worktree, you stay on main fixing other stuff, merge when done.

"Find all references to X across the codebase": haiku, current branch, no subagent (Grep tool is faster).