Agent Budget

---
name: agent-budget
description: Write the spend spec for an agentic workflow — per-stage model tiers, token caps with hard abort rules, a graceful-degradation order, and cost-per-outcome as the governing metric. Use when the user asks what an agent loop or multi-agent workflow should be allowed to spend, wants token/cost budgets and caps for AI automation, or got a surprise bill from an agent fleet.
---

# agent-budget

An unbudgeted agent loop is a runaway-cost incident with an architecture diagram. This skill produces the **budget spec** that governs an agentic workflow: what each stage may spend, on which tier of model, what happens at the cap, and — the number that actually matters — what one *outcome* costs. Pairs with `agent-loop-design` (the caps land in its loop spec) and `subagent-design` (the fleet line lands in its role cards); the tier vocabulary is this repo's own light/standard/heavy routing abstraction, so the spec ports across providers. Infra spend (compute, storage, egress) is `capacity-cost-model`'s domain — this skill budgets the tokens.

## How to respond

1. **Pin the outcome unit and the workflow's stages.** Ask at most 2 questions, spent on: *"what is one successful outcome?"* (a merged PR, a triaged ticket, a verified report — the denominator every cost divides by) and *"what does a typical run look like today?"* (stages, rounds, models — or "not built yet", which makes this a design-time budget, the cheap time to write one). Non-interactive run (no user to ask): derive both from the input and tag `[assumption]`; no outcome unit derivable → emit `BLOCKED: need the workflow and its outcome unit`.

2. **Assign each stage the cheapest adequate tier** — light / standard / heavy, per the routing rule of thumb: **light** for mechanical extraction and formatting, **standard** for most generation, **heavy** only where the hard thinking *is* the value (adversarial verification, weighted judgment) — and heavy stages are never downgraded to save money; they're where the money buys correctness. Every tier assignment carries a one-line rationale. The classic misallocation runs both directions: frontier models formatting JSON, and — worse — the cheap model doing the verify pass that exists to catch the cheap mistakes.

3. **Set three numbers per stage** in [`templates/budget-spec.md`](templates/budget-spec.md): **expected** spend per run (estimate honestly, tag `[assumption]` until measured), **cap** (the hard stop — 3–5× expected, tighter for unattended loops), and **on-cap action** (abort-and-escalate, or degrade — never "continue and warn"; a warning nobody is watching is a continue). State each as tokens **and** approximate money — tokens are what the harness enforces, but money is the only unit that sums across tiers, so **all cap comparisons happen in currency**. A stage that fans out per item carries two caps: a per-item cap (that item fails to the report's needs-human list; the rest continue) and a stage-wide cap. Then the **run-level cap** for the whole workflow — in currency, *less* than the sum of stage caps: every stage simultaneously hitting its cap is not a run to finish, it's an anomaly to stop.

4. **Write the degradation ladder** — what gives, in order, when spend pressure hits: first **narrow scope** (fewer items per run), then **reduce parallelism** (smaller fleet, slower wall-clock), then **cut non-verification stages** (skip the polish pass), and **last — never — verification**. Skipping verify to save tokens converts a cost problem into a correctness problem at the exact moment quality is already under pressure; a workflow that can't afford its verifier can't afford to run. State each rung's trigger and who flips it.

5. **Make cost-per-outcome the governing metric.** Total tokens is noise; **spend ÷ successful outcomes** is the number with meaning — a loop that gets cheaper per run but passes fewer runs got more expensive. Give it a target and a review threshold, and put beside it the **comparison line**: what the same outcome costs today (an hour of an engineer's time, the manual process) — a $4 triaged ticket is expensive against 60 seconds of a human's glance and cheap against twenty minutes of one; without the line, nobody can say which.

6. **Add measurement and emit.** Spend logged per run per stage (tagged by stage name, feeding the loop spec's telemetry row); weekly review of cost-per-outcome and cap-hit counts by a named role; alert on cap-hit rate rising (the leading indicator of drift — inputs grew, a prompt regressed, or a model changed under you) and on any run breaching the run-level cap (that's an incident, not a line item). Emit the spec in one message: stage table, run cap, degradation ladder, cost-per-outcome with comparison line, measurement plan. Flag every `[assumption]` estimate as the calibration backlog — after ~20 real runs, expected values stop being guesses. Hand off: the caps → `agent-loop-design`'s loop spec; per-agent tiers → `subagent-design`'s role cards; the verifier's quality gate → `llm-eval-harness`.

## Useful references in this skill

- [`templates/budget-spec.md`](templates/budget-spec.md) — stage table, degradation ladder, cost-per-outcome, and measurement skeleton

## Quality bar

- **The outcome unit is named** and every cost in the doc divides by it.
- **Every stage has tier + rationale + three numbers** (expected, cap, on-cap action). No stage rides free.
- **Heavy tiers survive.** No verification or judgment stage was downgraded to make the total look better.
- **Caps are hard.** Every on-cap action is abort or degrade — "warn and continue" appears nowhere.
- **The run cap is less than the sum of stage caps**, and the doc says why.
- **Verification is last on the degradation ladder**, explicitly.
- **The comparison line exists** — cost-per-outcome sits next to what the outcome costs without the agents.
- **Estimates are tagged.** `[assumption]` until measured; the calibration step is scheduled, not implied.

## When to use this skill

- ✅ "What should this agent workflow be allowed to spend?" — at design time, the cheap time
- ✅ A surprise token bill arrived — retrofit caps and a degradation ladder
- ✅ An `agent-loop-design` or `subagent-design` spec needs its budget line filled in
- ✅ "Is this automation actually cheaper than doing it by hand?" — build the comparison line

## When NOT to use this skill

- ❌ Infra/cloud cost modeling (compute, storage, egress) — `capacity-cost-model`
- ❌ Choosing a model tier for a single skilldrop skill — that's `model-routing.json`'s table, already decided
- ❌ Designing the loop or the fan-out itself — `agent-loop-design` / `subagent-design`; this skill prices what they draw
- ❌ Negotiating provider contracts or rate limits — procurement, not a spec

## Anti-patterns to avoid

- ❌ **Budget-free loops.** "We'll see what it costs" means the invoice is the monitoring system.
- ❌ **Warn-and-continue caps.** A cap whose breach action is a log line is a number, not a cap.
- ❌ **Skimping the verifier.** Downgrading or skipping verification under spend pressure — the false economy that ships fleet-speed garbage precisely when scrutiny dropped.
- ❌ **Token vanity metrics.** Celebrating "20% fewer tokens" while cost-per-successful-outcome rose because pass rates fell.
- ❌ **Frontier-everything.** The orchestrator's model formatting JSON at heavy-tier prices because nobody assigned tiers per stage.
- ❌ **Missing comparison line.** A cost-per-outcome with nothing beside it can justify anything or condemn anything.
- ❌ **Estimates that never graduate.** `[assumption]` numbers still governing caps six months and a thousand runs later.
- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.