ECC/docs/architecture/cross-harness.md

Cross-Harness Architecture

ECC is the reusable workflow layer. Harnesses are execution surfaces.

The goal is to keep the durable parts of agentic work in one repo:

• skills
• rules and instructions
• hooks where the harness supports them
• MCP configuration
• install manifests
• session and orchestration patterns
• durable, harness-neutral memory documents

Claude Code, Codex, OpenCode, Cursor, Gemini, and future harnesses should adapt those assets at the edge instead of requiring a new workflow model for every tool.

For the operator-facing support matrix and scorecard workflow, see Harness Adapter Compliance Matrix. For the full-stack platform framing and product-integration loop, see ECC Platform Value Loop.

Portability Model

Surface	Shared Source	Harness Adapter	Current Status
Skills	skills/*/SKILL.md	Claude plugin, Codex plugin, .agents/skills, Cursor skill copies, OpenCode plugin/config	Supported with harness-specific packaging
Rules and instructions	rules/, AGENTS.md, translated docs	Claude rules install, Codex AGENTS.md, Cursor rules, OpenCode instructions	Supported, but not identical across harnesses
Hooks	hooks/hooks.json, scripts/hooks/	Claude native hooks, OpenCode plugin events, Cursor hook adapter	Hook-backed in Claude/OpenCode/Cursor; instruction-backed in Codex
MCPs	.mcp.json, mcp-configs/	Native MCP config import per harness	Supported where the harness exposes MCP
Commands	commands/, CLI scripts	Claude slash commands, compatibility shims, CLI entrypoints	Supported, but command semantics vary
Memory	.ecc/memory/, ~/.ecc/memory/	ecc memory CLI or opt-in ecc-memory-mcp stdio server	Supported with explicit recall and unreviewed writes
Sessions	ecc2/, session adapters, orchestration scripts	TUI/daemon, tmux/worktree orchestration, harness-specific runners	Alpha

What Travels Unchanged

SKILL.md is the most portable unit.

A good ECC skill should:

• use YAML frontmatter with name, description, and origin
• describe when to use the skill
• state required tools or connectors without embedding secrets
• keep examples repo-relative or generic
• avoid harness-only command assumptions unless the section is clearly labeled

The same source skill can be installed into multiple harnesses because it is mostly instructions, constraints, and workflow shape.

What Gets Adapted

Each harness has different loading and enforcement behavior:

• Claude Code loads plugin assets and has native hook execution.
• Codex reads AGENTS.md, plugin metadata, skills, and MCP config, but hook parity is instruction-driven.
• OpenCode has a plugin/event system that can reuse ECC hook logic through an adapter layer.
• Cursor uses its own rule and hook layout, so ECC maintains translated surfaces under .cursor/.
• Gemini support is install/instruction oriented and should be treated as a compatibility surface, not as full hook parity.

Adapters should stay thin. The shared behavior belongs in skills/, rules/, hooks/, scripts/, and mcp-configs/.

Shared Memory Contract

ECC Memory Vault is the common knowledge-transfer surface for Claude, Codex, Hermes, Cursor, OpenCode, and other agents. It stores portable ecc.memory.v1 Markdown documents in three scopes:

• project: <repo>/.ecc/memory/project/
• team: <repo>/.ecc/memory/team/
• user: ~/.ecc/memory/

Every harness must use the same repository working directory or the same ECC_MEMORY_PROJECT_ROOT and ECC_MEMORY_USER_ROOT overrides. The deterministic ecc memory CLI is the baseline interface. Harnesses with MCP support may instead launch ecc-memory-mcp and use memory_save, memory_search, memory_read, and memory_doctor. Normal search recall is active-only across project and team; a direct ID read can inspect a non-active entry, and user must be requested explicitly. The CLI target flag is a caller-selected routing filter, not an authorization boundary.

The MCP server is opt-in. Its reference entry lives in mcp-configs/mcp-servers.json; it is intentionally absent from the default .mcp.json so installations do not silently gain a writable context surface or pay its tool-schema cost. Each MCP process requires a lowercase ECC_MEMORY_HARNESS; this server-bound identity supplies the source harness and target filter, so a tool caller cannot select another identity. User-scope MCP access remains blocked unless the operator launches the process with ECC_MEMORY_ALLOW_USER_SCOPE=1.

The trust boundary is consistent across every adapter:

• all first-release vault entries are create-only and always unreviewed;
• recalled memory is data, not executable instruction;
• known secret-shaped writes are rejected as a best-effort backstop, and readers do not follow symlinks;
• project-scope writes stop if the vault's protective .gitignore is altered;
• human acceptance promotes knowledge into a governed repository artifact; it never turns memory frontmatter into a self-asserted approval;
• active execution state remains in GitHub or Linear, not only in memory.

skills/unified-memory/SKILL.md owns this workflow. Codex and Cursor receive behavior-identical packaging copies under .agents/skills/ and .cursor/skills/; Hermes can import the canonical skill. No harness owns a separate authoritative memory store.

Hermes Boundary

Hermes is not the public ECC runtime.

Hermes is an operator shell that can consume ECC assets:

• import selected ECC skills into a Hermes skills directory
• use ECC MCP conventions for tool access
• route chat, CLI, cron, and handoff workflows through reusable ECC patterns
• distill repeated local operator work back into sanitized ECC skills

The public repo should ship reusable patterns, not local Hermes state.

Do ship:

• sanitized setup docs
• repo-relative demo prompts
• general operator skills
• examples that do not depend on private credentials

Do not ship:

• OAuth tokens or API keys
• raw ~/.hermes exports
• personal workspace memory
• private datasets
• local-only automation packs that have not been reviewed

Worked Example

Use skills/hermes-imports/SKILL.md as the same skill source across harnesses.

The workflow is:

1. Author the durable behavior once in skills/hermes-imports/SKILL.md.
2. Keep secrets, local paths, and raw operator memory out of the skill.
3. Let each harness adapt how the skill is loaded.
4. Test the source skill and the harness-facing metadata separately.

Claude Code gets the skill through the Claude plugin surface and can enforce related hooks natively.

Codex reads the repo instructions, .codex-plugin/plugin.json, and the MCP reference config. The same skill source still describes the workflow, but hook parity is instruction-backed unless Codex adds a native hook surface.

OpenCode gets the skill through the OpenCode package/plugin surface. Event handling can reuse ECC hook logic through the adapter layer, while the skill text stays unchanged.

If a change requires editing three harness copies of the same workflow, the shared source is in the wrong place. Put the workflow back in skills/, then adapt only loading, event shape, or command routing at the harness edge.

Today vs Later

Supported today:

• shared skill source in skills/
• Claude Code plugin packaging
• Codex plugin metadata and MCP reference config
• OpenCode package/plugin surface
• Cursor-adapted rules, hooks, and skills
• file-first cross-harness memory through the CLI and opt-in MCP adapter
• ecc2/ as an alpha Rust control plane

Still maturing:

• exact hook parity across all harnesses
• automated skill sync into Hermes
• release packaging for ecc2/
• cross-harness session resume semantics
• optional semantic reranking and governed memory-promotion workflows
• the full platform loop where external products contribute skill packs, gated APIs, evals, and case studies back into ECC

Rule For New Work

When adding a workflow, put the durable behavior in ECC first.

Use harness-specific files only for:

• loading the shared asset
• adapting event shapes
• mapping command names
• handling platform limits

If a workflow only works in one harness, document that boundary directly.