[EPIC] Native plugin installation and lifecycle across all APM targets

[danielmeppiel]

Proposals are welcome before implementation. For substantive changes, wait
for a responsible human maintainer to approve the scope and identify a review
contact. An automated recommendation, label alone, or silence is not approval.
See Contributing.

Is your feature request related to a problem? Please describe.

APM can currently install a plugin by separating its hooks, skills and supporting files into target-specific locations. A plugin that works when installed natively can then fail because its scripts no longer see the original plugin-root layout. Copying another missing file fixes one example without fixing the installation contract.

Issue #2824 provides two concrete acceptance cases:

• Codex Companion, a Claude-format plugin, reads ../../.claude-plugin/plugin.json from scripts/lib/app-server.mjs. The partial hook bundle omits that manifest and other root resources. Its name is not evidence of OpenAI Codex runtime compatibility.
• The Superpowers reproduction derives the plugin root from its hook location and reads skills/using-superpowers/SKILL.md. Separately installed skills are not at that path; the reporter observes an exit-zero hook injecting an error instead of the intended content.

PR #2826 addresses the manifest-only slice, not arbitrary sibling resources or native plugin registration. The maintainer has selected a different architectural direction: plugins remain indivisible bundles and are loaded natively by the target harness. Preserve the contributor's reproduction and useful regression evidence; do not treat this direction change as a defect in their contribution.

Describe the solution you'd like

Planning and ownership

Roadmap Horizon: Next. Status: accepted delivery program. Native plugin lifecycle is a fundamental selected priority, not a design-only exercise. Design and qualification are milestones within delivery; necessary child work is sequenced rather than automatically deferred. This is not a commitment that every harness already exposes a native plugin API or that all targets ship simultaneously. Bounded delivery issues record their own scope and acceptance criteria. Review contact: Daniel Meppiel (@danielmeppiel). No implementation assignee or release date is implied.

Keep #2824 open as the first regression sub-issue. Its previous manifest-copying/partial-projection implementation invitation is withdrawn pending the native design. Close #2826 unmerged as superseded by this direction and link it here; do not mark #2824 fixed by that closure.

Native contract

APM owns dependency intent, resolution, integrity/admission policy and the registrations it creates. The harness owns native component interpretation, runtime trust and activation. Use supported native commands, catalog registration or configuration interfaces rather than reverse-engineering private installed-state files.

A valid native route preserves the plugin's identity, complete internal resource layout and native loading semantics. It may register an APM-owned complete directory for live loading, or ask the harness to acquire a complete installed copy. Indivisible does not require one physical copy across all harnesses. A larger resource copy combined with separately registered loose hooks/skills is not native installation.

One installed instance must have one authoritative resolution/update decision. Verify the content selected by the harness, not just the download APM pinned. Semantic versions, cache-directory names and truncated identifiers alone do not prove exact content identity.

Complete target inventory

The baseline is the canonical target catalog at cd224037, not only the README. It contains 17 canonical targets. Current APM target support is not a claim of native whole-plugin support.

Target / harness	Current catalog classification	Required treatment in this epic
copilot - GitHub Copilot; aliases vscode, agents	Included in all	Preserve the existing canonical-Agent-Plugin native registrar; qualify CLI, VS Code and other relevant surfaces independently. Aliases do not establish runtime parity.
claude - Claude Code	Included in all	First regression-driven native pilot; compare registered local-marketplace live loading with harness-acquired complete copies.
cursor - Cursor	Included in all	Assess and qualify the supported native plugin/package registration, installation and lifecycle contract.
kiro - Kiro	Included in all	Assess the native unit and supported programmatic handoff; explicitly record any missing native contract.
opencode - OpenCode	Included in all	Assess native plugin/package semantics and lifecycle without assuming another harness's manifest or hook protocol.
gemini - Gemini CLI	Included in all	Assess its native extension/package mechanism and whether it preserves the required whole-bundle semantics.
grok-build - xAI Grok Build	Included in all	Independently assess native discovery, installation and lifecycle; do not infer support from Grok Cloud.
codex - OpenAI Codex	Included in all	Resolve documented-versus-released CLI behavior, native copied-plugin identity, trust and lifecycle with actual client evidence.
windsurf - Windsurf	Included in all	Assess its native unit and supported handoff; do not equate standalone skill/workflow discovery with whole-plugin installation.
antigravity - Antigravity; alias agy	Explicit-only	Include native-contract qualification while preserving explicit opt-in behavior.
hermes - Hermes	Explicit-only	Include native-contract qualification; preserve its existing skills/MCP behavior where native bundles are unavailable.
grok-cloud - xAI Grok Cloud	Explicit-only and experimental (grok_cloud)	Assess separately from Grok Build; retain its feature gate.
openclaw - OpenClaw	Experimental (openclaw)	Assess the native contract; do not promote the target or enable it by default through this epic.
copilot-cowork - Microsoft 365 Copilot Cowork	Experimental (copilot_cowork)	Assess separately from GitHub Copilot and retain its feature gate.
copilot-app - GitHub Copilot desktop app	Experimental (copilot_app)	Independently qualify desktop registration, trust and lifecycle; retain its feature gate.
agent-skills - cross-client skills target	Explicit-only; not a separate harness	Preserve standalone skill installation. Explicitly classify the native-plugin applicability boundary rather than inventing a runtime.
intellij - IntelliJ	MCP-only, using the Copilot primitive profile	Preserve MCP integration. Do not infer plugin support from the shared profile; record native applicability separately.

For every row, record primary-source evidence, native format/unit, client version/platform, project/user/global/remote scope, registration versus acquisition behavior, trust requirements, installed/loaded readback, source pinning/update ownership, and uninstall/rollback semantics. Track the catalog so future targets cannot silently be omitted.

During design, distinguish candidate/unqualified from qualified native support, evidence-backed native unavailability, and not applicable to this primitive/MCP-only target. Unknown is not unsupported. A target without a qualified native route must fail or explain the limitation explicitly for native-plugin requests; it must not silently decompose the bundle. Existing standalone primitives remain a separate supported use case.

Workstreams

• W1 - Contract and full inventory: agree native-bundle boundaries, evidence/status vocabulary, per-target capability matrix, lifecycle ownership and migration rules. All 17 rows are required; compatibility cannot be inferred from a similar product name or shared directory profile.

• W2 - First native delivery: resolve the Claude-format [BUG] User-scope hook deployment leaves out the plugin manifest: scripts reading ../../.claude-plugin/plugin.json crash (Codex Companion plugin) #2824 regressions through a native route, retain/requalify the existing Copilot investment from feat(install): register Agent Plugins natively with GitHub Copilot #2705, and establish reusable end-to-end fixtures. No loose duplicate registrations.

• W3 - Remaining target qualification and staged delivery: assess and deliver supported native routes across the remaining catalog, including explicit/experimental targets. Give Codex its own qualification decision; schedule other harnesses from evidence rather than treating them as an afterthought. Each delivery has its own bounded child issue and human scope decision.

• W4 - Lifecycle, reproducibility and migration: reconcile desired versus actually installed/loaded content, preserve disables and native consent, handle updates/failures/uninstall/prune, remove only APM-owned legacy registrations, and preserve foreign/user-managed state.

• W5 - User contract and documentation: one install intent with truthful outcomes and one actionable next step; update supported-target documentation and shipped usage resources. Breaking transitions require release/migration notes. README changes require separate maintainer approval.

• W6 - Supporting producer compatibility: deliver [BUG] apm pack --format plugin: hook commands keep .apm/ source paths, hook scripts are dropped, and hooks.json is not discoverable #3074's complete and correctly referenced packed hooks and [FEATURE] apm pack: generate .codex-plugin/plugin.json alongside the Claude and Copilot manifests #3077's end-to-end Codex-compatible plugin and matching marketplace generation. Use documented native/shared/compatibility formats verified on declared client versions and surfaces. No manual JSON repair, competing marketplace subsystem, or automatic native trust. This explicitly adds the approved producer work; independently shippable repairs need not wait for the entire installer.

Done when

• Every current catalog target has a version/scope-specific qualified route or an explicit, evidence-backed and maintainer-agreed native-unavailability/not-applicable decision. Unresolved candidates keep their work open; no blanket universal-support claim.
• Every route advertised as native is exercised with a real harness and an intact plugin, including supported hook/skill/MCP/resource behavior. Settings written or an install command returning success is not treated as proof of runtime loading.
• Both [BUG] User-scope hook deployment leaves out the plugin manifest: scripts reading ../../.claude-plugin/plugin.json crash (Codex Companion plugin) #2824 resource relationships are preserved in the released native path, with regression coverage proving actual installed behavior and absence of duplicate loose integrations.
• Supported install/restore/update/uninstall/prune and failure recovery preserve ownership, user data, explicit disables, scope isolation and required native trust. Durable plugin data is not confused with immutable package content.
• Reproducibility claims are backed by full resolved source/content identity for the bytes actually selected for loading, where observable; limitations are reported honestly otherwise.
• Native-plugin incompatibility does not silently fall back to component projection. Existing standalone skill/instruction/MCP workflows remain supported and clearly distinguished.
• Migration and compatibility documentation match the qualified matrix, and each implementation child has its own acceptance evidence and review contact.

Boundaries

Do not automatically accept command-source execution, OAuth, workspace trust or organization-policy changes. An APM allowlist is not a substitute for native authorization. Do not implement a universal hook translator, turn draft specification proposals into published requirements, promote experimental targets, invent an enterprise assignment authority, or use this epic to approve unrelated issue scopes. Preserve client-specific semantics without advertising unsupported portability.

Describe alternatives you've considered

Alternative	Decision and tradeoff
Add the manifest, then copy additional missing resources	Rejected as the architectural resolution. It remains a partial reconstruction and does not establish native registration/loading.
Copy the entire tree but register hooks and skills separately	Rejected as native compliance; intact files alone do not preserve native lifecycle and component ownership.
Register an APM-resolved whole directory	Preferred where the harness exposes a supported durable route; qualify path, trust, update and scope behavior rather than assuming arbitrary folder discovery.
Delegate acquisition of a whole copy to the harness	Valid native route. Accept additional storage while controlling resolution/update drift and observing the installed realization.
Require a clear native user action where automation is unavailable	Honest bounded fallback for genuine installation/trust gates; not a reason to claim activation or bypass consent.
Promise one universal format or installer immediately	Rejected. Portable package content does not standardize installation, activation, trust or lifecycle across every client.

Additional context

Primary regression: #2824. Superseded implementation approach: PR #2826. Existing native foundation: #2705.

Accepted linked delivery: #1120 (native plugin collision coexistence), #3074 (packed hook correctness), and #3077 (Codex package/catalog compatibility), alongside existing regression child #2824. #739 is related for native-plugin identity/provenance only; its standalone-skill remainder stays separately scoped and must not be treated as resolved by this epic.

Other related discussions are not automatically re-scoped or reparented: #2802 (non-Copilot Agent Plugin skills), #2992 (Codex-format MCP loss), and deferred #2105 (broad import/export loss-accounting redesign).

Public research starting points:

• Claude plugin loading and native CLI lifecycle.
• Codex plugin authoring and documented CLI commands. Documented behavior still requires version-qualified execution evidence.
• agentplugins/agent-plugins-spec#66, agentplugins/agent-plugins-spec#67, and jonathanhefner/agent-plugins-spec#9 are proposal inputs, not assumed ratified installation or hook contracts. Adopt content changes by published version and retain fail-closed handling of lossy exports.

Thanks to lkshrk (@lkshrk) for the original reproduction and PR #2826, and Gergely (@festo) for the additional sibling-skill reproduction. Design or testing contributions are welcome; this epic does not assign either contributor the redesign or commit maintainers to review capacity.

[sergio-sisternes-epam]

Thanks for writing this epic with clear ownership boundaries and a concrete regression trail (#2824).

Advisory recommendation: needs-design. This is not scope approval and does not invite implementation of the epic as a whole.

Direction looks sound: plugins stay indivisible bundles loaded natively by each harness; APM owns dependency intent, resolution, integrity/admission, and registrations; harnesses own native interpretation and activation. The issue already carries status/needs-design.

Before any bounded delivery issue is accepted, please settle at least W1 (contract and full inventory) named in the epic:

• native-bundle boundaries (what must stay co-located vs what may be registered separately)
• evidence/status vocabulary for "natively installed"
• per-target capability matrix (which harnesses expose a supported native plugin API today)
• identity/update authority (one authoritative resolution decision; verify harness-selected content, not only the APM pin)

Keep #2824 open as the first regression sub-issue. Treat #2826 as superseded by this direction (do not treat its closure as fixing #2824). Child delivery issues should each record their own bounded scope, acceptance criteria, and review contact per CONTRIBUTING.md.

Existing labels (theme/portability, area/multi-target, area/marketplace, type/feature, status/needs-design) look appropriate; this advice does not change human decision labels.

This comment is advisory only. A responsible human maintainer must approve each bounded delivery scope before implementation.

---

Generated by autopilot-issue-triage-worker. This comment is AI-generated and may contain errors.

[danielmeppiel]

Decision: approve
Area: project
Scope: Accept native plugin installation and lifecycle as a fundamental delivery program, not a design-only exercise: preserve intact native bundles and supported loading; qualify target contracts; deliver the #2824 and #1120 regressions; include the explicitly approved producer-side #3074 and #3077 scopes.
Done when: The current target catalog has truthful version/scope-specific qualification or explicitly recorded open limitations; every advertised native route proves actual selected/loaded content and ownership-aware lifecycle; the #2824 resource-layout and #1120 coexistence cases pass; accepted producer work produces usable native packages/catalogs; standalone primitives, native consent, user-managed state, documentation and migration boundaries remain preserved.
Out of scope: A promise that all targets expose native plugin APIs, simultaneous delivery or automatic acceptance of every proposed child, synthetic skill renaming, loose-file fallback advertised as native loading, universal primitive translation, trust/OAuth bypass, experimental-target promotion, unrelated scope, or a release/merge commitment.
Review contact: Daniel Meppiel (@danielmeppiel)

Native-first and standards-led is the selected product direction. Design and qualification are milestones within accepted delivery. Sequence necessary child work instead of marking it deferred merely because it comes later. Existing Horizon Next remains unchanged.

Recorded by Copilot on behalf of Daniel Meppiel (@danielmeppiel) following the direct product decisions confirmed on 2026-09-30 and explicit authorization to update the issues on 2026-10-01. Daniel separately confirmed that he is the review contact for accepted scopes. This records a human decision, not an autonomous triage recommendation. It does not promise a release, assign implementation, approve a merge, or bypass review.