Plugin packaging and Aura integration
ECC presents shared agent guidance through client-specific package contracts. Claude Code and Codex use native plugin packages, while OpenCode, Pi, and other clients use package surfaces or adapters that map the same source material to host-specific forms. Aura is a separate opt-in adapter that supplies a read-only reputation signal before a caller-controlled action.
Packaging model
ECC keeps shared skills and support files in the package root. package.json defines the published package boundary and client-facing package metadata. Each supported client then receives the package shape that its host can load. This design keeps client differences at the boundary and avoids a second copy of the core content.
Native package surfaces
The native Claude Code and Codex packages describe different host contracts. Claude exposes skills and commands with optional hook settings. Codex points to skills and MCP configuration and includes its supported lifecycle package. .claude-plugin/plugin.json• L25-45, .codex-plugin/plugin.json• L13-29, package.json• L42-91
The plugins/ecc directory remains a thin compatibility surface. Its manifest keeps the ecc package identity and version and maps skills, MCP configuration, and interface assets to the canonical repository content with parent-relative paths. It is not the active source for the native Codex package. Codex must receive a self-contained copy of the root package so its manifest references remain usable after installation. plugins/…/plugin.json• L1-49, plugins/…/README.md• L1-25
The same directory also publishes experimental adapter metadata for Antigravity 2.0 and the agy CLI. That metadata carries the ECC package identity and release details, but native acceptance remains pending, so it does not establish a supported native host contract. plugins/…/plugin.json• L1-12
The package metadata also declares a Pi surface through its extension, skill, and prompt entries. This is a host package contract rather than part of the Claude Code or Codex plugin manifests. package.json• L495-504
References: .claude-plugin/plugin.json• L25-45 .codex-plugin/plugin.json• L13-29 plugins/…/plugin.json• L1-49 plugins/…/plugin.json• L1-12 package.json• L42-91 package.json• L495-504 plugins/…/README.md• L1-25
OpenCode package surface
OpenCode uses an adapter-backed package surface rather than the native Claude Code or Codex contract. The published package includes the .opencode surface, and the prepack step builds its distribution output before publication. The OpenCode plugin package is a development dependency used by that build path. package.json• L42-53, package.json• L474-475, package.json• L496-504, scripts/build-opencode.js• L7-25
The package lock keeps the OpenCode plugin version and its transitive package graph reproducible. A package can therefore have a valid publication file list while still failing its adapter build if the locked development dependency is absent or out of sync. package-lock.json• L7-37, package-lock.json• L376-403
References: package.json• L42-53 package.json• L474-475 package.json• L496-504 package-lock.json• L7-37 package-lock.json• L376-403 scripts/build-opencode.js• L7-25
Host adapter surfaces
Host adapters translate shared ECC guidance into the local form supported by each client. A host can receive instructions, rules, skills, or event behavior without receiving the full plugin contract of Claude Code or Codex. The adapter boundary therefore defines capability differences rather than hiding them. scripts/…/harness-adapter-compliance.js• L42-123, scripts/…/registry.js• L16-80
| Client surface | Shared capability goal | Host-specific limit |
|---|---|---|
| Claude Code plugin | Load ECC skills and legacy command entries | Hook behavior is specific to Claude Code |
| Codex native plugin | Load ECC skills, MCP support, assets, and supported hooks | Plugin enablement and hook trust remain separate concerns |
| OpenCode adapter package | Load shared skills, MCP configuration, and adapted event behavior | Event names, package shape, and command dispatch differ from Claude Code |
| Pi package surface | Load the ECC extension, skills, and prompts declared by package metadata | Package metadata does not imply equivalent hooks or session control |
| Antigravity 2.0 / agy CLI metadata | Identify the experimental ECC adapter package | Native acceptance is pending |
| Other host adapters | Project ECC guidance into the host’s local surfaces | Guidance does not imply equivalent hooks or session control |
References: scripts/…/harness-adapter-compliance.js• L42-123 scripts/…/registry.js• L16-80 package.json• L495-504 plugins/…/plugin.json• L1-12
Client installation flow
Installation first examines the client’s current state. It then checks source identity and package shape before changing registration. A final check confirms that the client can use the resulting package rather than only reporting a successful command.
Claude Code installation
Claude setup reconciles one official ecc@ecc plugin at a chosen scope. It rejects legacy identities, duplicate ECC installs, manual layouts, and overlapping managed content before it changes the marketplace or plugin state. It then verifies the official marketplace and confirms that the enabled plugin exists only at the requested scope. scripts/…/claude-plugin-setup.js• L400-499, scripts/…/claude-plugin-setup.js• L502-569
The scope states who receives the plugin: the user, a shared project, or a private project setting. A scope change uses an explicit migration path. The destination must be installed and checked before the old scope is removed. scripts/…/claude-plugin-setup.js• L435-475, scripts/setup.js• L28-59
Codex installation
Codex setup treats the official marketplace and the ecc@ecc plugin as separate resources. It checks their inventories and source provenance, then adds or updates them before it verifies that the plugin is installed and enabled. The native source is the repository root. Codex copies that source into a cache, so usable installation depends on the cache containing every manifest reference. scripts/…/codex-plugin-setup.js• L361-459, scripts/…/check-plugin-cache.js• L139-161, scripts/…/check-plugin-cache.js• L173-238
The package flow links source choice to runtime validation. A registered plugin is not sufficient when a copied skill, MCP file, hook, or asset is missing from the cache.
This diagram shows how source identity and package completeness lead to a usable client package.
flowchart LR
S[Official ECC source] --> I[Client inventory]
I --> P[Identity and package checks]
P --> U[Marketplace or plugin update]
U --> V[Post-change verification]
V --> R[Usable client package]
V -->|Codex| C[Cache reference check]
C --> R
References: scripts/…/codex-plugin-setup.js• L242-274 scripts/…/codex-plugin-setup.js• L361-459 scripts/…/check-plugin-cache.js• L173-238
Compatibility shims
Compatibility shims preserve older entry points while native packages become the preferred path. They translate or discover prior layouts. They do not create a second source of ECC capabilities.
Legacy client identities
Claude discovery recognizes current and historical ECC roots so runtime hooks and commands can find an installed source. Setup does not merge old identities into the current plugin. It stops when it finds a legacy plugin, duplicate scope, manual layout, or overlapping managed content. scripts/…/resolve-ecc-root.js• L7-19, scripts/…/resolve-ecc-root.js• L33-80, scripts/…/claude-plugin-setup.js• L400-499
The resolver favors an explicit plugin root and then checks known complete roots. This prevents a partial scripts-only install or an unrelated skills directory from becoming the ECC source.
References: scripts/…/resolve-ecc-root.js• L7-80 scripts/…/claude-plugin-setup.js• L400-499
Legacy Codex synchronization
The legacy Codex sync is a separate path for users who need copied home configuration. It merges marked guidance, creates prompt files from older commands, merges MCP settings, and can install global Git safety hooks. It does not register the native Codex marketplace plugin. scripts/sync-ecc-to-codex.sh• L4-11, scripts/sync-ecc-to-codex.sh• L228-243, scripts/sync-ecc-to-codex.sh• L341-365
The sync records its ownership in a state file. It can restore only files that remain inside trusted roots and still match the recorded installed content. Modified or unsafe files remain for review. This protects user changes during update and removal. scripts/…/codex-legacy-sync.js• L138-155, scripts/…/codex-legacy-sync.js• L203-221, scripts/…/codex-legacy-sync.js• L514-632
Native Codex state and legacy sync state have different owners and removal rules. Native plugin cleanup must not remove legacy copied files or user conversation data. .codex-plugin/README.md• L56-60, .codex-plugin/README.md• L80-101
References: scripts/sync-ecc-to-codex.sh• L4-11 scripts/…/codex-legacy-sync.js• L138-155 scripts/…/codex-legacy-sync.js• L203-221 scripts/…/codex-legacy-sync.js• L514-632 .codex-plugin/README.md• L80-101
Legacy selection
The selective installer maps older language names and target requests to current shared module families. It rejects unknown inputs before it creates a plan. The selected target and its dependencies then limit the result to the content that the host needs. scripts/…/install-manifests.js• L39-155, scripts/…/install-manifests.js• L478-532, scripts/…/install-manifests.js• L602-725
References: scripts/…/install-manifests.js• L39-155 scripts/…/install-manifests.js• L478-532 scripts/…/install-manifests.js• L602-725
Aura adapter boundary
Aura is an opt-in read-only adapter for a host that wants a reputation signal before a sensitive action. It performs one HTTPS lookup for a counterparty DID and returns a verdict. The caller remains responsible for identity proof, action checks, signing, funds, and the final decision. integrations/…/README.md• L1-14, integrations/…/THREAT_MODEL.md• L44-55
Trust gate
The adapter offers a direct verdict query and a gate for protected actions. The default gate allows trusted and caution. It rejects high_risk, new, and unknown. A caller can allow new for a controlled onboarding flow. integrations/…/adapter.py• L45-51, integrations/…/adapter.py• L176-209
Aura does not install a global hook or change existing action code. The host places the gate immediately before the action and combines its result with its own forward-looking risk policy. integrations/…/README.md• L11-26, integrations/…/THREAT_MODEL.md• L16-24
References: integrations/…/adapter.py• L45-51 integrations/…/adapter.py• L176-213 integrations/…/README.md• L11-26
Trust boundary
The adapter sends only the counterparty DID to the public /check endpoint and keeps no state. It validates the DID and maps unknown verdict values to unknown. It does not prove that the live caller controls the DID. integrations/…/adapter.py• L107-130, integrations/…/adapter.py• L158-173, integrations/…/THREAT_MODEL.md• L36-42
The host owns the boundary between reputation evidence and action approval. The sequence is:
sequenceDiagram
participant Host as Host action policy
participant Aura as Aura /check
participant Action as Protected action
Host->>Aura: DID-only HTTPS GET
Aura-->>Host: Reputation verdict
Host->>Host: Check identity and action risk
Host->>Action: Allow or reject
References: integrations/…/adapter.py• L133-173 integrations/…/THREAT_MODEL.md• L7-24 integrations/…/THREAT_MODEL.md• L36-55
Failure policy
The query returns unknown for transport, HTTP, parse, or response-shape failures. The gate fails closed by default. fail_open=True can excuse an unreachable endpoint only. It does not approve a reachable error, malformed response, or unknown result. integrations/…/adapter.py• L141-173, integrations/…/adapter.py• L198-209
Callers that use a mirror, cache a verdict, or treat trusted as permission for an irreversible action own the related freshness, provenance, identity, and action-risk checks. integrations/…/THREAT_MODEL.md• L25-34
References: integrations/…/adapter.py• L141-173 integrations/…/adapter.py• L198-209 integrations/…/THREAT_MODEL.md• L25-34
Validation and threat concerns
Package tests protect client contracts and source boundaries. Aura tests protect the decision boundary without depending on a live network. Together they check that a package or reputation result cannot gain more authority than its contract grants.
Package validation
Manifest checks cover identity and version alignment, client-specific field shapes, supported hook projections, root-relative Codex references, and the absence of duplicated content in the thin marketplace folder. Setup checks cover provenance, inventory shape, scope conflicts, mutation order, and post-change state. tests/plugin-manifest.test.js• L302-410, tests/plugin-manifest.test.js• L537-619, tests/…/codex-plugin-setup.test.js• L194-243
These checks catch failures that a successful registration can hide. They also block an untrusted marketplace and references that escape the installed package boundary. tests/…/codex-plugin-setup.test.js• L464-506, scripts/…/check-plugin-cache.js• L199-237
References: tests/plugin-manifest.test.js• L302-410 tests/plugin-manifest.test.js• L537-619 tests/…/codex-plugin-setup.test.js• L194-243 scripts/…/check-plugin-cache.js• L199-237
Aura validation
Aura tests replay recorded response bodies through an injection seam. They cover verdict classes, custom allow lists, input checks, transport failure, and the difference between an unreachable service and a reachable invalid response. integrations/…/test_adapter.py• L1-12, integrations/…/test_adapter.py• L105-187
Offline fixtures keep policy checks independent from endpoint availability. This lets the suite test both the response shape and the caller’s allow or reject decision. integrations/…/fixtures.py• L1-7, integrations/…/fixtures.py• L70-94
References: integrations/…/test_adapter.py• L1-12 integrations/…/test_adapter.py• L105-187 integrations/…/fixtures.py• L1-7
Threat model
An Aura verdict is evidence about recorded past behavior. It is not proof of current action safety, execution quality, or live identity control. High-value actions still need a separate action-risk check and may need escrow or human review. integrations/…/THREAT_MODEL.md• L7-24
Package installation has a similar trust boundary. Marketplace provenance, safe path handling, and post-change verification prevent a name collision or incomplete cache from becoming a trusted runtime. scripts/…/codex-plugin-setup.js• L242-274, scripts/…/codex-plugin-setup.js• L333-355
References: integrations/…/THREAT_MODEL.md• L7-34 scripts/…/codex-plugin-setup.js• L242-274 scripts/…/codex-plugin-setup.js• L333-355
For the wider host capability matrix, see Host integrations and plugin adapters. For event, hook, and persistence behavior, see Hooks, memory, and host events.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep
nameandversionaligned across the Claude manifest, Codex manifest, and compatibility manifest. The package checks and release flow depend on this contract. - When the compatibility Codex manifest changes its parent-relative references or interface assets, keep it aligned with the canonical root content and the thin-directory rule.
- When experimental adapter metadata changes, keep its package identity and version aligned with the release while preserving the statement that native acceptance is pending.
- When a Codex manifest path or marketplace source changes, update the root package contents and cache check together. A path can work in a checkout and fail after Codex copies the package.
- When the published file set or OpenCode prepack build changes, keep the build output and package inclusion aligned. A package can publish successfully while its adapter references are absent.
- When package metadata adds or removes a host surface, check that the published file set and the host's expected extension, skill, and prompt paths still match.
- When Claude identity or scope behavior changes, keep legacy, duplicate, manual, and overlapping installs rejected before provider mutation.
- Keep native Codex state and legacy home-sync state as separate ownership models. Do not let native cleanup remove copied legacy files or conversation data.
- When changing legacy sync ownership or removal, preserve trusted-root checks and the rule that modified artifacts remain for review.
- When Aura verdict or failure handling changes, preserve the difference between transport failure and a reachable invalid or unknown response. Recheck the caller’s action-risk and DID-control duties.
- Keep Aura tests offline through the fetch seam and recorded response shapes. Do not make policy coverage depend on the live endpoint.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Codex marketplace points to a thin subdirectory with parent-relative references | The plugin can register while its skills or MCP file are missing from the cache | Use the repository root as the native source and run the cache reference check |
The ecc marketplace name has unknown or attacker-controlled provenance | Setup can use the wrong source | Verify the Git origin and reject the collision before marketplace mutation |
| Claude has a legacy plugin, duplicate scope, manual layout, or overlapping managed files | Setup can create duplicate commands, hooks, or conflicting ownership | Inspect the inventory and reject the state before mutation |
| Legacy Codex artifacts are changed or reached through an unsafe path | Update or uninstall can overwrite user data or follow a link outside the owned area | Compare recorded content and require trusted regular files inside trusted roots |
| The experimental Antigravity or agy metadata is treated as native acceptance | A host can rely on a package contract that the client does not yet support | Treat the manifest as experimental metadata until native acceptance is confirmed |
| The published package omits OpenCode build output or the prepack build cannot run | OpenCode installation can lack its adapter surface even when the package install succeeds | Keep .opencode/ in the published file set and build it during prepack |
| Package metadata points a host to a missing extension, skill, or prompt path | The host can install the package but fail to load its declared surface | Keep package metadata and the published file set aligned |
A caller treats Aura trusted as current action authorization | A harmful action can pass based on old reputation | Pair the verdict with DID-control and forward-looking action-risk checks |
Aura is reachable but returns malformed JSON, an invalid shape, or unknown | fail_open=True can be misread as approval | Allow fail-open only for an unreachable endpoint |
Key files
| File | Why to read it |
|---|---|
| .claude-plugin/plugin.json | Defines the Claude Code plugin contract and hook options. |
| .codex-plugin/plugin.json | Defines the native Codex manifest and package references. |
| plugins/…/plugin.json | Defines the thin compatibility manifest and its links to canonical skills, MCP configuration, and assets. |
| plugins/…/plugin.json | Defines experimental adapter metadata for Antigravity 2.0 and the agy CLI. |
| .codex-plugin/README.md | Explains native Codex installation, hook trust, cache checks, and legacy sync separation. |
| package.json | Defines the published package boundary, host package metadata, OpenCode prepack build, and package tools. |
| package-lock.json | Locks the OpenCode build dependency and the package dependency graph. |
| plugins/…/README.md | Explains why the thin Codex folder is retained only for compatibility. |
| scripts/build-opencode.js | Shows how the OpenCode distribution is built before package publication. |
| scripts/…/claude-plugin-setup.js | Shows Claude marketplace, scope, conflict, and post-install verification behavior. |
| scripts/…/codex-plugin-setup.js | Shows Codex inventory, provenance, marketplace reconciliation, and verification behavior. |
| scripts/…/check-plugin-cache.js | Checks that the installed Codex cache contains every manifest reference. |
| scripts/…/resolve-ecc-root.js | Describes current and legacy ECC root discovery for runtime callers. |
| scripts/…/codex-legacy-sync.js | Defines ownership, rollback, and safe removal for legacy Codex artifacts. |
| scripts/sync-ecc-to-codex.sh | Defines the copied-home compatibility flow for older Codex usage. |
| integrations/…/README.md | Gives the opt-in Aura use model and caller policy choices. |
| integrations/…/adapter.py | Defines the read-only reputation lookup and trust gate boundary. |
| integrations/…/THREAT_MODEL.md | States what Aura proves, what it does not prove, and which risks stay with the caller. |
| tests/plugin-manifest.test.js | Protects manifest shape, version alignment, package roots, and duplication rules. |
| integrations/…/test_adapter.py | Protects verdict mapping and fail-open or fail-closed behavior without network access. |