token-economics

name	token-economics
description	Token budgeting discipline for all agents. Treats tokens as a resource from session start — not just when the buffer hits 60%. Covers prompt compression, context hygiene, handoff packing, and HOT memory pruning.
argument-hint	Context management, token budgeting, session handoff, or prompt efficiency question

Token Economics

Tokens are a resource. Treat them as a budget from the first message, not a crisis to manage when the buffer alarm fires.

Inspired by the Caveman token compression philosophy (MIT License): tighter semantic frames improve both cost and model reasoning quality. The working buffer protocol in proactive-agent is the crisis backstop — this skill is the upstream discipline that delays or avoids that crisis.

---

Budget-First Mindset

Before every response, ask: is this response as compact as it can be while still being useful?

• Prefer a file reference over re-pasting file content into chat.
• Prefer a symbol name + line number over quoting a block of code.
• Prefer a one-sentence decision summary over re-explaining the context.
• If a question can be answered with one sentence, use one sentence.

---

Read Hygiene

• If the current hub has an optional codebase-intelligence lens skill, check for existing pre-computed artifacts before a multi-file Grep sweep — pre-computed graphs answer caller/callee/hotspot questions for free; paying for repeated Grep passes over source that's already indexed is a budget leak.
• Don't re-read a file you already read in the same session unless its content may have changed.
• Don't re-read a skill or profile already loaded this session.
• When a tool result is large, extract only the relevant fragment and discard the rest mentally.
• If a read returns more than needed, work from the relevant part — don't quote the whole result back.

---

Working Buffer Compression

When writing to memory/working-buffer.md or memory/<agent>.md:

• Write the decision or outcome, not the conversation.
• Write the current state, not how you got there.
• If a fact is derivable from the code or git history, don't store it in memory — read it when needed.
• HOT memory is for things that will vanish on compaction. If it survives a grep, it doesn't need to be in HOT.

---

Handoff Packing

When handing off between agents or sessions:

• Pass: the decision made, constraints it created, and the next concrete action.
• Don't pass: the full conversation, the reasoning path, or the context already in the ticket.
• If handing off to Builder, the ticket IS the context — don't duplicate it in the dispatch message.
• If handing off at session end, update memory/<agent>.md HOT section and stop. The next session reads memory, not chat history.

---

HOT Memory Pruning

Aggressively retire HOT items:

• If a decision is confirmed and has no open action, move it to WARM.
• If an item has been in HOT for more than 48 hours with no reference, move it to WARM.
• If an item is recoverable from a git log, ticket, or file read, remove it from HOT entirely.
• A long HOT section is a signal that decisions aren't being closed — not a sign of thoroughness.

---

Prompt Construction

When invoking a subagent or spawning a task:

• Include only the context the subagent cannot derive itself.
• Name the exact file, line, or artifact — don't describe it in prose.
• State the question or task in one sentence before any supporting context.
• Remove the supporting context if the subagent can read it directly.