[Feature] Support Agent Plugins spec (agent-plugins.org) manifests

[Minitour]

Description

Agent Plugins (v1.0.0, published) is a new cross-vendor plugin format, steered by Amazon, Cursor, Microsoft, OpenAI, and Vercel. A plugin is a directory with a root plugin.json, a skills/ directory, an mcp.json, and optional reverse-domain extension directories (e.g. com.example.client/). Where plugins come from (registries, marketplaces, trust) is left to each client, so capa's registry model doesn't need to change.

capa should be able to consume plugins in this format. Today it only looks for .claude-plugin/plugin.json and .cursor-plugin/plugin.json.

What happens today

When a repo only ships the spec layout, detectAndParseManifest (src/shared/plugin-manifest/detect.ts) finds no manifest and falls back to directory discovery:

Spec requirement	capa today
Root plugin.json	❌ Not recognized. Name and version are lost, and the plugin is reported as "discovered"
Skills in skills/	✅ Picked up by the fallback
mcp.json	❌ The fallback only reads .mcp.json, so MCP servers are silently dropped
${PLUGIN_ROOT} / ${PLUGIN_DATA}	❌ Only ${CLAUDE_PLUGIN_ROOT} is expanded (mcp-parser.ts)
stdio / streamable-http / sse	✅ Probably works (normalized by command/url), but needs a test
Closed-schema manifest validation	❌ None
Filesystem containment	⚠️ install-path-guard.ts exists; coverage for these paths is unverified
Unknown extension namespaces	✅ Already ignored

Scope

• Recognize a root plugin.json (identified by $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) as a manifest type, ordered after the Claude and Cursor manifests.
• Parse mcp.json (mcpServers with type: stdio | streamable-http | sse).
• Expand ${PLUGIN_ROOT} and ${PLUGIN_DATA} only in args, env values, and cwd, as the spec requires. Default cwd to the plugin root. Decide where capa keeps the plugin data dir.
• Validate plugin.json against the published schema. Problems should be warnings, not install failures (unknown top-level fields are non-fatal per spec).
• Enforce the spec's path rules: ./ paths and cwd must stay inside the plugin root or the data dir.
• Keep failures per-component: a broken mcp.json must not block the plugin's skills.
• Tests using https://github.com/agentplugins/agent-plugins-example, plus a run through the conformance checklist.
• Docs: update "Plugin discovery and unpack" in docs/README.md and capabilities-manager skill references.

Out of scope / follow-up

• A capa extension namespace (e.g. extensions["org.infragate.capa"] plus a matching directory) so spec plugins can also ship hooks, rules, sub-agents, and commands.

References

• Spec: https://agent-plugins.org/specification
• Schemas: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
• Spec repo: https://github.com/agentplugins/agent-plugins-spec