Status: research complete. Extracts the reusable install-pipeline architecture from ECC (Enhanced Claude Code, ~/ECC) — a mature, harness-agnostic operator system that installs one source tree into 14 target Agent tools. This doc is the evidence base for the Phase 3 design rewrite (design-phase-3-install.md), which adopts ECC's adapter factory + plan/ apply + install-state model. All code excerpts are from the ECC repo as of the time of writing; verify before copying verbatim.

ECC's explicit design philosophy (per docs/ECC-2.0-REFERENCE-ARCHITECTURE.md) is that treating any one agent harness as the canonical interface is a non-goal — the per-target adapter compliance matrix is the product. That is exactly Harness Nexus's thesis (consume upstream MCP once, re-expose aggregated to every tool), which makes ECC's install layer the closest existing implementation of what Phase 3 needs to build.

ECC is NOT copied wholesale. The transferable parts are the patterns (architecture, adapter factory, plan/apply, install-state); ECC's specific content (281 skills, 94 commands, its own module/profile/component declaration layer) is out of scope — Harness Nexus has its own Resource model. We also improve on ECC's one known rough edge (Codex's dual install path).

content        agents/ skills/ commands/ rules/ hooks/ mcp-configs/
               (the single source of truth — ECC's, not ours)
     │
declaration    manifests/install-{modules,profiles,components}.json
               modules (atomic, +deps/cost/stability) → profiles (named bundles)
               → components (user-facing family prefixes)
     │
resolution     scripts/lib/install-manifests.js — expand profiles+components
               into module IDs, resolve the dependency DAG (cycle detection),
               filter by target support
     │
target         scripts/lib/install-targets/*.js — 14 adapters behind registry.js
adapters       each turns selected modules (with source paths) into concrete
               file operations, applying namespacing/flattening/format rules
     │
execution      scripts/lib/install-executor.js + install/apply.js — materialize
               operations (copy-file / merge-json / link-rewrite), write
               install-state ledger
     │
operator       ecc.js CLI (plan/install/catalog/consult/doctor/repair/uninstall)

Harness Nexus maps onto this as: our Profile ≈ ECC's profile bundle; our Resource entries ≈ ECC's modules; our per-target adapter ≈ ECC's install target adapter. We do not adopt ECC's three-layer declaration system (modules/profiles/components) — our Profile + Resource model is simpler and already built (Phase 4.2–4.6).

A target adapter is produced by createInstallTargetAdapter(config) in scripts/lib/install-targets/helpers.js. A minimal adapter (Hermes, Codex) is a ~10-line config object:

// scripts/lib/install-targets/hermes-home.js — the entire file
const { createInstallTargetAdapter } = require('./helpers');
module.exports = createInstallTargetAdapter({
  id: 'hermes-home',
  target: 'hermes',
  kind: 'home', // 'home' (~/.xxx) | 'project' (./.xxx)
  rootSegments: ['.hermes'],
  installStatePathSegments: ['ecc-install-state.json'],
  nativeRootRelativePath: '.hermes',
});

The factory supplies default behavior, all overridable:

Adapters needing transformation override planOperations (Claude remaps rules/**→rules/ecc/**; Cursor flattens to .mdc; OpenCode requires a build step). The factory returns Object.freeze(adapter) — adapters are immutable records.

Harness Nexus adoption: packages/cli/src/install/adapters/ holds one file per target, each calling a local createTargetAdapter(config). Hermes and Codex start as near-minimal configs; Claude Code overrides planOperations for its namespacing. Adding a target = one new file.

A module's paths array can include every target's native directory. Each adapter silently drops paths belonging to a different target via isForeignPlatformPath:

// scripts/lib/install-targets/helpers.js — the ownership map
const PLATFORM_SOURCE_PATH_OWNERS = Object.freeze({
  '.claude-plugin': 'claude', '.codex': 'codex', '.cursor': 'cursor',
  '.gemini': 'gemini', '.hermes': 'hermes', /* …9 more… */,
});

function isForeignPlatformPath(sourceRelativePath, adapterTarget) {
  const normalizedPath = normalizeRelativePath(sourceRelativePath);
  for (const [prefix, ownerTarget] of Object.entries(PLATFORM_SOURCE_PATH_OWNERS)) {
    if (normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`)) {
      return ownerTarget !== adapterTarget;   // drop if owned by another target
    }
  }
  return false;
}

This is how one source feeds N targets without per-target duplication: a module lists .claude-plugin/..., .codex/..., .hermes/... and each adapter keeps only its own.

Harness Nexus adoption: our adapter base class uses the same filter. A profile's resources are target-agnostic in storage; the adapter drops anything that doesn't belong to its target at plan time.

Two entrypoints (scripts/install-plan.js, scripts/install-apply.js) feed one resolver:

• plan = resolve request → operation list. No filesystem writes. Serializable, inspectable, dry-runnable.
• apply = materialize the plan's operations to disk + write the install-state ledger.

applyInstallPlan (scripts/lib/install/apply.js:163) loops operations of three kinds:

Harness Nexus adoption: hnx install --profile <id> defaults to plan (dry-run, prints what would happen); --apply materializes. The plan is the unit the user reviews before any file is touched — this is safer than the original Phase 3 draft's "emit a directory and let the user copy it" approach.

MCP config is the format-divergence crux. ECC has two writer families from one source-of-truth (.mcp.json):

1. JSON targets (Claude / Cursor / OpenCode) — merge-json operation does a deepMergeJson into the target's existing .mcp.json/mcp.json, preserving user servers.
2. TOML target (Codex) — scripts/codex/merge-mcp-config.js does add-only TOML text surgery: parse [mcp_servers.*], append missing sections raw, preserve the file byte-for-byte otherwise. Builds server specs via dlxServer() which respects the detected package manager (npx/pnpm dlx/bunx/yarn dlx). Codex MCP is stdio-only — it refuses url keys (ECC issue #2224).

// ECC's single MCP source-of-truth: .mcp.json (abridged)
{
  "mcpServers": {
    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
  },
}

Harness Nexus adoption: our proxy-mode MCP emission (single aggregated /mcp?profile=<id> entry) and direct-mode emission (verbatim connection) each have a per-format emitter: JSON for Claude, TOML for Codex, YAML for Hermes. The adapter picks the emitter; the resolver hands it the same resolved MCP spec.

Every apply writes a ledger (schemas/install-state.schema.json, schemaVersion: "ecc.install.v1") recording every operation:

{ schemaVersion, installedAt, lastValidatedAt,
  target: { id, root, installStatePath, kind },
  request,            // what was asked for
  resolution,         // selected/skipped modules
  source: { repoVersion, repoCommit, manifestVersion },
  operations: [...]   // the full op list — the replay log
}

This is what makes doctor (detect drift), repair (restore managed files), and uninstall (remove only managed files) work idempotently. ECC validates it with a dependency-free hand-rolled validator (supply-chain vetting requires the validated bytes to be the installed bytes — no external Ajv in the runtime closure).

Harness Nexus adoption: each install writes a harness-nexus-install-state.json in the target root. Phase 3.3 ships plan + apply; doctor/repair/uninstall can follow but the ledger is written from day one so the surface exists.

This is the target with zero prior research in Harness Nexus; ECC fills the gap with ground-truth files:

The Codex dual-path lesson (improve, don't copy): ECC installs Codex via two parallel paths — the Node codex-home adapter (skills/rules) AND a separate bash scripts/sync-ecc-to-codex.sh sidecar (AGENTS.md marker-merge, TOML merge, prompt generation, git hooks). For a greenfield pipeline we fold both into one adapter with format-aware writers (JSON manifest + TOML config emitter), avoiding ECC's split-brain.

Confidence: medium. ECC's hermes-home adapter is minimal (rootSegments: ['.hermes']), and ECC treats Hermes as a first-class target (91 file mentions), but the full plugin.yaml schema still needs verification against hermes_cli/plugins.py before the Hermes adapter ships (Phase 3.4).

Unchanged from prior research; included for the comparison table:

ECC has zero references to ZCode anywhere in its repo (grep confirmed). The Harness Nexus prior research (research-phase-3-plugin-targets.md) relied on a single on-disk inspection that is no longer reproducible. ZCode stays in the AgentTarget enum (non-breaking) but is marked unsupported — no adapter, no writer, hnx install --target zcode → 409 TARGET_UNSUPPORTED. It can be revived if a reference surfaces.

The format divergence (YAML / JSON / TOML) is exactly why each target gets its own adapter rather than a shared "JSON-family" writer — Codex's TOML config and unique manifest interface block make sharing with CC a conditional mess.

Take:

• Target adapter factory (createTargetAdapter(config) + frozen adapter + overridable planOperations).
• Foreign-platform path filtering (one source feeds N targets).
• Plan/apply separation (dry-run by default, --apply to write).
• install-state ledger (written from day one for doctor/repair/uninstall).
• Format-aware config emitters (one MCP source, per-format writers).
• Per-target independent adapters (Hermes / CC / Codex each own their manifest + config format).

Leave (ECC-specific, not our model):

• ECC's three-layer declaration (modules/profiles/components) — we use Profile + Resource.
• ECC's 281 skills / 94 commands content.
• ECC's dependency-free validator requirement (we're not supply-chain-vetting the runtime closure the same way).
• ECC's Codex bash sidecar — we unify into one adapter.

• scripts/lib/install-targets/helpers.js — createInstallTargetAdapter, isForeignPlatformPath, PLATFORM_SOURCE_PATH_OWNERS.
• scripts/lib/install-targets/registry.js — adapter registry + planInstallTargetScaffold.
• scripts/lib/install-targets/{hermes,codex}-home.js — minimal adapter examples.
• scripts/lib/install/apply.js — applyInstallPlan, operation kinds, deepMergeJson.
• scripts/codex/merge-{codex,mcp}-config.js — TOML add-only mergers.
• schemas/install-state.schema.json — ledger schema (ecc.install.v1).
• manifests/install-modules.json — module shape (paths + targets array).
• .codex-plugin/plugin.json, .codex/config.toml — Codex ground-truth format.
• docs/ECC-2.0-REFERENCE-ARCHITECTURE.md — "no canonical harness" philosophy.