universal-plugin 0.4.0 → 0.6.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.4.0",
+  "version": "0.6.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -44,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/semver": "^7.7.1",
+    "ajv": "^8.20.0",
     "knip": "^6.14.1",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",

package/plugin.json

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

@@ -37,6 +37,8 @@ Author the canonical manifest and derive everything from it.
 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
 ```
@@ -45,6 +47,11 @@ npx universal-plugin plugin bundle               # pin skill npx references to w
 `.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.
+
 Each command writes JSON with `JSON.stringify`. Your repository decides how JSON looks, so run your
 formatter after any command that writes a manifest.
 
@@ -72,8 +79,12 @@ keep their previous version.
 
 ```sh
 npx universal-plugin marketplace init --codex --root .
+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.
+
 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

package/skills/doctor/README.md

@@ -7,8 +7,10 @@ disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
 
 `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, and whether the two
-authored version numbers still agree. It emits one JSON object: `vendors`, `findings`, `ok`.
+the canonical manifest, whether a stale or shadowing manifest is lying around, whether the two
+authored version numbers still agree, whether shipped content has moved since the version did, and
+whether every marketplace catalog at the repository root is a shape its runtime loads. It emits one
+JSON object: `vendors`, `findings`, `ok`.
 
 The skill supplies the judgment around it: which finding matters, and which skill owns its repair.
 

package/skills/doctor/SKILL.md

@@ -70,11 +70,23 @@ Each `code` below is what the script emits.
 | `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 |
+| `invalid-catalog` | a marketplace catalog at the repository root is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
+
+## Catalogs are checked at the repository root
+
+The marketplace catalogs sit above the plugin in a monorepo, so the catalog check runs against the
+repository root rather than `--root`. It reports only a catalog that would be **refused**: a missing
+one is not a fault, and nothing here has an opinion on which catalogs a repository ought to carry.
+
+The detail names the key at fault, so hand it to `/universal-plugin:marketplace` as it stands. An
+entry's fields are derived from the plugin's `plugin.json`, and the catalog's own `name` and `owner`
+are authored in the catalog — which half is at fault decides where the repair goes.
 
 ## Checking staleness properly
 
@@ -104,6 +116,25 @@ They diverge when someone ran `npm version`, or when changesets released a numbe
 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.
@@ -120,4 +151,5 @@ other.
 | Create, adopt, or change what the plugin declares | `init` |
 | Move the plugin's version | `version` |
 | Remove derived manifests, or the plugin itself | `remove-plugin` |
-| Publish it to a marketplace | `publish-plugin` |
+| Generate the repository's own marketplace catalogs | `marketplace` |
+| Publish it to the shared marketplace repository | `publish-plugin` |

package/skills/doctor/scripts/doctor.mjs

@@ -51,6 +51,12 @@ if (manifest === null) {
 }
 
 const ext = manifest.extensions?.[UP_NAMESPACE] ?? null
+
+// `packagePath` is the CLI's own config, and the CLI reads it from `.agents/universal-plugin.json`
+// (src/version/fs.ts). It is read here from the same file, so a plugin the CLI treats as npm-shipping
+// is one this script treats the same way. The manifest extension is accepted as a fallback for a
+// repository that put it there.
+const packagePath = readPackagePath()
 if (!manifest.$schema?.includes('agent-plugins.org') || ext === null) {
 	add(
 		'legacy-manifest',
@@ -148,28 +154,120 @@ if (build === null) {
 }
 
 // Version drift between the two authored numbers.
-if (ext?.packagePath) {
-	const pkgPath = path.join(root, ext.packagePath, 'package.json')
+if (packagePath !== null) {
+	const pkgPath = path.join(root, packagePath, 'package.json')
 	const pkg = readJson(pkgPath)
 	if (pkg === null) {
 		add(
 			'package-path-missing',
 			'medium',
-			`packagePath names ${ext.packagePath}, which holds no readable package.json`,
+			`packagePath names ${packagePath}, which holds no readable package.json`,
 			'fix packagePath, or create the package',
 		)
 	} else if (manifest.version !== undefined && pkg.version !== manifest.version) {
 		add(
 			'version-drift',
 			'high',
-			`plugin.json is ${manifest.version}, ${ext.packagePath}/package.json is ${pkg.version}`,
+			`plugin.json is ${manifest.version}, ${packagePath}/package.json is ${pkg.version}`,
 			'/universal-plugin:version',
 		)
 	}
 }
 
+// Content shipped since the version last moved (ADR-0010 §6). A runtime keys its plugin cache on the
+// version, so anything committed after the commit that set the current one is invisible to a consumer
+// who already installed the plugin. Read-only: the comparison is git's, and it is skipped wherever
+// git cannot answer.
+//
+// Not run where the release picks the number. ADR-0010 §2 makes `packagePath` the switch: a plugin
+// that ships to npm gets its version from the release, so content sitting ahead of the last released
+// one is the normal state there, not a defect. Only the author-picks model can forget the bump.
+if (manifest.version !== undefined && packagePath === null) {
+	const introduced = commitThatSetVersion(manifest.version)
+	if (introduced !== null) {
+		const changed = git('diff', '--name-only', `${introduced}..HEAD`, '--', ...shippedPaths())
+		const files = (changed ?? '').split('\n').filter(Boolean)
+		if (files.length > 0) {
+			const sample = files.slice(0, 3).join(', ')
+			add(
+				'unreleased-content',
+				'medium',
+				`${files.length} shipped file(s) changed since ${manifest.version} was set (${sample}${files.length > 3 ? ', …' : ''}) — a consumer keyed on that version never re-extracts them`,
+				'/universal-plugin:version',
+			)
+		}
+	}
+}
+
+// The marketplace catalogs a user installs from. They sit at the *repository* root, above a plugin in
+// a monorepo, and each is read by its runtime at install time — a catalog whose shape that runtime
+// refuses fails in the user's terminal, not here. The shipped CLI owns the rules; this only asks.
+for (const row of invalidCatalogs()) {
+	add(
+		'invalid-catalog',
+		'high',
+		`${row.path} is not a shape its runtime loads: ${row.issues.map((issue) => `${issue.path} ${issue.message}`).join('; ')}`,
+		'/universal-plugin:marketplace',
+	)
+}
+
 report({ vendors })
 
+/** Every catalog the repository carries that its runtime would refuse. Empty when there is nothing to
+ *  read, when the CLI is too old to answer, or when every catalog is fine — a missing catalog is not a
+ *  fault, and this reports no opinion on which ones a repository ought to carry. */
+function invalidCatalogs() {
+	const catalogRoot = git('rev-parse', '--show-toplevel') ?? root
+	const result = fs.existsSync(bin)
+		? spawnSync(process.execPath, [bin, 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
+				encoding: 'utf8',
+			})
+		: spawnSync('npx', ['universal-plugin', 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
+				encoding: 'utf8',
+			})
+	const rows = readJson_stdout(result.stdout)
+	return Array.isArray(rows) ? rows.filter((row) => row.status === 'invalid') : []
+}
+
+/** Runs git inside `root`, returning its stdout or `null` — a non-zero status, a missing git, and a
+ *  directory outside any repository are all the same answer here: no history to read. */
+function git(...args) {
+	const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+	return result.status === 0 ? result.stdout.trim() : null
+}
+
+/** The commit that introduced the version the manifest carries now, walking `plugin.json`'s history
+ *  newest-first until the version changes. `null` when there is no history, or when the newest
+ *  committed manifest already disagrees — that version is uncommitted, so nothing shipped under it. */
+function commitThatSetVersion(current) {
+	const log = git('log', '--format=%H', '-100', '--', 'plugin.json')
+	if (log === null || log === '') return null
+
+	let introduced = null
+	for (const sha of log.split('\n').filter(Boolean)) {
+		const blob = git('show', `${sha}:./plugin.json`)
+		if (blob === null) break
+		let version
+		try {
+			version = JSON.parse(blob).version
+		} catch {
+			break
+		}
+		if (version !== current) break
+		introduced = sha
+	}
+	return introduced
+}
+
+/** What a consumer installs, as pathspecs. The derived vendor manifests are deliberately absent —
+ *  they only ever change because the canonical manifest did, and counting both would report one
+ *  change twice. */
+function shippedPaths() {
+	const skills = typeof ext?.skills === 'string' ? ext.skills : './skills/'
+	const paths = ['plugin.json', skills, 'agents', 'governances', 'mcp.json']
+	return paths.filter((rel) => fs.existsSync(path.join(root, rel)))
+}
+
 function readJson_stdout(stdout) {
 	if (!stdout) return null
 	try {
@@ -194,3 +292,10 @@ function report({ vendors }) {
 	}
 	process.exit(0)
 }
+
+/** Where the npm package that ships this plugin lives, or `null` when the plugin ships to no
+ *  package. `null` is the author-picks release model of ADR-0010 §2. */
+function readPackagePath() {
+	const declared = readJson(path.join(root, '.agents', 'universal-plugin.json'))?.packagePath ?? ext?.packagePath
+	return typeof declared === 'string' && declared.length > 0 ? declared : null
+}

package/skills/init/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init
 description: Use this skill to create or change a universal agent plugin — scaffold a new one, adopt an existing vendor-specific plugin or already-shipped skills onto the open Agent Plugins Specification, or add and remove vendors and components on the canonical plugin.json that drives Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "init a plugin here", "make my Claude Code plugin work in Cursor", "convert this to the open plugin standard", "turn these skills into a plugin", "add Codex support", or "add a hooks component".
-argument-hint: '[--name <name>] [--vendor <id>] [--scaffold] [--npm] [--force]'
+argument-hint: '[--name <name>] [--vendor <id>] [--scaffold] [--npm] [--no-marketplace] [--force]'
 ---
 
 # Plugin Init
@@ -133,6 +133,23 @@ Then derive the vendor manifests:
 npx universal-plugin plugin build
 ```
 
+To try the result before publishing, `npx universal-plugin plugin install` puts the working copy
+into every runtime the manifest declares and names the reload each one needs. Never hand-write a
+symlink for this — `references/create.md` records why the recipe that circulated for it does not
+work.
+
+With `--vendor`, `plugin init` also registers the plugin in the repository's local marketplace: it
+writes each selected vendor's catalog at the **repository** root and folds an entry for this plugin
+into it, so users can add the repository as a marketplace and install from it. Say what it wrote,
+and read back any line it printed on stderr — a repository with no author, no package author, and no
+remote gets no catalog, because every runtime requires an owner. `--no-marketplace` skips the step.
+
+The catalog is named after the repository, `<owner>-<repo>-local`, not after the plugin: it lists
+every plugin the repository develops. Re-running `init` folds the entry back in and leaves the
+marketplace name, the owner, and every other entry alone, so it is safe over a catalog someone
+edited. Generating catalogs for a repository that already holds several plugins, and writing the
+README install section, is the `marketplace` skill's job.
+
 `plugin init` writes a **minimal** manifest — `$schema`, `name`, and the vendor list. It never reads
 an existing vendor manifest, so shared metadata and per-vendor overrides are carried in by hand
 afterwards, per the reference you routed to.
@@ -172,9 +189,10 @@ This skill is not a formatter. If the project has one, run it over the written f
   the Phase 5 diff is the check that proves it.
 - **Do not package repo-private agent configuration.** A `.claude/skills/` directory is the project's
   own tooling; offering to publish it is wrong.
-- **Do not convert vendor settings without a documented mapping.** Hook event names diverge by case
-  across runtimes and the build does not translate them today — see
-  `references/vendors/claude-code.md`. Unmapped settings stay where they are, reported.
+- **Do not convert vendor settings without a documented mapping.** Hooks have one: author them in
+  canonical PascalCase and `plugin build` derives each vendor's form, dropping handler types a vendor
+  cannot run — see `references/vendors/claude-code.md`. Unmapped settings stay where they are,
+  reported.
 - **Offer adoption once.** If the user declines, or asked for something unrelated, drop it and do
   what they asked.
 - Plugin authoring only. Do not change CI workflows, repository settings, or unrelated project files.
@@ -184,6 +202,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 | Task | Skill |
 |------|-------|
 | Diagnose a plugin — what is declared, built, stale, or drifting | `doctor` |
+| Make the repository installable, and document how | `marketplace` |
 | Move the plugin's version, or reconcile one that drifted | `version` |
 | Delete derived manifests, or the whole plugin | `remove-plugin` |
 | Move a repo-root plugin into its npm package | `migrate-plugin` |

package/skills/init/references/create.md

@@ -101,10 +101,21 @@ write all surface there rather than as errors.
 ## Step 8 — Install locally to test
 
 ```bash
-ln -sf "$(pwd)" ~/.claude/plugins/local/<plugin-name>   # Claude Code
-ln -sf "$(pwd)" ~/.cursor/plugins/local/<plugin-name>   # Cursor → Developer: Reload Window
+npx universal-plugin plugin install
 ```
 
+It installs into every runtime the manifest declares, linking where the runtime follows a symlink
+out of the tree and copying where it does not, and it prints the reload each one now needs — a
+restart for Claude Code, **Developer: Reload Window** for Cursor. `--list` shows where it would go
+without writing; `--vendor <id>` narrows it; `plugin uninstall` removes it again.
+
+Codex and Copilot CLI scan no local plugin directory, so they report as `unsupported`. Reach those
+through a repository-local marketplace — `publish-plugin`.
+
+Do not hand-write a symlink for this. The recipe that circulated for it named
+`~/.claude/plugins/local/`, which does not exist, and a symlink into Cursor's local directory is
+rejected by Cursor's own scan.
+
 ## Next
 
 Shipping it on npm → `migrate-plugin`. Listing it in a marketplace → `publish-plugin`. Releasing a

package/skills/init/references/standard.md

@@ -38,6 +38,7 @@ lives under one namespaced key, `extensions["org.cyberuni.universal-plugin"]`:
 | `harnesses` | per-vendor overrides, keyed by vendor id. `{}` opts in with no overrides |
 | `packagePath` | the npm package whose `package.json` carries the same version |
 | component paths (`skills`, `commands`, `agents`, `hooks`, …) | where each component lives |
+| `dependencies` | the plugins this plugin needs. Only Claude Code reads them; see [`vendors/claude-code.md`](./vendors/claude-code.md) |
 
 `vendors` and `harnesses` are separate on purpose: `vendors` says what to build, `harnesses` says
 what each build gets. A vendor listed in `vendors` with no `harnesses` entry still builds; a
@@ -68,7 +69,7 @@ directories. Create the rest only when the plugin has content for them.
 | MCP servers | `mcpServers` | `.mcp.json` | every vendor |
 | Commands | `commands` | `commands/<name>.md` | Claude Code, Cursor, Copilot CLI |
 | Agents | `agents` | `agents/<name>.md` | Claude Code, Cursor, Copilot CLI |
-| Hooks | `hooks` | `hooks/hooks.json` | partial — event names differ by case, and the build does not translate them |
+| Hooks | `hooks` | `hooks/hooks.json` | every vendor — authored PascalCase, translated per vendor by the build; handler types vary |
 | LSP servers | `lspServers` | `.lsp.json` | Claude Code, Cursor |
 | Rules | `rules` | `rules/<name>.mdc` | Cursor only |
 | Output styles | `outputStyles` | `output-styles/` | Claude Code only |

package/skills/init/references/vendors/claude-code.md

@@ -27,16 +27,48 @@ true` for `user`, `user-invocable: false` for `model`. See [`../frontmatter.md`]
 
 ## Hooks
 
-Claude Code hook events are **PascalCase** (`SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`,
-`UserPromptSubmit`). Cursor and Copilot CLI use camelCase; Codex is PascalCase like Claude Code.
+Author hooks once, in canonical form: **PascalCase** event names (`SessionStart`, `PreToolUse`,
+`PostToolUse`, `Stop`, `UserPromptSubmit`) over Claude Code's matcher-group shape. That is what the
+canonical schema admits, and `plugin build` derives the rest (ADR-0011).
 
-**The build does not translate event names.** It copies the `hooks` path through to every derived
-manifest as declared, so one `hooks/hooks.json` cannot currently satisfy both casings. Author hooks
-for the runtimes that share a casing, and say plainly which runtimes a hooks block does not reach
-rather than implying portability the build does not deliver.
+Claude Code and Codex read that form as authored. Copilot CLI accepts it too — PascalCase selects its
+Claude-compatible payload format. Cursor is the one vendor translated: it gets
+`.cursor-plugin/hooks.json` with camelCase events, `"version": 1`, and each matcher group flattened
+into one entry per handler, and its derived manifest points there.
 
-Source: `.research/hook-event-survey/conclusion.md` (June 2026) — re-verify against vendor docs
-before relying on it.
+**A handler type the vendor cannot run is dropped, and the build warns.** Claude Code runs `command`,
+`http`, `prompt`, and `agent`; Codex runs `command` only; Cursor runs `command` and `prompt`; Copilot
+CLI runs `command`, `http`, and `prompt`. Read the warnings — a plugin whose only `SessionStart`
+handler is `http` reaches Claude Code and Copilot CLI and nothing else. Copilot CLI reads the
+canonical file directly, so its unsupported handlers are reported as ignored at runtime rather than
+dropped from a derived file.
+
+Source: `.research/hook-event-survey/conclusion.md` (re-verified August 2026) — re-verify against
+vendor docs before relying on it.
+
+## Dependencies
+
+Claude Code is the only runtime that reads a plugin dependency, and it acts on one: it installs a
+missing dependency, enables it alongside the plugin that needs it, prunes it once nothing needs it,
+and refuses to load a plugin whose declared range the installed version does not satisfy. Declare it
+once, canonically, under `extensions["org.cyberuni.universal-plugin"].dependencies` — not under
+`harnesses["claude-code"]` (ADR-0013):
+
+```json
+"dependencies": ["cyber-asana", { "name": "cyber-notion", "marketplace": "cyberuni", "version": "^0.9.0" }]
+```
+
+A bare name resolves against the declaring plugin's own marketplace; `marketplace` picks another one,
+which the root marketplace must have allowed. Put a range in the object form — a range written as
+`"cyber-asana@^0.9.0"` is accepted and then discarded by the runtime, and the build warns and names
+the object to write instead.
+
+Cursor, Codex, and Copilot CLI read no such field. The build leaves it out of their manifests and
+warns; the build stays green. A plugin that loads there without its dependency is worth a line in
+your README.
+
+Source: `.research/plugin-schema/` (re-verified August 2026 against Claude Code 2.1.235) — re-verify
+against vendor docs before relying on it.
 
 ## Leave alone
 

package/skills/init/references/vendors/codex.md

@@ -44,5 +44,13 @@ so it is not part of the plugin's tracked output and does not travel with a clon
 
 ## Hooks
 
-Codex hook events are **PascalCase**, like Claude Code's. The build does not translate event names —
-see [`claude-code.md`](./claude-code.md).
+Codex hook events are **PascalCase**, like Claude Code's, so the canonical file reaches Codex as
+authored. Codex runs `command` handlers only — an `http`, `prompt`, or `agent` handler is dropped
+from `.codex-plugin/hooks.json` with a warning. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Codex reads no plugin dependency. A declaration is left out of `.codex-plugin/plugin.json` with a
+build warning — deliberately, because the validator Codex ships for its plugin ingestion contract
+rejects any field outside its allowlist, and one unaccepted key fails the whole manifest. See
+[`claude-code.md`](./claude-code.md).

package/skills/init/references/vendors/copilot-cli.md

@@ -41,5 +41,13 @@ derived manifest, or it does not ship. Do not invent a path for it.
 
 ## Hooks
 
-Copilot CLI hook events are **camelCase**. The build does not translate event names — see
-[`claude-code.md`](./claude-code.md).
+Copilot CLI accepts **either casing**, and the casing selects the payload format: PascalCase gets the
+Claude-compatible format, so the canonical file reaches Copilot CLI unchanged. Because Copilot CLI
+reads that file directly, the build derives nothing for it — an `agent` handler is reported as ignored
+at runtime rather than dropped. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Copilot CLI reads no plugin dependency. Because it reads the canonical manifest directly, there is no
+derived file to leave the declaration out of — it sits under `extensions`, which Copilot CLI ignores,
+and the build reports it as ignored at runtime. See [`claude-code.md`](./claude-code.md).

package/skills/init/references/vendors/cursor.md

@@ -41,5 +41,12 @@ never generate rules from a skill or a skill from a rule.
 
 ## Hooks
 
-Cursor hook events are **camelCase** (`sessionStart`). The build does not translate event names — see
-[`claude-code.md`](./claude-code.md).
+Cursor hook events are **camelCase** (`sessionStart`), and Cursor's hooks file differs in shape as
+well as casing. The build derives `.cursor-plugin/hooks.json` from the canonical file — never author
+it by hand. Cursor runs `command` and `prompt` handlers; an `http` or `agent` handler is dropped with
+a warning. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Cursor reads no plugin dependency. A declaration is left out of `.cursor-plugin/plugin.json` with a
+build warning. See [`claude-code.md`](./claude-code.md).