universal-plugin 0.2.1 → 0.3.0

package/skills/plugin/references/adopt.md

@@ -0,0 +1,114 @@
+# Adopt the open standard
+
+Convert something that is *already* a plugin — or already ships skills — onto the canonical
+Agent Plugins Specification manifest, without changing what it does.
+
+Two starting shapes land here:
+
+- **A vendor-specific plugin** — it has one or more hand-written vendor manifests
+  (`.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, …) and no canonical root
+  `plugin.json`.
+- **Bare public skills** — it ships `skills/<name>/SKILL.md` to users but has no plugin manifest of
+  any kind.
+
+Adoption is **lossless by contract**: every vendor that worked before must still work after. Step 6
+is the check that proves it — do not skip it.
+
+## Step 0 — Confirm the user wants this
+
+Adoption rewrites the project's manifest layout and turns hand-written vendor manifests into
+generated artifacts. Say that plainly and get agreement before touching files. If the user declines,
+route back to whatever they originally asked for.
+
+Also confirm the working tree is clean (`git status`). The Step 6 diff is worthless if uncommitted
+changes are mixed in.
+
+## Step 1 — Inventory what exists
+
+```bash
+ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
+test -f plugin.json && cat plugin.json
+find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
+ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/null
+```
+
+Record, for each vendor manifest found: its path, and every field it sets. You are about to
+reproduce all of it.
+
+**If a root `plugin.json` already exists**, read it before assuming anything. It is either the
+canonical manifest (has `$schema` pointing at `agent-plugins.org` and an `extensions` object — in
+which case there is nothing to adopt; route to `update.md` or `inspect.md` instead), or a legacy
+Copilot CLI manifest that now collides with the canonical path and must be folded in.
+
+## Step 2 — Sort every field into shared vs vendor-specific
+
+Build two buckets from the manifests you inventoried:
+
+- **Shared metadata** — `name`, `version`, `description`, `author`, `homepage`, `repository`,
+  `license`, `keywords`, and the component paths. These go at the canonical top level.
+- **Vendor-specific** — anything only one runtime understands (Cursor's `publisher`/`category`/
+  `tags`, Codex's `interface`, Copilot's `category`/`tags`). These go under
+  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`.
+
+Where two vendor manifests disagree on a shared field, **ask the user** which value is canonical
+rather than picking one. A silent choice here is a silent behavior change for one of their runtimes.
+
+## Step 3 — Write the canonical manifest
+
+Scaffold it, naming exactly the vendors you found in Step 1:
+
+```bash
+npx universal-plugin plugin init --name <name> --vendor claude-code --vendor cursor
+```
+
+> `plugin init` writes a **minimal** manifest — `$schema`, `name`, and the `vendors` list. It does
+> not read your existing vendor manifests. Carry the Step 2 buckets in by hand afterwards.
+
+Then fill in the shared metadata and `harnesses` as laid out in
+[`create.md`](./create.md) Step 5. Point the component paths at the directories that already exist —
+adoption must not move files.
+
+For the bare-public-skills case there is no metadata to carry over; supply `name`, `description`,
+and `version`, set `"skills": "./skills/"`, and choose vendors with the user (see
+[`create.md`](./create.md) Step 2).
+
+## Step 4 — Decide what happens to the old manifests
+
+The vendor manifests are now **build outputs**. They stay at the same paths, but they are
+regenerated rather than edited.
+
+- Commit them as-is first, so Step 6 has a baseline to diff against.
+- Tell the user they are generated from here on, and that hand-edits will be overwritten by
+  `plugin build`.
+- If the project has a legacy root `plugin.json` for Copilot CLI, that path is now the canonical
+  manifest — its derived Copilot output moves elsewhere. Check the vendor output table in
+  [`create.md`](./create.md) Step 2 for the current path.
+
+## Step 5 — Build
+
+```bash
+npx universal-plugin plugin build
+```
+
+## Step 6 — Prove it was lossless
+
+This is the point of the whole procedure.
+
+```bash
+git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+```
+
+Read every line of that diff. Expect only formatting and key-order churn.
+
+**Any field that disappeared is a regression**, not a cleanup. Trace it back: either it belongs in
+the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field the build
+does not yet support — in which case stop and tell the user rather than shipping a quiet
+capability loss.
+
+Then confirm the plugin still loads. See [`create.md`](./create.md) Step 8 for local install.
+
+## Step 7 — Hand off
+
+- Audit the skills: [`create.md`](./create.md) Step 6.
+- Shipping it on npm? → `migrate-plugin`.
+- Listing it in the marketplace? → `publish-plugin`.

package/skills/plugin/references/create.md

@@ -0,0 +1,163 @@
+# Create a universal plugin
+
+Scaffold a new plugin from a single canonical `plugin.json` and build one manifest per chosen
+vendor.
+
+## Step 1 — Gather plugin identity
+
+Ask if not provided. All fields map to the canonical root `plugin.json`.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | kebab-case, 1–64 chars, `a-z 0-9 - .` only |
+| `description` | Recommended | one sentence; Codex requires this |
+| `version` | If publishing | semver; Codex requires this |
+| `author.name` | Recommended | person or org name |
+| `homepage` | Optional | docs or landing page URL |
+| `repository` | Optional | source repo URL |
+| `license` | Optional | SPDX identifier e.g. `MIT` |
+| `keywords` | Optional | discovery tags; array of strings |
+
+## Step 2 — Choose vendor targets
+
+Ask the user which runtimes to support. Each chosen vendor becomes a key in
+`extensions["org.cyberuni.universal-plugin"].harnesses` — that is what drives the `build` output.
+Add the vendor's id to `extensions["org.cyberuni.universal-plugin"].vendors` too, so `build` knows
+to generate its manifest.
+
+| Vendor ID | Manifest read from | Hook event case | Required fields beyond `name` |
+|-----------|--------------------|-----------------|-------------------------------|
+| `claude-code` | `.claude-plugin/plugin.json` *(derived)* | PascalCase | none |
+| `cursor` | `.cursor-plugin/plugin.json` *(derived)* | camelCase | none |
+| `codex` | `.codex-plugin/plugin.json` *(derived)* | PascalCase | `version`, `description` |
+| `copilot-cli` | root `plugin.json` — **the canonical manifest itself** | camelCase | none |
+
+**Copilot CLI derives nothing.** It searches `.plugin/plugin.json` → `plugin.json` →
+`.github/plugin/plugin.json` → `.claude-plugin/plugin.json` and takes the *first* match, so root
+always wins; and it has read Open Plugin Spec v1 manifests since v1.0.74. `plugin build` reports it
+with status `canonical` and writes no file. A `harnesses["copilot-cli"]` override cannot be
+delivered — the canonical schema is closed to vendor-only fields — and the build warns if you set
+one.
+
+Universal minimum (no vendor manifest needed): `skills/<name>/SKILL.md` + `.mcp.json`.
+
+Default to all four if the user is unsure.
+
+## Step 3 — Choose components
+
+Infer from context; ask only if ambiguous. Apply rules from the `plugin-design` governance loaded
+in the gateway's Prerequisites.
+
+| Component | Field | Directory | Cross-vendor? |
+|-----------|-------|-----------|--------------|
+| Skills | `skills` | `skills/<name>/SKILL.md` | Yes — all |
+| Commands | `commands` | `commands/<name>.md` | Claude Code, Cursor, Copilot CLI |
+| Agents | `agents` | `agents/<name>.md` | Claude Code, Cursor, Copilot CLI |
+| MCP servers | `mcpServers` | `.mcp.json` | Yes — all |
+| Hooks | `hooks` | `hooks/hooks.json` | Partial — event names translated on build |
+| Rules | `rules` | `rules/<name>.mdc` | Cursor-only |
+| LSP servers | `lspServers` | `.lsp.json` | Claude Code, Cursor |
+| Output styles | `outputStyles` | `output-styles/` | Claude Code only |
+
+## Step 4 — Scaffold files
+
+Read the templates from `../assets/templates/` and fill in the placeholders:
+
+| File to create | Template |
+|----------------|----------|
+| `plugin.json` | `assets/templates/plugin.json` |
+| `skills/<name>/SKILL.md` | `assets/templates/skill.md` |
+| `commands/<name>.md` | `assets/templates/command.md` |
+| `agents/<name>.md` | `assets/templates/agent.md` |
+| `hooks/hooks.json` | `assets/templates/hooks.json` |
+| `commands/setup.md` (when `rules/` included) | `assets/templates/setup-command.md` |
+
+Directory layout:
+
+```
+<plugin-name>/
+├── plugin.json              ← canonical definition (source of truth)
+├── skills/<name>/SKILL.md
+├── commands/
+├── agents/
+├── rules/                  (only if always-on Cursor guidance requested)
+├── hooks/hooks.json
+├── .mcp.json
+└── README.md
+```
+
+## Step 5 — Populate extensions["org.cyberuni.universal-plugin"]
+
+In root `plugin.json`, under `extensions["org.cyberuni.universal-plugin"]`, add the chosen vendors
+to `vendors` and add a `harnesses` object with one entry per chosen vendor. An empty `{}` opts into
+that vendor's output with no vendor-specific fields.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "<plugin-name>",
+  "version": "1.0.0",
+  "description": "<description>",
+  "author": { "name": "<author>" },
+  "extensions": {
+    "org.cyberuni.universal-plugin": {
+      "vendors": ["claude-code", "cursor", "codex", "copilot-cli"],
+      "skills": "./skills/",
+      "harnesses": {
+        "claude-code": {},
+        "cursor": {
+          "publisher": "<org>",
+          "category": "<category>",
+          "tags": ["<tag>"]
+        },
+        "codex": {
+          "interface": {
+            "displayName": "<Human Name>",
+            "category": "<category>"
+          }
+        },
+        "copilot-cli": {
+          "category": "<category>",
+          "tags": ["<tag>"]
+        }
+      }
+    }
+  }
+}
+```
+
+See spec §3.3 for the full list of vendor-specific fields:
+https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
+
+## Step 6 — Audit skills
+
+Audit each skill via the aced **improve-skill** skill's mechanical `validate.mts` engine:
+
+```bash
+node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<skill-name>
+```
+
+Fix any CRITICAL findings. Then invoke the **audit-skill** skill for full review.
+
+## Step 7 — Build vendor manifests
+
+> **Note:** The `build` CLI is not yet available. Use the manual steps below.
+
+For each vendor in `extensions["org.cyberuni.universal-plugin"].vendors`:
+
+1. Copy canonical fields from root `plugin.json`
+2. Merge vendor-specific fields from `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`
+3. Drop fields not supported by that vendor (see spec §6.1)
+4. Translate hook event names (see spec §4.2)
+5. Translate `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` env vars (see spec §5)
+6. Write to the vendor output path (see the Step 2 table)
+
+See spec §7 for full build rules:
+https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
+
+## Step 8 — Install locally for testing
+
+```bash
+ln -sf "$(pwd)" ~/.claude/plugins/local/<plugin-name>   # Claude Code
+ln -sf "$(pwd)" ~/.cursor/plugins/local/<plugin-name>   # Cursor → Developer: Reload Window
+```

package/skills/plugin/references/delete.md

@@ -0,0 +1,23 @@
+# Delete a universal plugin
+
+## Remove generated manifests only (keep source)
+
+Delete each vendor's output file. Generated manifests are build artifacts — safe to delete and
+regenerate via [`create.md`](./create.md) Step 7.
+
+```bash
+rm -f .claude-plugin/plugin.json
+rm -f .cursor-plugin/plugin.json
+rm -f .codex-plugin/plugin.json
+```
+
+> **Never delete root `plugin.json`.** It is the canonical source of truth, not a build artifact —
+> and it is also what Copilot CLI reads, so removing it takes out both the source and the Copilot
+> target. `copilot-cli` has no generated manifest to clean.
+
+If the project has a stale `.github/plugin/plugin.json` from an older build, it is safe to delete —
+that path is shadowed by root and is no longer generated.
+
+## Remove the whole plugin
+
+Delete the plugin root directory. Confirm with the user before proceeding — this is irreversible.

package/skills/plugin/references/inspect.md

@@ -0,0 +1,21 @@
+# Inspect a universal plugin
+
+Show the current state of a plugin.
+
+1. Read root `plugin.json` — show `name`, `version`, declared vendors
+   (`extensions["org.cyberuni.universal-plugin"].vendors`).
+2. For each vendor, check whether the generated manifest exists at its output path.
+3. Report status: which vendors are built, which are missing or stale.
+
+Example output:
+
+```
+Plugin: my-plugin  v1.0.0
+Vendors declared: claude-code, cursor, codex, copilot-cli
+  claude-code   .claude-plugin/plugin.json   ✓ present
+  cursor        .cursor-plugin/plugin.json   ✓ present
+  codex         .codex-plugin/plugin.json    ✗ missing — run build
+  copilot-cli   plugin.json                  ✗ missing — run build
+```
+
+Vendor output paths are listed in [`create.md`](./create.md) Step 2.

package/skills/plugin/references/update.md

@@ -0,0 +1,26 @@
+# Update a universal plugin
+
+Change which vendors or components an existing plugin declares. Every path ends with a rebuild —
+see [`create.md`](./create.md) Step 7.
+
+## Add a vendor
+
+1. Add the vendor id to `extensions["org.cyberuni.universal-plugin"].vendors` in root
+   `plugin.json`, and add its key to `extensions["org.cyberuni.universal-plugin"].harnesses`.
+2. Populate vendor-specific fields (see spec §3.3).
+3. If the vendor requires extra fields (`codex`: `version`, `description`), ensure they are in the
+   canonical section.
+4. Rebuild for the new vendor.
+
+## Remove a vendor
+
+1. Remove the vendor id from `extensions["org.cyberuni.universal-plugin"].vendors` and its key from
+   `harnesses`.
+2. Delete the generated manifest at its output path.
+
+## Add or remove a component
+
+1. Add/remove the component field under `extensions["org.cyberuni.universal-plugin"]` in root
+   `plugin.json` (e.g. `"commands": "./commands/"`).
+2. Scaffold or delete the corresponding files.
+3. Rebuild to regenerate all vendor manifests.

package/skills/plugin/references/version.md

@@ -0,0 +1,97 @@
+# Move a universal plugin's version
+
+Bump or set the version a plugin releases under, keeping every file that carries one in sync.
+
+A plugin's version lives in up to five places, but only **two are authored** — the canonical root
+`plugin.json` and, when the project declares a `packagePath`, that `package.json`. The per-vendor
+manifests, the local marketplace catalogs, and the `npx`/`upx` pins inside `skills/**/SKILL.md` are
+all **derived**. So never hand-edit a version: editing one file leaves the other authored file and
+every derived artifact stale, and a consumer's plugin cache is keyed by version, so a content change
+without a matching bump is invisible to them.
+
+## Step 0 — Does this repo use changesets?
+
+```bash
+test -d .changeset && echo "changesets"
+```
+
+**If it does**, the version number is decided by changesets, not by you. Add a changeset and let the
+release run — the repo's `version` script should already call `publish sync-version`, which carries
+the released number from `package.json` into the canonical manifest:
+
+```bash
+npx universal-plugin publish sync-version
+```
+
+Do **not** run `plugin version` in a changesets repo — it would decide a number changesets is about
+to decide again.
+
+**If it does not**, `plugin version` is the whole release-number step. Continue below.
+
+## Step 1 — Move the version
+
+```bash
+npx universal-plugin plugin version <bump>
+```
+
+`<bump>` is either a semver release type or an explicit version:
+
+| `<bump>` | From `1.2.3` you get |
+|---|---|
+| `patch` | `1.2.4` |
+| `minor` | `1.3.0` |
+| `major` | `2.0.0` |
+| `prerelease --preid beta` | `1.2.4-beta.0` |
+| `2.0.0-rc.1` (explicit) | `2.0.0-rc.1` |
+
+Useful flags:
+
+| Flag | Effect |
+|---|---|
+| `--preid <id>` | Prerelease identifier for the `pre*` release types |
+| `--dry-run` | Print the plan, write nothing — run this first when unsure |
+| `--force` | Allow a target that does not advance on the current version |
+| `--no-build` | Skip re-deriving the vendor manifests (you will run `plugin build` yourself) |
+| `--format json` | Machine-readable result: `from`, `to`, `written` |
+
+**Which release type?** That is the user's call, not the command's and not yours to guess — a
+version is a promise to consumers about what broke. If the user has not said, ask, and offer the
+semver reading of the change: breaking → `major`, new behavior → `minor`, fix only → `patch` (on a
+`0.x` plugin, breaking → `minor` and everything else → `patch`).
+
+## Step 2 — Confirm what moved
+
+The command reports every file it wrote and every manifest it re-derived. Expect the canonical
+manifest, the `packagePath` `package.json` if one is declared, and one derived manifest per declared
+harness:
+
+```bash
+npx universal-plugin plugin version patch --format json
+```
+
+If the plugin declares no harnesses, only the authored files are written — that is correct, not a
+failure.
+
+## Guards
+
+Every guard resolves before the first write, so a failed run leaves the tree untouched.
+
+| Message names | What it means | Do this |
+|---|---|---|
+| a missing `plugin.json` | not at a plugin root, or the plugin was never scaffolded | `cd` to the plugin root, or see [`create.md`](./create.md) |
+| no version to bump from | the manifest has never carried a `version` | pass an explicit version (`plugin version 0.1.0`) to set the first one |
+| an unknown version or release type | the argument is neither a release type nor valid semver | use one of the values in the table above |
+| a target that does not advance | the requested version is not greater than the current one | pick a higher version, or pass `--force` if the user genuinely wants to move backward |
+| a missing `package.json` at `packagePath` | `.agents/universal-plugin.json` names a package directory that does not exist | fix `packagePath`, or create the package |
+
+## Do not
+
+- **Hand-edit a `version` field.** Two authored files and every derived artifact fall out of sync.
+- **Write a derived manifest.** `.claude-plugin/plugin.json` and its siblings belong to
+  `plugin build`; the bump already re-derived them.
+- **Run `npm version`.** It knows only `package.json` and leaves the canonical manifest — the actual
+  source of truth — stale.
+
+## References
+
+- Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/version/README.md