diff --git a/AGENTS.md b/AGENTS.md index c383f2e..37356c8 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -130,6 +130,26 @@ Load additional guides when the task requires them. - Installation and configuration are managed by Mosaic bootstrap and runtime linking. - If sequential-thinking is unavailable, you MUST report the failure and stop planning-intensive execution. +## Subagent Model Selection (Cost Optimization — Hard Rule) + +When delegating work to subagents, you MUST select the cheapest model capable of completing the task. Do NOT default to the most expensive model for every delegation. + +| Task Type | Model Tier | Rationale | +|-----------|-----------|-----------| +| File search, grep, glob, codebase exploration | **haiku** | Read-only, pattern matching, no reasoning depth needed | +| Status checks, health monitoring, heartbeat | **haiku** | Structured API calls, pass/fail output | +| Simple code fixes (typos, rename, one-liner) | **haiku** | Minimal reasoning, mechanical changes | +| Code review, lint, style checks | **sonnet** | Needs judgment but not deep architectural reasoning | +| Test writing, test fixes | **sonnet** | Pattern-based, moderate complexity | +| Standard feature implementation | **sonnet** | Good balance of capability and cost for most coding | +| Complex architecture, multi-file refactors | **opus** | Requires deep reasoning, large context, design judgment | +| Security review, auth logic | **opus** | High-stakes reasoning where mistakes are costly | +| Ambiguous requirements, design decisions | **opus** | Needs nuanced judgment and tradeoff analysis | + +**Decision rule**: Start with the cheapest viable tier. Only escalate if the task genuinely requires deeper reasoning — not as a safety default. Most coding tasks are sonnet-tier. Reserve opus for work where wrong answers are expensive. + +**Runtime-specific syntax**: See the runtime reference for how to specify model tier when spawning subagents (e.g., Claude Code Task tool `model` parameter). + ## Skills Policy - Use only the minimum required skills for the active task. diff --git a/runtime/claude/RUNTIME.md b/runtime/claude/RUNTIME.md index 433ea14..b4258de 100644 --- a/runtime/claude/RUNTIME.md +++ b/runtime/claude/RUNTIME.md @@ -16,6 +16,36 @@ This file applies only to Claude runtime behavior. 8. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...` 9. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates. +## Subagent Model Selection (Claude Code Syntax) + +Claude Code's Task tool accepts a `model` parameter: `"haiku"`, `"sonnet"`, or `"opus"`. + +You MUST set this parameter according to the model selection table in `~/.config/mosaic/AGENTS.md`. Do NOT omit the `model` parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well. + +**Examples:** + +``` +# Codebase exploration — haiku +Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers") + +# Code review — sonnet +Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/") + +# Standard feature work — sonnet +Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form") + +# Complex architecture — opus (only when justified) +Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy") +``` + +**Quick reference (from global AGENTS.md):** + +| haiku | sonnet | opus | +|-------|--------|------| +| Search, grep, glob | Code review | Complex architecture | +| Status/health checks | Test writing | Security/auth logic | +| Simple one-liner fixes | Standard features | Ambiguous design decisions | + ## Memory Override Do NOT write durable memory to `~/.claude/projects/*/memory/`. All durable memory MUST be written to `~/.config/mosaic/memory/` per `~/.config/mosaic/guides/MEMORY.md`. Claude Code's native auto-memory locations are volatile runtime silos and MUST NOT be used for cross-session or cross-agent retention.