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 / context-profiles-and-delivery

Context profiles and delivery

The context-profile system packages repository guidance for assistant sessions. It turns a versioned profile and the skill registry into a source-bound context plan, a provider-shaped carrier, and an optional isolated native session. It keeps guidance delivery separate from provider permissions, credentials, and task success.

Context-profile system

The system controls how much guidance an assistant can discover before task-level selection. A profile defines eager skills, required skills, routed skills, and an 8,000-token discovery-metadata budget. The skill-trigger manifest adds curated task phrases for some skills and records the registry and trigger digests that must stay current.

The registry projection covers canonical skills. It does not represent every repository guidance surface, such as agents, commands, rules, hooks, MCP schemas, harness wrappers, or learned skills. Trigger phrases are routing hints, not a second skill inventory. See Context selection and retrieval for the task-level selection and loading rules.

The supported profiles express two different starting points:

ProfileStarting pointBudget behavior
lean@1A small discovery kernel with the remaining skills routed.Blocks when the metadata estimate exceeds the limit.
full@1The full canonical skill set available for discovery.Reports the estimate without blocking delivery.

References: scripts/…/context-profiles.js• L9-31 scripts/…/context-profiles.js• L45-86 scripts/…/context-profiles.js• L106-145 manifests/…/skill-triggers@1.json• L1-15

Profile manifests

Profile manifests are the versioned contract for the shape of delivered context. manifests/…/lean@1.json and manifests/…/full@1.json state the profile identity, registry identity, selection policy, required entries, and budget mode. The profile compiler validates the contract before it combines the manifest with the current registry.

Required skills must be eager and cannot be excluded. Explicit includes add their declared dependency closure. The resulting plan records selected, routed, and excluded skill IDs together with the profile, registry, and compiler digests. Its estimate covers discovery metadata only. It does not measure the provider wrapper, native host, or full task context.

References: scripts/…/context-profiles.js• L12-31 scripts/…/context-profiles.js• L45-71 scripts/…/context-profiles.js• L111-145

Profile commands

The profile command is the user-facing boundary for inspecting, storing, resolving, and launching a context choice. Read-only commands show profile definitions, preview a plan, explain one skill entry, or propose a carrier. They do not activate a provider, grant authority, or write an artifact.

Managed commands use a dedicated state directory when a choice must persist. Their lifecycle is:

  1. Preview or set a profile, target, selection mode, and explicit changes.
  2. Inspect the saved generation and its revision.
  3. Resolve task context from that saved base.
  4. Prepare and verify a native generation when an isolated provider session is needed.
  5. Run a bounded task or start an interactive session.
  6. Roll back or recover a managed or native generation after an interrupted change.

set creates an owned generation. resolve and run honor the saved profile, mode, target, includes, and exclusions when a state directory is supplied. The routing index is rebuilt after a set, mode change, or rollback so prompt suggestions reflect the current metadata. Existing provider sessions are not changed.

References: scripts/profile.js• L11-53 scripts/profile.js• L169-191 scripts/…/context-profile-commands.js• L7-56 scripts/…/context-profile-commands.js• L99-164 scripts/…/context-profile-commands.js• L167-176

Carrier generation

A carrier is a target-shaped package of selected skill trees and an allowlisted discovery manifest. It bridges the canonical skill source to a provider layout without copying unrelated repository authority, such as hooks, commands, MCP settings, package scripts, or extensions.

The carrier planner creates a deterministic proposal for a supported target. The managed store materializes that proposal as an ECC-owned generation, checks source bytes while copying, and publishes it only after the generated file set matches the carrier. Unsupported targets remain explicit rather than receiving a guessed layout.

This diagram shows how a profile becomes a source-bound delivery generation and then an optional provider projection.

flowchart LR
    M[Profile manifest] --> C[Context compiler]
    R[Skill registry] --> C
    C --> P[Context plan]
    P --> K[Carrier planner]
    K --> G[Managed generation]
    G --> V[Delivery checks]
    V --> N[Optional native generation]

References: scripts/…/context-profiles.js• L100-145 scripts/…/context-profile-support.js• L8-15 scripts/…/context-profile-support.js• L111-182 scripts/…/context-profile-commands.js• L105-108

Native launch

Native launch is an explicit projection of a managed generation into a private provider home. The supported native targets are Codex and Claude. Preparation verifies an admitted provider version, registers the carrier in the isolated home, checks provider discovery, and binds the result to the managed revision and carrier digest.

Codex uses an isolated home with a local carrier registration. Claude loads the carrier for the session through its plugin directory. Neither path copies credentials or changes the user's provider home. The native root must be a dedicated private directory that does not overlap the managed state root or the normal provider home.

prepare-native creates a disposable verified generation. start requires that generation and a terminal, then launches the pinned provider with inherited terminal input and output. run can launch a bounded task through the same isolated generation. Context is passed as advisory reference data; it does not grant tools, permissions, hooks, network access, installation rights, or approval bypass.

The interactive bootstrap is receipt-bound. It checks the installed CLI identity, source digest, roots, carrier digest, and native readiness before it asks the provider to resolve task context. A changed executable, source set, managed generation, or native generation requires an explicit fresh preparation.

References: scripts/…/context-profile-native.js• L19-43 scripts/…/context-profile-native.js• L241-257 scripts/…/context-profile-native.js• L333-355 scripts/…/context-profile-native.js• L443-485 scripts/…/context-profile-interactive.js• L27-59 scripts/…/context-profile-interactive.js• L69-99 scripts/…/context-profile-launch.js• L18-80

Delivery validation

Delivery validation proves that a proposed context matches its source and target contract. It checks profile and carrier data, source and compiler digests, resource paths, destination collisions, provider versions, discovery results, and installed file inventories. It keeps unsupported, stale, and unobserved states visible instead of treating a proposal as an active session.

The trigger manifest is part of repository consistency. Its skill IDs must exist in the registry. Its registry digest and trigger digest must match the current sources. Its coverage fields describe the share of registry skills with curated hints. They do not claim complete trigger coverage.

Native preparation adds evidence for the isolated home. It records the provider version, executable fingerprint, carrier binding, discovery result, and relevant file state. This proves the prepared generation at that point in time. It does not prove that every task directory has the same context or that the assistant completed the task.

Source reads are bounded and source-bound. The delivery path rejects unsafe relative paths, symbolic-link sources, changing file identities, excessive file sizes, and excessive traversal. Native executable checks apply the same fail-closed approach to the provider binary and bind launch to its fingerprint.

References: scripts/…/context-profile-support.js• L27-55 scripts/…/context-profile-support.js• L61-129 scripts/…/context-profile-support.js• L185-209 scripts/…/context-profile-native-executable.js• L19-79 scripts/…/context-profile-native.js• L177-202 scripts/…/context-profile-native.js• L281-355 manifests/…/skill-triggers@1.json• L1-15

Context selection and retrieval

Profile delivery supplies the stable base from which a task can select and retrieve guidance. Task selection then applies the saved mode, explicit IDs, bounded proposals, exclusions, task revision, and source receipts before it returns context to the assistant.

Read Context selection and retrieval for manual, suggest, and auto behavior; loaded skill bodies and resources; receipt reuse; and the limits on context as advisory data.

References: scripts/…/context-profile-commands.js• L99-139 scripts/…/context-profile-interactive.js• L45-57 scripts/…/context-profile-launch.js• L33-65

Change checklist

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

  • Keep the profile schema, versioned manifests, compiler rules, and budget behavior aligned when changing eager or required selection.
  • Keep carrier target layouts, generated manifest rules, and provider discovery checks aligned when adding or changing a target.
  • Preserve digest bindings across the compiler, managed generation, native receipt, executable fingerprint, and interactive bootstrap.
  • Recheck Codex and Claude version admission and discovery expectations when changing skill names, resource paths, plugin contents, or provider output.
  • Treat an installed CLI, provider executable, or bootstrap source change as a native-generation refresh.
  • Keep trigger IDs, coverage, the registry digest, and the trigger digest aligned when curating or regenerating trigger phrases.
  • Rebuild the routing index after changes that alter the saved profile, selection mode, or exclusions.

Important failure modes

TriggerConsequenceGuard
A required skill is excluded or missing from eager selection.Profile compilation stops and no carrier is produced.Required entries must be eager and cannot be excluded.
A source file changes during carrier materialization.The managed generation is rejected as stale or incomplete.Source identity and content are checked during bounded reads and copy.
A target has no carrier layout.Delivery remains unsupported and contains no guessed files.Target adapters declare support before materialization.
A trigger ID or recorded digest is stale.Repository consistency validation fails.Trigger IDs and both recorded digests are checked against current sources.
The managed revision or carrier changes after native preparation.Native status becomes stale and launch is blocked.Native receipts bind the store revision and carrier digest.
Provider discovery finds an unexpected skill, component, or file.Native preparation fails and the isolated attempt remains for recovery.Discovery output and the complete installed inventory are compared with the carrier.
The provider executable or installed CLI source changes.Interactive or task launch stops before provider execution.Executable fingerprints and bootstrap source identity are checked.
A managed or native transaction is interrupted.The state requires recovery instead of silently switching generations.Journals, locks, immutable receipts, rollback, and explicit recovery preserve state.

Key files

FileWhy to read it
manifests/…/lean@1.json and manifests/…/full@1.jsonThe versioned profile contracts and budget behavior.
scripts/…/context-profiles.jsThe compiler that turns a manifest and registry into a context plan.
scripts/profile.jsThe public read-only and managed profile command surface.
scripts/…/context-profile-commands.jsThe command lifecycle from stored state through resolve, run, and native operations.
scripts/…/context-carriers.jsThe target layouts and source-backed carrier proposal.
scripts/…/context-profile-store.jsThe managed generations, receipts, rollback, and recovery model.
scripts/…/context-profile-native.jsThe isolated Codex and Claude generations, discovery proof, and readiness checks.
scripts/…/context-profile-interactive.jsThe receipt-bound bootstrap and terminal-only interactive start.
scripts/…/context-profile-launch.jsThe bounded task launch and isolated provider boundary.
scripts/…/context-profile-support.jsThe bounded source reader, digests, target validation, and shared safety rules.
scripts/…/context-profile-native-executable.jsProvider executable resolution and fingerprint checks.
manifests/…/skill-triggers@1.jsonThe versioned curated trigger hints and source digests.
schemas/context-profile.schema.json and schemas/context-carrier.schema.jsonThe explicit contracts for profile and carrier data.