universal-plugin 0.6.0 → 0.8.0

package/skills/adopt-upx/README.md

@@ -6,13 +6,13 @@ Rewrites `npx <pkg>@<version>` references in `SKILL.md` files to a caret range o
 
 ## When to use
 
-When you want a project's skills to call CLIs via `upx` instead of `npx`, for the ~10× speed win
-on repeated invocations (local-first resolution vs. `npx`'s ~1s registry+spawn cost per call, even
+When you want a project's skills to call CLIs via `upx` instead of `npx`, for the speed win
+on repeated invocations (local-first resolution vs. `npx`'s registry+spawn cost per call, even
 cached).
 
 ## What it does
 
-1. Confirms `upx` is installed (`npm i -g universal-plugin`) and on PATH.
+1. Confirms `upx` is installed (`npm i -g @repobuddy/upx`) and on PATH.
 2. Rewrites `npx <pkg>@<concrete-semver>` → `upx <pkg>@^<major>` (or `^0.<minor>` for a 0.x pin)
    across a chosen scope:
    - one specific skill (a path)
@@ -29,7 +29,7 @@ cached).
 ## Tradeoff
 
 A rewritten skill depends on `upx` being on PATH. `npx` ships with every npm install; `upx` only
-exists after `npm i -g universal-plugin`. This is an opt-in migration, not a safe default.
+exists after `npm i -g @repobuddy/upx`. This is an opt-in migration, not a safe default.
 
 ## Install
 

package/skills/adopt-upx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adopt-upx
-description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped by universal-plugin. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
+description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped as @repobuddy/upx. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
 ---
 
 # Adopt upx
@@ -11,7 +11,7 @@ fast local-first runner shipped by `universal-plugin` (see the package
 
 ## When to use
 
-The user wants their project's skills to shell out via `upx` instead of `npx`, for the ~10× speed
+The user wants their project's skills to shell out via `upx` instead of `npx`, for the speed
 win on repeated calls. This is an opt-in migration, not a default — see Tradeoff below before
 running it broadly.
 
@@ -20,7 +20,7 @@ running it broadly.
 Install the runner:
 
 ```bash
-npm i -g universal-plugin
+npm i -g @repobuddy/upx
 ```
 
 This puts the `upx` bin on PATH. Verify:
@@ -94,7 +94,7 @@ a no-op (there's no `npx` left to match), so it's safe to run again after adding
 
 A skill rewritten to `upx` now depends on the `upx` bin being on that environment's PATH.
 `npx` always ships with npm — every Node environment has it. `upx` does not — it only exists after
-`npm i -g universal-plugin`. So this is a deliberate opt-in for environments where
+`npm i -g @repobuddy/upx`. So this is a deliberate opt-in for environments where
 `universal-plugin` is installed globally, not a safe-by-default swap.
 
 Mitigating factor: `upx` itself falls back to plain `npx` on a miss (no local/global install

package/skills/doctor/README.md

@@ -16,7 +16,7 @@ The skill supplies the judgment around it: which finding matters, and which skil
 
 ## It never repairs
 
-Every finding names the skill that fixes it — `init` for anything that rewrites the manifest,
+Every finding names the skill that fixes it — `init-universal-plugin` 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.
 
@@ -29,9 +29,8 @@ The checks are deterministic: same tree, same findings. The one check that is no
 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.
+Manifest validation is a CLI capability (`plugin validate`). This script stays a thin composition
+on purpose, so it folds into that command rather than competing with it.
 
 ## Boundaries
 

package/skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+description: Use this skill to diagnose a universal agent plugin — when `plugin build` reports "built 0" or "nothing to build", when it warns "No vendors declared in harnesses", when a repository still carries `.plugin/plugin.json` or a top-level `vendorExtensions` block after upgrading universal-plugin across a major, when a released version never reached the vendor manifests, when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, 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", "the build says built 0", "why did nothing get built", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
 ---
 
 # Plugin Doctor
@@ -21,6 +21,9 @@ 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.
+Add `--marketplace-root <path>` (repeatable) to also check a **separately-cloned** shared marketplace
+repository (e.g. a local clone of `cyberuni/marketplace`) — see
+[Catalogs are checked at the repository root](#catalogs-are-checked-at-the-repository-root).
 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:
@@ -43,13 +46,20 @@ Read `vendors[].status` literally:
 
 | Status | Means |
 | --- | --- |
-| `built` | the build writes this vendor's manifest |
+| `built` | the build writes this vendor's output. For `copilot-cli` that output is the `com.github.copilot/` component tree, not a 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.
+`copilot-cli` reporting `canonical` is a healthy plugin, not a missing build — root `plugin.json`
+serves it, and a plugin declaring no agents, commands, rules, hooks, or LSP servers has nothing else
+to derive. Never report it as a fault.
+
+A plugin that **does** declare those reports `copilot-cli` as `built` at `com.github.copilot/`
+instead. Declaring the canonical `$schema` moves them there: Copilot CLI stops reading them from the
+plugin root entirely, so a root-only layout loads none of them and says nothing
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)). That is what
+`copilot-root-components` reports.
 
 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.
@@ -60,23 +70,27 @@ 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 |
+| `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init-universal-plugin` |
+| `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init-universal-plugin`, adopt route |
+| `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init-universal-plugin`, 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 |
+| `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init-universal-plugin`, 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` |
+| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `universal-plugin plugin build` |
 | `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 |
+| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init-universal-plugin`, adopt route on the pre-0.6 layout, else update route |
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
+| `package-path-unknown` | the CLI could not report `packagePath` (a version too old to read it), so `version-drift` and `unreleased-content` were skipped rather than guessed | upgrade universal-plugin |
+| `misplaced-package-path` | `plugin.json` declares `packagePath` under `extensions["org.cyberuni.universal-plugin"]`, where the CLI never reads it — the plugin is silently treated as not shipping to npm | move it to `.agents/universal-plugin.json`, relative to the plugin root |
 | `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` |
+| `invalid-catalog` | a marketplace catalog — at the repository root, or at a `--marketplace-root` clone — is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
+| `marketplace-root-missing` | a `--marketplace-root` path does not exist, so it could not be checked at all | clone the marketplace repository, or fix the path |
 
 ## Catalogs are checked at the repository root
 
@@ -88,6 +102,20 @@ The detail names the key at fault, so hand it to `/universal-plugin:marketplace`
 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.
 
+A **shared** marketplace repository (e.g. `cyberuni/marketplace`) is a repository of its own — a bad
+entry that reached it by another path (a hand-edited entry, a PR from a different tool, a curator
+edit) is invisible to a `doctor` run inside any plugin's own repo, because that run never sees the
+shared repository at all. Clone it separately and name the clone explicitly:
+
+```bash
+node scripts/doctor.mjs --marketplace-root ../marketplace
+```
+
+Pass `--marketplace-root` once per clone to check more than one. Each invalid entry it finds is still
+reported as `invalid-catalog`, with the clone's path in the detail so it reads apart from the plugin
+repo's own catalogs; a path that does not exist is `marketplace-root-missing` rather than a silent
+skip.
+
 ## Checking staleness properly
 
 The `stale` finding is an mtime comparison, which catches the common case and nothing more. It cannot
@@ -108,8 +136,8 @@ 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
+Two files carry an authored version: the canonical `plugin.json`, and the `package.json` at the
+`packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root. The script compares
 them and emits `version-drift`.
 
 They diverge when someone ran `npm version`, or when changesets released a number that never flowed
@@ -140,7 +168,9 @@ is meant to ship — content that is still being worked on is not a finding to a
 - **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 report `copilot-cli` writing no **manifest** as a fault. It reads the canonical manifest
+  directly. Its **components** are a separate question — a `copilot-root-components` finding is a real
+  fault, and `canonical` is only healthy for a plugin that declares none of the moved kinds.
 - 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`.
 
@@ -148,7 +178,7 @@ is meant to ship — content that is still being worked on is not a finding to a
 
 | Task | Skill |
 |------|-------|
-| Create, adopt, or change what the plugin declares | `init` |
+| Create, adopt, or change what the plugin declares | `init-universal-plugin` |
 | Move the plugin's version | `version` |
 | Remove derived manifests, or the plugin itself | `remove-plugin` |
 | Generate the repository's own marketplace catalogs | `marketplace` |

package/skills/doctor/scripts/doctor.mjs

@@ -15,6 +15,9 @@ const argv = process.argv.slice(2)
 const verbose = argv.includes('--verbose')
 const rootFlag = argv.indexOf('--root')
 const root = path.resolve(rootFlag === -1 ? process.cwd() : (argv[rootFlag + 1] ?? process.cwd()))
+// A shared marketplace repository (e.g. cyberuni/marketplace) is cloned separately from any plugin
+// repo, so it is named explicitly rather than discovered — repeatable, one clone per flag.
+const marketplaceRoots = argv.flatMap((arg, i) => (arg === '--marketplace-root' ? [argv[i + 1]] : [])).filter(Boolean)
 
 const findings = []
 const add = (code, severity, detail, repair) => findings.push({ code, severity, detail, repair })
@@ -42,27 +45,56 @@ if (manifest === null) {
 			'vendor-only',
 			'high',
 			`vendor manifests with no canonical manifest: ${orphans.join(', ')}`,
-			'/universal-plugin:init, adopt route',
+			'/universal-plugin:init-universal-plugin, adopt route',
 		)
 	} else {
-		add('no-manifest', 'high', 'no root plugin.json — this is not a plugin yet', '/universal-plugin:init')
+		add(
+			'no-manifest',
+			'high',
+			'no root plugin.json — this is not a plugin yet',
+			'/universal-plugin:init-universal-plugin',
+		)
 	}
 	report({ vendors: [] })
 }
 
 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.
+// The shipped CLI, preferring the one this skill ships with. Every question the CLI can answer is asked
+// of it rather than re-derived here, so this script cannot drift from the commands it diagnoses.
+const bin = path.join(packageRoot, 'bin', 'universal-plugin.mjs')
+const runCli = (...args) =>
+	fs.existsSync(bin)
+		? spawnSync(process.execPath, [bin, ...args], { encoding: 'utf8' })
+		: spawnSync('npx', ['universal-plugin', ...args], { encoding: 'utf8' })
+
+// `packagePath` is the CLI's own config. It is asked of the CLI (`config get --key packagePath`), the
+// same reader `plugin version` and `publish sync-version` use, so a plugin the CLI treats as
+// npm-shipping is one this script treats the same way (issue #79). `undefined` means the CLI could not
+// answer — too old to read the key — and every check that depends on it is skipped rather than guessed.
 const packagePath = readPackagePath()
+if (packagePath === undefined) {
+	add(
+		'package-path-unknown',
+		'low',
+		'the CLI could not report packagePath, so version-drift and unreleased-content were not checked',
+		'upgrade universal-plugin',
+	)
+}
+if (ext !== null && Object.hasOwn(ext, 'packagePath')) {
+	add(
+		'misplaced-package-path',
+		'high',
+		`plugin.json declares extensions["${UP_NAMESPACE}"].packagePath, which the CLI never reads${packagePath === null ? ' — this plugin is treated as not shipping to npm' : ''}`,
+		'move packagePath to .agents/universal-plugin.json, relative to the plugin root',
+	)
+}
 if (!manifest.$schema?.includes('agent-plugins.org') || ext === null) {
 	add(
 		'legacy-manifest',
 		'high',
 		'root plugin.json carries no $schema on agent-plugins.org or no extensions block',
-		'/universal-plugin:init, adopt route',
+		'/universal-plugin:init-universal-plugin, adopt route',
 	)
 }
 
@@ -84,15 +116,59 @@ if (fs.existsSync(path.join(root, '.github/plugin/plugin.json'))) {
 	)
 }
 
+// Copilot CLI's spec mode reads its native components ONLY under com.github.copilot/ — declaring the
+// canonical $schema moves them out of the plugin root (ADR-0015). A plugin that ships them at the
+// root and has no namespace copy loads none of them on Copilot CLI, and nothing at runtime says so.
+// Checked from the filesystem rather than from the build result, so it still fires on a repository
+// whose build cannot run.
+const COPILOT_NAMESPACE = 'com.github.copilot'
+const declaredTargets = ext?.vendors ?? Object.keys(ext?.harnesses ?? {})
+if (declaredTargets.includes('copilot-cli')) {
+	const nsDir = path.join(root, COPILOT_NAMESPACE)
+	const declaredPaths = (value, fallback) => {
+		if (value === undefined) return fallback === null ? [] : [fallback]
+		if (typeof value === 'string') return [value]
+		if (Array.isArray(value)) return value.filter((entry) => typeof entry === 'string')
+		if (value && Array.isArray(value.paths)) return value.paths.filter((entry) => typeof entry === 'string')
+		return []
+	}
+	const hasContent = (rel) => {
+		const abs = path.join(root, rel)
+		return fs.existsSync(abs) && fs.statSync(abs).isDirectory() && fs.readdirSync(abs).length > 0
+	}
+	const missing = []
+	// The same defaults the build derives from. Passing null here would make the check fire only for a
+	// manifest that names the path — and the manifest that names none is the common one.
+	for (const [kind, defaultPath] of [
+		['agents', './agents/'],
+		['commands', './commands/'],
+		['rules', './rules/'],
+	]) {
+		const roots = declaredPaths(ext?.[kind], defaultPath)
+		if (roots.some(hasContent) && !hasContent(path.join(COPILOT_NAMESPACE, kind))) missing.push(kind)
+	}
+	// hooks is a single file, declared as a path or inline in the manifest, and carries a default the
+	// manifest need not declare at all.
+	const inlineHooks = ext?.hooks !== null && typeof ext?.hooks === 'object' && 'hooks' in ext.hooks
+	const hookSources = inlineHooks ? [] : declaredPaths(ext?.hooks, './hooks/hooks.json')
+	const hasHooks = inlineHooks || hookSources.some((rel) => fs.existsSync(path.join(root, rel)))
+	if (hasHooks && !fs.existsSync(path.join(nsDir, 'hooks', 'hooks.json'))) missing.push('hooks')
+	const lspSources = declaredPaths(ext?.lspServers, null)
+	if (lspSources.some((rel) => fs.existsSync(path.join(root, rel))) && !fs.existsSync(path.join(nsDir, 'lsp.json'))) {
+		missing.push('lspServers')
+	}
+	if (missing.length > 0) {
+		add(
+			'copilot-root-components',
+			'high',
+			`${missing.join(', ')} sit at the plugin root with no copy under ${COPILOT_NAMESPACE}/ — Copilot CLI reads them only from there once the canonical $schema is declared, so it loads none of them`,
+			'universal-plugin plugin build',
+		)
+	}
+}
+
 // Ask the shipped CLI what it would write, without writing it.
-const bin = path.join(packageRoot, 'bin', 'universal-plugin.mjs')
-const cli = fs.existsSync(bin)
-	? spawnSync(process.execPath, [bin, 'plugin', 'build', '--dry-run', '--format', 'json', '--root', root], {
-			encoding: 'utf8',
-		})
-	: spawnSync('npx', ['universal-plugin', 'plugin', 'build', '--dry-run', '--format', 'json', '--root', root], {
-			encoding: 'utf8',
-		})
+const cli = runCli('plugin', 'build', '--dry-run', '--format', 'json', '--root', root)
 
 const vendors = []
 const build = readJson_stdout(cli.stdout)
@@ -106,6 +182,17 @@ if (build === null) {
 			'codex is targeted without version or description — the build writes nothing at all, for any vendor',
 			'add both to the canonical top level',
 		)
+	} else if (findings.some((f) => f.code === 'legacy-manifest' || f.code === 'shadowing-manifest')) {
+		// The build stops rather than reporting a definitive empty state when the layout explains the
+		// empty result (issue #61). That is still the no-vendors diagnosis — the layout findings above
+		// name the signals, and this names the consequence. Keyed on those findings rather than on the
+		// build's message, so the two never have to agree on wording.
+		add(
+			'no-vendors',
+			'medium',
+			'no vendor is declared — the project is on the pre-0.6 layout, so the build derives nothing and no runtime reads this plugin',
+			'/universal-plugin:init-universal-plugin, adopt route',
+		)
 	} else {
 		add(
 			'build-failed',
@@ -137,13 +224,13 @@ if (build === null) {
 	}
 	for (const warning of build.warnings ?? []) {
 		if (/not delivered/.test(warning)) {
-			add('undeliverable-override', 'medium', warning, '/universal-plugin:init, update route')
+			add('undeliverable-override', 'medium', warning, '/universal-plugin:init-universal-plugin, update route')
 		} else if (/No vendors declared/.test(warning)) {
 			add(
 				'no-vendors',
 				'medium',
 				'no vendor is declared — the build writes nothing, so no runtime reads this plugin',
-				'/universal-plugin:init, update route',
+				'/universal-plugin:init-universal-plugin, update route',
 			)
 		} else if (/^Unknown vendor/.test(warning)) {
 			add('unknown-vendor', 'medium', warning, 'fix the vendor id in plugin.json')
@@ -154,7 +241,7 @@ if (build === null) {
 }
 
 // Version drift between the two authored numbers.
-if (packagePath !== null) {
+if (typeof packagePath === 'string') {
 	const pkgPath = path.join(root, packagePath, 'package.json')
 	const pkg = readJson(pkgPath)
 	if (pkg === null) {
@@ -202,31 +289,45 @@ if (manifest.version !== undefined && packagePath === null) {
 // 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()) {
+// A shared marketplace repository (--marketplace-root) is a separate clone this plugin's repo root
+// cannot see, so it is checked the same way but reported with the clone's path attached.
+const missingMarketplaceRoots = marketplaceRoots.filter((r) => !fs.existsSync(path.resolve(r)))
+for (const r of missingMarketplaceRoots) {
+	add(
+		'marketplace-root-missing',
+		'high',
+		`--marketplace-root ${r} does not exist`,
+		'clone the marketplace repository, or fix the path',
+	)
+}
+const existingMarketplaceRoots = marketplaceRoots.filter((r) => fs.existsSync(path.resolve(r)))
+
+for (const row of invalidCatalogs(existingMarketplaceRoots)) {
+	const label = row.own ? row.path : `${row.catalogRoot}/${row.path}`
 	add(
 		'invalid-catalog',
 		'high',
-		`${row.path} is not a shape its runtime loads: ${row.issues.map((issue) => `${issue.path} ${issue.message}`).join('; ')}`,
+		`${label} 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() {
+/** Every catalog the repository — and any explicitly named marketplace clone — 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(extraRoots) {
 	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') : []
+	const targets = [{ catalogRoot, own: true }, ...extraRoots.map((r) => ({ catalogRoot: path.resolve(r), own: false }))]
+	return targets.flatMap(({ catalogRoot, own }) => {
+		const result = runCli('marketplace', 'validate', '--format', 'json', '--root', catalogRoot)
+		const rows = readJson_stdout(result.stdout)
+		return Array.isArray(rows)
+			? rows.filter((row) => row.status === 'invalid').map((row) => ({ ...row, catalogRoot, own }))
+			: []
+	})
 }
 
 /** Runs git inside `root`, returning its stdout or `null` — a non-zero status, a missing git, and a
@@ -293,9 +394,16 @@ 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. */
+/** Where the npm package that ships this plugin lives, relative to the plugin root, as the CLI reads
+ *  it; `null` when the plugin ships to no package (the author-picks release model of ADR-0010 §2);
+ *  `undefined` when the CLI could not answer. */
 function readPackagePath() {
-	const declared = readJson(path.join(root, '.agents', 'universal-plugin.json'))?.packagePath ?? ext?.packagePath
-	return typeof declared === 'string' && declared.length > 0 ? declared : null
+	const result = runCli('config', 'get', '--key', 'packagePath', '--format', 'json', '--root', root)
+	if (result.status !== 0) return undefined
+	try {
+		const declared = JSON.parse(result.stdout)
+		return typeof declared === 'string' || declared === null ? declared : undefined
+	} catch {
+		return undefined
+	}
 }

package/skills/{init → init-universal-plugin}/README.md

@@ -1,4 +1,4 @@
-# init skill
+# init-universal-plugin skill
 
 Give a project one canonical `plugin.json` on the [Agent Plugins
 Specification](https://agent-plugins.org), then derive the manifest each runtime expects — Claude
@@ -53,5 +53,8 @@ touch CI, repository settings, or unrelated project files.
 ## 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)
+- [Manifest schema (Agent Plugins Specification v1.0.0)](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)
+- [Extension schema](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json)
+  — the body of `extensions["org.cyberuni.universal-plugin"]`, also shipped in the package at
+  `schema/extension.schema.json`
 - [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/{init → init-universal-plugin}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: init
+name: init-universal-plugin
 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] [--no-marketplace] [--force]'
 ---
@@ -10,10 +10,18 @@ Give a project one canonical plugin manifest — a root `plugin.json` on the Age
 Specification — and derive from it the manifest each runtime expects.
 
 Most of the manifest is shared. The divergence is small and asymmetric: Copilot CLI reads the
-canonical `plugin.json` directly and gets no derived file at all, while Claude Code, Cursor, and
+canonical `plugin.json` directly and gets no derived *manifest*, while Claude Code, Cursor, and
 Codex each read their own path. Keep that asymmetry in mind — this is a consolidation job, not a
 copy-everywhere job.
 
+That asymmetry does not extend to components. Declaring the canonical `$schema` puts a plugin in
+Open Plugin Spec mode, and Copilot CLI then reads its **native** components — agents, commands,
+rules, hooks, LSP servers — from a `com.github.copilot/` directory rather than the plugin root.
+Authoring still happens at the canonical locations: `plugin build` derives that directory
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)), so do not tell
+an author to move `agents/` into it — the root copy is what the other three vendors derive from. See
+[`references/vendors/copilot-cli.md`](./references/vendors/copilot-cli.md).
+
 `references/standard.md` defines the baseline every plugin gets. Read the vendor file for each
 runtime you are enabling, and only those.
 
@@ -22,7 +30,7 @@ runtime you are enabling, and only those.
 | Claude Code | `.claude-plugin/plugin.json` | none | `references/vendors/claude-code.md` |
 | Cursor | `.cursor-plugin/plugin.json` | none | `references/vendors/cursor.md` |
 | Codex | `.codex-plugin/plugin.json` | `version`, `description` | `references/vendors/codex.md` |
-| GitHub Copilot CLI | none — reads root `plugin.json` | none | `references/vendors/copilot-cli.md` |
+| GitHub Copilot CLI | none — reads root `plugin.json` | native components derived under `com.github.copilot/` ([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)) | `references/vendors/copilot-cli.md` |
 
 This skill owns the **authoring** side: the plugin a project ships. Setting a repository up to
 *consume* skills — the `.agents/skills/` layout, `AGENTS.md`, per-harness bridges — is
@@ -40,7 +48,7 @@ It is the authoritative source for which component to reach for and which anti-p
 
 ## Arguments
 
-An invocation may carry the CLI's own flags: `/universal-plugin:init --name my-plugin --scaffold --npm`.
+An invocation may carry the CLI's own flags: `/universal-plugin:init-universal-plugin --name my-plugin --scaffold --npm`.
 
 Read them from the invocation itself rather than from a placeholder. Claude Code appends what the
 caller typed as `ARGUMENTS: <value>`, and Codex substitutes nothing at all, so on every runtime the
@@ -78,9 +86,12 @@ Sort each finding into exactly one bucket:
 - **adoptable** — a hand-written vendor manifest with no canonical manifest above it, a legacy root
   `plugin.json` carrying neither `$schema` nor `extensions`, or publicly-shipped skills with no
   manifest at all. These become canonical content in Phase 4.
-- **undeliverable** — a vendor-specific field with no delivery path, most often a
-  `harnesses["copilot-cli"]` override: the canonical schema is closed, so the field cannot ride
-  along in root and the build warns about it. Report; do not invent a home for it.
+- **undeliverable** — a vendor-specific field with no delivery path, because Copilot CLI reads the
+  canonical manifest directly and has no derived file of its own. Two shapes reach this bucket: a
+  `harnesses["copilot-cli"]` override, which the build warns about; and a non-spec field on a
+  **legacy root `plugin.json`** — `category`, `tags` — which nothing warns about at all, because the
+  correct adoption never writes a `harnesses` entry for it. Report every one by name; do not invent
+  a home for it.
 - **not a plugin** — repo-private agent configuration (`.claude/skills/`, `.agents/skills/`,
   `.cursor/rules/`). It is this project's own tooling, not something it distributes. Say nothing
   about packaging it.
@@ -95,6 +106,11 @@ hand-written vendor manifests become generated artifacts, which vendors will be
 canonical metadata will say (show `name`, `version`, and `description` verbatim), and what is being
 left alone and why.
 
+An adoption also presents **every non-spec field it is about to drop, by name and value** — the
+undeliverable bucket from Phase 2. Nothing downstream warns about those, so this is the only notice
+the user gets. [`references/adopt.md`](./references/adopt.md) Step 2 has the command that enumerates
+them.
+
 Get explicit approval before any step that deletes, replaces, or rewrites a user-authored file —
 adoption always crosses that line, because it turns manifests the user maintains into build output.
 Creating a missing `plugin.json`, a missing component directory, or a missing skill scaffold needs
@@ -145,7 +161,7 @@ and read back any line it printed on stderr — a repository with no author, 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
+every plugin the repository develops. Re-running `init-universal-plugin` 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.
@@ -167,11 +183,16 @@ override both surface there and both are silent capability loss if ignored.
 When the work was an adoption, the proof is the diff:
 
 ```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+git diff -- plugin.json .claude-plugin .cursor-plugin .codex-plugin .github/plugin
 ```
 
-Expect only formatting and key-order churn. Any field that disappeared is a regression, not a
-cleanup — trace it back to the shared metadata or to that vendor's `harnesses` entry before shipping.
+From the four derived paths, expect only formatting and key-order churn. Root `plugin.json` is
+different and is in the list on purpose: it shows real hunks — the `$schema`/`extensions` rewrite —
+and under the legacy layout it *was* Copilot CLI's manifest, so it is the one file where a field can
+vanish unnoticed. Read those hunks rather than skimming them.
+
+Any field that disappeared is a regression, not a cleanup — trace it back to the shared metadata, to
+that vendor's `harnesses` entry, or to the drop list you reported in Phase 3, before shipping.
 
 Audit each skill the plugin ships, per [`references/create.md`](./references/create.md) Step 6.
 Report what was created, adopted, derived, and left alone. For a fuller read of the plugin's state
@@ -186,7 +207,9 @@ This skill is not a formatter. If the project has one, run it over the written f
 - **Never hand-edit a `version` field.** Two authored files and every derived artifact fall out of
   sync. The `version` skill owns that move.
 - **Adoption is lossless by contract.** Every vendor that worked before must still work after, and
-  the Phase 5 diff is the check that proves it.
+  the Phase 5 diff — root `plugin.json` included — is the check that proves it. Where a field
+  genuinely cannot be carried, losing it is a decision the user makes, not one the adoption makes
+  quietly: name it first.
 - **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.** Hooks have one: author them in
@@ -215,5 +238,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 
 - Governance: `npx universal-plugin 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
+- Manifest schema (Agent Plugins Specification v1.0.0): https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
+- Extension schema (the body of `extensions["org.cyberuni.universal-plugin"]`), shipped in the package at
+  `schema/extension.schema.json`: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json
 - Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples