feat(plugins): add Agent Plugins compiler and native import

[dcramer]

Adds project-scoped plugin dependencies to dotagents with an explicit compiler/importer contract.

[[plugins]]
name = "review-tools"
source = "getsentry/agent-plugins"
path = "plugins/review-tools"
targets = ["claude", "cursor", "codex", "grok", "opencode", "pi"]

install resolves the source using the existing trust and minimum-release-age policies, stages the bundle under .agents/plugins/<name>/, records the resolved source in agents.lock, and reconciles the selected client harnesses. Plugins participate in install, offline sync, list, remove, doctor, lockfile updates, and selective gitignore generation.

Forward compilation: Agent Plugins → client harness

The portable input is Agent Plugins v1: required plugin.json, optional skills/, optional mcp.json, and reverse-domain extension directories. Portable source files are preserved unchanged.

Each target adapter owns an exact filesystem contract:

Target	Generated output
Claude Code	Project marketplace plus a Claude-native manifest inside the installed bundle
Cursor	Project marketplace plus a Cursor-native manifest inside the installed bundle
Codex	Repo-scoped marketplace plus a Codex-native manifest inside the installed bundle
Grok Build	Sanitized managed copy of the portable bundle
OpenCode	Supported Agent Skill symlinks only; this is resource projection, not plugin installation
Pi	Agent Skill symlinks in the shared .agents/skills/ directory

Target JSON remains client-native. Dotagents ownership is recorded in adjacent .dotagents-managed sidecars, so native validators do not receive dotagents-only fields. Legacy metadata-marked output is still recognized for migration.

Standard bundles reject legacy root agents, commands, rules, hooks, and native MCP files. Client-owned content must live in reverse-domain extension directories and is not guessed or translated into another client. Pi is the explicit isolation exception: targeting Pi projects skills into the shared .agents/skills/ surface, making them visible to other clients that consume that directory.

Portable MCP validation covers stdio, streamable HTTP, and SSE transports, safe command/cwd rules, reserved runtime variables, and per-server recovery. A malformed server is omitted while valid siblings are emitted into a sanitized target-owned MCP adapter. Valid source MCP remains untouched.

Reverse import: native bundle → portable intersection

Native Claude, Cursor, and Codex bundles remain discoverable. Dotagents preserves the owning native manifest and resources, records native provenance in a managed marker, and exposes only the portable intersection—core metadata and valid Agent Skills—to other selected clients.

Native commands, agents, rules, hooks, apps, and MCP references are never cross-translated. Grok receives a sanitized Agent Plugins core rather than another client’s native directories. Native MCP-to-portable conversion remains explicit future importer work rather than an inferred transformation.

Exact integration contract

The main integration contract is one table-driven test definition run in six isolated projects—Claude, Cursor, Codex, Grok, OpenCode, and Pi. Each case enumerates the complete expected file/symlink inventory and validates every file’s full semantic contents and every symlink target. This prevents one harness, especially Pi’s shared skill projection, from making another harness pass accidentally.

The fixture includes a contained linked skills/ directory, client-extension files, a stdio MCP server using PLUGIN_ROOT/PLUGIN_DATA, and a streamable HTTP MCP server. A separate reverse-import case proves native provenance survives sync and native components do not leak into Cursor, OpenCode, or Grok.

Ownership and safety

• Canonical and referenced paths are checked using resolved filesystem paths.
• Broken or escaping symlinks are rejected; contained relative symlinks survive staging and target copies verbatim.
• Existing plugin destinations require the on-disk managed marker; lockfile state alone never authorizes replacement.
• Source-supplied dotagents ownership markers are stripped before installation.
• Unmanaged marketplaces, manifests, projections, and skill links are preserved and reported.
• Replacement uses staged and backup directories, retaining recoverable state after failure.
• Obsolete native adapters are pruned before dependent copies are refreshed.

Review order

1. specs/plugins.md for forward/reverse invariants and explicit gaps.
2. plugins/schema.ts and plugins/store.ts for portable parsing, native discovery, provenance, containment, and installation.
3. plugins/runtime/ for target manifests, marketplaces, MCP recovery, projection, ownership, pruning, and verification.
4. CLI lifecycle integration and diagnostics.
5. The isolated harness integration table and skills/dotagents-qa client proofs.

Validation includes the full repository suite, install/sync repair QA, clean Claude validation plus actual marketplace add/install/details with one skill and two MCP servers, and Codex marketplace add/install/list with the installed non-empty MCP file inspected. Cursor remains deterministic-contract-only because its desktop CLI exposes no plugin validation command; Grok client proof runs when its CLI is available.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dotagents	Ready	Preview	Aug 9, 2026 7:58am

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 09a84dd. Configure here.}

[cursor]

MCP schema case folding gap

Low Severity

parsePluginManifest now treats Agent Plugins schema origins as case-insensitive and canonicalizes them, but parsePluginMcpBestEffort still requires an exact AGENT_PLUGIN_MCP_SCHEMA literal. A standard bundle whose mcp.json uses the same case-folded origin is classified as standard, then drops portable MCP after envelope validation fails.

Additional Locations (1)

• packages/dotagents/src/plugins/schema.ts#L277-L331

 

^{Reviewed by Cursor Bugbot for commit 09a84dd. Configure here.}