universal-plugin 0.17.0 → 0.18.0

package/references/slash-invocation.md

@@ -10,7 +10,7 @@ description: Deploy the application after running release checks.
 invocation-policy: user
 ---
 
-Deploy $ARGUMENTS.
+Deploy the environment the user names in the invocation.
 ```
 
 | Policy | Meaning | Default |
@@ -22,7 +22,7 @@ Deploy $ARGUMENTS.
 `plugin build` derives vendor behavior from that policy:
 
 - Claude Code uses the same `SKILL.md` and adds its native invocation flag.
-- Cursor receives a thin `.cursor/commands/<skill>.md` prompt insert for `user` and `both` skills.
+- Cursor uses the same `SKILL.md` and its native invocation flag; no per-skill command is derived.
 - Codex uses the skill itself. A user invokes it with `$skill` or `/skills`, so no command is derived. Codex custom prompts are deprecated and home-only, and `plugin build` never writes outside the plugin tree.
 - Copilot CLI receives no derived command. Its `/skill-name` form is only a prompt hint, not deterministic invocation.
 

package/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/rewrite-upx.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/adopt-upx/scripts/rewrite-upx.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/adopt-upx/scripts/rewrite-upx.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 { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 //#region src/skill-scripts/rewrite-upx.ts

package/skills/build-plugin/SKILL.md

@@ -47,7 +47,7 @@ node scripts/build.mjs --root <plugin-root>
 
 Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI the project installed
 (`pnpm exec universal-plugin`), else the CLI pinned to the version this skill shipped with
-(`npx universal-plugin@0.17.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
+(`npx universal-plugin@0.18.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
 must name the directory that holds the canonical `plugin.json`.
 
 The command never prompts, so it is safe to run unattended.
@@ -132,8 +132,7 @@ Validation runs before the first write, so a failed build leaves the tree untouc
 - **Expect a build to pin skill `npx` references or decide a version.** Build derives and copies
   whatever `plugin.json` carries. Stamping is the release-time `plugin version`, not this step.
 - **Expect a build to copy governances into skills.** A skill loads a reference through the
-  `reference` skill in the `cyber-agentkit` plugin; the build does not copy them and has no
-  `--check` flag.
+  `reference` skill in the `cyber-agentkit` plugin; the build does not copy them.
 
 ## Related skills
 

package/skills/build-plugin/scripts/build.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.0","entry":"skills/build-plugin/scripts/build.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/build-plugin/scripts/build.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/doctor-universal-plugin/README.md

@@ -35,7 +35,7 @@ on purpose, so it folds into that command rather than competing with it.
 ## Boundaries
 
 Diagnoses the plugin a project ships. A repository's own agent wiring — `.agents/skills/`,
-`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor`.
+`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor-buddy-agent-harness`.
 
 ## References
 

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

@@ -95,6 +95,14 @@ Each `code` below is what the script emits.
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
 | `package-path-unknown` | the CLI could not report `packagePath` (a version too old to read it), so `version-drift` and `unreleased-content` were skipped rather than guessed | upgrade universal-plugin |
 | `misplaced-package-path` | `plugin.json` declares `packagePath` under `extensions["org.cyberuni.universal-plugin"]`, where the CLI never reads it — the plugin is silently treated as not shipping to npm | move it to `.agents/universal-plugin.json`, relative to the plugin root |
+| `changesets-no-package` | the repository is released with changesets, the plugin ships to no npm package, and its root has no `package.json` — changesets releases only a package, so `changeset version` and `changeset publish` fail | `/universal-plugin:init-universal-plugin` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) — `plugin init` writes a private `package.json` |
+| `changesets-private-untagged` | a non-npm plugin in a changesets repository, and `.changeset/config.json` does not set `"privatePackages": { "version": true, "tag": true }` — `changeset publish` tags no private package, so no release is made | set `privatePackages` in `.changeset/config.json` |
+| `changesets-no-publish-script` | a non-npm plugin in a changesets repository, and a workflow runs `changesets/action` with no `publish-script` (`publish` in v1) — after the Version Packages PR merges the action does nothing, so no tag or GitHub release is made | add `publish-script: pnpm release` to the step, with a `release` script running `changeset publish` |
+| `release-please-no-restamp` | the plugin ships to no npm package, `release-please-config.json` bumps its `plugin.json` through `extra-files`, and no workflow runs `plugin version` — release-please runs no command before its release commit, so 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 running `universal-plugin plugin version --from-manifest` and pushing the stamped files — `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`) has the workflow |
+| `release-please-restamp-no-ci` | a workflow restamps the release PR with `plugin version --from-manifest` and pushes with the default `GITHUB_TOKEN` — that push starts no workflow run, so the PR's checks never run on its head commit and a required check blocks the merge. A `workflow_dispatch` re-run does not fix it: its checks do not count toward a required check | mint a GitHub App token with `actions/create-github-app-token` and pass it as `token:` to `release-please-action` and `actions/checkout` — `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`) has the workflow |
+| `release-it-no-stamp` | a release-it config (`.release-it.*`, or the `release-it` key of `package.json`) has no hook running `plugin version` — release-it commits and tags the release with `plugin.json` and the vendor manifests still on the previous version | add `"hooks": { "after:bump": "universal-plugin plugin version ${version}" }` to the config |
+| `semantic-release-no-stamp` | a semantic-release config (`.releaserc*`, `.config/releaserc*`, `release.config.*`, or the `release` key of `package.json`) has no `@semantic-release/exec` `prepareCmd` running `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` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) wires it |
+| `semantic-release-npm-unshipped` | the plugin ships to no npm package, and its semantic-release config lists `@semantic-release/npm` or relies on the default `plugins` list, which includes it — with no `package.json` the release fails (`ENOPKG`), and with one the plugin still rewrites its version | remove `@semantic-release/npm`, writing the `plugins` list out if the config relies on the defaults — `/universal-plugin:init-universal-plugin` (pnpm install: `pnpm-universal-plugin-init-universal-plugin`) wires it |
 | `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
 | `invalid-catalog` | a marketplace catalog — at the repository root, or at a `--marketplace-root` clone — is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` (pnpm install: `pnpm-universal-plugin-marketplace`) |
 | `marketplace-root-missing` | a `--marketplace-root` path does not exist, so it could not be checked at all | clone the marketplace repository, or fix the path |
@@ -143,7 +151,7 @@ user can run, or ask before running it yourself.
 
 ## Version drift
 
-A version lives in five places. Two are authored: the canonical `plugin.json`, and the `package.json`
+A version lives in six places. Two are authored: the canonical `plugin.json`, and the `package.json`
 at the `packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root.
 The rest are stamped from them by `plugin version`: the vendor manifests, this plugin's entry in each
 repository catalog, the `npx`/`upx <package>@<version>` pins in the skills, and each `mcpServers`
@@ -172,7 +180,7 @@ it does not, offer to add it — ask first, because both are the user's files:
   semantic-release bot opens.
 
 Use the locked `universal-plugin` from the repository's devDependencies when it has one; otherwise
-`npx universal-plugin@0.17.0`, pinned. This check matters most where the release tool picks the
+`npx universal-plugin@0.18.0`, pinned. This check matters most where the release tool picks the
 number, because nothing else runs between that bump and publish.
 
 ## Unreleased content
@@ -187,9 +195,13 @@ The script compares the shipped paths — the canonical manifest, the skills dir
 emits `unreleased-content` for anything committed since. Uncommitted work is not reported; it has not
 shipped.
 
-Two cases are deliberately silent. A plugin that declares `packagePath` is skipped, because there the
-release picks the number ([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §2) and content waiting ahead of the last released version is the
-normal state of a branch. A tree with no git history is skipped rather than guessed at.
+Two cases are deliberately silent. A plugin whose release picks the number is skipped, because
+content waiting ahead of the last released version is the normal state of a branch there
+([ADR-0010](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/design/decisions/0010-version-policy.md) §6). That is a plugin that declares `packagePath`, or a plugin a release tool versions:
+changesets (`.changeset/` and a private or absent plugin-root `package.json`), release-please (its
+config bumps this `plugin.json` through `extra-files`), semantic-release (`.releaserc*`,
+`release.config.*`, or a `release` key in `package.json`), or release-it (a `.release-it.*` file, or a
+`release-it` key in `package.json`). A tree with no git history is skipped rather than guessed at.
 
 The repair is the bump, and it belongs to `/universal-plugin:version` (pnpm install: `pnpm-universal-plugin-version`). Judge first whether the change
 is meant to ship — content that is still being worked on is not a finding to act on.
@@ -203,7 +215,7 @@ is meant to ship — content that is still being worked on is not a finding to a
   directly. Its **components** are a separate question — a `copilot-root-components` finding is a real
   fault, and `canonical` is only healthy for a plugin that declares none of the moved kinds.
 - Do not treat repo-private agent configuration (`.claude/skills/`, `.agents/skills/`) as part of the
-  plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor`.
+  plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor-buddy-agent-harness`.
 
 ## Related skills
 

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.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"}};
+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/README.md

@@ -47,7 +47,7 @@ hold everywhere belongs in the Markdown body. See `references/frontmatter.md`, w
 ## 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
+`.agents/skills/` layout, per-harness bridges — is `buddy-agent-harness:init-buddy-agent-harness`. This skill does not
 touch CI, repository settings, or unrelated project files.
 
 ## References

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

@@ -34,7 +34,7 @@ runtime you are enabling, and only those.
 
 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.
+`buddy-agent-harness:init-buddy-agent-harness`, not this.
 
 ## Prerequisites
 
@@ -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
 
@@ -240,7 +299,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 | 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` |
+| Set a repository up to *consume* skills (`AGENTS.md`, `.agents/skills/`) | `buddy-agent-harness:init-buddy-agent-harness` |
 
 ## References
 

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

@@ -34,7 +34,7 @@ entry in both `vendors` and `harnesses` under
 
 Infer from context; ask only if ambiguous. [`standard.md`](./standard.md) has the component table and
 the layout they go in; the `plugin-design` reference decides which component a given need calls
-for. The universal minimum is `skills/<name>/SKILL.md` plus `.mcp.json`.
+for. The universal minimum is `skills/<name>/SKILL.md` plus `mcp.json`.
 
 ## Step 4 — Scaffold
 
@@ -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.0`. 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
@@ -83,10 +86,10 @@ delivery path at all.
 Run the mechanical validator from the aced **improve-skill** skill:
 
 ```bash
-node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<skill-name>
+node "<path to aced improve-skill>/scripts/validate.mjs" --path skills/<skill-name>
 ```
 
-Fix every CRITICAL finding, then invoke the **audit-skill** skill for the full review.
+Fix every CRITICAL finding, then invoke the `aced:improve-skill` skill for the full review.
 [`frontmatter.md`](./frontmatter.md) covers what has to hold across runtimes.
 
 ## Step 7 — Build
@@ -98,8 +101,8 @@ npx universal-plugin plugin build
 Useful flags: `--dry-run` to see the plan, `--verbose` for field-by-field decisions, `--vendor <id>`
 for one target, `--clean` to delete derived manifests first.
 
-Read the warnings. An unknown vendor id, an undeliverable Copilot override, and a failed Codex prompt
-write all surface there rather than as errors.
+Read the warnings. An unknown vendor id and an undeliverable Copilot override both surface there
+rather than as errors.
 
 ## Step 8 — Install locally to test
 
@@ -113,7 +116,7 @@ restart for Claude Code, **Developer: Reload Window** for Cursor. `--list` shows
 without writing; `--vendor <id>` narrows it; `plugin uninstall` removes it again.
 
 Codex and Copilot CLI scan no local plugin directory, so they report as `unsupported`. Reach those
-through a repository-local marketplace — `publish-plugin`.
+through a repository-local marketplace — `marketplace`.
 
 Do not hand-write a symlink for this. The recipe that circulated for it named
 `~/.claude/plugins/local/`, which does not exist, and a symlink into Cursor's local directory is

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

@@ -40,7 +40,7 @@ Only a skill the project *distributes* belongs to a plugin.
 | `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | **No** — repo-private tooling |
 
 If the only skills are in private locations, say nothing about adoption. A repository that configures
-its own agents is not a plugin waiting to happen; `buddy-agent-harness:init` is the skill for that
+its own agents is not a plugin waiting to happen; `buddy-agent-harness:init-buddy-agent-harness` is the skill for that
 side of the line.
 
 ## Making the adoption offer

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

@@ -30,7 +30,7 @@ universal-plugin reads `invocation-policy` from each `SKILL.md` and projects it
 | --- | --- | --- |
 | `both` (default) | user- and model-invocable | nothing |
 | `user` | explicit invocation only | writes `disable-model-invocation: true` into the skill's frontmatter |
-| `model` | model-invocable only, not user-facing | writes `user-invocable: false`, and emits no Codex prompt |
+| `model` | model-invocable only, not user-facing | writes `user-invocable: false` |
 
 Two consequences worth knowing before you run a build: