mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-29 13:33:31 +08:00
112 lines
4.2 KiB
Markdown
112 lines
4.2 KiB
Markdown
# 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
|
|
|
|
## 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.
|