atlas-router

---
name: atlas-router
description: "Runtime model cost router (Haiku→Sonnet→Opus cascade by task complexity). Use when 'router status', 'pick model', 'estimate cost', 'why Opus', or before launching expensive agent."
mode: [engineering]
effort: medium
version: 1.0.0
tier: [admin]
---

# ATLAS Router — Runtime Model Cost Cascade

Runtime cost router that recommends the cheapest capable Claude model for a given task by combining four heuristics (LOC touched, dependency fan-out, abstraction level, intent keywords). Extends the existing `effort-router` hook (W2.1) with explicit Haiku→Sonnet→Opus cascade and ties decisions back to actual spend via `cost-analytics` (W1.4) and per-skill scorecards (W1.2).

The router is **advisory**: it sets `ATLAS_RECOMMENDED_MODEL` for downstream tools and logs every decision to `~/.atlas/router-decisions.jsonl`. Explicit `model:` declarations in AGENT.md / SKILL.md frontmatter always win.

## Why This Exists

W1.x telemetry surfaced two patterns: (1) ~40% of trivial diffs (typo, single-file rename) ran on Opus, burning 25× the tokens needed; (2) Opus over-reach on architectural refactors caused $-spikes invisible until weekly review. atlas-router cuts the first by routing trivial tasks to Haiku 4.5, and budgets the second via daily/weekly $ caps.

## Heuristics (combined for routing decision)

| # | Axis | Signal | Routes to |
|---|------|--------|-----------|
| **1** | **LOC touched** | < 50 LOC | **Haiku 4.5** |
|   |   | 50–200 LOC | **Sonnet 4.6** |
|   |   | > 200 LOC | **Opus 4.7** |
| **2** | **Deps fan-out** | Single file, no imports modified | Haiku ok |
|   |   | 1–5 imports modified | Sonnet+ |
|   |   | > 5 imports modified OR cross-package | **Opus** (high blast-radius) |
| **3** | **Abstraction level** | Typo / rename / format / docs | **Haiku** |
|   |   | Feature add / unit logic / single-service | **Sonnet** |
|   |   | Architecture refactor / cross-cutting / ADR | **Opus** |
| **4** | **Intent keywords** | "ultrathink", "deep", "audit", "architect" | **Opus + max-effort** |
|   |   | "trivial", "quick", "typo", "rename" | **Haiku + low-effort** |
|   |   | (default — none of the above) | Tier from axes 1–3 |

**Combination rule**: take the **MAX** of the four axis recommendations. Any one Opus signal escalates the whole task to Opus (blast-radius bias toward correctness). Override always available via explicit `model:` frontmatter or `--model` CLI flag.

## Cost Budget

Daily and weekly $ caps live in `~/.atlas/cost-budgets.json`:

```json
{
  "daily_usd": 10.0,
  "weekly_usd": 50.0,
  "alert_threshold_pct": 80,
  "block_threshold_pct": 100
}
```

- **80% of cap** → router emits a soft warning via `atlas-analytics` and prefers downgrade (Sonnet over Opus when ambiguous)
- **100% of cap** → router refuses Opus routing for the rest of the window unless `ATLAS_ROUTER_BUDGET_OVERRIDE=1` set explicitly
- Spend data is read from `cost-analytics --window 1d|7d --json` (existing W1.4 surface — no duplication)

If `~/.atlas/cost-budgets.json` is absent, the router runs **uncapped** and only logs decisions (back-compat with v6 behavior).

## CLI

| Command | Behavior |
|---------|----------|
| `atlas router predict <task-description>` | Returns recommended model + cost estimate + reasoning (4-axis breakdown). Read-only, JSON or pretty output. |
| `atlas router stats --window 7d` | Actual model distribution + cost per skill (delegates to `cost-analytics --per-skill --window 7d`). |
| `atlas router budget --set daily=10 weekly=50` | Updates `~/.atlas/cost-budgets.json` (creates if missing). |
| `atlas router budget --show` | Prints current caps + spend window remaining. |
| `atlas router decisions --tail` | Live-tails `~/.atlas/router-decisions.jsonl` (W1.3 trace-replay-compatible schema). |

All subcommands fail-open: missing budget file, unreachable cost-analytics, or malformed input never block the calling tool.

## Integration

- **`hooks/effort-router`** — extended (this work). Before existing logic, the hook calls a Python predictor (4-axis), exports `ATLAS_RECOMMENDED_MODEL`, and appends a JSONL decision row. The effort-heuristic.sh fallback path is preserved verbatim — atlas-router is **additive**.
- **`cost-analytics`** (W1.4) — read-only consumer for actual spend. Never mutated by atlas-router.
- **`skill-scorecard`** (W1.2) — atlas-router decisions get joined to scorecards via `trace_id`, enabling "cost per successful skill invocation" reports.
- **`atlas-trace`** (W1.1) — every router decision is a span (`event=router.decide`) with `model.recommended`, `model.actual` (filled by PostToolUse), `axes.{loc,deps,abstraction,keywords}`.

## Backward Compatibility

If `ATLAS_ROUTER_DISABLED=1`, the new logic short-circuits and `effort-router` behaves exactly as v6.0. The pre-existing `EFFORT` suggestion path (low|medium|high|xhigh|max|auto) is unchanged in shape and emission. Adding atlas-router does **not** change the hookSpecificOutput JSON schema — only enriches the `additionalContext` string.

## Anti-Patterns

1. **Trusting the router on irreversible actions** — Opus for any HITL gate, schema migration, or production deploy. The router defers to `dod.md` Tier 4 mandates.
2. **Mocking budget caps in tests** — use `ATLAS_ROUTER_BUDGET_OVERRIDE=1` instead of editing `~/.atlas/cost-budgets.json` in CI.
3. **Stacking model overrides** — explicit `model:` in AGENT.md > CLI `--model` > router. Never combine all three; pick one source of truth.

## References

- Plan: `.blueprint/plans/ultrathink-regarde-ce-qui-abundant-petal.md` Section H W2.2
- Predecessor: `hooks/effort-router` (v6.0, extended here)
- Telemetry sources: `skills/atlas-trace/`, `skills/skill-scorecard/`, `skills/cost-analytics/`
- Decisions log: `~/.atlas/router-decisions.jsonl` (one JSON line per routing decision)
- Budget file: `~/.atlas/cost-budgets.json`