universal-plugin 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -28,8 +28,8 @@
     "LICENSE",
     "bin",
     "dist",
-    "governances",
     "plugin.json",
+    "references",
     "schema",
     ".claude-plugin",
     ".cursor-plugin",
@@ -63,13 +63,12 @@
   },
   "scripts": {
     "build": "tsdown",
-    "check:governances": "tsx src/cli.ts plugin build --check --root .",
     "dev": "tsx src/cli.ts",
     "knip": "knip",
     "lint": "biome check .",
     "test": "pnpm build && vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm check:governances"
+    "verify": "pnpm typecheck && pnpm lint && pnpm test"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -79,11 +79,15 @@ keep their previous version.
 
 ```sh
 npx universal-plugin marketplace init --codex --root .
+npx universal-plugin marketplace add npm:repobuddy --description "Repo automation"
 npx universal-plugin marketplace validate --root .
 ```
 
-`validate` checks each catalog against the schema its runtime loads and names the key at fault, so a
-catalog that would be refused at install time is caught in the repository.
+`init` derives a catalog from the plugins a repository holds. `add` lists a plugin that lives
+elsewhere — a path, a GitHub repo (`--subdir` for a monorepo, `--ref`/`--sha` to pin it), an npm
+package, or another marketplace's entry — so a curating repository never needs a hand-written
+catalog. `validate` checks each catalog against the schema its runtime loads and names the key at
+fault, so a catalog that would be refused at install time is caught in the repository.
 
 Codex caches a local plugin install by its marketplace entry version. After you change packaged
 plugin files: update the canonical `plugin.json` version, regenerate the catalog (add `--force` to
@@ -102,14 +106,14 @@ npx universal-plugin config add --key sdd-plugins --entry '{"name":"aces","handl
 `add` appends the entry, or replaces the existing entry with the same `name`. Both commands print
 TOON by default; pass `--format json` for JSON.
 
-### governance
+### governance (retired)
 
-Version-pinned agent-tool contracts, read at runtime.
+`governance list` and `governance show` are retired. They print the replacement and exit 1 for one
+release, then go away. Read the documents with `buddy-agent-harness reference show <name>`, or, from a
+skill, with the `load-reference` skill in the `buddy-agent-harness` plugin.
 
-```sh
-npx universal-plugin governance list
-npx universal-plugin governance show plugin-design
-```
+This package ships its own documents (`plugin-design`, `slash-invocation`, `universal-plugin`) under
+`references/`, so `reference show` finds them in any project that depends on `universal-plugin`.
 
 ### Housekeeping
 

package/{governances → references}/plugin-design.md

@@ -330,10 +330,6 @@ Portability rules for skill bodies: keep each `SKILL.md` body under 6,000 chars;
 
 ## References
 
-```bash
-npx universal-plugin@<version> governance show skill-design
-npx universal-plugin@<version> governance show skill-repo-structure
-npx universal-plugin@<version> governance show agent-tool-output
-```
+Load `skill-design`, `skill-repo-structure`, and `agent-tool-output` with the `load-reference` skill in the `buddy-agent-harness` plugin.
 
 Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md

package/references/universal-plugin.md

@@ -0,0 +1,4 @@
+# Universal Plugin Format
+
+The rules for the universal plugin format live in `plugin-design`, which this package also ships.
+Load `plugin-design` with the `load-reference` skill in the `buddy-agent-harness` plugin.

package/skills/build-plugin/README.md

@@ -0,0 +1,29 @@
+# build-plugin skill
+
+Derive every vendor's form of a plugin from its one canonical `plugin.json`.
+
+## When to use
+
+- "build the plugin", "run plugin build"
+- "regenerate the vendor manifests", "sync the manifests after my change"
+
+## What it does
+
+Runs `plugin build`, which writes the Claude Code, Cursor, and Codex manifests and Copilot CLI's
+`com.github.copilot/` tree. It also refreshes this plugin's entry in the repository's marketplace
+catalogs. The skill prefers the project's own build
+script, otherwise runs `scripts/build.mjs`, which uses the CLI shipped beside the skill, so nothing
+is downloaded.
+
+The skill reads the result back to the user: which vendors were built, which catalogs changed, and
+each warning about something a vendor cannot represent. A `built 0` result is handed to `doctor`
+rather than reported as success.
+
+## Install
+
+Ships with the `universal-plugin` plugin. It is invoked in Claude Code as
+`/universal-plugin:build-plugin`.
+
+## References
+
+- [`plugin build` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/build/README.md)

package/skills/build-plugin/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: build-plugin
+description: Use this skill to build a universal agent plugin — regenerate the Claude Code, Cursor, and Codex manifests and the Copilot CLI component tree from the canonical plugin.json, after editing the manifest, a skill, an agent, a hook, or a command. It also refreshes this plugin's entry in the repository's marketplace catalogs. Trigger on "build the plugin", "regenerate the vendor manifests", "sync the manifests after my change", "run plugin build", or "update .claude-plugin/plugin.json".
+---
+
+# Build a plugin
+
+Derive every vendor's form of the plugin from the one canonical `plugin.json`.
+
+The canonical root `plugin.json` is the only manifest anyone authors. Everything a runtime reads
+beside it is **derived**, and this build is the one step that writes all of it:
+
+| Derived artifact | Read by |
+|---|---|
+| `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json` | Claude Code, Cursor, Codex |
+| `com.github.copilot/` (agents, commands, rules, hooks, LSP) | Copilot CLI in spec mode; the manifest itself is root `plugin.json` |
+| this plugin's entry in each marketplace catalog the repository already carries | anyone installing from the repository |
+
+So a change to the plugin is not done until it has been built. A runtime reads the derived files,
+not the canonical manifest, and a derived file that predates the change still ships the old plugin.
+
+## Step 0: Is this the right skill?
+
+| The ask is | Use instead |
+|---|---|
+| declare a new vendor, component, or field | `init-universal-plugin` edits `plugin.json`, then builds |
+| move the version | `version`: it writes the number and builds |
+| delete derived manifests, or drop a vendor | `remove-plugin` |
+| "the build says built 0" or a runtime loads nothing | `doctor-universal-plugin` |
+
+Everything else that ends in "regenerate what the runtimes read" is here.
+
+## Step 1: Find how the project builds
+
+```bash
+grep -n "plugin build" package.json
+```
+
+If a script already runs `plugin build`, run that script (for example `pnpm plugin:build`). It
+carries the project's own `--root` and whatever it chains after the build, such as a formatter over
+the written JSON. Otherwise run the launcher shipped beside this skill:
+
+```bash
+node scripts/build.mjs --root <plugin-root>
+```
+
+Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI that shipped beside
+it, so nothing is downloaded and the build cannot resolve a different version from the one installed.
+`npx universal-plugin plugin build` is the fallback. `--root` defaults to the working directory and
+must name the directory that holds the canonical `plugin.json`.
+
+The command never prompts, so it is safe to run unattended.
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Validate and report the plan, write nothing. Run this first when unsure what will change |
+| `--vendor <id>` | Build one vendor (`claude-code`, `cursor`, `codex`, `copilot-cli`), and refresh only its catalog |
+| `--verbose` | Print each field-level decision the derivation made |
+| `--format json` | The same result as JSON, for scripts |
+
+`--clean` also exists. It deletes derived manifests before rewriting them, so reach for it only
+through `remove-plugin`.
+
+## Step 2: Read the result
+
+Default stdout is TOON: one row per vendor (`vendor, path, status`), one row per catalog
+(`path, status`), and a precomputed summary. Read the rows; do not re-derive them.
+
+| Vendor status | Meaning |
+|---|---|
+| `built` | the derived manifest or component tree was written |
+| `canonical` | Copilot CLI with nothing to derive: root `plugin.json` serves it directly |
+| `skipped` / `failed` | the row says why; fix that and rebuild |
+
+A catalog row reads `updated`, `unchanged`, or `planned` on `--dry-run`. A build **never creates** a
+catalog, and it keeps an entry's non-local source, such as an npm package, while it re-derives the
+version. To add a catalog or change a source, use `marketplace`.
+
+Read stderr too. The build drops what a vendor cannot represent and warns instead of failing: a hook
+handler type a vendor cannot run, a `harnesses.copilot-cli` override with no delivery path, an
+invalid catalog. Each warning names something that will not reach a runtime. Tell the user each
+one; do not bury it in a summary.
+
+`built 0` with "nothing to build" is not success. The manifest declares no vendor, so hand it to
+`doctor-universal-plugin`, which the stderr line names.
+
+## Step 3: Commit what was derived
+
+Derived manifests are committed with the change that caused them, because a
+git-sourced install reads them straight from the repository. Stage the source change and its
+derived files together:
+
+```bash
+git status --short
+```
+
+Expect the vendor manifests, `com.github.copilot/`, and any refreshed catalog. A diff outside those paths did not come from the build.
+
+## Guards
+
+Validation runs before the first write, so a failed build leaves the tree untouched.
+
+| Message names | What it means | Do this |
+|---|---|---|
+| a missing `plugin.json` | `--root` is not the plugin root | point `--root` at the directory holding the canonical manifest |
+| codex requires `description` / `version` | Codex rejects a manifest without them | add them to `plugin.json` through `init-universal-plugin`, or `version` for the number |
+| a `--vendor` not among the targets | the manifest does not declare that vendor | declare it through `init-universal-plugin`, or drop the flag |
+| `vendorExtensions` or `.plugin/plugin.json` | a pre-0.6 layout this CLI no longer reads | run `doctor-universal-plugin`, which names the migration |
+
+## Do not
+
+- **Hand-edit a derived file.** The next build overwrites it. Change `plugin.json` or the component
+  source, then build.
+- **Edit `plugin.json` to get a different derived manifest.** A per-vendor field belongs under
+  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`. That is a declaration, and
+  `init-universal-plugin` owns it.
+- **Expect a build to pin skill `npx` references.** That is the release-time `plugin bundle`, not
+  this step.
+- **Expect a build to copy governances into skills.** A skill loads a reference through the
+  `load-reference` skill in the `buddy-agent-harness` plugin; the build no longer copies them, and
+  `--check` is gone.
+
+## Related skills
+
+| Task | Skill |
+|------|-------|
+| Change what the plugin declares | `init-universal-plugin` |
+| Diagnose a build that derives nothing, or a runtime that loads nothing | `doctor-universal-plugin` |
+| Move the version and rebuild in one step | `version` |
+| Delete derived manifests or drop a vendor | `remove-plugin` |
+| Create a catalog, or list a plugin with an npm source | `marketplace` |
+
+## References
+
+- Spec: [`plugin/build/`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/build/README.md)
+- [ADR-0014](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0014-build-refreshes-catalogs.md): the build refreshes catalogs it finds
+- [ADR-0017](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0017-retire-governance-for-reference.md): the build no longer copies governances into skills

package/skills/build-plugin/scripts/build.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Runs `universal-plugin plugin build` from the CLI that ships beside this skill, so the manifests a
+// plugin ships are derived by the version the author installed, never by one `npx` resolves.
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// <package>/skills/<skill>/scripts/build.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+
+process.argv.splice(2, 0, 'plugin', 'build')
+await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))

package/skills/doctor-universal-plugin/SKILL.md

@@ -152,7 +152,7 @@ pushed without a bump reaches nobody who already installed the plugin, and neith
 ([ADR-0010](../../.agents/spec/design/decisions/0010-version-policy.md) §6).
 
 The script compares the shipped paths — the canonical manifest, the skills directory, `agents/`,
-`governances/`, `mcp.json` — against the commit that set the version the manifest carries now, and
+`governances/`, `references/`, `mcp.json` — against the commit that set the version the manifest carries now, and
 emits `unreleased-content` for anything committed since. Uncommitted work is not reported; it has not
 shipped.
 

package/skills/doctor-universal-plugin/scripts/doctor.mjs

@@ -365,7 +365,7 @@ function commitThatSetVersion(current) {
  *  change twice. */
 function shippedPaths() {
 	const skills = typeof ext?.skills === 'string' ? ext.skills : './skills/'
-	const paths = ['plugin.json', skills, 'agents', 'governances', 'mcp.json']
+	const paths = ['plugin.json', skills, 'agents', 'governances', 'references', 'mcp.json']
 	return paths.filter((rel) => fs.existsSync(path.join(root, rel)))
 }
 

package/skills/init-universal-plugin/SKILL.md

@@ -38,11 +38,8 @@ This skill owns the **authoring** side: the plugin a project ships. Setting a re
 
 ## Prerequisites
 
-Load the component-selection governance before any work that adds or removes components:
-
-```bash
-npx universal-plugin governance show plugin-design
-```
+Before any work that adds or removes components, load `plugin-design` with the `load-reference`
+skill in the `buddy-agent-harness` plugin.
 
 It is the authoritative source for which component to reach for and which anti-patterns to avoid.
 
@@ -236,7 +233,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 
 ## References
 
-- Governance: `npx universal-plugin governance show plugin-design`
+- Reference: `plugin-design`, loaded with the `load-reference` skill in the `buddy-agent-harness` plugin
 - Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
 - Manifest schema (Agent Plugins Specification v1.0.0): https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
 - Extension schema (the body of `extensions["org.cyberuni.universal-plugin"]`), shipped in the package at

package/skills/init-universal-plugin/references/create.md

@@ -33,7 +33,7 @@ entry in both `vendors` and `harnesses` under
 ## Step 3 — Choose components
 
 Infer from context; ask only if ambiguous. [`standard.md`](./standard.md) has the component table and
-the layout they go in; `governance show plugin-design` decides which component a given need calls
+the layout they go in; the `plugin-design` reference decides which component a given need calls
 for. The universal minimum is `skills/<name>/SKILL.md` plus `.mcp.json`.
 
 ## Step 4 — Scaffold

package/skills/init-universal-plugin/references/standard.md

@@ -80,7 +80,7 @@ directories. Create the rest only when the plugin has content for them.
 
 The universal minimum — reaching every runtime with no vendor manifest at all — is
 `skills/<name>/SKILL.md` plus `.mcp.json`. Reach for a narrower component only when the plugin needs
-what only that component does; `governance show plugin-design` is the authority on that choice.
+what only that component does; the `plugin-design` reference is the authority on that choice.
 
 ## Constraints
 

package/skills/init-universal-plugin/references/vendors/cursor.md

@@ -34,7 +34,7 @@ into the shared `SKILL.md`.
 
 `rules/<name>.mdc` reaches Cursor and nothing else. Reach for a rule only when the plugin genuinely
 needs always-on guidance in Cursor; anything a task can load on demand belongs in a skill, where every
-runtime sees it. `governance show plugin-design` is the authority on that call.
+runtime sees it. The `plugin-design` reference is the authority on that call.
 
 `.mdc` and `.md` are not interchangeable, and path-scoping has no equivalent in the other runtimes —
 never generate rules from a skill or a skill from a rule.

package/skills/marketplace/README.md

@@ -1,15 +1,26 @@
 # marketplace skill
 
-Make a repository installable on its own terms: generate the marketplace catalogs the runtimes read,
-then write the README section that tells users what to type.
+Run a repository's own plugin marketplace: generate the catalogs the runtimes read, list plugins
+that live elsewhere, and check that what is on disk is what each runtime will load.
 
-## What it does
+## A gateway over three routes
 
-`marketplace init` discovers the plugins under `plugins/` and derives one catalog per selected
-runtime. This skill picks the targets with the user, runs the generation, validates every catalog
-against the schema its runtime loads, and offers the install documentation that goes with it.
+`SKILL.md` holds no procedure. It classifies the request and loads one reference:
 
-Nothing is published. The catalogs sit in the repository until someone adds it as a marketplace.
+| Route | Covers | Reference |
+| --- | --- | --- |
+| `init` | The repository holds the plugins. Derive a catalog from `plugins/`, then offer the README install section. | `references/init.md` |
+| `add` | The plugin lives elsewhere — an npm package, a GitHub repo, or `<plugin>@<marketplace>`. | `references/add.md` |
+| `validate` | Check the catalogs against the schema each runtime loads. Both other routes end here. | `references/validate.md` |
+
+The split exists because the two writing routes answer different questions and share almost no
+steps. A single document had to hedge every instruction with "unless the plugin is not in this
+repository", and the `add` half did not exist at all.
+
+`init` and `add` compose on one repository. A regeneration keeps the entries `add` wrote, because
+discovery could never have produced them — and keeps a non-local source on a plugin it *does*
+discover, so a plugin shipped through npm is not rewritten to a repository path holding gitignored
+build output.
 
 ## Support is uneven, and the skill says so
 
@@ -25,6 +36,10 @@ evidence ID. That constraint exists because the obvious way to write an install
 one from another project's README, and two of the four commands in the README that prompted this
 skill are not in any vendor documentation.
 
+The unevenness reaches `add` as well: only a repository path installs everywhere. An npm source
+reaches Claude Code and Codex, and the other two are reported skipped rather than written a source
+they refuse.
+
 ## The validation half
 
 `scripts/validate.mjs` checks each catalog against the shape its runtime actually loads and names the
@@ -45,6 +60,7 @@ document.
 ## References
 
 - [Research: local marketplaces](https://github.com/cyberuni/universal-plugin/blob/main/.research/local-marketplaces/conclusion.md)
+- [`marketplace add` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/add/README.md)
 - [`marketplace init` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/init/README.md)
 - [`marketplace validate` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/validate/README.md)
 - [Official Claude Code marketplace schema](https://json.schemastore.org/claude-code-marketplace.json)