universal-plugin 0.3.1 → 0.5.0

package/dist/data/vendors.json

@@ -6,6 +6,9 @@
 		"hookGlob": "~/.claude/plugins/universal-plugin/hooks/hooks.json",
 		"globalPluginDir": "~/.claude/plugins/",
 		"pluginRootSuffix": ".claude-plugin/plugin.json",
+		"localPluginDir": "~/.claude/skills/",
+		"localPluginLink": true,
+		"localReload": "restart Claude Code — it loads as <name>@skills-dir",
 		"installCommand": "claude plugin install {name}",
 		"removeCommand": "claude plugin remove {name}",
 		"updateCommand": "claude plugin update {name}@{version}"
@@ -17,6 +20,9 @@
 		"hookGlob": null,
 		"globalPluginDir": null,
 		"pluginRootSuffix": ".cursor-plugin/plugin.json",
+		"localPluginDir": "~/.cursor/plugins/local/",
+		"localPluginLink": false,
+		"localReload": "run Developer: Reload Window in Cursor",
 		"installCommand": null,
 		"removeCommand": null,
 		"updateCommand": null
@@ -28,6 +34,9 @@
 		"hookGlob": null,
 		"globalPluginDir": null,
 		"pluginRootSuffix": ".codex-plugin/plugin.json",
+		"localPluginDir": null,
+		"localPluginLink": false,
+		"localReload": null,
 		"installCommand": null,
 		"removeCommand": null,
 		"updateCommand": null
@@ -39,6 +48,9 @@
 		"hookGlob": null,
 		"globalPluginDir": null,
 		"pluginRootSuffix": "plugin.json",
+		"localPluginDir": null,
+		"localPluginLink": false,
+		"localReload": null,
 		"installCommand": null,
 		"removeCommand": null,
 		"updateCommand": null

package/dist/run.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import * as fsNode from "node:fs";
 import * as path from "node:path";
+import * as semver$1 from "semver";
 import { spawnSync } from "node:child_process";
-import * as semver from "semver";
 //#region src/run/fs.ts
 function readInstall(dir) {
 	try {
@@ -121,13 +121,13 @@ function parseSpec(spec) {
 /** A valid semver range drives local-first matching; a non-empty non-semver spec (`next`,
 *  `latest`) is a dist-tag that can't be matched against an installed `package.json` version. */
 function isSemverRange(range) {
-	return semver.validRange(range) !== null;
+	return semver$1.validRange(range) !== null;
 }
 /** Nearest-local → global, first install whose version satisfies `range`. `locals` must already be
 *  nearest-first. */
 function selectInstall(range, locals, globalInstall) {
-	for (const install of locals) if (semver.satisfies(install.version, range)) return install;
-	if (globalInstall && semver.satisfies(globalInstall.version, range)) return globalInstall;
+	for (const install of locals) if (semver$1.satisfies(install.version, range)) return install;
+	if (globalInstall && semver$1.satisfies(globalInstall.version, range)) return globalInstall;
 }
 /** Resolves the executable from a `package.json` `bin` field: a string bin, an object entry keyed
 *  by the package's unscoped name (even among several bins), or a single-entry object. A

package/governances/plugin-design.md

@@ -49,6 +49,9 @@ All component paths and build config live under `extensions["org.cyberuni.univer
 | `lspServers` | `.lsp.json` path | Extended | Claude Code only |
 | `outputStyles` | Output style resources directory | Extended | Claude Code only |
 
+One field under this namespace is not a component path: `dependencies`. See
+[Plugin Dependencies](#plugin-dependencies).
+
 A conformant host must support at least one core component (`skills` or `mcpServers`). Extended types are silently ignored on non-supporting hosts — do not rely on them for core plugin functionality.
 
 ### `extensions["org.cyberuni.universal-plugin"]` — `vendors` and `harnesses`
@@ -70,7 +73,7 @@ Vendor-specific extension fields:
 | `defaultEnabled` | ✓ (bool) | — | — | — |
 | `userConfig` | ✓ (prompted at enable) | — | — | — |
 | `channels` | ✓ | — | — | — |
-| `dependencies` | ✓ (inter-plugin) | — | — | — |
+| `dependencies` | ✓ (inter-plugin — declared canonically, see [Plugin Dependencies](#plugin-dependencies)) | — | — | — |
 | `themes` | ✓ | — | — | — |
 | `monitors` | ✓ | — | — | — |
 | `logo` | — | ✓ | — | — |
@@ -145,6 +148,44 @@ Build reads root `plugin.json`, applies the rules below, writes each vendor's ou
 | `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | adapt → camelCase, pass-through env |
 | `lspServers` | ✓ | **omit** | **omit** | **omit** |
 | `outputStyles` | ✓ | **omit** | **omit** | **omit** |
+| `dependencies` | ✓ | **drop + warn** | **drop + warn** | **drop + warn** |
+
+## Plugin Dependencies
+
+A plugin declares the plugins it needs under
+`extensions["org.cyberuni.universal-plugin"].dependencies`, once, whatever it targets. Claude Code is
+the only runtime that reads a dependency; build drops the declaration for the rest and warns
+(ADR-0013). The build stays green.
+
+```json
+{
+  "extensions": {
+    "org.cyberuni.universal-plugin": {
+      "dependencies": [
+        "cyber-asana",
+        { "name": "cyber-notion", "marketplace": "cyberuni", "version": "^0.9.0" }
+      ]
+    }
+  }
+}
+```
+
+An entry is a plugin name, optionally `@marketplace`-qualified, or an object carrying that name plus a
+constraint:
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `name` | string | Required. |
+| `marketplace` | string | Which marketplace to resolve `name` in. A bare name resolves against the declaring plugin's own marketplace. |
+| `version` | string | Semver range, checked against the installed plugin's version. |
+| `sha` | string | Commit sha to pin a git-sourced dependency to. |
+
+Write a range in the object form. `"cyber-asana@^0.9.0"` validates and the runtime then discards the
+range, so build warns and names the object to write instead. `"cyber-asana@>=1.0.0"` is not a legal
+name at all and fails the build, as does an npm-style object map.
+
+Build validates shape only. Whether a declared plugin exists is a question for a resolver, and
+resolving, fetching, and installing dependencies is out of scope (ADR-0013).
 
 ## Hook Event Name Mapping
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -25,6 +25,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "LICENSE",
     "bin",
     "dist",
     "governances",
@@ -36,6 +37,7 @@
     "agents"
   ],
   "dependencies": {
+    "@toon-format/toon": "^4.1.1",
     "commander": "^14.0.3",
     "semver": "^7.8.1"
   },

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.3.1",
+	"version": "0.5.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

@@ -1,87 +1,102 @@
 # universal-plugin
 
 [![npm version](https://img.shields.io/npm/v/universal-plugin.svg)](https://www.npmjs.com/package/universal-plugin)
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/universal-plugin.svg)](https://www.npmjs.com/package/universal-plugin)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cyberuni/universal-plugin/blob/main/LICENSE)
 
-Universal AI agent plugin build tool. Author one canonical plugin manifest (root `plugin.json`) and generate vendor-specific manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
-
-## Specification
-
-This package follows the [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec).
-Consult that repository's versioned specification and releases before changing manifest
-or component compatibility behavior; it is the canonical reference for the current standard.
+Write one canonical plugin manifest (root `plugin.json`). Generate the vendor manifests for Claude
+Code, Cursor, Codex, and GitHub Copilot CLI.
 
 ## Usage
 
-No install required — run with `npx`:
+No install required:
 
 ```sh
 npx universal-plugin <command>
 ```
 
-Or pin to an exact version for reproducible builds:
+Pin an exact version for reproducible builds:
 
 ```sh
-npx universal-plugin@0.2.0 <command>
+npx universal-plugin@0.3.1 <command>
 ```
 
-## upx — the fast package runner
-
-`npm i -g universal-plugin` also puts a second bin, `upx`, on PATH. `upx <pkg>@^<major>` finds an
-already-installed version satisfying the range (local `node_modules` first, then global) and runs
-it directly — about 10× faster than `npx`'s ~1s per-call resolve+spawn cost — falling back to
-`npx` when nothing installed matches:
-
-```sh
-npm i -g universal-plugin
-upx cyber-skills@^2 audit validate
-```
+## Specification
 
-Use a caret range on the major, not an exact pin, so one global install serves every caller. `upx`
-needs to be installed to be on PATH; `npx` always ships with npm, so `npx` remains the safe default
-where `universal-plugin` isn't installed globally.
+This package follows the [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec).
+That repository is the canonical reference. Consult its versioned specification and releases before
+you change manifest or component compatibility behavior.
 
 ## Commands
 
-### plugin — author the canonical manifest
+### plugin
+
+Author the canonical manifest and derive everything from it.
 
 ```sh
-# Generate vendor manifests from root plugin.json
-npx universal-plugin plugin build
+npx universal-plugin plugin init                 # scaffold plugin.json
+npx universal-plugin plugin init --npm           # also wire an npm package to ship it
+npx universal-plugin plugin build                # generate vendor manifests
+npx universal-plugin plugin install              # install the working copy into the runtimes it targets
+npx universal-plugin plugin uninstall            # take it back out
+npx universal-plugin plugin version <bump>       # move the version across every file carrying one
+npx universal-plugin plugin bundle               # pin skill npx references to workspace versions
 ```
 
-`validate` and `init` are specified but implementation is deferred.
+`build` writes `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and
+`.codex-plugin/plugin.json`. Copilot CLI reads the canonical root `plugin.json` directly, so no
+fourth file is derived.
+
+`install` puts the plugin you are editing into each runtime's local plugin directory, so you can use
+it before publishing anything. It links where the runtime follows a symlink out of the tree, copies
+where it does not, refuses a destination another plugin owns, and prints the reload each runtime now
+needs. Installing a *published* plugin by name stays the runtime's own job.
 
-### sync — cross-vendor plugin sync
+Each command writes JSON with `JSON.stringify`. Your repository decides how JSON looks, so run your
+formatter after any command that writes a manifest.
+
+### sync
+
+Move an installed plugin from the runtime that installed it to the others.
 
 ```sh
-# Detect cross-vendor sync actions from a vendor's manifest
 npx universal-plugin prepare <vendor-id>              # e.g. claude-code
 npx universal-plugin prepare <vendor-id> --scope project --root <path>
-npx universal-plugin prepare <vendor-id> --dry-run    # print action count without writing state
-
-# Apply a pending sync action
+npx universal-plugin prepare <vendor-id> --dry-run    # print the action count without writing state
 npx universal-plugin sync apply <action-id>
 ```
 
 ### publish
 
 ```sh
-# Sync version from packagePath/package.json into root plugin.json
-npx universal-plugin publish sync-version
+npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json
 ```
 
+This writes the canonical `plugin.json` only. Run `plugin build` afterwards, or the vendor manifests
+keep their previous version.
+
 ### marketplace
 
 ```sh
-# Generate a local Codex catalog from canonical plugin manifests.
 npx universal-plugin marketplace init --codex --root .
 ```
 
-Codex caches a local plugin install by its marketplace entry version. After changing packaged plugin
-files, update the canonical `plugin.json` version, regenerate the Codex catalog (use `--force` when
-replacing an existing catalog), reinstall the plugin, and start a new Codex session. This ensures the
-installed copy and its generated marketplace entry use the same version.
+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
+replace an existing one), reinstall the plugin, then start a new Codex session. The installed copy
+and its marketplace entry then carry the same version.
+
+### config
+
+Read and write plugin-registered config in `.agents/universal-plugin.json`.
+
+```sh
+npx universal-plugin config get --key sdd-plugins
+npx universal-plugin config add --key sdd-plugins --entry '{"name":"aces","handles":["agent evaluation"]}'
+```
+
+`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
 
@@ -99,6 +114,29 @@ npx universal-plugin clean                            # remove the asset store
 npx universal-plugin self-update <version>            # update the version pin in hook files
 ```
 
+## upx, the fast package runner
+
+`npm i -g universal-plugin` puts a second bin, `upx`, on PATH.
+
+`upx <pkg>@^<major>` looks for an already-installed version satisfying the range, checking local
+`node_modules` first and then global. It spawns that binary directly, skipping the resolve step that
+costs `npx` roughly 1s per call. When nothing installed matches, it falls back to `npx`.
+
+```sh
+npm i -g universal-plugin
+upx cyber-skills@^2 audit validate
+```
+
+Use a caret range on the major rather than an exact pin, so one global install serves every caller.
+
+`upx` only works once `universal-plugin` is installed globally. `npx` ships with npm, so keep `npx`
+as the default anywhere you cannot guarantee that install.
+
+## Related
+
+This package publishes a plugin. To set up the agent configuration of a repository you work in, use
+[`buddy-agent-harness`](https://github.com/repobuddy/buddy-agent-harness).
+
 ## License
 
-MIT
+[MIT](https://github.com/cyberuni/universal-plugin/blob/main/LICENSE)

package/skills/doctor/README.md

@@ -0,0 +1,42 @@
+# doctor skill
+
+Diagnose a universal agent plugin: what the canonical `plugin.json` declares, and whether what is on
+disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
+
+## What it does
+
+`scripts/doctor.mjs` composes the shipped CLI's `plugin build --dry-run --format json` with the
+filesystem facts that build cannot see — whether each derived manifest exists, whether it predates
+the canonical manifest, whether a stale or shadowing manifest is lying around, whether the two
+authored version numbers still agree, and whether shipped content has moved since the version did. It emits one JSON object: `vendors`, `findings`, `ok`.
+
+The skill supplies the judgment around it: which finding matters, and which skill owns its repair.
+
+## It never repairs
+
+Every finding names the skill that fixes it — `init` for anything that rewrites the manifest,
+`version` for the release number, `remove-plugin` for artifacts. A repair can overwrite a manifest
+the user maintains, and that judgment belongs to the skill that owns the write.
+
+The script is read-only and exits `0` whether or not it finds anything, so it is safe to run
+unattended, including from a session-start hook.
+
+## Why a script rather than a checklist
+
+The checks are deterministic: same tree, same findings. The one check that is not scriptable is the
+definitive staleness test — rebuild on a clean tree and read the diff — because it writes. The skill
+reports that one as a repair for the user to run.
+
+Manifest validation is chartered as a CLI capability (`plugin validate`, specified but not yet
+shipped). This script stays a thin composition on purpose, so it folds into that command rather than
+competing with it.
+
+## Boundaries
+
+Diagnoses the plugin a project ships. A repository's own agent wiring — `.agents/skills/`,
+`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor`.
+
+## References
+
+- [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
+- [`plugin build`](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/plugin/build/README.md)

package/skills/doctor/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: doctor
+description: Use this skill to diagnose a universal agent plugin — when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, when a build prints warnings nobody has read, or when checking whether what the canonical plugin.json declares still matches what is on disk for Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "is my plugin set up right", "why isn't my plugin loading", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
+---
+
+# Plugin Doctor
+
+Root `plugin.json` is the canonical manifest. Every other manifest a runtime reads is derived from
+it, and a derived manifest that is missing, stale, or hand-edited fails silently: the runtime loads
+what it finds, or loads nothing, and says nothing either way.
+
+This skill is **read-only**. It never repairs. Every finding names the skill that owns its repair —
+hand it over rather than fixing it here, because a repair can rewrite a manifest the user maintains
+and that judgment belongs to the skill that owns the write.
+
+## Diagnose
+
+```bash
+node scripts/doctor.mjs
+```
+
+Resolve that path against this skill's own directory. It runs the CLI that shipped beside it against
+the current working directory, so nothing is downloaded; add `--root <path>` to diagnose elsewhere.
+It never prompts and never writes, so it is safe to run unattended.
+
+Stdout is one JSON object — that is the contract to read, not the CLI's own terminal output:
+
+```json
+{
+  "root": "…",
+  "manifest": { "name": "my-plugin", "version": "1.0.0" },
+  "vendors": [{ "vendor": "claude-code", "path": ".claude-plugin/plugin.json", "status": "built", "exists": true, "stale": false }],
+  "findings": [{ "code": "unbuilt", "severity": "high", "detail": "…", "repair": "…" }],
+  "ok": false
+}
+```
+
+`findings` is empty and `ok` is `true` when everything resolves — say so outright rather than
+reporting an empty list. Exit status is `0` whether or not findings exist; a finding is a result, not
+a failure. Add `--verbose` for a human-readable summary on stderr.
+
+Read `vendors[].status` literally:
+
+| Status | Means |
+| --- | --- |
+| `built` | the build writes this vendor's manifest |
+| `canonical` | the vendor reads root `plugin.json`; **no file is written, and that is correct** |
+| `skipped` | an unknown vendor id — a typo in `vendors` |
+| `failed` | the write itself failed; the finding names why |
+
+`copilot-cli` reporting `canonical` with `exists: false` is a healthy plugin, not a missing build.
+Never report it as a fault.
+
+If `node` is unavailable, read `scripts/doctor.mjs` and apply the same checks by hand: it composes
+`universal-plugin plugin build --dry-run --format json` with filesystem facts that build cannot see.
+
+## Findings and their repairs
+
+Each `code` below is what the script emits.
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init` |
+| `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init`, adopt route |
+| `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init`, adopt route |
+| `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `universal-plugin plugin build` |
+| `stale` | a derived manifest older than `plugin.json` | `universal-plugin plugin build` |
+| `hand-edited` | a derived manifest that `build` would rewrite — the edit is already lost, it just has not been overwritten yet | move the field to the canonical manifest or to `harnesses.<vendor>`, then rebuild |
+| `unknown-vendor` | a `vendors` entry no build target matches; reported as `skipped` plus a warning | fix the id in `plugin.json` |
+| `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init`, update route — move them to a vendor that has a derived manifest, or drop them |
+| `codex-fields-missing` | Codex is targeted without `version` or `description`; the build fails and writes **nothing at all**, including for the other vendors | add both to the canonical top level |
+| `version-drift` | the `packagePath` `package.json` and the canonical manifest carry different versions | `/universal-plugin:version` |
+| `unreleased-content` | shipped content was committed after the commit that set the current version — a consumer keyed on that version never re-extracts it | `/universal-plugin:version` |
+| `stale-github-plugin` | a leftover `.github/plugin/plugin.json` from an older build — shadowed by root and no longer generated | `/universal-plugin:remove-plugin` |
+| `shadowing-manifest` | a `.plugin/plugin.json` exists — it outranks root in Copilot CLI's search order and silently shadows the canonical manifest | `/universal-plugin:remove-plugin` |
+| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin | `/universal-plugin:init`, update route |
+| `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
+| `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
+
+## Checking staleness properly
+
+The `stale` finding is an mtime comparison, which catches the common case and nothing more. It cannot
+see a hand-edit made after the last build. The definitive check is to rebuild on a clean tree and read
+the diff:
+
+```bash
+git status --short          # must be clean first, or the diff proves nothing
+npx universal-plugin plugin build
+git diff -- .claude-plugin .cursor-plugin .codex-plugin
+```
+
+An empty diff means the derived manifests match what the canonical manifest says. Any hunk is drift —
+either a stale build or a hand-edit that the rebuild has now discarded.
+
+That rebuild is a **write**, so it is not part of the diagnosis. Report the check as a repair the
+user can run, or ask before running it yourself.
+
+## Version drift
+
+Two files carry an authored version: the canonical `plugin.json`, and the `package.json` at
+`extensions["org.cyberuni.universal-plugin"].packagePath` when one is declared. The script compares
+them and emits `version-drift`.
+
+They diverge when someone ran `npm version`, or when changesets released a number that never flowed
+back. Both are `/universal-plugin:version`'s to fix — never patch one file by hand to match the
+other.
+
+## Unreleased content
+
+A runtime keys its plugin cache on the version, not on content: Claude Code resolves the version,
+finds it unchanged, and reports *"already at the latest version"* without re-extracting. So content
+pushed without a bump reaches nobody who already installed the plugin, and neither side is told
+([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
+emits `unreleased-content` for anything committed since. Uncommitted work is not reported; it has not
+shipped.
+
+Two cases are deliberately silent. A plugin that declares `packagePath` is skipped, because there the
+release picks the number (ADR-0010 §2) and content waiting ahead of the last released version is the
+normal state of a branch. A tree with no git history is skipped rather than guessed at.
+
+The repair is the bump, and it belongs to `/universal-plugin:version`. Judge first whether the change
+is meant to ship — content that is still being worked on is not a finding to act on.
+
+## Rules
+
+- **Never repair.** Report the finding and name the skill that owns it.
+- **Never hand-edit a derived manifest to make a finding go away.** The next build overwrites it and
+  the finding comes back.
+- Do not report `copilot-cli` writing no file as a fault. It reads the canonical manifest directly.
+- Do not treat repo-private agent configuration (`.claude/skills/`, `.agents/skills/`) as part of the
+  plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor`.
+
+## Related skills
+
+| Task | Skill |
+|------|-------|
+| Create, adopt, or change what the plugin declares | `init` |
+| Move the plugin's version | `version` |
+| Remove derived manifests, or the plugin itself | `remove-plugin` |
+| Generate the repository's own marketplace catalogs | `marketplace` |
+| Publish it to the shared marketplace repository | `publish-plugin` |