Context budget: referenced instruction expansion is the largest token source

[JustAGhosT]

Problem

When chat.includeReferencedInstructions: true is enabled, the client attaches the full customization surface every turn:

• CLAUDE.md files (root, workspace, project — often 3+ levels deep)
• .claude/rules/*.md files (architecture, code-style, commits, governance, rust)
• Skill catalogs (67+ skills in skills.yaml)
• Agent catalogs (17+ agent definitions)
• .agents/guards/*.md governance files

In mystira-workspace, this alone accounts for a significant portion of the ~120k token sessions.

Proposed Solutions

1. Lazy instruction loading — retort sync engine should generate a compact index/summary rather than full agent/skill definitions. Full definitions loaded on-demand when a specific agent or skill is invoked.
2. Instruction budget calculator — retort healthcheck should estimate the per-turn instruction cost for an onboarded repo and warn when it exceeds a threshold (e.g., 15k tokens).
3. Tiered CLAUDE.md — support a CLAUDE.summary.md (compact, always loaded) vs CLAUDE.md (full, loaded on request). The sync engine generates the summary automatically.
4. Rule file consolidation — instead of N separate .claude/rules/*.md files, retort could bundle them into a single file during sync to reduce file-read overhead.

Context

• mystira-workspace has 5 rule files, 17 agents, 14 project-specific skills, 3 CLAUDE.md levels
• VS Code setting chat.includeReferencedInstructions causes all of these to be injected every turn
• This is the Add orchestration engine, workflow commands, and comprehensive documentation #1 contributor to context bloat based on analysis

[blocksorg]

Mention Blocks like a regular teammate with your question or request:

@blocks can you add technical details to this issue?
@blocks make the following changes ...
@blocks create an issue from what was mentioned in the following comment ...
@blocks explain the following code ...
@blocks are there any security or performance concerns?

Run @blocks /help for more information.

Workspace settings | Disable this message