universal-plugin 0.3.1 → 0.5.0

package/skills/{plugin/references/version.md → version/SKILL.md}

@@ -1,4 +1,9 @@
-# Move a universal plugin's version
+---
+name: version
+description: Use this skill to move a universal agent plugin's version — bump it, set an explicit one, cut a release number, or reconcile a version that drifted between the canonical plugin.json and its npm package.json. Handles both release models: a changesets repository, where the number is decided by the release and carried in with publish sync-version, and a plain repository, where plugin version does the whole move. Trigger on "bump the plugin version", "release a new version of this plugin", "set the plugin version to 1.0.0", "cut a patch release", or "the manifest and package.json versions disagree".
+---
+
+# Move a plugin's version
 
 Bump or set the version a plugin releases under, keeping every file that carries one in sync.
 
@@ -31,9 +36,13 @@ to decide again.
 ## Step 1 — Move the version
 
 ```bash
-npx universal-plugin plugin version <bump>
+node scripts/version.mjs <bump>
 ```
 
+Resolve that path against this skill's own directory; it runs the CLI that shipped beside it, so
+nothing is downloaded. `npx universal-plugin plugin version <bump>` is the fallback. The command
+never prompts, so it is safe to run unattended once the release type is decided.
+
 `<bump>` is either a semver release type or an explicit version:
 
 | `<bump>` | From `1.2.3` you get |
@@ -66,9 +75,12 @@ manifest, the `packagePath` `package.json` if one is declared, and one derived m
 harness:
 
 ```bash
-npx universal-plugin plugin version patch --format json
+node scripts/version.mjs patch --format json
 ```
 
+Default stdout is TOON, which is the machine contract this CLI documents; `--format json` is there
+for non-LLM consumers. Either way, read the reported files rather than re-deriving what moved.
+
 If the plugin declares no harnesses, only the authored files are written — that is correct, not a
 failure.
 
@@ -78,7 +90,7 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 
 | 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) |
+| a missing `plugin.json` | not at a plugin root, or the plugin was never scaffolded | `cd` to the plugin root, or run `/universal-plugin:init` |
 | 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 |
@@ -92,6 +104,16 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 - **Run `npm version`.** It knows only `package.json` and leaves the canonical manifest — the actual
   source of truth — stale.
 
+## Related skills
+
+| Task | Skill |
+|------|-------|
+| Create, adopt, or change what the plugin declares | `init` |
+| Check whether the two authored versions agree | `doctor` |
+| Add a changeset for the change being released | `add-changeset` |
+| Refresh the repository's own marketplace catalogs after a bump | `marketplace` |
+| List the released plugin in the shared marketplace | `publish-plugin` |
+
 ## References
 
-- Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/version/README.md
+- Spec: [`plugin/version/`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/version/README.md)

package/skills/version/scripts/version.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Runs `universal-plugin plugin version` from the CLI that ships beside this skill, so a release
+// number never depends on a network fetch or on which version `npx` happens to resolve.
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// <package>/skills/<skill>/scripts/version.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+
+process.argv.splice(2, 0, 'plugin', 'version')
+await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))

package/skills/plugin/README.md

@@ -1,37 +0,0 @@
-# plugin skill
-
-A skill for creating, inspecting, updating, and deleting universal AI coding agent plugins that target multiple runtimes from a single source of truth.
-
-## Supported runtimes
-
-| Vendor      | Manifest path                |
-| ----------- | ---------------------------- |
-| Claude Code | `.claude-plugin/plugin.json` |
-| Cursor      | `.cursor-plugin/plugin.json` |
-| Codex       | `.codex-plugin/plugin.json`  |
-| Copilot CLI | root `plugin.json` (the canonical manifest; nothing derived) |
-
-Universal minimum (no vendor manifest needed): `skills/<name>/SKILL.md` or `.mcp.json`. The canonical source of truth is root `plugin.json`.
-
-## Operations
-
-`SKILL.md` is a gateway: it detects what the project already contains, then routes to one operation
-reference and only that one gets read.
-
-| Operation | Reference | What it covers |
-| --------- | --------- | -------------- |
-| Create | [`references/create.md`](./references/create.md) | scaffold a new plugin with chosen vendors and components |
-| Adopt | [`references/adopt.md`](./references/adopt.md) | put an existing vendor-specific plugin, or already-shipped skills, onto the open standard |
-| Inspect | [`references/inspect.md`](./references/inspect.md) | show build status for each declared vendor |
-| Update | [`references/update.md`](./references/update.md) | add/remove vendors or components |
-| Delete | [`references/delete.md`](./references/delete.md) | remove generated manifests or the whole plugin |
-
-On invocation the gateway checks for existing vendor manifests and publicly-shipped skills, and
-offers adoption when it finds either without a canonical `plugin.json`. Repo-private agent config
-(`.claude/skills/`, `.agents/skills/`) is deliberately excluded — it is not something to package.
-
-## References
-
-- [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
-- [Schema](https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json)
-- [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/plugin/SKILL.md

@@ -1,105 +0,0 @@
----
-name: plugin
-description: Use this skill when creating, inspecting, updating, versioning, or deleting a universal agent plugin that targets multiple AI coding agent runtimes — Claude Code, Cursor, Codex, GitHub Copilot CLI. Also use it to convert a vendor-specific plugin, or a project that already ships skills, onto the open Agent Plugins Specification, or to move a plugin's version — for asks like "make my Claude Code plugin work in Cursor", "convert this to the open plugin standard", "turn these skills into a plugin", "bump my plugin's version", "release a new version of this plugin", or "set the plugin version to 1.0.0".
----
-
-# Universal Plugin
-
-Gateway skill. Identify which operation the user wants, load that operation's reference, and follow
-it.
-
-## When to use
-
-When the user wants to create, inspect, update, version, or delete a plugin targeting Claude Code,
-Cursor, Codex, and/or GitHub Copilot CLI from a single source of truth.
-
-## Prerequisites
-
-Load governance before starting any operation:
-
-```bash
-npx universal-plugin governance show plugin-design
-```
-
-Until the CLI is available, read `governances/plugin-design.md` from this plugin's installation
-directory. It is the authoritative source for component selection rules and anti-patterns.
-
-## Step 0 — Detect what is already here
-
-Run this before routing. What the project already contains often changes which operation is
-actually right — a "create a plugin" request in a repo that already ships skills is an *adopt*, not
-a create.
-
-```bash
-ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
-test -f plugin.json && head -20 plugin.json
-find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
-```
-
-Read the signals:
-
-| What you find | What it means | Do this |
-|---------------|---------------|---------|
-| Root `plugin.json` with `$schema` on `agent-plugins.org` **and** an `extensions` object | Already on the open standard | Nothing to offer — route normally |
-| A vendor manifest (`.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`) with **no** canonical root `plugin.json` | A vendor-specific plugin | **Offer to adopt** |
-| Root `plugin.json` with no `$schema`/`extensions` | Legacy single-vendor manifest | **Offer to adopt** |
-| Public skills (see below) and no plugin manifest at all | Skills shipped without a plugin | **Offer to adopt** |
-| None of the above | Greenfield | Route normally |
-
-### Which skills count as public
-
-Only offer on skills the project **distributes**. Repo-local agent configuration is not a plugin,
-and offering to package it is wrong.
-
-| Location | Public? |
-|----------|---------|
-| `skills/<name>/SKILL.md` at the repo root | Yes |
-| `<package>/skills/<name>/SKILL.md` where `package.json` `files` ships it | Yes |
-| `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | **No** — repo-private tooling |
-
-If the only skills are in private locations, say nothing about adoption.
-
-### Making the offer
-
-State what you found, what adoption would give them, and let them decline:
-
-> This repo has a Claude Code plugin manifest but no canonical `plugin.json`. I can convert it to
-> the open Agent Plugins Specification, which would let one manifest drive Cursor, Codex, and
-> Copilot CLI too — Claude Code keeps working exactly as it does now. Want me to?
-
-Offer once. If the user declines, or their request is already a specific unrelated operation
-(deleting manifests, inspecting status), drop it and do what they asked.
-
-## Route
-
-Read exactly the reference for the operation at hand — do not load all six.
-
-| The user wants to… | Reference |
-|--------------------|-----------|
-| Scaffold a new plugin, add vendors/components to a fresh one, or build vendor manifests | [`references/create.md`](./references/create.md) |
-| Put an existing vendor-specific plugin, or already-shipped skills, onto the open standard | [`references/adopt.md`](./references/adopt.md) |
-| See what a plugin declares and which vendor manifests are built or stale | [`references/inspect.md`](./references/inspect.md) |
-| Add or remove a vendor, or add or remove a component, on an existing plugin | [`references/update.md`](./references/update.md) |
-| Bump or set the plugin's version, or cut a release of it | [`references/version.md`](./references/version.md) |
-| Remove generated manifests, or remove the whole plugin | [`references/delete.md`](./references/delete.md) |
-
-If the request spans more than one operation (for example "add Codex and rebuild"), load each
-reference in turn as you reach that part of the work.
-
-If the operation is unclear, ask which the user means rather than guessing.
-
-## Related skills
-
-| Task | Skill |
-|------|-------|
-| Move a repo-root plugin into its npm package | `migrate-plugin` |
-| Publish a packaged plugin to the marketplace | `publish-plugin` |
-| Bump the pinned `universal-plugin@<version>` the project *calls* (not the plugin's own version) | `upgrade-plugin` |
-| Rewrite `npx` pins to the `upx` runner | `adopt-upx` |
-
-## References
-
-- Governance: `npx cyberplace governance show plugin-design`
-- Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
-- Schema: https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json
-- Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples

package/skills/plugin/references/create.md

@@ -1,163 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
-# 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.