{"id":49214491,"url":"https://github.com/epicsagas/epic-harness","last_synced_at":"2026-07-03T03:00:46.242Z","repository":{"id":350223397,"uuid":"1205860304","full_name":"epicsagas/epic-harness","owner":"epicsagas","description":"Multi-tool AI agent harness — 22 skills, self-evolving engine, unified memory, autonomous spec-to-PR pipeline. Works with Claude Code, Codex, Cursor, OpenCode, and Cline.","archived":false,"fork":false,"pushed_at":"2026-06-25T14:49:19.000Z","size":10131,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T16:19:53.428Z","etag":null,"topics":["ai-agent","claude","claude-code","cli","developer-tools","llm","rust"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/epic-harness","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epicsagas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"epicsagas","buy_me_a_coffee":"epicsaga"}},"created_at":"2026-04-09T10:54:42.000Z","updated_at":"2026-06-25T14:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/epicsagas/epic-harness","commit_stats":null,"previous_names":["epicsagas/epic-harness"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/epicsagas/epic-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicsagas%2Fepic-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicsagas%2Fepic-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicsagas%2Fepic-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicsagas%2Fepic-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epicsagas","download_url":"https://codeload.github.com/epicsagas/epic-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicsagas%2Fepic-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35070339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","claude-code","cli","developer-tools","llm","rust"],"created_at":"2026-04-23T23:05:49.764Z","updated_at":"2026-07-03T03:00:46.235Z","avatar_url":"https://github.com/epicsagas.png","language":"Rust","funding_links":["https://github.com/sponsors/epicsagas","https://buymeacoffee.com/epicsaga"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eEpic Harness\u003c/h1\u003e\n\n\u003cblockquote\u003e\u003cp align=\"center\"\u003eA self-evolving AI coding agent harness — 3 commands, 26 skills, 1 autonomous pipeline, learns from your failures.\u003c/p\u003e\u003c/blockquote\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003eLess to memorize. More intelligence per keystroke. Gets smarter every session.\u003c/b\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e | \u003ca href=\"i18n/ja/README.md\"\u003e日本語\u003c/a\u003e | \u003ca href=\"i18n/ko/README.md\"\u003e한국어\u003c/a\u003e | \u003ca href=\"i18n/de/README.md\"\u003eDeutsch\u003c/a\u003e | \u003ca href=\"i18n/fr/README.md\"\u003eFrançais\u003c/a\u003e | \u003ca href=\"i18n/zh-CN/README.md\"\u003e简体中文\u003c/a\u003e | \u003ca href=\"i18n/zh-TW/README.md\"\u003e繁體中文\u003c/a\u003e | \u003ca href=\"i18n/pt-BR/README.md\"\u003ePortuguês\u003c/a\u003e | \u003ca href=\"i18n/es/README.md\"\u003eEspañol\u003c/a\u003e | \u003ca href=\"i18n/hi/README.md\"\u003eहिन्दी\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/epicsagas/epic-harness/stargazers\"\u003e\u003cimg alt=\"Stars\" src=\"https://img.shields.io/github/stars/epicsagas/epic-harness?style=for-the-badge\u0026labelColor=0d1117\u0026color=ffd700\u0026logo=github\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/epicsagas/epic-harness/network/members\"\u003e\u003cimg alt=\"Forks\" src=\"https://img.shields.io/github/forks/epicsagas/epic-harness?style=for-the-badge\u0026labelColor=0d1117\u0026color=2ecc71\u0026logo=github\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/epicsagas/epic-harness/issues\"\u003e\u003cimg alt=\"Issues\" src=\"https://img.shields.io/github/issues/epicsagas/epic-harness?style=for-the-badge\u0026labelColor=0d1117\u0026color=ff6b6b\u0026logo=github\u0026logoColor=white\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/epicsagas/epic-harness/commits/main\"\u003e\u003cimg alt=\"Last commit\" src=\"https://img.shields.io/github/last-commit/epicsagas/epic-harness?style=for-the-badge\u0026labelColor=0d1117\u0026color=58a6ff\u0026logo=git\u0026logoColor=white\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-3fb950?style=for-the-badge\u0026labelColor=0d1117\" /\u003e\u003c/a\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-0.7.0-fc8d62?style=for-the-badge\u0026labelColor=0d1117\" /\u003e\n  \u003cimg alt=\"Rust\" src=\"https://img.shields.io/badge/rust-1.82+-d73a49?style=for-the-badge\u0026labelColor=0d1117\u0026logo=rust\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Claude Code\" src=\"https://img.shields.io/badge/Claude_Code-plugin-bc8cff?style=for-the-badge\u0026labelColor=0d1117\" /\u003e\n  \u003ca href=\"https://buymeacoffee.com/epicsaga\"\u003e\u003cimg alt=\"Buy Me a Coffee\" src=\"https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge\u0026labelColor=0d1117\u0026logo=buymeacoffee\u0026logoColor=black\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA Claude Code plugin that **consolidates 30+ commands into 3 commands + 26 auto-trigger skills**, and **evolves new skills** from your own failure patterns.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/features.png\" alt=\"epic harness features\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n---\n\n![Demo](./docs/demo/demo.gif)\n\n### Web Dashboard — auto-launches on session start\n\n10-screen real-time metrics for eval scores, tool stats, orbit pipelines, evolved skills, and hook health. Opens automatically with the first Claude Code session — no manual setup needed. The **Eval \u0026 Evolve** screen surfaces the HarnessX evolution-engine state: reward-hacking warnings, seesaw solved-task registry, variant pool, and the adaptation landscape (persistent failures + untried edit types).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/dashboard.png\" alt=\"Dashboard\" width=\"49%\" /\u003e\n  \u003cimg src=\"./assets/dashboard-orbit.png\" alt=\"Orbit Pipeline\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\n```bash\n# Auto-launches on first session (default: http://localhost:7700)\n# Configure port or disable in ~/.harness/config.toml:\n[dashboard]\nport = 7700       # set to 0 to disable auto-launch\nauto_open = true  # open browser on first session\n```\n\nScreens: **Dashboard** · /orbit Pipeline · Commands (3) · Skills (26) · Live Agents · Eval \u0026 Evolve · Hooks (6) · Integrations (6) · harness-mem · Settings\n\n---\n\n## What It Does\n\nOne command ships a feature end-to-end. Skills fire without you asking. The agent gets smarter after every session.\n\n```bash\n$ /orbit \"Add JWT auth to the login API\"\n→ spec approved → go (TDD subagents) → check (PASS) → ship (PR + CI) → evolve\n```\n\nOr invoke pipeline skills directly:\n\n```bash\n/spec \"Add JWT auth to the login API\"   # clarifies requirements → SPEC-*.md\n/go                                      # auto-plans → TDD subagents → 4 min\n/check                                   # parallel review + security + tests → PASS\n/ship                                    # isolated test → PR → CI green\n```\n\nSkills trigger automatically in the background — no extra commands:\n\n```\nWriting a feature?    → tdd fires (Red→Green→Refactor enforced)\nTest fails?           → debug fires (root-cause first, no random fixes)\nTouching auth or DB?  → secure fires (OWASP checklist, no shortcuts)\nFile hits 200 lines?  → simplify fires (extract, rename, reduce)\n```\n\nAfter the session ends, the **evolve loop** analyzes what broke, generates targeted skills, and loads them next session. The agent that struggled with TypeScript build failures will have an `evo-ts-care` skill next time.\n\n---\n\n## Installation\n\n\u003e **First time?** Read the [Quick Start Guide (5 min)](docs/quickstart.md).\n\nepic-harness ships as a **plugin** — skills, hooks, and the `harness-mem` MCP server are loaded directly from the plugin layout (`skills/`, `hooks.json`, `mcp_config.json`). There is no `install` subcommand; each tool reads the plugin from disk.\n\n### Claude Code (recommended)\n\n```\n/plugin marketplace add epicsagas/plugins\n/plugin install epic@epicsagas\n```\n\nAuto-installs the binary, skills, hooks, and the `harness-mem` MCP server in one step.\n\n### Codex CLI\n\n```bash\ncodex plugin marketplace add epicsagas/plugins\n```\n\nSkills and agents are available immediately — no further steps needed.\n\n### agy (Antigravity CLI)\n\n```bash\nagy plugin install https://github.com/epicsagas/epic-harness\nagy plugin enable epic\n```\n\nSkills (27), hooks, and the `harness-mem` MCP server are auto-discovered from the plugin's `plugin.json` + `skills/` + `hooks.json` + `mcp_config.json`.\n\n### Binary-only (no plugin host)\n\n```bash\nbrew install epicsagas/tap/epic-harness      # macOS / Linux (Homebrew)\ncargo binstall epic-harness                  # pre-built binary (Rust)\ncargo install epic-harness                   # build from source\n```\n\nNo Homebrew? Use the installer script:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf \\\n  https://github.com/epicsagas/epic-harness/releases/latest/download/install.sh | sh\n```\n\nWindows:\n\n```powershell\nirm https://github.com/epicsagas/epic-harness/releases/latest/download/install.ps1 | iex\n```\n\nThe binary self-seeds `~/.harness/config.toml` and `HARNESS.md` on the first hook run — no setup wizard, no `install` step.\n\n\u003e `epic-harness --version` to verify. Update with `brew upgrade epic-harness` or re-run the installer script.\n\nPrerequisites: **Git**. Source/binary installs also need the [Rust toolchain](https://rustup.rs).\n\n### Verify\n\n```bash\nepic --version              # Binary installed\nls ~/.harness/              # Data directory (auto-created on first session)\n```\n\nInside a Claude Code session: `/evolve status`\n\n\u003e **Telemetry**: usage reporting is on by default (opt-out). Toggle with `epic-harness telemetry status|on|off`.\n\n---\n\n## Telemetry\n\nepic-harness collects **anonymous** usage telemetry by default (opt-out) to improve hook reliability and skill evolution. Events are sent to Posthog.\n\n**What we collect:** command name, duration, outcome (success/failure), failure class, and hook block/failure events — plus `product`, `product_version`, `os`, and a random `install_id` (a UUID generated on first run, stored at `~/.config/epic-harness/install-id`).\n\n**What we never collect:** source code, file contents, file paths, environment variables, secrets, or any personally-identifiable information.\n\n**Control it:**\n\n```bash\nepic-harness telemetry status   # show current consent\nepic-harness telemetry off      # disable (stops all sending immediately)\nepic-harness telemetry on       # re-enable\n```\n\nConsent is stored at `~/.config/epic-harness/telemetry-consent`. When off, no telemetry is sent.\n\n---\n\n## Commands\n\n| Command | What it does |\n|---------|-------------|\n| `/orbit` | **Full autonomous pipeline**: spec → go → check → ship → evolve in one shot |\n| `/team` | Browse org libraries, hire existing teams, or design new ones (3–6 agents, synced to `.claude/agents/`) |\n| `/evolve` | Manual evolution trigger — analyze sessions, view dashboard, inspect skill effectiveness, rollback |\n\nPipeline stages (`/spec`, `/go`, `/check`, `/ship`, `/discover`) are now **skills** — they auto-trigger via context or can be invoked by name. Legacy command names still work via alias routing.\n\n---\n\n## /orbit — Autonomous Pipeline\n\n`/orbit` wraps the entire pipeline into a single autonomous execution. Pick a mode — everything else is hands-off until the PR.\n\n```mermaid\nflowchart TD\n    START([\"/orbit\"]) --\u003e MODE{\"requirement?\"}:::human\n    MODE --\u003e|\"unclear\"| WAIT[\"Interactive\\n/discover → /spec\\nthen 'orbit go'\"]:::human\n    MODE --\u003e|\"clear + complex\"| COUNCIL[\"Council\\n4-voice auto-spec\"]:::auto\n    MODE --\u003e|\"clear + simple\"| DIRECT[\"Direct\\nauto-spec\"]:::auto\n    WAIT --\u003e SPEC_LOAD[\"Load spec\"]\n    COUNCIL --\u003e SPEC_LOAD\n    DIRECT --\u003e SPEC_LOAD\n    SPEC_LOAD --\u003e GO[\"Go\\nplan → TDD → integrate\"]:::auto\n    GO --\u003e CHECK[\"Check\\nreview + audit + test\"]:::auto\n    CHECK --\u003e|\"PASS / WARN\"| SHIP[\"Ship\\nisolated test → PR → CI\"]:::auto\n    CHECK --\u003e|FAIL| RETRY{\"retry \u003c 3?\"}\n    RETRY --\u003e|yes| GO\n    RETRY --\u003e|no| PAUSE[\"Pause\\nuser decides\"]:::human\n    PAUSE --\u003e|continue| GO\n    PAUSE --\u003e|abort| ABORT([\"Abort\"])\n    SHIP --\u003e EVOLVE[\"Evolve\\nauto-analyze session\"]:::auto\n    EVOLVE --\u003e DONE([\"Orbit Complete\\nconsolidated report\"]):::auto\n\n    classDef human fill:#4a4a6a,stroke:#9b9bcc,color:#fff\n    classDef auto  fill:#1a5c3a,stroke:#4caf7d,color:#fff\n```\n\n**Purple** — human steps: mode selection (unclear → interactive), 3× check failure pause.\n**Green** — clear + complex → council auto-spec; clear + simple → direct build; both fully autonomous.\n\nState persisted in `$HARNESS_DIR/orbit/PIPELINE-{timestamp}.json` — survives context compaction.\n\n\u003e **Caveats**: The agent may bypass the pipeline when modifying orbit itself or editing docs only. See [Known Issues (Agent Judgment)](#known-issues-agent-judgment).\n\n---\n\n## Auto Skills (Ring 2)\n\nSkills trigger automatically based on context. You don't invoke them.\n\n| Skill | Triggers when |\n|-------|--------------|\n| **spec** | Requirements need defining — converts to numbered R + AC document |\n| **go** | Build phase — auto-plan → TDD sub-agents → parallel execution → AC verification |\n| **check** | Review phase — parallel code review + security audit + tests with scope extras |\n| **ship** | Shipping phase — isolated test → PR with full check report → CI watch + auto-fix |\n| **audit** | Full audit — parallel code quality + security + test review with semantic dedup |\n| **eval** | Quality regression evaluation with baseline comparison — correctness, perf, quality |\n| **tdd** | New feature implementation or bug fix |\n| **debug** | Test failure or runtime error |\n| **discover** | Vague request, solution without a problem, unfocused complaint |\n| **secure** | Auth / DB / API / secrets code touched |\n| **threat-model** | Security scoping — trust boundary enumeration, threat actors, scenarios → THREAT_MODEL.md |\n| **vuln-scan** | Systematic vulnerability scan — injection, auth, data exposure, dependencies → VULN-FINDINGS.json |\n| **triage** | Adversarial validation — severity adjustment, chaining analysis, root-cause grouping → TRIAGE.json |\n| **perf** | Loops, queries, rendering, batch operations |\n| **simplify** | File \u003e 200 lines or high cyclomatic complexity |\n| **document** | Public API added or signature changed |\n| **verify** | Before completing `/go` or `/ship` |\n| **context** | Context window \u003e 70% |\n| **council** | Ambiguous architectural or design decisions |\n| **orchestrate** | Multi-agent orchestration status and live agent intervention |\n| **agent-introspection** | 3+ consecutive failures or circular retry pattern |\n| **reflect** | On-demand: are you using AI as a thought amplifier? Cold evidence-based self-assessment |\n| **commit** | Conventional Commits generation — auto-generates from git diff |\n\n\u003e **Token budget note:** Claude Code loads skill descriptions into every session context. epic's 26 skills fit within the default `skillListingBudgetFraction: 0.01` (1%). If you install additional skills (e.g. episteme, alcove, obscura), the combined total may exceed the budget and trigger a \"descriptions dropped\" warning. Add this to `~/.claude/settings.json` to fix it:\n\u003e\n\u003e ```json\n\u003e \"skillListingBudgetFraction\": 0.02\n\u003e ```\n\u003e\n\u003e Use `0.03` if you have 20+ skills installed.\n\n---\n\n## Evolve (Ring 3)\n\nThe harness watches every tool call, scores it on 3 axes, detects failure patterns, and generates targeted skills — automatically, at session end.\n\n### Scoring\n\n```\ncomposite = 0.5 × tool_success + 0.3 × output_quality + 0.2 × execution_cost\n```\n\nFailure classification (9 types): `type_error` · `syntax_error` · `test_fail` · `lint_fail` · `build_fail` · `permission_denied` · `timeout` · `not_found` · `runtime_error`\n\n### Pattern Detection\n\n| Pattern | Detects | Default threshold |\n|---------|---------|-------------------|\n| `repeated_same_error` | Same error N+ times | 3 |\n| `fix_then_break` | Edit success → build/test fails | 3 lookback, 2 cycles |\n| `long_debug_loop` | Stuck on same file | 5 operations |\n| `thrashing` | Edit↔Error alternating | 3 edits, 3 errors |\n\n### Evolution Flow\n\n```\nObserve (PostToolUse — 3-axis scoring)\n    ↓ obs/session_{id}.jsonl\nAnalyze (SessionEnd)\n    ↓ per-tool, per-ext scores + patterns\nPropose (Solver — graduated by score: ≥0.90 skip, ≥0.70 moderate, \u003c0.70 full)\n    ↓ SkillProposal[] with confidence\nCurate (Accept/Merge/Skip, feedback masked from solver)\n    ↓ evolved/{skill}/SKILL.md + meta.json\nGate (format check, dedup, cap 10, gated promotion ≥ 3 sessions)\n    ↓ evolved_backup/ (best checkpoint)\nInstinct (high-success patterns → cross-project memory.db nodes)\n    ↓\nReload (next session — resume loads evolved skills)\n```\n\nSkill seeding: weak tool (success \u003c60%, min 5 obs), weak file type (success \u003c50%, min 3 obs), high-frequency error (5+ occurrences).\n\nStagnation: 3 sessions without 5% improvement → auto-rollback to best checkpoint.\n\n### SkillOpt-Inspired Optimization\n\nThree deep learning-inspired techniques adapted from [SkillOpt](https://arxiv.org/abs/2605.23904):\n\n| Technique | How it works |\n|-----------|-------------|\n| **Negative Feedback Buffer** | Rejected proposals stored with TTL-based expiry; future proposals checked against buffer before generation |\n| **Minibatch Reflection** | Observations decomposed into fixed-size batches for structural pattern extraction; reusable when dominant error ≥60% + ≥2 distinct files |\n| **Slow/Meta Update** | Linear regression over last 5 sessions classifies epochs as Improving / Regressing / PersistentFailure / StableSuccess; auto-evicts underperforming skills |\n\n### Prompt Auto-Tuning\n\nUnderperforming evolved skills receive targeted tuning guidance appended after `\u003c!-- auto-tuned --\u003e` delimiter. Original content is never modified. 3 consecutive declining sessions → auto-rollback tuning, history cleared.\n\n### Skill Effectiveness (Holdout A/B)\n\nEvery evolved skill is measured against a genuine counterfactual: each day an\nunder-evaluation skill is deterministically rotated into the **active** arm\n(injected into context at session start) or the **holdout** arm (withheld).\n\"With\" averages active-arm sessions, \"Without\" averages holdout-arm sessions —\nnot a derived guess from pre-creation history.\n\n```\n/evolve history → Skill Effectiveness (illustrative)\n\n| Skill              | With | Without | Holdout n | Delta |\n|--------------------|------|---------|-----------|-------|\n| evo-ts-care        | 0.87 | 0.72    | 4         | +15%  |\n| evo-bash-discipline| 0.65 | 0.68    | 3         | -3%   |\n```\n\nPositive delta = effective. Negative delta with ≥3 active and ≥2 holdout\nsessions → auto-evicted. Manual removal: `/evolve rollback`.\n\n### Cold-Start Presets\n\nOn first session, stack-appropriate preset skills auto-apply:\n\n| Stack | Presets |\n|-------|---------|\n| Node.js/TypeScript | `evo-ts-care`, `evo-fix-build-fail` |\n| Go | `evo-go-care` |\n| Python | `evo-py-care` |\n| Rust | `evo-rs-care` |\n\n### Instinct Learning\n\nHigh-success patterns extracted and promoted across projects:\n\n```\nobserve (100% confirmed) → extract_instincts() → instinct node (confidence ≥ 0.8)\n    → promote to global when observed in ≥ 2 projects\n```\n\n```bash\n/evolve              # Run now\n/evolve status       # Dashboard: scores, trends, patterns, skills\n/evolve history      # Full history + skill effectiveness\n/evolve cross-project # Cross-project pattern analysis\n/evolve rollback     # Restore previous best\n/evolve reset        # Clear all evolution data\n```\n\n### HarnessX-Inspired Defenses (v0.7.0)\n\nThe evolution loop now carries the safety mechanisms from the [HarnessX](https://arxiv.org/abs/2606.14249v1) paper's AEGIS pipeline, adapted to epic-harness's single-agent, per-project model. See `docs/references/operational-mirror.md` for the RL-analogy mapping.\n\n| Defense | Module | Protects against | Paper |\n|---------|--------|------------------|-------|\n| **Seesaw gate** | `evolve/seesaw.rs` | Catastrophic forgetting — blocks seeding when a previously-solved task regresses | §4.1 |\n| **Variant isolation** | `evolve/variants.rs` | Catastrophic forgetting — forks a sibling variant on regression instead of overwriting | §4.5 |\n| **Reward-hacking detection** | `evolve/metrics.rs` | Metric gaming — flags when execution_cost rises while output_quality falls | §4.3 |\n| **Critic layer** | `evolve/critic.rs` | Reward hacking — suppresses seeding + rejects manifests contradicting evidence | §4.3 |\n| **Digester** | `evolve/digester.rs` | (Trace compression) — per-task digests feeding the Planner | §4.3 |\n| **Planner** | `evolve/planner.rs` | Under-exploration — tracks untried edit types + persistent failures | §4.3 |\n| **Typed edits + manifests** | `evolve/edits.rs` | Opaque edits — each edit carries a falsifiable manifest (Table 9) | §4.3 |\n| **Processor abstraction** | `hooks/processor.rs` | (Foundation) — typed `HookPoint`/`Processor` over the CLI hooks | §3.2 |\n\nA **regression harness** (`tests/evolve_regression_test.rs`) locks these contracts with 6 hermetic scenarios — no live benchmark required.\n\n### Harness Snapshot (v0.7.0)\n\nThe harness is now a serializable, comparable first-class object:\n\n```bash\nepic harness snapshot              # JSON: config + skills + guard rules + metrics + content hash\nepic harness diff before.json after.json   # field-by-field structural diff\n# (restore is deferred — destructive)\n```\n\n---\n\n## Security Pipeline\n\nThree-stage vulnerability assessment pipeline ported from [defending-code](https://github.com/anthropics/defending-code-reference-harness):\n\n```bash\n/threat-model    # 1. Trust boundaries, threat actors, scenarios → THREAT_MODEL.md\n/vuln-scan       # 2. 4-dimension scanner (injection, auth, data exposure, deps) → VULN-FINDINGS.json\n/triage          # 3. Adversarial validation, severity adjustment, chaining → TRIAGE.json\n```\n\n### Audit `--strict` Mode\n\nFor security engagements, `--strict` mode enforces independence between audit modes:\n- Code, security, and test reviewers receive only the diff + spec — no builder context\n- Cross-check independence: modes run blind until synthesis\n- Blind scoring prevents anchoring bias\n\nOptional engagement context via `.harness/engagement.md` in project root (authorization, scope, constraints, exclusions). See `docs/references/engagement.md` for the template.\n\n---\n\n## Hooks (Ring 0)\n\nRun invisibly on every session. Single Rust binary (`epic-harness`) with subcommands.\n\n| Hook | When | Does |\n|------|------|------|\n| **resume** | Session start | Restore context, load memory, detect stack |\n| **guard** | Before Bash | Block force-push-to-main, `rm -rf /`, DROP prod |\n| **polish** | After Edit | Auto-format (Biome/Prettier/ruff/gofmt) + typecheck |\n| **observe** | Every tool use | Log to `~/.harness/projects/{slug}/obs/` for evolution |\n| **snapshot** | Before compact | Save state to `~/.harness/projects/{slug}/sessions/` |\n| **reflect** | Session end | Analyze failures, seed evolved skills, gate, extract instincts |\n\nPolish feeds back into observe: format failure → `lint_fail`, TypeScript error → `build_fail`. Edit→Error thrashing gets detected even when errors come from polish.\n\nEach session writes its own `session_{date}_{pid}_{random}.jsonl` — multiple concurrent sessions won't corrupt each other's data.\n\n### Hook Profiles\n\nVia `~/.harness/config.toml` or `EPIC_HOOK_PROFILE` env var:\n\n| Profile | Active hooks |\n|---------|-------------|\n| `minimal` | guard, observe, resume |\n| `standard` (default) | above + polish, reflect, snapshot |\n| `strict` | all hooks + future strict-only checks |\n\n### Custom Guard Rules\n\nAdd project-specific rules via `.harness/guard-rules.yaml` in your project root:\n\n```yaml\nblocked:\n  - pattern: kubectl\\s+delete\\s+namespace | msg: Namespace deletion blocked\nwarned:\n  - pattern: docker\\s+system\\s+prune | msg: Docker prune — verify first\n```\n\n---\n\n## Team (`epic team`)\n\nTeams are **org-level**, not project-bound. Running `/team` in any project enriches a shared pool of agent definitions — never silently overwrites.\n\n```bash\nepic team                              # Interactive: scan → design → write → sync\nepic team sync backend                 # Dispatch agents → .claude/agents/backend/\nepic team link backend                 # Dispatch + register project in team config\nepic team list                         # All teams in current org\nepic team list --org netflix           # Teams in a named org\nepic team show backend --playbook      # Config + full playbook\nepic team delete backend               # Recall from current project only\nepic team delete backend --global      # Permanently delete from org store\n```\n\nAfter syncing, agents are available in the next session: `@domain-expert`, `@reviewer`, `@tester`, etc.\n\n| Type | Keyword | Default agents |\n|------|---------|---------------|\n| Stream-aligned | `stream` | domain-expert, reviewer, tester |\n| Platform | `platform` | api-designer, infra-specialist, dx-agent |\n| Enabling | `enabling` | specialist |\n| Complicated Subsystem | `subsystem` | domain-specialist, integration-tester |\n\nMulti-org: `epic team --org netflix` — separate topology per org.\n\nMerge strategy: changed agents prompt (default: keep existing, backup to `.history/`). Playbook always appends.\n\n---\n\n## Multi-Tool Support\n\nAll tools share the same `~/.harness/projects/{slug}/` data directory.\n\n| Tool | Ring 0 Hooks | Commands | Skills | Agents |\n|------|-------------|----------|--------|--------|\n| **Claude Code** | ✓ Full | ✓ 3 commands (incl. /orbit) | ✓ 26 skills | Live |\n| **Codex CLI** | ✓ Full¹ | ✓ 3 prompts (incl. /orbit) | ✓ 26 | — |\n| **Antigravity** | ✓ Partial² | ✓ 3 commands (incl. /orbit) | ✓ 26 | — |\n\n¹ `plugin_hooks = true` in `~/.codex/config.toml` · ² PreInvocation/PostInvocation only — no PreToolUse (guard/polish unavailable)\n\n---\n\n## Architecture: 4-Ring Model\n\n```mermaid\nflowchart TB\n    subgraph R0[\"Ring 0 — Autopilot (hooks, invisible)\"]\n        direction LR\n        h1(resume) --- h2(guard) --- h3(polish) --- h4(observe) --- h5(snapshot) --- h6(reflect)\n    end\n\n    subgraph R1[\"Ring 1 — Commands (you call these)\"]\n        direction TB\n        subgraph orbit_wrap[\"  /orbit  \"]\n            direction LR\n            c1(\"spec\") --\u003e c2(\"go\") --\u003e c3(\"check\") --\u003e c4(\"ship\") --\u003e c5(\"evolve\")\n        end\n        c6(\"/team\")\n        c7(\"/evolve (manual)\")\n    end\n\n    subgraph R2[\"Ring 2 — Auto Skills (context-triggered)\"]\n        direction LR\n        s1(spec) --- s2(go) --- s3(check) --- s4(ship) --- s5(tdd) --- s6(debug) --- s7(secure) --- s8(perf) --- s9(simplify) --- s10(verify) --- s11(audit) --- s12(eval) --- s13(threat-model) --- s14(vuln-scan) --- s15(triage)\n    end\n\n    subgraph R3[\"Ring 3 — Evolve (self-improving)\"]\n        direction LR\n        e1(observe) --\u003e e2(analyze) --\u003e e3(seed) --\u003e e4(gate) --\u003e e5(reload)\n    end\n\n    R0 --\u003e|\"observe every tool call\"| R3\n    R3 -.-\u003e|\"evolved skills\"| R2\n    R1 --\u003e|\"auto-trigger skills\"| R2\n    R0 --\u003e|\"resume: restore context\"| R1\n```\n\n---\n\n## Cross-Project Learning\n\nOpt-in to share failure patterns across projects:\n\n```bash\ntouch ~/.harness/projects/{slug}/.cross-project-enabled\n```\n\nSession end → exports anonymized patterns to `~/.harness/global_patterns.jsonl`. Session start → shows hints from other projects' weak areas.\n\n---\n\n## Unified Memory\n\nAll agents share a knowledge graph in `~/.harness/memory.db` (SQLite with full-text search). No external runtime.\n\n```\nscore = recency(25%) + importance(35%) + access_frequency(15%) + FTS_match(25%)\n```\n\n### CLI\n\n```bash\nepic mem recall \"auth refactor\" --project my-project   # Smart recall\nepic mem add --title \"JWT rotation\" --type decision    # Add node\nepic mem search \"JWT\"                                  # FTS5 search\nepic mem list --type decision --project my-project    # Filter\nepic mem context --project my-project                  # Project context\nepic mem serve                                         # Web UI → :7700 or custom port with --port 8800\nepic mem mcp-install                                   # Register MCP server\nepic mem export --out ./docs/memory                    # Export to Markdown\n```\n\n### MCP Tools (6)\n\n| Tool | Purpose |\n|------|---------|\n| `mem_recall` | Smart contextual recall with hint + project + graph neighbors |\n| `mem_add` | Add node with auto-importance by type (or explicit 0.0–1.0) |\n| `mem_search` | Keyword search (full-text), ranked by importance |\n| `mem_query` | Filter by tag/type/project |\n| `mem_context` | Project-scoped smart recall (no hint) |\n| `mem_related` | Graph traversal from a node ID (finds connected knowledge) |\n\n### Node Types\n\n| Type | Created by | Importance |\n|------|-----------|------------|\n| `decision` | Manual / MCP | 0.9 |\n| `resolution` | Manual / MCP | 0.8 |\n| `concept` | Manual / MCP | 0.7 |\n| `project` | Manual / MCP | 0.7 |\n| `instinct` | Auto (reflect) | 0.7 |\n| `pattern` | Auto (reflect) | 0.5 |\n| `error` | Auto (reflect) | 0.4 |\n| `session` | Auto (reflect) | 0.2 |\n\nLifecycle: 30+ days without access → 10% importance decay (floor 0.05). 180+ days → tagged `stale`, excluded from recall. `pinned` tag prevents decay.\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProject Data — directory layout\u003c/strong\u003e\u003c/summary\u003e\n\n## Project Data\n\nAll data lives in `~/.harness/` (home directory), not in your project root. Survives project deletion, doesn't pollute git history.\n\n```\n~/.harness/\n├── memory.db                  # SQLite knowledge graph (nodes + edges + FTS5)\n├── graph.json                 # Cached graph (for web UI)\n├── config.toml                # User configuration\n├── global_patterns.jsonl      # Cross-project patterns (opt-in)\n├── orgs/                      # Team global store\n│   └── {org}/teams/{team}/\n│       ├── config.json, mission.md, playbook.md, agents/, .history/\n└── projects/{slug}/\n    ├── memory/                # Project patterns and rules\n    ├── sessions/              # Session snapshots (for resume)\n    ├── obs/                   # Tool usage observation logs (JSONL)\n    ├── evolved/               # Auto-evolved skills\n    │   ├── manifest.json\n    │   └── {skill}/SKILL.md + meta.json\n    ├── evolved_backup/        # Best checkpoint (for rollback)\n    ├── dispatch/              # Skill dispatch logs\n    ├── evolution.jsonl        # Full evolution history\n    └── metrics.json           # Aggregate stats + skill attribution\n```\n\nShare safety rules with your team: `.harness/guard-rules.yaml` in the project root (committed to git).\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConfiguration — config.toml reference\u003c/strong\u003e\u003c/summary\u003e\n\n## Configuration\n\nAll tunable parameters in `~/.harness/config.toml`. Absent = hardcoded defaults.\n\n```toml\n# Priority: env var (EPIC_HOOK_PROFILE) \u003e this file \u003e defaults\n\n[hook]\nprofile = \"standard\"         # \"minimal\" | \"standard\" | \"strict\"\ngateguard_hints = true\n\n[scoring]\nweights = [0.5, 0.3, 0.2]   # [success, quality, cost]\n\n[evolution]\nmax_skills = 10\nstagnation_limit = 3\nimprovement_threshold = 0.05\ngated_promotion_min = 3\n\n[pattern]\n# repeated_error_min = 3\n# debug_loop_min = 5\n# graduated_scope_skip = 0.90\n# graduated_scope_moderate = 0.70\n\n[instinct]\n# confidence_threshold = 0.8\n# promotion_min_projects = 2\n# max_instincts = 20\n# min_observations = 10\n# min_avg_score = 0.5\n```\n\n\u003c/details\u003e\n\n---\n\n## Known Issues (Agent Judgment)\n\nThese issues arise from the agent's interpretation of context rather than bugs in the code. Listed here so users know what to watch for.\n\n### Discovered Issues\n\n| Issue | When | What happens | Workaround |\n|-------|------|-------------|------------|\n| **Orbit self-modification bypass** | `/orbit` is asked to improve orbit itself | Agent may skip the orbit pipeline entirely and edit files ad-hoc on main, leaving changes uncommitted with no spec/PR/traceability | After orbit completes, check `git status`. If changes are on main without a pipeline state, commit manually or re-run `/orbit` from a separate branch |\n| **Doc-only task skips protocol** | `/orbit` receives a markdown-only change (no code to test) | Agent may judge TDD/test phases as meaningless and skip the full pipeline | Acceptable for pure doc changes. For mixed code+doc, ensure the agent doesn't skip code-related phases |\n| **Mode misclassification** | Request is borderline between Direct and Council | Agent may choose Direct when Council (4-voice) would catch more edge cases, or Council when Direct suffices | If the agent picks a mode that feels wrong, say \"use Council mode\" or \"use Direct mode\" explicitly |\n\n### Intentional Design Choices\n\nThese were considered for enhancement but kept as-is after evaluation:\n\n| Choice | Why not enhanced | Rationale |\n|--------|-----------------|-----------|\n| **Worktree enters at Go phase, not orbit start** | Could isolate from preflight | Preflight/mode/spec are read-only. Isolating earlier adds complexity with no benefit — the branch isn't created until Go phase anyway |\n| **Worktree preserved after Ship** | Could auto-remove on PR merge | The branch is the PR head. Removing it before merge breaks the PR. Cleanup is left to the user after merge |\n| **Branch named `orbit-{slug}` not `feature/{slug}`** | Could match conventional branch naming | `EnterWorktree` doesn't allow `/` in names. Renaming post-creation adds a step for cosmetic benefit only |\n| **No lightweight pipeline path for doc changes** | Could detect doc-only and skip TDD/tests | Detection is fragile (what counts as \"doc\"?). Adding a separate path increases protocol complexity for marginal gain |\n\n---\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003ecommand not found: epic after install\u003c/summary\u003e\n\nAdd the Cargo bin directory to your PATH:\n\n```bash\nexport PATH=\"$HOME/.cargo/bin:$PATH\"\n```\n\nAdd this line to your `~/.zshrc` or `~/.bashrc` to make it permanent.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eHooks not firing in Claude Code\u003c/summary\u003e\n\nReinstall the plugin to reload hooks:\n\n```\n/plugin install epic@epicsagas\n```\n\nThen restart Claude Code. Hooks are loaded from the plugin's `hooks.json`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ePermission denied on macOS (Gatekeeper)\u003c/summary\u003e\n\nmacOS may block unsigned binaries downloaded from the internet:\n\n```bash\nxattr -d com.apple.quarantine ~/.cargo/bin/epic-harness\nxattr -d com.apple.quarantine ~/.cargo/bin/epic\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eepic: binary not found inside plugin hooks\u003c/summary\u003e\n\nThe plugin looks for the binary in `hooks/bin/epic-harness` first. After updating via `cargo install`, copy it:\n\n```bash\ncp ~/.cargo/bin/epic-harness hooks/bin/epic-harness\n```\n\u003c/details\u003e\n\n---\n\n## Development\n\n```bash\ncargo install --path .                                        # Build + install\ncp ~/.cargo/bin/epic-harness hooks/bin/epic-harness           # Update plugin binary\ncargo test                                                    # Tests\n```\n\nHooks look for the binary in two places: `hooks/bin/epic-harness` (plugin local) → `~/.cargo/bin/epic-harness` (PATH).\n\n---\n\n## Links\n\n- [Changelog](CHANGELOG.md) — release history\n- [Contributing](CONTRIBUTING.md) — how to contribute\n- [Security](SECURITY.md) — reporting vulnerabilities\n- [Issues](https://github.com/epicsagas/epic-harness/issues) — bug reports and feature requests\n\n## Acknowledgments\n\n- [a-evolve](https://github.com/A-EVO-Lab/a-evolve) — Automated evolution and benchmark patterns\n- [agent-skills](https://github.com/addyosmani/agent-skills) — Claude Code agent skill system\n- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) — Comprehensive Claude Code patterns\n- [gstack](https://github.com/garrytan/gstack) — Plugin architecture reference\n- [harness](https://github.com/revfactory/harness) — Hook and harness infrastructure patterns\n- [serena](https://github.com/oraios/serena) — Autonomous agent design\n- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Multi-command framework architecture\n- [superpowers](https://github.com/obra/superpowers) — Claude Code extension patterns\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicsagas%2Fepic-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepicsagas%2Fepic-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicsagas%2Fepic-harness/lists"}