| name | source-command-context-budget |
| description | Context budget — guidance on WHICH context files to load per task type (always / on-demand / skip) to keep token cost low. Read-only advice. (ADR-0066) |
source-command-context-budget
Use this skill when the user asks to run the migrated source command context-budget.
Command Template
🎯 Context Budget
Loading every memory file into context on every task is the most common way a
session goes token-heavy. This is read-only guidance — it changes nothing on
disk. It tells you which context to pull in for the task at hand, so the boot
context stays lean and /token-report trends cool.
The discipline is a three-tier budget per task type:
- ALWAYS — load up front; the task is unsafe or aimless without it.
- ON-DEMAND — pull in only when the task actually touches that area. Use the
lightweight loading primitive (below) rather than re-reading wholesale.
- SKIP — leave it out unless something explicitly points you to it. Loading it
"just in case" is pure token cost with no payoff.
This complements the measurement commands — /token-report (per-session/week
token aggregation) and the token-attribution.mjs script (where the tokens went).
This command is the prevention side: spend fewer tokens in the first place.
The loading primitive: @-imports
On Codex, an @-import pulls a file into context on demand and is the
cheapest way to load a reference doc exactly when you need it:
@contextkit/best-practices.md
@contextkit/behaviors.md
Codex resolves these relative to the file that contains them (e.g.
AGENTS.md at the project root), so the paths above point at the installed kit
artifacts. Prefer one targeted @-import over re-reading a whole tree.
Cross-host note (ADR-0066 trade-off): the @-import is a Claude-Code
feature. On Antigravity and Codex the converted skill keeps the same
lines as plain textual references — they read as "open this file" rather
than auto-resolving. The guidance is identical; only the loading mechanism
differs by host.
Per-task-type budget
The artifacts referenced below all exist in an installed project:
AGENTS.md (root constitution), contextkit/best-practices.md,
contextkit/behaviors.md (+ behaviors-examples.md),
contextkit/memory/decisions/ (ADRs — the why),
contextkit/memory/sessions/ (the what changed, one file per session) and its
index contextkit/memory/SESSIONS.md, contextkit/memory/GLOSSARY.md
(UI ↔ code naming), contextkit/memory/project-map/00-index.md (the where —
durable structural map), .context-snapshot.md (full dynamic snapshot), and
docs/CHANGELOG.md.
🐛 Bugfix
| Tier | Load |
|---|
| ALWAYS | AGENTS.md; the specific file(s) under suspicion; the failing test or repro. |
| ON-DEMAND | @contextkit/memory/GLOSSARY.md if the bug spans a domain term; the latest matching entry in contextkit/memory/sessions/ if the area was touched recently; the one ADR that governs the buggy subsystem. |
| SKIP | The full .context-snapshot.md, the whole ADR set, the project-map, docs/CHANGELOG.md. A bug is local — pull terrain only if the repro is non-local. |
✨ New feature
| Tier | Load |
|---|
| ALWAYS | AGENTS.md; contextkit/memory/project-map/00-index.md (orient before adding); any ADR that constrains the feature's area. |
| ON-DEMAND | @contextkit/best-practices.md when writing non-trivial code; @contextkit/memory/GLOSSARY.md before coining an identifier; the relevant contextkit/memory/sessions/ entry for adjacent recent work. |
| SKIP | .context-snapshot.md in full, docs/CHANGELOG.md, ADRs for unrelated subsystems. |
♻️ Refactor
| Tier | Load |
|---|
| ALWAYS | AGENTS.md (the file-size + SRP + layering rules drive the refactor); contextkit/memory/project-map/00-index.md (blast radius); the file(s) being refactored. |
| ON-DEMAND | @contextkit/best-practices.md; the ADR that justifies the current structure (so you don't undo a deliberate decision); /simulate-impact for a high-risk path. |
| SKIP | contextkit/memory/sessions/ history, docs/CHANGELOG.md, unrelated ADRs. |
📝 Docs
| Tier | Load |
|---|
| ALWAYS | the doc file(s) being edited; AGENTS.md §Language policy + §Documentation. |
| ON-DEMAND | @contextkit/memory/GLOSSARY.md for naming consistency; the source file you're documenting. |
| SKIP | ADRs, .context-snapshot.md, the project-map, sessions history, contextkit/best-practices.md. Docs work rarely needs deep code context. |
🔍 Review
| Tier | Load |
|---|
| ALWAYS | the diff under review; AGENTS.md (the constitution is the rubric). |
| ON-DEMAND | @contextkit/best-practices.md; @contextkit/behaviors.md for how the change was made; the ADR governing the changed area; the matching contextkit/memory/sessions/ entry. |
| SKIP | The full .context-snapshot.md, the whole ADR set, unrelated modules from the project-map. |
How to apply it
- Classify the task first — bugfix / feature / refactor / docs / review.
- Load the ALWAYS tier and start.
- Pull ON-DEMAND items with an
@-import (Codex) or by opening the
named file (other hosts) only when the work reaches that area — never
pre-emptively.
- Leave the SKIP tier out. If you find yourself reaching for it, that's a
signal the task is broader than you classified it — re-scope, don't bulk-load.
Why this matters
- Cheaper sessions — fewer full-file reads is the single biggest lever on
tokens.budgetPerSession; verify the effect with /token-report.
- Sharper context — a lean window keeps the model on-task; a bloated one
buries the signal.
- Composable — pairs with
/dev-start (lock the scope) and /token-report
(measure the result). Budget, then measure, then tighten.
Guidance only. This command never edits a file — it tells you what not to load.
