elias/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-04-30 16:45:48 +08:00
Code Issues Packages Projects Releases Wiki Activity
everything-claude-code/docs/architecture/cross-harness.md
Affaan Mustafa 69b8ec4e0b docs: add ecc2 rc1 quickstart path
2026-04-29 20:15:38 -04:00

5.3 KiB
Raw Blame History

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

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.

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
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/.

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
  • 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
  • deeper memory and operator planning layers

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.