agentleFS
haruharu/redmine_ai_helper/.claude/skills/speckit-token-budget-scope/SKILL.md

speckit-token-budget-scope

Skill107 starsChanged 9 months agoMITView on GitHub

Build a focused reading manifest for the next workflow step. Names the

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
  1. Very specific:

    Start from scope.phase_inputs[<phase>] and expand contracts/ to its actual files.

    line 45
  2. Very specific:

    Use estimate_tokens.sh to count each region's tokens.

    line 73
  3. Very specific:

    If the total exceeds scope.max_total_tokens:

    line 74
  4. Distinctive:

    If still over, flag the overflow and recommend:

    line 76
  5. Very specific:

    Write specs/<feature>/.token-budget/scope-<phase>.md with this exact shape (replace placeholders, keep the headings):

    line 83

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Resolve the active feature directory from the current git branch.
  2. 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).
  3. Load token-budget-config.yml — scope.max_total_tokens and scope.phase_inputs are 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:

PhaseReads in fullCan skim/skip
planspec.md (FRs, NFRs, user stories, constraints)spec.md "Background", "Out of scope"
tasksplan.md (Constitution Check, Phase 0/1 outcomes), data-model.md, contracts/*plan.md "Progress Tracking", "Complexity Tracking"
implementtasks.md (full), plan.md (file paths only), contracts/*research.md, quickstart.md, spec rationale
analyzespec.md, plan.md, tasks.md (full)research.md, quickstart.md
checklistspec.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=aggressive on the largest contributor; or
    • splitting the next phase into a phased run (per tasks.md Phase 1 only, then Phase 2, etc.).

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.