From fe01e0cdc28291cfce029c1917de875780931ec4 Mon Sep 17 00:00:00 2001 From: Ivan Malison Date: Thu, 9 Jul 2026 16:08:47 -0700 Subject: [PATCH] agents: define model routing policy --- dotfiles/agents/AGENTS.md | 26 +++++++++++++++++-- .../skills/cross-agent-delegation/SKILL.md | 3 ++- .../cross-agent-delegation/scripts/ask-claude | 20 ++++++++++++-- .../cross-agent-delegation/scripts/ask-codex | 20 ++++++++++++-- dotfiles/claude/agents/codex-delegator.md | 4 +-- dotfiles/codex/agents/claude-delegator.toml | 6 ++--- 6 files changed, 67 insertions(+), 12 deletions(-) diff --git a/dotfiles/agents/AGENTS.md b/dotfiles/agents/AGENTS.md index 387fd9b7..148e2898 100644 --- a/dotfiles/agents/AGENTS.md +++ b/dotfiles/agents/AGENTS.md @@ -4,15 +4,37 @@ - When the primary model is Fable, strongly prefer delegating coding tasks to subagents (via the Agent tool). Fable should usually act as the orchestrator: planning, delegating, reviewing, and integrating. It may still work directly when delegation would add disproportionate overhead or the task cannot be usefully separated. - For other primary models, subagent delegation is optional rather than required. Use judgment: delegate when work is meaningfully parallelizable, independently scoped, or benefits from a separate implementation/review pass; work directly when that is simpler and more efficient. - The primary agent remains responsible for reviewing and integrating delegated work. -- Use judgement to select the model tier per task. Opus/medium is sufficient for simple, well-specified tasks. For harder tasks where architecture and design taste matter, prefer a stronger tier (e.g. fable). - Whenever you pick a model tier for an agent, record a one-line justification for that choice (in your reasoning/CoT or a brief note in the delegating message) so the decision is auditable. Tie the justification to what the agent must actually decide at execution time, not just the topic's importance — a task specified tightly enough that the taste is already discharged doesn't need the stronger tier. If you can't articulate why the cheaper tier is insufficient, default to it. - These guidelines apply to writing, editing, and refactoring code. Non-coding work (reading, searching, planning, running commands, answering questions) does not need to be delegated. +## Model and effort selection + +Treat model selection and effort level as separate decisions. The following scores are subjective routing scores from 1 to 10; for cost, 10 means most expensive. + +| Model | Intelligence / judgment | Design sense | Cost | Primary role | +| --- | ---: | ---: | ---: | --- | +| Fable | 10 | 10 | 10 | Design planning, ambiguity, architecture, intuition, and the hardest work | +| GPT-5.6 Sol | 9.5 | 8.5 | 4 | Default engineering model and best intelligence-to-cost choice | +| Opus | 8.8 | 9.5 | 7 | Specialized design critique, UX writing, aesthetic review, and alternative perspectives | + +- Do not select models below GPT-5.6 Sol at medium effort. Terra, Sonnet, Luna, GPT Mini, and Haiku should not be used, including for subagents. +- Default to Sol at high effort for most implementation, debugging, investigation, review, research, and agentic work. +- Use Sol at extra-high effort for unusually difficult but reasonably well-specified engineering, including complex debugging, algorithms, migrations, concurrency, multi-system changes, and high-stakes correctness review. +- Sol at medium effort is the minimum permitted configuration. Use it for bounded mechanical work, exploration, summaries, verification, and simple coordination. +- Prefer Fable for most design planning, product architecture, UI/UX direction, API design, and work where ambiguity, intuition, or taste materially affects the result. +- Use Fable at medium effort for ordinary design planning and at high effort for truly meaty, ambiguous, high-stakes, or long-horizon work. +- Use Opus selectively as a specialist rather than the default design planner. Good uses include independent design critique, visual refinement, UX writing, naming, prose, and alternative aesthetic perspectives. +- Do not automatically use low or max effort. Medium is the floor, high is the general default, and extra high is reserved for tasks where deeper reasoning is likely to affect correctness. +- Difficulty alone does not require Fable. Prefer Sol at extra-high effort when execution is difficult but the desired outcome is clear; prefer Fable when determining the right outcome requires judgment or taste. + ## Cross-model delegation - Use cross-model delegation only when the user requests it or model diversity or an independent check would be useful; it is never mandatory. -- Codex should prefer the `claude_delegator` agent, and Claude should prefer the `codex-delegator` agent. Use `$cross-agent-delegation` or its `ask-claude` and `ask-codex` wrappers when direct invocation is simpler. +- Codex should use the `claude_delegator` agent only for the specialized Opus cases below. Claude should prefer the `codex-delegator` agent when delegating to Sol. Use `$cross-agent-delegation` or its `ask-claude` and `ask-codex` wrappers when direct invocation is simpler. - Permit at most one cross-model handoff and never recursively delegate. Keep the child read-only and advisory by default, with only one writer per worktree. - The parent agent owns review, verification, and integration of the child's output. +- A Sol agent must never spawn, invoke, or delegate to Fable, including through cross-model wrappers or indirect subagent chains. If a task warrants Fable, select Fable as the primary model before beginning rather than allowing Sol to escalate itself. +- Sol may delegate to other Sol agents at medium effort or higher. It may use Opus only for specialized design critique, UX writing, aesthetic review, or an independent design perspective. +- Fable may delegate bounded execution, exploration, and verification work downward to Sol. ## Sharing dev-server / preview links - When sharing a local server or preview URL, always prefer this machine's Tailscale address over `127.0.0.1`/`localhost`/LAN IPs, so the link opens from any device on the tailnet. diff --git a/dotfiles/agents/skills/cross-agent-delegation/SKILL.md b/dotfiles/agents/skills/cross-agent-delegation/SKILL.md index 874c1f99..14528845 100644 --- a/dotfiles/agents/skills/cross-agent-delegation/SKILL.md +++ b/dotfiles/agents/skills/cross-agent-delegation/SKILL.md @@ -5,7 +5,7 @@ description: Safely delegate between Codex and Claude through read-only CLI wrap # Cross-Agent Delegation -Use a cheap native driver agent when available. Invoke the wrapper directly when that is simpler: +Use the minimum permitted native driver agent when available. Invoke the wrapper directly when that is simpler: - Pipe a self-contained prompt to `ask-claude` or `ask-codex` on stdin. - Reserve `--base64 ''` for native driver agents as injection-safe transport. A driver must encode the complete task itself and never embed raw delegated task text in shell source. @@ -13,6 +13,7 @@ Use a cheap native driver agent when available. Invoke the wrapper directly when - Review and verify the output in the parent agent before using it. - Never include credentials, secrets, or unnecessary personal data in the prompt. - Permit at most one cross-model handoff. Never ask the child to invoke either CLI or delegate again. +- A Sol caller may target Opus for specialized design work but must never target Fable. Choose Fable as the primary model before the task begins when Fable is warranted. - Keep one writer per worktree. Have the parent make any resulting edits. Environment variables documented in the scripts may override their conservative model, effort, timeout, turn, and budget defaults. diff --git a/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-claude b/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-claude index 6f4370d2..35c87fab 100755 --- a/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-claude +++ b/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-claude @@ -46,11 +46,27 @@ fi export CROSS_AGENT_DEPTH=1 timeout_value=${CROSS_AGENT_TIMEOUT:-10m} -model=${CROSS_AGENT_CLAUDE_MODEL:-haiku} -effort=${CROSS_AGENT_CLAUDE_EFFORT:-low} +model=${CROSS_AGENT_CLAUDE_MODEL:-opus} +effort=${CROSS_AGENT_CLAUDE_EFFORT:-medium} max_turns=${CROSS_AGENT_CLAUDE_MAX_TURNS:-4} max_budget_usd=${CROSS_AGENT_CLAUDE_MAX_BUDGET_USD:-0.25} +case "$model" in + opus|claude-opus-*) ;; + *) + echo "ask-claude: cross-model delegation is restricted to Opus, not Fable or lower-tier models" >&2 + exit 2 + ;; +esac + +case "$effort" in + medium|high|xhigh|max) ;; + *) + echo "ask-claude: effort must be medium or higher" >&2 + exit 2 + ;; +esac + umask 077 tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/ask-claude.XXXXXX") cleanup() { diff --git a/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-codex b/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-codex index a017efa4..e87dbba3 100755 --- a/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-codex +++ b/dotfiles/agents/skills/cross-agent-delegation/scripts/ask-codex @@ -46,8 +46,24 @@ fi export CROSS_AGENT_DEPTH=1 timeout_value=${CROSS_AGENT_TIMEOUT:-10m} -model=${CROSS_AGENT_CODEX_MODEL:-gpt-5.4-mini} -reasoning_effort=${CROSS_AGENT_CODEX_REASONING_EFFORT:-low} +model=${CROSS_AGENT_CODEX_MODEL:-gpt-5.6-sol} +reasoning_effort=${CROSS_AGENT_CODEX_REASONING_EFFORT:-medium} + +case "$model" in + gpt-5.6-sol) ;; + *) + echo "ask-codex: cross-model delegation is restricted to GPT-5.6 Sol" >&2 + exit 2 + ;; +esac + +case "$reasoning_effort" in + medium|high|xhigh|max) ;; + *) + echo "ask-codex: reasoning effort must be medium or higher" >&2 + exit 2 + ;; +esac umask 077 tmp_dir=$(mktemp -d "${TMPDIR:-/tmp}/ask-codex.XXXXXX") diff --git a/dotfiles/claude/agents/codex-delegator.md b/dotfiles/claude/agents/codex-delegator.md index 0680792e..621b0f01 100644 --- a/dotfiles/claude/agents/codex-delegator.md +++ b/dotfiles/claude/agents/codex-delegator.md @@ -2,8 +2,8 @@ name: codex-delegator description: Ask Codex for one independent read-only opinion tools: Bash -model: haiku -effort: low +model: opus +effort: medium maxTurns: 3 --- diff --git a/dotfiles/codex/agents/claude-delegator.toml b/dotfiles/codex/agents/claude-delegator.toml index aff04bb8..a11d38e9 100644 --- a/dotfiles/codex/agents/claude-delegator.toml +++ b/dotfiles/codex/agents/claude-delegator.toml @@ -1,7 +1,7 @@ name = "claude_delegator" -description = "Ask Claude for one independent read-only opinion" -model = "gpt-5.4-mini" -model_reasoning_effort = "low" +description = "Ask Opus for specialized independent design critique" +model = "gpt-5.6-sol" +model_reasoning_effort = "medium" developer_instructions = """ UTF-8 base64-encode the complete task yourself without using a tool. Verify that the payload contains only `A-Z`, `a-z`, `0-9`, `+`, `/`, and valid terminal `=` padding. Then make exactly one shell tool call: `ask-claude --base64 ''`. Never place raw task text in shell source. Return the command's stdout verbatim. Do not investigate or reason about the task yourself, edit files, run any other command, or call, spawn, communicate with, or delegate to any other agent. """