Customization delivery, discovery and activation

Status: intended architecture and acceptance contract, reconciled on 2026-10-19 and extended with shared-catalog evaluation requirements on 2026-10-20. The 2026-10-24 native-first rules decision and implementation-order amendment are reconciled with retained slice-1 evidence on 2026-10-25 for user adoption review under AD-0040. This contract does not describe newly implemented adapters or qualify a client. The roadmap owns release order; AD-0040 resolves conflicts with earlier experimental instruction plans. A proposal dated 2026-10-23 suggests managed per-client packages for skills and subagents, and places subagents in the MVP; its amendments are listed in AD-0040’s proposed amendments and are not adopted here.

Architecture and authority

Delivery places files or registers a package. Discovery makes content available to a runtime. Activation loads instructions, invokes a skill or agent, starts a server, registers a tool or executes a hook. These are separate outcomes. Ownership authorizes upskill changes; it does not authorize an incidental reader.

Always-on rules use native loading where available and a qualified trusted hook where no native route exists. Codex and OpenCode delivery must be independent of team AGENTS.md; explicit OpenCode paths are a candidate, not a mandatory plugin route. See the selected routes and retained limits. Install, update and removal must leave team instruction bytes and modes unchanged. File placement or packaging alone is insufficient: the selected route must deliver guidance at the required lifecycle points with scope, precedence, exclusion and activation evidence. CD-04 records the bounded Codex history-duplication allowance; it does not waive planner deduplication. A skill inside a package is not automatically an always-on rule. The exact event/API and package storage remain adapter qualification decisions. Missing capabilities block that route; they never authorize an AGENTS.md rewrite fallback.

The merged Codex contribution compiler and with_prepared_codex are experimental library mechanisms. Their explicit reader reports and guarded editing tests remain useful foundation evidence. They are not the approved production rule architecture, and identical Markdown for potential readers does not establish intentional sharing. No existing experimental installation is silently adopted or converted to a plugin installation. Recorded removal and recovery retain their root/ownership safety contracts.

Claude and Copilot rules use native rule loading where qualification establishes the requested behavior. Skills/resources use qualified native discovery where possible, even when packaged in a plugin. Agents retain native client formats; new owned-agent management is not added to M1. Bundles compose installations and references; native plugins remain separate packages. Existing plugin/MCP functionality must remain compatible without advancing general hooks, tools, permissions or expanded MCP management into this implementation.

Client representation baseline

AD-0041 selects separate generated representations per intended client, with explicitly qualified sharing as an exception. One authored source supplies copied outputs; each logical item/client has one selected representation and effective native exposure. Resources belong to that selection. A generated authored default is not an installed shared catalog, and a default need not exist.

Retain the one-copy unscoped Claude/Copilot rule exception and native-first routes. Other sharing requires compatible declared readers, preserved capabilities and qualified exclusion, duplicate and lifecycle controls. A client-named directory or equal bytes cannot establish isolation.

Selection and lifecycle reuse source capture, provenance, owner/reference contracts, preflight, locking, backups and recovery. Preserve manual content, local edits, surviving references and native state. Removing a selected client replacement makes it unavailable; switching to a default requires an explicit, qualified selection. This future lifecycle policy does not change schema-1 behavior or implement active source overrides.

This adoption does not settle exact paths, package granularity/defaults, new owned-agent MVP scope, OpenCode skill sources, Codex distribution/trust or any other pending scope amendment. The remaining step-7 decisions, preservation contracts, Q10/Q11 and CD-01 through CD-11 gates remain required. Skills/resources stay first, then rules and automatic maintenance; the four-client release scope is unchanged.

Shared content root evaluation

Evaluate .agents/{rules,skills,agents} with client-specific adapters under #349. This is a candidate content layout, not an adopted production default. Compare intentional .claude sharing and selective Copilot/OpenCode Claude-compatibility exclusions as alternative profiles before selecting a root. A skill-directory exclusion does not establish exclusion of rules, agents, commands or explicit imports. The repository research note docs/technotes/shared-content-root-evaluation.md records current source evidence and route candidates. CD-11 below defines the coexistence gate.

Treat .agents/skills as intentionally shared discovery space for a declared shared-catalog installation. Prefer one shared native entrypoint per logical skill and client; a client lacking qualified direct discovery needs one adapter route, not an additional private-looking compatibility copy visible to other clients. Client-specific variants stay outside all shared catalogs. A variant and shared base may not both remain exposed to the same client. Native source namespaces, aliases and package exports do not redefine logical identity to hide duplicates.

.agents/rules and .agents/agents are source-catalog candidates, not universal native formats or proven inert storage. Each adapter retains qualified native scoping and restrictions. Codex/OpenCode rules still require independent delivery beside unchanged team AGENTS.md; the native-first amendment permits explicit OpenCode instruction paths after Q5 PASS. Shared skills must be directly consumption-ready; raw client directives or silently weakened permission semantics cannot be placed there. An audience exclusion chooses another qualified representation or fails preflight rather than silently publishing to shared discovery.

Shared authoring does not require shared native discovery. A common procedure can remain in the canonical body with generation-time client directives for small orchestration differences, or in copied resources explicitly read by client-specific wrappers for larger differences. Whole-body overrides replace the canonical body and do not compose with it. Their specified semantics are not implemented by the historical installer or captured compiler; see format §2.3 and AD-0025. Resource copies do not create additional skill entrypoints. Qualify the native read, resource path and permission behavior separately; references do not register agents or grant tools/MCP access. An embedded composition/include feature and override execution are separate work, outside this Gate 6 change.

This intent does not adopt existing schema-1 outputs or manual content, add owners from compatibility readers, or authorize moving installed files. Select one effective native route per logical item/client before effects and preserve manual/third-party entries and surviving direct/bundle references. Require per-client retained PASS before implementing a candidate skill adapter and integrated qualification before adopting its route. The user’s skills-before-rules implementation order supersedes the former all-four-feasibility-first and rules-before-new-owned-skills implementation dependency only. Gate 6 still requires selected M1 rules and preservation of existing kinds; the new skill layout and combined four-client MVP release remain blocked until qualified (AD-0040 amendment, CD-11). An unadopted layout has no production effects. All applicable platform/scope and existing regression obligations still apply to schema-2 activation. Generated files and earlier independent-rule probes do not satisfy shared-layout qualification.

Reader and activation policy

Every adapter/profile must declare the client/runtime/surface, exact version, OS, project or user scope, effective roots and configuration. Its record includes all entrypoints, resources, package payloads, native registrations, imports, recursive discovery, compatibility directories, configured globs, ancestor and nested roots, shared paths and relevant external-home overrides. Inventory all four clients, plus known supported IDE/compatibility surfaces. Unknown behavior is a blocker for an isolation claim, not an empty reader set.

For each possible reader record intended, unintended or unresolved, with its discovery condition. Declared shared-catalog consumption under the policy above is intentional; other cross-client consumption defaults to unintended unless explicitly selected and accepted for that installation/profile. Audience/body compatibility, equal bytes, a directory name or a warning alone never supplies that consent. A requested audience exclusion must prevent activation, not just omit one generated copy. Incidental readers gain neither owners nor references.

A shared artifact is permissible only for explicitly intended consumers with qualified equivalent behavior, compatible resources and recorded owner contracts. Otherwise select an independently qualified route or fail preflight. Do not disable existing user/team discovery or rewrite their settings to make a negative control pass. Existing configurations with imports/globs that prevent isolation are explicitly unsupported until an approved representation works.

Native catalogs and prompts must distinguish availability from activation. Each unintended-reader negative needs a successful positive control in that same client and an invocation relevant to the customization. For skills and agents, inspect native catalog/registration and explicit invocation as well as behavior; no marker in an unrelated prompt does not prove absence from discovery. Use registration/event counters or equivalent native receipts to distinguish repeated activation: a single final marker cannot prove exactly-once loading. Test same-name and alias collisions, project/user overlap, compatibility copies and direct-plus-plugin installation. One logical installation activates at most once per intended event/invocation. Intentional repeated user invocations are separate events. CD-04 separately records the selected Codex recorded-history limitation without claiming provider-effective duplication or waiving planner deduplication. Client-specific precedence or deduplication is evidence to verify, not a portable assumption (resume-only, AD-0040).

Preservation contracts

Every matrix row below inherits these installation, update and removal rules:

• Files (F): capture exact entrypoint/resource bytes and modes, enumerate owned resources individually, reject unowned collisions even when bytes match, and preserve manual files, unrelated owners and references. Update/remove rejects edited owned artifacts; no recursive deletion of a mixed directory. Rule resources must not become instructions through a broad Markdown glob.
• Rules (R): F plus no team AGENTS.md, override-file or imported-manual-text changes for independent plugin rules. Native Claude/Copilot rule files remain separately owned; existing bridge/settings entries need their own ownership evidence. Scope mappings must preserve matching and nonmatching behavior.
• Native registrations (N): F for package/config files plus observe existing registration, scope, enablement, trust and inverse actions. Add only owned entries; update/remove preserve other keys, comments, order where meaningful, credentials and manual registrations. Unknown/pre-existing registrations are conflicts or externally satisfied objects, not automatically owned. File success is not native effect success. Recovery observes native outcomes before retrying, and blocks if it cannot safely determine the result.
• Composition (B): preserve dependency identity, source/ref, aliases and direct/bundle reference edges. Removing one bundle releases only its edges; surviving direct/other-bundle references retain content, resources and native registrations. No new retention is inferred from incidental readers. Existing explicit integration-removal policy remains; narrowed selection cannot silently uninstall a plugin or MCP server.

Reuse complete selected-set preflight, captured source/destination evidence, qualified roots and writer locking, exact schema-1 backup, owner contracts and journaled recovery. Extend native-effect planning where needed; the file journal alone is not proof of native registration recovery. Keep schema-1 production routing until every applicable activation requirement passes. Never expose a schema-2 writer alongside legacy recursive removal or save only the legacy projection over an outer owned state.

Per-client delivery matrix

The paths here distinguish current output from intended routes. They are not new path guarantees. Project/user roots, package locations and compatibility settings must be pinned for each released version before qualification.

Status vocabulary: I means code exists; X means experimental library; O means a bounded native observation exists; Q means the exact recorded native case passed; P means intended work remains. I and generated-file tests do not imply O/Q. Historical Q applies only to its recorded method/version, never automatically to this corrected delivery route.

Rules

The following are intended routes, not a change to schema-1 production output. Each evidence link qualifies only its recorded case. The user selected these always-on routes on 2026-10-24; CD-01 through CD-11 still gate implementation (AD-0040).

One physical delivery per rule/project and per-item intended-reader ownership are required planner behavior, not a new implemented lockfile field. Existing schema-1 output does not yet implement that ownership record. Claude-only rules visible to Copilot require a compatible intended-reader declaration or are unsupported for that project; warnings do not supply consent. Claude IDE, Copilot cloud agent, code review and VS Code are unresolved readers, not intended consumers inferred from CLI selection (Q1, AD-0040).

Scoped rules are a secondary native capability policy: Claude paths:, and Copilot applyTo only where Claude is not selected. Matching/nonmatching native controls remain required; Q1 did not access a matching file. Shared scoped Claude+Copilot rules and other unenforced scopes are reported unsupported, never widened to always-on. Q1b matching-file access and Q3b Copilot startup-hook injection are deferred, unscheduled. Q4 is unscoped-only and does not prove fresh resume attachment or provider-effective uniqueness (Q1, Q3, Q4, handoff).

Skills and supporting resources

Every resource inherits its parent installation’s consumer classification. Test relative links after relocation/aliasing, executable modes, ignored files, resource-name collisions and resources reachable through another client’s instruction glob. Native packaging must not cause direct and packaged copies of the same skill/resources to activate twice. A valid entrypoint cannot qualify missing or differently interpreted supporting files.

Agents

Require real delegated execution with model, tool, permission, instruction and MCP inheritance controls. A registered prompt or parent response is insufficient. Claude plugin agents ignore hooks, mcpServers and permissionMode; do not replace these with broader plugin/session settings. Reject unsupported mappings. Codex instructions do not establish a child sandbox override. OpenCode v2’s ordered permission/agent-merging contract needs a qualified adapter; existing legacy generated output is not proof. Copilot project .claude/agents is a known compatibility reader with no established selective directory exclusion. Keep client variants outside shared catalogs and preserve manual registrations. These are capability/regression requirements, not new agent management in M1.

Bundles

Plugins

Plugin update transport, upskill CLI binary updates and installed-content reconciliation remain three separate lifecycles. Namespace or manifest names alone cannot prove activation isolation. A package that exports MCP/tools has the corresponding additional activation and permission checks.

MCP servers

An intentionally shared remote endpoint does not imply shared credentials, consent, ownership or connection lifecycle. A denied/offline server must not be reported as connected; a config parser passing is not runtime evidence.

Planned hooks, tools and permissions

These rows are requirements inventory, not new implementation work. Internal rule-delivery/maintenance hooks needed by the MVP are qualified as plugin internals; general hook management, tool mapping and permission management retain the roadmap’s later scope. Existing restrictions remain regression obligations.

Slice-1 evidence and adoption (2026-10-25)

This is the separate step-7 reconciliation for task #412. The user owns adoption at its PR review. Native-first always-on rules and skills-before-rules implementation order were already decided on 2026-10-24; the additional direction choices below are not implied by a PASS. Merged packets and indexed technotes complete a control administratively, including FAIL results, without completing Gate 6 or adopting a production adapter (handoff, AD-0040).

Retained control dispositions

All rows below are macOS arm64 observations. Pins are per row, not an implied current four-client support range. Retained qualified: false stays false; Linux, IDE/hosted, arbitrary user-root and integrated ownership/recovery evidence are not supplied by these packets (CD-09 and CD-10).

The Codex selected support policy is supported with declared limitation. The resume-only result attributes the extra recorded copy before compaction; it does not establish whether the provider receives both copies or when that duplicate ceases to affect input. The older combined run’s second compaction records one body per rule in that separate window. Do not merge those observations into a new provider-lifetime claim, rewrite the historical FAIL, remove native history or implement a transcript-dedup workaround (Q9, resume-only).

Update visibility and preservation review

These observations bound the implementation contract; they do not grant permission to leave unrelated configuration changed. Exact restoration of measured files and declared native effects are separate from whole-profile equality. Native cache directories are never directly edited or reclaimed by upskill (Q6, Q8, CD-07).

Decision required: the user approves each client’s owned-key/byte preservation allowances before implementation. Recovery must use the journal plus observed native registration state; no successful file operation proves deactivation (CD-07, handoff).

Amendment inventory

This inventory reconciles every record named by the proposal. Shipped output is kept distinct from intended route changes; no path table below is a declaration that code has changed (proposal inventory).

Decisions and entry controls still required

AD-0041 settles the organizing baseline and removal selection policy only. The user separately accepts or rejects each remaining direction change below; until then, its existing scope remains in force (AD-0040 proposed amendments, roadmap):

• Decision required: make self-contained per-client skill/subagent packages the default instead of the shared-root-first experiment. Q6/Q8 establish bounded feasibility, not a default selection or integrated ownership design.
• Decision required: add new owned-subagent management to the MVP. Q2/Q7 do not adopt release scope.
• Move authorable bundles out of the MVP, preserving existing bundle composition.
• Decision required: select explicit OpenCode package skill sources instead of the native-directory candidate. Q5 has not run that control, so this is a design decision only.

Decision required: select the Codex hook-bearing package distribution channel. The local marketplace fixtures establish no public-directory distribution or automatic trust. Ordinary native hook review is mandatory (design ledger, Q9).

The Codex index-only trust control remains unscheduled: start with a trusted hook/index positive, change only the static index while retaining exact hook bytes, compare native trust state, complete any ordinary user re-review, then verify activation. Capture version, exact changed bytes and native trust/outcome receipts. Failed positive blocks the result; no trust bypass or credential copy. Its result determines update UX, not a presumed exemption from hook review (handoff, Q9).

Q10 #409 must pass same-package user/project overlap with one catalog entry and one observable activation; Q11 #410 must pass calibrated unintended-reader controls for each applicable package profile. Direct-plus-package coexistence remains CD-04 work even without another numbered control. Preflight must inventory .claude/rules, .github/instructions, compatibility roots and imports/globs; onboarding, preservation and update visibility need per-client controls before owned-skill implementation (handoff, CD-03 through CD-08).

Q1b and Q3b remain deferred and unscheduled. Step 8 stays blocked while Q5 lacks explicit-path PASS: no bridge/glob removal, automatic deletion or production route activation follows from this documentation PR. Generic package-hook loading on all four clients remains rejected context; Copilot hook injection is untested. No native-versus-hook performance comparison has run. Criterion 7 still requires identical bytes/tasks and cached/uncached token counts, one client at a time (user decision, Q5 retry).

Acceptance and evidence gates

Qualification starts with a complete matrix and upstream contract refresh for pinned releases. The existing canonical-file discovery harness qualifies only its exact fixtures; it does not test installed independent rule delivery, all customization kinds, unintended-reader isolation or duplicate activation. Existing observations retain their provenance but cannot pass CD-02 through CD-09 or CD-11 by implication. Production activation remains blocked until applicable G6 and CD examples have evidence and exact-head review/hosted checks pass.

Documentation sources and limits

The following official documentation was refreshed on 2026-10-19 to identify reader risks, not to declare installed-version conformance:

• OpenCode v2 skills lists native and Claude/shared compatibility sources. V2 instructions describes nested AGENTS.md discovery and configured instruction loading.
• Copilot skill sources and CLI instructions/imports expose compatibility and explicit-reference paths across client conventions.
• Claude skills and plugin manifest describe standalone/package discovery and exported customization types.
• OpenAI skill documentation and plugin documentation distinguish skill payloads from package installation. Exact Codex CLI discovery and rule injection capabilities still require the pinned CLI contract and native probe; generic plugin documentation is not proof of a supported rule event.

Compatibility paths not established by these sources remain explicit questions for the adapter inventory, never assertions that other clients cannot read them.

Edit the canonical source.