universal-plugin 0.3.1 → 0.5.0

package/skills/doctor/scripts/doctor.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+// Read-only diagnosis of a universal plugin. Emits one JSON object on stdout; never writes.
+// Derivation itself is not re-implemented here — the shipped CLI's own build resolver is the source
+// of truth for what each vendor gets, and this script only adds the filesystem facts it cannot see.
+import { spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const UP_NAMESPACE = 'org.cyberuni.universal-plugin'
+// <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
+const packageRoot = path.dirname(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url)))))
+
+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()))
+
+const findings = []
+const add = (code, severity, detail, repair) => findings.push({ code, severity, detail, repair })
+
+const readJson = (file) => {
+	try {
+		return JSON.parse(fs.readFileSync(file, 'utf8'))
+	} catch {
+		return null
+	}
+}
+const mtime = (file) => (fs.existsSync(file) ? fs.statSync(file).mtimeMs : null)
+
+const VENDOR_MANIFESTS = ['.claude-plugin/plugin.json', '.cursor-plugin/plugin.json', '.codex-plugin/plugin.json']
+
+const manifestPath = path.join(root, 'plugin.json')
+const manifest = fs.existsSync(manifestPath) ? readJson(manifestPath) : null
+
+if (manifest === null) {
+	const orphans = VENDOR_MANIFESTS.filter((rel) => fs.existsSync(path.join(root, rel)))
+	if (fs.existsSync(manifestPath)) {
+		add('unparsable-manifest', 'critical', 'plugin.json is not valid JSON', 'fix the syntax error')
+	} else if (orphans.length > 0) {
+		add(
+			'vendor-only',
+			'high',
+			`vendor manifests with no canonical manifest: ${orphans.join(', ')}`,
+			'/universal-plugin:init, adopt route',
+		)
+	} else {
+		add('no-manifest', 'high', 'no root plugin.json — this is not a plugin yet', '/universal-plugin:init')
+	}
+	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.
+const packagePath = readPackagePath()
+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',
+	)
+}
+
+// Shadowing and leftovers. `.plugin/plugin.json` outranks root in Copilot CLI's search order.
+if (fs.existsSync(path.join(root, '.plugin/plugin.json'))) {
+	add(
+		'shadowing-manifest',
+		'high',
+		'.plugin/plugin.json outranks root and is read instead of the canonical manifest',
+		'/universal-plugin:remove-plugin',
+	)
+}
+if (fs.existsSync(path.join(root, '.github/plugin/plugin.json'))) {
+	add(
+		'stale-github-plugin',
+		'low',
+		'.github/plugin/plugin.json is a leftover from an older build and is no longer generated',
+		'/universal-plugin:remove-plugin',
+	)
+}
+
+// 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 vendors = []
+const build = readJson_stdout(cli.stdout)
+
+if (build === null) {
+	const stderr = (cli.stderr ?? '').trim()
+	if (/required when targeting codex/.test(stderr)) {
+		add(
+			'codex-fields-missing',
+			'high',
+			'codex is targeted without version or description — the build writes nothing at all, for any vendor',
+			'add both to the canonical top level',
+		)
+	} else {
+		add(
+			'build-failed',
+			'high',
+			stderr.split('\n')[0] || 'plugin build could not resolve the manifest',
+			'run plugin build to see the full error',
+		)
+	}
+} else {
+	const manifestMtime = mtime(manifestPath)
+	for (const row of [...build.built, ...build.canonical, ...build.skipped, ...build.failed]) {
+		const abs = path.join(root, row.path)
+		const exists = fs.existsSync(abs)
+		// `canonical` means the vendor reads root plugin.json; no derived file is expected.
+		const stale = row.status === 'built' && exists && manifestMtime !== null && mtime(abs) < manifestMtime
+		vendors.push({ vendor: row.vendor, path: row.path, status: row.status, exists, stale })
+
+		if (row.status === 'built' && !exists) {
+			add(
+				'unbuilt',
+				'high',
+				`${row.vendor} is declared but ${row.path} does not exist — that runtime sees no plugin`,
+				'universal-plugin plugin build',
+			)
+		}
+		if (stale) {
+			add('stale', 'medium', `${row.path} is older than plugin.json`, 'universal-plugin plugin build')
+		}
+	}
+	for (const warning of build.warnings ?? []) {
+		if (/not delivered/.test(warning)) {
+			add('undeliverable-override', 'medium', warning, '/universal-plugin:init, 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',
+			)
+		} else if (/^Unknown vendor/.test(warning)) {
+			add('unknown-vendor', 'medium', warning, 'fix the vendor id in plugin.json')
+		} else {
+			add('build-warning', 'low', warning, 'read the warning and decide')
+		}
+	}
+}
+
+// Version drift between the two authored numbers.
+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 ${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}, ${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',
+			)
+		}
+	}
+}
+
+report({ vendors })
+
+/** 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 {
+		return JSON.parse(stdout)
+	} catch {
+		return null
+	}
+}
+
+function report({ vendors }) {
+	const result = {
+		root,
+		manifest: manifest === null ? null : { name: manifest.name ?? null, version: manifest.version ?? null },
+		vendors,
+		findings,
+		ok: findings.length === 0,
+	}
+	process.stdout.write(`${JSON.stringify(result)}\n`)
+	if (verbose) {
+		process.stderr.write(result.ok ? 'no findings\n' : `${findings.length} finding(s)\n`)
+		for (const f of findings) process.stderr.write(`  [${f.severity}] ${f.code}: ${f.detail}\n`)
+	}
+	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/README.md

@@ -0,0 +1,57 @@
+# init 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
+Code, Cursor, Codex, and GitHub Copilot CLI.
+
+## What it does
+
+The skill runs a five-phase workflow: survey what the project already has, classify each finding,
+confirm the plan, apply it, then verify and report.
+
+It detects what is already there — a canonical manifest, hand-written vendor manifests, a legacy root
+manifest, publicly-shipped skills with no manifest at all — and either adopts it onto the standard,
+rebuilds it, or reports it as something to leave alone. It never rewrites a file the user authored
+without asking first.
+
+## Why the derivation step is small
+
+Copilot CLI reads the canonical `plugin.json` directly, so nothing is generated for it. Only Claude
+Code, Cursor, and Codex get a derived manifest, and the difference between them is a handful of
+vendor-specific fields under `harnesses.<vendor>`.
+
+`references/standard.md` defines the baseline every plugin gets. `references/vendors/<vendor>.md`
+covers what one runtime needs on top of it, and `SKILL.md` routes to them directly rather than
+loading all four.
+
+## Routes
+
+Phase 4 routes to exactly one reference:
+
+| Route | Reference | Covers |
+| --- | --- | --- |
+| Create | [`references/create.md`](./references/create.md) | scaffold a new plugin with chosen vendors and components |
+| Adopt | [`references/adopt.md`](./references/adopt.md) | put an existing vendor-specific plugin, or already-shipped skills, onto the open standard |
+| Update | [`references/update.md`](./references/update.md) | add or remove a vendor or a component |
+
+Three neighbours own the rest of the plugin's life, each named for what it does: `doctor` diagnoses,
+`version` moves the number, `remove-plugin` deletes. This skill is the one that writes the manifest.
+
+## The part that needs care
+
+Deriving a manifest is easy; keeping a skill's *behavior* identical across runtimes is not. Each
+runtime parses the frontmatter fields it knows and silently drops the rest, so anything that must
+hold everywhere belongs in the Markdown body. See `references/frontmatter.md`, which also documents
+`invocation-policy` — the one field this build acts on, by rewriting the authored `SKILL.md`.
+
+## Boundaries
+
+Plugin authoring only. Setting a repository up to *consume* skills — `AGENTS.md`, the
+`.agents/skills/` layout, per-harness bridges — is `buddy-agent-harness:init`. This skill does not
+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)
+- [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/init/SKILL.md

@@ -0,0 +1,219 @@
+---
+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] [--no-marketplace] [--force]'
+---
+
+# Plugin Init
+
+Give a project one canonical plugin manifest — a root `plugin.json` on the Agent Plugins
+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
+Codex each read their own path. Keep that asymmetry in mind — this is a consolidation job, not a
+copy-everywhere job.
+
+`references/standard.md` defines the baseline every plugin gets. Read the vendor file for each
+runtime you are enabling, and only those.
+
+| Vendor | Derived manifest | Extra requirements | Read |
+| --- | --- | --- | --- |
+| 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` |
+
+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
+`buddy-agent-harness:init`, not this.
+
+## Prerequisites
+
+Load the component-selection governance before any work that adds or removes components:
+
+```bash
+npx universal-plugin governance show plugin-design
+```
+
+It is the authoritative source for which component to reach for and which anti-patterns to avoid.
+
+## Arguments
+
+An invocation may carry the CLI's own flags: `/universal-plugin:init --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
+flags arrive as text you can read. Writing `$ARGUMENTS` into this body would resolve on Claude Code
+and stay literal everywhere else.
+
+- `--name`, `--vendor`, `--scaffold`, `--force`, `--npm`, and `--root` pass through to
+  `universal-plugin plugin init` in Phase 4.
+- Prose carries the same weight: "ship it on npm" means `--npm`, "overwrite what's there" means
+  `--force`.
+- An argument never skips a phase. `--force` still needs the Phase 3 approval, and the survey still
+  runs first.
+- Say what you did not recognize and carry on. Never guess at a flag.
+
+Work in five phases. Do not skip Phase 3.
+
+## 1. Survey
+
+Locate the plugin root — the directory that holds, or will hold, the canonical `plugin.json`. In a
+monorepo that is usually the package that ships the plugin, not the repository root; `migrate-plugin`
+covers moving one that sits in the wrong place.
+
+Inventory both the canonical surface (root `plugin.json`, its `extensions` block, the component
+directories it names) and every pre-existing vendor artifact listed in `references/detection.md`.
+Read what you find. Write nothing yet.
+
+## 2. Classify
+
+Sort each finding into exactly one bucket:
+
+- **canonical** — a root `plugin.json` with `$schema` on `agent-plugins.org` and an `extensions`
+  object. This is the source of truth; every edit lands here.
+- **derived** — `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/` manifests that `plugin build`
+  regenerates. Rebuild them; never hand-edit them.
+- **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.
+- **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.
+
+`references/detection.md` maps each signal to its bucket, and draws the public-versus-private line
+that decides the last two.
+
+## 3. Confirm
+
+Present the plan before touching anything the user wrote: which files will be created, which
+hand-written vendor manifests become generated artifacts, which vendors will be enabled, what the
+canonical metadata will say (show `name`, `version`, and `description` verbatim), and what is being
+left alone and why.
+
+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
+no approval; report those rather than asking.
+
+One case needs asking even when nothing is overwritten: two vendor manifests that disagree on a
+shared field. A silent pick there is a silent behavior change for one runtime.
+
+## 4. Apply
+
+Route by what Phase 2 found. Read exactly the reference for the work at hand — do not load all six.
+
+| What Phase 2 found | Do this | Reference |
+| --- | --- | --- |
+| nothing — greenfield | scaffold a canonical manifest and its components | [`references/create.md`](./references/create.md) |
+| adoptable | carry it onto the canonical manifest, losslessly | [`references/adopt.md`](./references/adopt.md) |
+| canonical, and a vendor or component changes | edit `extensions`, then rebuild | [`references/update.md`](./references/update.md) |
+
+Three asks leave this skill rather than routing inside it. Hand them over instead of improvising a
+route: **`doctor`** reports what is declared, built, stale, or drifting; **`version`** moves the
+number; **`remove-plugin`** deletes derived manifests or the plugin itself.
+
+Every route ends in the same two commands. Scaffold with the CLI that shipped beside this skill:
+
+```bash
+node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor
+```
+
+Resolve that path against this skill's own directory. The launcher runs the bundled CLI, so nothing
+is downloaded; fall back to `npx universal-plugin plugin init` when the path cannot be resolved.
+`plugin init` never prompts, so it is safe to run unattended (`--yes` is accepted as a no-op).
+
+Then derive the vendor manifests:
+
+```bash
+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.
+
+If the request spans more than one route ("add Codex, then cut a release"), take this skill's part
+first and hand the rest to the skill that owns it. If the route is unclear, ask which the user means
+rather than guessing.
+
+## 5. Verify and report
+
+Confirm the build wrote what the manifest declares: one file per derived vendor, `canonical` status
+and no file for Copilot CLI. Read the build's warnings — an unknown vendor id and an undeliverable
+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
+```
+
+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.
+
+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
+than this phase gives — drift, version skew, shadowing manifests — hand off to `doctor`.
+
+This skill is not a formatter. If the project has one, run it over the written files and say so.
+
+## Rules
+
+- **Edit the canonical manifest, never a derived one.** `.claude-plugin/plugin.json` and its
+  siblings belong to `plugin build`; a hand-edit there is overwritten on the next build.
+- **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.
+- **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
+  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.
+
+## Related skills
+
+| 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` |
+| Publish a packaged plugin to the marketplace | `publish-plugin` |
+| Bump the pinned `universal-plugin@<version>` the project *calls* (not the plugin's own version) | `upgrade-plugin` |
+| Rewrite `npx` pins to the `upx` runner | `adopt-upx` |
+| Set a repository up to *consume* skills (`AGENTS.md`, `.agents/skills/`) | `buddy-agent-harness:init` |
+
+## References
+
+- 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
+- Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples

package/skills/{plugin → init}/references/adopt.md

@@ -16,8 +16,9 @@ is the check that proves it — do not skip it.
 
 ## Step 0 — Confirm the user wants this
 
-Adoption rewrites the project's manifest layout and turns hand-written vendor manifests into
-generated artifacts. Say that plainly and get agreement before touching files. If the user declines,
+This is the skill's Phase 3 gate, and adoption always needs it: adoption rewrites the project's
+manifest layout and turns hand-written vendor manifests into generated artifacts. Say that plainly
+and get agreement before touching files. If the user declines,
 route back to whatever they originally asked for.
 
 Also confirm the working tree is clean (`git status`). The Step 6 diff is worthless if uncommitted
@@ -37,7 +38,7 @@ reproduce all of it.
 
 **If a root `plugin.json` already exists**, read it before assuming anything. It is either the
 canonical manifest (has `$schema` pointing at `agent-plugins.org` and an `extensions` object — in
-which case there is nothing to adopt; route to `update.md` or `inspect.md` instead), or a legacy
+which case there is nothing to adopt; route to `update.md`, or hand off to `doctor`, instead), or a legacy
 Copilot CLI manifest that now collides with the canonical path and must be folded in.
 
 ## Step 2 — Sort every field into shared vs vendor-specific
@@ -58,9 +59,12 @@ rather than picking one. A silent choice here is a silent behavior change for on
 Scaffold it, naming exactly the vendors you found in Step 1:
 
 ```bash
-npx universal-plugin plugin init --name <name> --vendor claude-code --vendor cursor
+node scripts/init.mjs --name <name> --vendor claude-code --vendor cursor
 ```
 
+Resolve `scripts/init.mjs` against this skill's directory; `npx universal-plugin plugin init` is the
+fallback.
+
 > `plugin init` writes a **minimal** manifest — `$schema`, `name`, and the `vendors` list. It does
 > not read your existing vendor manifests. Carry the Step 2 buckets in by hand afterwards.