speckit-token-budget-scope
Skill107 starsChanged 9 months agoMITView on GitHub
Build a focused reading manifest for the next workflow step. Names the
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- commitSkill
- create-pull-requestSkill
- create-release-branchSkill
- create-release-notesSkill
- handle-pr-reviewSkill
- qlty-checkSkill
- record-code-review-feedbackSkill
- record-spec-feedbackSkill
- recreate-test-dbSkill
- redmine-playwright-loginSkill
- regression-checkSkill
- rubocopSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-branch-convention-configureSkill
- speckit-branch-convention-renameSkill
- speckit-branch-convention-validateSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-token-budget-compactSkill
- speckit-token-budget-conciseSkill
- speckit-token-budget-usageSkill
- speckit-wiki-ingestSkill
- speckit-wiki-initSkill
- speckit-wiki-lintSkill
- speckit-wiki-querySkill
- speckit-wiki-statusSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Start from scope.phase_inputs[<phase>] and expand contracts/ to its actual files.
- Very specific: line 73
Use estimate_tokens.sh to count each region's tokens.
- Very specific: line 74
If the total exceeds scope.max_total_tokens:
- Distinctive: line 76
If still over, flag the overflow and recommend:
- Very specific: line 83
Write specs/<feature>/.token-budget/scope-<phase>.md with this exact shape (replace placeholders, keep the headings):
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Token Budget Scope Skill
/speckit.token-budget.scope
The user has invoked /speckit.token-budget.scope with arguments: $ARGUMENTS.
Your task
Produce a reading manifest the agent will follow on the next core SDD command. The goal is to load the smallest set of artifact regions that still covers everything the next phase needs to do its job correctly.
This command never modifies artifacts. It only writes one file:
specs/<feature>/.token-budget/scope-<phase>.md.
Inputs
- Resolve the active feature directory from the current git branch.
- Determine the target phase from
$ARGUMENTS:- explicit:
plan|tasks|implement|analyze|checklist - empty → infer the next phase from which artifacts already exist
(no plan.md →
plan; plan.md but no tasks.md →tasks; both →implement).
- explicit:
- Load
token-budget-config.yml—scope.max_total_tokensandscope.phase_inputsare the relevant keys.
Algorithm
Step 1 — Candidate set
Start from scope.phase_inputs[<phase>] and expand contracts/ to its
actual files. Add any file the user named explicitly via
--include=<path> (comma-separated) and remove any file the user named
via --exclude=<path>.
Step 2 — Prefer compacted
For each candidate, if a compacted version exists (the file does not
end in .full.md and a sibling <base>.full.md exists), use the
compacted version. Note the savings. If only .full.md exists, suggest
the user run /speckit.token-budget.compact first and continue with the
full version.
Step 3 — Section pruning
For each artifact, identify sections the target phase actually consumes and mark the rest as "skim". Defaults:
| Phase | Reads in full | Can skim/skip |
| plan | spec.md (FRs, NFRs, user stories, constraints) | spec.md "Background", "Out of scope" |
| tasks | plan.md (Constitution Check, Phase 0/1 outcomes), data-model.md, contracts/* | plan.md "Progress Tracking", "Complexity Tracking" |
| implement | tasks.md (full), plan.md (file paths only), contracts/* | research.md, quickstart.md, spec rationale |
| analyze | spec.md, plan.md, tasks.md (full) | research.md, quickstart.md |
| checklist | spec.md (FRs, NFRs) | everything else |
These are heuristics. Look at the actual artifact contents and adjust if a non-default section clearly carries information the next phase needs.
Step 4 — Token accounting
Use estimate_tokens.sh to count each region's tokens. Sum running total.
If the total exceeds scope.max_total_tokens:
- First, downgrade the lowest-priority "read" regions to "skim".
- If still over, flag the overflow and recommend:
- running
/speckit.token-budget.compact --level=aggressiveon the largest contributor; or - splitting the next phase into a phased run (per
tasks.mdPhase 1 only, then Phase 2, etc.).
- running
Step 5 — Write the manifest
Write specs/<feature>/.token-budget/scope-<phase>.md with this exact
shape (replace placeholders, keep the headings):
# Reading manifest — phase: <phase>
Generated: <ISO-8601-timestamp>
Active feature: <feature-name>
Token budget: <total>/<max_total_tokens>
## Read in full
- `<path>` — <region>, ~<N> tokens
- Why: <one-line justification>
## Skim only
- `<path>` — <region>, ~<N> tokens
- Look for: <what the agent should extract if anything>
## Skip
- `<path>` — ~<N> tokens — reason: <not needed for this phase>
## Notes
<any overflow warnings, missing artifacts, or recommendations>Step 6 — Tell the agent how to use it
Print, after the manifest is written:
Manifest written: specs/<feature>/.token-budget/scope-<phase>.md
Budget: <total>/<max> (<headroom> tokens free)
To use: when you run /speckit.<phase>, read the manifest first and load
only what it lists under "Read in full". Treat "Skim only" entries as
table-of-contents lookups — read the heading list, then jump to the
named region. Do not load "Skip" entries unless the manifest is wrong;
if it is, update it before proceeding.End the response. Do not produce a long explanation.
Re-runs
A new manifest overwrites the previous one for the same phase. Manifests
from prior phases (e.g. scope-plan.md after the user has moved to
tasks) are kept — they document what was loaded historically and are
useful for audit and for /speckit.token-budget.usage.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

