docs/architecture/harness-adapter-compliance.md
This matrix is the public onramp for teams that want to use ECC across more than one coding harness. It turns the cross-harness architecture into a practical scorecard: what works today, what is instruction-only, what needs an adapter, and what evidence an operator should collect before trusting a setup.
ECC's durable units stay in shared sources:
skills/*/SKILL.mdrules/commands/hooks/hooks.jsonscripts/hooks/Harness-specific files should only adapt loading, event shape, command names, or platform limits.
| State | Meaning |
|---|---|
| Native | ECC can install or verify the surface directly for this harness. |
| Adapter-backed | ECC has a thin adapter, plugin, or package surface, but parity differs by harness. |
| Instruction-backed | ECC can provide the guidance and files, but the harness does not expose the runtime hook/session surface ECC needs for enforcement. |
| Reference-only | The tool is useful as a design pressure or external runtime, but ECC does not yet ship a direct installer or adapter for it. |
The matrix below is rendered from
scripts/lib/harness-adapter-compliance.js and verified by
npm run harness:adapters -- --check.
| Harness or runtime | State | Supported assets | Unsupported or different surfaces | Install or onramp | Verification command | Risk notes |
|---|---|---|---|---|---|---|
| Claude Code | Native | Claude plugin assets; skills; commands; hooks; MCP config; local rules; statusline-oriented workflows | Claude-native hooks do not imply parity in other harnesses | ./install.sh --profile minimal --target claude; Claude plugin install | npm run harness:audit -- --format json; node scripts/session-inspect.js --list-adapters | Avoid loading every skill by default; keep hooks opt-in and inspectable. |
| Codex | Instruction-backed | AGENTS.md; Codex plugin metadata; skills; MCP reference config; command patterns | Native hook enforcement and Claude slash-command semantics are not equivalent | ./install.sh --profile minimal --target codex; repo-local AGENTS.md review | npm run harness:audit -- --format json | Treat hooks as policy text unless a native Codex hook surface exists. |
| OpenCode | Adapter-backed | OpenCode package/plugin metadata; shared skills; MCP config; event adapter patterns | Event names, plugin packaging, and command dispatch differ from Claude Code | OpenCode package or plugin surface from this repo | node tests/scripts/build-opencode.test.js; npm run harness:audit -- --format json | Keep hook logic in shared scripts and adapt only event shape at the edge. |
| Cursor | Adapter-backed | Cursor rules; project-local skills; hook adapter; shared scripts | Cursor hook events and rule loading differ from Claude Code | ./install.sh --profile minimal --target cursor | node tests/lib/install-targets.test.js; npm run harness:audit -- --format json | Cursor adapters must preserve existing project rules and avoid silent overwrite. |
| Gemini | Instruction-backed | Gemini project-local instructions; shared skills; rules; compatibility docs | No full ECC hook parity; ecosystem ports must document drift from upstream ECC | ./install.sh --profile minimal --target gemini | node tests/lib/install-targets.test.js | Treat Gemini ports as ecosystem adapters until validated end to end inside Gemini CLI. |
| Zed | Adapter-backed | Zed project settings; flattened project rules; shared skills; commands; agents | Zed external agents and native Agent Panel permissions are not Claude hooks | ./install.sh --profile minimal --target zed | node tests/lib/install-targets.test.js; npm run harness:audit -- --format json | Keep project settings conservative and do not copy BYOK/OpenRouter secrets into .zed/. |
| dmux | Adapter-backed | session snapshots; tmux/worktree orchestration status; handoff exports | dmux is an orchestration runtime, not an install target for skills/rules | node scripts/session-inspect.js --list-adapters; dmux session target inspection | node tests/lib/session-adapters.test.js | Treat dmux events as session/runtime signals, not as a replacement for repo validation. |
| Orca | Reference-only | worktree lifecycle; review state; notification; provider-identity design pressure | No ECC installer or direct adapter today | Use as a comparison target for worktree/session state requirements | npm run observability:ready | Do not import product-specific assumptions; convert lessons into ECC event fields. |
| Superset | Reference-only | workspace presets; parallel-agent review loops; worktree isolation design pressure | No ECC installer or direct adapter today | Use as a comparison target for workspace preset taxonomy | npm run observability:ready | Keep ECC portable; do not require a desktop workspace to get basic value. |
| Ghast | Reference-only | terminal-native pane grouping; cwd grouping; search; notifications | No ECC installer or direct adapter today | Use as a comparison target for terminal-first session grouping | node scripts/session-inspect.js --list-adapters | Preserve terminal ergonomics before adding visual UI assumptions. |
| Terminal-only | Native | skills; rules; commands; scripts; harness audit; observability readiness; handoffs | No external UI, no automatic session control unless scripts are run explicitly | Clone repo; run commands directly; use minimal profile for project installs | npm run harness:audit -- --format json; npm run observability:ready | This is the fallback contract; every higher-level adapter should degrade to it. |
Use this sequence before asking ECC to make a team or repo setup more autonomous:
npm run harness:adapters -- --check
npm run harness:audit -- --format json
npm run observability:ready
node scripts/session-inspect.js --list-adapters
node scripts/loop-status.js --json --write-dir .ecc/loop-status
Read the result as a setup scorecard, not a product badge:
harness:adapters -- --check proves this public matrix still matches the
adapter source data and required evidence fields.harness:audit scores tool coverage, context efficiency, quality gates,
memory persistence, eval coverage, security guardrails, and cost efficiency.observability:ready proves the repo still exposes the local status,
session, tool-activity, risk-ledger, and release-onramp signals.session-inspect --list-adapters shows which session surfaces are actually
inspectable in the current environment.loop-status --json creates a machine-readable handoff/status payload for
longer autonomous runs.Each adapter record exposes:
idstatesupported_assetsunsupported_surfacesinstall_or_onrampverification_commandsrisk_noteslast_verified_atownersource_docsThe validator fails if a public adapter claim has no install path, verification command, risk note, owner, source doc, or verification date.