How to Configure Cross-Harness Compatibility in ECC: Complete Setup Guide

Run ./install.sh --target <harness> to generate adapter files for Claude Code, Codex, Cursor, OpenCode, or Gemini, then verify compliance with npm run harness:adapters -- --check to ensure shared skills and rules work across all supported runtimes.

ECC (Everything Claude Code) is designed as a reusable workflow layer that operates across multiple AI coding harnesses. When you configure cross-harness compatibility in ECC, you enable a single source of truth for skills, rules, and hooks that adapts to each runtime's native conventions without duplicating business logic.

Understanding the Cross-Harness Architecture

ECC organizes compatibility into three distinct layers. Understanding these layers ensures you place customizations in the correct location without corrupting portable assets.

Durable Assets (Portable Layer)

The durable assets are files that never change per harness. These include:

• skills/*/SKILL.md — Skill definitions with frontmatter that work verbatim in any harness
• rules/ — Shared rule definitions for code quality and constraints
• hooks/hooks.json — Hook definitions executed natively by Claude Code and translated by adapters
• mcp-configs/ — Model Context Protocol configurations
• scripts/ — Utility scripts for installation and verification

These files live in the repository once and remain unchanged regardless of the target harness.

Adapter Surface (Harness-Specific Glue)

The adapter surface contains harness-specific metadata that tells each runtime how to install, load, and invoke durable assets. According to the architecture documentation in docs/architecture/cross-harness.md, adapters handle wrapper scripts, command shims, and packaging files that bridge ECC's portable layer to a harness's native expectations.

Session Orchestration (Optional Runtime)

For long-running or multi-session workflows, the session layer includes the ecc2/ control plane (Rust-based) and helper scripts like scripts/orchestrate-worktrees.js. This layer is alpha status and only required for advanced coordination across tmux sessions or git worktrees.

Installing Harness-Specific Adapters

Use the universal installer script to generate the correct adapter files for your target harness. The script accepts a --target flag and reads configuration data from scripts/lib/harness-adapter-compliance.js.

Run one of the following commands based on your target environment:

# Claude Code (native support)

./install.sh --profile minimal --target claude

# Codex (instruction-backed adapter)

./install.sh --profile minimal --target codex

# OpenCode (adapter-backed)

./install.sh --profile minimal --target opencode

# Cursor (adapter-backed)

./install.sh --profile minimal --target cursor

# Gemini (instruction-backed)

./install.sh --profile minimal --target gemini

The script creates the necessary wrapper files and directory structures (such as .cursor/rules/ or .agents/skills/) while keeping durable assets in their original locations.

Verifying Cross-Harness Compliance

After installation, validate that your configuration meets the requirements defined in docs/architecture/harness-adapter-compliance.md. The compliance matrix tracks whether each harness has Native, Adapter-backed, Instruction-backed, or Reference-only support.

Run the verification suite:

# Validate the matrix data structure

npm run harness:adapters -- --check

# Run full capability audit with JSON output

npm run harness:audit -- --format json

# Check observability readiness

npm run observability:ready

# List available session adapters

node scripts/session-inspect.js --list-adapters

These commands verify that every adapter record contains an install path, verification command, risk note, and current last_verified_at timestamp.

Customizing Adapters for Specific Harnesses

When a harness requires different command names or event shapes, edit the small adapter file rather than duplicating the entire skill. For example, to add a Codex-specific slash-command alias, copy the skill to the harness-specific directory while keeping the content identical:

# Copied to .agents/skills/my-skill/SKILL.md

# Add Codex-only command metadata

command: my-skill-codex

The original file remains in skills/my-skill/SKILL.md, while the adapter handles the translation to Codex's expected format.

For Cursor-specific rule adjustments, create harness-specific copies under .cursor/rules/:

# .cursor/rules/curated.rules.yaml

rules:
  - name: no-console-log
    pattern: "console\\.log"
    level: warning

Advanced Session Orchestration

For complex workflows requiring persistence across multiple sessions, use the optional orchestration layer:

# Plan and execute cross-harness worktrees

node scripts/orchestrate-worktrees.js plan.json --execute

The ecc2/ control plane (Rust implementation) manages these sessions, respecting the adapter matrix and only spawning the required harness runtime when necessary.

Summary

• Durable assets (skills/*/SKILL.md, rules/, hooks/hooks.json) remain unchanged across all harnesses and represent the single source of truth.
• Run ./install.sh --target <harness> to generate adapter files for Claude Code, Codex, Cursor, OpenCode, or Gemini based on the compliance matrix.
• Verify installations using npm run harness:adapters -- --check and node scripts/session-inspect.js --list-adapters to ensure compatibility.
• Edit adapter files, not durable assets, when a harness requires specific command aliases or event shapes.
• Use ecc2/ and scripts/orchestrate-worktrees.js only when you need advanced session management across multiple worktrees or tmux sessions.

Frequently Asked Questions

Where is the compliance matrix data stored?

The compliance matrix data is stored in scripts/lib/harness-adapter-compliance.js. This file defines which harnesses have native support versus adapter-backed or instruction-backed support, and it provides the verification commands used by npm run harness:adapters -- --check.

Can I use the same SKILL.md file across Claude Code and Cursor?

Yes. The SKILL.md format is the most portable unit in ECC. You can copy the file verbatim from skills/*/SKILL.md into harness-specific locations like .cursor/skills/ or .agents/skills/ while maintaining identical frontmatter and content. The adapter layer handles any necessary translations for the target harness.

What is the difference between adapter-backed and instruction-backed harnesses?

Adapter-backed harnesses (like Cursor and OpenCode) use wrapper scripts and configuration files generated by install.sh to translate ECC assets into the harness's native format. Instruction-backed harnesses (like Codex and Gemini) rely on specific prompting instructions or documentation files rather than programmatic adapters, though both types use the same durable assets underneath.

How do I check if my current environment supports a specific harness?

Run node scripts/session-inspect.js --list-adapters to display all available adapters in your current environment. This command checks the installed components against the compliance matrix and lists which harnesses are ready for use based on the generated adapter files and system configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}