Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / plugin-packaging-and-aura-integration

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 surfaceShared capability goalHost-specific limit
Claude Code pluginLoad ECC skills and legacy command entriesHook behavior is specific to Claude Code
Codex native pluginLoad ECC skills, MCP support, assets, and supported hooksPlugin enablement and hook trust remain separate concerns
OpenCode adapter packageLoad shared skills, MCP configuration, and adapted event behaviorEvent names, package shape, and command dispatch differ from Claude Code
Pi package surfaceLoad the ECC extension, skills, and prompts declared by package metadataPackage metadata does not imply equivalent hooks or session control
Antigravity 2.0 / agy CLI metadataIdentify the experimental ECC adapter packageNative acceptance is pending
Other host adaptersProject ECC guidance into the host’s local surfacesGuidance 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 name and version aligned 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

TriggerConsequenceGuard
Codex marketplace points to a thin subdirectory with parent-relative referencesThe plugin can register while its skills or MCP file are missing from the cacheUse the repository root as the native source and run the cache reference check
The ecc marketplace name has unknown or attacker-controlled provenanceSetup can use the wrong sourceVerify the Git origin and reject the collision before marketplace mutation
Claude has a legacy plugin, duplicate scope, manual layout, or overlapping managed filesSetup can create duplicate commands, hooks, or conflicting ownershipInspect the inventory and reject the state before mutation
Legacy Codex artifacts are changed or reached through an unsafe pathUpdate or uninstall can overwrite user data or follow a link outside the owned areaCompare recorded content and require trusted regular files inside trusted roots
The experimental Antigravity or agy metadata is treated as native acceptanceA host can rely on a package contract that the client does not yet supportTreat the manifest as experimental metadata until native acceptance is confirmed
The published package omits OpenCode build output or the prepack build cannot runOpenCode installation can lack its adapter surface even when the package install succeedsKeep .opencode/ in the published file set and build it during prepack
Package metadata points a host to a missing extension, skill, or prompt pathThe host can install the package but fail to load its declared surfaceKeep package metadata and the published file set aligned
A caller treats Aura trusted as current action authorizationA harmful action can pass based on old reputationPair the verdict with DID-control and forward-looking action-risk checks
Aura is reachable but returns malformed JSON, an invalid shape, or unknownfail_open=True can be misread as approvalAllow fail-open only for an unreachable endpoint

Key files

FileWhy to read it
.claude-plugin/plugin.jsonDefines the Claude Code plugin contract and hook options.
.codex-plugin/plugin.jsonDefines the native Codex manifest and package references.
plugins/…/plugin.jsonDefines the thin compatibility manifest and its links to canonical skills, MCP configuration, and assets.
plugins/…/plugin.jsonDefines experimental adapter metadata for Antigravity 2.0 and the agy CLI.
.codex-plugin/README.mdExplains native Codex installation, hook trust, cache checks, and legacy sync separation.
package.jsonDefines the published package boundary, host package metadata, OpenCode prepack build, and package tools.
package-lock.jsonLocks the OpenCode build dependency and the package dependency graph.
plugins/…/README.mdExplains why the thin Codex folder is retained only for compatibility.
scripts/build-opencode.jsShows how the OpenCode distribution is built before package publication.
scripts/…/claude-plugin-setup.jsShows Claude marketplace, scope, conflict, and post-install verification behavior.
scripts/…/codex-plugin-setup.jsShows Codex inventory, provenance, marketplace reconciliation, and verification behavior.
scripts/…/check-plugin-cache.jsChecks that the installed Codex cache contains every manifest reference.
scripts/…/resolve-ecc-root.jsDescribes current and legacy ECC root discovery for runtime callers.
scripts/…/codex-legacy-sync.jsDefines ownership, rollback, and safe removal for legacy Codex artifacts.
scripts/sync-ecc-to-codex.shDefines the copied-home compatibility flow for older Codex usage.
integrations/…/README.mdGives the opt-in Aura use model and caller policy choices.
integrations/…/adapter.pyDefines the read-only reputation lookup and trust gate boundary.
integrations/…/THREAT_MODEL.mdStates what Aura proves, what it does not prove, and which risks stay with the caller.
tests/plugin-manifest.test.jsProtects manifest shape, version alignment, package roots, and duplication rules.
integrations/…/test_adapter.pyProtects verdict mapping and fail-open or fail-closed behavior without network access.