universal-plugin 0.11.1 → 0.11.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.2",
 	"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.11.1",
+	"version": "0.11.2",
 	"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.11.1",
+	"version": "0.11.2",
 	"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/dist/cli.mjs

@@ -6392,6 +6392,66 @@ const COPILOT_LSP_PATH = "lsp.json";
 /** Authored under the namespace, never derived: Copilot's canvas extensions have no canonical root
 *  location to derive from, so `--clean` must leave this subtree alone. */
 const COPILOT_AUTHORED_DIR = "extensions";
+/** The component paths each derived manifest accepts. A path on the shared extension reaches every
+*  derived manifest unless the vendor is listed here without it — then the build leaves it out and
+*  warns, as it does for `dependencies` (issue #132). A harness override is applied after this
+*  filter, so `harnesses.<vendor>` can still set any key on purpose.
+*  Each row is what the runtime reads: Claude Code's SchemaStore manifest schema, Cursor's published
+*  `plugin.schema.json`, and Codex's manifest loader, which reads `commands` too (migrated into
+*  skills on install). Codex's plugin-creator validator is narrower — it rejects `hooks` and
+*  `commands` — and is not what the row follows. With a root Agent Plugins `$schema`, Codex reads only
+*  `apps`, `hooks` and `interface` from its manifest and ignores the rest, so the Codex row is the
+*  superset its legacy (no-`$schema`) mode reads (`.research/plugin-schema/evidence.md` E28).
+*  Copilot CLI is absent: it reads the canonical manifest and derives no manifest of its own. */
+const VENDOR_COMPONENTS = {
+	"claude-code": /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"agents",
+		"hooks",
+		"mcpServers",
+		"lspServers",
+		"outputStyles",
+		"themes",
+		"channels",
+		"monitors"
+	]),
+	cursor: /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"agents",
+		"rules",
+		"hooks",
+		"mcpServers"
+	]),
+	codex: /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"apps",
+		"hooks",
+		"mcpServers"
+	])
+};
+/** Every component key some vendor reads. Only these are filtered; any other key on the extension is
+*  not a component and passes through as before. */
+const COMPONENT_KEYS = new Set(Object.values(VENDOR_COMPONENTS).flatMap((set) => [...set ?? []]));
+/** Splits the shared component config into what `vendor` reads and the component keys it has none
+*  of. A vendor without a table entry keeps everything. */
+function vendorComponentConfig(componentConfig, vendor) {
+	const supported = VENDOR_COMPONENTS[vendor];
+	if (!supported) return {
+		config: componentConfig,
+		dropped: []
+	};
+	const config = {};
+	const dropped = [];
+	for (const [key, value] of Object.entries(componentConfig)) if (COMPONENT_KEYS.has(key) && !supported.has(key)) dropped.push(key);
+	else config[key] = value;
+	return {
+		config,
+		dropped
+	};
+}
 /** What each vendor's build output occupies in the published package, for `plugin init --npm`'s
 *  `package.json` `files` wiring. */
 const VENDOR_SHIPPED_PATHS = {
@@ -6501,9 +6561,10 @@ function buildPlugin(root, opts = {}) {
 		const outputPath = path.join(root, relPath);
 		const outputDir = path.dirname(outputPath);
 		const vendorFields = harnesses[vendor] ?? {};
+		const components = vendorComponentConfig(componentConfig, vendor);
 		const vendorManifest = {
 			...metadata,
-			...componentConfig,
+			...components.config,
 			...vendorFields
 		};
 		const hooks = canonicalHooks ? translateHooks(canonicalHooks, vendor) : null;
@@ -6515,7 +6576,7 @@ function buildPlugin(root, opts = {}) {
 			if (mcp?.changed) warnings.push(`${vendor} reads the canonical plugin.json directly — the pinned mcpServers is not delivered to it`);
 			const overrides = Object.keys(vendorFields);
 			if (overrides.length > 0) warnings.push(`harnesses.${vendor} sets ${overrides.join(", ")}, but ${vendor} reads the canonical plugin.json directly — these fields are not delivered`);
-			writeSkillArtifacts(vendor, skills, opts, written, warnings);
+			writeSkillArtifacts(vendor, skills, opts, written);
 			const derived = deriveCopilotNamespace(root, componentConfig, hooks, indent, opts, written, warnings);
 			rows.push(derived ? {
 				vendor,
@@ -6528,6 +6589,7 @@ function buildPlugin(root, opts = {}) {
 			});
 			continue;
 		}
+		for (const key of components.dropped.filter((k) => !(k in vendorFields))) warnings.push(`${vendor} has no "${key}" component — the path is left out of ${relPath}`);
 		for (const drop of dedupeDrops(hooks?.drops ?? [])) warnings.push(`${vendor} cannot run the "${drop.type}" hook handler on ${drop.event} — dropped from the derived hooks file`);
 		const derivedHooksPath = path.join(outputDir, "hooks.json");
 		if (hooks?.changed) {
@@ -6555,7 +6617,7 @@ function buildPlugin(root, opts = {}) {
 				else if (!opts.dryRun && fs.existsSync(derivedHooksPath)) fs.unlinkSync(derivedHooksPath);
 			}
 			if (mcp?.changed && declaredMcp && !declaredMcp.inline) writeArtifact(derivedMcpPath, `${JSON.stringify({ mcpServers: mcp.servers }, null, indent)}\n`, opts, written);
-			writeSkillArtifacts(vendor, skills, opts, written, warnings);
+			writeSkillArtifacts(vendor, skills, opts, written);
 			rows.push({
 				vendor,
 				path: relPath,
@@ -6643,20 +6705,9 @@ function refreshCatalogs(root, manifest, vendors, opts, written, warnings) {
 		catalogRoot: repo.root
 	} : { catalogs: rows };
 }
-function writeSkillArtifacts(vendor, skills, opts, written, warnings) {
-	for (const skill of skills) {
-		if (vendor === "claude-code") {
-			writeClaudeSkill(skill, opts, written);
-			continue;
-		}
-		if (vendor === "cursor") continue;
-		if (skill.invocationPolicy === "model") continue;
-		if (vendor === "codex") try {
-			writeArtifact(path.join(os.homedir(), ".codex", "prompts", `${skill.name}.md`), skill.body, opts, written);
-		} catch (err) {
-			warnings.push(`Failed to write Codex prompt for skill "${skill.name}" (best-effort): ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
+function writeSkillArtifacts(vendor, skills, opts, written) {
+	if (vendor !== "claude-code") return;
+	for (const skill of skills) writeClaudeSkill(skill, opts, written);
 }
 /** Resolves a `pathValue` declaration — a single "./" path, an array of them, or a { paths: [...] }
 *  object — into the list of declared paths. Returns null when the field is absent or malformed, so
@@ -7664,7 +7715,7 @@ function initCommand$1(deps = { fs: realInitFs }) {
 	return cmd;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@cyberuni+agent-harness@0.1.0/node_modules/@cyberuni/agent-harness/dist/index.js
+//#region ../../node_modules/.pnpm/@cyberuni+agent-harness@0.3.0/node_modules/@cyberuni/agent-harness/dist/index.js
 const harnessIds = [
 	"claude-code",
 	"cursor",
@@ -7675,7 +7726,10 @@ const harnessIds = [
 	"gemini-cli",
 	"qwen-code",
 	"vscode-copilot",
-	"cline"
+	"cline",
+	"crush",
+	"openhands",
+	"augment"
 ];
 function resolveHarnessEnvironment(environment = {}) {
 	return {
@@ -7896,6 +7950,50 @@ const storages = {
 				research: "E-CLINE-P3"
 			}]
 		};
+	},
+	crush: ({ env, homedir }) => {
+		return {
+			harness: "crush",
+			configDir: env.CRUSH_GLOBAL_CONFIG || join(env.XDG_CONFIG_HOME || join(homedir, ".config"), "crush"),
+			locations: []
+		};
+	},
+	openhands: ({ env, homedir }) => {
+		const configDir = env.OH_PERSISTENCE_DIR || env.OPENHANDS_PERSISTENCE_DIR || join(homedir, ".openhands");
+		const installed = join(configDir, "plugins", "installed");
+		return {
+			harness: "openhands",
+			configDir,
+			locations: [{
+				kind: "installed-plugins",
+				path: installed,
+				description: "Installed plugins, one folder each",
+				research: "E-OH-P3"
+			}, {
+				kind: "enabled-record",
+				path: join(installed, ".installed.json"),
+				description: "Install metadata keyed by plugin name, each with enabled: <bool>",
+				research: "E-OH-P4"
+			}]
+		};
+	},
+	augment: ({ homedir }) => {
+		const configDir = join(homedir, ".augment");
+		return {
+			harness: "augment",
+			configDir,
+			locations: [{
+				kind: "marketplaces",
+				path: join(configDir, "plugins", "marketplaces"),
+				description: "Marketplace checkouts",
+				research: "E-AUG-P2"
+			}, {
+				kind: "enabled-record",
+				path: join(configDir, "settings.json"),
+				description: "User settings; enabledPlugins maps plugin@marketplace to a boolean",
+				research: "E-AUG-P4"
+			}]
+		};
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -39,8 +39,8 @@
     "agents"
   ],
   "dependencies": {
-    "@cyberuni/agent-harness": "^0.1.0",
-    "@repobuddy/upx": "^0.1.0",
+    "@cyberuni/agent-harness": "^0.3.0",
+    "@repobuddy/upx": "^0.2.0",
     "@toon-format/toon": "^4.1.1",
     "commander": "^14.0.3",
     "semver": "^7.8.1"

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.2",
 	"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/references/slash-invocation.md

@@ -23,7 +23,7 @@ Deploy $ARGUMENTS.
 
 - 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.
-- Codex receives a best-effort, local-only `~/.codex/prompts/<skill>.md` for `user` and `both` skills. Codex has deprecated custom prompts, so the skill remains the primary integration.
+- 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.
 
 If a workflow requires deterministic user-triggered invocation, document Copilot

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

@@ -77,6 +77,7 @@ Each `code` below is what the script emits.
 | `stale` | a derived manifest older than `plugin.json` | `universal-plugin plugin build` |
 | `hand-edited` | a derived manifest that `build` would rewrite — the edit is already lost, it just has not been overwritten yet | move the field to the canonical manifest or to `harnesses.<vendor>`, then rebuild |
 | `unknown-vendor` | a `vendors` entry no build target matches; reported as `skipped` plus a warning | fix the id in `plugin.json` |
+| `unsupported-component` | a component path on the shared extension names a component one targeted vendor has none of (`agents` for Codex, `rules` for Claude Code, …); the build leaves it out of that vendor's manifest | declare the path under `harnesses.<vendor>` for the vendors that read it, or leave it — nothing is lost |
 | `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init-universal-plugin`, update route — move them to a vendor that has a derived manifest, or drop them |
 | `codex-fields-missing` | Codex is targeted without `version` or `description`; the build fails and writes **nothing at all**, including for the other vendors | add both to the canonical top level |
 | `version-drift` | the `packagePath` `package.json` and the canonical manifest carry different versions | `/universal-plugin:version` |

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

@@ -232,6 +232,13 @@ if (build === null) {
 				'no vendor is declared — the build writes nothing, so no runtime reads this plugin',
 				'/universal-plugin:init-universal-plugin, update route',
 			)
+		} else if (/has no "[^"]+" component/.test(warning)) {
+			add(
+				'unsupported-component',
+				'low',
+				warning,
+				'declare the path under harnesses.<vendor> for the vendors that read it, or leave it — the build already drops it',
+			)
 		} else if (/^Unknown vendor/.test(warning)) {
 			add('unknown-vendor', 'medium', warning, 'fix the vendor id in plugin.json')
 		} else {

package/skills/init-universal-plugin/references/vendors/claude-code.md

@@ -8,7 +8,8 @@ npx universal-plugin plugin build --vendor claude-code
 
 ## What lands in the derived manifest
 
-The shared metadata from the canonical top level, plus the component paths, plus whatever
+The shared metadata from the canonical top level, plus the component paths Claude Code reads (every
+one except `rules` and Codex's `apps`; the build drops those with a warning), plus whatever
 `extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"]` sets. `$schema`, `extensions`,
 `vendors`, and `harnesses` are universal-plugin's own orchestration — they never
 appear in a vendor manifest.

package/skills/init-universal-plugin/references/vendors/codex.md

@@ -33,14 +33,35 @@ Codex's presentation metadata goes under its `harnesses` entry:
 }
 ```
 
-## Skills
+## Components
+
+What Codex reads from `.codex-plugin/plugin.json` depends on the root `plugin.json`:
+
+- **Root declares the canonical `$schema`** (`https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`,
+  the normal universal-plugin layout). Codex reads root `plugin.json` as an Agent Plugins manifest,
+  takes skills from `./skills` and MCP servers from `./mcp.json`, and uses `.codex-plugin/plugin.json`
+  only as an overlay for `apps`, `hooks`, and `interface`. Any other key there is ignored, and
+  commands are not read at all.
+- **Root has no `$schema`**. `.codex-plugin/plugin.json` is the manifest. Codex reads `skills`,
+  `commands`, `hooks`, `mcpServers`, and `apps` from it, and migrates each command into a skill on
+  install, falling back to `./commands/` when `commands` is absent.
 
-For every skill that is not `invocation-policy: model`, the build also writes
-`~/.codex/prompts/<name>.md` — the skill body, as a Codex prompt.
+Codex has no `agents`, `rules`, `lspServers`, `outputStyles`, `themes`, `channels`, or `monitors` in
+either case. `plugin build` leaves any of those out of `.codex-plugin/plugin.json` and warns
+(`codex has no "agents" component — the path is left out of .codex-plugin/plugin.json`); the other
+vendors still get the path. Set the path under `harnesses.codex` only if you mean Codex to see it
+anyway — a harness override is never filtered.
+
+The Codex runtime ignores keys it does not read. The plugin-creator validator Codex ships
+(`validate_plugin.py`) is stricter: it rejects any field outside its allowlist, including `commands`
+and `hooks`. That matters only if you submit the plugin through OpenAI's ingestion flow.
+
+## Skills
 
-Two things follow. It writes **outside the repository**, into the current machine's home directory,
-so it is not part of the plugin's tracked output and does not travel with a clone. And it is
-**best-effort**: a failure there becomes a build warning, not a failed build. Read the warnings.
+Codex reaches a plugin's skills natively. A user invokes one with `$name` or `/skills`, so the
+build derives nothing per skill for Codex. Codex custom prompts (`~/.codex/prompts/`) are deprecated
+and load only from the user's home directory, and the build never writes there. See
+[`codex-skill-invocation`](https://github.com/cyberuni/universal-plugin/blob/main/.research/codex-skill-invocation/conclusion.md).
 
 ## Hooks
 

package/skills/init-universal-plugin/references/vendors/cursor.md

@@ -22,6 +22,12 @@ Cursor's catalog metadata goes under its `harnesses` entry, not at the canonical
 }
 ```
 
+## Components
+
+Cursor reads `skills`, `commands`, `agents`, `rules`, `hooks`, and `mcpServers`. Its manifest schema
+is closed, so the build leaves `lspServers`, `outputStyles`, `apps`, and Claude Code's other
+components out of `.cursor-plugin/plugin.json` and warns.
+
 ## Skills
 
 Cursor reads `SKILL.md` straight from the path the manifest's `skills` field names, and lets the user