feat(dist): ship the package as an Agent Plugins 1.0.0 plugin root

[filip131311]

What

Adds two files — packages/argent/plugin.json and packages/argent/mcp.json — so the published npm tarball doubles as a loadable Agent Plugins 1.0.0 plugin root. The spec fixes plugin.json, mcp.json and skills/ at the plugin root, and skills/ already lands there at build time (bundle-tools.cjs copies packages/skills/skills → packages/argent/skills), so the layout is a two-file gap, not a restructure.

@swmansion/argent/          ← plugin root
├── plugin.json             ← new
├── mcp.json                ← new
├── skills/                 ← already there
└── dist/, bin/, dylibs/, …

What this does NOT change

argent init is untouched and stays the default. Zero lines change under packages/argent-installer/ — editor detection, the MCP entries written into all ten supported clients, global vs. --local committable mode, rules and agent copying, stale-config cleanup, allowlists, telemetry all behave exactly as before. This is an additional way in for clients that implement the standard, not a replacement.

The README section says so explicitly, and lists what a plugin structurally cannot carry (the spec has only two portable component types — Agent Skills and MCP servers): rules/argent.md, the argent-environment-inspector subagent, and the per-client touches init applies.

Why npx, and why pinned

{ "type": "stdio", "command": "npx", "args": ["-y", "@swmansion/argent@0.19.0", "mcp"] }

A plugin directory can reach a client by a route that never runs npm install — a git clone, a marketplace copy — so the server can't be assumed to sit next to the manifest, which rules out the ${PLUGIN_ROOT}/dist/cli.js form. The version pin keeps the launched server on the same release as the skills shipped beside it in the same plugin; an unpinned @latest would silently decouple them.

Trade-off worth knowing: the first launch downloads the package (~36 MB of platform binaries) unless it's already in the npx cache. Documented in the README.

The server key stays argent, matching MCP_SERVER_KEY in the installer — clients namespace a plugin server's tools by that id, so renaming it would rename every mcp__argent__* tool the bundled skills call for by name.

Keeping it from rotting

Both files are inert at build time, so nothing in the repo would notice a release bump leaving them behind — the plugin would keep launching the previous release next to this release's skills. scripts/check-workspace-versions.mjs (already run by repo-hygiene.yml) now holds them to packages/argent/package.json the same way it holds server.json, via a new pure pluginManifestMismatches():

• plugin.json version == the workspace version
• the npx arg pins @swmansion/argent@<that version> (an unpinned or stale spec fails)
• both $schema values name spec 1.0.0 and agree with each other
• mcp.json declares an argent stdio server
• files lists both filenames — npm ships package.json/README/LICENSE implicitly and nothing else, so forgetting either one publishes a tarball that isn't a plugin root while every other check still passes

Note for the next release: plugin.json's version and mcp.json's npx pin join the version-bump file set. Getting either wrong now fails CI rather than shipping quietly.

Testing

• node --test scripts/check-workspace-versions.test.mjs — 42 pass (17 new: the pluginManifestMismatches() matrix plus spawned-script runs for plugin drift, a combined half-finished bump, and missing/malformed file handling)
• node scripts/check-workspace-versions.mjs against this branch → in sync at 0.19.0
• Both manifests validated with ajv against the published schemas fetched from agent-plugins.org/schemas/1.0.0/ → VALID
• npm pack --dry-run -w @swmansion/argent → plugin.json and mcp.json present in the tarball contents
• tsc -p tsconfig.scripts.json, eslint scripts/, prettier --check all clean

Follow-ups (not in this PR)

• Marketplace listings (VS Code discovers from copilot-plugins/awesome-copilot-style repos; each client has its own route)
• A com.anthropic.claude-code/ extension namespace dir if we want the rule and subagent to travel with the plugin for Claude Code
• Live verification in VS Code / Copilot CLI once we decide on a distribution route

🤖 Generated with Claude Code