Repository navigation
[0.38] feat(native): project-scope plugins for Claude and Copilot (#3921) - #4010
Draft
Daniel Meppiel (danielmeppiel) wants to merge 4 commits into
Draft
Daniel Meppiel (danielmeppiel) wants to merge 4 commits into
Daniel Meppiel (danielmeppiel) wants to merge 4 commits into
Conversation
6 of 11 tasks
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-miniature-robot
branch
2 times, most recently
from
November 20, 2026 01:24
8f09d01 to
7f3a508
Compare
8 of 13 tasks
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-miniature-robot
branch
2 times, most recently
from
November 20, 2026 02:18
802efae to
45e0b51
Compare
This was referenced Nov 20, 2026
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-miniature-robot
branch
4 times, most recently
from
November 20, 2026 05:00
48dc338 to
a8706e0
Compare
) Deploy approved plugin roots to committed .agents/plugins/<plugin>/, generate the catalog under a per-repo marketplace name, and declare it with a relative path in .claude/settings.json and .github/copilot/settings.json through the shared settings writer, following each plugin's targets. Ownership comes from the previous and next apm.lock.yaml; every harness file is previewed before any root deploys and restored on failure. The committed root digest covers paths and bytes; the exec bit is checked per machine against the apm_modules source at deploy. Agent Plugins move onto the same owner at both scopes; registrations kept in apm_modules/.github/plugin/apm-registration.json are migrated away. Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…le priority (#3921) Cover committed relative declarations, target-following harness files, lock-derived removal that keeps user entries and explicit false, the multi-file rollback unit, the exec-bit-free committed digest, the per-repo marketplace name and the apm-registration.json migration. Move the Agent Plugin lifecycle tests onto the deployed .agents/plugins copy, and pin Copilot's project settings priority against the real CLI when it is on PATH. Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…q-na-002 Amendment 0.1.68 (provisional; renumbered at merge). At project scope the committed root digest omits the executable-bit byte (it equals the approval digest construction), and the consumer compares the bit per machine between the materialized source and the deployed root before writing activation entries. Criterion A5 accepts, at project scope, an observed file-priority order the consumer discloses and pins with a conformance test; Part C records GitHub Copilot CLI as native-eligible at project scope under that test, and the Copilot req-tg-013 route as moved to this profile. req-na-005 is unchanged; no statement count changes. Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Document committed .agents/plugins deployment at project scope, the per-repo marketplace name, the two harness settings files and Copilot's file priority, lock-only ownership, the portable committed digest, the move off the apm-registration.json route, and what to commit. Rebuilt on the #3996 layout; apm-usage updated to match. Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-miniature-robot
branch
from
November 20, 2026 05:23
a8706e0 to
caa0ede
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
TL;DR. At project scope,
apm installnow deploys each approved plugin intact to the committed.agents/plugins/<plugin>/, generates the catalog under a marketplace name unique to the repo, and declares it with a relative path in.claude/settings.jsonand.github/copilot/settings.json, following each plugin's targets. A fresh clone loads the plugins in Claude Code and GitHub Copilot after the folder-trust prompt, with no APM. The Copilot Agent Plugin route moves onto the same owner, andapm-registration.jsonregistrations are migrated away.Stacked on #3290 (includes the 0.37 stack); retarget to main after the 0.37 tag.
Problem (WHY)
apm-registration.jsonreceipt inapm_modulesand wrote only the uncommitted.github/copilot/settings.local.json, so a fresh clone got nothing without APM.Approach (WHAT)
apm_modules; agents load from.agents. APM resolves, locks and approves whole plugins, deploys the approved root to.agents/plugins(committed at project scope) and declares it only through each harness's documented settings keys. No vendor CLI/RPC, no receipt; ownership =apm.lock.yaml.claude_plugins/registrar.pyfalse.native_plugins/settings.py,native_plugins/scopes.pyapm-p-<8 hex>from theoriginremote (host/owner/repo), else theapm.ymlname; once recorded in the lock or committed catalog, that name is reused (forks keep it).native_plugins/scopes.pyapm_modulessource at deploy), never recorded.claude_plugins/admission.py,registrar.py"<plugin>@<market>": falseinto.github/copilot/settings.json(read later, so it wins). APM owns that Copilot key for every plugin it declares to Claude, so it flips or retires it as targets change; every otherfalseis kept. A test pins the order against the real CLI.native_plugins/settings.py,registrar.py(_suppression),tests/integration/test_copilot_project_settings_precedence.pyImplementation (HOW)
claude_plugins/registrar.pyreconcile_claude_plugins→reconcile_native_plugins: both scopes, both harnesses. Previews every harness file before any root deploys; snapshots and restores all of them on failure (one rollback unit). A plugin admitted this run goes to the harnesses its targets select; a harness the run did not evaluate (--targetnarrowing, uninstall, prune) keeps its declarations.claude_plugins/admission.pyharnesses={claude}at user scope,{claude, copilot}∩ targets at project scope. Project scope records the portable digest.native_plugins/scopes.py(new)./.agents/plugins, per-repo/per-home names,COPILOT_PROJECT_SETTINGS_PRECEDENCE.native_plugins/uninstall.py(new)commands/uninstall/cli.pycalls it from one small hunk.copilot_plugins/*,install/native_plugin_admission.py{copilot}, both scopes). Theapm_modulescatalog/ledger/apmmarketplace code is removed.plan_legacy_copilot_retirementplans the migration without writing; the owner applies it inside its transaction (legacy settings snapshotted, written through the shared writer, restored on rollback) and deletes the ledger and catalog only after commit. It runs only in a run that evaluatedcopilotand declares every legacy plugin from.agents/plugins; otherwise (uninstall, prune,--target claude, an old lock, an unreadable ledger) the legacy state is kept with a warning to runapm install.install/phases/lockfile.py,drift.py,deps/cli.py,services.pyapm deps listreads the lock; scope-correct transition hints..apm/architecture,scripts/architecture_linterDiagram
Legend: how one locked plugin reaches each harness at project scope (dashed: Copilot also reads Claude's file, at lower priority).
Trade-offs
apm_moduleslive). Required for a clone without APM.falsefor Claude-only plugins. Copilot also reads.claude/settings.json, so APM writesfalsefor a Claude-only plugin in.github/copilot/settings.json. Ownership is exact without a lock-schema change: APM owns the Copilot key of every plugin it declares to Claude. The cost: to keep a Claude+Copilot plugin off in Copilot, narrow itstargets:(APM then writes thefalse) rather than hand-editing that key; when APM overrides a value it did not write, it prints one[!]line naming the key and pointing totargets:. What APM last wrote is recorded beside each native row asnative_declared(a per-entry field 0.37 readers already preserve as unknown; advisory, not trust-bearing), so values a narrowed run left behind change silently. Afalsefor a Copilot-only plugin, or in Claude's file, is still kept.targets:, never reach that plugin keeps its whole previous lock row, deployed root and declarations, even if its source changed, and says the update waits (same shape as req-na-005's "keep the previous entry"). Such a run also deploys nothing loose for that dependency (for example itscursorfiles), so the kept row and disk agree.apm audit --ciandapm install --frozenthen report only the deferred update itself (a local source newer than the lock) until a full install, after which both pass.apm uninstall <pkg> && apm install <pkg>(inherited fix(claude): install intact user plugins through Claude settings, owned by the lock #3290 guard, now with a scope-correct hint); plugins without loose hooks switch automatically.originremote, the name derives from theapm.ymlname, so two remote-less repos with the same name on one machine share a name.Benefits
claudestays off in Copilot (real CLI:(disabled)), and turns on whencopilotis added to its targets.copilot plugin list→demo-plug@apm-p-… (enabled) from <clone>/.agents/plugins), none before trust.superpowers@apm-p-… (v7.0.2) (enabled).mine@team: truesurvive; explicitfalsesurvives.core.fileMode=falsepassapm auditagainst the committed lock.Validation evidence (local, CI runs after retarget to main)
Note
CI does not run on a PR whose base is not
main. Everything below ran locally on headcaa0ede9(2 CPUs, git commit signing disabled for tests viaGIT_CONFIG_*). Every remaining failure also fails on basece7f86b9.uv run --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/uv run --extra dev ruff format --check …(same paths)uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/relative_toguard (fromci.yml)bash scripts/lint-auth-signals.shuv run --extra dev python scripts/lint_architecture_boundaries.py --root .pytest tests/unit -q -n autotest_unix_install_ownership×246 run as root,test_public_release_metadata×35,test_isolated_network_guard×8, git env/transport ×5)APM_BINARY_PATH=.venv/bin/apm pytestnative lifecycle set¹pytest tests/spec_conformance -n 2test_marketplace_directory_reqs, also on base)pytest tests/integration/test_architecture_owner_rule_mutations.py -k "claude or copilot or native or marketplace"removal-baseline, also on base)pytest tests/integration/test_copilot_project_settings_precedence.py(real Copilot CLI 1.0.112, isolatedCOPILOT_HOME; skips without the client)¹ Native lifecycle set
test_claude_native_hook_lifecycle.py,test_native_plugin_audit_lifecycle.py,test_native_plugin_cache_audit.py,test_native_plugin_cache_replay.py,test_dependency_replacement_lifecycle.py,test_unmanaged_skill_preflight_matrix.py,test_plugin_bin_trust_posture.py,test_copilot_project_settings_precedence.py,test_global_audit_external_apm_home_lifecycle.py,test_install_dry_run_transitive_lifecycle.py, plustests/unit/install/test_native_project_scope.py,tests/unit/copilot_plugins/,tests/spec_conformance/test_copilot_plugins_reqs.py.Scenario evidence
test_a_fresh_checkout_loads_the_apm_declared_plugin+ manual clone run; Claude: settings/catalog shape pertest_install_commits_a_relative_declaration_to_both_harness_files(no Claude binary here)diff -r apm_modules/obra/superpowers .agents/plugins/superpowers→ only APM's.apm-pindiffers; Copilot lists it enabledtest_removal_keeps_user_entries_and_explicit_false,test_dependency_replacement_lifecycle.pynative case, manual runtest_the_later_file_wins_when_both_name_the_plugin(all 6 file pairs, real CLI)--targetnever retires a plugin it did not evaluate (targets: [claude]+--target copilot;targets: [copilot]+--target claude), even when its source changed: both settings files, the deployed root and the whole lock row (to_dict()) stay byte-identical, with a default-visible "Kept the previous version" notetest_a_narrowed_target_never_retires_a_plugin_it_did_not_evaluate(separate CLI processes; 4 cases; the 2 changed-content cases fail on45e0b51e)targets:edited, then--target claude) leaves APM's Copilot value to change silently on the next full installtest_a_narrowed_run_leaves_apms_copilot_value_to_change_silently(fails on71dffff9)--target cursorthe loose and native files and lock row stay at v1 with no deployed drift; a full install applies v2 andaudit --ciandinstall --frozenpasstest_a_kept_plugin_deploys_nothing_loose_so_lock_and_disk_agree(fails on71dffff9)--target cursor, and the full install applies v2 with--frozenpassingtest_a_kept_plugin_converges_on_the_next_full_install(fails on48dc338f)test_an_evaluated_dependency_wins_a_ledger_record_it_shares_with_a_kept_one(fails witha8706e0e's ordering)targets:changes silently, and atargets:narrow or widen retires the stale declarationtest_apm_reports_when_it_flips_a_copilot_value_it_owns,test_a_targets_edit_retires_the_stale_declaration_quietly(narrow and widen),test_a_value_apm_wrote_under_earlier_targets_changes_without_a_warning(the last 3 fail on45e0b51e)test_a_plugin_targeting_claude_only_stays_off_in_copilot(real CLI),test_apm_owned_suppression_follows_the_targets_both_ways,test_cross_target_suppression_is_the_consumers_own_false(req-na-004)apm-registration.jsonis one rollback unit and never silently deactivatestest_legacy_registration_moves_when_copilot_declares_its_plugins,test_a_failure_after_retirement_restores_the_legacy_registration,test_legacy_registration_is_kept_unless_copilot_declares_its_plugins(uninstall/prune,--target claude, plugin no longer for Copilot),test_an_unreadable_ledger_is_never_deleted, lifecycle migration testtest_committed_digest_ignores_the_exec_bit_a_teammate_checkout_dropsWarning
Residuals, not verified here. (1) Superpowers' SessionStart hook running: no
claudebinary in this environment, and a Copilot session needs a login an isolatedCOPILOT_HOMEcannot borrow; needs a human witness. (2) Cross-harness spill for Antigravity (documents that<workspace>/.agents/plugins/folders activate in that project, our profile root) and Grok Build (docs say it reads project.claude/settings.jsonmarketplaces; observed not loading): no binaries here, listed only. (3) Accepted Claude residuals: per-user name registry (handled by the per-repo name), worktrees resolving the relative path against the main checkout, one-session lag with relative paths. (4) Pre-existing:apm prunedoes not see an orphaned Agent Plugin root that has onlyplugin.json, so it is not retired by prune (uninstall retires it).Manual verification for the reviewer
About 2 minutes. Needs
claude(Claude Code) and, optionally,copiloton PATH. It closes the one residual this environment could not witness: Superpowers' SessionStart hook running from the committed root.1 native plugin(s) deployed to /tmp/sp-check/.agents/plugins and declared in Claude Code and GitHub Copilot settings;.agents/plugins/superpowers/hooks/hooks.jsonexists;.claude/settings.jsonhassuperpowers@apm-p-…: trueand"path": "./.agents/plugins".git add -A && git commit -qm t && git clone -q /tmp/sp-check /tmp/sp-clone && cd /tmp/sp-clone.claude, accept the folder-trust prompt, then/exitand runclaudeagain (relative-path plugins can load from the second session). In that session run/plugin.Observe:
superpowers@apm-p-…is listed and enabled.Did a SessionStart hook inject context? Quote its first sentence.Observe: Claude quotes the Superpowers session-start context: an
<EXTREMELY_IMPORTANT>block whose first sentence isYou have superpowers.For extra certainty,claude --debugprints the SessionStart hook from.agents/plugins/superpowers/hooks/run-hook.cmdrunning with exit 0./tmp/sp-clone, runcopilot plugin listafter trusting the folder.Observe:
superpowers@apm-p-… (v7.0.2) (enabled) from /tmp/sp-clone/.agents/plugins.Clean up:
rm -rf /tmp/sp-check /tmp/sp-clone.How to test
origin,apm.ymltargets[claude, copilot]and a Claude-format plugin dependency:apm install; check.agents/plugins/<p>/, the catalog and both settings files ("path": "./.agents/plugins",apm-p-…).copilot plugin list→ enabled from<clone>/.agents/plugins.targets: [claude]andapm install→.github/copilot/settings.jsonholds"<p>@apm-p-…": falseandcopilot plugin listshows it disabled; addcopilotback →true, enabled.apm uninstall <dep>→ APM keys and.agents/plugins/<p>gone, your own keys kept.chmod -xa deployed hook script,apm audit→ no drift at project scope.Docs re-home after #3996
Done: the docs commit (last) is written directly on the #3996 layout. Main home
consumer/install-plugins.md(#native-plugins); alsoconsumer/install-packages.md(what to commit),consumer/install-mcp-servers.md,consumer/installing-from-marketplaces.md,consumer/approve-executables.mdx,quickstart.mdx(re-run end to end),concepts/how-apm-works.md,reference/cli/{install,uninstall,audit,approve,pack}.md,reference/{lockfile-spec,package-types,policy-schema}.md,producer/{write-primitives.md,build-a-plugin.mdx,publish-to-a-marketplace.mdx},troubleshooting/index.md, and apm-usagecommands.md,package-authoring.md,governance.md,workflow.md.Issue and approved scope
Issue: Fixes #3921
Human scope-approval comment: #3921 (comment)
Completes the issue's code, tests, docs and changelog. The runtime witness that Superpowers' hooks run in Claude Code needs a human with the
claudebinary (see residuals).Type of change
Testing
ce7f86b9(listed above)Changelog
## [Unreleased]inCHANGELOG.md(Added, last line).Spec conformance (OpenAPM v0.1)
Important
The normative change is isolated in one commit,
spec(normative, pending Daniel): project-scope clause for Part C / req-na-002, amendment 0.1.68 (provisional; 0.1.67 is taken by #3993; renumbered at merge). It revises the req-na-002 root-digest clause for project scope (paths + bytes recorded; exec bit compared per machine), the req-na-004falserule (cross-target suppression: the consumer owns the Copilot key of a plugin it declares to Claude), and criterion A5 (a disclosed file priority, verified against Copilot CLI 1.0.112 by a test that skips without the client), and updates Part C and the Section 5.2native_pluginrow. req-na-005 is untouched; statement count unchanged (148). The implementation commits do not depend on it.docs/src/content/docs/specs/openapm-v0.1.md(amendment row in Appendix D).@pytest.mark.req("req-na-002"),req-na-003,req-na-004,req-na-007tests intests/spec_conformance/test_native_activation_profile_reqs.py.CONFORMANCE.{md,json}regenerated viauv run --extra dev python -m tests.spec_conformance.gen_statementand committed.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com