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):

   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:

   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