[Extension]: Add Token Budget

[tinesoft]

Extension ID

token-budget

Extension Name

Token Budget

Version

1.0.1

Description

Reduces LLM token consumption in Spec Kit workflows: compact artifacts in-place, scope per-phase reading, suppress prose padding, and report token usage.

Author

Tine Kondo

Repository URL

https://github.com/tinesoft/spec-kit-token-budget

Download URL

https://github.com/tinesoft/spec-kit-token-budget/archive/refs/tags/v1.0.1.zip

License

MIT

Homepage (optional)

https://github.com/tinesoft/spec-kit-token-budget

Documentation URL (optional)

https://github.com/tinesoft/spec-kit-token-budget/blob/main/README.md

Changelog URL (optional)

https://github.com/tinesoft/spec-kit-token-budget/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.1.0

Required Tools (optional)

- `python3` + `tiktoken` — optional, for accurate token counts (cl100k_base); falls back to chars/4 heuristic if absent
- `rtk` binary — optional, for stronger CLI output compression in `slim_output.sh`; built-in rules used otherwise

Number of Commands

4

Number of Hooks (optional)

6

Tags

tokens, budget, context, efficiency, cost-optimization

Key Features

• /speckit.token-budget.compact — lossless SDD artifact compaction (light / medium / aggressive). Backs up originals as <artifact>.full.md. Never touches IDs matching FR-, NFR-, T-, US-, AC- patterns or headings in preserve_sections. Aliases: compress, distill.
• /speckit.token-budget.scope — pre-flight reading manifest for the next workflow phase (plan / tasks / implement / analyze / checklist), with per-file token budgets. Aliases: brief, focus.
• /speckit.token-budget.concise — toggles a marker-bracketed concise-output directive in the project's agent memory file. Prefers AGENTS.md (open cross-agent standard); falls back to CLAUDE.md, GEMINI.md, .cursor/rules/, etc. Reversible. Aliases: terse, quiet.
• /speckit.token-budget.usage — read-only token dashboard: per-artifact sizes, savings vs .full.md backups, projected per-phase budgets. Aliases: stats, report.
• scripts/bash/slim_output.sh — CLI output compressor with built-in rules for git status, git log, pytest, npm test, and a generic head/tail fallback. Defers to rtk if installed.
• 6 lifecycle hooks: before_plan, before_tasks, before_implement (auto-scope); after_specify, after_plan, after_tasks (auto-compact). All optional.

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• macOS 15.x with Spec Kit v0.1.0

Test project: https://github.com/tinesoft/spec-kit-token-budget-demo

Test scenarios:

1. Installed extension via specify extension add token-budget --from <release-zip-url>
2. Copied token-budget-config.template.yml to token-budget-config.yml
3. Ran /speckit.token-budget.usage — verified per-artifact token counts
4. Ran /speckit.token-budget.compact at all three levels — verified lossless preservation of FR-/NFR-/T-/US-/AC- IDs and preserve_sections headings; confirmed .full.md backup created
5. Ran /speckit.token-budget.concise on — verified marker block injected in AGENTS.md; ran concise off — verified block removed cleanly
6. Ran /speckit.token-budget.scope tasks — verified manifest written to specs/<feature>/.token-budget/scope-tasks.md
7. Verified slim_output.sh compression on git status and git log -n 50
8. Verified lifecycle hooks fire at the correct phases

Example Usage

# Install extension
specify extension add token-budget \
  --from https://github.com/tinesoft/spec-kit-token-budget/archive/refs/tags/v1.0.1.zip

# Copy and edit config
cp .specify/extensions/token-budget/token-budget-config.template.yml \
   .specify/extensions/token-budget/token-budget-config.yml

# Inside an SDD project, after running /speckit.specify and /speckit.plan:
/speckit.token-budget.usage          # see baseline token counts
/speckit.token-budget.compact        # compress every artifact (medium level by default)
/speckit.token-budget.concise on     # silence prose narration during SDD steps
/speckit.token-budget.scope tasks    # write a focused reading manifest before /speckit.tasks
/speckit.tasks                       # agent reads the manifest first

Proposed Catalog Entry

{
  "token-budget": {
    "name": "Token Budget",
    "id": "token-budget",
    "description": "Reduces LLM token consumption in Spec Kit workflows: compact artifacts in-place, scope per-phase reading, suppress prose padding, and report token usage.",
    "author": "Tine Kondo",
    "version": "1.0.1",
    "download_url": "https://github.com/tinesoft/spec-kit-token-budget/archive/refs/tags/v1.0.1.zip",
    "repository": "https://github.com/tinesoft/spec-kit-token-budget",
    "homepage": "https://github.com/tinesoft/spec-kit-token-budget",
    "documentation": "https://github.com/tinesoft/spec-kit-token-budget/blob/main/README.md",
    "changelog": "https://github.com/tinesoft/spec-kit-token-budget/blob/main/CHANGELOG.md",
    "license": "MIT",
    "requires": {
      "speckit_version": ">=0.1.0"
    },
    "provides": {
      "commands": 4,
      "hooks": 6
    },
    "tags": ["tokens", "budget", "context", "efficiency", "cost-optimization"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-12T00:00:00Z"
  }
}

Additional Context

This extension was designed to address the structural property of SDD artifact pipelines: earlier artifacts (spec, plan, research) are re-read on every subsequent phase, so compacting them at the source compounds savings across every downstream turn and phase. It is inspired by RTK, CavemanClaude, claude-token-efficient, and Anthropic's official cost guide.