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

> Configure cross-harness compatibility in ECC by running install.sh then verifying compliance with npm run harnessadapters to ensure shared skills work across all runtimes

- Repository: [Affaan Mustafa/ECC](https://github.com/affaan-m/ECC)
- Tags: how-to-guide
- Published: 2026-05-26

---

**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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/scripts/lib/harness-adapter-compliance.js).

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

```bash

# 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`](https://github.com/affaan-m/ECC/blob/main/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:

```bash

# 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:

```yaml

# 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`](https://github.com/affaan-m/ECC/blob/main/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/`:

```yaml

# .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:

```bash

# 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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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`](https://github.com/affaan-m/ECC/blob/main/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.