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 / installation-manifests-and-schemas

Installation manifests and schemas

The installation manifest system defines what ECC can install and how users select it. Components present user-facing capabilities, modules group source content for supported targets, and profiles provide named module sets. A validated install-state record then preserves the request, the resolved selection, and the managed file operations for later health checks, repair, update, and removal. See Installation and distribution for the wider install lifecycle and Installer orchestration for the related execution flow.

Manifest model

The manifests form a small selection model rather than a list of individual files. A user chooses a profile, module, or component; the installer resolves that choice into target-compatible modules and records the result as persistent state.

Component manifests

An install component is a user-facing capability with a stable ID, a family, a description, and one or more module IDs. Component families distinguish broad selection areas such as baseline support, languages, frameworks, capabilities, agents, skills, and locales. For example, capability:database exposes the database module while framework:quarkus combines framework guidance with security guidance. (manifests/install-components.json lines 1-16, 125-145)

Components give selection a meaningful product boundary. The catalog also covers platform-specific capability groups such as Itô compute, Nasiko control-plane guidance, translated documentation, and optional documentation change and test workflows. The installer expands each selected component into its modules, removes duplicates, and can filter the component by the targets supported by all of its modules. (manifests/install-components.json lines 158-211, 594-672, 730-744; scripts/…/install-manifests.js lines 371-407, 448-460)

The component schema keeps this public catalog predictable. IDs must use a known family prefix and a lowercase, hyphenated suffix. Each component must have a non-empty description and at least one module reference. (schemas/install-components.schema.json lines 15-54)

References: manifests/install-components.json• L1-16 manifests/install-components.json• L125-145 manifests/install-components.json• L158-211 manifests/install-components.json• L594-672 manifests/install-components.json• L730-744 schemas/install-components.schema.json• L15-54 scripts/…/install-manifests.js• L371-460

Module manifests

An install module is the unit that the installer resolves and installs for a target. It names a kind of content, the source paths that belong to it, the targets that can receive it, its dependencies, and install metadata such as default status, expected cost, and stability. The catalog covers shared rules, agents, commands, hooks, platform setup, skills, orchestration, translated docs, and shared utility support. (manifests/install-modules.json lines 3-29, 31-150, 739-763, 993-1151, 1363-1453)

Dependencies make modules composable. A selected module brings in its required modules, while target support can cause a requested module to be skipped or can prevent a dependent selection from resolving. Optional dependencies may be omitted when the selected target does not support them; supported optional dependencies still install. For example, optional capability modules can depend on common platform or workflow support, while orchestration depends on command and platform support. The resolver also rejects unknown IDs and circular dependency chains. (manifests/install-modules.json lines 239-247, 381-387, 756-762; schemas/install-modules.schema.json lines 70-85; scripts/…/install-manifests.js lines 262-283, 623-685)

The module schema limits the vocabulary for kinds, targets, cost, and stability. It also requires source paths and dependency lists even when those lists are empty. This gives planning and later state checks a complete description of each module. (schemas/install-modules.schema.json lines 10-31, 37-44, 45-93, 95-114)

References: manifests/install-modules.json• L3-29 manifests/install-modules.json• L239-247 manifests/install-modules.json• L381-387 manifests/install-modules.json• L739-763 manifests/install-modules.json• L993-1151 manifests/install-modules.json• L1363-1453 schemas/install-modules.schema.json• L10-114 schemas/install-modules.schema.json• L70-85 scripts/…/install-manifests.js• L262-283 scripts/…/install-manifests.js• L623-685

Profile manifests

An install profile is a named preset of modules for a common installation goal. Profiles describe the intended balance between baseline support and optional capability areas, from the small minimal and core sets through the broader developer, research, security, and full sets. The full profile also tracks newer optional documentation and regression workflows as classified modules. (manifests/install-profiles.json lines 3-108)

Profiles do not replace modules or components. They provide a starting selection that can be combined with explicit component choices and target filtering. The resolver uses a target-specific default profile only when the request does not already name a profile, module, or component; OpenCode therefore starts from its dedicated profile and keeps hooks opt-in. (scripts/…/install-manifests.js lines 145-155, 535-570)

The profile schema requires a version and at least one profile. Every profile must have a non-empty description and at least one lowercase module ID. The schema checks the shape of those references; manifest validation checks whether the referenced modules exist and whether required profiles are present. (schemas/install-profiles.schema.json lines 10-44; scripts/…/validate-install-manifests.js lines 173-215; scripts/…/install-manifests.js lines 262-273)

References: manifests/install-profiles.json• L3-108 schemas/install-profiles.schema.json• L10-44 scripts/…/validate-install-manifests.js• L173-215 scripts/…/install-manifests.js• L145-155 scripts/…/install-manifests.js• L535-570

Synthetic skill components

The selection model also exposes a skill directory as a one-skill component when the directory has no catalog entry. This keeps individual skills selectable without requiring a separate hand-written component entry for every skill. (scripts/…/install-manifests.js lines 170-217)

These generated entries follow the same conceptual model as declared entries: a skill:<id> component points to a skill-<id> module. They are added when manifests load, so tools that list or resolve components see both cataloged and discovered skill choices. (scripts/…/install-manifests.js lines 293-334)

The skill trigger manifest is adjacent metadata for context retrieval, not another install selection layer. manifests/…/skill-triggers@1.json maps some skill IDs to short user phrases and records the registry digest and trigger coverage. The runtime loader accepts only schema version 1, normalizes trigger phrases, and the context-profile validator rejects unknown skills, stale registry data, or a changed trigger digest. (manifests/…/skill-triggers@1.json line 1; scripts/…/context-pack-registry.js lines 128-142; scripts/…/validate-context-profiles.js lines 8-23)

References: scripts/…/install-manifests.js• L170-217 scripts/…/install-manifests.js• L293-334 manifests/…/skill-triggers@1.json• L1 scripts/…/context-pack-registry.js• L128-142 scripts/…/validate-context-profiles.js• L8-23

Selection flow

The selection flow turns user intent into an install plan without treating every request as a raw file copy. It combines named presets and capabilities, applies exclusions, resolves dependencies, checks target support, and returns selected, skipped, and excluded modules.

The relationship between the three manifest levels and the resulting plan is shown below.

flowchart LR
    Request[Install request] --> Profile[Profile modules]
    Request --> Component[Component modules]
    Request --> Module[Explicit modules]
    Profile --> Resolve[Resolve dependencies and target support]
    Component --> Resolve
    Module --> Resolve
    Resolve --> Selected[Selected modules]
    Resolve --> Skipped[Skipped modules]
    Resolve --> Excluded[Excluded modules]
    Selected --> Plan[Target install plan]

When an install request is normalized, profile IDs, module IDs, component IDs, locale choices, and legacy language input are kept distinct. Manifest selections cannot be mixed with legacy language arguments, which prevents two different selection models from silently producing one ambiguous plan. (scripts/…/request.js lines 87-150)

The manifest resolver then follows this order:

  1. Load the module, profile, and component catalogs.
  2. Add modules from the selected profile, explicit module IDs, and included components.
  3. Remove excluded components and target-specific default exclusions.
  4. Resolve each remaining module and its dependencies.
  5. Mark unsupported target selections as skipped and return the target operation plan.

The resulting plan retains the original selection context as well as the resolved module lists. That distinction lets the system later compare current manifest intent with the state that was installed. (scripts/…/install-manifests.js lines 535-725)

The planning interface makes this model visible without changing a target. It can list profiles, modules, and components, or emit a machine-readable resolved plan for a profile, module set, component selection, and target. (scripts/install-plan.js lines 22-44, 198-268)

References: scripts/…/request.js• L87-150 scripts/…/install-manifests.js• L535-725 scripts/install-plan.js• L22-44 scripts/install-plan.js• L198-268

Schema boundaries

The schemas define the data contract for the catalogs and for persistent state. They make required fields, value types, allowed names, and version markers explicit. They do not by themselves prove that a module reference exists or that a dependency graph can resolve.

Install request schema

The install request schema defines the stable input shape for selecting a target and its capabilities. It accepts one profile, explicit module IDs, component IDs to include or exclude, and an open options object for request-specific choices; it keeps the schema version fixed at 1. (schemas/ecc-install-config.schema.json lines 1-18, 39-71)

The request contract accepts the component families that users can select through the manifest model: baseline, language, framework, capability, agent, skill, and locale IDs. It also permits an explicit target from the supported target set. Reference and dependency checks still occur after schema validation, so a correctly shaped name can still fail if the catalog does not define it. (schemas/ecc-install-config.schema.json lines 18-71; manifests/install-components.json lines 378-486, 594-672)

References: schemas/ecc-install-config.schema.json• L1-71 manifests/install-components.json• L378-486 manifests/install-components.json• L594-672

Context carrier schema

The context carrier schema defines a read-only proposal for carrying selected skills to targets that support a skill layout. It records selection and routing IDs, source and generated files, content digests, and known limits so a proposal can be inspected without changing an installation. (schemas/context-carrier.schema.json lines 1-85)

The schema keeps unsupported targets inactive and file-free. Supported targets must use a known profile and layout, while every file entry must use a safe relative path and a declared digest and size. These rules make the proposal a checked description of possible skill delivery, not a second install-state record. (schemas/context-carrier.schema.json lines 87-105)

References: schemas/context-carrier.schema.json• L1-105

Validation is split across clear boundaries:

BoundaryMain guarantee
Install request schemaVersioned request shape and valid target and component naming patterns
Component, module, and profile schemasCatalog shape, required values, naming patterns, and allowed enums
Context carrier schemaValid read-only skill proposal status, layout, paths, digests, and file forms
Manifest loading and resolutionKnown references, supported targets, dependency order, exclusions, and cycle checks
CI manifest validatorCross-catalog references, unique IDs, source path coverage, profile coverage, and curated skill coverage
Install-state schema and validatorStable state shape, schema version, target identity fields, request and resolution records, and operation metadata

The manifest loader reads the three catalogs together and exposes maps for cross-reference. CI then checks relationships that a JSON schema cannot check, including unique IDs, existing and non-overlapping source paths, required profiles, and coverage of curated skill directories. This is why editing one manifest can affect plan resolution or validation even when its JSON shape remains valid. (scripts/…/install-manifests.js lines 293-334; scripts/…/validate-install-manifests.js lines 71-147, 149-245)

References: schemas/ecc-install-config.schema.json• L1-71 schemas/install-components.schema.json• L1-59 schemas/install-modules.schema.json• L1-128 schemas/install-profiles.schema.json• L1-45 schemas/context-carrier.schema.json• L1-105 scripts/…/validate-install-manifests.js• L71-245 scripts/…/install-manifests.js• L293-334

Persistent installation state

Install state is the durable record of one resolved installation for one target. It lets later commands identify what ECC owns, reconstruct the user request, compare the recorded resolution with current manifests, and inspect the health of managed files.

The state has five useful parts beyond its schema version and time fields:

State areaMeaning
targetThe target identity, target scope, install root, and state-file path
requestThe profile, explicit modules, included or excluded components, legacy mode, hook consent, trust, and MCP consent used by the request
resolutionModules selected for the target and modules skipped during resolution
sourceRepository version, commit, and manifest version used for the install
operationsThe managed source-to-destination actions, their strategy and ownership, scaffold status, and optional content hash

The state schema fixes the format at ecc.install.v1. It requires the target, request, resolution, source, and operations sections and rejects unknown top-level fields. The request can record hook consent, trust, and MCP consent. Operation records allow extra fields so target-specific operation data can remain attached to the common record, while Claude settings updates must identify an approved hook source and target. (schemas/install-state.schema.json lines 1-18, 20-61, 62-128, 130-186, 187-285, 287-313)

State is validated when it is created, read, and written. The validator mirrors the state schema without relying on a separate runtime package, so state consumers can reject malformed or changed records before they use ownership or operation data. (scripts/…/install-state.js lines 4-10, 220-299)

The lifecycle uses the recorded state as a comparison point rather than as a blind truth. It reports missing or changed managed files, missing source files, unsafe operation paths, manifest-version changes, and resolution drift when the current manifests no longer produce the recorded module selection. (scripts/…/install-lifecycle.js lines 1383-1477)

References: schemas/install-state.schema.json• L1-313 scripts/…/install-state.js• L220-299 scripts/…/install-lifecycle.js• L1383-1477

Change checklist

When these files or sections are changed, remember to consider these:

  • When a component ID or family changes, review request validation, profile entries, component selections, and user-facing commands that refer to the old ID.
  • When a module ID changes, update component references, profile references, dependency references, and any recorded state or migration path that must still be readable.
  • When a module target, kind, or dependency changes, review target-specific skips, default exclusions, and the resulting selectedModules and skippedModules state contract.
  • When a module path changes, check that the path exists, remains owned by one module, and still covers every curated skill that should ship.
  • When a request field or allowed component family changes, keep schemas/ecc-install-config.schema.json aligned with the selection paths exposed by the manifests.
  • When a manifest version changes, keep the source version recorded in install state aligned with the value used by lifecycle health checks.
  • When a skill description or skill registry changes, regenerate manifests/…/skill-triggers@1.json so its registry digest, trigger digest, and coverage still match the discovered skills.
  • When the context carrier schema changes, keep supported target, profile, layout, file, digest, and limitation rules aligned with the producer that creates read-only proposals.
  • When the install-state schema changes, update both the schema and the dependency-free validator. Preserve compatibility for existing ecc.install.v1 records or define an explicit migration path, especially for request fields such as hook consent.
  • When operation fields or path rules change, review repair, update, uninstall, and ownership checks because they use recorded operations as their managed-file boundary.

Important failure modes

TriggerConsequenceGuard
A profile, component, or dependency names an unknown modulePlanning stops instead of producing a partial selectionManifest loading and resolution check module IDs before use
A module points to a missing path or two modules claim the same pathCI rejects the manifests before an install can create an incomplete or ambiguous planThe manifest validator checks path existence and normalized path ownership
A curated skill directory is not covered by a moduleThe skill is not part of a declared install capability and CI failsThe validator checks each curated skill with a SKILL.md against module paths
A selected module does not support the requested targetThe module is skipped, or a dependent selection cannot resolveTarget support is checked during dependency resolution
Excluding a module required by another selected moduleThe plan fails rather than silently installing an incomplete capabilityDependency resolution rejects an excluded required module
A dependency graph contains a cyclePlanning cannot determine a safe module orderThe resolver detects a module already being visited
A required profile is missing, or the full profile omits a required non-optional moduleThe manifest set fails CI and broad installs can miss a declared capabilityThe validator checks the required profile set and full-profile coverage
The skill trigger manifest names an unknown skill, uses an old registry digest, or has a changed trigger digestContext profile validation fails and trigger-based skill lookup cannot use the checked-in indexContext profile validation compares trigger IDs and digests with the current skill registry
Install state has the wrong schema version or missing required fieldsState consumers reject it and health status becomes an errorState creation, reads, and writes validate the ecc.install.v1 contract
Current manifests resolve differently from recorded stateHealth checks report resolution drift and may require reviewLifecycle analysis compares current selected and skipped modules with state
A context carrier marks an unsupported target as active or includes files without a valid layoutThe proposal fails validation or cannot be safely consumed as a read-only skill planConditional schema rules bind target support to status, layout, and file presence

Key files

FileWhy to read it
manifests/install-components.jsonThe user-facing capability catalog and its mapping from component IDs to modules
manifests/install-modules.jsonThe installable module catalog, target support, dependencies, and install metadata
manifests/install-profiles.jsonThe named module presets used as common installation starting points
schemas/ecc-install-config.schema.jsonThe versioned request shape for target and capability selection
schemas/context-carrier.schema.jsonThe checked contract for read-only skill carrier proposals and target layouts
schemas/install-components.schema.jsonThe structural contract for component entries and family-based IDs
schemas/install-modules.schema.jsonThe structural contract for module kinds, targets, dependencies, and metadata
schemas/install-profiles.schema.jsonThe structural contract for profile names and module lists
schemas/install-state.schema.jsonThe persistent install-state contract and its stable ecc.install.v1 shape
scripts/…/install-manifests.jsThe boundary that loads catalogs and resolves profiles, components, modules, dependencies, exclusions, and targets
manifests/…/skill-triggers@1.jsonThe checked-in skill phrase index that supports context retrieval without changing install selection
scripts/…/context-pack-registry.jsThe boundary that loads discovered skills and validates the trigger metadata used with them
scripts/…/install-state.jsThe state creation, validation, read, and write boundary
scripts/…/install-lifecycle.jsThe health checks that compare managed files and current manifest resolution with recorded state
scripts/…/validate-install-manifests.jsThe CI checks for cross-manifest links, path ownership, profile coverage, and curated skill coverage
scripts/install-plan.jsThe read-only interface for inspecting available selections and resolved plans