spec-kit-token-budget: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A Spec Kit extension (extension.yml) that adds five slash commands to reduce LLM token consumption in Spec-Driven Development workflows. It is installed by specify extension add and picked up by any agent spec-kit supports.

Development workflow

This extension has no build step. There are no tests in the conventional sense — validation is done by installing the extension into a real spec-kit project and running the commands.

# Install locally into an SDD project for manual testing
specify extension add --dev /path/to/spec-kit-token-budget

# Estimate tokens for a file (used internally by the commands)
bash scripts/bash/estimate_tokens.sh <file>

# Test slim_output.sh
bash scripts/bash/slim_output.sh -- git status
bash scripts/bash/slim_output.sh -- git log -n 50

# Test compact_helper.sh subcommands directly
bash scripts/bash/compact_helper.sh snapshot <file>
bash scripts/bash/compact_helper.sh summarize <orig> <compacted>
bash scripts/bash/compact_helper.sh has_marker <file>
bash scripts/bash/compact_helper.sh stamp <file> medium

PowerShell equivalents live under scripts/powershell/ and mirror the bash API exactly.

Architecture

The extension has two layers:

1. Slash command prompts (commands/*.md) Each file is a full agent instruction prompt with YAML frontmatter. The frontmatter declares scripts.sh / scripts.ps1 pointers to helper scripts. The agent follows the in-prompt algorithm to do content transformation (rewriting artifacts, writing manifests, toggling directives); the scripts handle the deterministic bookkeeping side.

• compact.md — artifact compaction in three levels (light / medium / aggressive). Instructs the agent to rewrite in place with hard guardrails: never touch lines with IDs matching preserve_id_patterns, never touch preserve_sections headings, never touch fenced code blocks. Uses compact_helper.sh for backup, token snapshot, and stamp. On first run, also injects a backup guard directive into the agent memory file (same marker pattern as concise) so agents do not read .full.md files.
• restore.md — undoes a previous compact run. Copies <artifact>.full.md back over the compacted file and deletes the backup. Removes the backup guard directive from the agent memory file when no backups remain anywhere in the project.
• scope.md — reads scope.phase_inputs from config, builds a per-phase reading manifest at specs/<feature>/.token-budget/scope-<phase>.md. Uses estimate_tokens.sh to budget each artifact.
• concise.md — locates the right agent memory file (AGENTS.md preferred, then agent-specific files in priority order from concise.memory_files), then inserts or removes a directive block between unique HTML comment markers.
• usage.md — read-only dashboard. Calls estimate_tokens.sh for each artifact, compares against .full.md backups, projects per-phase budgets.