universal-plugin 0.6.0 → 0.7.0

package/skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: Use this skill to diagnose a universal agent plugin — when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, when a build prints warnings nobody has read, or when checking whether what the canonical plugin.json declares still matches what is on disk for Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "is my plugin set up right", "why isn't my plugin loading", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
+description: Use this skill to diagnose a universal agent plugin — when `plugin build` reports "built 0" or "nothing to build", when it warns "No vendors declared in harnesses", when a repository still carries `.plugin/plugin.json` or a top-level `vendorExtensions` block after upgrading universal-plugin across a major, when a released version never reached the vendor manifests, when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, or when checking whether what the canonical plugin.json declares still matches what is on disk for Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "is my plugin set up right", "why isn't my plugin loading", "the build says built 0", "why did nothing get built", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
 ---
 
 # Plugin Doctor
@@ -43,13 +43,20 @@ Read `vendors[].status` literally:
 
 | Status | Means |
 | --- | --- |
-| `built` | the build writes this vendor's manifest |
+| `built` | the build writes this vendor's output. For `copilot-cli` that output is the `com.github.copilot/` component tree, not a manifest |
 | `canonical` | the vendor reads root `plugin.json`; **no file is written, and that is correct** |
 | `skipped` | an unknown vendor id — a typo in `vendors` |
 | `failed` | the write itself failed; the finding names why |
 
-`copilot-cli` reporting `canonical` with `exists: false` is a healthy plugin, not a missing build.
-Never report it as a fault.
+`copilot-cli` reporting `canonical` is a healthy plugin, not a missing build — root `plugin.json`
+serves it, and a plugin declaring no agents, commands, rules, hooks, or LSP servers has nothing else
+to derive. Never report it as a fault.
+
+A plugin that **does** declare those reports `copilot-cli` as `built` at `com.github.copilot/`
+instead. Declaring the canonical `$schema` moves them there: Copilot CLI stops reading them from the
+plugin root entirely, so a root-only layout loads none of them and says nothing
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)). That is what
+`copilot-root-components` reports.
 
 If `node` is unavailable, read `scripts/doctor.mjs` and apply the same checks by hand: it composes
 `universal-plugin plugin build --dry-run --format json` with filesystem facts that build cannot see.
@@ -71,9 +78,10 @@ Each `code` below is what the script emits.
 | `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` |
 | `unreleased-content` | shipped content was committed after the commit that set the current version — a consumer keyed on that version never re-extracts it | `/universal-plugin:version` |
+| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `universal-plugin plugin build` |
 | `stale-github-plugin` | a leftover `.github/plugin/plugin.json` from an older build — shadowed by root and no longer generated | `/universal-plugin:remove-plugin` |
 | `shadowing-manifest` | a `.plugin/plugin.json` exists — it outranks root in Copilot CLI's search order and silently shadows the canonical manifest | `/universal-plugin:remove-plugin` |
-| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin | `/universal-plugin:init`, update route |
+| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init`, adopt route on the pre-0.6 layout, else update route |
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
 | `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
 | `invalid-catalog` | a marketplace catalog at the repository root is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
@@ -140,7 +148,9 @@ is meant to ship — content that is still being worked on is not a finding to a
 - **Never repair.** Report the finding and name the skill that owns it.
 - **Never hand-edit a derived manifest to make a finding go away.** The next build overwrites it and
   the finding comes back.
-- Do not report `copilot-cli` writing no file as a fault. It reads the canonical manifest directly.
+- Do not report `copilot-cli` writing no **manifest** as a fault. It reads the canonical manifest
+  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`.
 

package/skills/doctor/scripts/doctor.mjs

@@ -84,6 +84,57 @@ if (fs.existsSync(path.join(root, '.github/plugin/plugin.json'))) {
 	)
 }
 
+// Copilot CLI's spec mode reads its native components ONLY under com.github.copilot/ — declaring the
+// canonical $schema moves them out of the plugin root (ADR-0015). A plugin that ships them at the
+// root and has no namespace copy loads none of them on Copilot CLI, and nothing at runtime says so.
+// Checked from the filesystem rather than from the build result, so it still fires on a repository
+// whose build cannot run.
+const COPILOT_NAMESPACE = 'com.github.copilot'
+const declaredTargets = ext?.vendors ?? Object.keys(ext?.harnesses ?? {})
+if (declaredTargets.includes('copilot-cli')) {
+	const nsDir = path.join(root, COPILOT_NAMESPACE)
+	const declaredPaths = (value, fallback) => {
+		if (value === undefined) return fallback === null ? [] : [fallback]
+		if (typeof value === 'string') return [value]
+		if (Array.isArray(value)) return value.filter((entry) => typeof entry === 'string')
+		if (value && Array.isArray(value.paths)) return value.paths.filter((entry) => typeof entry === 'string')
+		return []
+	}
+	const hasContent = (rel) => {
+		const abs = path.join(root, rel)
+		return fs.existsSync(abs) && fs.statSync(abs).isDirectory() && fs.readdirSync(abs).length > 0
+	}
+	const missing = []
+	// The same defaults the build derives from. Passing null here would make the check fire only for a
+	// manifest that names the path — and the manifest that names none is the common one.
+	for (const [kind, defaultPath] of [
+		['agents', './agents/'],
+		['commands', './commands/'],
+		['rules', './rules/'],
+	]) {
+		const roots = declaredPaths(ext?.[kind], defaultPath)
+		if (roots.some(hasContent) && !hasContent(path.join(COPILOT_NAMESPACE, kind))) missing.push(kind)
+	}
+	// hooks is a single file, declared as a path or inline in the manifest, and carries a default the
+	// manifest need not declare at all.
+	const inlineHooks = ext?.hooks !== null && typeof ext?.hooks === 'object' && 'hooks' in ext.hooks
+	const hookSources = inlineHooks ? [] : declaredPaths(ext?.hooks, './hooks/hooks.json')
+	const hasHooks = inlineHooks || hookSources.some((rel) => fs.existsSync(path.join(root, rel)))
+	if (hasHooks && !fs.existsSync(path.join(nsDir, 'hooks', 'hooks.json'))) missing.push('hooks')
+	const lspSources = declaredPaths(ext?.lspServers, null)
+	if (lspSources.some((rel) => fs.existsSync(path.join(root, rel))) && !fs.existsSync(path.join(nsDir, 'lsp.json'))) {
+		missing.push('lspServers')
+	}
+	if (missing.length > 0) {
+		add(
+			'copilot-root-components',
+			'high',
+			`${missing.join(', ')} sit at the plugin root with no copy under ${COPILOT_NAMESPACE}/ — Copilot CLI reads them only from there once the canonical $schema is declared, so it loads none of them`,
+			'universal-plugin plugin build',
+		)
+	}
+}
+
 // Ask the shipped CLI what it would write, without writing it.
 const bin = path.join(packageRoot, 'bin', 'universal-plugin.mjs')
 const cli = fs.existsSync(bin)
@@ -106,6 +157,17 @@ if (build === null) {
 			'codex is targeted without version or description — the build writes nothing at all, for any vendor',
 			'add both to the canonical top level',
 		)
+	} else if (findings.some((f) => f.code === 'legacy-manifest' || f.code === 'shadowing-manifest')) {
+		// The build stops rather than reporting a definitive empty state when the layout explains the
+		// empty result (issue #61). That is still the no-vendors diagnosis — the layout findings above
+		// name the signals, and this names the consequence. Keyed on those findings rather than on the
+		// build's message, so the two never have to agree on wording.
+		add(
+			'no-vendors',
+			'medium',
+			'no vendor is declared — the project is on the pre-0.6 layout, so the build derives nothing and no runtime reads this plugin',
+			'/universal-plugin:init, adopt route',
+		)
 	} else {
 		add(
 			'build-failed',

package/skills/init/README.md

@@ -53,5 +53,8 @@ touch CI, repository settings, or unrelated project files.
 ## References
 
 - [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
-- [Schema](https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json)
+- [Manifest schema (Agent Plugins Specification v1.0.0)](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)
+- [Extension schema](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json)
+  — the body of `extensions["org.cyberuni.universal-plugin"]`, also shipped in the package at
+  `schema/extension.schema.json`
 - [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/init/SKILL.md

@@ -10,10 +10,18 @@ Give a project one canonical plugin manifest — a root `plugin.json` on the Age
 Specification — and derive from it the manifest each runtime expects.
 
 Most of the manifest is shared. The divergence is small and asymmetric: Copilot CLI reads the
-canonical `plugin.json` directly and gets no derived file at all, while Claude Code, Cursor, and
+canonical `plugin.json` directly and gets no derived *manifest*, while Claude Code, Cursor, and
 Codex each read their own path. Keep that asymmetry in mind — this is a consolidation job, not a
 copy-everywhere job.
 
+That asymmetry does not extend to components. Declaring the canonical `$schema` puts a plugin in
+Open Plugin Spec mode, and Copilot CLI then reads its **native** components — agents, commands,
+rules, hooks, LSP servers — from a `com.github.copilot/` directory rather than the plugin root.
+Authoring still happens at the canonical locations: `plugin build` derives that directory
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)), so do not tell
+an author to move `agents/` into it — the root copy is what the other three vendors derive from. See
+[`references/vendors/copilot-cli.md`](./references/vendors/copilot-cli.md).
+
 `references/standard.md` defines the baseline every plugin gets. Read the vendor file for each
 runtime you are enabling, and only those.
 
@@ -22,7 +30,7 @@ runtime you are enabling, and only those.
 | Claude Code | `.claude-plugin/plugin.json` | none | `references/vendors/claude-code.md` |
 | Cursor | `.cursor-plugin/plugin.json` | none | `references/vendors/cursor.md` |
 | Codex | `.codex-plugin/plugin.json` | `version`, `description` | `references/vendors/codex.md` |
-| GitHub Copilot CLI | none — reads root `plugin.json` | none | `references/vendors/copilot-cli.md` |
+| GitHub Copilot CLI | none — reads root `plugin.json` | native components derived under `com.github.copilot/` ([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)) | `references/vendors/copilot-cli.md` |
 
 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
@@ -78,9 +86,12 @@ Sort each finding into exactly one bucket:
 - **adoptable** — a hand-written vendor manifest with no canonical manifest above it, a legacy root
   `plugin.json` carrying neither `$schema` nor `extensions`, or publicly-shipped skills with no
   manifest at all. These become canonical content in Phase 4.
-- **undeliverable** — a vendor-specific field with no delivery path, most often a
-  `harnesses["copilot-cli"]` override: the canonical schema is closed, so the field cannot ride
-  along in root and the build warns about it. Report; do not invent a home for it.
+- **undeliverable** — a vendor-specific field with no delivery path, because Copilot CLI reads the
+  canonical manifest directly and has no derived file of its own. Two shapes reach this bucket: a
+  `harnesses["copilot-cli"]` override, which the build warns about; and a non-spec field on a
+  **legacy root `plugin.json`** — `category`, `tags` — which nothing warns about at all, because the
+  correct adoption never writes a `harnesses` entry for it. Report every one by name; do not invent
+  a home for it.
 - **not a plugin** — repo-private agent configuration (`.claude/skills/`, `.agents/skills/`,
   `.cursor/rules/`). It is this project's own tooling, not something it distributes. Say nothing
   about packaging it.
@@ -95,6 +106,11 @@ hand-written vendor manifests become generated artifacts, which vendors will be
 canonical metadata will say (show `name`, `version`, and `description` verbatim), and what is being
 left alone and why.
 
+An adoption also presents **every non-spec field it is about to drop, by name and value** — the
+undeliverable bucket from Phase 2. Nothing downstream warns about those, so this is the only notice
+the user gets. [`references/adopt.md`](./references/adopt.md) Step 2 has the command that enumerates
+them.
+
 Get explicit approval before any step that deletes, replaces, or rewrites a user-authored file —
 adoption always crosses that line, because it turns manifests the user maintains into build output.
 Creating a missing `plugin.json`, a missing component directory, or a missing skill scaffold needs
@@ -167,11 +183,16 @@ override both surface there and both are silent capability loss if ignored.
 When the work was an adoption, the proof is the diff:
 
 ```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+git diff -- plugin.json .claude-plugin .cursor-plugin .codex-plugin .github/plugin
 ```
 
-Expect only formatting and key-order churn. Any field that disappeared is a regression, not a
-cleanup — trace it back to the shared metadata or to that vendor's `harnesses` entry before shipping.
+From the four derived paths, expect only formatting and key-order churn. Root `plugin.json` is
+different and is in the list on purpose: it shows real hunks — the `$schema`/`extensions` rewrite —
+and under the legacy layout it *was* Copilot CLI's manifest, so it is the one file where a field can
+vanish unnoticed. Read those hunks rather than skimming them.
+
+Any field that disappeared is a regression, not a cleanup — trace it back to the shared metadata, to
+that vendor's `harnesses` entry, or to the drop list you reported in Phase 3, before shipping.
 
 Audit each skill the plugin ships, per [`references/create.md`](./references/create.md) Step 6.
 Report what was created, adopted, derived, and left alone. For a fuller read of the plugin's state
@@ -186,7 +207,9 @@ This skill is not a formatter. If the project has one, run it over the written f
 - **Never hand-edit a `version` field.** Two authored files and every derived artifact fall out of
   sync. The `version` skill owns that move.
 - **Adoption is lossless by contract.** Every vendor that worked before must still work after, and
-  the Phase 5 diff is the check that proves it.
+  the Phase 5 diff — root `plugin.json` included — is the check that proves it. Where a field
+  genuinely cannot be carried, losing it is a decision the user makes, not one the adoption makes
+  quietly: name it first.
 - **Do not package repo-private agent configuration.** A `.claude/skills/` directory is the project's
   own tooling; offering to publish it is wrong.
 - **Do not convert vendor settings without a documented mapping.** Hooks have one: author them in
@@ -215,5 +238,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 
 - Governance: `npx universal-plugin governance show plugin-design`
 - Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
-- Schema: https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json
+- Manifest schema (Agent Plugins Specification v1.0.0): https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
+- Extension schema (the body of `extensions["org.cyberuni.universal-plugin"]`), shipped in the package at
+  `schema/extension.schema.json`: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json
 - Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples

package/skills/init/references/adopt.md

@@ -41,19 +41,94 @@ canonical manifest (has `$schema` pointing at `agent-plugins.org` and an `extens
 which case there is nothing to adopt; route to `update.md`, or hand off to `doctor`, instead), or a legacy
 Copilot CLI manifest that now collides with the canonical path and must be folded in.
 
-## Step 2 — Sort every field into shared vs vendor-specific
+## Step 2 — Sort every field into shared, vendor-specific, and undeliverable
 
-Build two buckets from the manifests you inventoried:
+Build three buckets from the manifests you inventoried:
 
-- **Shared metadata** — `name`, `version`, `description`, `author`, `homepage`, `repository`,
-  `license`, `keywords`, and the component paths. These go at the canonical top level.
+- **Shared metadata** — the canonical top level is a **closed** set of exactly ten fields:
+  `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`,
+  `keywords`, `extensions`. A field in that list stays at the top level. That set is the upstream
+  spec's, not this project's — see
+  [the published schema](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json).
 - **Vendor-specific** — anything only one runtime understands (Cursor's `publisher`/`category`/
-  `tags`, Codex's `interface`, Copilot's `category`/`tags`). These go under
-  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`.
+  `tags`, Codex's `interface`). These go under
+  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`. The component paths
+  (`skills`, `commands`, `agents`, `hooks`, `mcpServers`, `rules`, `lspServers`, `outputStyles`)
+  are not top-level either — they go under that same extension namespace, one level up from
+  `harnesses`.
+- **Undeliverable** — a field whose only consumer is Copilot CLI. Copilot CLI reads the canonical
+  root manifest directly and gets no derived file, so such a field has no home on either side: the
+  closed schema rejects it at the top level, and a `harnesses["copilot-cli"]` entry is never
+  written anywhere. Before dropping one, check
+  [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) — the two fields that actually turn up here,
+  `category` and `tags`, have a spec-conformant home (`keywords`) and are not a loss.
 
 Where two vendor manifests disagree on a shared field, **ask the user** which value is canonical
 rather than picking one. A silent choice here is a silent behavior change for one of their runtimes.
 
+### Name every field you are about to drop
+
+A legacy root `plugin.json` is what makes the third bucket real. Before 0.6 the build wrote
+Copilot CLI's output *to root*, so root carries whatever Copilot-specific fields the project set —
+`category` and `tags` are the ones seen in the wild. After adoption root is the canonical manifest
+and those fields have nowhere to go.
+
+Nothing warns about this. The build's `undeliverable-override` warning and `doctor`'s matching
+finding fire only on a `harnesses["copilot-cli"]` entry — which is what someone doing it *wrong*
+writes. An adoption done correctly never creates one, so it gets silence. Enumerate the fields
+yourself, from the pre-adoption root manifest, before you overwrite it:
+
+```bash
+node -e '
+  const spec = ["$schema", "name", "version", "description", "author",
+                "homepage", "repository", "license", "keywords", "extensions"]
+  const root = JSON.parse(require("node:fs").readFileSync("plugin.json", "utf8"))
+  for (const k of Object.keys(root)) {
+    if (!spec.includes(k)) console.log(k, "=", JSON.stringify(root[k]))
+  }
+'
+```
+
+Every name it prints is a field the canonical top level cannot hold. Sort each one:
+
+| The field | Where it goes |
+| --- | --- |
+| `vendorExtensions` — the whole pre-0.6 block | `extensions["org.cyberuni.universal-plugin"].harnesses` — **renamed, not dropped** |
+| a component path (`skills`, `commands`, `agents`, …) | `extensions["org.cyberuni.universal-plugin"].<name>` — carried |
+| a field a vendor with a *derived* manifest understands | that vendor's `harnesses` entry — carried |
+| `category` / `tags` from the legacy Copilot output | fold into **`keywords`** — see below |
+| anything left | **dropped** |
+
+`vendorExtensions` is the row that catches people out, because the snippet prints it alongside the
+genuinely undeliverable fields and it looks like one of them. It is not: it is the old name for
+`harnesses`, and dropping it discards every per-harness override the project had. Carry the block
+across, then sort the `copilot-cli` entry inside it by the rule above — that entry is the one whose
+contents have no delivery path.
+
+`plugin build` will not let this one pass quietly: a root manifest still carrying `vendorExtensions`
+now exits 1 rather than reporting `built 0`, naming the signal and routing to `doctor`. If Step 5
+fails that way, the block did not get carried across.
+
+`category` and `tags` have their own row because they are the fields this whole step exists for, and
+they are **not** simply dropped. Copilot CLI has no `plugin.json` handling for either — its manifest
+validator knows `keywords` and treats these two as unknown-and-ignored — while `keywords` is both a
+spec field and the one Copilot actually parses. So fold the values in rather than deleting them:
+
+```
+category: "productivity" + tags: ["workflow", "planning", "verification"]
+  → keywords: ["productivity", "workflow", "planning", "verification"]
+```
+
+If the project also ships a `marketplace.json` catalog, `category` and `tags` are real fields on a
+catalog entry and belong there as well — with the right types, because a wrong one is a fatal browse
+error rather than a warning. [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) has the evidence
+and the exact validator messages.
+
+**Report anything genuinely dropped to the user by name, with the value each held, before Step 3
+writes anything.** That report is the only notice they get, and it is the difference between an informed
+decision and a field that evaporates. Say what the field was for if you know; if a field looks load-
+bearing and the user wants it kept, stop rather than shipping the adoption around it.
+
 ## Step 3 — Write the canonical manifest
 
 Scaffold it, naming exactly the vendors you found in Step 1:
@@ -85,8 +160,8 @@ regenerated rather than edited.
 - Tell the user they are generated from here on, and that hand-edits will be overwritten by
   `plugin build`.
 - If the project has a legacy root `plugin.json` for Copilot CLI, that path is now the canonical
-  manifest — its derived Copilot output moves elsewhere. Check the vendor output table in
-  [`create.md`](./create.md) Step 2 for the current path.
+  manifest. Copilot CLI gets no replacement file: it reads root directly, so the canonical manifest
+  *is* its manifest from here on. See the vendor output table in [`create.md`](./create.md) Step 2.
 
 ## Step 5 — Build
 
@@ -99,14 +174,27 @@ npx universal-plugin plugin build
 This is the point of the whole procedure.
 
 ```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+git diff -- plugin.json .claude-plugin .cursor-plugin .codex-plugin .github/plugin
 ```
 
-Read every line of that diff. Expect only formatting and key-order churn.
+Root `plugin.json` is in that list on purpose, and it is the one path that behaves differently from
+the other four.
+
+- For `.claude-plugin`, `.cursor-plugin`, `.codex-plugin`, and `.github/plugin`, expect only
+  formatting and key-order churn. A hunk that changes a value is a finding.
+- For root `plugin.json`, **expect real hunks** — the `$schema` line and the `extensions` object are
+  new, and the component paths moved under them. That is the rewrite working. Because the diff is
+  large by design it is the easy one to skim, and under the legacy layout root *was* a vendor
+  manifest — Copilot CLI's — so it is also the only file where a field can go missing without any
+  other check noticing. Read it, do not skim it.
+
+Account for **every key that leaves root**. Each one must land in exactly one of three places: at the
+canonical top level, under `extensions`, or on the dropped list you enumerated and reported in
+Step 2. A key that left root and is on none of those three is a regression.
 
-**Any field that disappeared is a regression**, not a cleanup. Trace it back: either it belongs in
-the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field the build
-does not yet support — in which case stop and tell the user rather than shipping a quiet
+**Any field that disappeared unannounced is a regression**, not a cleanup. Trace it back: either it
+belongs in the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field
+the build does not yet support — in which case stop and tell the user rather than shipping a quiet
 capability loss.
 
 Then confirm the plugin still loads. See [`create.md`](./create.md) Step 8 for local install.

package/skills/init/references/detection.md

@@ -15,13 +15,19 @@ ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/nul
 | `.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 |
+| a top-level `vendorExtensions` block | the pre-0.6 name for `harnesses`; `plugin build` exits 1 on it | adoptable — carry the block, do not drop it |
 | 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 |
+| a non-spec field on a legacy root `plugin.json` (`category`, `tags`, …) | it was Copilot CLI's, and Copilot CLI has no derived manifest to move it to | undeliverable — and **nothing warns**; name it in Phase 3 |
 | `.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.
+For every vendor manifest found, record its path and **every field it sets** — root `plugin.json`
+included, when it is the legacy kind. Adoption reproduces all of it, and the Phase 5 diff is checked
+field by field. The canonical top level accepts exactly ten fields (`$schema`, `name`, `version`,
+`description`, `author`, `homepage`, `repository`, `license`, `keywords`, `extensions`); everything
+else either moves under `extensions` or is dropped, and
+[`adopt.md`](./adopt.md) Step 2 is where you sort out which.
 
 ## Which skills count as public
 

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

@@ -1,9 +1,11 @@
 # 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.
+Reads the **canonical root `plugin.json` directly**, so the build derives no vendor manifest for it.
+It does derive its **components** — see [`com.github.copilot/` — the namespace directory](#comgithubcopilot--the-namespace-directory).
+A plugin declaring none of the moved kinds is reported with status `canonical`, which is success, not
+a skipped target.
 
-## Why nothing is derived
+## Why no manifest is derived
 
 Copilot CLI searches four paths and takes the first match:
 
@@ -12,8 +14,9 @@ Copilot CLI searches four paths and takes the first match:
 ```
 
 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.
+has consumed Open Plugin Spec v1 manifests since **v1.0.74** (2026-07-23, [changelog](https://github.com/github/copilot-cli/blob/main/changelog.md):
+"Add support for Open Plugin Spec v1 plugin manifests and mcp.json configuration"), 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.
@@ -32,22 +35,167 @@ 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.
 
+## `category` and `tags` belong to the catalog, not the manifest
+
+A project on the pre-0.6 layout carries these on its **root** `plugin.json`, because root *was*
+Copilot CLI's derived output. Adoption drops them from there, and that loses nothing — but not for
+the reason the field table suggests.
+
+**Copilot CLI has no `plugin.json` handling for either field.** Verified against the shipped
+`@github/copilot-linux-x64` **1.0.83** runtime (the plugin loader is Rust in
+`prebuilds/*/runtime.node`, not the bundled JS), and confirmed by running the binary. The manifest
+validator carries a dedicated message for `keywords` and none for `category` or `tags`; both land on
+the unknown-field path:
+
+```
+Plugin manifest "…": field "keywords" must be an array of strings (ignored)
+Plugin manifest "…": unknown field "…" (ignored)
+```
+
+Unknown keys are **warn-and-ignore**: not rejected, not stripped from disk, dropped from the parsed
+struct. A manifest carrying `category`, `tags`, and an outright bogus key installs cleanly with no
+output about any of them. GitHub's published field table lists `category`/`tags` under the
+`plugin.json` optional metadata fields anyway — as of 1.0.83 that part of the table does not match
+the shipped loader.
+
+**Where they are real is `marketplace.json`.** The catalog validator type-checks both on every
+`plugins[]` entry, and a wrong type is a *fatal* browse failure, not a warning:
+
+```
+Failed to browse marketplace: Invalid marketplace.json:
+  plugins.0.category: Expected string, received number,
+  plugins.0.tags: Expected array, received string
+```
+
+With valid values, nothing renders them — `marketplace browse` prints only `name` and `description`,
+and `plugins list --json` emits neither field, nor `keywords`. No list, search, sort, or filter in
+the CLI touches any of them. GitHub's own marketplace (`github/copilot-plugins`, 17 curated entries)
+sets `category` and `tags` zero times while populating `keywords` on 15 of 17.
+
+### So where does a migrating project put them
+
+| Was | Goes |
+| --- | --- |
+| `category` / `tags` on root `plugin.json` | fold into **`keywords`** — a spec field, in the closed set, and the one Copilot's manifest validator actually knows |
+| the same values for marketplace discovery | the **catalog entry** in `marketplace.json`, where Copilot defines them |
+
+Do not build a delivery path for these into the plugin manifest. There is nothing at the other end.
+
+### Still open
+
+- **Where the `unknown field (ignored)` warning surfaces.** It exists in the binary but reached no
+  output on `plugin install`, `plugin list`, or `plugins list`. Likely the interactive dashboard or
+  the session config-problems channel.
+- **The full known-field allow-list for `plugin.json`.** The validator's field set is a Rust const
+  array in a stripped binary; only fields with dedicated messages are recoverable. The negative is
+  solid — neither `category` nor `tags` has any handling — but the positive list is not.
+- **Server-side catalog search.** The runtime carries a remote catalog client with a `canSearch`
+  capability. Whether GitHub's hosted catalog indexes `category`/`tags` is outside what the shipped
+  code can answer, and it would be indexing `marketplace.json`, not a plugin manifest.
+- **Extension, command, rule, and hook loading from the namespace directory** (below) was not
+  observed directly — only agents were proven by experiment. The rest rests on GitHub's GA post.
+
+### Sources
+
+- Shipped runtime: `@github/copilot-linux-x64` 1.0.83, `prebuilds/linux-x64/runtime.node`; validator
+  strings and live `plugin install` / `marketplace browse` / `plugins list --json` runs.
+- Copilot CLI plugin reference (the field table this contradicts):
+  https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
+- GitHub's own catalog: https://github.com/github/copilot-plugins `.github/plugin/marketplace.json`
+- Agent Plugins Specification v1.0.0 §8 (`extensions` is the sanctioned channel for non-spec data)
+  and the closed field set: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
+
+## `com.github.copilot/` — the namespace directory
+
+Declaring the canonical `$schema` puts a plugin in **spec mode**, and spec mode changes where
+Copilot CLI looks for its *native* components. They move out of the plugin root and into a
+reverse-domain directory that other runtimes ignore by design:
+
+```
+com.github.copilot/agents/  commands/  rules/  hooks  extensions/
+```
+
+Spec components stay where the spec puts them: `skills/` and `mcp.json` remain at the plugin root.
+Only Copilot-native kinds move. `extensions/` — canvas extensions, added in **1.0.79**
+(2026-08-10) — is one subdirectory of it.
+
+The directory pairs with the manifest key of the same name: `com.github.copilot/` carries Copilot's
+*files*, `extensions["com.github.copilot"]` carries Copilot's *data* (§8). Same namespace, two
+surfaces.
+
+**This is a real delivery path, and it narrows the rule above.** "A Copilot-only field has nowhere
+to go" still holds for **manifest fields** — the canonical schema is closed and that argument is
+untouched. It does **not** hold for **content**: Copilot-specific agents, commands, rules, and hooks
+have a sanctioned home, and `extensions["com.github.copilot"]` is the right place for Copilot
+metadata.
+
+The list above is the shape; these are the exact paths, and `lsp.json` belongs on it too:
+
+| Component | Spec-mode path | Root still read |
+| --- | --- | --- |
+| agents | `com.github.copilot/agents/` | no |
+| commands | `com.github.copilot/commands/` | no |
+| rules | `com.github.copilot/rules/` | no |
+| hooks | `com.github.copilot/hooks/hooks.json` | no |
+| LSP servers | `com.github.copilot/lsp.json` | no |
+| extensions (canvases) | `com.github.copilot/extensions/` | never had a root path |
+| skills | `skills/` | **yes — does not move** |
+| MCP servers | `mcp.json` | **yes — does not move** |
+
+The namespace **replaces** the root rather than supplementing it, and an explicit component path in
+the manifest does **not** opt back into root loading. The move landed in **1.0.80-0** and the
+runtime's own changelog labels it breaking. Evidence and its confidence, including which kinds were
+proven by experiment:
+[`.research/copilot-spec-mode-namespace/`](../../../../../../.research/copilot-spec-mode-namespace/conclusion.md).
+The published CLI plugin reference still says spec support is "additive on top of standard plugin
+loading" and documents only the root layout — it is stale; do not build against it.
+
+### What the build derives
+
+`plugin build` derives the tree ([ADR-0015](../../../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)),
+so **authoring stays at the canonical locations**:
+
+- `agents`, `commands` and `rules` are copied, resolved through the same `pathValue` contract
+  `skills` uses, defaults included.
+- Agents are **renamed** on the way. Copilot CLI reads `agents/` as `.agent.md` files while the
+  canonical `agents/` is the Claude Code-shaped `*.md`, so a copy under the authored name would land
+  a file the runtime ignores. Commands and rules keep their authored names — the runtime documents no
+  extension for either.
+- Hooks are **translated** into `com.github.copilot/hooks/hooks.json`, so a handler Copilot CLI
+  cannot run is dropped from that file with a warning rather than reported as ignored at runtime.
+- A declared `lspServers` **path** is copied to `com.github.copilot/lsp.json`. An **inline** map is
+  not delivered: the file's top-level shape is undocumented, so the build warns instead of composing
+  one.
+- `com.github.copilot/extensions/` is the inverse — authored there, never derived, and left alone by
+  `--clean`.
+
+The vendor reports `built` at `com.github.copilot/` when it derives any of this, and keeps reporting
+`canonical` at `plugin.json` when the plugin declares none of the moved kinds.
+
 ## 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.
+  manifest with a copy nothing regenerates. `plugin build` names it as a pre-0.6 signal and exits 1 —
+  but only when nothing derived at all. A project whose other harnesses still build keeps the shadow
+  and gets no warning, so this stays a rule you follow rather than one the tool enforces.
+- **Do not tell an author to move `agents/` into `com.github.copilot/`.** The root copy is the
+  canonical input every other vendor derives from; the namespace is a build output. Moving it
+  serves Copilot and strands the other three.
+- **Do not hand-write the namespace directory.** `--clean` replaces everything the build derives
+  under it. `extensions/` is the one subtree it leaves alone, and the only one to author there.
 
 ## Hooks
 
 Copilot CLI accepts **either casing**, and the casing selects the payload format: PascalCase gets the
-Claude-compatible format, so the canonical file reaches Copilot CLI unchanged. Because Copilot CLI
-reads that file directly, the build derives nothing for it — an `agent` handler is reported as ignored
-at runtime rather than dropped. See [`claude-code.md`](./claude-code.md).
+Claude-compatible format, so the canonical file needs no translation. It is written to
+`com.github.copilot/hooks/hooks.json` all the same, because that is where spec mode reads it — so a
+handler Copilot CLI cannot run is **dropped from that derived file** with a warning, like any other
+vendor's. See [`claude-code.md`](./claude-code.md).
 
 ## Dependencies
 
-Copilot CLI reads no plugin dependency. Because it reads the canonical manifest directly, there is no
-derived file to leave the declaration out of — it sits under `extensions`, which Copilot CLI ignores,
+Copilot CLI reads no plugin dependency. Because it reads the canonical *manifest* directly, there is
+no derived manifest to leave the declaration out of — it sits under `extensions`, which Copilot CLI ignores,
 and the build reports it as ignored at runtime. See [`claude-code.md`](./claude-code.md).