The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: preserve cheap native context routing from PR 2740
haelyra807c98aff608
diff --cc manifests/context-packs/[email protected]index 5b82f9671,000000000..a34f0bef5mode 100644,000000..100644--- a/manifests/context-packs/[email protected]+++ b/manifests/context-packs/[email protected]@@@ -1,295 -1,0 +1,295 @@@+{+ "coverage": {+ "skills": 306,+ "withTriggers": 33+ },+ "generatedAt": "2026-09-24T23:51:22.784Z",+ "id": "skill-triggers@1",+ "model": {+ "effort": null,+ "id": "hand-seeded",+ "source": "manual-curation-pending-regeneration"+ },- "registryDigest": "55c884295c64fce1328cc906c6828fa4ce45606efec2f7e55887028e44b8b0a6",++ "registryDigest": "950e47846cda35f0cd2032e540bbb2c5bc14ad15590d18aae69450f757a12f64",+ "schemaVersion": 1,+ "triggers": {+ "skill:agent-runtime-gateway-smoke-test": [+ "test local agent gateway",+ "remote sandbox callback smoke test",+ "agent task stuck after dispatch",+ "verify gateway tunnel",+ "restore web api after agent test"+ ],+ "skill:api-connector-builder": [+ "add api integration",+ "new provider connector",+ "match existing integration pattern"+ ],+ "skill:api-design": [+ "rest endpoint design",+ "pagination api",+ "status codes",+ "api versioning",+ "rate limiting api",+ "resource naming",+ "filtering api",+ "api error responses",+ "offset pagination",+ "limit query parameter",+ "pagination defaults"+ ],+ "skill:backend-patterns": [+ "express api",+ "node backend architecture",+ "nextjs api routes",+ "server side patterns",+ "data access layer",+ "static file server",+ "url path handling",+ "file server"+ ],+ "skill:browser-qa": [+ "deployed feature test",+ "visual regression screenshots",+ "core web vitals check",+ "axe accessibility audit",+ "ship do not ship",+ "staging verification"+ ],+ "skill:canary-watch": [+ "post deploy monitoring",+ "smoke test url",+ "production url check",+ "console errors production",+ "sse stream check",+ "after deploy verification"+ ],+ "skill:code-tour": [+ "onboarding walkthrough",+ "explain subsystem",+ "architecture tour",+ "pr walkthrough",+ "rca tour"+ ],+ "skill:coding-standards": [+ "code review standards",+ "naming conventions",+ "readability review",+ "immutability conventions",+ "fix naming typo",+ "export naming",+ "consistent exports"+ ],+ "skill:content-hash-cache-pattern": [+ "cache file processing",+ "content addressed cache",+ "sha256 hash cache"+ ],+ "skill:database-migrations": [+ "zero downtime migration",+ "schema change production",+ "add column large table",+ "backfill data",+ "expand contract",+ "concurrent index",+ "migration rollback",+ "prisma migration",+ "django migration"+ ],+ "skill:deployment-patterns": [+ "ci cd setup",+ "dockerize app",+ "health checks",+ "rollback strategy",+ "production readiness",+ "deploy pipeline",+ "containerize application"+ ],+ "skill:design-system": [+ "design tokens",+ "visual consistency audit",+ "css custom properties",+ "ui audit",+ "design system bootstrap"+ ],+ "skill:django-patterns": [+ "django orm",+ "drf api",+ "django rest framework",+ "django caching",+ "django signals",+ "django middleware"+ ],+ "skill:django-security": [+ "django authentication",+ "csrf protection",+ "sql injection prevention",+ "xss prevention",+ "django deployment security",+ "role based access control",+ "authorization middleware",+ "permissions checks"+ ],+ "skill:docker-patterns": [+ "dockerfile review",+ "docker compose setup",+ "container security",+ "multi service orchestration"+ ],+ "skill:error-handling": [+ "error types",+ "retry logic",+ "circuit breaker",+ "user facing errors",+ "exception handling patterns",+ "typed errors",+ "error boundaries",+ "go error handling",+ "custom error class",+ "error codes",+ "config validation"+ ],+ "skill:evm-token-decimals": [+ "token decimals",+ "wei conversion",+ "erc20 balance off",+ "bridge token precision"+ ],+ "skill:frontend-a11y": [+ "aria attributes",+ "screen reader support",+ "focus management",+ "semantic html",+ "form labeling",+ "keyboard navigation react",+ "a11y lint errors"+ ],+ "skill:git-workflow": [+ "merge vs rebase",+ "commit conventions",+ "resolve merge conflict",+ "branching strategy",+ "clean up commits",+ "pull request cleanup",+ "git history tidy"+ ],+ "skill:hexagonal-architecture": [+ "ports and adapters",+ "dependency injection boundaries",+ "decouple domain from io"+ ],+ "skill:kubernetes-patterns": [+ "kubernetes manifests",+ "kubectl debugging",+ "pod probes",+ "k8s rbac",+ "autoscaling config",+ "configmap secrets"+ ],+ "skill:orch-fix-defect": [+ "fix a bug",+ "broken behavior",+ "regression fix",+ "reproduce bug",+ "defect repair"+ ],+ "skill:postgres-patterns": [+ "slow postgres query",+ "query optimization",+ "index design",+ "rls policies",+ "supabase schema",+ "postgres indexing",+ "database performance",+ "schema design postgres",+ "postgres driver",+ "node postgres",+ "query planner"+ ],+ "skill:python-patterns": [+ "pythonic code",+ "pep 8",+ "type hints python",+ "python code review",+ "idiomatic python"+ ],+ "skill:python-testing": [+ "pytest fixtures",+ "mocking python",+ "parametrized tests",+ "coverage python",+ "tdd python"+ ],+ "skill:redis-patterns": [+ "cache aside pattern",+ "distributed lock",+ "redis rate limiting",+ "cache invalidation"+ ],+ "skill:regex-vs-llm-structured-text": [+ "parse invoice",+ "extract receipt data",+ "text extraction pipeline",+ "parse form fields",+ "cheap document parser",+ "extract table data",+ "parse log lines",+ "parse access logs",+ "common log format",+ "log line parsing"+ ],+ "skill:rust-patterns": [+ "rust ownership",+ "borrow checker",+ "rust error handling",+ "traits rust",+ "rust concurrency",+ "idiomatic rust"+ ],+ "skill:search-first": [+ "find existing library",+ "npm package research",+ "before writing custom code",+ "evaluate existing tools",+ "add dependency research"+ ],+ "skill:security-review": [+ "security audit",+ "authentication review",+ "sanitize user input",+ "secrets handling",+ "payment security checklist",+ "prevent injection attacks",+ "secure api endpoints",+ "authn authz review",+ "vulnerability checklist",+ "input validation security",+ "parameterized queries",+ "sql injection"+ ],+ "skill:security-scan": [+ "audit claude config",+ "claudemd security",+ "mcp server audit",+ "agentshield scan",+ "hook configuration audit",+ "settings json security"+ ],+ "skill:tdd-workflow": [+ "write test first",+ "failing test",+ "red green refactor",+ "test driven development",+ "regression test first",+ "write a regression test"+ ],+ "skill:verification-loop": [+ "pre pr checks",+ "verification report",+ "quality gates",+ "build lint test coverage",+ "before creating a pr"+ ]+ },+ "triggersDigest": "054898acb769893c46e5bd7037141f7be83fb775515ea1dbb52fb1c18aca19e6"+}diff --cc skills/context-budget/SKILL.mdindex 084b30901,b5da5b2c6..d3bb1bcbb--- a/skills/context-budget/SKILL.md+++ b/skills/context-budget/SKILL.md@@@ -1,186 -1,78 +1,134 @@@---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. Use when the context window is filling up too fast and the agents, skills, MCP servers, or rules consuming it need to be identified.-description: Routes live context checks to the native Codex or Claude Code meter without scanning files, and performs a bounded static component audit only when explicitly requested.++description: Routes live context checks to the native Codex or Claude Code meter without scanning files, and performs a bounded static component audit only when explicitly requested. Use for context-budget requests about remaining capacity or installed context overhead.metadata:origin: ECC---# Context Budget- Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.+ Use the provider's native meter for live session usage. Keep the separate,+ estimated installation audit behind an explicit opt-in.- ## When to Use+ ## Default: Live Context- - 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)+ Treat an invocation with no audit request as a live-context request. This+ includes requests for the current window, remaining capacity, headroom, token+ usage, or a context breakdown.- ## How It Works+ For this default path:- ### Phase 1: Inventory+ - Do not call or use tools.+ - Do not scan or read files.+ - Do not run shell commands, provider CLIs, debug logging, or MCP discovery.+ - Reply with only the native command and one short explanation.- Scan all component directories and estimate token consumption:+ Route by the active harness:- **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)+ | Harness | Native command | Guidance |+ | --- | --- | --- |+ | Codex CLI | `/status` | Shows current token usage and remaining context capacity. Use `/statusline` and enable **Context stats** plus **Token counters** for a persistent footer meter. |++| Codex app | `/status` | Shows current thread context usage and rate limits. |+ | Claude Code | `/context` | Shows the live context breakdown. Use `/context all` for expanded items. |+ | Other or unknown | None verified | State that ECC cannot read live provider state and ask which harness is active. |- **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++These commands are documented in the [Codex command reference](https://developers.openai.com/codex/cli/slash-commands) and [Claude Code command reference](https://code.claude.com/docs/en/commands).+- **Rules** (`rules/**/*.md`)- - Count tokens per file- - Flag: files >100 lines- - Detect content overlap between rule files in the same language module+ A skill cannot invoke a TUI slash command on the user's behalf. Never replace+ the native command with an estimated scan and never infer an audit request from+ phrases such as “context is heavy” or “how much is left.”- **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`)+ ## Explicit Static Audit- **Persisted-record bytes** (optional)+ Run an installation/configuration audit only when the user explicitly says+ `--audit`, “audit installed components,” or equivalent unambiguous wording.+ `--verbose` changes report detail; it does not opt into an audit by itself.++ If the audit scope is ambiguous, ask for the harness and installation root+ before reading anything. Keep every audit bounded and read-only:++ 1. Inspect only the named plugin/install root and the named harness's known+ configuration files.+ 2. Never recursively enumerate the workspace root, home directory, provider+ cache, transcripts, debug logs, or unrelated worktrees.+ 3. Never launch a provider CLI, MCP server, or debug session to count tools.+ 4. Cap inventory output at 50 entries per component class. Summarize the rest.+ 5. Do not write temporary logs or copy configuration content into the report.++ Audit only the component metadata relevant to eager discovery:++ - agent and skill descriptions;+ - command descriptions when the harness discovers them eagerly;+ - always-loaded instruction files in the explicitly named scope;+ - configured MCP tool schemas when an existing bounded manifest exposes them.++ Full skill, agent, command, and rule bodies are generally on-demand content.+ Report their disk size separately from estimated eager overhead instead of+ adding every body to the session baseline.++ ## Audit Output++ Return a compact report containing:++ - harness and exact paths inspected;+ - estimated eager/discovery overhead by component class;+ - installed counts and the heaviest metadata entries;+ - assumptions, unavailable measurements, and up to three optimizations.++ Every calculated token number is an estimate of static configuration overhead,+ not live session context. Do not claim that an estimate is provider-reported,+ current, exact, or evidence of realized savings. Direct the user back to the+ native live-context command for current usage.++++## Optional Selected-Record Diagnostic++++Inspect a persisted record only when the user explicitly selects that file for this diagnostic. This is separate from the default live-context request and the installation audit.++For a local file diagnostic, explicitly select a stable, regular JSONL file or a snapshot you+intend to inspect. Replace the example path below; this does not find or reconnect a session.+The snippet prints aggregate byte counts only. It reads one line at a time, so memory use depends+on the largest record; avoid very large records and actively growing files.++```sh+python3 - "/path/to/selected-session.jsonl" <<'EOF'+import json+import sys++total = attachment = other = unclassified = 0+try:+ with open(sys.argv[1], "rb") as source:+ for raw in source:+ size = len(raw)+ total += size+ try:+ record = json.loads(raw.decode("utf-8"))+ except (UnicodeDecodeError, json.JSONDecodeError):+ unclassified += size+ continue+ record_type = record.get("type") if isinstance(record, dict) else None+ if not isinstance(record_type, str):+ unclassified += size+ elif record_type == "attachment":+ attachment += size+ else:+ other += size+except OSError:+ print("Cannot read selected JSONL file.", file=sys.stderr)+ raise SystemExit(1)++pct = attachment * 100.0 / total if total else 0.0+print(f"persisted {total}B | attachment records {attachment}B ({pct:.1f}%) | "+ f"other records {other}B | unclassified {unclassified}B")+EOF+```++The three categories add up to the original file bytes, including line endings and blank lines.+`attachment` is an exact record-type filter, not a guarantee about a harness's current internal+schema. Other records have a different string `type`; malformed JSON, invalid UTF-8, nonobject+values, missing or non-string types, and blank lines are unclassified. Neither category means+"conversation," and the percentage is only a share of persisted bytes.++These counts do not establish active context, remaining room, token usage, billing, or what a+reconnect loads. For current harness-reported context and usage, use the version-appropriate+[`/context` and `/usage` commands (`/cost` is an alias)](https://code.claude.com/docs/en/commands).+- **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 │- └─────────────────┴────────┴───────────┘-- WARNING: 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