| name | token-budget |
| description | Token budget tracking and enforcement for Gastown convoy-level execution. Hard limits with pre-execution checking, per-convoy and per-agent tracking, structured stop reasons. |
| type | skill |
| category | state |
| status | stable |
| origin | tibsfox |
| modified | false |
| first_seen | "2026-04-04T00:00:00.000Z" |
| first_path | .claude/skills/token-budget/SKILL.md |
| superseded_by | null |
Token Budget Enforcement
Pre-execution budget gating for multi-agent convoy execution. Prevents token overspend by checking budgets BEFORE API calls, not after. Identified by the 12 Primitives analysis (Primitive 5) as the #1 actionable improvement.
Activation
This skill activates when:
- A convoy execution starts (mayor creates a convoy)
- Agents are spawned within a convoy
- Any agent is about to make an API call during convoy execution
- Budget reporting is requested during or after execution
Architecture
Budget Hierarchy
Convoy Budget (hard limit, default 500K tokens)
|
+-- Agent A budget (hard limit, default 100K tokens)
+-- Agent B budget (hard limit, default 100K tokens)
+-- Agent C budget (hard limit, default 100K tokens)
The convoy budget is the aggregate ceiling. Individual agent budgets prevent any single polecat from consuming a disproportionate share.
Check-Before-Execute Pattern
Every API call in a convoy MUST follow this sequence:
- Estimate the projected token cost for the call
- Check
checkBudget(budget, agentId, projectedCost) — returns BudgetCheckResult
- If
allowed: false — stop immediately, do NOT make the API call
- If
reason: 'warning_threshold' — proceed but log the warning
- If
reason: 'ok' — proceed normally
- After execution —
recordUsage(budget, agentId, actualInput, actualOutput)
- Persist —
saveBudget(budget, budgetDir) to survive crashes
Structured Stop Reasons
| Reason | Meaning | Action |
|---|
ok | Under budget, no concerns | Proceed |
warning_threshold | Past warning % but under hard limit | Proceed, log warning |
convoy_budget_exceeded | Convoy would exceed hard limit | STOP, do not call API |
agent_budget_exceeded | Agent would exceed its limit | STOP, do not call API |
