| name | gdd-budget |
| description | Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles - surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only - it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run. |
| argument-hint | [--cycles N] [--scenario best|typical|worst] |
| user-invocable | true |
| tools | Read, Bash, Grep, Glob, ToolSearch, Task |
{{command_prefix}}budget
Closes the long-horizon cost gap: Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track
cost, but nothing forecasts it. This skill projects the next N cycles of spend and tells you how
many cycles you have before you hit your project_cap. Read-only - it forecasts and warns; it
never spends, never edits budget.json, and never halts (the Phase 25 budget-enforcer hook is the
only thing that blocks a spawn). Contract: ../../reference/cost-governance.md.
Invocation
| Command | Behavior |
|---|
{{command_prefix}}budget | Typical-scenario forecast over the next 5 cycles + cycles-to-cap. |
{{command_prefix}}budget --cycles N | Forecast over the next N cycles. |
{{command_prefix}}budget --scenario best|typical|worst | Pick the projection rate (best / steady / worst). |
Steps
- Check telemetry exists. No
.design/telemetry/costs.jsonl (or zero rows) → print
budget: no cost telemetry yet — run a cycle first. and exit.
- Delegate to
cost-forecaster (via Task): it groups est_cost_usd by cycle, runs the pure
scripts/lib/budget/cost-forecast.cjs model for the requested --scenario/--cycles, reads
project_cap_usd from .design/budget.json, and computes cycles-to-cap.
- Render. Show: the scenario + its per-cycle rate, the best↔worst band, the projected total over
N cycles, and - when
project_cap_usd > 0 - "at the <scenario> rate (~$X/cycle) you'll reach
your $<cap> project cap in <Y> cycles" (or "not at this rate" when the trend is flat/down).
When no cap is set, show the trajectory and note that project_cap_usd is unset (so the hook won't
halt).
- Do not act. Never raise/lower the cap, never spend - GDD forecasts; the human sets the budget.
Output
End with:
## BUDGET COMPLETE
