Spec Kit Token Economy

Spec Kit Token Economy adds three Spec Kit commands for reducing wasted context while keeping evidence honest:

• speckit.token-economy.route-evidence: route large logs, source files, or routeable agent-context references through the token-router pattern and analyze only raw line slices.
• speckit.token-economy.report-savings: report measured RTK and Headroom savings separately, with no estimates.
• speckit.token-economy.audit-context: audit a Spec Kit project for oversized context, injected instruction files, and routing opportunities.

The extension adapts ideas from:

• sleeplesshan/token-router: local line-range routing with raw, lossless evidence extraction.
• formin/token-saver: RTK and Headroom are the only measured token-saving channels; orchestration tools are not counted as savings.

It does not vendor either project. It provides Spec Kit workflow commands that tell the agent when to use those tools, how to preserve raw evidence, and how to report savings truthfully.

Where It Fits In The Spec Kit Flow

Spec Kit still owns the main spec-driven development sequence:

/speckit.constitution
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

Token Economy is a companion extension for evidence routing, context audits, and measured savings reports. It does not replace any core Spec Kit command. Use it around the core flow as follows:

Spec Kit stage	Token Economy use	Typical output
Before /speckit.constitution	Install the extension and run a baseline context audit if the repository already has long agent instructions, logs, or docs.	.specify/extensions/token-economy/ is installed. Optional .specify/token-economy/context-audit.md.
/speckit.constitution	Normally no automatic Token Economy action. If constitution input comes from long policy docs, use route-evidence agent_context first and cite the raw slices.	Optional evidence note under .specify/token-economy/evidence/. Core Spec Kit owns the constitution file.
/speckit.specify	Use route-evidence agent_context for long product notes, stakeholder docs, or imported requirements before writing the spec.	Optional evidence note under .specify/token-economy/evidence/. Core Spec Kit owns spec.md.
/speckit.plan	Use route-evidence heavy_code or agent_context when planning against large existing code, architecture notes, or long technology constraints.	Optional evidence note under .specify/token-economy/evidence/. Core Spec Kit owns plan.md.
/speckit.tasks	The extension registers an optional after_tasks hook. Accept the prompt to run speckit.token-economy.audit-context and check whether generated artifacts are becoming token-heavy before implementation.	.specify/token-economy/context-audit.md. Core Spec Kit owns tasks.md.
/speckit.implement	Use route-evidence error_log or heavy_code whenever implementation produces large build logs, test logs, or source files. The extension also registers an optional after_implement hook for report-savings.	Optional evidence notes during implementation. Optional .specify/token-economy/reports/<timestamp>-savings.md after implementation.

Automatic Hooks

Token Economy installs two optional hooks:

• after_tasks: prompts to run speckit.token-economy.audit-context.
• after_implement: prompts to run speckit.token-economy.report-savings.

All other uses are manual and situational. This is intentional: small greenfield features should not pay routing overhead when there is no large evidence to route.

Install

From a release archive:

specify extension add token-economy --from https://github.com/formin/spec-kit-token-economy/archive/refs/tags/v1.0.0.zip

For local development:

specify extension add --dev /path/to/spec-kit-token-economy

Requirements

Only Spec Kit is required. The token economy tools are optional and degrade gracefully:

• rtk: shell-output compression and measured savings via rtk gain.
• headroom: context compression and measured savings via headroom perf.
• token-router: local Ollama-backed line routing for large files.
• ollama and Python 3.10+: needed only when using the upstream token-router script.

Commands

Route Evidence

Use when a log, source file, or routeable instruction reference is too large to load directly.

/speckit.token-economy.route-evidence error_log build.log --query "timeout"
/speckit.token-economy.route-evidence heavy_code src/service.py --query "token expiration"
/speckit.token-economy.route-evidence agent_context docs/agent-rules/frontend.md --query "testing workflow"

The command follows token-router's separation of concerns:

1. A local router selects candidate line ranges.
2. The script extracts exact raw text from the original file.
3. The cloud model reasons over raw slices only.
4. If evidence is too narrow, request wider nearby ranges before making claims.

Report Savings

Use after a large Spec Kit session or as an after_implement hook.

/speckit.token-economy.report-savings
/speckit.token-economy.report-savings --hours 24

The report separates:

• RTK savings from rtk gain.
• Headroom savings from headroom perf.
• Tool usage such as token-router, omo, UltraWork, lazycodex, and Superpowers, which must never be counted as token savings.

Audit Context

Use after speckit.tasks, before implementation, or when a session is nearing context limits.

/speckit.token-economy.audit-context

The audit looks for:

• Large Spec Kit artifacts under .specify/.
• Oversized always-on agent files such as AGENTS.md, CLAUDE.md, and GEMINI.md.
• Logs and generated outputs that should be routed rather than pasted whole.
• Missing or inactive RTK, Headroom, and token-router setup.

Todo App Example

This example shows a small Todo app moving through the normal Spec Kit sequence with Token Economy added at the points where it helps.

0. Initialize And Install

specify init todo-app --integration claude
cd todo-app
specify extension add token-economy --from https://github.com/formin/spec-kit-token-economy/archive/refs/tags/v1.0.0.zip

Generated by installation:

• .specify/extensions/token-economy/README.md
• .specify/extensions/token-economy/commands/speckit.token-economy.route-evidence.md
• .specify/extensions/token-economy/commands/speckit.token-economy.report-savings.md
• .specify/extensions/token-economy/commands/speckit.token-economy.audit-context.md
• For Claude integrations, registered command skills such as .claude/skills/speckit-token-economy-audit-context/SKILL.md

1. Constitution

/speckit.constitution Create principles for a small Todo app: simple UX, local-first data, accessible keyboard interactions, and tests for task creation, completion, filtering, and deletion.

Token Economy use:

/speckit.token-economy.audit-context baseline before constitution

For a new Todo app, this usually confirms there is no oversized context yet. If the project has a long product policy or design brief, route it first:

/speckit.token-economy.route-evidence agent_context docs/product-principles.md --query "todo app principles accessibility local-first"

Generated markdown:

• .specify/token-economy/context-audit.md if the audit is run.
• .specify/token-economy/evidence/<timestamp>-todo-principles.md if routed evidence is worth preserving.

2. Specify

/speckit.specify Build a Todo app where users can add tasks, mark them complete, filter active/completed/all tasks, edit task text, delete tasks, and keep data locally after refresh.

Token Economy use:

/speckit.token-economy.route-evidence agent_context docs/todo-requirements.md --query "add complete filter edit delete local persistence"

Use this only when requirements come from a long note, imported backlog, meeting transcript, or existing README. For the simple prompt above, routing is optional.

Generated markdown:

• Core Spec Kit creates the feature spec.md.
• Token Economy may create .specify/token-economy/evidence/<timestamp>-todo-requirements.md.

3. Plan

/speckit.plan Use Vite, TypeScript, localStorage, and Vitest. Keep the UI single-page and avoid backend services.

Token Economy use:

/speckit.token-economy.route-evidence heavy_code src/App.tsx --query "todo state localStorage filtering"

For a brand-new Todo app there may be no source file yet, so this step is most useful in brownfield projects or when planning against starter code. If no large source or architecture file exists, skip routing and continue.

Generated markdown:

• Core Spec Kit creates plan.md.
• Token Economy may create .specify/token-economy/evidence/<timestamp>-planning-evidence.md.

4. Tasks

/speckit.tasks

Token Economy use:

After tasks are generated, accept the optional hook prompt:

Audit token and context budget for this feature? yes

Or run it manually:

/speckit.token-economy.audit-context

Generated markdown:

• Core Spec Kit creates tasks.md.
• Token Economy creates or updates .specify/token-economy/context-audit.md.

5. Implement

/speckit.implement

Token Economy use during implementation:

/speckit.token-economy.route-evidence error_log logs/test.log --query "failing todo filter test"
/speckit.token-economy.route-evidence heavy_code src/App.tsx --query "toggle completed localStorage"

After implementation, accept the optional hook prompt:

Report measured RTK and Headroom savings for this work? yes

Or run it manually:

/speckit.token-economy.report-savings --hours 168

Generated markdown:

• Token Economy may create .specify/token-economy/evidence/<timestamp>-implementation-log.md for routed logs or code evidence.
• Token Economy may create .specify/token-economy/reports/<timestamp>-savings.md after the savings report.

Generated Markdown Files

Token Economy creates or installs these Markdown files at different moments:

File	Created when	Purpose
.specify/extensions/token-economy/README.md	Extension install	Installed extension documentation inside the Spec Kit project.
.specify/extensions/token-economy/commands/*.md	Extension install	Source prompt files for the three extension commands.
.specify/extensions/token-economy/docs/usage.md	Extension install	Additional usage guide copied into the installed extension.
.specify/extensions/token-economy/docs/submission.md	Extension install	Catalog submission metadata copied into the installed extension.
.claude/skills/speckit-token-economy-*/SKILL.md	Extension install in Claude skills mode	Registered Claude skill wrappers for the three commands. Other integrations may use different command locations.
.specify/token-economy/context-audit.md	speckit.token-economy.audit-context, usually after /speckit.tasks	Project-local audit of large context, routing opportunities, and tool readiness.
.specify/token-economy/evidence/<timestamp>-<topic>.md	speckit.token-economy.route-evidence when useful evidence should be preserved	Raw source/log/context line ranges and citations used by the agent.
.specify/token-economy/reports/<timestamp>-savings.md	speckit.token-economy.report-savings, usually after /speckit.implement	Measured RTK and Headroom savings report.

Core Spec Kit still creates the main feature Markdown files, such as the constitution, spec.md, plan.md, and tasks.md. Token Economy adds supporting Markdown records for context control and evidence traceability.

What You Gain

Using Token Economy in a Spec Kit project gives you:

• Less wasted context: large logs, source files, and instruction references are routed before they enter the reasoning context.
• Raw evidence instead of lossy summaries: token-router-style routing returns original line slices, not rewritten explanations from a small model.
• Measured savings discipline: RTK and Headroom are reported separately, and missing data is reported as n/a rather than guessed.
• Better timing: context audit happens after task generation, before implementation consumes the largest context budget.
• Cleaner implementation loops: large failing logs can be routed during /speckit.implement without pasting the full output.
• Durable records: audit, evidence, and savings reports can live under .specify/token-economy/ for later review or handoff.
• Safer agent instructions: long optional rules can be moved into routeable references while mandatory root instructions stay compact.

Configuration

Installing the extension copies config-template.yml to:

.specify/extensions/token-economy/token-economy-config.yml

Important options:

• routing.max_direct_lines: line-count threshold for routing instead of direct reads.
• routing.token_router_home: optional local checkout path for token-router.
• savings.headroom_hours: default Headroom reporting window.
• state.evidence_dir: where routed evidence notes should be stored.
• state.report_dir: where savings reports should be stored.

Optional Status Scripts

The extension includes small helper scripts:

.specify/extensions/token-economy/scripts/bash/token-economy-status.sh

.specify/extensions/token-economy/scripts/powershell/token-economy-status.ps1

They check tool availability and print measured RTK/Headroom data when available. They do not print secrets, and they never estimate savings.

Safety Rules

• Do not send secrets, API keys, service-account JSON, or raw private data through compression or reports.
• Do not count token-router, local Ollama, omo, UltraWork, lazycodex, or Superpowers as token savings.
• Do not summarize code or logs through a small model when exact raw lines are needed.
• Do not make claims from omitted context; expand the range and cite the source file or command.

License

MIT. See LICENSE.