RFC: APM Strategic Direction — Governance and Composition for AI Agent Plugins

[danielmeppiel]

Context

The Claude Code plugin specification has shipped — and GitHub Copilot CLI has adopted it. Between plugin.json, marketplace discovery, enabledPlugins in settings.json, and enterprise managed settings, the native ecosystem now covers a significant portion of what APM originally set out to do: bundling, sharing, and project-scoped distribution of agent primitives.

This is a good thing. It validates the need APM identified. It also means APM's positioning needs to evolve. This RFC proposes a direction and invites feedback before we commit to it.

Proposed Direction

APM becomes the governance and composition layer for AI agent plugins. Not an alternative to plugins. Not a competing format. The tool that makes plugins reproducible, auditable, and composable from heterogeneous sources.

Two pillars:

1. Reproducibility & Governance

enabledPlugins in settings.json is a boolean map — "formatter@acme-tools": true. No version field. No SHA. No lock file. The consuming project can't independently pin versions.

APM already ships apm.lock (since v0.7.2) with commit-pinned versions and resolution metadata. Extending this to plugin references — plus adding drift detection (apm audit --drift) and CI gates (apm audit --ci) — fills a gap that plugin systems won't address. Lock files are a package manager concern, not a runtime concern.

The enterprise question this answers: "What agent instructions were active when release 4.2.1 was built?"

2. Multi-Source Composition

Enterprise teams compose agent config from GitHub, Azure DevOps, internal repos, and sub-paths within monorepos. No vendor will build a tool that assembles plugins from competing platforms' sources. APM is the neutral assembler:

# apm.yml — compose from heterogeneous sources
dependencies:
  apm:
    - acme-corp/security-baseline/instructions/
    - dev.azure.com/acme/internal/hooks/scan-on-edit
    - acme-corp/python-standards/skills/linting

Format strategy: apm.yml as build manifest, plugin.json as output

apm.yml is where developers declare intent (dependencies, versions, sources). apm install resolves everything and writes valid native config — settings.json, plugin directories, and apm.lock. If you stop using APM, the generated files still work. Zero runtime dependency.

apm.yml  →  apm install  →  .claude/settings.json
                          →  .github/plugin/
                          →  apm_modules/
                          →  apm.lock

Existing apm_modules/ + compiled output (AGENTS.md, CLAUDE.md) continues working for tools that don't support plugins yet. As plugin support broadens, compiled output can be phased out gradually.

Proposed Roadmap (Priority Order)

1. Output native plugin formats — apm install writes valid settings.json and plugin directories (PR Implement plugin management system and CLI commands #83 direction)
2. Extend lock file to plugins — integrity hashes, CI verification mode
3. Governance tooling — apm audit --drift, trusted source enforcement
4. apm build — assemble valid plugin directories from heterogeneous sources
5. Schema evolution — support both APM package refs and plugin refs in apm.yml
6. Maintain compilation — keep apm compile for tools that don't support plugins yet; don't expand

What's changing in messaging

Before	After
"The npm for agent primitives"	"Governance and composition layer for AI agent plugins"
"You need apm.yml instead of settings.json"	"apm.yml adds reproducibility and policy on top of settings.json"
"Compilation is a core feature"	"Compilation translates between standards — valuable as a bridge, not the long-term differentiator"

Known gaps we need to close

• Source diversity: APM only supports GitHub.com, GHE, and ADO today. The plugin spec supports GitLab, Bitbucket, and any git URL. Generic git URL support (Generic git URL support and optional output override #72, with [FEATURE] GitLab support (SaaS + self-hosted) #133 and [FEATURE] Bitbucket Cloud support #134 as sub-issues) is the fix.
• Plugin format output: APM doesn't produce plugin.json yet. PR Implement plugin management system and CLI commands #83 starts this.

What I'd like feedback on

1. Does this direction resonate? Is governance + composition the right layer for APM, or do you see a different role?
2. Roadmap priorities — would you reorder anything? Are we missing something critical?
3. Migration concerns — if you're using APM today, does the transition path (keep existing formats, add plugin output alongside) work for your setup?
4. Source support — how important is GitLab/Bitbucket support for your team? Does the generic git URL approach (Generic git URL support and optional output override #72) seem right?

[cteyton]

Interesting thoughts.
Regarding the governance and multi-source composition, have you imagined some policies defined in apm.yaml that could exclude some specific sources for instance? I wonder if some extra security features could come with the governance feature.

[danielmeppiel]

Yes, this is a central piece, allowing teams and organizations to forbid packages, sources as well as enforcing others. Working on a proposal for this one. Going to update the roadmap discussion.

[danielmeppiel]

Strategy Update: PR #83 Review & Refined Positioning

Following up on this RFC with findings from the PR #83 review (plugin support) and refined strategic thinking.

PR #83 Status

PR #83 implements the decompose-and-normalize approach: plugins are downloaded, their plugin.json is parsed, artifacts are mapped to APM's standard .apm/ structure, and a synthetic apm.yml is generated. After normalization, plugins become standard APM packages — all existing commands (install, uninstall, deps, prune, compile) work without plugin-specific code.

Architecture verdict: correct. The decompose approach preserves APM's composition value. Bundle placement (just copying whole plugins to .github/plugin/) would make APM a thin wrapper around copilot plugin install — no differentiation.

PR has 6 must-fix items before merge (security: symlink following + non-deterministic glob, test fixes, docs). Full review posted on the PR.

Refined Positioning: "Terraform for AI Agents"

After deeper analysis, the positioning has crystallized. APM doesn't compete with copilot plugin install or Claude's enabledPlugins — it orchestrates across them. Just as Terraform orchestrates across AWS/Azure/GCP without competing with cloud providers.

The value flywheel:

1. CONSUME — apm install resolves plugins from any git source → normalizes → scatters to native locations
2. COMPOSE — apm.yml assembles from N sources, including cherry-picked sub-paths from plugins
3. LOCK — apm.lock pins every dependency to exact commit SHA — runtimes don't build lock files
4. BUILD — apm compile translates to AGENTS.md/CLAUDE.md. Future: apm build --format plugin produces valid plugin directories
5. DISTRIBUTE — Output IS native format — stop using APM and .github//.claude/ configs still work

Cherry-Picking: A Key Differentiator

One insight that emerged: APM's existing virtual package support (subdirectory and file-level packages) means you can cherry-pick individual primitives from plugins:

dependencies:
  apm:
    - acme-corp/security-plugin@^2.0              # Full plugin
    - acme-corp/code-quality/skills/linting        # Just the linting skill
    - acme-corp/standards/instructions/security.md # Single instruction file

Plugins are atomic — you get everything or nothing. APM lets you pick exactly what you need and compose from multiple sources.

Priority System Advantage

When APM decomposes plugins and scatters primitives to .github/agents/, they appear at project-level priority (priority 2 in Copilot CLI's loading order). Natively installed plugins appear at priority 7. APM-managed config takes precedence — correct governance behavior.

@cteyton — On Security Policies

Great question about exclusion policies. This is exactly the direction for apm audit:

• apm audit --drift — detect when someone manually adds unapproved plugins to settings.json that aren't declared in apm.yml
• Trusted source enforcement — finer-grained than strictKnownMarketplaces. APM could enforce "only plugins from these specific repos/orgs" or even "no plugins with MCP servers that connect to production endpoints"
• apm audit --ci — CI gate that blocks PRs if agent config doesn't match the lock file

The plugin spec's governance model (strictKnownMarketplaces) is marketplace-level allowlisting. APM can be granular down to the repo, sub-path, or individual primitive level. Combined with lock file verification, this gives enterprises the "what agent instructions were active at release 4.2.1?" audit trail that no native tooling provides today.

Updated Roadmap

No changes to the priorities proposed in the RFC. PR #83 lands item 1 (output native plugin formats). Next priorities remain lock file extension and governance tooling.

[Nyrok]

The reproducibility and auditability problem you describe at the plugin layer exists at the prompt layer too.

enabledPlugins with no version pin is one form of implicit state. Prompt constraints buried in prose are another. You can't diff them, you can't version them cleanly, and downstream tooling has no reliable way to inspect what the agent was told it could or couldn't do.

The same governance instinct that motivated APM applies here: if you separate concerns into explicit typed blocks, role, context, constraints, output format, then the prompt becomes something you can audit, reproduce, and compose from. Right now most prompts are the equivalent of a flat config file with all settings inline.

I've been building flompt for exactly this, a visual prompt builder that decomposes prompts into 12 semantic blocks and compiles to Claude-optimized XML. Open-source: github.com/Nyrok/flompt