Adopt the Agent Plugins open standard (1.0.0) as the portable target contract

[ScriptedAlchemy]

Adopt the Agent Plugins open standard as the portable target contract

Spec pin: Agent Plugins 1.0.0 — https://agent-plugins.org/specification, repository agentplugins/agent-plugins-spec @ ff8ab5e392cc87bd88d87c060815a87490e51003 (2026-08-19). Vendored schema hashes (sha256):

• plugin.schema.json: 0a4aad95ce337878ad38802ebf0daa3fde76abe3f65400c86bcbb1ec0b3ab883
• mcp.schema.json: 6539175bfcdf43085855183e86da40ea94b166547a72b47ae9a0a390516d3acb

Decision

The portable target IS the Agent Plugins adapter (adapterRevision 1.3.0). It emits root plugin.json (canonical $schema), skills/, and mcp.json, validates against the pinned schemas at build time, and declares rules/commands/hooks/events/marketplace honestly unavailable (the v1 standard packages only skills and MCP servers).

Native proof status

• Repeatable CI-safe proof: installer + isolated-Cursor-home filesystem + pinned-schema conformance (runPortableHostInstallProof).
• IDE dogfood (2026-09-02, Cursor 3.18.25 stable 280eca2911f1, isolated instance): plugin discovered with Local badge, skill discovered with exact SKILL.md description, MCP config discovered and spawned, stdio handshake completed with a launchable config. Audit: docs/audits/2026-09-02-agent-plugins-cursor-ide-proof.md.

Upstream interop gaps observed in Cursor 3.18.25 (all violate spec 7.2.1/9.2 MUSTs)

1. ${PLUGIN_ROOT} not expanded in cwd — literal cwd → spawn <cmd> ENOENT (the spec's own stdio example uses "cwd": "${PLUGIN_ROOT}").
2. ${PLUGIN_ROOT} not expanded in args — server starts, gets the literal path, exits MODULE_NOT_FOUND.
3. Omitted cwd defaults to $HOME, not the plugin root.

Cursor's proprietary ${CURSOR_PLUGIN_ROOT} expands and connects (verified, stable heartbeat), so the loader pipeline works — it is not wired to the standard's placeholders for this format. Consequence: spec-conformant portable stdio MCP servers currently cannot launch on Cursor, though discovery/skills work fully.

Follow-ups

• Report the three expansion gaps to Cursor (product feedback) with the audit evidence.
• Re-run the IDE dogfood when a Cursor release notes Agent Plugins placeholder expansion; upgrade capability evidence when servers launch spec-conformantly.
• Watch the spec repository for post-1.0.0 revisions (subtree/chore cadence as with the Effect RC re-pin).

[ScriptedAlchemy]

Close-out: Agent Plugins 1.0.0 is the portable target contract

Delivered in two PRs, both squash-merged to main with green CI:

• feat(portable): complete Agent Plugins 1.0.0 adoption — manifest metadata, pinned byte lane, doctor findings (#307) #373 — 65c05a617 — manifest metadata + extensions, pinned byte lane (AB6035–AB6038), doctor AB7320, capability rows, docs, changeset, adapterRevision 1.5.0 → 1.6.0.
• fix(portable): fail closed on Agent Plugins normative MCP rules in ordinary builds (#307 review follow-up) #406 — 98751df4a — review follow-ups: normative MCP rules fail closed at plan time and in ordinary build / validate --artifact, platform-independent containment, RFC 9110 header values, drive-relative Windows commands, symlink-safe byte lane, built-in-adapter identity check. (Main CI on 98751df4a went green after a rerun of one unrelated Node 24 flake in playground-service.test.ts; the commit does not touch that file.)

Per-item evidence

Item	Status	Evidence
Spec located and pinned	Done	Agent Plugins 1.0.0, agentplugins/agent-plugins-spec @ ff8ab5e392cc87bd88d87c060815a87490e51003 (2026-08-19). packages/agent-bundle/src/adapters/schemas/portable/{plugin,mcp}.schema.json with dated PROVENANCE.json (retrieved 2026-09-01, re-verified 2026-09-02 against the live 1.0.0 schema URLs; sha256 0a4aad95…3ab883 / 6539175b…6d3acb, identical to the hashes in this issue's body).
Manifest + layout conform to 1.0.0	Done	src/adapters/portable.ts emits root plugin.json (canonical $schema, §5.4 author/homepage/repository/license/keywords, §5.6 reverse-domain extensions), skills/<name>/SKILL.md, and mcp.json. Omitted metadata leaves the manifest byte-identical to the previous contract; malformed values fail closed with portable.manifest.<field>.invalid.
Component directories per standard	Done (honest)	The 1.0.0 standard packages only skills and MCP servers. capabilities/portable-1.0.0.json records dated unavailable rows for commands, agents, hooks, rules, event routes, marketplace, notice delivery, extension directories, legacy SSE (27 unavailable / 4 supported rows), each citing the spec section.
Build-time validation against the pinned schema, fail-closed	Done	Plan time: portable.mcp.{command,cwd,env,url,headers}.standard errors (src/adapters/portable-mcp-rules.ts, shared with the byte lane). Artifact: AB6035 (schema/JSON), AB6036 (normative text the schemas cannot express), AB6037 (symlink containment) run over every built-in portable/ tree in build and validate --artifact (src/build/validate-artifact.ts → validatePortableTargets); --host-validation adds the host report + AB6038 provenance note. All codes documented in docs/diagnostics.md ("Agent Plugins portable validation (AB6035–AB6038)").
doctor static findings (#340 pattern)	Done	src/install/doctor.ts AB7320 validates installed root plugin.json that declares the Agent Plugins $schema against the pinned 1.0.0 contract; tests/doctor.test.ts "validates root plugin.json installs that declare an Agent Plugins schema against the pinned 1.0.0 contract".
Tests	Done	tests/portable-adapter.test.ts (plan-time rules incl. bin/server, escaping cwd, plain HTTP off loopback, duplicate headers, control chars, C:\…, C:server, ./../anchor/server), tests/portable-plugin-validation.test.ts (schema conformance + every normative rule + full forbidden-header-byte sweep), tests/artifact-validator.test.ts (ordinary-build fail-closed, symlink not followed, custom adapter named portable left alone, --host-validation does not duplicate diagnostics), tests/adapter-metadata.test.ts pins (adapterRevision 1.6.0, both schema sha256s), tests/host-install-proof.test.ts runPortableHostInstallProof (installer + isolated Cursor home + pinned-schema conformance, fixture tests/fixtures/host-install-portable/).
Docs	Done	README portable section, docs/framework-mode.md portable target, docs/diagnostics.md (AB6035–AB6038, AB7320, portable.mcp.*.standard), docs/audits/2026-09-02-agent-plugins-cursor-ide-proof.md evidence/source matrix.
Changesets	Done	.changeset/portable-agent-plugins-contract.md, .changeset/portable-agent-plugins-evidence.md, .changeset/portable-normative-rules-fail-closed.md (all agent-bundle: minor).
adapterRevision bump + pins	Done	1.5.0 → 1.6.0; capabilities/portable-1.0.0.json + tests/adapter-metadata.test.ts pinned to the new revision and schema hashes.
Backward compatibility	Done (explicit)	No previously emitted portable path or field changed: plugin.json / skills/ / mcp.json layout is preserved and new manifest fields are opt-in. Behavioural tightening is documented in .changeset/portable-normative-rules-fail-closed.md: bundles whose MCP servers already satisfy the standard emit byte-identical output; servers relying on path-bearing / whitespace-bearing command, escaping cwd, plain-HTTP remote URLs, or placeholders in headers now fail the build with a field-scoped diagnostic instead of being published. Contract matrix visibility: adapterRevision bump in the #218 metadata pins.

Review-thread inventory (maintainer rule)

PR	Threads found	Fixed	Replied	Final reviewer state
#373	2 (P1 placeholder/normative rules only in --host-validation; P2 header control chars)	2 (both in #406)	2	re-swept after merge; both threads answered with the #406 fix references
#406	7 (P1 anchor collision, P2 built-in-adapter identity, P2 header bytes, P2 duplicate diagnostics, P2 symlink before byte lane, P2 drive-relative Windows, P3 changeset wording)	6 fixed + 1 not-a-defect pinned with a regression test	7	Codex re-review of 33e5b0cdf: "Didn't find any major issues"; the final push was a content-identical rebase onto main

Follow-ups

The three unchecked items in this issue's body (Cursor product feedback for the placeholder-expansion gaps, IDE dogfood re-run on a fixed Cursor release, post-1.0.0 spec watch) are external / time-gated and cannot be completed from this repository. They are carried over verbatim to #426 so this issue can close on the engineering deliverable.

[ScriptedAlchemy]

Closing: engineering deliverable complete (#373 65c05a6, #406 98751df); external follow-ups tracked in #426.