{
  "markdown": "# ⚗ Meta-Harness-YGN\n\n**Don't guess. Evolve. Prove.**\n\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin%20%2F%2Fmh-5A67D8?logo=anthropic&logoColor=white)](https://claude.ai/code)\n[![License MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/yannabadie/Meta-Harness-YGN?style=flat)](https://github.com/yannabadie/Meta-Harness-YGN/stargazers)\n[![Version](https://img.shields.io/badge/version-v1.0.0-blue)](https://github.com/yannabadie/Meta-Harness-YGN/releases)\n\n---\n\n## The Problem\n\nYou've spent hours tweaking your CLAUDE.md, writing custom skills, adjusting agent prompts. But you have **no idea if any of it actually helped.** Did that new rule reduce errors? Did that prompt rewrite cost more tokens? Did the last edit break something that used to work?\n\nEvery other approach to harness optimization is guesswork:\n\n- **Edit, hope, repeat** — no measurement, no history, no rollback\n- **Copy someone else's CLAUDE.md** — their project isn't yours\n- **Add more instructions** — research shows this often makes things worse (ETH Zurich: LLM-generated context files degrade performance by 3%)\n\n## The Solution\n\nMeta-Harness turns harness engineering into a **scientific process**:\n\n1. **You describe what to improve** — `/mh:evolve \"reduce tool thrashing on refactoring tasks\"`\n2. **The plugin proposes a controlled change** — one hypothesis, one patch, with predicted impact and risk assessment\n3. **It evaluates the change with evidence** — 9 deterministic checks, not vibes\n4. **It tracks everything on a Pareto frontier** — score vs. latency vs. token cost, so you see trade-offs\n5. **If something regresses, it explains why** — causal analysis, not just \"score went down\"\n\nEvery improvement has a measured before/after delta. Every regression has a diagnosis. Nothing is lost.\n\n---\n\n## What Can You Do With It?\n\n### \"My CLAUDE.md is 300 lines and I don't know what's helping\"\n\n```\n/mh:eval\n```\n\nRuns 9 deterministic checks against your current harness. Shows exactly what's valid, what's broken, and what's untested. Then:\n\n```\n/mh:evolve \"simplify CLAUDE.md — remove instructions Claude follows without being told\"\n```\n\nThe proposer reads your CLAUDE.md, compares against actual Claude behavior, and suggests specific deletions with predicted token savings.\n\n### \"Claude keeps editing files it shouldn't touch\"\n\n```\n/mh:evolve \"add scope constraints to prevent application code edits\"\n```\n\nThe proposer creates a `.claude/rules/` file with path-scoped constraints. The evaluator checks that the `files_in_scope` guard passes. If promoted, the change is tracked with a reversible patch.\n\n### \"Someone changed the prompts and now everything is worse\"\n\n```\n/mh:regressions\n```\n\nShows which run caused the score drop, compares the patch diff against the frontier leader, and identifies confounds (\"prompt rewrite and stop condition changed simultaneously — test them in isolation\").\n\n```\n/mh:rollback run-0011\n```\n\nReverse-applies the patch with a safety git tag. One command, no risk.\n\n### \"I want to optimize but I don't know where to start\"\n\n```\n/mh:bootstrap\n```\n\nAnalyzes your project — CLAUDE.md, rules, skills, agents, git history, installed plugins — and generates initial eval tasks. Creates both regression tests (things that should always work) and capability tests (things you want to improve).\n\n### \"I have 8 plugins installed but no idea how they interact\"\n\n```\n/mh:dashboard\n```\n\nScans all installed Claude Code plugins, maps their skill/agent/hook surfaces, shows your Pareto frontier, eval health, and active regressions in one view.\n\n### \"I want to know if my harness is actually getting better over time\"\n\nRun `/mh:evolve` repeatedly. Each run is recorded on the Pareto frontier with full metrics:\n\n```\n◆ FRONTIER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n| Run       | Score | Latency | Tokens | Risk |\n|-----------|-------|---------|--------|------|\n| run-0012  | 0.82  | 7340ms  | 10.9K  | low  |\n| run-0009  | 0.76  | 7800ms  | 12.1K  | low  |\n| run-0006  | 0.95  | 5200ms  | 8.5K   | low  |\n\nNon-dominated: 3 | Total runs: 12\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\nOnly non-dominated candidates stay on the frontier. You always know the best trade-offs.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Clone\ngit clone https://github.com/yannabadie/Meta-Harness-YGN.git\npip install \"mcp>=1.12\"   # optional — MCP server only\n\n# 2. Load\nclaude --plugin-dir ./Meta-Harness-YGN\n\n# 3. Go\n/mh:bootstrap                    # generate eval tasks for your project\n/mh:evolve \"improve validation\"  # propose a measured improvement\n/mh:dashboard                    # see the full picture\n```\n\n---\n\n## How It Works\n\nWhen you run `/mh:evolve`, five phases execute in sequence:\n\n| Phase | What happens | Agent |\n|-------|-------------|-------|\n| **Harvest** | BM25-scored extraction of project context (CLAUDE.md, memory, git history, plugins) | context-harvester |\n| **Propose** | One controlled change with hypothesis, patch, and risk assessment | harness-proposer (worktree-isolated) |\n| **Evaluate** | 9 deterministic checks + LLM-judge criteria. Evaluator never sees proposer's reasoning (context break) | harness-evaluator |\n| **Audit** | Causal regression analysis against the Pareto frontier | regression-auditor (read-only) |\n| **Report** | Measured before/after deltas with verdict: PROMOTE / REJECT / ITERATE | — |\n\n```\n⚗ EVOLUTION REPORT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nRun: run-0012 | Hypothesis: tighter tool-call validation\n\n| Metric        | Baseline | Candidate | Delta    |\n|---------------|----------|-----------|----------|\n| Score         | 0.764    | 0.821     | +7.5%  ▲ |\n| Latency (ms)  | 8120     | 7340      | -9.6%  ▲ |\n| Tokens        | 11382    | 10890     | -4.3%  ▲ |\n\nConfidence: N=12 | Method: deterministic + LLM-judge\nRisk: low — additive validation layer, fully reversible\nVerdict: PROMOTE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n### Key design decisions\n\n- **Evaluator never sees proposer's reasoning** — prevents self-congratulatory scoring\n- **Maximum 3 files per patch** — keeps changes focused and reversible\n- **Additive changes first** — new rules before prompt rewrites\n- **Everything on disk** — crashes and context compaction don't lose progress\n- **Zero external dependencies** for core (mcp package optional for MCP server)\n\n---\n\n## What's Under the Hood\n\n| Layer | What | Count |\n|-------|------|-------|\n| Skills | Entry points (`/mh:evolve`, `frontier`, `regressions`, `dashboard`, `eval`, `bootstrap`) | 6 |\n| MCP Server | Tools (frontier, traces, eval, plugins, context) + Resources (dashboard, traces, regressions, context) | 7 + 4 |\n| Agents | Proposer, evaluator (context-break), auditor (read-only), harvester (BM25) | 4 |\n| Hooks | SessionStart, PostToolUse, Stop (Haiku quality gate), PostCompact, InstructionsLoaded, SubagentStop | 7 |\n| Eval checks | json_valid, file_exists, file_contains, file_not_contains, exit_code, command_output, patch_not_empty, max_files_changed, files_in_scope | 9 |\n| Tests | Unit + integration | 55 |\n\n---\n\n## Does It Actually Work?\n\n**Yes. The plugin optimized its own harness (run-0005):**\n\n- **Gap found:** 4 eval check types were implemented but never wired into any eval task. A proposer could submit an empty or out-of-scope patch and pass all checks.\n- **Fix applied:** Added 4 deterministic guards, promoting scope checking from LLM-judge-only to a hard gate.\n- **Result:** 100% eval score maintained. Guardrail coverage increased from 3 to 7 checks.\n\nThis is the proof: the plugin found a real blind spot in its own eval suite and fixed it.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 7700,
  "sha": "25fe357f93ed1a7110131197be31f41f104b21f5c8d980b11ae63a4a1e8b26ac",
  "repo_slug": "yannabadie/meta-harness-ygn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_yannabadie_meta_harness_ygn_meta_harness_99e614e2/readme"
}