universal-plugin 0.17.1 → 0.18.0

package/skills/doctor-universal-plugin/scripts/doctor.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/doctor.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.18.0","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -51,6 +51,17 @@ const marketplaceRoots = argv.flatMap((arg, i) => arg === "--marketplace-root" ?
 const findings = [];
 /** semantic-release's version placeholder until its publish run stamps the real number. */
 const UNSTAMPED_VERSION = "0.0.0-development";
+/** The config files release-it reads, besides the `release-it` key of package.json. */
+const RELEASE_IT_FILES = [
+	"json",
+	"yaml",
+	"yml",
+	"toml",
+	"js",
+	"cjs",
+	"mjs",
+	"ts"
+].map((ext) => `.release-it.${ext}`);
 const add = (code, severity, detail, repair) => findings.push({
 	code,
 	severity,
@@ -187,7 +198,7 @@ if (packagePath !== void 0 && !packageMissing) {
 		if (manifest.version !== void 0 && pkg.version !== UNSTAMPED_VERSION && pkg.version !== manifest.version) add("version-drift", "high", `plugin.json is ${manifest.version}, ${packagePath}/package.json is ${pkg.version}`, "/universal-plugin:version");
 	}
 }
-if (manifest.version !== void 0 && packagePath === null) {
+if (manifest.version !== void 0 && packagePath === null && releaseTool() === null) {
 	const introduced = commitThatSetVersion(manifest.version);
 	if (introduced !== null) {
 		const files = (git("diff", "--name-only", `${introduced}..HEAD`, "--", ...shippedPaths()) ?? "").split("\n").filter(Boolean);
@@ -197,6 +208,10 @@ if (manifest.version !== void 0 && packagePath === null) {
 		}
 	}
 }
+for (const finding of changesetsReleaseFindings()) add(...finding);
+for (const finding of releasePleaseReleaseFindings()) add(...finding);
+for (const file of releaseItConfigsWithoutStamp()) add("release-it-no-stamp", "high", `${file} configures release-it, but no hook runs plugin version — the release is tagged with plugin.json and the vendor manifests still on the previous version`, "add \"hooks\": { \"after:bump\": \"universal-plugin plugin version ${version}\" } to the release-it config");
+for (const finding of semanticReleaseFindings()) add(...finding);
 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)));
@@ -222,6 +237,214 @@ function invalidCatalogs(extraRoots) {
 		})) : [];
 	});
 }
+/** The release-config gaps of a non-npm plugin in a changesets repository: no `packagePath`, and a
+*  plugin-root package.json that is absent or private. An npm-shipped plugin is not checked here —
+*  `changeset publish` there publishes to npm whatever the private-package settings say. */
+function changesetsReleaseFindings() {
+	if (packagePath !== null) return [];
+	const repoRoot = git("rev-parse", "--show-toplevel") ?? root;
+	const workspace = changesetsWorkspace(repoRoot);
+	if (workspace === void 0) return [];
+	const pkg = readJson(path.join(root, "package.json"));
+	const out = [];
+	if (pkg === null) out.push([
+		"changesets-no-package",
+		"high",
+		"the repository is released with changesets, but the plugin root has no package.json — changesets releases only a package, so changeset version and changeset publish fail",
+		"/universal-plugin:init-universal-plugin — it writes a private package.json (name, \"private\": true, version)"
+	]);
+	const setting = readJson(path.join(workspace, ".changeset", "config.json"))?.privatePackages;
+	if (!(typeof setting === "object" && setting !== null && setting.version !== false && setting.tag === true)) out.push([
+		"changesets-private-untagged",
+		"high",
+		".changeset/config.json does not set \"privatePackages\": { \"version\": true, \"tag\": true } — changeset publish creates no tag for a private package, so no release is made",
+		"set \"privatePackages\": { \"version\": true, \"tag\": true } in .changeset/config.json"
+	]);
+	for (const workflow of changesetsWorkflowsWithoutPublish(repoRoot)) out.push([
+		"changesets-no-publish-script",
+		"high",
+		`${workflow} runs changesets/action with no publish script — after the Version Packages PR merges it does nothing, so no tag or release is made`,
+		"add `publish-script: pnpm release` (changesets/action v1: `publish:`) to the changesets/action step, with a \"release\" script running changeset publish"
+	]);
+	return out;
+}
+/** The directory holding `.changeset/` for a non-npm plugin a changesets repository releases: the
+*  plugin root or the repository root, with a plugin-root package.json that is absent or private.
+*  `undefined` when changesets does not release this plugin as a non-npm one. */
+function changesetsWorkspace(repoRoot) {
+	const workspace = [root, repoRoot].find((dir) => fs.existsSync(path.join(dir, ".changeset")));
+	if (workspace === void 0) return void 0;
+	const pkg = readJson(path.join(root, "package.json"));
+	return pkg !== null && pkg.private !== true ? void 0 : workspace;
+}
+/** The release tool that picks a non-npm plugin's next version, or `null` when the author picks it
+*  (ADR-0010 §6). Each tool moves the number at release time, from what accumulated since the last
+*  release: changesets from changeset files, release-please and semantic-release from commits,
+*  release-it from its prompt or increment argument. Config is looked for where each tool loads it:
+*  the plugin root and the repository root. */
+function releaseTool() {
+	const repoRoot = git("rev-parse", "--show-toplevel") ?? root;
+	if (changesetsWorkspace(repoRoot) !== void 0) return "changesets";
+	const rpConfig = readJson(path.join(repoRoot, "release-please-config.json"));
+	if (rpConfig !== null && releasePleaseBumpsManifest(rpConfig, repoRoot)) return "release-please";
+	const dirs = [.../* @__PURE__ */ new Set([root, repoRoot])];
+	if (dirs.some((dir) => semanticReleaseConfig(dir) !== null)) return "semantic-release";
+	if (dirs.some((dir) => hasConfig(dir, RELEASE_IT_FILES, "release-it"))) return "release-it";
+	return null;
+}
+/** Whether `dir` holds one of the config files `files`, or a package.json carrying `key`. */
+function hasConfig(dir, files, key) {
+	if (files.some((file) => fs.existsSync(path.join(dir, file)))) return true;
+	const pkg = readJson(path.join(dir, "package.json"));
+	return pkg !== null && typeof pkg === "object" && Object.hasOwn(pkg, key);
+}
+/** The release-please gap of a non-npm plugin: `release-please-config.json` bumps this plugin's
+*  plugin.json through `extra-files`, and no workflow runs `plugin version` to restamp the rest, or
+*  the restamp is pushed with the default `GITHUB_TOKEN` and so gets no checks. A plugin with `packagePath` is not checked: its number comes from the package, through
+*  `--from-package`. */
+function releasePleaseReleaseFindings() {
+	if (packagePath !== null) return [];
+	const repoRoot = git("rev-parse", "--show-toplevel") ?? root;
+	const config = readJson(path.join(repoRoot, "release-please-config.json"));
+	if (config === null || !releasePleaseBumpsManifest(config, repoRoot)) return [];
+	if (!workflowsMention(repoRoot, /plugin version|version\.mjs/)) return [[
+		"release-please-no-restamp",
+		"high",
+		"release-please-config.json bumps plugin.json through extra-files, but no workflow runs plugin version — the release PR leaves the vendor manifests, catalogs, skill pins and compiled scripts on the old version",
+		"add a workflow step on the release PR branch that runs `universal-plugin plugin version --from-manifest` and pushes the stamped files (see the version skill)"
+	]];
+	return restampWorkflowsWithoutCi(repoRoot).map((workflow) => [
+		"release-please-restamp-no-ci",
+		"medium",
+		`${workflow} pushes the --from-manifest restamp with the default GITHUB_TOKEN — that push starts no workflow run, so the release PR's checks never run on its head commit and a required check blocks the merge`,
+		"mint a GitHub App token with actions/create-github-app-token and pass it to release-please-action and actions/checkout as `token:` (see the version skill)"
+	]);
+}
+/** Workflow files that restamp with `--from-manifest`, push, and leave the push on the default
+*  `GITHUB_TOKEN`, which starts no workflow run. Read as text, so it clears a file on any sign of
+*  another credential: a GitHub App token, a deploy key, or a `token:` input that is not the default
+*  token. A workflow dispatch does not clear it: its checks do not count toward a required check. */
+function restampWorkflowsWithoutCi(repoRoot) {
+	const startsCi = /create-github-app-token|ssh-key:|token:\s*\$\{\{(?!\s*(?:secrets\.GITHUB_TOKEN|github\.token)\b)/;
+	return workflowFiles(repoRoot).filter(({ text }) => /--from-manifest/.test(text) && /git push/.test(text) && !startsCi.test(text)).map(({ file }) => file);
+}
+/** Whether a release-please config lists this plugin's plugin.json in `extra-files`. A package's own
+*  `extra-files` replaces the top-level default. A path is relative to the package path, or to the
+*  repository root with a leading `/`. */
+function releasePleaseBumpsManifest(config, repoRoot) {
+	const target = path.join(root, "plugin.json");
+	const packages = config.packages ?? {};
+	return Object.entries(packages).some(([packageDir, options]) => {
+		const extra = options?.["extra-files"] ?? config["extra-files"];
+		if (!Array.isArray(extra)) return false;
+		return extra.some((entry) => {
+			const file = typeof entry === "string" ? entry : entry?.path;
+			if (typeof file !== "string") return false;
+			return (file.startsWith("/") ? path.join(repoRoot, file) : path.join(repoRoot, packageDir, file)) === target;
+		});
+	});
+}
+/** The semantic-release wiring gaps, for the config at the plugin root and at the repository root.
+*  Each config is read as text, so a JavaScript config is checked only for what it names. A config
+*  that `extends` a shareable config is skipped: the wiring may live in the shared one. */
+function semanticReleaseFindings() {
+	const repoRoot = git("rev-parse", "--show-toplevel") ?? root;
+	return [.../* @__PURE__ */ new Set([root, repoRoot])].flatMap((dir) => {
+		const config = semanticReleaseConfig(dir);
+		if (config === null || /\bextends\b/.test(config.text)) return [];
+		const label = path.relative(root, path.join(dir, config.file)) || config.file;
+		const out = [];
+		if (!/\bprepareCmd\b['"]?\s*:\s*(?:[>|][-+]?\s*\n\s*)?[^,\n}]*(?:\bplugin\s+version\b|version\.mjs)/.test(config.text)) out.push([
+			"semantic-release-no-stamp",
+			"high",
+			`${label} configures semantic-release, but no @semantic-release/exec prepareCmd runs plugin version — the release is tagged with plugin.json, the vendor manifests and the catalogs still on the previous version`,
+			"add [\"@semantic-release/exec\", { \"prepareCmd\": \"universal-plugin plugin version ${nextRelease.version}\" }] before @semantic-release/git — /universal-plugin:init-universal-plugin wires it"
+		]);
+		const runsNpm = /@semantic-release\/npm(?![\w-])/.test(config.text) || !/\bplugins\b/.test(config.text);
+		if (packagePath === null && runsNpm) out.push([
+			"semantic-release-npm-unshipped",
+			"high",
+			`${label} runs @semantic-release/npm, but the plugin ships to no npm package — with no package.json the release fails (ENOPKG), and with one it still rewrites that version`,
+			"remove @semantic-release/npm from the plugins list (write the list out if the config relies on the defaults) — /universal-plugin:init-universal-plugin wires it"
+		]);
+		return out;
+	});
+}
+/** The semantic-release config semantic-release would read in `dir`, as text, or `null` when there
+*  is none. The search order is cosmiconfig 9's default for the module name `release`: the `release`
+*  key of package.json, then the files below. The first one found is the only one read. */
+function semanticReleaseConfig(dir) {
+	const rc = [
+		"",
+		".json",
+		".yaml",
+		".yml",
+		".js",
+		".ts",
+		".cjs",
+		".mjs"
+	];
+	const files = [
+		...rc.map((ext) => `.releaserc${ext}`),
+		...rc.map((ext) => `.config/releaserc${ext}`),
+		...[
+			".js",
+			".ts",
+			".cjs",
+			".mjs"
+		].map((ext) => `release.config${ext}`)
+	];
+	const fromPackage = readJson(path.join(dir, "package.json"))?.release;
+	if (fromPackage !== void 0 && fromPackage !== null) return {
+		file: "package.json",
+		text: JSON.stringify(fromPackage, null, 2)
+	};
+	for (const file of files) {
+		const abs = path.join(dir, file);
+		if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return {
+			file,
+			text: fs.readFileSync(abs, "utf8")
+		};
+	}
+	return null;
+}
+/** Whether any workflow file's text matches. */
+function workflowsMention(repoRoot, pattern) {
+	return workflowFiles(repoRoot).some(({ text }) => pattern.test(text));
+}
+/** The workflow files under `.github/workflows`, each with its path from the repository root and its text. */
+function workflowFiles(repoRoot) {
+	const dir = path.join(repoRoot, ".github", "workflows");
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir).filter((file) => /\.ya?ml$/.test(file)).map((file) => ({
+		file: `.github/workflows/${file}`,
+		text: fs.readFileSync(path.join(dir, file), "utf8")
+	}));
+}
+/** Workflow files that run changesets/action and give it no publish command. Read as text: a step
+*  names it as `publish-script:` (v2) or `publish:` (v1). */
+function changesetsWorkflowsWithoutPublish(repoRoot) {
+	const dir = path.join(repoRoot, ".github", "workflows");
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir).filter((file) => /\.ya?ml$/.test(file)).filter((file) => {
+		const text = fs.readFileSync(path.join(dir, file), "utf8");
+		return /uses:\s*['"]?changesets\/action@/.test(text) && !/^\s*(publish-script|publish)\s*:/m.test(text);
+	}).map((file) => `.github/workflows/${file}`);
+}
+/** release-it configs, at the plugin root or the repository root, that never call `plugin version`.
+*  release-it reads `.release-it.{json,yaml,yml,toml,js,cjs,mjs,ts}` or the `release-it` key of
+*  package.json. Each is read as text, so the check is only that the stamp is named somewhere. */
+function releaseItConfigsWithoutStamp() {
+	const repoRoot = git("rev-parse", "--show-toplevel") ?? root;
+	const stamps = (text) => /\bplugin\s+version\b/.test(text);
+	return [.../* @__PURE__ */ new Set([root, repoRoot])].flatMap((dir) => {
+		const label = (file) => path.relative(root, path.join(dir, file)) || file;
+		const found = RELEASE_IT_FILES.filter((file) => fs.existsSync(path.join(dir, file))).filter((file) => !stamps(fs.readFileSync(path.join(dir, file), "utf8"))).map(label);
+		const config = readJson(path.join(dir, "package.json"))?.["release-it"];
+		if (config !== void 0 && !stamps(JSON.stringify(config))) found.push(label("package.json"));
+		return found;
+	});
+}
 /** 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) {

package/skills/init-universal-plugin/SKILL.md

@@ -70,6 +70,9 @@ 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`.
+Note the release tool the repository uses, if any: `.changeset/` (changesets), `.releaserc*`,
+`release.config.*`, or a `release` key in `package.json` (semantic-release), `.release-it.*` or a
+`release-it` key in `package.json` (release-it), or `release-please-config.json` (release-please).
 Read what you find. Write nothing yet.
 
 ## 2. Classify
@@ -126,9 +129,63 @@ plan, and ask before running init: it rewrites the user's root `package.json`. I
 run init without `--npm` and wire `files` by hand. A custom `version` script is never rewritten;
 init prints the line to append, so relay it and let the user place it.
 
+A plugin that ships to **no** npm package in a changesets repository gets its own plan line.
+Changesets releases only a package, so when the repository root carries `.changeset/` and the plugin
+root has no `package.json`, `plugin init` writes a minimal private one: `name` from the plugin name,
+`"private": true`, and `version` from the `plugin.json` it replaces (else `0.0.0`), with no `files`,
+`main`, or `exports`. It also wires the root `version` script as above and adds
+`"release": "changeset publish"`, which tags the release for changesets/action. Offer this in the
+plan and show the file; if the user declines, add `--no-changesets` to the init call. Relay init's
+notes: a plugin below the repository root must be a workspace package, and `.changeset/config.json`
+needs `"privatePackages": { "version": true, "tag": true }` before `changeset publish` tags anything.
+
+A plugin released with **semantic-release** gets the release wiring as a plan line too.
+`plugin init` writes nothing for it, so the skill edits the config itself, once the user approves.
+Add `@semantic-release/exec` with
+`prepareCmd: "universal-plugin plugin version ${nextRelease.version}"`, and add
+`@semantic-release/git` with the stamped files as `assets`. For a plugin that ships to no npm
+package, also drop `@semantic-release/npm`: `npmPublish: false` is not enough, because the plugin
+still edits `package.json`. Show the `plugins` list before and after, and edit the config file the
+survey found, in its own format. [`references/release-tools.md`](./references/release-tools.md) has
+the config, the plugin order, the full `assets` list, and the packages the release job must
+install. If the user declines, leave the config alone.
+
+A plugin released with **release-it** gets its wiring as a plan line as well. Add an `after:bump`
+hook running `universal-plugin plugin version ${version}`, after any hook the user already has. For a
+plugin that ships to no npm package, also set `"npm": false`, and run the hook through the pinned
+`npx universal-plugin@0.18.0`. release-it then reads the current number from the latest git tag,
+so when `git describe --tags` finds none, propose tagging the current commit with the version
+`plugin.json` holds (`git tag v1.2.0`). Without that tag the first release starts from `0.0.0` and
+fails. Create the tag only once the user approves, and leave pushing it to the user.
+
+A plugin released with **release-please** gets its wiring as a plan line too. For a plugin that
+ships to no npm package, write `release-please-config.json` with `release-type: simple` and an
+`extra-files` entry bumping `plugin.json`. Put the version `plugin.json` holds in
+`.release-please-manifest.json`, so the first release PR starts from it. The restamp runs in a
+workflow step on the release PR and pushes with a GitHub App token, so the PR's checks run. Show that
+step and the App setup, and hand both to the user.
+
+[`references/release-tools.md`](./references/release-tools.md) has the configs for release-it and
+release-please, the npm-shipped variants, and the tag and manifest checks. Show each file before and
+after. If the user declines, leave the config alone.
+
+When the survey found **no** release tool, ask the user how the plugin will be released before
+running init. A new repository may simply not have set one up yet:
+
+- **changesets.** Set up `.changeset/` first (`buddy-changesets:init-changesets` when it is
+  installed, else `npx @changesets/cli init`), then run init. It then finds `.changeset/` and writes
+  the private `package.json` above.
+- **semantic-release.** Propose a new `.releaserc.json` carrying the wiring above, and write it once
+  the user approves. No `package.json` is needed.
+- **release-it.** Propose a new `.release-it.json` carrying the wiring above, with the initial tag
+  for a plugin that ships to no npm package. Write it once the user approves.
+- **release-please.** Propose `release-please-config.json` and `.release-please-manifest.json` as
+  above, and hand over the workflow step. Write them once the user approves.
+- **None.** Run init as planned. The author picks each number with `version`.
+
 ## 4. Apply
 
-Route by what Phase 2 found. Read exactly the reference for the work at hand — do not load all six.
+Route by what Phase 2 found. Read exactly the reference for the work at hand — do not load them all.
 
 | What Phase 2 found | Do this | Reference |
 | --- | --- | --- |
@@ -227,6 +284,8 @@ This skill is not a formatter. If the project has one, run it over the written f
 - **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.
+  The release tool's config is the one file outside the plugin this skill edits, and only once the
+  user approves it in Phase 3. The one git write is release-it's initial tag, on the same approval.
 
 ## Related skills
 

package/skills/init-universal-plugin/references/create.md

@@ -43,10 +43,13 @@ node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor
 ```
 
 Resolve `scripts/init.mjs` against this skill's directory; it runs the project's installed CLI, else
-the pinned `npx universal-plugin@0.17.1`. Add `--npm` when an npm package ships the plugin,
+the pinned `npx universal-plugin@0.18.0`. Add `--npm` when an npm package ships the plugin,
 which also wires that `package.json`'s `files` to carry the derived manifests, copies its `version`
 into the manifest, and, in a changesets repository, wires the root `version` script to run
 `plugin version --from-package` (SKILL.md Phase 3 asks before that rewrite).
+Without `--npm`, in a changesets repository with no `package.json` at the plugin root, init writes a
+private `package.json` so changesets can release the plugin (SKILL.md Phase 3 offers it; pass
+`--no-changesets` when the user declines).
 
 `init` writes a minimal manifest — `$schema`, `name`, the vendor list, and the package `version`
 under `--npm`. Fill in the Step 1

package/skills/init-universal-plugin/references/release-tools.md

@@ -0,0 +1,272 @@
+# Release tool wiring
+
+Each release tool decides the release number in its own way. The plugin still needs that number
+stamped into `plugin.json`, the vendor manifests, the catalogs, and the skill pins. The `version`
+skill owns the stamp: `plugin version` with a number the tool hands it. This file covers the wiring
+that makes a release tool call it.
+
+`plugin init` writes the changesets wiring itself (SKILL.md Phase 3). It writes nothing for the
+other tools. Their config takes several file formats, JavaScript modules among them, and it often
+carries plugins the user added. Editing it is a judgment call, so the skill makes the edit and the
+user approves it.
+
+| Tool | Config the survey finds | Wiring |
+| --- | --- | --- |
+| changesets | `.changeset/` | `plugin init` writes it (SKILL.md Phase 3) |
+| semantic-release | `.releaserc`, `.releaserc.{json,yaml,yml,js,cjs,mjs}`, `release.config.{js,cjs,mjs}`, or a `release` key in `package.json` | [below](#semantic-release) |
+| release-it | `.release-it.{json,yaml,yml,toml,js,cjs,ts}`, or a `release-it` key in `package.json` | [below](#release-it) |
+| release-please | `release-please-config.json`, `.release-please-manifest.json` | [below](#release-please) |
+
+## semantic-release
+
+semantic-release writes the version only during its own run. Two plugins carry the number into the
+plugin:
+
+- **`@semantic-release/exec`** runs the stamp in its `prepare` step:
+  `prepareCmd: "universal-plugin plugin version ${nextRelease.version}"`. semantic-release fills in
+  `${nextRelease.version}` with its lodash template. Add `--root <plugin-root>` when the plugin root
+  is not the repository root.
+- **`@semantic-release/git`** commits the stamped files back. Copilot CLI and GitHub-hosted
+  marketplaces read `plugin.json` from the repository, not from a package, so without this commit
+  those channels never see the new number (ADR-0010 §2).
+
+A `plugins` list replaces semantic-release's default list. It does not merge with it. The defaults
+are `commit-analyzer`, `release-notes-generator`, `npm`, and `github`. A config with no `plugins`
+key therefore gets the full list written out, minus whatever the case below drops.
+
+Within each step, plugins run in list order. Put `exec` after `npm` and before `git`. That way `npm`
+moves `package.json` first, `exec` stamps the plugin, and `git` commits both.
+
+### A plugin that ships to no npm package
+
+Drop `@semantic-release/npm` from the list. `npmPublish: false` does not cover this: the plugin
+still sets `package.json` `version`, and it requires a `package.json` that a git-installed plugin
+usually lacks. Without `npm`, semantic-release needs no `package.json` at all.
+
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    ["@semantic-release/exec", {
+      "prepareCmd": "npx universal-plugin@0.18.0 plugin version ${nextRelease.version}"
+    }],
+    ["@semantic-release/git", {
+      "assets": [
+        "plugin.json",
+        ".claude-plugin/**",
+        ".cursor-plugin/**",
+        ".codex-plugin/**",
+        ".agents/plugins/marketplace.json",
+        ".github/plugin/**",
+        "com.github.copilot/**",
+        "skills/**",
+        ".plugin/pins.json"
+      ]
+    }],
+    "@semantic-release/github"
+  ]
+}
+```
+
+With no `package.json`, `universal-plugin` is not installed, so the command runs it through `npx`.
+Pin it to the CLI version this skill ships with, as shown. The `upgrade-plugin` skill moves that pin
+later.
+Where the repository does install `universal-plugin` as a devDependency, use the bare
+`universal-plugin` instead.
+
+### A plugin that ships on npm
+
+Keep `@semantic-release/npm` and add the other two after it:
+
+```json
+["@semantic-release/npm"],
+["@semantic-release/exec", { "prepareCmd": "universal-plugin plugin version ${nextRelease.version}" }],
+["@semantic-release/git", { "assets": ["package.json", "plugin.json", "..."] }]
+```
+
+Setting `assets` replaces the git plugin's default list, which holds `package.json`,
+`package-lock.json`, `npm-shrinkwrap.json`, and `CHANGELOG.md`. List again each of those the
+repository needs, alongside the plugin files above.
+
+### Assets
+
+`plugin version` rewrites `plugin.json` and the skill pins, and then re-derives every vendor
+manifest and repository catalog. Commit all of them, or the repository's files disagree with the
+tag. The list above covers every place the CLI writes. A glob that matches nothing adds nothing, so
+the whole list is safe to keep for a plugin that does not declare every vendor. Under a plugin root
+below the repository root, prefix the plugin's own paths with that root. The catalogs
+(`.claude-plugin/marketplace.json`, `.cursor-plugin/marketplace.json`,
+`.agents/plugins/marketplace.json`, `.github/plugin/marketplace.json`) stay at the repository root.
+Add the mcp file when the plugin declares one.
+
+The git plugin's default commit message ends in `[skip ci]`, so the commit back does not start
+another release.
+
+### Applying it
+
+1. Edit the config file the survey found, in its own format. For a JavaScript config, edit the
+   `plugins` array in place. If no config exists, write `.releaserc.json`.
+2. Keep every plugin the user already lists, and keep their order relative to each other.
+3. Show the before and after `plugins` list in the Phase 3 plan. Apply only once the user approves.
+4. Name the packages the release job must install: `@semantic-release/exec` and
+   `@semantic-release/git`. The `--no-ci` local run, and the CI job that runs semantic-release, both
+   need them. Installing them is the user's step. Do not edit the CI workflow (SKILL.md Rules).
+
+## release-it
+
+release-it runs its `after:bump` hook after it settles the new number and before its release
+commit and tag. That commit stages every tracked file the hook changed (`git add . --update`), so
+the stamp ships in the tagged commit with no extra plugin. `${version}` in a hook is the new number.
+
+### A plugin that ships to no npm package
+
+Set `"npm": false`. release-it then ignores `package.json`, needs none, and reads the current version
+from the latest git tag. Add the stamp as the `after:bump` hook:
+
+```json
+{
+  "npm": false,
+  "hooks": {
+    "after:bump": "npx universal-plugin@0.18.0 plugin version ${version}"
+  }
+}
+```
+
+With no `package.json`, `universal-plugin` is not installed, so the hook runs it through `npx`. Pin
+it to the CLI version this skill ships with, as shown. The `upgrade-plugin` skill moves that pin
+later.
+
+### A plugin that ships on npm
+
+Keep release-it's npm plugin. It bumps `package.json`, and the hook then stamps the same number into
+the plugin:
+
+```json
+{
+  "hooks": { "after:bump": "universal-plugin plugin version ${version}" }
+}
+```
+
+Use the bare `universal-plugin` when the repository installs it as a devDependency, as an
+npm-shipped plugin usually does. Otherwise use the pinned `npx` form above. Here release-it reads
+the current version from `package.json`, so the first release needs no tag.
+
+Add `--root <plugin-root>` to the hook when release-it runs from a directory other than the plugin
+root.
+
+### The first release needs a tag
+
+With `"npm": false`, release-it reads the current number from the latest tag, never from
+`plugin.json`. With no tag it starts from `0.0.0`, proposes `0.0.1`, and the stamp refuses a number
+that does not advance on the version `plugin.json` holds. The release then fails.
+
+So, when the plugin ships to no npm package, check for a tag in the Phase 3 plan:
+
+```bash
+git describe --tags --abbrev=0
+```
+
+If that finds no tag, propose tagging the current commit with the version `plugin.json` holds, and
+create the tag once the user approves:
+
+```bash
+git tag v1.2.0
+```
+
+- Use `v<version>` unless the repository already tags in another form. release-it names its next
+  tag after the latest one, so the first tag sets the form every later release keeps.
+- A lightweight tag is enough. release-it finds it with `git describe --tags`.
+- Tag the commit whose `plugin.json` holds that version, and only after the plugin's files are
+  committed. Do not move or replace an existing tag.
+- The tag is local until pushed. A release that runs in CI needs it on the remote. Pushing it is the
+  user's step, so name `git push origin v1.2.0` and run it only if the user asks.
+- If the user declines, say the first release fails until a tag on the current version exists.
+
+### Applying it
+
+1. Edit the config the survey found, in its own format: a `.release-it.*` file, or the `release-it`
+   key in `package.json`. If none exists, write `.release-it.json`.
+2. Keep every key the user already set. If an `after:bump` hook already exists, keep its command and
+   run the stamp after it: a string becomes an array of both commands. Show the hooks before and
+   after in the Phase 3 plan. Apply only once the user approves.
+3. For a plugin that ships to no npm package, set `"npm": false`, and handle the tag as above.
+4. Commit the plugin's generated files (`plugin.json`, the vendor manifests, the catalogs,
+   `.plugin/pins.json`) before the first release. The release commit stages only tracked files, so
+   a stamped file git does not track yet stays out of the tagged commit.
+5. Installing release-it is the user's step. Do not edit the CI workflow (SKILL.md Rules).
+
+`doctor` reports `release-it-no-stamp` for a release-it config that never runs `plugin version`.
+
+## release-please
+
+release-please runs no command before its release commit. Its release PR moves the number in the
+files it knows, and a workflow step on that PR then restamps the plugin. The wiring is two files the
+skill writes, and one workflow step the user adds.
+
+### A plugin that ships to no npm package
+
+`release-type: simple` keeps the number in `.release-please-manifest.json`, and `extra-files` bumps
+`plugin.json`. Write `release-please-config.json`:
+
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "extra-files": [{ "type": "json", "path": "plugin.json", "jsonpath": "$.version" }]
+    }
+  }
+}
+```
+
+The restamp step runs `npx -y universal-plugin@0.18.0 plugin version --from-manifest`, which takes
+the number `plugin.json` already holds. Pin it to the CLI version this skill ships with.
+
+### A plugin that ships on npm
+
+`release-type: node` bumps `package.json`. The restamp step runs
+`universal-plugin plugin version --from-package` instead. Do not add `plugin.json` to `extra-files`
+here: the package owns the number, and `--from-package` carries it into the plugin.
+
+### The manifest holds the current version
+
+release-please reads the last release from `.release-please-manifest.json`. A package with no entry
+starts from a default version, not from the plugin's. Write the entry with the version `plugin.json`
+holds, keyed by the package path:
+
+```json
+{ ".": "1.2.0" }
+```
+
+For a plugin below the repository root, use its path as the key in both files (`"packages/my-plugin"`),
+and make `extra-files` paths relative to that package.
+
+### The workflow step
+
+The `version` skill's section *release-please with no `package.json`* has the workflow: a GitHub
+App token minted for the run, the release-please action given that token, then a checkout of the
+release PR branch with the same token, the restamp, and a commit pushed back. Show it in the plan and
+hand it to the user. Do not write or edit the workflow (SKILL.md Rules). For an npm-shipped plugin,
+the step runs `--from-package` in place of `--from-manifest`.
+
+The token matters. A push made with the default `GITHUB_TOKEN` starts no workflow run, so the
+release PR's checks never run on its head commit and a required check blocks the merge. Tell the
+user the App setup the workflow needs: an App with Contents, Pull requests and Issues set to read and
+write, installed on the repository, its client ID in the variable `RELEASE_APP_CLIENT_ID` and a
+private key in the secret `RELEASE_APP_PRIVATE_KEY`. Do not offer a `workflow_dispatch` re-run of CI
+instead: its checks do not count toward a required check.
+
+### Applying it
+
+1. If `release-please-config.json` exists, add `extra-files` to the plugin's package entry and keep
+   every other key. If it does not, write the config above.
+2. Add the plugin's entry to `.release-please-manifest.json`, or write the file. Never lower or
+   replace an entry that already exists: that is the last released version.
+3. Show both files before and after in the Phase 3 plan. Apply only once the user approves.
+4. Hand over the workflow step and the App setup.
+
+`doctor` reports `release-please-no-restamp` when `extra-files` bumps `plugin.json` and no workflow
+runs `plugin version`, and `release-please-restamp-no-ci` when the restamp is pushed with the default
+`GITHUB_TOKEN`.

package/skills/init-universal-plugin/scripts/init.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.18.0","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/add.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.1","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.18.0","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the