Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(cost-tracker): consistency audit β€” agent + README mention all 13 skills (v0.16.1) (#1750)

rUv4f1580bf1827
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index 6730332ba6..385a27e49e 100644
--- a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
+++ b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-cost-tracker",
"description": "Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations β€” uses memory_* (namespace-routed) for cost-tracking and cost-patterns; pairs with federation budget circuit breaker (ADR-097)",
- "version": "0.16.0",
+ "version": "0.16.1",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-cost-tracker/README.md b/plugins/ruflo-cost-tracker/README.md
index 44645d3cb5..c57cbf2762 100644
--- a/plugins/ruflo-cost-tracker/README.md
+++ b/plugins/ruflo-cost-tracker/README.md
@@ -30,22 +30,29 @@ claude --plugin-dir plugins/ruflo-cost-tracker
| `cost-booster-edit` | `/cost-booster-edit <intent> <file>` | **Apply** a Tier 1 transform via `agent-booster.apply()` (sub-millisecond, $0, deterministic) |
| `cost-benchmark` | `/cost-benchmark [--llm] [--anthropic]` | Run the corpus benchmark and persist measured-vs-claimed table to `docs/benchmarks/runs/` |
| `cost-trend` | `/cost-trend` | Read all bench runs and surface drift (win rate, latency, speedup) β€” flags regressions the smoke gate misses |
+| `cost-conversation` | `/cost-conversation` | Per-conversation cost view (different lens from cost-report's per-agent / per-model) |
+| `cost-export` | `/cost-export [--prometheus <path>] [--webhook <url>]` | Emit cost data as Prometheus textfile or POST to a webhook |
+| `cost-federation` | `/cost-federation` | ADR-097 Phase 3 consumer β€” per-peer 1h/24h/7d federation_spend rolling windows |
+| `cost-summary` | `/cost-summary [--format json\|markdown]` | Single-shot programmatic dump of all cost data (stable JSON contract for inter-plugin consumption) |
| `cost-compact-context` | `/cost-compact-context <query>` | Wrap `getTokenOptimizer().getCompactContext()` for retrieval-compacted analysis (graceful fallback when agentic-flow not installed) |
-## Commands (8 subcommands)
+## Commands (15 subcommands)
```bash
cost track # Auto-capture this session's token usage (producer)
-cost budget set <amount> # Set USD budget (real impl, persists to cost-tracking)
-cost budget get # Show current budget config
-cost budget check [--period ...] # Compute utilization + alert; exit 1 on HARD_STOP
cost report [--period today|week|month] # Cost report (with By-tier block, reads measured booster data)
cost breakdown [--by agent|model|task] # Detailed breakdown by dimension
-cost budget set <amount> # Set budget limit in USD
cost optimize # Analyze usage and suggest savings (+ auto-emits hooks_model-outcome via outcome.mjs)
cost outcome <task> <model> <outcome> # Emit hooks_model-outcome (success|escalated|failure) so the router learns
+cost budget set <amount> # Set USD budget (real impl, persists to cost-tracking)
+cost budget get # Show current budget config
+cost budget check [--period ...] # Compute utilization + alert; exit 1 on HARD_STOP
cost benchmark [--llm] [--anthropic] # Run measured benchmark β€” booster + optional Gemini/Sonnet/Opus baselines
cost trend # Drift across bench runs (win rate, latency, regressions)
+cost conversation # Per-conversation cost view
+cost summary [--format json|markdown] # Programmatic JSON contract for inter-plugin consumption
+cost export [--prometheus] [--webhook] # External observability β€” Prometheus textfile + webhook POST
+cost federation # ADR-097 Phase 3 federation_spend consumer
cost workers # Inspect optimize + benchmark loop-workers consumed
cost history # Show cost tracking over time
```
diff --git a/plugins/ruflo-cost-tracker/agents/cost-analyst.md b/plugins/ruflo-cost-tracker/agents/cost-analyst.md
index 221ff6799f..b8806dd9ef 100644
--- a/plugins/ruflo-cost-tracker/agents/cost-analyst.md
+++ b/plugins/ruflo-cost-tracker/agents/cost-analyst.md
@@ -15,13 +15,35 @@ You are a cost analyst agent. Your responsibilities:
Model pricing per 1M tokens (Haiku/Sonnet/Opus Γ— Input/Output/Cache-Write/Cache-Read), the cost attribution formula, the four-tier budget alert ladder (50% / 75% / 90% / 100%), the optimization strategy catalog with savings ranges, and the standard cost-report markdown layout all live in [`REFERENCE.md`](../REFERENCE.md). Read it when you need a price, threshold, or report shape β€” keeping reference data out of the agent prompt costs ~50% fewer tokens per spawn (per ADR-098 Part 2).
-## Tools
-
-- `mcp__claude-flow__agentdb_hierarchical-store` β€” store usage records and budget configuration.
-- `mcp__claude-flow__agentdb_hierarchical-recall` β€” recall usage history and budget status.
-- `mcp__claude-flow__agentdb_pattern-store` β€” store cost optimization patterns.
-- `mcp__claude-flow__agentdb_pattern-search` β€” search for cost reduction strategies.
-- `mcp__claude-flow__agentdb_semantic-route` β€” route cost queries to relevant data.
+## Skills (13 β€” what each does, when to invoke)
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `cost-track` | **Producer** β€” reads session jsonl, persists per-session usage to `cost-tracking` | After significant work; cron-friendly |
+| `cost-report` | Per-agent / per-model narrative report (with By-tier block) | User asks for a cost report |
+| `cost-optimize` | Recommend downgrades + auto-emit `hooks_model-outcome` | Cost is higher than expected |
+| `cost-budget-check` | 50/75/90/100% alert ladder; exit 1 on HARD_STOP | Before spawning swarms; cron-friendly |
+| `cost-conversation` | Per-conversation cost view (different lens from cost-report) | "Which conversations cost the most?" |
+| `cost-summary` | Stable JSON contract for inter-plugin consumption | Another plugin/dashboard needs a snapshot |
+| `cost-trend` | Drift across `runs/*.json` β€” flags regressions the binary smoke gate misses | Pre-release audit |
+| `cost-export` | Prometheus textfile + webhook POST | External observability dashboards |
+| `cost-federation` | ADR-097 Phase 3 consumer β€” per-peer 1h/24h/7d windows | After Phase 3 emits federation_spend events |
+| `cost-benchmark` | Run the corpus harness β€” booster + optional Gemini/Sonnet/Opus | Verifying speedup claims, regression check |
+| `cost-booster-route` | Wrap `hooks_route`, partition by `[AGENT_BOOSTER_AVAILABLE]` | Audit how many tasks would route to Tier 1 |
+| `cost-booster-edit` | Apply a Tier 1 transform via `agent-booster.apply()` | When a transform is already classified as Tier 1 |
+| `cost-compact-context` | Wrap `getTokenOptimizer().getCompactContext()` | Retrieval-augmented prompt compression |
+
+`cost track` populates the namespace; everything else consumes it. Run `cost-track` first or other skills will operate on empty data.
+
+## Tools (MCP-routed primary path)
+
+- `mcp__claude-flow__memory_store` β€” store usage records, budget config, optimization patterns (the `memory_*` family is namespace-routed; prefer this over `agentdb_hierarchical-*`)
+- `mcp__claude-flow__memory_search` / `memory_list` / `memory_retrieve` β€” read cost-tracking + cost-patterns namespaces
+- `mcp__claude-flow__memory_delete` β€” clean up stale config (used by budget upsert-via-timestamp pattern)
+- `mcp__claude-flow__hooks_route` β€” invoked by `cost-booster-route`
+- `mcp__claude-flow__hooks_model-outcome` β€” invoked by `cost-optimize` step 8 (auto-emits via `outcome.mjs`)
+- `mcp__claude-flow__hooks_worker-status` β€” `cost workers` subcommand (consumes `optimize` + `benchmark` worker outputs)
+- `mcp__claude-flow__agentdb_pattern-store` / `_pattern-search` β€” ReasoningBank-routed (no namespace arg) for typed cost-optimization patterns
## Agent Booster (direct invocation, $0/edit, ~1 ms measured)
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
index 11880460f6..56326ded13 100755
--- a/plugins/ruflo-cost-tracker/scripts/smoke.sh
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -8,10 +8,10 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.16.0 with new keywords"
+step "1. plugin.json declares 0.16.1 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.16.0" ]]; then
- bad "expected 0.16.0, got '$v'"
+if [[ "$v" != "0.16.1" ]]; then
+ bad "expected 0.16.1, got '$v'"
else
miss=""
for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified telemetry budget; do
@@ -391,5 +391,36 @@ grep -q "winRate" "$WF" || miss="$miss no-regression-gate"
grep -q "BENCH_ANTHROPIC\|BENCH_LLM_BASELINE" "$WF" && miss="$miss llm-cost-in-CI"
[[ -z "$miss" ]] && ok || bad "$miss"
+# ─── Consistency invariants (prevent README/agent drift) ─────────────────────
+
+step "41. cost-analyst.md mentions every skill in skills/"
+F="$ROOT/agents/cost-analyst.md"
+miss=""
+for d in "$ROOT"/skills/*/; do
+ name=$(basename "$d")
+ grep -q "$name" "$F" 2>/dev/null || miss="$miss $name"
+done
+[[ -z "$miss" ]] && ok || bad "agent does not mention:$miss"
+
+step "42. README.md skills table has a row for every skill in skills/"
+F="$ROOT/README.md"
+miss=""
+for d in "$ROOT"/skills/*/; do
+ name=$(basename "$d")
+ grep -qE "\\| \`$name\`" "$F" 2>/dev/null || miss="$miss $name"
+done
+[[ -z "$miss" ]] && ok || bad "README skills table missing:$miss"
+
+step "43. every script in scripts/*.mjs parses cleanly"
+miss=""
+for f in "$ROOT"/scripts/*.mjs; do
+ node --check "$f" 2>/dev/null || miss="$miss $(basename "$f")"
+done
+[[ -z "$miss" ]] && ok || bad "syntax errors:$miss"
+
+step "44. plugin.json parses + version sentinel matches step 1"
+node -e "JSON.parse(require('fs').readFileSync('$ROOT/.claude-plugin/plugin.json'))" 2>/dev/null \
+ && ok || bad "plugin.json invalid JSON"
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1