The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: refresh ECC 2.0 reference architecture (#1783)
Affaan Mustafa60bd26fadfbb
diff --git a/docs/ECC-2.0-GA-ROADMAP.md b/docs/ECC-2.0-GA-ROADMAP.mdindex abfd52a20..d590f92ef 100644--- a/docs/ECC-2.0-GA-ROADMAP.md+++ b/docs/ECC-2.0-GA-ROADMAP.md@@ -34,8 +34,9 @@ As of 2026-05-12:- Do not publish release or social announcements until the GitHub release,npm/package state, billing state, and plugin submission surfaces are verifiedwith fresh evidence.-- Do not treat closed stale PRs as discarded. Inspect them, port useful current- compatible work on maintainer-owned branches, and credit the source PR.+- Do not treat closed stale PRs as discarded. Pair each cleanup batch with a+ salvage pass: inspect the closed diffs, port useful compatible work on+ maintainer-owned branches, and credit the source PR.- Do not create new Linear issues until the active issue limit is cleared.## Reference Pressure@@ -167,7 +168,8 @@ Acceptance:- Each useful artifact is marked landed, Linear/project-tracked, salvagebranch, or archive/no-action.- Stale PR salvage policy stays in force: close stale/conflicted PRs first,- then port useful compatible content on maintainer branches with attribution.+ record a salvage ledger item, then port useful compatible content on+ maintainer branches with attribution.- #1687 localization leftovers are handled only by translator/manual review,not blind cherry-pick.@@ -181,3 +183,5 @@ Acceptance:payments announcement.5. Inventory `_legacy-documents-*` and map useful artifacts to landed,milestone-tracked, salvage, or archive states.+6. Build the stale-PR salvage ledger from closed cleanup batches, then port+ useful pieces in small attributed maintainer PRs.diff --git a/docs/ECC-2.0-REFERENCE-ARCHITECTURE.md b/docs/ECC-2.0-REFERENCE-ARCHITECTURE.mdindex 0ec7e396c..643b09dc7 100644--- a/docs/ECC-2.0-REFERENCE-ARCHITECTURE.md+++ b/docs/ECC-2.0-REFERENCE-ARCHITECTURE.md@@ -1,57 +1,238 @@# ECC 2.0 Reference Architecture-Research summary from competitor/reference analysis (2026-03-22).--For the current GA execution roadmap and Linear milestone mirror, see+Current execution mirror:[`ECC-2.0-GA-ROADMAP.md`](ECC-2.0-GA-ROADMAP.md).-## Competitive Landscape+This document turns the May 2026 reference sweep into concrete ECC backlog+shape. It is not a second strategy memo: every reference pressure below should+land as an adapter, check, observable signal, security policy, PR review+surface, or release-readiness gate.-| Project | Stars | Language | Type | Multi-Agent | Worktrees | Terminal-native |-|---------|-------|----------|------|-------------|-----------|-----------------|-| **ECC 2.0** | - | Rust | TUI | Yes | Yes | **Yes (SSH)** |-| superset-sh/superset | 7.7K | TypeScript | Electron | Yes | Yes | No (desktop) |-| standardagents/dmux | 1.2K | TypeScript | TUI (Ink) | Yes | Yes | Yes |-| opencode-ai/opencode | 11.5K | Go | TUI | No | No | Yes |-| smtg-ai/claude-squad | 6.5K | Go | TUI | Yes | Yes | Yes |+## Reference Baseline-## Three-Layer Architecture+Snapshot date: 2026-05-12.+| Reference | Primary pressure on ECC 2.0 | Concrete ECC delta |+| --- | --- | --- |+| [`stablyai/orca`](https://github.com/stablyai/orca) | Worktree-native multi-agent IDE with terminals, source control, GitHub integration, SSH, notifications, design/browser mode, account switching, and per-worktree context. | Treat worktree lifecycle, review state, notification state, and account/provider identity as first-class adapter signals. |+| [`superset-sh/superset`](https://github.com/superset-sh/superset) | Desktop AI-agent workspace with parallel execution, worktree isolation, diff review, workspace presets, and broad CLI-agent compatibility. | Add workspace preset taxonomy and make ECC2 session/worktree state exportable enough for external editors to consume. |+| [`standardagents/dmux`](https://github.com/standardagents/dmux) | Tmux/worktree orchestration, lifecycle hooks, multi-select agent control, smart merging, file browser, notifications, and cleanup. | Add lifecycle-hook coverage to the harness matrix and define merge/conflict queue events. |+| [`aidenybai/ghast`](https://github.com/aidenybai/ghast) | Native macOS terminal multiplexer with cwd-grouped workspaces, panes, tabs, drag/drop, search, and notifications. | Preserve terminal-native ergonomics while adding cwd/session grouping and searchable handoff/session records. |+| [`jarrodwatts/claude-hud`](https://github.com/jarrodwatts/claude-hud) | Always-visible Claude Code statusline for context, tools, agents, todos, and transcript-backed activity. | Formalize the ECC HUD/status payload for context, cost, tool calls, active agents, todos, queue state, checks, and risk. |+| [`stanford-iris-lab/meta-harness`](https://github.com/stanford-iris-lab/meta-harness) | Automated search over task-specific harness design: what to store, retrieve, and show. | Split ECC improvement loops into scenario spec, proposer trace, verifier result, and promoted playbook. |+| [`greyhaven-ai/autocontext`](https://github.com/greyhaven-ai/autocontext) | Recursive harness improvement using traces, reports, artifacts, datasets, playbooks, and role-separated evaluators. | Store reusable traces and playbooks before mutating installed harness assets. |+| [`NousResearch/hermes-agent`](https://github.com/NousResearch/hermes-agent) | Self-improving operator shell with memories, skills, scheduler, gateways, subagents, terminal backends, and migration tooling. | Keep ECC portable across local, SSH, container, and hosted terminal backends without hiding the underlying commands. |+| [`anthropics/claude-code`](https://github.com/anthropics/claude-code), [`sst/opencode`](https://github.com/sst/opencode), Zed, Codex, Cursor, Gemini | Different agent harnesses expose different hooks, plugin surfaces, session stores, config files, and review loops. | Maintain a public adapter compliance matrix instead of treating one harness as the canonical UX. |+| Local Claude Code source review | Session, tool, permission, hook, remote, analytics, task, and context-suggestion surfaces are more structured than the public CLI UX suggests. | Model status and risk events around session messages, permission requests, tool progress, context pressure, and summary state. |++## Architecture Shape++ECC 2.0 should be a harness operating system, not only a catalog of commands,+agents, and skills.++```text+┌──────────────────────────────────────────────────────────────┐+│ Operator Surface │+│ CLI, plugin, TUI, HUD/statusline, release gates, PR checks │+├──────────────────────────────────────────────────────────────┤+│ Harness Adapter Layer │+│ Claude Code, Codex, OpenCode, Cursor, Gemini, Zed, dmux, │+│ Orca, Superset, Ghast, terminal-only │+├──────────────────────────────────────────────────────────────┤+│ Worktree, Session, And Queue Runtime │+│ worktrees, panes, sessions, todos, checks, merge/conflict │+│ queues, notification state, ownership, handoff exports │+├──────────────────────────────────────────────────────────────┤+│ Observability And Evaluation Loop │+│ JSONL traces, status snapshots, risk ledger, harness audit, │+│ scenario specs, verifiers, promoted playbooks, RAG sets │+├──────────────────────────────────────────────────────────────┤+│ Security And Commercial Platform │+│ AgentShield policies/SARIF, ECC Tools checks, billing, │+│ Linear/GitHub sync, enterprise reports │+└──────────────────────────────────────────────────────────────┘```-┌─────────────────────────────────┐-│ TUI Layer (ratatui) │ User-facing dashboard-│ Panes, diff viewer, hotkeys │ Communicates via Unix socket-├─────────────────────────────────┤-│ Runtime Layer (library) │ Workspace runtime, agent registry,-│ State persistence, detection │ status detection, SQLite-├─────────────────────────────────┤-│ Daemon Layer (process) │ Persistent across TUI restarts-│ Terminal sessions, git ops, │ PTY management, heartbeats-│ agent process supervision │-└─────────────────────────────────┘-```-## Patterns to Adopt--### From Superset (Electron, 7.7K stars)-- **Workspace Runtime Registry** — trait-based abstraction with capability flags-- **Persistent daemon terminal** — sessions survive restarts via IPC-- **Per-project mutex** for git operations (prevents race conditions)-- **Port allocation** per workspace for dev servers-- **Cold restore** from serialized terminal scrollback--### From dmux (Ink TUI, 1.2K stars)-- **Worker-per-pane status detection** — fingerprint terminal output + LLM classification-- **Agent Registry** — centralized agent definitions (install check, launch cmd, permissions)-- **Retry strategies** — different policies for destructive vs read-only operations-- **PaneLifecycleManager** — exclusive locks preventing concurrent pane races-- **Lifecycle hooks** — worktree_created, pre_merge, post_merge-- **Background cleanup queue** — async worktree deletion--## ECC 2.0 Advantages-- Terminal-native (works over SSH, unlike Superset)-- Integrates with 116-skill ecosystem-- AgentShield security scanning-- Self-improving skill evolution (continuous-learning-v2)-- Rust single binary (3.4MB, no runtime deps)-- First Rust-based agentic IDE TUI in open source+## Reference-To-Backlog Map++### Worktree And Session Orchestration++Adopt from Orca, Superset, dmux, and Ghast:++- Worktree lifecycle events: create, resume, pause, stop, diff, review, PR,+ merge-ready, conflict, stale, close, salvage.+- Session grouping by repo, branch, cwd, task, owner, and harness.+- Workspace presets for release lane, PR triage lane, docs lane, security lane,+ and test-writer lane.+- Notifications for blocked CI, dirty worktrees, merge conflicts, stale review,+ and finished autonomous runs.+- Review loops that can annotate diffs and PRs without taking ownership away+ from maintainers.++Repo work:++- `everything-claude-code`: extend the adapter compliance matrix and public+ scorecard onramp.+- `ecc2`: surface session/worktree state through a stable local payload before+ adding hosted telemetry.+- `ECC-Tools`: consume the same lifecycle events for PR checks, issue routing,+ and Linear sync.++Verification:++- `npm run harness:audit -- --format json`+- `npm run observability:ready`+- targeted adapter matrix tests once the matrix moves from docs to data++### HUD, Status, And Observability++Adopt from Claude HUD and the Claude Code source review:++- Context pressure: usage, compaction risk, large-result warnings, and summary+ state.+- Tool activity: active tool, recent tools, duration, risky operations, and+ permission requests.+- Agent activity: active subagents, delegated task, branch/worktree, and wait+ state.+- Queue activity: open PRs/issues, CI state, stale/conflict batches, review+ state, and closed-stale salvage backlog.+- Cost/risk: token cost estimate, destructive-operation risk, hook/MCP risk,+ and security scan state.++Repo work:++- Keep `docs/architecture/observability-readiness.md` as the operator-facing+ readiness gate.+- Define a versioned HUD/status JSON contract that both ECC2 and ECC Tools can+ consume.+- Add sample exports from `loop-status`, `session-inspect`, harness audit, and+ risk ledger into a fixture directory before building visual UI.++Verification:++- `npm run observability:ready`+- fixture validation for every status payload+- cross-platform smoke test for commands that read session history++### Self-Improving Harness Loop++Adopt from Meta-Harness, Autocontext, and Hermes Agent:++- Separate the loop into observation, proposal, verification, promotion, and+ rollback.+- Store every proposed improvement as trace plus artifact, not only as a final+ changed file.+- Promote playbooks only after a verifier proves that they improve a scenario+ without widening blast radius.+- Use RAG/reference sets for vetted ECC patterns, team history, CI failures,+ review outcomes, harness config quality, and security decisions.++Repo work:++- `everything-claude-code`: document scenario specs, verifier contracts, and+ playbook promotion rules.+- `ECC-Tools`: map analyzer findings to PR comments, check runs, and Linear+ tasks without flooding the workspace.+- `agentshield`: feed prompt-injection and config-risk findings into regression+ suites.++Verification:++- read-only prototype that emits a trace, report, candidate playbook, and+ verifier result+- regression fixture proving a bad proposal is rejected++### AgentShield Enterprise Security Platform++AgentShield should move from useful scanner to enterprise security platform.++Backlog shape:++- Policy schema for org baseline, rule severity, owner, exception, expiration,+ evidence, and audit trail.+- SARIF output for GitHub code scanning.+- Policy packs for OSS, team, enterprise, regulated, high-risk hooks/MCP, and+ CI enforcement.+- Supply-chain intelligence for MCP packages, npm/pip provenance, CVEs,+ typosquats, and dependency reputation.+- Prompt-injection corpus and regression benchmark.+- JSON plus executive HTML/PDF report output.++Verification:++- schema unit tests+- SARIF fixture tests+- policy-pack golden tests+- false-positive regression tests from the public issue history++### ECC Tools Commercial And Review Platform++ECC Tools should become the GitHub-native layer for billing, deep analysis,+PR checks, and Linear progress tracking.++Backlog shape:++- Native GitHub Marketplace billing audit before any payments announcement:+ plans, seats, org/account mapping, subscription state, overage behavior,+ downgrade/cancel behavior, and failure modes.+- Deep analyzer comparable in scope to the useful parts of GitGuardian,+ Dependabot, CodeRabbit, and Greptile: security evidence, dependency risk,+ CI/CD recommendations, PR review behavior, config quality, token/cost risk,+ and harness drift.+- RAG/reference set over vetted ECC patterns, historical PR outcomes,+ dependency advisories, CI failures, review decisions, and team-specific+ conventions.+- Linear sync that maps findings to project status, milestone evidence, and+ owner-ready issues without exhausting issue limits.++Verification:++- check-run fixture tests+- billing webhook replay tests+- analyzer golden PR fixtures+- Linear sync dry-run fixture++### Closed-Stale Salvage Lane++Closing stale PRs keeps the public queue usable, but useful work should not be+lost because a contributor no longer has time to rebase.++Execution rule:++1. Close stale, conflicted, or obsolete PRs with a clear courtesy comment.+2. Record them in a salvage ledger with source PR, author, reason closed,+ useful files/concepts, risk, and recommended maintainer action.+3. After the cleanup batch, inspect each closed PR diff manually.+4. Cherry-pick only when the patch still applies cleanly and preserves current+ architecture. Otherwise reimplement the useful idea in a fresh maintainer+ branch.+5. Preserve attribution in the commit body or PR body.+6. Comment back on the source PR when useful work lands, linking the maintainer+ PR or merged commit.+7. Mark the ledger item as landed, superseded, Linear-tracked, or no-action.++Required safeguards:++- Never blind cherry-pick generated churn, bulk localization, or dependency+ major-version changes.+- Prefer small maintainer PRs over one salvage megabranch.+- Run the same validation gates as normal code, docs, or catalog changes.+- Keep contributor credit even when the final implementation is rewritten.++## Near-Term Implementation Order++1. Extend the harness adapter matrix and public scorecard onramp.+2. Add the release/name/plugin publication checklist with evidence fields.+3. Define the HUD/status JSON contract and fixture directory.+4. Start AgentShield policy schema plus SARIF fixtures.+5. Audit ECC Tools billing and check-run surfaces.+6. Inventory legacy folders and closed-stale PRs into the salvage ledger.+7. Port useful stale work in small attributed maintainer PRs.++## Non-Goals++- Hosted telemetry before the local event model is useful and testable.+- Automatic mutation of user harness configs without verifier evidence.+- Treating any one agent harness as the canonical interface.+- Release or payments announcements before command, package, marketplace, and+ billing evidence is fresh.