routing-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

# routing-guide

Reference skill for buhhdy's provider routing logic. Load this when you
need to reason about which provider to use and why, or when a task doesn't
clearly match the main routing tree.

## Quick Reference: Routing Decision Tree

Apply in order; stop at first match. Before applying rule 1, 6, or 8 (which
route to gemini), check gemini's availability (Provider Strengths below) —
if unavailable, use claude_code or codex instead.

| # | Condition | Provider | Tier |
|---|-----------|----------|------|
| 1 | Native video/audio/PDF/multimodal | gemini-complex | COMPLEX |
| 2 | Native OpenAI tool (voice, image-gen, Assistants) | codex | COMPLEX |
| 3 | Complex coding: multi-file refactor, deep debugging, long agentic execution | claude_code | COMPLEX |
| 4 | Strict JSON/schema output, automation-grade instructions | codex | STANDARD |
| 5 | User-facing prose or plans under a format contract | claude_code (codex ALT) | STANDARD |
| 6 | Bulk classification/extraction/fanout (cost-dominant) | gemini-lite (claude_code fallback if unavailable/quota-low) | LIGHTWEIGHT |
| 7 | Context >200K tokens, code reasoning | claude_code or codex | COMPLEX |
| 8 | Context >200K tokens, raw documents/media/search | gemini-complex | COMPLEX |
| 9 | Default lightweight (no rule matched) | claude_code (cheapest available if unavailable) | LIGHTWEIGHT |

Rules 5, 6 (fallback only), and 9 carry a slight quota-driven claude_code
preference (we pay for Claude Max but only standard team/business-tier
Codex/Gemini) — see
`config.yaml`'s Subscription Tier Interview and Provider Routing Decision
Tree for the full mechanics, including how a reported subscription tier can
reorder this per session. Rule 6's gemini primary is capability/cost-based,
not quota-based, and is never demoted by that reordering.

## Inception vs Change Routing (added 2026-07-21)

Product/initiative scale, EXPLICITLY requested → core-workflows
**Workflow 0** (`product-inception`; trigger phrases per Workflow 0's
intro — that section is canonical). Everything else — features, changes,
bugs, refactors — → **Workflow 1**. Tie-breaker: when in doubt, Workflow 1
— inception must be explicitly requested, never inferred from task size.
Workflow 0 terminates at the architecture doc (LD-3); its epic queue feeds
Workflow 1.

## Gemini Worker Naming (ACP migration, 2026-07-08)

buhhdy runs on stock upstream omnigent, which drives Gemini through its
generic ACP harness. ACP cannot switch gemini models per-dispatch, so each
tier is its own worker with the model baked into its ACP command:

| Worker | Model | Tier |
|---|---|---|
| gemini-complex | gemini-3.1-pro-preview | COMPLEX |
| gemini-standard | gemini-3.5-flash | STANDARD |
| gemini-lite | gemini-3.1-flash-lite | LIGHTWEIGHT |

Anywhere this guide (or any other skill) names "gemini" plus a tier or a
model, dispatch the matching `gemini-*` worker and OMIT args.model — it is
silently ignored for these workers. All three are ONE vendor sharing one
binary and one auth: an availability failure applies to all three at once,
and a `gemini-*` implementer can never be cross-reviewed by another `gemini-*`
worker.

## Model Tier Table (verified 2026-06-30; FRONTIER row added 2026-07-01;
opencode column added 2026-07-07)

| Tier        | claude_code      | codex          | gemini                 | opencode                |
|-------------|------------------|----------------|------------------------|-------------------------|
| FRONTIER    | claude-fable-5   | —              | —                      | —                       |
| COMPLEX     | claude-opus-4-8  | gpt-5.5        | gemini-3.1-pro-preview | openrouter/z-ai/glm-5.2 |
| STANDARD    | claude-sonnet-5  | gpt-5.4-mini   | gemini-3.5-flash       | —                       |
| LIGHTWEIGHT | claude-haiku-4-5 | gpt-5.4-nano   | gemini-3.1-flash-lite  | —                       |

## Provider Strengths Summary

**Claude (claude_code)**
- Best: multi-file refactoring, long agentic runs, subtle code logic, self-verification
- Best: writing, planning, brainstorming, explaining (prose depth)
- Weakness: native voice/image-gen, extreme-scale cheap classification, video/audio
- Note: claude-sonnet-5 (STANDARD) rivals claude-opus-4-8 on coding/agentic
  work per Anthropic's own docs — a valid cheaper COMPLEX-tier ALT for
  execution-shaped tasks, driven by model choice alone (this dispatch
  contract has no separate effort knob). Keep Opus for planning/architecture judgment
  (writing-plans, domain-modeling) where the bottleneck is judgment, not coding.
- Note: claude-fable-5 (FRONTIER) is ESCALATION-ONLY (operator directives
  2026-07-08, tightened later same day): never development dispatches —
  implementation, review, and exploration always run COMPLEX or lower —
  and NOT the default for planning/orchestration either. Routine planning
  and decomposition run claude-opus-4-8 (or claude-sonnet-5 when stakes
  are modest); Fable is reserved for the most complex work only — large
  multi-workstream decomposition, novel/hard-to-reverse architecture, or
  the heaviest cross-agent orchestration — with a stated one-line reason
  why Opus is insufficient. Metered per-token ($10/$50 per MTok, separate
  API key) as of 2026-07-08 — every dispatch is a real cost decision.

**OpenAI (codex)**
- Best: strict structured output, JSON schemas, tool routing, format contracts
- Best: narrow well-scoped changes, strict-simplify passes, automation pipelines
- Weakness: broad multi-file refactoring (route to Claude), massive long-context (route to Gemini)
- Note: o3/o4-mini fully retired; gpt-5/gpt-5-mini/gpt-4.1-nano superseded by
  gpt-5.5/gpt-5.4-mini/gpt-5.4-nano (verified 2026-06-30, cross-vendor checked).
  claude-sonnet-5 tokenizes ~30% heavier.

**Gemini (gemini)** — available again as of 2026-06-30 (an earlier headless-
OAuth failure, exit code 41 `FatalAuthenticationError`, was resolved
upstream; confirmed via a successful live dispatch).
- Best: bulk cheap ingestion, multimodal, Google Search grounding, high-volume fanout
- Best: large document corpus analysis (1M context at low cost per token)
- Weakness: subtle code logic vs Claude, nuanced long-form writing vs Claude/OpenAI
- Note: 2M context = Vertex enterprise only; standard API caps at 1M.
  gemini-2.5-pro/flash/flash-lite superseded by gemini-3.1-pro-preview/
  gemini-3.5-flash/gemini-3.1-flash-lite (verified 2026-06-30, cross-vendor).
  2.5-pro/flash confirmed shutdown no earlier than 2026-10-16; flash-lite's
  status is disputed between sources. gemini-3.1-pro-preview is PREVIEW, not GA.

**OpenCode (opencode)** — added 2026-07-07 (harness `opencode-native`,
auth = user's OpenRouter credentials, verified via live boot + dispatch).
- Best: cross-review diversity — GLM is a fourth model family, distinct from
  Anthropic/OpenAI/Google, so it's the strongest independence pick when
  reviewing any of the other three.
- Best: cost-effective COMPLEX ALT on routing rule 3 (complex coding) —

From uhstray-io/huhhb, MIT.

More from uhstray-io/huhhb