universal-plugin 0.17.0 → 0.18.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.0",
+	"version": "0.18.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.0",
+	"version": "0.18.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.17.0",
+	"version": "0.18.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # universal-plugin
 
+## 0.18.0
+
+### Minor Changes
+
+- 760b3d7: `doctor` checks semantic-release wiring. It reports `semantic-release-no-stamp` when the semantic-release config has no `@semantic-release/exec` `prepareCmd` running `plugin version`, and `semantic-release-npm-unshipped` when a plugin that ships to no npm package still runs `@semantic-release/npm`, listed or through the default plugins list.
+- c7739a2: The `init-universal-plugin` skill now wires release-it and release-please when the survey finds them or the user picks them, once the user approves. For release-it it adds an `after:bump` hook running `plugin version ${version}`, sets `"npm": false` for a plugin that ships to no npm package, and offers to tag the current commit with the plugin's version when the repository has no tag, since release-it then reads the current version from the tag. For release-please it writes `release-please-config.json` (`release-type: simple` with an `extra-files` entry for `plugin.json`, or `release-type: node` for an npm package) and seeds `.release-please-manifest.json` with the current version, and it hands the user the workflow step that restamps the release PR. `plugin init` gets no new flag.
+- 9f5f59a: The `init-universal-plugin` skill now wires semantic-release when the survey finds it or the user picks it. Once the user approves, it adds `@semantic-release/exec` running `plugin version ${nextRelease.version}` in `prepare`, and `@semantic-release/git` to commit the stamped files back. For a plugin that ships to no npm package it drops `@semantic-release/npm`. For release-it and release-please, the skill names the stamp each tool must call. The wiring stays in the skill, and `plugin init` gets no new flag.
+- 11c42a6: A plugin that ships to no npm package can now be released with changesets. In a changesets repository with no `package.json` at the plugin root, `plugin init` writes a minimal private one (`name`, `"private": true`, `version`), wires the root `version` script, and adds `"release": "changeset publish"`; `--no-changesets` opts out. `plugin version --from-package` with no package in a changesets repository names that `package.json` and the `privatePackages` setting. `doctor` reports `changesets-no-package`, `changesets-private-untagged`, and `changesets-no-publish-script`.
+- fa31d36: release-it is now a documented release model. With `"npm": false` release-it reads the version from the latest git tag and needs no `package.json`; an `after:bump` hook running `universal-plugin plugin version ${version}` stamps it before the release commit and tag. `doctor` reports `release-it-no-stamp` for a release-it config with no hook running `plugin version`.
+- bea7278: `doctor` reports `release-please-restamp-no-ci` when a 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. The `version` skill's release-please workflow now mints a GitHub App token with `actions/create-github-app-token` and passes it to release-please and to `actions/checkout`.
+- 8e20a28: A plugin that ships to no npm package can now be released with release-please. `plugin version --from-manifest` restamps every place at the version `plugin.json` already holds, for a CI step on the release PR after `extra-files` bumps `plugin.json`; it is refused where `packagePath` is declared. `doctor` reports `release-please-no-restamp` when a release-please config bumps `plugin.json` and no workflow runs `plugin version`. The `version` skill gives the config and the workflow.
+
+### Patch Changes
+
+- 7e8b2e1: `doctor` no longer reports `unreleased-content` for a non-npm plugin that a release tool versions. A plugin released with changesets (through a private `package.json`), release-please (its config bumps `plugin.json`), semantic-release, or release-it is skipped like a plugin that declares `packagePath`, because the tool picks the next number at release time.
+
+## 0.17.1
+
+### Patch Changes
+
+- 7c951cc: `plugin bundle` and `publish sync-version` no longer warn that they are removed "in the next minor release", a release that has already shipped. The warning now says they have been deprecated since 0.14.0 and will be removed in a later release.
+- 621d36d: The `publish-plugin` skill's clone, fork and pull request commands now use the marketplace repo the user chose instead of always naming `cyberuni/cyberplace`.
+- 621d36d: The skill references no longer contradict each other on how the plugin is built and shipped: Copilot CLI reads the canonical `plugin.json` directly, a local install goes through `plugin install` rather than a hand-written symlink, `anthropics/claude-plugins-official` takes no pull requests, the build writes no Cursor command or Codex prompt, `packagePath` lives in `.agents/universal-plugin.json`, and `plugin build` has a `--check` flag.
+- 621d36d: The plugin references and the `agentskills-specialist` agent now say Copilot CLI hooks keep the canonical PascalCase event names, which is what the build writes, instead of camelCase.
+- 621d36d: The skills now name skills that exist: `buddy-agent-harness:init-buddy-agent-harness`, `buddy-agent-harness:doctor-buddy-agent-harness`, `buddy-changesets:changesets`, `aced:improve-skill` and its `validate.mjs` script, and the `marketplace` skill for a repository-local catalog.
+- 621d36d: The plugin references now name `mcp.json` as a plugin's MCP config, the fixed location the build reads, and drop the rule that it must be a symlink to `.mcp.json`.
+- 621d36d: The plugin references and the `agentskills-specialist` agent drop claims nothing backs: a fixed `SKILL.md` section template, a 6,000-character limit for every runtime, a `skill.json`, support for Zed, Continue.dev and Cline, `$ARGUMENTS` expanding everywhere, and dated "next minor release" wording. They also call references references, not governances.
+
 ## 0.17.0
 
 ### Minor Changes

package/agents/agentskills-specialist.md

@@ -14,7 +14,7 @@ model: opus
 # AgentSkills Specialist
 
 ## Role
-You are an expert AgentSkills engineer who designs, audits, and improves skills across Claude Code, Cursor, Codex, GitHub Copilot CLI, Windsurf, Zed, Continue.dev, and Cline runtimes.
+You are an expert AgentSkills engineer who designs, audits, and improves skills across Claude Code, Cursor, Codex, and GitHub Copilot CLI, the runtimes `plugin build` targets. Flag a skill meant for Windsurf as needing conversion, and Zed, Aider, Continue.dev, or Cline as incompatible.
 
 ## Core Responsibilities
 
@@ -32,14 +32,9 @@ skills/<name>/SKILL.md       # Universal skill definition (primary)
 .agents/skills/<name>/SKILL.md  # Project-level extension (if present)
 ```
 
-A `SKILL.md` must include:
-- **Purpose**: One sentence describing what the skill does.
-- **Trigger**: When/how this skill is invoked.
-- **Inputs**: What context or parameters the skill consumes.
-- **Outputs / Side Effects**: What the skill produces or changes.
-- **Steps**: Numbered, concrete procedural steps.
-- **Runtime Notes**: Any known incompatibilities or runtime-specific behavior.
-- **Examples**: At least one concrete invocation example.
+A `SKILL.md` should make clear what the skill does, when it is invoked, what it consumes and
+produces, and the steps it follows, plus runtime limitations and an example where they help. These
+are questions the body answers, not required section names.
 
 ## Auditing Workflow
 
@@ -75,7 +70,7 @@ For skill creation or edits, write the full `SKILL.md` content directly — no p
 ## Key Research Context
 
 - A root `plugin.json` on Agent Plugins Spec 1.0.0 is the universal manifest; `skills/<name>/SKILL.md` is the universal skill entry point.
-- Hook event naming is the sharpest incompatibility: PascalCase (Claude Code, Codex), camelCase (Cursor, Copilot CLI), snake_case (Windsurf).
+- Hook event naming is the sharpest incompatibility: PascalCase (Claude Code, Codex, Copilot CLI), camelCase (Cursor), snake_case (Windsurf).
 - Only Claude Code and Cursor publish machine-readable JSON Schemas.
 
 ## Out of Scope
@@ -87,7 +82,7 @@ For skill creation or edits, write the full `SKILL.md` content directly — no p
 ## Quality Gates
 
 Before declaring any skill complete:
-- [ ] SKILL.md is present and complete per the standard above.
+- [ ] SKILL.md is present and answers the questions above.
 - [ ] No runtime-specific assumptions are baked into the universal layer.
 - [ ] Project-level `.agents/skills/<name>/SKILL.md` extension is merged, not duplicated.
 - [ ] Examples are concrete and runnable.

package/com.github.copilot/agents/agentskills-specialist.agent.md

@@ -14,7 +14,7 @@ model: opus
 # AgentSkills Specialist
 
 ## Role
-You are an expert AgentSkills engineer who designs, audits, and improves skills across Claude Code, Cursor, Codex, GitHub Copilot CLI, Windsurf, Zed, Continue.dev, and Cline runtimes.
+You are an expert AgentSkills engineer who designs, audits, and improves skills across Claude Code, Cursor, Codex, and GitHub Copilot CLI, the runtimes `plugin build` targets. Flag a skill meant for Windsurf as needing conversion, and Zed, Aider, Continue.dev, or Cline as incompatible.
 
 ## Core Responsibilities
 
@@ -32,14 +32,9 @@ skills/<name>/SKILL.md       # Universal skill definition (primary)
 .agents/skills/<name>/SKILL.md  # Project-level extension (if present)
 ```
 
-A `SKILL.md` must include:
-- **Purpose**: One sentence describing what the skill does.
-- **Trigger**: When/how this skill is invoked.
-- **Inputs**: What context or parameters the skill consumes.
-- **Outputs / Side Effects**: What the skill produces or changes.
-- **Steps**: Numbered, concrete procedural steps.
-- **Runtime Notes**: Any known incompatibilities or runtime-specific behavior.
-- **Examples**: At least one concrete invocation example.
+A `SKILL.md` should make clear what the skill does, when it is invoked, what it consumes and
+produces, and the steps it follows, plus runtime limitations and an example where they help. These
+are questions the body answers, not required section names.
 
 ## Auditing Workflow
 
@@ -75,7 +70,7 @@ For skill creation or edits, write the full `SKILL.md` content directly — no p
 ## Key Research Context
 
 - A root `plugin.json` on Agent Plugins Spec 1.0.0 is the universal manifest; `skills/<name>/SKILL.md` is the universal skill entry point.
-- Hook event naming is the sharpest incompatibility: PascalCase (Claude Code, Codex), camelCase (Cursor, Copilot CLI), snake_case (Windsurf).
+- Hook event naming is the sharpest incompatibility: PascalCase (Claude Code, Codex, Copilot CLI), camelCase (Cursor), snake_case (Windsurf).
 - Only Claude Code and Cursor publish machine-readable JSON Schemas.
 
 ## Out of Scope
@@ -87,7 +82,7 @@ For skill creation or edits, write the full `SKILL.md` content directly — no p
 ## Quality Gates
 
 Before declaring any skill complete:
-- [ ] SKILL.md is present and complete per the standard above.
+- [ ] SKILL.md is present and answers the questions above.
 - [ ] No runtime-specific assumptions are baked into the universal layer.
 - [ ] Project-level `.agents/skills/<name>/SKILL.md` extension is merged, not duplicated.
 - [ ] Examples are concrete and runnable.

package/dist/cli.mjs

@@ -8608,10 +8608,31 @@ function ownPackage(state) {
 		json: state.rootPackageJson ?? null
 	};
 }
+/** Changesets releases only what has a `package.json`, so a plugin that ships to no npm package
+*  needs a private one to carry its version (#234). Names the file and the config that makes
+*  `changeset publish` tag it. */
+function changesetsPackageHint(state) {
+	const name = typeof state.manifest?.name === "string" ? state.manifest.name : "<plugin-name>";
+	const version = typeof state.manifest?.version === "string" ? state.manifest.version : "0.0.0";
+	return [
+		"changesets releases only a package, so a plugin that is not published to npm needs a private package.json at the plugin root:",
+		`  ${JSON.stringify({
+			name,
+			private: true,
+			version
+		})}`,
+		"and .changeset/config.json needs \"privatePackages\": { \"version\": true, \"tag\": true } so changeset publish tags the release.",
+		"plugin init writes the package.json when it finds .changeset/."
+	].join("\n");
+}
 /** Reads the version a release tool already wrote into the package. */
 function versionFromPackage(state) {
 	const pkg = ownPackage(state);
-	if (pkg.json === null) throw new Error(state.packagePath === null ? "No package.json to read the version from: packagePath is not set in .agents/universal-plugin.json and the plugin root has no package.json" : `No package.json found at packagePath "${state.packagePath}"`);
+	if (pkg.json === null) {
+		if (state.packagePath !== null) throw new Error(`No package.json found at packagePath "${state.packagePath}"`);
+		const message = "No package.json to read the version from: packagePath is not set in .agents/universal-plugin.json and the plugin root has no package.json";
+		throw new Error(state.changesets ? `${message}\n${changesetsPackageHint(state)}` : message);
+	}
 	const version = pkg.json["version"];
 	if (typeof version !== "string" || version.length === 0) throw new Error(`No version found in ${pkg.path}`);
 	if (version === "0.0.0-development") throw new Error(`${pkg.path} holds the placeholder ${UNSTAMPED_VERSION} — pass the release's version explicitly (plugin version \${nextRelease.version})`);
@@ -8619,15 +8640,33 @@ function versionFromPackage(state) {
 	if (valid === null) throw new Error(`Version "${version}" in ${pkg.path} is not valid semver`);
 	return valid;
 }
-/** Picks the number. Exactly one source: a bump argument or `--from-package`. Under ADR-0010 §2 a
+/** Reads the version a release tool already wrote into the canonical manifest (#238). Under a
+*  declared `packagePath` the package owns the number, so the manifest is not a source there. */
+function versionFromManifest(state, from) {
+	if (state.packagePath !== null) {
+		const pkg = joinRelative(state.packagePath, "package.json");
+		throw new Error(`packagePath is declared, so ${pkg} owns the number, not plugin.json — run plugin version --from-package`);
+	}
+	if (from === null) throw new Error("plugin.json has no version to restamp — pass an explicit version (e.g. 0.1.0) to set the first one");
+	if (from === "0.0.0-development") throw new Error(`plugin.json holds the placeholder ${UNSTAMPED_VERSION} — pass the release's version explicitly`);
+	const valid = import_semver.valid(from);
+	if (valid === null) throw new Error(`Version "${from}" in plugin.json is not valid semver`);
+	return valid;
+}
+/** Picks the number. Exactly one source: a bump argument, `--from-package`, or `--from-manifest`. Under ADR-0010 §2 a
 *  plugin with `packagePath` gets its number from the package, so a release type there is refused —
 *  the explicit and `--from-package` forms stay, because release tools call them. */
 function resolveVersion(state, from, opts) {
+	if (opts.fromPackage && opts.fromManifest) throw new Error("Pass --from-package or --from-manifest, not both");
+	if (opts.fromManifest) {
+		if (opts.bump !== void 0) throw new Error(`Pass a version or --from-manifest, not both (got "${opts.bump}")`);
+		return versionFromManifest(state, from);
+	}
 	if (opts.fromPackage) {
 		if (opts.bump !== void 0) throw new Error(`Pass a version or --from-package, not both (got "${opts.bump}")`);
 		return versionFromPackage(state);
 	}
-	if (opts.bump === void 0) throw new Error(`Pass a release type (${RELEASE_TYPES.join(", ")}), an explicit version, or --from-package`);
+	if (opts.bump === void 0) throw new Error(`Pass a release type (${RELEASE_TYPES.join(", ")}), an explicit version, --from-package, or --from-manifest`);
 	if (state.packagePath !== null && isReleaseType(opts.bump)) {
 		const pkg = joinRelative(state.packagePath, "package.json");
 		throw new Error(`packagePath is declared, so the release picks the number — bump ${pkg} with your release tool (e.g. changeset version), then run plugin version --from-package`);
@@ -8896,6 +8935,10 @@ function gatherMcpFiles(root, declaration) {
 	}
 	return files;
 }
+/** Whether `.changeset/` sits at the plugin root or at the repository root above it. */
+function hasChangesets(root) {
+	return [root, gitToplevel(root)].some((dir) => dir !== void 0 && fs$1.existsSync(path$1.join(dir, ".changeset")));
+}
 function toRelative(root, abs) {
 	return path$1.relative(root, abs).split(path$1.sep).join("/");
 }
@@ -8921,7 +8964,8 @@ const realVersionFs = {
 			})),
 			workspace: Object.fromEntries(discoverWorkspace(root)),
 			mcpFiles: gatherMcpFiles(root, uext["mcpServers"]),
-			pinsMapExists: fs$1.existsSync(path$1.join(root, PINS_MAP_PATH))
+			pinsMapExists: fs$1.existsSync(path$1.join(root, PINS_MAP_PATH)),
+			changesets: hasChangesets(root)
 		};
 	},
 	apply(root, plan) {
@@ -8987,7 +9031,7 @@ const NEXT_STEP$1 = "→ review and commit the pinned skills\n";
 function bundleCommand() {
 	const cmd = new Command("bundle").description("Deprecated: use `plugin version`, which stamps the skill pins");
 	cmd.option("--dry-run", "Resolve and report pins without writing them").option("--full", "Show every pins row without truncation").option("--format <format>", "Output format: json or toon (default: toon)").option("--runner <runner>", "Runner word to emit on rewritten refs: npx or upx (default: preserve each ref's runner)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin bundle --dry-run --full\n").action((opts) => {
-		process.stderr.write("warn: plugin bundle is deprecated and will be removed in the next minor release — use plugin version, which stamps the skill pins\n");
+		process.stderr.write("warn: plugin bundle is deprecated since 0.14.0 and will be removed in a later release — use plugin version, which stamps the skill pins\n");
 		try {
 			const runner = opts.runner;
 			if (runner !== void 0 && runner !== "npx" && runner !== "upx") throw new Error(`error: unknown --runner value "${runner}" (expected npx or upx)`);
@@ -9164,9 +9208,22 @@ function gatherChangesets(root, repo) {
 	if (!fs$1.existsSync(path$1.join(workspace, ".changeset"))) return void 0;
 	return {
 		pluginPath,
-		packageJson: readJson$1(packageJsonPath(workspace))
+		packageJson: readJson$1(packageJsonPath(workspace)),
+		config: readJsonSafe(path$1.join(workspace, ".changeset", "config.json"))
 	};
 }
+function readJsonSafe(file) {
+	try {
+		return readJson$1(file);
+	} catch {
+		return null;
+	}
+}
+/** The version an existing `plugin.json` carries, which a new private package.json is seeded from. */
+function readManifestVersion(root) {
+	const version = readJsonSafe(manifestPath(root))?.version;
+	return typeof version === "string" && version !== "" ? version : void 0;
+}
 function writeJson(file, value) {
 	const existing = fs$1.existsSync(file) ? fs$1.readFileSync(file, "utf8") : void 0;
 	fs$1.writeFileSync(file, formatJson(value, {
@@ -9179,6 +9236,7 @@ const realInitFs = {
 		const repo = gatherRepo(root);
 		return {
 			manifestExists: fs$1.existsSync(manifestPath(root)),
+			manifestVersion: readManifestVersion(root),
 			packageJson: readJson$1(packageJsonPath(root)),
 			repo,
 			changesets: gatherChangesets(root, repo)
@@ -9284,6 +9342,89 @@ function wireChangesets(pkg, pluginPath, cliVersion) {
 	};
 	return { content: next };
 }
+const CHANGESET_PUBLISH = "changeset publish";
+/** The version a private package starts at when the manifest carries none to seed it from. */
+const FIRST_VERSION = "0.0.0";
+/** The package.json a plugin that ships to no npm package needs before changesets can release it
+*  (#234). Changesets finds only packages, and `@changesets/apply-release-plan` always writes
+*  `<dir>/package.json`, so this file is what carries the version. `private` keeps
+*  `changeset publish` to a git tag; no `files`, `main`, or `exports`, because nothing is packed. */
+function privatePackage(name, version) {
+	return {
+		name,
+		private: true,
+		version
+	};
+}
+/** Adds `"release": "changeset publish"`, the script changesets/action runs as its publish step.
+*  For a private package it creates the git tag the GitHub release hangs on. A custom `release`
+*  script is left alone with a note. Returns `null` content when nothing changes. */
+function wireReleaseScript(pkg) {
+	const scripts = typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
+	const script = typeof scripts.release === "string" ? scripts.release : void 0;
+	if (script?.includes(CHANGESET_PUBLISH)) return { content: null };
+	if (script !== void 0) return {
+		content: null,
+		note: `changesets: the root "release" script is custom; make sure it runs "${CHANGESET_PUBLISH}" so a release is tagged`
+	};
+	return { content: {
+		...pkg,
+		scripts: {
+			...scripts,
+			release: CHANGESET_PUBLISH
+		}
+	} };
+}
+/** Whether `.changeset/config.json` has changesets bump and tag private packages. Changesets bumps
+*  them by default but tags them only when `privatePackages.tag` is `true`. */
+function tagsPrivatePackages(config) {
+	const setting = config?.privatePackages;
+	if (typeof setting !== "object" || setting === null) return false;
+	const { version, tag } = setting;
+	return version !== false && tag === true;
+}
+/** Wires a plugin that ships to no npm package for a changesets release: a private package.json at
+*  the plugin root, and the `version` and `release` scripts at the workspace root. Appends to `rows`
+*  and `notes` in place. */
+function planPrivateRelease(opts, name, version, changesets, rows, notes) {
+	const sameFile = changesets.pluginPath === "";
+	let packageJson = privatePackage(name, version);
+	rows.push({
+		path: "package.json",
+		action: "created"
+	});
+	if (sameFile) packageJson = {
+		...packageJson,
+		scripts: { version: CHANGESET_VERSION }
+	};
+	else notes.push(`changesets: ${changesets.pluginPath}/package.json must be a workspace package (pnpm-workspace.yaml or "workspaces") for changesets to release it`);
+	let workspacePackageJson = null;
+	const rootPkg = sameFile ? packageJson : changesets.packageJson;
+	if (rootPkg === null) notes.push(`changesets: no package.json at the workspace root to wire; add a "version" script running "${CHANGESET_VERSION} && ${syncVersionCommand(changesets.pluginPath)}" and a "release" script running "${CHANGESET_PUBLISH}"`);
+	else {
+		const versioned = wireChangesets(rootPkg, changesets.pluginPath, opts.cliVersion);
+		if (versioned.note) notes.push(versioned.note);
+		const released = wireReleaseScript(versioned.content ?? rootPkg);
+		if (released.note) notes.push(released.note);
+		const wired = released.content ?? versioned.content;
+		if (wired && sameFile) packageJson = wired;
+		else if (wired) {
+			workspacePackageJson = {
+				path: `${changesets.pluginPath.split("/").map(() => "..").join("/")}/package.json`,
+				content: wired
+			};
+			rows.push({
+				path: workspacePackageJson.path,
+				action: "updated"
+			});
+		}
+	}
+	if (!tagsPrivatePackages(changesets.config)) notes.push("changesets: set \"privatePackages\": { \"version\": true, \"tag\": true } in .changeset/config.json so changeset publish tags each release");
+	return {
+		packageJson,
+		workspacePackageJson
+	};
+}
 /** The local marketplace a repository carries is named after the repository, not after the plugin:
 *  the catalog sits at the repository root and lists every plugin the repository develops. `-local`
 *  separates it from a published marketplace of the same plugins. */
@@ -9356,9 +9497,12 @@ function planCatalogs(state, opts, manifest, notes) {
 function planInit(state, opts, rootDirName, resolveShippedPaths) {
 	if (opts.npm && state.packageJson === null) throw new Error("error: --npm requires a package.json at the project root");
 	if (state.manifestExists && !opts.force) throw new Error("plugin.json already exists — pass --force to overwrite");
-	const manifest = buildManifest(opts.name ?? rootDirName, opts.vendors);
+	const name = opts.name ?? rootDirName;
+	const manifest = buildManifest(name, opts.vendors);
 	const packageVersion = state.packageJson?.version;
 	if (opts.npm && typeof packageVersion === "string" && packageVersion !== "") manifest.version = packageVersion;
+	const privateVersion = !opts.npm && opts.changesets !== false && state.changesets && state.packageJson === null ? state.manifestVersion ?? FIRST_VERSION : void 0;
+	if (privateVersion !== void 0) manifest.version = privateVersion;
 	const dirs = opts.scaffold ? [...SCAFFOLD_DIRS] : [];
 	const rows = [{
 		path: "plugin.json",
@@ -9384,7 +9528,7 @@ function planInit(state, opts, rootDirName, resolveShippedPaths) {
 		});
 	}
 	let workspacePackageJson = null;
-	const changesets = state.changesets;
+	const changesets = opts.changesets === false ? void 0 : state.changesets;
 	if (opts.npm && changesets) {
 		const sameFile = changesets.pluginPath === "";
 		const rootPkg = sameFile ? packageJson : changesets.packageJson;
@@ -9405,6 +9549,11 @@ function planInit(state, opts, rootDirName, resolveShippedPaths) {
 			}
 		}
 	}
+	if (privateVersion !== void 0 && changesets) {
+		const wired = planPrivateRelease(opts, name, privateVersion, changesets, rows, notes);
+		packageJson = wired.packageJson;
+		workspacePackageJson = wired.workspacePackageJson;
+	}
 	const created = rows.filter((r) => r.action === "created").length;
 	const updated = rows.filter((r) => r.action === "updated").length;
 	const unchanged = rows.filter((r) => r.action === "unchanged").length;
@@ -9431,7 +9580,7 @@ function collect$1(value, previous) {
 }
 function initCommand$1(deps = { fs: realInitFs }) {
 	const cmd = new Command("init").description("Scaffold the canonical plugin.json (with --npm, wire an npm package to ship it)");
-	cmd.option("--name <name>", "Plugin name (default: the root directory name)").option("--vendor <id>", "Target vendor; repeatable", collect$1, []).option("--scaffold", "Create the standard skills/ agents/ references/ commands/ directories").option("--force", "Overwrite an existing plugin.json").option("--yes", "Non-interactive (compatibility no-op; init never prompts)").option("--npm", "Wire package.json to ship the plugin (files, version; changesets version sync)").option("--no-marketplace", "Skip the repository's local marketplace catalogs").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin init --name my-plugin --scaffold\n").action((opts) => {
+	cmd.option("--name <name>", "Plugin name (default: the root directory name)").option("--vendor <id>", "Target vendor; repeatable", collect$1, []).option("--scaffold", "Create the standard skills/ agents/ references/ commands/ directories").option("--force", "Overwrite an existing plugin.json").option("--yes", "Non-interactive (compatibility no-op; init never prompts)").option("--npm", "Wire package.json to ship the plugin (files, version; changesets version sync)").option("--no-marketplace", "Skip the repository's local marketplace catalogs").option("--no-changesets", "Skip the changesets release wiring (private package.json, version and release scripts)").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin init --name my-plugin --scaffold\n").action((opts) => {
 		try {
 			const root = resolveRoot(opts.root);
 			const plan = planInit(deps.fs.gather(root), {
@@ -9441,6 +9590,7 @@ function initCommand$1(deps = { fs: realInitFs }) {
 				force: Boolean(opts.force),
 				npm: Boolean(opts.npm),
 				marketplace: opts.marketplace !== false,
+				changesets: opts.changesets !== false,
 				cliVersion: deps.version
 			}, path$1.basename(root), (vendor) => VENDOR_SHIPPED_PATHS[vendor] ?? []);
 			deps.fs.apply(root, plan);
@@ -18114,12 +18264,13 @@ function prepareCommand() {
 //#region src/version/cli.ts
 function versionCommand(deps = { fs: realVersionFs }) {
 	const cmd = new Command("version").description("Stamp the plugin version into every file that carries one").argument("[bump]", `Release type (${RELEASE_TYPES.join(", ")}) or an explicit version (1.4.0)`);
-	cmd.option("--from-package", "Take the version the package's package.json already holds (changesets, release-please)").option("--preid <id>", "Prerelease identifier for the pre* release types").option("--force", "Allow a version that does not advance on the current one").option("--no-build", "Skip re-deriving the vendor manifests").option("--dry-run", "Print what would be written without writing").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", [
+	cmd.option("--from-package", "Take the version the package's package.json already holds (changesets, release-please)").option("--from-manifest", "Restamp every place with the version plugin.json already holds (release-please extra-files)").option("--preid <id>", "Prerelease identifier for the pre* release types").option("--force", "Allow a version that does not advance on the current one").option("--no-build", "Skip re-deriving the vendor manifests").option("--dry-run", "Print what would be written without writing").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", [
 		"",
 		"Examples:",
 		"  $ universal-plugin plugin version minor            # plain repository: the author picks",
 		"  $ universal-plugin plugin version 1.4.0            # semantic-release: prepareCmd",
-		"  $ universal-plugin plugin version --from-package   # changesets / release-please",
+		"  $ universal-plugin plugin version --from-package   # changesets / release-please, npm package",
+		"  $ universal-plugin plugin version --from-manifest  # release-please, plugin.json bumped by extra-files",
 		""
 	].join("\n")).action((bump, opts) => runVersion(bump, opts, deps.fs));
 	return cmd;
@@ -18132,6 +18283,7 @@ function runVersion(bump, opts, versionFs = realVersionFs) {
 		const plan = planVersion(versionFs.gather(root), {
 			...bump === void 0 ? {} : { bump },
 			fromPackage: Boolean(opts.fromPackage),
+			fromManifest: Boolean(opts.fromManifest),
 			...opts.preid === void 0 ? {} : { preid: opts.preid },
 			force: Boolean(opts.force)
 		});
@@ -18303,7 +18455,7 @@ function stringField(value, key) {
 function publishCommand() {
 	const cmd = new Command("publish").description("Prepare plugin for publishing").helpCommand(false);
 	cmd.command("sync-version").description("Deprecated: use `plugin version --from-package`").option("--no-build", "Skip re-deriving the vendor manifests").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).action((opts) => {
-		process.stderr.write("warn: publish sync-version is deprecated and will be removed in the next minor release — use plugin version --from-package\n");
+		process.stderr.write("warn: publish sync-version is deprecated since 0.14.0 and will be removed in a later release — use plugin version --from-package\n");
 		runVersion(void 0, {
 			...opts,
 			fromPackage: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.17.0",
+	"version": "0.18.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -74,7 +74,7 @@ npx universal-plugin publish check-version            # fail when any place carr
 ```
 
 `publish sync-version` and `plugin bundle` are deprecated aliases of `plugin version --from-package`
-and `plugin version`. They print a warning and are removed in the next minor release.
+and `plugin version`. They print a warning and will be removed in a later release.
 
 ### marketplace
 

package/references/plugin-design.md

@@ -1,12 +1,12 @@
 # Plugin Design
 
-Authoritative rules for creating, validating, and transforming cross-vendor agent plugins. Apply when creating, auditing, or distributing a plugin; see **skill-design** governance for standalone skill authoring rules.
+Authoritative rules for creating, validating, and transforming cross-vendor agent plugins. Apply when creating, auditing, or distributing a plugin; see the **skill-design** reference for standalone skill authoring rules.
 
 A **plugin** is the distribution unit — it bundles skills, MCP servers, hooks, commands, agents, and other extensions into a single installable package. A **skill** is the capability unit inside a plugin. Install plugins; invoke skills.
 
 ## Source of Truth: root `plugin.json`
 
-Author `plugin.json` at the plugin root as the canonical manifest — the Agent Plugins Specification v1.0.0 shape (closed field set, `additionalProperties: false`). All vendor manifests are derived from it via `build`. This file is never read directly by vendors at runtime; it is the single source that the build layer transforms into each vendor's manifest.
+Author `plugin.json` at the plugin root as the canonical manifest — the Agent Plugins Specification v1.0.0 shape (closed field set, `additionalProperties: false`). All vendor manifests are derived from it via `build`. GitHub Copilot CLI reads this file directly at runtime; every other vendor reads the manifest the build layer derives from it.
 
 Schema declaration (first field, fixed by the spec):
 
@@ -98,8 +98,7 @@ Vendor-specific extension fields:
 │
 ├── hooks/hooks.json              ← canonical hooks (PascalCase, ${PLUGIN_ROOT})
 │
-├── .mcp.json                     ← source of truth (all vendors)
-├── mcp.json -> .mcp.json         ← symlink (Cursor + open-plugin-spec)
+├── mcp.json                      ← MCP config (fixed location, all vendors)
 │
 └── README.md
 ```
@@ -141,11 +140,11 @@ Build reads root `plugin.json`, applies the rules below, writes each vendor's ou
 | Canonical field | Claude Code | Cursor | Codex | Copilot CLI |
 | --- | --- | --- | --- | --- |
 | `skills` | ✓ | ✓ | ✓ | ✓ |
-| `mcpServers` | ✓ → `./.mcp.json` | adapt → `./mcp.json` (symlink) | ✓ → `./.mcp.json` | ✓ |
+| `mcpServers` | ✓ → `./mcp.json` | ✓ → `./mcp.json` | ✓ → `./mcp.json` | ✓ |
 | `commands` | ✓ | ✓ | **omit** | ✓ |
 | `agents` | ✓ | ✓ | **omit** | ✓ |
 | `rules` | **omit** | ✓ | **omit** | **omit** |
-| `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | adapt → camelCase, pass-through env |
+| `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | ✓ → PascalCase (selects the Claude-compatible payload) |
 | `lspServers` | ✓ | **omit** | **omit** | **omit** |
 | `outputStyles` | ✓ | **omit** | **omit** | **omit** |
 | `dependencies` | ✓ | **drop + warn** | **drop + warn** | **drop + warn** |
@@ -193,15 +192,15 @@ Canonical hooks file uses **PascalCase** event names. Build translates per vendo
 
 | Canonical (PascalCase) | Claude Code | Cursor | Codex | Copilot CLI |
 | --- | --- | --- | --- | --- |
-| `PreToolUse` | `PreToolUse` | `preToolUse` | `PreToolUse` | `preToolUse` |
-| `PostToolUse` | `PostToolUse` | `postToolUse` | `PostToolUse` | `postToolUse` |
+| `PreToolUse` | `PreToolUse` | `preToolUse` | `PreToolUse` | `PreToolUse` |
+| `PostToolUse` | `PostToolUse` | `postToolUse` | `PostToolUse` | `PostToolUse` |
 | `PostToolUseFailure` | `PostToolUseFailure` | — (drop+warn) | — (drop+warn) | — (drop+warn) |
-| `SessionStart` | `SessionStart` | `sessionStart` | `SessionStart` | `sessionStart` |
-| `SessionEnd` | `SessionEnd` | `sessionEnd` | `SessionEnd` | `sessionEnd` |
-| `Stop` | `Stop` | — (drop+warn) | — (drop+warn) | `agentStop` |
+| `SessionStart` | `SessionStart` | `sessionStart` | `SessionStart` | `SessionStart` |
+| `SessionEnd` | `SessionEnd` | `sessionEnd` | `SessionEnd` | `SessionEnd` |
+| `Stop` | `Stop` | — (drop+warn) | — (drop+warn) | `Stop` |
 | `UserPromptSubmit` | `UserPromptSubmit` | `beforeSubmitPrompt` | — (drop+warn) | — (drop+warn) |
-| `Notification` | `Notification` | — (drop+warn) | — (drop+warn) | `notification` |
-| `PermissionRequest` | `PermissionRequest` | — (drop+warn) | — (drop+warn) | `permissionRequest` |
+| `Notification` | `Notification` | — (drop+warn) | — (drop+warn) | `Notification` |
+| `PermissionRequest` | `PermissionRequest` | — (drop+warn) | — (drop+warn) | `PermissionRequest` |
 | `SubagentStart` | — | `subagentStart` | — | — |
 | `SubagentStop` | — | `subagentStop` | — | — |
 | `PreCompact` | `PreCompact` | `preCompact` | — | — |
@@ -230,20 +229,9 @@ Events not in this table: pass through for `claude-code`; drop + warn for all ot
 
 Build generates vendor-specific versions. Do not hand-author the generated hook files.
 
-## MCP: Symlink Rule
+## MCP: `mcp.json`
 
-`.mcp.json` is the source of truth. `mcp.json` is always a symlink — never a regular file.
-
-```bash
-ln -sf .mcp.json mcp.json
-```
-
-| Runtime | Reads |
-| --- | --- |
-| Claude Code, Codex | `.mcp.json` |
-| Cursor, open-plugin-spec | `mcp.json` (via symlink) |
-
-If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattributes`. MCP server startup failures are non-fatal.
+`mcp.json` at the plugin root is the Agent Plugins Specification's fixed MCP location, Author it as a regular file. `build` points each derived manifest at it, unless it has to change an entry for that vendor; then it writes the changed copy beside the vendor manifest. MCP server startup failures are non-fatal.
 
 ### Pinning a self-published server to the plugin version
 
@@ -271,9 +259,9 @@ A plugin whose MCP server is its own npm package writes an unpinned invocation
 
 ## Component Authoring Rules
 
-**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** governance. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`. Use the **slash-invocation** governance when a skill needs a user-only, model-only, or explicit both-invocation policy.
+**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** reference. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`. Use the **slash-invocation** reference when a skill needs a user-only, model-only, or explicit both-invocation policy.
 
-**Commands:** One `.md` file per command in `commands/`. Filename (minus extension) is the command identifier. Optional frontmatter: `description`, `argument-hint`, `allowed-tools`, `disable-model-invocation`. `$ARGUMENTS` expands to user input.
+**Commands:** One `.md` file per command in `commands/`. Filename (minus extension) is the command identifier. Optional frontmatter: `description`, `argument-hint`, `allowed-tools`, `disable-model-invocation`. `$ARGUMENTS` expands to user input on Claude Code and stays literal on other runtimes.
 
 **Agents:** One `.md` file per agent in `agents/`. Required frontmatter: `name` (1–64 lowercase alphanumeric + hyphens), `description` (≤ 1024 chars). Body is the agent system prompt.
 
@@ -306,9 +294,9 @@ A plugin whose MCP server is its own npm package writes an unpinned invocation
 
 | Scope | Claude Code | Cursor | Codex |
 | --- | --- | --- | --- |
-| **Personal** | `~/.claude/plugins/local/<name>` symlink | `~/.cursor/plugins/local/<name>` symlink + reload | `~/.agents/plugins/marketplace.json` |
+| **Personal** | `universal-plugin plugin install`, then restart | `universal-plugin plugin install` (copies), then reload the window | `~/.agents/plugins/marketplace.json` |
 | **Team** | npm private package | Cursor Teams admin import | `.agents/plugins/marketplace.json` in repo |
-| **Public** | PR to `anthropics/claude-plugins-official` | `cursor.com/marketplace/publish` | `codex plugin marketplace add` |
+| **Public** | `anthropics/claude-plugins-official` is curated and takes no pull requests; check its submission route live (`publish-plugin`, step 0c) | `cursor.com/marketplace/publish` | `codex plugin marketplace add` |
 
 Default scope: **team**.
 
@@ -318,13 +306,11 @@ Default scope: **team**.
 
 - Using `../` in any manifest-declared path
 - Hardcoding absolute paths instead of `${PLUGIN_ROOT}` or `${PLUGIN_DATA}`
-- Committing `mcp.json` as a regular file — must always be a symlink to `.mcp.json`
 - Hand-authoring vendor hook files — use canonical `hooks/hooks.json` and let build generate vendor versions
 - Relying on extended component types (commands, rules, agents, hooks) for core functionality — silently ignored on non-supporting hosts
 - Duplicating SKILL.md content in `plugin.json` — the manifest is a path index, never a content mirror
 - Using `rules/` for cross-agent always-on guidance — use AGENTS.md instead
 - Putting role- or task-scoped guidance in always-on context (`rules/` or AGENTS.md) — make it a reference loaded on demand
-- Putting install-time metadata in `plugin.json` instead of `skill.json`
 
 ## Cross-Platform Portability
 
@@ -338,7 +324,7 @@ Default scope: **team**.
 | Windsurf | Needs conversion | 6,000 char/file hard limit; 12,000 chars total |
 | Zed, Aider, Continue.dev, Cline | No | Incompatible formats |
 
-Portability rules for skill bodies: keep each `SKILL.md` body under 6,000 chars; use forward slashes in path references; declare environment requirements in `compatibility` frontmatter; do not embed vendor-specific syntax in skill bodies.
+Portability rules for skill bodies: for a skill that must load in Windsurf, keep the `SKILL.md` body under its 6,000-char limit and move detail into `references/`; use forward slashes in path references; declare environment requirements in `compatibility` frontmatter; do not embed vendor-specific syntax in skill bodies.
 
 ## References