Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions .apm/architecture/owners/marketplace-plugins.json
Original file line number Diff line number Diff line change
Expand Up @@ -182,12 +182,15 @@
},
{
"id": "claude-native-plugin-registration",
"decision": "Intact Claude plugin admission, lockfile-derived native ownership (native_plugin records), deployment to ~/.agents/plugins, and settings-only declaration through the shared native settings writer without any vendor CLI",
"owner": "claude_plugins/admission.py (plan_native_claude_plugin); claude_plugins/registrar.py (reconcile_claude_plugins, verify_claude_native_cache); native_plugins/ (record, layout, settings)",
"decision": "Intact Claude plugin admission, lockfile-derived native ownership (native_plugin records), deployment to .agents/plugins (committed at project scope, ~/.agents/plugins at user scope), and settings-only declaration to Claude and Copilot through the shared native settings writer without any vendor CLI",
"owner": "claude_plugins/admission.py (plan_native_claude_plugin); claude_plugins/registrar.py (reconcile_claude_plugins, verify_claude_native_cache); native_plugins/reconcile.py (reconcile_native_plugins) over native_plugins/ (binding, harnesses, record, layout, settings)",
"selectors": [
"src/apm_cli/claude_plugins/admission.py",
"src/apm_cli/claude_plugins/registrar.py",
"src/apm_cli/native_plugins/binding.py",
"src/apm_cli/native_plugins/harnesses.py",
"src/apm_cli/native_plugins/layout.py",
"src/apm_cli/native_plugins/reconcile.py",
"src/apm_cli/native_plugins/record.py",
"src/apm_cli/native_plugins/settings.py"
],
Expand All @@ -211,12 +214,11 @@
},
{
"id": "copilot-marketplace-ownership",
"decision": "APM-owned Copilot marketplace catalog, settings entries, and ownership ledger",
"decision": "Retirement of the legacy APM-owned Copilot catalog, settings entries and apm-registration.json ledger; Agent Plugins are declared through the shared native reconcile",
"owner": "copilot_plugins/registrar.py (synchronize_copilot_plugins, resync_native_plugins)",
"selectors": [
"src/apm_cli/copilot_plugins/registrar.py",
"src/apm_cli/copilot_plugins/settings.py",
"src/apm_cli/copilot_plugins/catalog.py"
"src/apm_cli/copilot_plugins/settings.py"
],
"guards": ["marketplace-integrations-copilot-ownership"]
},
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- OpenAPM v0.1 adds the native plugin activation profile: which harnesses APM may install plugins into natively, and what APM guarantees when it does (`req-na-001`-`007`). (closes #3919, #3929)
- `apm approve` lists what each package runs and pins MCP servers, hook files and whole native plugins to their content; changed content is parked until re-approved. (#3918)
- Native Claude plugins can ship MCP and LSP servers; Claude loads them, whole-plugin approval covers them, and org MCP policy applies (#3290)
- Projects targeting Claude or Copilot install Claude and Agent Plugins intact to committed `.agents/plugins/`; fresh clones load them without APM. (#4047, closes #3921)

### Changed

Expand Down
2 changes: 1 addition & 1 deletion CONFORMANCE.json
Original file line number Diff line number Diff line change
Expand Up @@ -2018,7 +2018,7 @@
"test_count": 7,
"tests": [
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_invalid_settings_fail_closed_without_overwrite",
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_missing_ledger_re_adopts_only_the_exact_reserved_namespace",
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_missing_lock_re_adopts_exact_state_and_removes_nothing",
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_native_lifecycle_registration_clauses_persist_in_spec",
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_native_registration_is_aggregate_in_place_and_consumer_owned",
"tests/spec_conformance/test_copilot_plugins_reqs.py::test_non_copilot_target_creates_no_native_registration",
Expand Down
75 changes: 32 additions & 43 deletions docs/src/content/docs/consumer/copilot-agent-plugins.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
title: Install Agent Plugins for Copilot
description: Install a portable Agent Plugins 1.0 package and let GitHub Copilot load it live from apm_modules.
description: Install a portable Agent Plugins 1.0 package and let GitHub Copilot load it live from the committed .agents/plugins.
---

APM installs an Agent Plugin whole and GitHub Copilot loads it **live** from
`apm_modules` -- no copy, no `--plugin-dir`. An
the committed `.agents/plugins/<plugin>/` -- no `--plugin-dir`, and a fresh
clone needs no APM. An
[Agent Plugin](../../reference/package-types/#agent-plugin-pluginjson-with-an-agent-plugins-schema)
is a whole unit: one `plugin.json`, its `skills/`, and its root `mcp.json`,
and APM installs it without taking it apart.
Expand Down Expand Up @@ -36,47 +37,38 @@ $ copilot

## What APM writes

APM writes two generated files it fully owns, and merges two namespaced keys
into your Copilot settings, which stays yours:
Agent Plugins take the same native route as
[Claude plugins at project scope](../installing-from-marketplaces/#apm-managed-project-plugins-claude-and-copilot):

| Path | Owner | Purpose |
| --- | --- | --- |
| `apm_modules/.github/plugin/marketplace.json` | APM (generated) | One catalog listing every installed Agent Plugin, each pointing at its real directory |
| `apm_modules/.github/plugin/apm-registration.json` | APM (generated) | Primary ownership ledger for the settings keys APM manages |
| `.github/copilot/settings.local.json` | You (merge-only) | APM adds two namespaced keys: `extraKnownMarketplaces.apm` and `enabledPlugins["<plugin>@apm"]` |
| `.agents/plugins/<plugin>/` | APM (committed) | The approved plugin root, copied from `apm_modules/` |
| `.agents/plugins/.claude-plugin/marketplace.json` | APM (committed) | One catalog listing every deployed plugin |
| `.github/copilot/settings.json` | You (merge-only, committed) | APM adds `extraKnownMarketplaces["apm-p-<hash>"]` and `enabledPlugins["<plugin>@apm-p-<hash>"]` |

```json title=".github/copilot/settings.local.json"
```json title=".github/copilot/settings.json"
{
"extraKnownMarketplaces": {
"apm": { "source": { "source": "directory", "path": "apm_modules" } }
"apm-p-1a2b3c4d": { "source": { "source": "directory", "path": "./.agents/plugins" } }
},
"enabledPlugins": { "my-plugin@apm": true }
"enabledPlugins": { "my-plugin@apm-p-1a2b3c4d": true }
}
```

The marketplace path is repository-relative, so the registration survives
clones, worktrees, and moved checkouts. Global installs (`apm install -g`)
write the same two keys to `$COPILOT_HOME/settings.json` (unset or blank:
`~/.copilot/settings.json`) with an absolute path under `~/.apm/apm_modules`.

APM preserves unrelated JSON keys and values semantically. Its stable
serialization may reformat the settings document.
The install fails closed only when a pre-existing `apm` marketplace entry
points somewhere other than APM's materialization root and the ledger does not
record APM as its owner. An entry that already matches what APM would write is
re-adopted silently, ledger or not. The `<plugin>@apm` enabled keys sit in
APM's namespace: once APM owns the `apm` marketplace it sets the ones it needs
and retires any leftover `@apm` key, so a lost ledger (`rm -rf apm_modules`)
still converges on re-install. Do not create manual `*@apm` activation keys;
APM reconciliation may retire them. Keys using another marketplace suffix are
preserved.

Only plugins that pass target and security admission participate in
registration and name-collision handling. If two admitted dependencies declare
the same plugin name, a direct dependency wins over a transitive dependency.
Two admitted claimants at the same precedence fail with an actionable collision
instead of registering either one. An admitted transitive dependency cannot
silently replace the owner recorded in APM's ledger.
`apm.lock.yaml` records each plugin as `native_plugin`, and that record is
APM's only ownership evidence: APM adds what the lock needs, removes only what
the previous lock produced, writes `true` only when a key is absent, and keeps
your entries and any explicit `false`. A marketplace with APM's name that
points elsewhere fails the install without a write. Global installs
(`apm install -g`) deploy to `~/.agents/plugins/` and write
`$COPILOT_HOME/settings.json` (unset or blank: `~/.copilot/settings.json`) with
an absolute path.

Earlier APM versions registered Agent Plugins from `apm_modules` through
`apm_modules/.github/plugin/apm-registration.json` and an `apm` marketplace in
`.github/copilot/settings.local.json`. The next `apm install`, `apm uninstall`
or `apm prune` removes exactly the entries that ledger recorded, then the
ledger and its catalog.

## What APM does not do

Expand Down Expand Up @@ -104,17 +96,17 @@ See the
[GitHub Copilot CLI releases](https://github.com/github/copilot-cli/releases).
Non-Copilot targets remain outside this native registration path.
APM may still acquire and lock the dependency, but it creates no Copilot
catalog, ledger, settings entry, or loose primitive projection for it.
deployed root, catalog, settings entry, or loose primitive projection for it.

## Lifecycle

| Command | Effect |
| --- | --- |
| `apm install` | Materializes the plugin under `apm_modules/`, then rebuilds the catalog and settings entries |
| `apm install` | Materializes the plugin under `apm_modules/`, deploys it to `.agents/plugins/`, then updates the catalog and settings entries |
| `apm install --force` | Reapplies the current dependency selection while overriding supported collision and trust prompts; it does not select newer remote refs |
| `apm update` | Downloads and validates replacement package content while the current plugin remains available, then publishes it; a failed refresh keeps the prior content |
| `apm deps list` | Reports which Agent Plugins APM registers natively |
| `apm uninstall` / `apm prune` | Removes only APM-owned catalog rows and settings keys, then deletes the generated catalog once it is empty |
| `apm uninstall` / `apm prune` | Removes only the deployed roots and settings keys the lock recorded, then the catalog once it is empty |

Your plugin sources are never deleted by the registration lifecycle -- APM
only retires what it wrote.
Expand All @@ -126,13 +118,10 @@ the project registration path is repository-relative, and repository-scoped
settings are folder-trust gated. Grant folder trust once; APM does not
pre-seed trust on your behalf.

**A settings collision.** APM refuses to overwrite an `apm` marketplace entry
whose directory differs from what it would write when the ledger at
`apm_modules/.github/plugin/apm-registration.json` does not record APM as its
owner. Rename or remove that entry and re-run the install. Deleting the ledger
is not a collision on its own: as long as the `apm` marketplace still matches,
the next install re-adopts it and regenerates the ledger, so
`rm -rf apm_modules && apm install` recovers with no hand-editing.
**A settings collision.** APM refuses to overwrite a marketplace entry with
its `apm-p-<hash>` name that points somewhere other than `./.agents/plugins`,
in any settings file Copilot reads. Rename or remove that entry and re-run the
install.

**The merge fails on invalid JSON or comments.** APM writes stable 2-space JSON,
so JSONC comments are not supported. Invalid JSON fails closed with an explicit
Expand Down
43 changes: 42 additions & 1 deletion docs/src/content/docs/consumer/installing-from-marketplaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,50 @@ then reinstall to switch it to the native route.
A human witness on Claude Code 2.1.322 (macOS arm64) observed `SessionStart`
and `UserPromptSubmit` hooks and a namespaced plugin command reading bundled
resources through `CLAUDE_PLUGIN_ROOT`. `SubagentStart` was not observed.
Project scope comes later (#3921).
:::

### APM-managed project plugins (Claude and Copilot)

In a project that targets `claude` or `copilot`, `apm install` installs an
eligible Claude plugin intact and commits it, so a fresh clone loads it in
Claude Code and GitHub Copilot CLI without APM:

1. `apm_modules/` keeps the fetched source and stays ignored by git.
2. APM copies the approved plugin root to `.agents/plugins/<plugin>/` and
generates `.agents/plugins/.claude-plugin/marketplace.json`. Commit both.
3. It declares the marketplace, with the relative path `./.agents/plugins`,
in `.claude/settings.json` when the dependency targets Claude and in
`.github/copilot/settings.json` when it targets Copilot. The name,
`apm-p-<hash>`, comes from the `name` in `apm.yml`, so every clone uses the
same one and other projects use a different one.

```json title=".github/copilot/settings.json"
{
"extraKnownMarketplaces": {
"apm-p-1a2b3c4d": { "source": { "source": "directory", "path": "./.agents/plugins" } }
},
"enabledPlugins": { "superpowers@apm-p-1a2b3c4d": true }
}
```

Each harness loads the plugin after you trust the folder. Ownership, approval,
the explicit `false`, refusals and uninstall work as for user plugins above.
Differences at project scope:

- The lock fingerprint covers each file's path and bytes, not the executable
bit, because checkouts on Windows or with `core.fileMode=false` drop it.
- Copilot CLI also reads `.claude/settings.json` and
`.claude/settings.local.json`. When a key appears in several files, Copilot
applies them in this order, later winning: `.claude/settings.json`,
`.claude/settings.local.json`, `.github/copilot/settings.json`,
`.github/copilot/settings.local.json` (observed on Copilot CLI 1.0.112). To
turn a plugin off for yourself only, set it to `false` in
`.github/copilot/settings.local.json` or `.claude/settings.local.json`.
- Claude resolves the relative path against the main checkout, also from a git
worktree, and loads a newly declared plugin from the next session.
- A package whose loose hooks an earlier install wrote must be removed with
`apm uninstall <package>` and installed again to switch to this route.

### Direct native installs

Native runtime commands install the plugin and stop there. They do
Expand Down
6 changes: 6 additions & 0 deletions docs/src/content/docs/reference/cli/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,12 @@ not declared, with a warning. Rejected capabilities fail without loose-file
fallback. See
[Claude admission and qualification](../../../consumer/installing-from-marketplaces/#apm-managed-claude-user-plugins).

In a project that targets `claude` or `copilot`, the same plugins are copied to
the committed `.agents/plugins/<plugin>/` and declared with the relative path
`./.agents/plugins` in `.claude/settings.json` and `.github/copilot/settings.json`,
following each dependency's targets. See
[project plugins](../../../consumer/installing-from-marketplaces/#apm-managed-project-plugins-claude-and-copilot).

### Policy and trust

| Flag | Default | Description |
Expand Down
7 changes: 4 additions & 3 deletions docs/src/content/docs/reference/cli/uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,10 @@ What gets removed, in order:
failure. Fix the reported configs, then run `apm install` to reconcile stale
entries.
7. Lockfile entries. If no dependencies remain, `apm.lock.yaml` is deleted.
8. For global uninstalls, after lockfile processing, remove the removed packages'
`~/.agents/plugins/<plugin>/` roots and their `enabledPlugins` keys. A key you
set to `false`, your own entries and a root you edited are kept.
8. After lockfile processing, remove the removed packages' native plugin roots
(`.agents/plugins/<plugin>/`, or `~/.agents/plugins/<plugin>/` with
`--global`) and their `enabledPlugins` keys. A key you set to `false`, your
own entries and a root you edited are kept.

When uninstall rebuilds a surviving package's loose skills, it deploys only the
skills that package selects with `skills:`, as `apm install` does. APM records
Expand Down
Loading