# Worker Budget

> Use BEFORE spawning any Agent worker for substantial work (builds, audits, releases). Deterministic budget analysis — pricing snapshot, per-worker-class token forecast from observed history, tier recommendation, and a worker contract with success thresholds + orchestrator-escalation triggers. Also use when the user asks about worker costs, budget analysis, or model-tier selection.

- Skill: `esummervill/worker-budget` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add esummervill/worker-budget`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esummervill/worker-budget/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: esummervill (https://skillmd.com/u/esummervill)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/esummervill/worker-budget

---


# Worker budget + designation system

Applies a delegation-tiering doctrine mechanically: no big model on mundane
work, no small model planning, and the **orchestrator woken only at mediation
points**. The system itself follows the deterministic-shell pattern —
arithmetic is a script, and the ONLY model involvement is a small-model scout
(Haiku) for the two genuinely fuzzy inputs: price verification when stale, and
task-complexity classification when novel.

## Flow (each time workers are about to be spawned)

1. **Run the deterministic budgeter** (no model, no network):

   ```bash
   node ~/.claude/skills/worker-budget/scripts/budget.mjs <worker-class> [count]
   ```

   Worker classes: `build-heavy`, `build-standard`, `cartography`, `research`,
   `release`, `verify`, `grind`. Output: cost estimate per tier, recommended
   tier, staleness warning, and a filled worker-contract template.

2. **If output says `PRICING STALE`** (snapshot older than the configured
   window): spawn ONE Haiku scout (`model: haiku`) with exactly this brief:
   "Fetch current Claude API per-MTok pricing for Opus, Sonnet, Haiku from
   docs.anthropic.com (WebSearch/WebFetch). Return ONLY a JSON object matching
   the schema in ~/.claude/skills/worker-budget/scripts/pricing.json — same
   keys, updated prices, as_of today. No prose." Then write its JSON over
   pricing.json and re-run the budgeter. Never let a large model do this
   errand; never trust remembered pricing.

3. **If the task fits no existing worker class**: spawn ONE Haiku scout to
   classify it — input: one-paragraph task description + the class definitions
   from history.json; output: nearest class + a token multiplier (0.5–2.0).
   The deterministic budgeter consumes that multiplier. (The orchestrator may
   override — the scout estimates, it does not decide.)

4. **Fill the worker contract** (the budgeter prints the template): success
   metrics the worker must hit, budget ceiling, and the escalation triggers
   that wake the orchestrator. Paste the contract into the worker's prompt
   verbatim. Adapt the success metrics to your repo's own gates (test suite,
   linter, typechecker, build, schema checks — whatever "green" means for you).

5. **After each worker completes**: append its actual token usage to
   history.json via:

   ```bash
   node ~/.claude/skills/worker-budget/scripts/record.mjs <worker-class> <actual-tokens> <outcome>
   ```

   The forecast is an EWMA over observed runs — it self-corrects.

## The worker contract (thresholds + escalation)

Every substantial worker prompt gets a CONTRACT block:

- **Success metrics** (worker self-reports against each): tests pass count ≥
  baseline+new, lint/typecheck/build clean, repo-specific gates green, zero
  out-of-surface files (or each one flagged with justification).
- **Budget ceiling**: estimated tokens × 1.5. Worker instruction: "if you
  project exceeding the ceiling, STOP at the current slice boundary, commit
  what is green, and report — do not push through."
- **Escalation triggers — the ONLY reasons to stop and wake the orchestrator
  mid-run**:
  1. contract ambiguity (spec contradicts code reality)
  2. a decision that crosses repo/system boundaries
  3. anything security- or tenancy-adjacent not explicitly in the spec
  4. projected budget overrun >50%
  5. a gate that fails twice for the same root cause
  Everything else: worker decides, documents the judgment call in its report.

## Division of labor (fixed)

| Actor | Does | Never does |
|---|---|---|
| budget.mjs (script) | all arithmetic, tier choice, contract template | — |
| Haiku scout | price refresh, novel-task classification | decide tier, plan |
| Worker (per doctrine tier) | build to contract, self-report metrics | expand scope |
| Orchestrator | set thresholds, mediate escalations, verify, integrate | grind, arithmetic |