▋
agent/clankie-perf/SKILL.md

name: clankie-perf description: >- Clankie agent-orchestration performance hub (mission runs, lead/worker friction, skill efficacy) — archive orchestration runs as data points, aggregate metrics and trends, regenerate the static dashboard. Use when asked how Clankie's agent runs are performing, to archive/review a clankie-lead run, to update the performance dashboard, or to check whether skill fixes reduced friction. NOT for app/UI/runtime code performance — that's ordinary profiling in the app repo.

Clankie Performance Hub

The hub for improving Clankie's skills and orchestration performance with real data instead of vibes. Data lives in ${CLANKIE_RUN_ARCHIVE:-~/.clankie/run-archive}/ (one dir per run — schema in that directory's README.md); this skill is how an agent plugs into it.

Set OP="<this skill's directory>/scripts" once.

Answer "how is Clankie doing?"

node "$OP/report.mjs"          # markdown digest: totals, alerts, trends, per-run, action items
node "$OP/report.mjs" --json   # same, machine-readable

Read <archive>/<run-id>/review.md for the qualitative story behind any run. The headline reading order: alerts first (bad closes / violations / stale action items), then friction trend, then outcomes. Rising throughput with a bad close shipped is a regression, not progress.

Archive a run (turn a run into a data point)

  1. Mechanical snapshot (idempotent — re-run when an in-flight run completes): 
    "$OP/archive-run.sh" <run-id> --lead-pane <pane-id> --session <lead-session.jsonl>
    The lead's session jsonl lives under ~/.claude/projects/<project-dir>/<session-id>.jsonl; get the session id from herdr pane list (agent_session_id of the lead pane).
  2. Author review.md — the reviewer must not be the run's lead (a lead grading itself is a weak signal). Cover: protocol adherence, what went well, defects/improvables, verdict. Anchor every claim in the snapshot artifacts.
  3. Author metrics.json from the generated metrics-TEMPLATE.json. Keep field names stable across runs — comparability is the entire point. The driver block (harness/model/brain/skills) is the key comparison axis: it separates "the skills are good" from "the harness is good".
  4. Update <archive>/action-items.json: add newly surfaced fixes; for existing items, move open → applied when the fix lands in its target skill, and applied → validated (set validated_run) when a later run shows the validates_metric dropped. This ledger is the improvement loop.
  5. Regenerate the dashboard (below) and mention the archive in your summary.
  6. Commit and push: the archive is a private git repo (<owner>/clankie-run-archive) with a gitleaks pre-commit gate. Raw session transcripts and pane scrollbacks are gitignored — they may carry tokens; commit one only after an explicit gitleaks detect pass on the file, with git add -f. Runtime credential files never get committed under any circumstances.

Regenerate / view the dashboard

node "$OP/build-dashboard.mjs"                 # -> <archive>/dashboard.html
open "${CLANKIE_RUN_ARCHIVE:-$HOME/.clankie/run-archive}/dashboard.html"

Self-contained static HTML (data inlined at build time) — rebuild after any archive or ledger change. It renders KPI tiles, the rubric heatmap, friction / safety / outcomes per run, the action-item ledger, and the run log.

Gotchas

  • Mid-run snapshots are fine and useful — set snapshot_state: "in-flight" in metrics.json and re-run archive-run.sh at run end (it refreshes run-dir-snapshot/ without touching authored review/metrics).
  • metrics.json without a review.md gets flagged by the report as a weak data point — numbers without the qualitative story don't teach anything.
  • Friction counts only mean something relative to mission size; eyeball scale.workers_spawned / wall-clock before celebrating a drop.
  • When comparing drivers (e.g. claude-code manual-skill-driven vs eve-native), compare runs of the same mission class; a triage swarm and a build wave have different natural friction profiles.