universal-plugin 0.3.1 → 0.4.0

package/skills/init/references/create.md

@@ -0,0 +1,111 @@
+# Create a universal plugin
+
+Scaffold a new plugin from one canonical `plugin.json` and derive a manifest per chosen vendor.
+
+## Step 1 — Gather plugin identity
+
+Ask for what is missing. Every field lands at the canonical top level.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | kebab-case, 1–64 chars, `a-z 0-9 - .` only |
+| `description` | Recommended | one sentence; **required** when targeting Codex |
+| `version` | If publishing | semver; **required** when targeting Codex |
+| `author.name` | Recommended | person or org name |
+| `homepage` | Optional | docs or landing page URL |
+| `repository` | Optional | source repo URL |
+| `license` | Optional | SPDX identifier, e.g. `MIT` |
+| `keywords` | Optional | discovery tags; array of strings |
+
+## Step 2 — Choose vendor targets
+
+Ask which runtimes to support; default to all four if the user is unsure. Each choice becomes an
+entry in both `vendors` and `harnesses` under
+`extensions["org.cyberuni.universal-plugin"]`.
+
+| Vendor ID | Derived manifest | Read before enabling |
+|-----------|------------------|----------------------|
+| `claude-code` | `.claude-plugin/plugin.json` | [`vendors/claude-code.md`](./vendors/claude-code.md) |
+| `cursor` | `.cursor-plugin/plugin.json` | [`vendors/cursor.md`](./vendors/cursor.md) |
+| `codex` | `.codex-plugin/plugin.json` | [`vendors/codex.md`](./vendors/codex.md) |
+| `copilot-cli` | none — reads root `plugin.json` | [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) |
+
+## Step 3 — Choose components
+
+Infer from context; ask only if ambiguous. [`standard.md`](./standard.md) has the component table and
+the layout they go in; `governance show plugin-design` decides which component a given need calls
+for. The universal minimum is `skills/<name>/SKILL.md` plus `.mcp.json`.
+
+## Step 4 — Scaffold
+
+```bash
+node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor --scaffold
+```
+
+Resolve `scripts/init.mjs` against this skill's directory; it runs the CLI that shipped beside it.
+`npx universal-plugin plugin init` is the fallback. Add `--npm` when an npm package ships the plugin,
+which also wires that `package.json`'s `files` to carry the derived manifests.
+
+`init` writes a minimal manifest — `$schema`, `name`, and the vendor list. Fill in the Step 1
+metadata and the `harnesses` overrides by hand afterwards; [`standard.md`](./standard.md) shows the
+finished shape.
+
+Then create the component files from `../assets/templates/`:
+
+| File to create | Template |
+|----------------|----------|
+| `skills/<name>/SKILL.md` | `assets/templates/skill.md` |
+| `commands/<name>.md` | `assets/templates/command.md` |
+| `agents/<name>.md` | `assets/templates/agent.md` |
+| `hooks/hooks.json` | `assets/templates/hooks.json` |
+| `commands/setup.md` (only with `rules/`) | `assets/templates/setup-command.md` |
+
+## Step 5 — Fill in the harness overrides
+
+Only fields one runtime understands go here; shared metadata stays at the top level. See each
+`vendors/<vendor>.md` for what that vendor accepts, and note that a `copilot-cli` entry has no
+delivery path at all.
+
+```json
+"harnesses": {
+  "claude-code": {},
+  "cursor": { "publisher": "<org>", "category": "<category>", "tags": ["<tag>"] },
+  "codex": { "interface": { "displayName": "<Human Name>", "category": "<category>" } },
+  "copilot-cli": {}
+}
+```
+
+## Step 6 — Audit the skills
+
+Run the mechanical validator from the aced **improve-skill** skill:
+
+```bash
+node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<skill-name>
+```
+
+Fix every CRITICAL finding, then invoke the **audit-skill** skill for the full review.
+[`frontmatter.md`](./frontmatter.md) covers what has to hold across runtimes.
+
+## Step 7 — Build
+
+```bash
+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.
+
+## Step 8 — Install locally to test
+
+```bash
+ln -sf "$(pwd)" ~/.claude/plugins/local/<plugin-name>   # Claude Code
+ln -sf "$(pwd)" ~/.cursor/plugins/local/<plugin-name>   # Cursor → Developer: Reload Window
+```
+
+## Next
+
+Shipping it on npm → `migrate-plugin`. Listing it in a marketplace → `publish-plugin`. Releasing a
+number → `/universal-plugin:version`.

package/skills/init/references/detection.md

@@ -0,0 +1,62 @@
+# Detection
+
+What to look for during the survey, and where each finding belongs.
+
+```bash
+ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
+test -f plugin.json && cat plugin.json
+find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
+ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/null
+```
+
+| What you find | What it means | Bucket |
+| --- | --- | --- |
+| root `plugin.json` with `$schema` on `agent-plugins.org` **and** an `extensions` object | already on the open standard | canonical |
+| `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/` manifest **below** a canonical root | build output | derived |
+| a vendor manifest with **no** canonical root `plugin.json` | a vendor-specific plugin | adoptable |
+| root `plugin.json` with neither `$schema` nor `extensions` | a legacy single-vendor manifest now sitting on the canonical path | adoptable |
+| publicly-shipped skills and no manifest of any kind | skills shipped without a plugin | adoptable |
+| `harnesses["copilot-cli"]` carrying fields | no delivery path — the canonical schema is closed | undeliverable |
+| `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | the project's own tooling | not a plugin |
+| `.github/plugin/plugin.json` | a path older builds wrote; shadowed by root and no longer generated | stale, safe to delete |
+
+For every vendor manifest found, record its path and **every field it sets**. Adoption reproduces
+all of it, and the Phase 5 diff is checked field by field.
+
+## Which skills count as public
+
+Only a skill the project *distributes* belongs to a plugin.
+
+| Location | Public? |
+|----------|---------|
+| `skills/<name>/SKILL.md` at the plugin root | Yes |
+| `<package>/skills/<name>/SKILL.md` where `package.json` `files` ships it | Yes |
+| `.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
+side of the line.
+
+## Making the adoption offer
+
+State what you found, what adoption buys, and let the user decline:
+
+> This project has a Claude Code plugin manifest but no canonical `plugin.json`. I can convert it to
+> the open Agent Plugins Specification, so one manifest drives Cursor, Codex, and Copilot CLI too —
+> Claude Code keeps working exactly as it does now. Want me to?
+
+Offer once. If the user declines, or their request was already something specific and unrelated
+(inspecting status, removing manifests), drop it and do what they asked.
+
+## Choosing vendors
+
+Ask which runtimes the plugin targets; default to all four when the user is unsure. Enabling a vendor
+costs a derived manifest and nothing else — except Codex, which additionally requires `version` and
+`description` on the canonical manifest and fails the build without them.
+
+Enabling Copilot CLI writes no file at all. Say so, rather than letting the user read a missing
+manifest as a broken build.
+
+Detecting a vendor directory means there is configuration to reconcile. It does not by itself mean
+the user wants that vendor maintained — say which vendors you are enabling and why, and let them
+correct the part that is actually variable.

package/skills/init/references/frontmatter.md

@@ -0,0 +1,65 @@
+# Skill frontmatter across runtimes
+
+A plugin's skills are the one component every runtime reads, so their frontmatter is where
+cross-vendor behavior is won or lost. Each runtime parses the fields it knows and silently drops the
+rest.
+
+## Required, everywhere
+
+```yaml
+---
+name: release-checklist
+description: Runs the release checklist. Use when cutting a release or publishing a package version.
+---
+```
+
+- `name` — 1–64 characters, lowercase letters, digits, hyphens. **Match the parent directory name**;
+  Claude Code resolves the command from the directory and treats `name` as a label, so matching them
+  removes the discrepancy.
+- `description` — say what the skill does *and* when to use it. This is the only text most runtimes
+  see when deciding whether to load it.
+
+Two failures actually cost you the skill: a missing `description`, and YAML that does not parse. The
+usual cause of the second is an unquoted colon — quote any description containing one.
+
+## `invocation-policy` — the field this build acts on
+
+universal-plugin reads `invocation-policy` from each `SKILL.md` and projects it per vendor:
+
+| Value | Meaning | What the build does |
+| --- | --- | --- |
+| `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 |
+
+Two consequences worth knowing before you run a build:
+
+- **The build rewrites the authored `SKILL.md`** to carry those flags. That file is both source and
+  artifact for this one field. Expect it in the diff; it is not a stray edit.
+- Any value other than `user`, `model`, or `both` **fails the build** rather than being ignored.
+
+## Which runtime understands which field
+
+| Field | Recognized by |
+| --- | --- |
+| `name`, `description` | all |
+| `license`, `metadata`, `compatibility` | accepted broadly, largely ignored |
+| `allowed-tools` | most |
+| `disable-model-invocation` | Claude Code, Cursor |
+| `context: fork`, `agent:` | Claude Code only |
+| `paths`, legacy `globs` | Cursor only |
+| `model` | Copilot CLI only |
+| `argument-hint`, `arguments` | Claude Code only |
+
+`argument-hint` and `arguments` are the one group that fails loudly rather than quietly: claude.ai
+uploads and the Skills API reject fields outside the standard set. A skill that takes arguments and
+also ships through those paths cannot use them — and does not need to, because no runtime but Claude
+Code substitutes anything anyway. Claude Code appends what the caller typed as `ARGUMENTS: <value>`
+when the body has no `$ARGUMENTS`, so a body that says how to read the invocation works everywhere,
+while a `$ARGUMENTS` placeholder resolves on one runtime and stays literal on the rest.
+
+## The rule that follows
+
+Anything that must hold on every runtime belongs in the Markdown body, not only in a vendor-specific
+field. The body is the one part every runtime reads. Treat vendor frontmatter as an optimization
+layered on instructions that already work without it.

package/skills/init/references/standard.md

@@ -0,0 +1,92 @@
+# The canonical baseline
+
+What every universal plugin has, before any vendor-specific work.
+
+## The one authored file
+
+Root `plugin.json`, on the Agent Plugins Specification v1.0.0 schema. Everything else a vendor reads
+is derived from it.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "One sentence saying what the plugin does.",
+  "author": { "name": "<author>" },
+  "extensions": {
+    "org.cyberuni.universal-plugin": {
+      "vendors": ["claude-code", "cursor", "codex", "copilot-cli"],
+      "skills": "./skills/",
+      "harnesses": {
+        "claude-code": {},
+        "cursor": {},
+        "codex": {},
+        "copilot-cli": {}
+      }
+    }
+  }
+}
+```
+
+The spec's top level holds the shared metadata. Everything universal-plugin needs to run a build
+lives under one namespaced key, `extensions["org.cyberuni.universal-plugin"]`:
+
+| Key | Holds |
+| --- | --- |
+| `vendors` | the build targets. When absent, the `harnesses` keys are the targets |
+| `harnesses` | per-vendor overrides, keyed by vendor id. `{}` opts in with no overrides |
+| `packagePath` | the npm package whose `package.json` carries the same version |
+| component paths (`skills`, `commands`, `agents`, `hooks`, …) | where each component lives |
+
+`vendors` and `harnesses` are separate on purpose: `vendors` says what to build, `harnesses` says
+what each build gets. A vendor listed in `vendors` with no `harnesses` entry still builds; a
+`harnesses` entry with no `vendors` list builds only while `vendors` is absent.
+
+## Directory layout
+
+```
+<plugin-root>/
+├── plugin.json              ← canonical definition (source of truth)
+├── skills/<name>/SKILL.md
+├── commands/<name>.md
+├── agents/<name>.md
+├── rules/<name>.mdc         (Cursor-only guidance)
+├── hooks/hooks.json
+├── .mcp.json
+└── README.md
+```
+
+`plugin init --scaffold` creates the standard `skills/`, `agents/`, `governances/`, and `commands/`
+directories. Create the rest only when the plugin has content for them.
+
+## Components
+
+| Component | Field | Directory | Reaches |
+|-----------|-------|-----------|---------|
+| Skills | `skills` | `skills/<name>/SKILL.md` | every vendor |
+| MCP servers | `mcpServers` | `.mcp.json` | every vendor |
+| Commands | `commands` | `commands/<name>.md` | Claude Code, Cursor, Copilot CLI |
+| Agents | `agents` | `agents/<name>.md` | Claude Code, Cursor, Copilot CLI |
+| Hooks | `hooks` | `hooks/hooks.json` | partial — event names differ by case, and the build does not translate them |
+| LSP servers | `lspServers` | `.lsp.json` | Claude Code, Cursor |
+| Rules | `rules` | `rules/<name>.mdc` | Cursor only |
+| Output styles | `outputStyles` | `output-styles/` | Claude Code only |
+
+The universal minimum — reaching every runtime with no vendor manifest at all — is
+`skills/<name>/SKILL.md` plus `.mcp.json`. Reach for a narrower component only when the plugin needs
+what only that component does; `governance show plugin-design` is the authority on that choice.
+
+## Constraints
+
+- **Never hand-edit a derived manifest.** `plugin build` owns `.claude-plugin/plugin.json` and its
+  siblings; an edit there survives until the next build and no longer.
+- **Never hand-edit a `version` field.** That move belongs to `/universal-plugin:version`.
+- **The canonical schema is closed.** A vendor-only field cannot be added at the top level; it goes
+  under that vendor's `harnesses` entry or nowhere.
+- Root `plugin.json` is not a build artifact. It is both the source of truth and the file Copilot CLI
+  reads, so deleting it takes out both.
+
+## Next
+
+Read only the `vendors/<vendor>.md` files for the runtimes being enabled. `SKILL.md` has the table.

package/skills/init/references/update.md

@@ -0,0 +1,31 @@
+# Update a universal plugin
+
+Change which vendors or components an existing plugin declares. Every path ends with a rebuild:
+
+```bash
+npx universal-plugin plugin build
+```
+
+## Add a vendor
+
+1. Add the vendor id to `extensions["org.cyberuni.universal-plugin"].vendors` in root
+   `plugin.json`, and add its key to `extensions["org.cyberuni.universal-plugin"].harnesses`.
+2. Populate vendor-specific fields — see that vendor's [`vendors/<vendor>.md`](./vendors/).
+3. If the vendor requires extra fields (`codex`: `version`, `description`), add them to the canonical
+   top level first — the build fails loudly without them.
+4. Rebuild for the new vendor: `plugin build --vendor <id>`.
+
+## Remove a vendor
+
+1. Remove the vendor id from `extensions["org.cyberuni.universal-plugin"].vendors` and its key from
+   `harnesses`.
+2. Delete the generated manifest at its output path. `copilot-cli` has none — removing it is a
+   manifest edit and nothing else.
+
+## Add or remove a component
+
+1. Add or remove the component field under `extensions["org.cyberuni.universal-plugin"]` in root
+   `plugin.json` (e.g. `"commands": "./commands/"`). [`standard.md`](./standard.md) has the component
+   table and which runtimes each one reaches.
+2. Scaffold or delete the corresponding files.
+3. Rebuild to regenerate all vendor manifests.

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

@@ -0,0 +1,44 @@
+# Claude Code
+
+Reads `.claude-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+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
+`extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"]` sets. `$schema`, `extensions`,
+`vendors`, `packagePath`, and `harnesses` are universal-plugin's own orchestration — they never
+appear in a vendor manifest.
+
+An empty `"claude-code": {}` is the normal case: it opts into the build with no overrides.
+
+## Extra requirements
+
+None beyond `name`. Claude Code loads a manifest that carries only the shared metadata.
+
+## Skills
+
+Claude Code reads the skills the manifest's `skills` path names. The build additionally rewrites each
+`SKILL.md`'s frontmatter when the skill declares `invocation-policy` — `disable-model-invocation:
+true` for `user`, `user-invocable: false` for `model`. See [`../frontmatter.md`](../frontmatter.md).
+
+## Hooks
+
+Claude Code hook events are **PascalCase** (`SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`,
+`UserPromptSubmit`). Cursor and Copilot CLI use camelCase; Codex is PascalCase like Claude Code.
+
+**The build does not translate event names.** It copies the `hooks` path through to every derived
+manifest as declared, so one `hooks/hooks.json` cannot currently satisfy both casings. Author hooks
+for the runtimes that share a casing, and say plainly which runtimes a hooks block does not reach
+rather than implying portability the build does not deliver.
+
+Source: `.research/hook-event-survey/conclusion.md` (June 2026) — re-verify against vendor docs
+before relying on it.
+
+## Leave alone
+
+Output styles are Claude Code-only, and hook blocks in `.claude/settings.json` are settings, not
+plugin content. Report them; do not convert them.

package/skills/init/references/vendors/codex.md

@@ -0,0 +1,48 @@
+# Codex
+
+Reads `.codex-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+npx universal-plugin plugin build --vendor codex
+```
+
+## Extra requirements — the build enforces these
+
+Targeting Codex requires `version` **and** `description` on the canonical manifest. Without either,
+`plugin build` fails loudly and writes nothing:
+
+```
+plugin.json validation failed:
+  - description is required when targeting codex
+  - version is required when targeting codex
+```
+
+The check is scoped to the vendors actually being built, so a Codex block that is not a selected
+target never blocks a build of the others.
+
+## Vendor-specific fields
+
+Codex's presentation metadata goes under its `harnesses` entry:
+
+```json
+"codex": {
+  "interface": {
+    "displayName": "<Human Name>",
+    "category": "<category>"
+  }
+}
+```
+
+## Skills
+
+For every skill that is not `invocation-policy: model`, the build also writes
+`~/.codex/prompts/<name>.md` — the skill body, as a Codex prompt.
+
+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.
+
+## Hooks
+
+Codex hook events are **PascalCase**, like Claude Code's. The build does not translate event names —
+see [`claude-code.md`](./claude-code.md).

package/skills/init/references/vendors/copilot-cli.md

@@ -0,0 +1,45 @@
+# GitHub Copilot CLI
+
+Reads the **canonical root `plugin.json` directly**. The build derives nothing for it and writes no
+file — `plugin build` reports it with status `canonical`, which is success, not a skipped target.
+
+## Why nothing is derived
+
+Copilot CLI searches four paths and takes the first match:
+
+```
+.plugin/plugin.json → plugin.json → .github/plugin/plugin.json → .claude-plugin/plugin.json
+```
+
+Root `plugin.json` — the canonical manifest — is second, so it always shadows the two below it. It
+has consumed Open Plugin Spec v1 manifests since v1.0.74, so it already serves the canonical manifest
+as-is.
+
+Earlier builds wrote `.github/plugin/plugin.json`. That path loses to root by construction and was
+never read; a leftover copy is stale and safe to delete.
+
+## Vendor-specific fields cannot be delivered
+
+A `harnesses["copilot-cli"]` entry has nowhere to go. The canonical schema is closed
+(`additionalProperties: false`), so a Copilot-only field cannot ride along in root, and there is no
+derived file to put it in. The build warns:
+
+```
+harnesses.copilot-cli sets category, tags, but copilot-cli reads the canonical plugin.json
+directly — these fields are not delivered
+```
+
+Treat that warning as a decision to make, not noise: either the field belongs to a vendor that has a
+derived manifest, or it does not ship. Do not invent a path for it.
+
+## Do not
+
+- **Do not delete root `plugin.json` to "clean up" a Copilot target.** It is the source of truth and
+  the Copilot manifest at once.
+- Do not write `.plugin/plugin.json`. It outranks root, so it would silently shadow the canonical
+  manifest with a copy nothing regenerates.
+
+## Hooks
+
+Copilot CLI hook events are **camelCase**. The build does not translate event names — see
+[`claude-code.md`](./claude-code.md).

package/skills/init/references/vendors/cursor.md

@@ -0,0 +1,45 @@
+# Cursor
+
+Reads `.cursor-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+npx universal-plugin plugin build --vendor cursor
+```
+
+## Extra requirements
+
+None beyond `name`.
+
+## Vendor-specific fields
+
+Cursor's catalog metadata goes under its `harnesses` entry, not at the canonical top level:
+
+```json
+"cursor": {
+  "publisher": "<org>",
+  "category": "<category>",
+  "tags": ["<tag>"]
+}
+```
+
+## Skills
+
+Cursor reads `SKILL.md` straight from the path the manifest's `skills` field names, and lets the user
+invoke a skill by typing `/` and searching for it. **The build derives no per-skill artifact for
+Cursor** — a mirrored `.cursor/commands/*.md` would be a second copy of the same body. Explicit-only
+invocation is expressed natively through `disable-model-invocation`, which the build already writes
+into the shared `SKILL.md`.
+
+## Rules are Cursor-only
+
+`rules/<name>.mdc` reaches Cursor and nothing else. Reach for a rule only when the plugin genuinely
+needs always-on guidance in Cursor; anything a task can load on demand belongs in a skill, where every
+runtime sees it. `governance show plugin-design` is the authority on that call.
+
+`.mdc` and `.md` are not interchangeable, and path-scoping has no equivalent in the other runtimes —
+never generate rules from a skill or a skill from a rule.
+
+## Hooks
+
+Cursor hook events are **camelCase** (`sessionStart`). The build does not translate event names — see
+[`claude-code.md`](./claude-code.md).

package/skills/init/scripts/init.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Runs `universal-plugin plugin init` from the CLI that ships beside this skill, so a scaffold
+// never depends on a network fetch or on which version `npx` happens to resolve.
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// <package>/skills/<skill>/scripts/init.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+
+process.argv.splice(2, 0, 'plugin', 'init')
+await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))

package/skills/remove-plugin/README.md

@@ -0,0 +1,38 @@
+# remove-plugin skill
+
+Remove a universal plugin's artifacts — from cleaning a build output to taking the plugin out of a
+project entirely.
+
+## Three removals, not one
+
+They are not equally reversible, and the skill establishes which one is being asked for before
+deleting anything:
+
+| Ask | Removes | Reversible by |
+| --- | --- | --- |
+| clean the build output | derived vendor manifests | `plugin build` |
+| drop a vendor | one manifest, and its declaration | re-adding the vendor, then a build |
+| remove the plugin | the canonical manifest and every component | nothing |
+
+Only the last is irreversible, and only it needs a confirmation.
+
+## What it will not do
+
+Root `plugin.json` is never deleted as cleanup. It is the canonical source of truth *and* the
+manifest GitHub Copilot CLI reads, so removing it takes out the source and a live target at once.
+
+Dropping a vendor is a manifest edit first: deleting only the file leaves the vendor declared, and
+the next build writes it straight back. That edit routes to `init`.
+
+Deleting a published plugin's source does not unpublish it. The skill says so rather than implying
+the removal reached consumers.
+
+## Why there is no delete script
+
+`plugin build --clean` already removes exactly what the manifest declares and nothing it does not.
+Anything beyond that is a judgment call about authored content, which is the part that should stay
+in front of a human.
+
+## References
+
+- [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)