universal-plugin 0.3.1 → 0.4.0

package/skills/doctor/SKILL.md

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

package/skills/doctor/scripts/doctor.mjs

@@ -0,0 +1,196 @@
+#!/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
+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 (ext?.packagePath) {
+	const pkgPath = path.join(root, ext.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`,
+			'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}`,
+			'/universal-plugin:version',
+		)
+	}
+}
+
+report({ vendors })
+
+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)
+}

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,200 @@
+---
+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]'
+---
+
+# 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
+```
+
+`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.** 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.
+- **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` |
+| 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.