Skip to content

armgit / ECC

Public Imported from GitHub
0

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..a34f0bef5
mode 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.md
index 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