The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: salvage cost tracking and skill scout (#1815)
Affaan Mustafa65c1502ecd28
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex a2b76bbe5..e39cefd5e 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -11,7 +11,7 @@{"name": "ecc","source": "./",- "description": "The most comprehensive Claude Code plugin — 60 agents, 221 skills, 74 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",+ "description": "The most comprehensive Claude Code plugin — 60 agents, 223 skills, 75 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning","version": "2.0.0-rc.1","author": {"name": "Affaan Mustafa",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 95f1fabb1..56664e1f2 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ecc","version": "2.0.0-rc.1",- "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 221 skills, 74 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",+ "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 223 skills, 75 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use","author": {"name": "Affaan Mustafa","url": "https://x.com/affaanmustafa"diff --git a/AGENTS.md b/AGENTS.mdindex 2c8b05df6..748fd9596 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — Agent Instructions-This is a **production-ready AI coding plugin** providing 60 specialized agents, 221 skills, 74 commands, and automated hook workflows for software development.+This is a **production-ready AI coding plugin** providing 60 specialized agents, 223 skills, 75 commands, and automated hook workflows for software development.**Version:** 2.0.0-rc.1@@ -150,8 +150,8 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat```agents/ — 60 specialized subagents-skills/ — 221 workflow skills and domain knowledge-commands/ — 74 slash commands+skills/ — 223 workflow skills and domain knowledge+commands/ — 75 slash commandshooks/ — Trigger-based automationsrules/ — Always-follow guidelines (common + per-language)scripts/ — Cross-platform Node.js utilitiesdiff --git a/README.md b/README.mdindex 7b3851a4c..f8763680b 100644--- a/README.md+++ b/README.md@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:/plugin list ecc@ecc```-**That's it!** You now have access to 60 agents, 221 skills, and 74 legacy command shims.+**That's it!** You now have access to 60 agents, 223 skills, and 75 legacy command shims.### Dashboard GUI@@ -1361,8 +1361,8 @@ The configuration is automatically detected from `.opencode/opencode.json`.| Feature | Claude Code | OpenCode | Status ||---------|-------------|----------|--------|| Agents | PASS: 60 agents | PASS: 12 agents | **Claude Code leads** |-| Commands | PASS: 74 commands | PASS: 35 commands | **Claude Code leads** |-| Skills | PASS: 221 skills | PASS: 37 skills | **Claude Code leads** |+| Commands | PASS: 75 commands | PASS: 35 commands | **Claude Code leads** |+| Skills | PASS: 223 skills | PASS: 37 skills | **Claude Code leads** || Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** || Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** || MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |@@ -1466,8 +1466,8 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **Agents** | 60 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |-| **Commands** | 74 | Shared | Instruction-based | 35 |-| **Skills** | 221 | Shared | 10 (native format) | 37 |+| **Commands** | 75 | Shared | Instruction-based | 35 |+| **Skills** | 223 | Shared | 10 (native format) | 37 || **Hook Events** | 8 types | 15 types | None yet | 11 types || **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks || **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions |diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 894bf8528..1c048940c 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**完成!** 你现在可以使用 60 个代理、221 个技能和 74 个命令。+**完成!** 你现在可以使用 60 个代理、223 个技能和 75 个命令。### multi-* 命令需要额外配置diff --git a/agent.yaml b/agent.yamlindex 4808ec659..658ad362f 100644--- a/agent.yaml+++ b/agent.yaml@@ -158,6 +158,7 @@ commands:- build-fix- checkpoint- code-review+ - cost-report- cpp-build- cpp-review- cpp-testdiff --git a/commands/cost-report.md b/commands/cost-report.mdnew file mode 100644index 000000000..adf2d2522--- /dev/null+++ b/commands/cost-report.md@@ -0,0 +1,107 @@+---+description: Generate a local Claude Code cost report from a cost-tracker SQLite database.+argument-hint: [csv]+---++# Cost Report++Query the local cost-tracking database and present a spending report by day,+project, tool, and session. This command assumes a cost-tracking hook or plugin+is already writing usage rows to `~/.claude-cost-tracker/usage.db`.++## What This Command Does++1. Check that `sqlite3` is available.+2. Check that `~/.claude-cost-tracker/usage.db` exists.+3. Run aggregate queries against the `usage` table.+4. Present a compact report, or export recent rows as CSV when the argument is+ `csv`.++## Prerequisites++The database must be populated by a local cost tracker. If the file is missing,+tell the user the tracker is not set up and suggest installing or enabling a+trusted Claude Code cost-tracking hook/plugin first.++```bash+test -f ~/.claude-cost-tracker/usage.db && echo "Database found" || echo "Database not found"+```++## Summary Query++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT+ ROUND(COALESCE(SUM(CASE WHEN date(timestamp) = date('now') THEN cost_usd END), 0), 4) AS today_cost,+ ROUND(COALESCE(SUM(CASE WHEN date(timestamp) = date('now', '-1 day') THEN cost_usd END), 0), 4) AS yesterday_cost,+ ROUND(COALESCE(SUM(cost_usd), 0), 4) AS total_cost,+ COUNT(*) AS total_calls,+ COUNT(DISTINCT session_id) AS sessions+ FROM usage;+"+```++## Project Breakdown++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT project, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY project+ ORDER BY cost DESC;+"+```++## Tool Breakdown++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT tool_name, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY tool_name+ ORDER BY cost DESC;+"+```++## Last Seven Days++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT date(timestamp) AS date, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY date(timestamp)+ ORDER BY date DESC+ LIMIT 7;+"+```++## CSV Export++If the user asks for `/cost-report csv`, export the most recent usage rows with+an explicit column list:++```bash+sqlite3 -csv -header ~/.claude-cost-tracker/usage.db "+ SELECT timestamp, project, tool_name, input_tokens, output_tokens, cost_usd, session_id, model+ FROM usage+ ORDER BY timestamp DESC+ LIMIT 100;+"+```++## Report Format++Format the response as:++1. Summary: today, yesterday, total, calls, sessions.+2. By project: projects ranked by total cost.+3. By tool: tools ranked by total cost.+4. Last seven days: date, cost, call count.++Use four decimal places for sub-dollar amounts. Do not estimate pricing from raw+tokens in this command; rely on the precomputed `cost_usd` values written by the+tracker.++## Source++Salvaged from stale community PR #1304 by `MayurBhavsar`.diff --git a/docs/stale-pr-salvage-ledger.md b/docs/stale-pr-salvage-ledger.mdindex ac80dc2ed..26a6f1014 100644--- a/docs/stale-pr-salvage-ledger.md+++ b/docs/stale-pr-salvage-ledger.md@@ -19,6 +19,8 @@ on fresh branches, and credit the source PR.| Source PR | Original contribution | Salvage result || --- | --- | --- |+| #1232 | `skill-scout` search-before-creating workflow | Salvaged in the May 12 cost/skill-scout maintainer pass with current repo wording, external-source vetting, and no stale catalog-count edits. |+| #1304 | Cost tracking skill and `/cost-report` command | Salvaged in the May 12 cost/skill-scout maintainer pass with current command/skill conventions and without stale hard-coded model pricing. || #1309 | Trading/community project material | Salvaged in #1761 as a neutral community-project README listing. || #1310 | Django reviewer, build resolver, and Celery async task guidance | Salvaged in the May 12 Django/Celery maintainer pass with current catalog counts and minor example cleanup. || #1322 | Vietnamese README translation | Salvaged in #1764 as `docs/vi-VN/README.md` plus selector updates. |diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.mdindex 1259a0ca5..0988b66d9 100644--- a/docs/zh-CN/AGENTS.md+++ b/docs/zh-CN/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — 智能体指令-这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、221 项技能、74 条命令以及自动化钩子工作流,用于软件开发。+这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、223 项技能、75 条命令以及自动化钩子工作流,用于软件开发。**版本:** 2.0.0-rc.1@@ -147,8 +147,8 @@```agents/ — 60 个专业子代理-skills/ — 221 个工作流技能和领域知识-commands/ — 74 个斜杠命令+skills/ — 223 个工作流技能和领域知识+commands/ — 75 个斜杠命令hooks/ — 基于触发的自动化rules/ — 始终遵循的指导方针(通用 + 每种语言)scripts/ — 跨平台 Node.js 实用工具diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.mdindex 863dc6380..3bc41efba 100644--- a/docs/zh-CN/README.md+++ b/docs/zh-CN/README.md@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**搞定!** 你现在可以使用 60 个智能体、221 项技能和 74 个命令了。+**搞定!** 你现在可以使用 60 个智能体、223 项技能和 75 个命令了。***@@ -1137,8 +1137,8 @@ opencode| 功能特性 | Claude Code | OpenCode | 状态 ||---------|-------------|----------|--------|| 智能体 | PASS: 60 个 | PASS: 12 个 | **Claude Code 领先** |-| 命令 | PASS: 74 个 | PASS: 35 个 | **Claude Code 领先** |-| 技能 | PASS: 221 项 | PASS: 37 项 | **Claude Code 领先** |+| 命令 | PASS: 75 个 | PASS: 35 个 | **Claude Code 领先** |+| 技能 | PASS: 223 项 | PASS: 37 项 | **Claude Code 领先** || 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** || 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** || MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |@@ -1245,8 +1245,8 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以| 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **智能体** | 60 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |-| **命令** | 74 | 共享 | 基于指令 | 35 |-| **技能** | 221 | 共享 | 10 (原生格式) | 37 |+| **命令** | 75 | 共享 | 基于指令 | 35 |+| **技能** | 223 | 共享 | 10 (原生格式) | 37 || **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 || **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 || **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |diff --git a/manifests/install-modules.json b/manifests/install-modules.jsonindex c6c3477c5..9cfb51cdc 100644--- a/manifests/install-modules.json+++ b/manifests/install-modules.json@@ -236,6 +236,7 @@"skills/iterative-retrieval","skills/plankton-code-quality","skills/production-audit",+ "skills/skill-scout","skills/skill-stocktake","skills/strategic-compact","skills/tdd-workflow",@@ -369,6 +370,7 @@"skills/automation-audit-ops","skills/api-connector-builder","skills/connections-optimizer",+ "skills/cost-tracking","skills/customer-billing-ops","skills/dashboard-builder","skills/ecc-tools-cost-audit",diff --git a/package.json b/package.jsonindex 84715ac4c..bbe28af05 100644--- a/package.json+++ b/package.json@@ -124,6 +124,7 @@"skills/continuous-learning/","skills/continuous-learning-v2/","skills/cost-aware-llm-pipeline/",+ "skills/cost-tracking/","skills/council/","skills/cpp-coding-standards/","skills/cpp-testing/",@@ -241,6 +242,7 @@"skills/security-review/","skills/security-scan/","skills/seo/",+ "skills/skill-scout/","skills/skill-stocktake/","skills/social-graph-ranker/","skills/springboot-patterns/",diff --git a/skills/cost-tracking/SKILL.md b/skills/cost-tracking/SKILL.mdnew file mode 100644index 000000000..d9d5fd479--- /dev/null+++ b/skills/cost-tracking/SKILL.md@@ -0,0 +1,147 @@+---+name: cost-tracking+description: Track and report Claude Code token usage, spending, and budgets from a local cost-tracking database. Use when the user asks about costs, spending, usage, tokens, budgets, or cost breakdowns by project, tool, session, or date.+origin: community+---++# Cost Tracking++Use this skill to analyze Claude Code cost and usage history from a local SQLite+database. It is intended for users who already have a cost-tracking hook or+plugin writing usage rows to `~/.claude-cost-tracker/usage.db`.++Source: salvaged from stale community PR #1304 by `MayurBhavsar`.++## When to Use++- The user asks "how much have I spent?", "what did this session cost?", or+ "what is my token usage?"+- The user mentions budgets, spending limits, overruns, or cost controls.+- The user wants a cost breakdown by project, tool, session, model, or date.+- The user wants to compare today against yesterday or inspect a recent trend.+- The user asks for a CSV export of recent usage records.++## How It Works++First verify prerequisites:++```bash+command -v sqlite3 >/dev/null && echo "sqlite3 available" || echo "sqlite3 missing"+test -f ~/.claude-cost-tracker/usage.db && echo "Database found" || echo "Database not found"+```++If the database is missing, do not fabricate usage data. Tell the user that cost+tracking is not configured and suggest installing or enabling a trusted local+cost-tracking hook/plugin.++The expected `usage` table usually contains one row per tool call or model+interaction. Column names vary by tracker, but the examples below assume:++| Column | Meaning |+| --- | --- |+| `timestamp` | ISO timestamp for the usage event |+| `project` | Project or repository name |+| `tool_name` | Tool or event name |+| `input_tokens` | Input token count, when recorded |+| `output_tokens` | Output token count, when recorded |+| `cost_usd` | Precomputed cost in USD |+| `session_id` | Claude Code session identifier |+| `model` | Model used for the event |++Prefer `cost_usd` over hand-calculating pricing. Model prices and cache pricing+change over time, and the tracker should be the source of truth for how each row+was priced.++## Examples++### Quick Summary++```bash+sqlite3 ~/.claude-cost-tracker/usage.db "+ SELECT+ 'Today: $' || ROUND(COALESCE(SUM(CASE WHEN date(timestamp) = date('now') THEN cost_usd END), 0), 4) ||+ ' | Total: $' || ROUND(COALESCE(SUM(cost_usd), 0), 4) ||+ ' | Calls: ' || COUNT(*) ||+ ' | Sessions: ' || COUNT(DISTINCT session_id)+ FROM usage;+"+```++### Cost By Project++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT project, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY project+ ORDER BY cost DESC;+"+```++### Cost By Tool++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT tool_name, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY tool_name+ ORDER BY cost DESC;+"+```++### Last Seven Days++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT date(timestamp) AS date, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls+ FROM usage+ GROUP BY date(timestamp)+ ORDER BY date DESC+ LIMIT 7;+"+```++### Session Drilldown++```bash+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "+ SELECT session_id,+ MIN(timestamp) AS started,+ MAX(timestamp) AS ended,+ ROUND(SUM(cost_usd), 4) AS cost,+ COUNT(*) AS calls+ FROM usage+ GROUP BY session_id+ ORDER BY started DESC+ LIMIT 10;+"+```++## Reporting Guidance++When presenting cost data, include:++1. Today's spend and yesterday comparison.+2. Total spend across the tracked database.+3. Top projects ranked by cost.+4. Top tools ranked by cost.+5. Session count and average cost per session when enough data exists.++For small amounts, format currency with four decimal places. For larger amounts,+two decimals are enough.++## Anti-Patterns++- Do not estimate costs from raw token counts when `cost_usd` is present.+- Do not assume the database exists without checking.+- Do not run unbounded `SELECT *` exports on large databases.+- Do not hard-code current model pricing in user-facing answers.+- Do not recommend installing unreviewed hooks or plugins that execute arbitrary+ code.++## Related++- `/cost-report` - Command-form report using the same database.+- `cost-aware-llm-pipeline` - Model-routing and budget-design patterns.+- `token-budget-advisor` - Context and token-budget planning.+- `strategic-compact` - Context compaction to reduce repeated token spend.diff --git a/skills/skill-scout/SKILL.md b/skills/skill-scout/SKILL.mdnew file mode 100644index 000000000..780f4e849--- /dev/null+++ b/skills/skill-scout/SKILL.md@@ -0,0 +1,140 @@+---+name: skill-scout+description: Search existing local, marketplace, GitHub, and web skill sources before creating a new skill. Use when the user wants to create, build, fork, or find a skill for a workflow.+origin: community+---++# Skill Scout++Use this skill before creating a new skill. The goal is to avoid duplicating+existing community or marketplace work, while still vetting anything external+before adoption.++Source: salvaged from stale community PR #1232 by `redminwang`.++## When to Use++- The user says "create a skill", "build a skill", "make a skill", or "new+ skill".+- The user asks "is there a skill for X?" or "does a skill exist that does Y?"+- The user describes a workflow and you are about to suggest creating a new+ skill.+- The user wants to fork or extend an existing skill.++If the user explicitly says to skip search or create from scratch, acknowledge+that and proceed with the requested creation workflow.++## How It Works++### Step 1 - Capture Intent++Extract:++- The task the skill should perform.+- The trigger conditions for using it.+- The domain, tools, frameworks, or data sources involved.+- Three to five search keywords plus useful synonyms.++### Step 2 - Search Local Sources++Search installed and marketplace skill names first. Local sources are preferred+because they are already part of the user's environment.++```bash+find ~/.claude/skills -maxdepth 2 -name SKILL.md 2>/dev/null | grep -iE "keyword|synonym"+find ~/.claude/plugins/marketplaces -path '*/skills/*/SKILL.md' 2>/dev/null | grep -iE "keyword|synonym"+```++Then search frontmatter descriptions:++```bash+grep -RilE "keyword|synonym" ~/.claude/skills ~/.claude/plugins/marketplaces 2>/dev/null+```++### Step 3 - Search Remote Sources++Use available GitHub and web search tools. Prefer concise queries:++```bash+gh search repos "claude code skill keyword" --limit 10 --sort stars+gh search code "name: keyword" --filename SKILL.md --limit 10+```++For web search, use at most three targeted queries such as:++```text+"claude code skill" keyword+"SKILL.md" keyword+"everything-claude-code" keyword+```++### Step 4 - Vet External Matches++Before recommending any external skill for adoption or forking:++- Read the `SKILL.md` frontmatter and instructions.+- Look for unexpected shell commands, file writes, network calls, credential+ handling, or package installs.+- Check whether the repository appears maintained.+- Prefer copying into a fresh local branch and reviewing the diff over editing+ marketplace originals.++### Step 5 - Rank Results++Rank candidates by:++1. Exact keyword match in the skill name.+2. Keyword or synonym match in description.+3. Local installed or marketplace source.+4. Maintained GitHub source with recent activity.+5. Web-only mention.++Cap the final list at 10 results.++### Step 6 - Present Decision Options++Give the user a short table:++| Option | Meaning |+| --- | --- |+| Use existing | Invoke or install a matching skill as-is. |+| Fork or extend | Copy the closest skill and modify it. |+| Create fresh | Build a new skill after confirming no close match exists. |++Only create a new skill after the user chooses that path or after the search+finds no close match.++## Examples++### Result Table++```markdown+| # | Skill | Source | Why it matches | Gap |+| --- | --- | --- | --- | --- |+| 1 | article-writing | Local ECC | Drafts articles and guides | Not focused on release notes |+| 2 | content-engine | Local ECC | Multi-format content workflow | Heavier than needed |+| 3 | blog-writer | GitHub | Blog writing skill with recent commits | Needs security review |+```++### User-Facing Summary++```markdown+I found two close local matches and one external candidate. The closest fit is+`article-writing`; it covers drafting and revision, but it does not include the+release-note checklist you asked for. I can either use it as-is, fork it into a+release-note variant, or create a fresh skill.+```++## Anti-Patterns++- Do not jump directly to new skill creation when a search is reasonable.+- Do not install external skills without reading them first.+- Do not present a long unranked list of weak matches.+- Do not treat web-only mentions as trusted sources.+- Do not edit installed marketplace originals in place.++## Related++- `search-first` - General search-before-building workflow.+- `skill-stocktake` - Audit installed skills for health, duplicates, and gaps.+- `agent-sort` - Categorize and organize existing agents and skills.diff --git a/tests/docs/stale-pr-salvage-ledger.test.js b/tests/docs/stale-pr-salvage-ledger.test.jsindex 9d2e1a3d1..63934ec1e 100644--- a/tests/docs/stale-pr-salvage-ledger.test.js+++ b/tests/docs/stale-pr-salvage-ledger.test.js@@ -46,6 +46,8 @@ test('stale PR salvage ledger preserves representative source attribution', () =for (const pr of ['#1309',+ '#1232',+ '#1304','#1322','#1326','#1310',