feat(commands): add /context-budget optimizer command (#554)

* feat(commands): add /context-budget optimizer command

Adds a command that audits context window token consumption across
agents, skills, rules, MCP servers, and CLAUDE.md files.

Detects bloated agent descriptions, redundant components, MCP
over-subscription, and CLAUDE.md bloat. Produces a prioritized
report with specific token savings per optimization.

Directly relevant to #434 (agent descriptions too verbose, ~26k
tokens causing performance warnings).

* fix: address review feedback on context-budget command

- Add $ARGUMENTS to enable --verbose flag passthrough
- Fix MCP token estimate: 45 tools × ~500 tokens = ~22,500 (was ~2,200)
- Fix heavy agents example: all 3 now exceed 200-line threshold
- Fix description threshold: warning at >30 words, fail at >50 words
- Add Step 4 instructions (was empty)
- Fix audit cadence: "quarterly" → "regularly" + "monthly" consistently
- Fix Output Format heading level under Step 4
- Replace "Antigravity" with generic "harness versions"
- Recalculate total overhead to match corrected MCP numbers

* fix: correct MCP tool count and savings percentage in sample output

- Fix MCP tool count: table now shows 87 tools matching the issues
  section (was 45 in table vs 87 in issues)
- Fix savings percentage: 5,100 / 66,400 = 7.7% (was 20.6%)
- Recalculate total overhead and effective context to match

* fix: correct sample output arithmetic

- Fix total overhead: 66,400 → 66,100 to match component table sum
  (12,400 + 6,200 + 2,800 + 43,500 + 1,200 = 66,100)
- Fix MCP savings: ~1,500 → ~27,500 tokens (55 tools × 500 tokens/tool)
  to match the per-tool formula defined in Step 1
- Reorder optimizations by savings (MCP removal is now #1)
- Fix total savings and percentage (31,100 / 66,100 = 47.0%)

* fix: distinguish always-on vs on-demand agent overhead

Agent descriptions are always loaded into Task tool routing context,
but the full agent body is only loaded when invoked. The audit now
measures both: description-only tokens as always-on overhead and
full-file tokens as worst-case overhead. This resolves the
contradiction between Step 1 (counting full files) and Tip 1 (saying
only descriptions are loaded per session).

* fix: simplify agent accounting and resolve inconsistencies

- Revert to single agent overhead metric (full file tokens) — simpler
  and matches what the report actually displays
- Add back 200-line threshold for heavy agents in Step 1
- Fix heavy agents action to match issue type (split/trim, not
  description-only)
- Remove .agents/skills/ scan path (doesn't exist in ECC repo)
- Consolidate description threshold to single 30-word check

* fix: add model assumption and verbose mode activation

- Step 4: assume 200K context window by default (Claude has no way to
  introspect its model at runtime)
- Step 4: add explicit instruction to check $ARGUMENTS for --verbose
  flag and include additional output when present

* fix: handle .agents/skills/ duplicates in skill scan

Skills scan now checks .agents/skills/ for Codex harness copies and
skips identical duplicates to avoid double-counting overhead.

* fix: add savings estimate to heavy agents action for consistency

* feat(skills): add context-budget backing skill, slim command to delegator

* fix: use structurally detectable classification criteria instead of session frequency

---------

Co-authored-by: vazidmansuri005 <vazidmansuri005@users.noreply.github.com>

commands/context-budget.md

@@ -0,0 +1,29 @@
+---
+description: Analyze context window usage across agents, skills, MCP servers, and rules to find optimization opportunities. Helps reduce token overhead and avoid performance warnings.
+---
+
+# Context Budget Optimizer
+
+Analyze your Claude Code setup's context window consumption and produce actionable recommendations to reduce token overhead.
+
+## Usage
+
+```
+/context-budget [--verbose]
+```
+
+- Default: summary with top recommendations
+- `--verbose`: full breakdown per component
+
+$ARGUMENTS
+
+## What to Do
+
+Run the **context-budget** skill (`skills/context-budget/SKILL.md`) with the following inputs:
+
+1. Pass `--verbose` flag if present in `$ARGUMENTS`
+2. Assume a 200K context window (Claude Sonnet default) unless the user specifies otherwise
+3. Follow the skill's four phases: Inventory → Classify → Detect Issues → Report
+4. Output the formatted Context Budget Report to the user
+
+The skill handles all scanning logic, token estimation, issue detection, and report formatting.

skills/context-budget/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: context-budget
+description: Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.
+origin: ECC
+---
+
+# Context Budget
+
+Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.
+
+## When to Use
+
+- Session performance feels sluggish or output quality is degrading
+- You've recently added many skills, agents, or MCP servers
+- You want to know how much context headroom you actually have
+- Planning to add more components and need to know if there's room
+- Running `/context-budget` command (this skill backs it)
+
+## How It Works
+
+### Phase 1: Inventory
+
+Scan all component directories and estimate token consumption:
+
+**Agents** (`agents/*.md`)
+- Count lines and tokens per file (words × 1.3)
+- Extract `description` frontmatter length
+- Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)
+
+**Skills** (`skills/*/SKILL.md`)
+- Count tokens per SKILL.md
+- Flag: files >400 lines
+- Check for duplicate copies in `.agents/skills/` — skip identical copies to avoid double-counting
+
+**Rules** (`rules/**/*.md`)
+- Count tokens per file
+- Flag: files >100 lines
+- Detect content overlap between rule files in the same language module
+
+**MCP Servers** (`.mcp.json` or active MCP config)
+- Count configured servers and total tool count
+- Estimate schema overhead at ~500 tokens per tool
+- Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)
+
+**CLAUDE.md** (project + user-level)
+- Count tokens per file in the CLAUDE.md chain
+- Flag: combined total >300 lines
+
+### Phase 2: Classify
+
+Sort every component into a bucket:
+
+| Bucket | Criteria | Action |
+|--------|----------|--------|
+| **Always needed** | Referenced in CLAUDE.md, backs an active command, or matches current project type | Keep |
+| **Sometimes needed** | Domain-specific (e.g. language patterns), not referenced in CLAUDE.md | Consider on-demand activation |
+| **Rarely needed** | No command reference, overlapping content, or no obvious project match | Remove or lazy-load |
+
+### Phase 3: Detect Issues
+
+Identify the following problem patterns:
+
+- **Bloated agent descriptions** — description >30 words in frontmatter loads into every Task tool invocation
+- **Heavy agents** — files >200 lines inflate Task tool context on every spawn
+- **Redundant components** — skills that duplicate agent logic, rules that duplicate CLAUDE.md
+- **MCP over-subscription** — >10 servers, or servers wrapping CLI tools available for free
+- **CLAUDE.md bloat** — verbose explanations, outdated sections, instructions that should be rules
+
+### Phase 4: Report
+
+Produce the context budget report:
+
+```
+Context Budget Report
+═══════════════════════════════════════
+
+Total estimated overhead: ~XX,XXX tokens
+Context model: Claude Sonnet (200K window)
+Effective available context: ~XXX,XXX tokens (XX%)
+
+Component Breakdown:
+┌─────────────────┬────────┬───────────┐
+│ Component       │ Count  │ Tokens    │
+├─────────────────┼────────┼───────────┤
+│ Agents          │ N      │ ~X,XXX    │
+│ Skills          │ N      │ ~X,XXX    │
+│ Rules           │ N      │ ~X,XXX    │
+│ MCP tools       │ N      │ ~XX,XXX   │
+│ CLAUDE.md       │ N      │ ~X,XXX    │
+└─────────────────┴────────┴───────────┘
+
+⚠ Issues Found (N):
+[ranked by token savings]
+
+Top 3 Optimizations:
+1. [action] → save ~X,XXX tokens
+2. [action] → save ~X,XXX tokens
+3. [action] → save ~X,XXX tokens
+
+Potential savings: ~XX,XXX tokens (XX% of current overhead)
+```
+
+In verbose mode, additionally output per-file token counts, line-by-line breakdown of the heaviest files, specific redundant lines between overlapping components, and MCP tool list with per-tool schema size estimates.
+
+## Examples
+
+**Basic audit**
+```
+User: /context-budget
+Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
+       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
+       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)
+```
+
+**Verbose mode**
+```
+User: /context-budget --verbose
+Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
+       MCP tool list with per-tool sizes, duplicated rule lines side by side
+```
+
+**Pre-expansion check**
+```
+User: I want to add 5 more MCP servers, do I have room?
+Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
+       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%
+```
+
+## Best Practices
+
+- **Token estimation**: use `words × 1.3` for prose, `chars / 4` for code-heavy files
+- **MCP is the biggest lever**: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined
+- **Agent descriptions are loaded always**: even if the agent is never invoked, its description field is present in every Task tool context
+- **Verbose mode for debugging**: use when you need to pinpoint the exact files driving overhead, not for regular audits
+- **Audit after changes**: run after adding any agent, skill, or MCP server to catch creep early