From 589ec01d1bceb306180f2b12865d1374cccdadc5 Mon Sep 17 00:00:00 2001
From: Nikolai Emil Damm <nikolaiemildamm@icloud.com>
Date: Sat, 18 Jul 2026 12:29:19 +0200
Subject: [PATCH 1/5] docs: record that VS Code now auto-loads bundled plugin
 components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VS Code shipped agent plugins, so the repo premise that it is not a plugin
surface — and the manual copy steps built on it — is stale. Corrects the
consumer READMEs and adds dated superseding notes to ADR 0001 and ADR 0003,
preserving the original point-in-time analysis.

Fixes #66
---
 README.md                                     | 43 +++++++------
 ...-bundling-mcp-servers-and-custom-agents.md | 61 +++++++++++++------
 docs/adr/0003-vibe-coding-plugin-design.md    | 15 ++++-
 plugins/vibe-coding/README.md                 | 11 ++--
 4 files changed, 86 insertions(+), 44 deletions(-)

diff --git a/README.md b/README.md
index 4f74229..0c9ff7f 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ npx skills add devantler-tech/agent-plugins --skill gitops-knowledge --agent cur
 ```
 
 > [!IMPORTANT]
-> This is a **partial** install path. It resolves all **27 bundled skills**, but **not** the [MCP servers](#mcp-servers) or [custom agents](#custom-agents). For those, use **Claude Code** or **Copilot CLI** above — they are the only tools that load a plugin's bundled `.mcp.json` and `agents/` automatically. In **VS Code**, a plugin install delivers the skills only, and MCP servers and agents are added manually (see [MCP servers](#mcp-servers) and [custom agents](#custom-agents) for the exact steps).
+> This is a **partial** install path. It resolves all **27 bundled skills**, but **not** the [MCP servers](#mcp-servers) or [custom agents](#custom-agents). To get everything a plugin bundles, install it as a plugin in **VS Code**, **Copilot CLI**, or **Claude Code** above — all three load a plugin's bundled `.mcp.json` and `agents/` automatically.
 
 ## MCP servers
 
@@ -83,20 +83,23 @@ cluster out of the box.
 The server is authored once as the plugin's [`.mcp.json`](plugins/gitops-kubernetes/.mcp.json)
 (`mcpServers` map). How each tool consumes it differs (per [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
 
-- **Claude Code** and **Copilot CLI** — the bundled `.mcp.json` is loaded automatically when the
-  plugin is installed; no extra configuration is needed.
-- **VS Code** consumes MCP but does not bundle it from a plugin. Add the equivalent entry to your
-  workspace `.vscode/mcp.json` (note the key is `servers`, not `mcpServers`):
+- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `.mcp.json` is loaded automatically
+  when the plugin is installed; no extra configuration is needed. In VS Code the server starts and
+  stops with the plugin and needs no separate trust prompt, because installing the plugin is what
+  grants the trust.
 
-  ```json
-  {
-    "servers": {
-      "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve"] }
-    }
+You only need to write MCP config by hand if you are **not** installing this as a plugin — then add the
+server to your workspace `.vscode/mcp.json` (note the key there is `servers`, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve"] }
   }
-  ```
+}
+```
 
-All three paths invoke the same `flux-operator-mcp` binary, so install it first — e.g.
+Every path invokes the same `flux-operator-mcp` binary, so install it first — e.g.
 `brew install controlplaneio-fluxcd/tap/flux-operator-mcp` or `go install
 github.com/controlplaneio-fluxcd/flux-operator/cmd/mcp@latest` (it reads your kubeconfig from
 `KUBECONFIG` / `~/.kube/config`). See the
@@ -117,18 +120,18 @@ The agent is authored once as `agents/<name>.md` (Markdown + YAML frontmatter, w
 `name`/`description`/`tools`/`model` core). How each tool consumes it differs (per
 [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
 
-- **Claude Code** and **Copilot CLI** — the bundled `agents/` directory is loaded automatically when
-  the plugin is installed; the agent is namespaced `gitops-kubernetes:flux-troubleshooter`. (Copilot
-  reads the same file as `*.agent.md`.)
-- **VS Code** consumes agents but does not bundle them from a plugin. Copy the agent to your
-  workspace as `.github/agents/flux-troubleshooter.agent.md`.
+- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded
+  automatically when the plugin is installed; in Claude Code the agent is namespaced
+  `gitops-kubernetes:flux-troubleshooter`. (Copilot reads the same file as `*.agent.md`.)
+
+As with MCP, hand-placing an agent at `.github/agents/<name>.agent.md` is only for setups that aren't
+installing this as a plugin.
 
 The [`vibe-coding`](plugins/vibe-coding/) plugin bundles
 [`vibe-coding-companion`](plugins/vibe-coding/agents/vibe-coding-companion.md) — a plain-language
 build companion for a non-technical audience (design:
-[ADR 0003](docs/adr/0003-vibe-coding-plugin-design.md)). Same delivery rules; its VS Code copy is
-`.github/agents/vibe-coding-companion.agent.md`, and its guardrail requires the consuming
-deployment to author a `## Stack map` section in its `AGENTS.md` (see the
+[ADR 0003](docs/adr/0003-vibe-coding-plugin-design.md)). Same delivery rules. Its guardrail requires
+the consuming deployment to author a `## Stack map` section in its `AGENTS.md` (see the
 [plugin README](plugins/vibe-coding/README.md)).
 
 The [`automated-ai-engineer`](plugins/automated-ai-engineer/) plugin bundles two agents —
diff --git a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
index e80e7eb..339da21 100644
--- a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
+++ b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
@@ -16,6 +16,27 @@
 > `skills/` and `agents/` directories. The tables and CI notes below are corrected accordingly; the
 > resource model (§D1) and the rest of the decision stand.
 
+> **Correction (2026-07-18) — VS Code is now a plugin surface.** This ADR's central asymmetry finding —
+> *"VS Code is not a plugin surface"*, so a bundled MCP server or agent must reach it as hand-written
+> per-workspace config — has been **overtaken by VS Code shipping
+> [agent plugins](https://code.visualstudio.com/docs/agent-customization/agent-plugins)** (Preview).
+> VS Code now installs plugins from a marketplace and loads their bundled components directly:
+> *"When you install a plugin, its commands, skills, agents, hooks, and MCP servers appear in chat."*
+> It reads the **same on-disk defaults this repo already publishes** — `skills` *"Defaults to
+> `skills/`"*, `agents` *"Defaults to `agents/`"*, and for MCP *"Place MCP server definitions in
+> `.mcp.json` at the plugin root. VS Code discovers this file automatically when it loads the plugin."*
+> Plugin MCP servers also *"start automatically when the plugin is enabled"* and are *"implicitly
+> trusted when you install the plugin"*, with no per-workspace entry and no startup trust prompt.
+>
+> **Consequence:** the delivery asymmetry this ADR treated as a permanent negative is **gone** — all
+> three supported tools now bundle all three resource types from one unchanged plugin directory, and no
+> manual copy step is required anywhere. The matrix and analysis below are corrected accordingly. Two
+> VS-Code-only caveats replace it, both install-time rather than per-resource: the feature is gated by
+> the `chat.plugins.enabled` setting (*"managed at the organization level"*), and it is marked
+> **Preview**, so the contract may still move. The decision (§D1–D4) and the resource model stand
+> unchanged — this correction *strengthens* them, since the canonical `.mcp.json` / `agents/` layout
+> D1 chose turns out to be exactly what VS Code reads.
+
 ## Context
 
 `AGENTS.md` and the README already commit this marketplace to being **tool-neutral and not
@@ -60,10 +81,10 @@ VS Code [MCP config](https://code.visualstudio.com/docs/agents/reference/mcp-con
 
 | Capability | Claude Code | GitHub Copilot CLI / cloud agent | VS Code (Copilot) |
 |---|---|---|---|
-| **Plugin / marketplace bundle** | ✅ `.claude-plugin/marketplace.json` + a plugin dir (`plugin.json`) bundling skills, `agents/`, `.mcp.json`, hooks, commands — installed as one unit | ✅ **`plugin.json` + `marketplace.json`** bundling `skills`, `agents`, `mcpServers`, `hooks`, `commands`, `lspServers`; installed via `copilot plugin install` or `enabledPlugins` in `~/.copilot/settings.json` / `.github/copilot/settings.json` | ❌ Not a plugin surface; consumes MCP/agents as per-workspace/repo config |
-| **Agent Skills** | ✅ `skills/<skill>/SKILL.md` ([agentskills.io](https://agentskills.io) open spec) | ✅ `skills` field (default `skills/`), `SKILL.md` | ✅ Agent Skills |
-| **MCP servers** | ✅ **bundled** — `.mcp.json` at plugin root (or inline `mcpServers` in `plugin.json`), auto-discovered | ✅ **bundled** — `mcpServers` field → `.mcp.json` / `.github/mcp.json` (or inline), key `mcpServers` | ✅ consumed, **not bundled** — `.vscode/mcp.json` / user `mcp.json`, key `servers` |
-| **Custom agents** | ✅ **bundled** — `agents/*.md` (md + YAML frontmatter), auto-discovered, namespaced `plugin:agent` | ✅ **bundled** — `agents` field (default `agents/`), `*.agent.md`, ID from filename | ✅ consumed, **not bundled** — `.github/agents/*.agent.md` (renamed from `.chatmode.md`) |
+| **Plugin / marketplace bundle** | ✅ `.claude-plugin/marketplace.json` + a plugin dir (`plugin.json`) bundling skills, `agents/`, `.mcp.json`, hooks, commands — installed as one unit | ✅ **`plugin.json` + `marketplace.json`** bundling `skills`, `agents`, `mcpServers`, `hooks`, `commands`, `lspServers`; installed via `copilot plugin install` or `enabledPlugins` in `~/.copilot/settings.json` / `.github/copilot/settings.json` | ✅ **`plugin.json` + marketplace** (Preview) — added via `chat.plugins.marketplaces`, installed from **Extensions → `@agentPlugins`**; gated by `chat.plugins.enabled` |
+| **Agent Skills** | ✅ `skills/<skill>/SKILL.md` ([agentskills.io](https://agentskills.io) open spec) | ✅ `skills` field (default `skills/`), `SKILL.md` | ✅ **bundled** — `skills` field, *"Defaults to `skills/`"* |
+| **MCP servers** | ✅ **bundled** — `.mcp.json` at plugin root (or inline `mcpServers` in `plugin.json`), auto-discovered | ✅ **bundled** — `mcpServers` field → `.mcp.json` / `.github/mcp.json` (or inline), key `mcpServers` | ✅ **bundled** — `.mcp.json` at plugin root, *"discovers this file automatically"*; starts with the plugin, no trust prompt |
+| **Custom agents** | ✅ **bundled** — `agents/*.md` (md + YAML frontmatter), auto-discovered, namespaced `plugin:agent` | ✅ **bundled** — `agents` field (default `agents/`), `*.agent.md`, ID from filename | ✅ **bundled** — `agents` field, *"Defaults to `agents/`"* |
 
 ### What is tool-neutral vs tool-specific
 
@@ -82,22 +103,25 @@ VS Code [MCP config](https://code.visualstudio.com/docs/agents/reference/mcp-con
   - **The custom-agent *body*** — markdown + YAML frontmatter with the neutral core `name` +
     `description` + `tools` + `model`. Converged de-facto across all three.
 - **Tool-specific (the residual divergence — now small):**
-  - **VS Code is not a plugin surface.** It is the one supported tool with no plugin/marketplace bundle;
-    it consumes MCP via `.vscode/mcp.json` (key **`servers`**, not `mcpServers`) and agents via
-    `.github/agents/*.agent.md`. A bundled MCP/agent must be delivered to VS Code as documented config.
+  - **VS Code's plugin support is Preview and setting-gated.** *(Superseding the original
+    "VS Code is not a plugin surface" finding — see the 2026-07-18 correction.)* VS Code now bundles all
+    three resource types from the same plugin directory, so the delivery asymmetry is gone; what remains
+    is install-time, not per-resource: `chat.plugins.enabled` must be on (*"managed at the organization
+    level"*) and the feature is marked **Preview**. Its non-plugin config paths — `.vscode/mcp.json`
+    (key **`servers`**) and `.github/agents/*.agent.md` — still exist for hand-authored,
+    non-plugin setups, but are no longer required to consume a plugin.
   - **The MCP wrapper key:** `mcpServers` (Claude Code, Copilot) vs `servers` (VS Code); the `type` enum
     (`stdio`/`local`); VS Code's `inputs`/`oauth`/`sandbox`; Copilot's per-agent `tools` allow-list.
   - **Custom-agent file convention:** `agents/*.md` (Claude Code) vs `agents/*.agent.md` (Copilot, where
     the ID derives from the filename) vs `.github/agents/*.agent.md` (VS Code), plus Copilot-only
     frontmatter (`target`, `mcp-servers`, `user-invocable`).
 
-**The load-bearing consequence (corrected):** bundling an MCP server or a custom agent is **natively
-supported by both Claude Code *and* Copilot CLI** from a single plugin dir — the marketplace's committed
-"not skills-only" promise is realizable as a *true cross-tool bundle*, not a Claude-only bundle plus
-docs. Only **VS Code** needs the same resource delivered as documented per-workspace config. So a
-non-skill plugin has **one bundled path serving both plugin-native tools** (from the canonical
-`.mcp.json` / `agents/`) and **one documented path for VS Code** — and the marketplace must be honest
-that VS Code is the sole consume-via-config surface, not imply that Copilot needs hand-configuration.
+**The load-bearing consequence (corrected 2026-07-18):** bundling an MCP server or a custom agent is
+**natively supported by all three supported tools** — Claude Code, Copilot CLI, *and* VS Code — from a
+single unchanged plugin dir. The marketplace's committed "not skills-only" promise is realizable as a
+*true cross-tool bundle* with **no documented manual step on any surface**: one bundled path, from the
+canonical `.mcp.json` / `agents/`, serves everything. (This originally read that VS Code was the sole
+consume-via-config surface; that asymmetry no longer exists.)
 
 ## Decision
 
@@ -215,10 +239,11 @@ named in #39.
 
 **Negative / risks**
 
-- **Asymmetric delivery (VS Code only):** MCP/agent bundles are auto-installed on both Claude Code and
-  Copilot CLI; **VS Code** is the sole surface that requires a documented manual config step. This must
-  be stated plainly in each such plugin's README so cross-tool expectations stay honest — but the
-  asymmetry is now one tool, not two.
+- ~~**Asymmetric delivery (VS Code only):**~~ **Resolved 2026-07-18** — VS Code shipped agent plugins
+  and now auto-loads bundled skills, agents, and MCP servers from the same plugin dir, so no surface
+  requires a manual config step. Two install-time caveats replace the risk: VS Code's support is
+  **Preview** (the contract may move) and is gated by `chat.plugins.enabled`, *"managed at the
+  organization level"* — so a plugin can be blocked by org policy rather than by packaging.
 - **CI surface grows:** the validator gains MCP/agent branches and new self-test fixtures — more to
   maintain, but bounded and self-tested.
 - **Versioning:** a bundled MCP server pins a server version/source; keeping it fresh is new maintenance
diff --git a/docs/adr/0003-vibe-coding-plugin-design.md b/docs/adr/0003-vibe-coding-plugin-design.md
index c187776..1ba1987 100644
--- a/docs/adr/0003-vibe-coding-plugin-design.md
+++ b/docs/adr/0003-vibe-coding-plugin-design.md
@@ -7,6 +7,15 @@
 
 > 🤖 Generated by the Daily AI Engineer
 
+> **Correction (2026-07-18) — the VS Code delivery step is obsolete.** D5's child-3 bullet required the
+> plugin README to carry a manual *"VS Code delivery step"* (copy the companion agent to
+> `.github/agents/<name>.agent.md`), because ADR-0001 found VS Code could not bundle plugin agents.
+> **VS Code has since shipped [agent plugins](https://code.visualstudio.com/docs/agent-customization/agent-plugins)**
+> and now loads a plugin's bundled `agents/` directory automatically — see the 2026-07-18 correction on
+> [ADR 0001](0001-bundling-mcp-servers-and-custom-agents.md). The copy step has been removed from the
+> plugin README; the requirement it satisfied (AC1 coverage of the VS Code surface) is now met by the
+> plugin install itself. The rest of this ADR stands.
+
 ## Context
 
 [#49](https://github.com/devantler-tech/agent-plugins/issues/49) asks for a plugin that lets a
@@ -126,10 +135,12 @@ The persona's conversational contract (agent definition + the voice skill):
   specifics in skill bodies).
 - **Child 3 — assemble:** `plugins/vibe-coding/` — the companion agent under `agents/`, the three
   skills bundled from agent-skills, both manifests + README updated in parity, validated by the
-  standard gate (`scripts/validate-manifests.sh`, skill spec-validation). Bundled `agents/` auto-load
+  standard gate (`scripts/validate-manifests.sh`, skill spec-validation). ~~Bundled `agents/` auto-load
   only in Claude Code and Copilot CLI (ADR-0001; repo README), so the plugin README must carry the
   documented **VS Code delivery step** — copy the companion agent to `.github/agents/<name>.agent.md`
-  — for AC1's coverage of the marketplace's supported VS Code surface.
+  — for AC1's coverage of the marketplace's supported VS Code surface.~~ **Superseded 2026-07-18:**
+  bundled `agents/` auto-load in VS Code too, so AC1's VS Code coverage is met by the plugin install and
+  no delivery step is documented (see the correction note above).
 - **Child 4 — consume & E2E:** author devantler-tech's Stack map in the consuming deployment and
   validate the plugin end-to-end per the verify-it-works-behaviourally rule — voice and guardrail
   quality cannot be proven by manifest validation alone. The scenario set covers **both sides of the
diff --git a/plugins/vibe-coding/README.md b/plugins/vibe-coding/README.md
index a451285..3ce223c 100644
--- a/plugins/vibe-coding/README.md
+++ b/plugins/vibe-coding/README.md
@@ -20,8 +20,11 @@ carry a **`## Stack map`** section: a table with **Building block** / **Good for
 repo** columns plus a **default intake repo** for unmapped needs. Without it the plugin fails
 closed (declines every build). See ADR 0003 D3 for the pinned contract.
 
-## VS Code delivery step
+## Getting the companion agent
 
-Claude Code and Copilot CLI load the bundled `agents/` directory automatically when the plugin is
-installed. **VS Code does not** — copy the companion agent into your workspace as
-`.github/agents/vibe-coding-companion.agent.md` to use it there.
+Claude Code, Copilot CLI, and VS Code all load the bundled `agents/` directory automatically when the
+plugin is installed — there is no copy step on any of them. In VS Code this needs the
+`chat.plugins.enabled` setting, which your organization may control.
+
+If you are not installing this as a plugin, place the companion agent in your workspace by hand as
+`.github/agents/vibe-coding-companion.agent.md`.

From 21e63f0cd63005bd12216615e611f672db2d2827 Mon Sep 17 00:00:00 2001
From: Nikolai Emil Damm <nikolaiemildamm@icloud.com>
Date: Sat, 18 Jul 2026 15:54:44 +0200
Subject: [PATCH 2/5] fix(agents): use VS Code-discoverable .agent.md filenames
 for bundled agents

Address codex review: VS Code only discovers plugin agents named
agents/<name>.agent.md, so the no-copy claim required the rename. Claude Code
is filename-agnostic (frontmatter-named), so one file serves all three tools.
Also purge the residual manual-VS-Code-config text from ADR 0001's D2/D4/
Follow-up sections, and teach the manifest validator + self-test the
.agent.md stem derivation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                                     | 18 ++++++++-------
 ...-bundling-mcp-servers-and-custom-agents.md | 23 +++++++++++--------
 ...neer.md => automated-ai-engineer.agent.md} |  0
 ...urveyor.md => portfolio-surveyor.agent.md} |  0
 ...hooter.md => flux-troubleshooter.agent.md} |  0
 ...nion.md => vibe-coding-companion.agent.md} |  0
 scripts/validate-manifests.sh                 |  8 ++++---
 scripts/validate-manifests.test.sh            |  8 +++++++
 8 files changed, 36 insertions(+), 21 deletions(-)
 rename plugins/automated-ai-engineer/agents/{automated-ai-engineer.md => automated-ai-engineer.agent.md} (100%)
 rename plugins/automated-ai-engineer/agents/{portfolio-surveyor.md => portfolio-surveyor.agent.md} (100%)
 rename plugins/gitops-kubernetes/agents/{flux-troubleshooter.md => flux-troubleshooter.agent.md} (100%)
 rename plugins/vibe-coding/agents/{vibe-coding-companion.md => vibe-coding-companion.agent.md} (100%)

diff --git a/README.md b/README.md
index 0c9ff7f..7da00cf 100644
--- a/README.md
+++ b/README.md
@@ -110,34 +110,36 @@ transport.
 
 A plugin may also bundle **custom agents** (subagents). The
 [`gitops-kubernetes`](plugins/gitops-kubernetes/) plugin bundles
-[`flux-troubleshooter`](plugins/gitops-kubernetes/agents/flux-troubleshooter.md) — a **read-only**
+[`flux-troubleshooter`](plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md) — a **read-only**
 Flux CD triage agent that traces the GitOps dependency chain (source → Kustomization/HelmRelease →
 workloads), reads status conditions and controller logs via the bundled `flux-operator-mcp` server,
 and returns a root-cause diagnosis plus the human-applied fix. It has no apply/reconcile/suspend/
 delete tool by design, so it never mutates the cluster.
 
-The agent is authored once as `agents/<name>.md` (Markdown + YAML frontmatter, with the neutral
-`name`/`description`/`tools`/`model` core). How each tool consumes it differs (per
-[ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
+The agent is authored once as `agents/<name>.agent.md` (Markdown + YAML frontmatter, with the neutral
+`name`/`description`/`tools`/`model` core). The `.agent.md` filename is what VS Code and Copilot
+discover inside a plugin's `agents/` directory; Claude Code is filename-agnostic (it reads any
+Markdown in `agents/` and takes the agent's name from frontmatter), so one file serves all three
+tools (per [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
 
 - **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded
   automatically when the plugin is installed; in Claude Code the agent is namespaced
-  `gitops-kubernetes:flux-troubleshooter`. (Copilot reads the same file as `*.agent.md`.)
+  `gitops-kubernetes:flux-troubleshooter`.
 
 As with MCP, hand-placing an agent at `.github/agents/<name>.agent.md` is only for setups that aren't
 installing this as a plugin.
 
 The [`vibe-coding`](plugins/vibe-coding/) plugin bundles
-[`vibe-coding-companion`](plugins/vibe-coding/agents/vibe-coding-companion.md) — a plain-language
+[`vibe-coding-companion`](plugins/vibe-coding/agents/vibe-coding-companion.agent.md) — a plain-language
 build companion for a non-technical audience (design:
 [ADR 0003](docs/adr/0003-vibe-coding-plugin-design.md)). Same delivery rules. Its guardrail requires
 the consuming deployment to author a `## Stack map` section in its `AGENTS.md` (see the
 [plugin README](plugins/vibe-coding/README.md)).
 
 The [`automated-ai-engineer`](plugins/automated-ai-engineer/) plugin bundles two agents —
-[`automated-ai-engineer`](plugins/automated-ai-engineer/agents/automated-ai-engineer.md) (the
+[`automated-ai-engineer`](plugins/automated-ai-engineer/agents/automated-ai-engineer.agent.md) (the
 autonomous portfolio-engineer actor) and
-[`portfolio-surveyor`](plugins/automated-ai-engineer/agents/portfolio-surveyor.md) (its read-only
+[`portfolio-surveyor`](plugins/automated-ai-engineer/agents/portfolio-surveyor.agent.md) (its read-only
 survey subagent) — alongside its three engineering skills (design:
 [ADR 0002](docs/adr/0002-automated-ai-engineer-plugin-boundary.md)). Same delivery rules; the
 consuming deployment must define the five contract sections (Portfolio map, Trust gate, Cadence,
diff --git a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
index 339da21..b81f524 100644
--- a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
+++ b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
@@ -152,13 +152,15 @@ the canonical model, consumed natively by both plugin-native tools and documente
 - **Copilot CLI / cloud agent:** the **same** `.mcp.json` is bundled — `plugin.json`'s `mcpServers`
   field resolves to it (and the plugin installs via `copilot plugin install` or `enabledPlugins`). No
   hand-configuration; the server ships *inside* the plugin exactly as on Claude Code.
-- **VS Code:** the only consume-via-config surface — the plugin README documents the equivalent
-  `.vscode/mcp.json` entry under the **`servers`** key (key-renamed from the canonical `mcpServers`;
-  same per-server shape).
+- **VS Code:** ~~the only consume-via-config surface~~ **now a plugin-native consumer too** (see the
+  2026-07-18 correction above): it discovers the bundled `.mcp.json` automatically when the plugin
+  loads, and the server starts with the plugin. The plugin README's `.vscode/mcp.json` snippet
+  (**`servers`** key, key-renamed from the canonical `mcpServers`; same per-server shape) remains
+  **only** for setups that consume the server without installing the plugin.
 
-The README install snippet is the parity mechanism for VS Code alone — generated from the one canonical
-`.mcp.json`, never independently authored, so it cannot drift in substance. Claude Code and Copilot CLI
-need no snippet; they bundle the canonical file directly.
+The README install snippet is the parity mechanism for non-plugin setups alone — generated from the one
+canonical `.mcp.json`, never independently authored, so it cannot drift in substance. Plugin installs
+need no snippet on any of the three tools; they bundle the canonical file directly.
 
 ### D3 — CI / manifest changes (the gate stays the contract)
 
@@ -199,8 +201,9 @@ the first proof. Rationale: the bundled `gitops-cluster-debug` skill already dec
 `compatibility: Requires flux-operator-mcp` and, on failure, tells the user *"the `flux-operator-mcp`
 server is not running. Provide the install command."* Bundling the server makes that skill
 **self-sufficient on Claude Code** and is the highest-utility, lowest-divergence first bundle — a skill
-and the MCP it already depends on, shipped together. Copilot CLI / VS Code get the documented config per
-D2. This is exactly the "MCP paired with an existing plugin where the skills already assume it" candidate
+and the MCP it already depends on, shipped together. Copilot CLI and VS Code load the same bundle
+(per the 2026-07-18 correction; D2's documented config remains only for non-plugin setups). This is
+exactly the "MCP paired with an existing plugin where the skills already assume it" candidate
 named in #39.
 
 ## Considered alternatives
@@ -253,7 +256,7 @@ named in #39.
 
 - **AC#3 child ([#42](https://github.com/devantler-tech/agent-plugins/issues/42), next):** implement D3
   (validator + self-test generalization) **and** D4 (the `flux-operator-mcp` bundle in
-  `gitops-kubernetes`: `.mcp.json`, README bundled + Copilot/VS Code config snippets, manifest/README
-  prose broadening) in one PR — the design here is the contract it implements.
+  `gitops-kubernetes`: `.mcp.json`, README bundled note + the non-plugin-setup config snippet,
+  manifest/README prose broadening) in one PR — the design here is the contract it implements.
 - Custom-agent bundling (the `agents/` path in D1/D3) proves out after the MCP path, as a later child of
   epic #38 Theme 1.
diff --git a/plugins/automated-ai-engineer/agents/automated-ai-engineer.md b/plugins/automated-ai-engineer/agents/automated-ai-engineer.agent.md
similarity index 100%
rename from plugins/automated-ai-engineer/agents/automated-ai-engineer.md
rename to plugins/automated-ai-engineer/agents/automated-ai-engineer.agent.md
diff --git a/plugins/automated-ai-engineer/agents/portfolio-surveyor.md b/plugins/automated-ai-engineer/agents/portfolio-surveyor.agent.md
similarity index 100%
rename from plugins/automated-ai-engineer/agents/portfolio-surveyor.md
rename to plugins/automated-ai-engineer/agents/portfolio-surveyor.agent.md
diff --git a/plugins/gitops-kubernetes/agents/flux-troubleshooter.md b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
similarity index 100%
rename from plugins/gitops-kubernetes/agents/flux-troubleshooter.md
rename to plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
diff --git a/plugins/vibe-coding/agents/vibe-coding-companion.md b/plugins/vibe-coding/agents/vibe-coding-companion.agent.md
similarity index 100%
rename from plugins/vibe-coding/agents/vibe-coding-companion.md
rename to plugins/vibe-coding/agents/vibe-coding-companion.agent.md
diff --git a/scripts/validate-manifests.sh b/scripts/validate-manifests.sh
index bfe6320..750d0fe 100755
--- a/scripts/validate-manifests.sh
+++ b/scripts/validate-manifests.sh
@@ -243,13 +243,14 @@ validate_marketplace_plugins_parity() {
 # resource kinds validate_plugin_json accepts (ADR 0001 §D3): every skill directory under
 # plugins/<name>/skills/, every MCP server key in an optional plugins/<name>/.mcp.json, AND
 # every custom-agent entry under an optional plugins/<name>/agents/ (its basename, with a
-# trailing .md stripped). These are the tokens the README "Resources" column must list.
+# trailing .agent.md — VS Code's discovery suffix, ADR 0001's 2026-07-18 correction — or bare
+# .md stripped). These are the tokens the README "Resources" column must list.
 # Count EVERY skill directory / agent entry, not only those already fleshed out, so a
 # stray/half-added folder (the exact drift this parity check guards against) is surfaced
 # rather than silently hidden. Kept in lockstep with validate_plugin_json's resource model
 # so a plugin can never satisfy that check with a resource kind this enumerator ignores.
 plugin_disk_resources() {
-  local name="$1" d mcp="plugins/$1/.mcp.json"
+  local name="$1" d b mcp="plugins/$1/.mcp.json"
   {
     for d in "plugins/$name/skills"/*/; do
       [ -d "$d" ] || continue
@@ -260,7 +261,8 @@ plugin_disk_resources() {
     fi
     for d in "plugins/$name/agents"/*; do
       [ -e "$d" ] || continue
-      basename "$d" .md
+      b="$(basename "$d" .md)"
+      printf '%s\n' "${b%.agent}"
     done
   } | sort | tr '\n' ' '
 }
diff --git a/scripts/validate-manifests.test.sh b/scripts/validate-manifests.test.sh
index b654e98..d388b5f 100755
--- a/scripts/validate-manifests.test.sh
+++ b/scripts/validate-manifests.test.sh
@@ -344,6 +344,14 @@ d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.md
 check_fail "custom agent missing from README resources fails" "README.md Resources for 'alpha'" "$d"
 
+# VS Code's discovery suffix (<name>.agent.md, ADR 0001's 2026-07-18 correction) resolves to the
+# same README token as <name>.md — the enumerator strips the whole .agent.md, never just .md.
+d=$(fresh)
+mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.agent.md
+# shellcheck disable=SC2016
+sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md"
+check_pass "agent named <name>.agent.md resolves to <name> in README resources" "$d"
+
 # An agents/ dir with no *.md (only a stray non-agent file) is not a valid agent resource.
 d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"; printf 'notes\n' > "$d/plugins/alpha/agents/README.txt"

From 04d1076324dd31b88e8a6e775d7b62e5f85725fd Mon Sep 17 00:00:00 2001
From: Nikolai Emil Damm <nikolaiemildamm@icloud.com>
Date: Sat, 18 Jul 2026 16:14:28 +0200
Subject: [PATCH 3/5] fix(agents): enforce the .agent.md suffix and make the
 agent portable cross-tool

Address codex round 2: the validator now rejects bare .md agents (invisible to
VS Code/Copilot discovery; RED-proven fixture), the Flux agent's MCP allowlist
carries both tool-name spellings so the one-file claim actually holds on all
three tools, and the vibe-coding non-plugin fallback installs the companion's
three load-bearing skills.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                                     |  5 ++++-
 .../agents/flux-troubleshooter.agent.md       |  5 ++++-
 plugins/vibe-coding/README.md                 |  8 ++++++-
 scripts/validate-manifests.sh                 | 17 ++++++++++++---
 scripts/validate-manifests.test.sh            | 21 ++++++++++---------
 5 files changed, 40 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 7da00cf..5af61b2 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,10 @@ The agent is authored once as `agents/<name>.agent.md` (Markdown + YAML frontmat
 `name`/`description`/`tools`/`model` core). The `.agent.md` filename is what VS Code and Copilot
 discover inside a plugin's `agents/` directory; Claude Code is filename-agnostic (it reads any
 Markdown in `agents/` and takes the agent's name from frontmatter), so one file serves all three
-tools (per [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
+tools. The same goes for the `tools:` allowlist: MCP tools are listed in both spellings — Claude
+Code's `mcp__<server>__<tool>` and VS Code / Copilot's `<server>/<tool>` — because each tool
+ignores entries it does not recognise (per
+[ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)):
 
 - **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded
   automatically when the plugin is installed; in Claude Code the agent is namespaced
diff --git a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
index 2c9e953..06a1bee 100644
--- a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
+++ b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
@@ -9,7 +9,10 @@ description: >-
   against the Git manifests, and returns a structured diagnosis plus the exact
   human-applied fix. It never applies, reconciles, suspends, resumes, or deletes —
   hand any remediation back to the caller.
-tools: Read, Grep, Glob, mcp__flux-operator-mcp__get_flux_instance, mcp__flux-operator-mcp__get_kubeconfig_contexts, mcp__flux-operator-mcp__get_kubernetes_api_versions, mcp__flux-operator-mcp__get_kubernetes_resources, mcp__flux-operator-mcp__get_kubernetes_logs
+# The MCP tools are listed in BOTH spellings on purpose: Claude Code allowlists them as
+# mcp__<server>__<tool>, VS Code / Copilot CLI as <server>/<tool>, and each tool ignores
+# allowlist entries it does not recognise — so one file serves all three tools.
+tools: Read, Grep, Glob, mcp__flux-operator-mcp__get_flux_instance, mcp__flux-operator-mcp__get_kubeconfig_contexts, mcp__flux-operator-mcp__get_kubernetes_api_versions, mcp__flux-operator-mcp__get_kubernetes_resources, mcp__flux-operator-mcp__get_kubernetes_logs, flux-operator-mcp/get_flux_instance, flux-operator-mcp/get_kubeconfig_contexts, flux-operator-mcp/get_kubernetes_api_versions, flux-operator-mcp/get_kubernetes_resources, flux-operator-mcp/get_kubernetes_logs
 model: sonnet
 ---
 
diff --git a/plugins/vibe-coding/README.md b/plugins/vibe-coding/README.md
index 3ce223c..6d962db 100644
--- a/plugins/vibe-coding/README.md
+++ b/plugins/vibe-coding/README.md
@@ -27,4 +27,10 @@ plugin is installed — there is no copy step on any of them. In VS Code this ne
 `chat.plugins.enabled` setting, which your organization may control.
 
 If you are not installing this as a plugin, place the companion agent in your workspace by hand as
-`.github/agents/vibe-coding-companion.agent.md`.
+`.github/agents/vibe-coding-companion.agent.md` — **and install its three load-bearing skills too**
+(the agent's guardrails defer to them), e.g.:
+
+```sh
+npx skills add devantler-tech/agent-plugins --skill needs-stack-mapping \
+  --skill allowed-stack-guardrail --skill jargon-free-voice
+```
diff --git a/scripts/validate-manifests.sh b/scripts/validate-manifests.sh
index 750d0fe..262cc35 100755
--- a/scripts/validate-manifests.sh
+++ b/scripts/validate-manifests.sh
@@ -95,13 +95,24 @@ frontmatter_has_value() {
 }
 
 # A bundled custom-agents resource (ADR 0001 §D1/§D3): an agents/ directory must hold at least
-# one agents/*.md, and every agent file must carry YAML frontmatter with a non-empty 'name' and
-# 'description' (the neutral cross-tool core). A body-only or placeholder .md is rejected.
+# one agents/*.agent.md, and every agent file must carry YAML frontmatter with a non-empty 'name'
+# and 'description' (the neutral cross-tool core). The .agent.md suffix is REQUIRED — it is the
+# discovery pattern VS Code and Copilot CLI use, while Claude Code is filename-agnostic, so a bare
+# .md agent would pass CI yet be invisible on two of the three supported tools. A body-only or
+# placeholder file is rejected.
 validate_agent_dir() {
   local dir="$1" md count=0 failed=0
   for md in "$dir"/*.md; do
     [ -e "$md" ] || continue
     count=$((count + 1))
+    case "$md" in
+      *.agent.md) ;;
+      *)
+        echo "::error::$md: agent files must use the <name>.agent.md suffix (VS Code/Copilot discovery; bare .md is invisible there)"
+        failed=1
+        continue
+        ;;
+    esac
     if ! frontmatter_has_value "$md" name; then
       echo "::error::$md: agent must declare a non-empty 'name' in its YAML frontmatter"
       failed=1
@@ -112,7 +123,7 @@ validate_agent_dir() {
     fi
   done
   if [ "$count" -eq 0 ]; then
-    echo "::error::$dir: must contain at least one agents/*.md"
+    echo "::error::$dir: must contain at least one agents/*.agent.md"
     return 1
   fi
   return "$failed"
diff --git a/scripts/validate-manifests.test.sh b/scripts/validate-manifests.test.sh
index d388b5f..2992444 100755
--- a/scripts/validate-manifests.test.sh
+++ b/scripts/validate-manifests.test.sh
@@ -332,16 +332,17 @@ Agent body.
 EOF
 }
 
-# A plugin bundling a conformant agents/<name>.md passes when that agent name is in the README.
+# A conformant agent under the bare .md name FAILS: VS Code and Copilot CLI only discover
+# agents/*.agent.md, so a bare .md would pass CI while being invisible on two of three tools.
 d=$(fresh)
-mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.md
+mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" bare-agent.md
 # shellcheck disable=SC2016
-sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md"
-check_pass "plugin bundling a custom agent passes (agent in README resources)" "$d"
+sed 's/`example-skill` | Alpha plugin/`example-skill`, `bare-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md"
+check_fail "agent named bare .md fails (not VS Code/Copilot-discoverable)" "must use the <name>.agent.md suffix" "$d"
 
 # A bundled agent name missing from the README Resources column drifts out of lockstep.
 d=$(fresh)
-mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.md
+mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.agent.md
 check_fail "custom agent missing from README resources fails" "README.md Resources for 'alpha'" "$d"
 
 # VS Code's discovery suffix (<name>.agent.md, ADR 0001's 2026-07-18 correction) resolves to the
@@ -355,17 +356,17 @@ check_pass "agent named <name>.agent.md resolves to <name> in README resources"
 # An agents/ dir with no *.md (only a stray non-agent file) is not a valid agent resource.
 d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"; printf 'notes\n' > "$d/plugins/alpha/agents/README.txt"
-check_fail "agents/ with no *.md fails" "must contain at least one agents/*.md" "$d"
+check_fail "agents/ with no *.md fails" "must contain at least one agents/*.agent.md" "$d"
 
 # A body-only agent (no YAML frontmatter) is rejected — placeholders must not pass.
 d=$(fresh)
-mkdir -p "$d/plugins/alpha/agents"; printf '%s\n' 'Just a body, no frontmatter.' > "$d/plugins/alpha/agents/test-agent.md"
+mkdir -p "$d/plugins/alpha/agents"; printf '%s\n' 'Just a body, no frontmatter.' > "$d/plugins/alpha/agents/test-agent.agent.md"
 check_fail "agent .md without frontmatter fails" "must declare a non-empty 'name'" "$d"
 
 # An agent whose frontmatter omits 'description' is rejected.
 d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"
-cat > "$d/plugins/alpha/agents/test-agent.md" <<'EOF'
+cat > "$d/plugins/alpha/agents/test-agent.agent.md" <<'EOF'
 ---
 name: test-agent
 ---
@@ -376,7 +377,7 @@ check_fail "agent .md missing description fails" "must declare a non-empty 'desc
 # A folded/block-scalar description (>-) with a non-blank body satisfies the check.
 d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"
-cat > "$d/plugins/alpha/agents/test-agent.md" <<'EOF'
+cat > "$d/plugins/alpha/agents/test-agent.agent.md" <<'EOF'
 ---
 name: test-agent
 description: >-
@@ -392,7 +393,7 @@ check_pass "agent with a folded (>-) description passes" "$d"
 # A bare block-scalar description indicator with no body is empty ⇒ rejected.
 d=$(fresh)
 mkdir -p "$d/plugins/alpha/agents"
-cat > "$d/plugins/alpha/agents/test-agent.md" <<'EOF'
+cat > "$d/plugins/alpha/agents/test-agent.agent.md" <<'EOF'
 ---
 name: test-agent
 description: >-

From e50a2c08e9acafa903f3ecaab77cdfa229fe3f03 Mon Sep 17 00:00:00 2001
From: Nikolai Emil Damm <nikolaiemildamm@icloud.com>
Date: Sat, 18 Jul 2026 21:06:43 +0200
Subject: [PATCH 4/5] docs: fix the stale VS Code copy step and allowlist
 cross-tool read/search identifiers

Codex round-3 P2s: the merged-in automated-ai-engineer plugin README still
instructed VS Code users to hand-copy agents (contradicting the corrected
delivery model), and flux-troubleshooter's built-in tools carried only the
Claude Code spellings, leaving it unable to read or search the repo on
VS Code / Copilot CLI.
---
 plugins/automated-ai-engineer/README.md              | 12 +++---------
 .../agents/flux-troubleshooter.agent.md              | 11 +++++++----
 2 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/plugins/automated-ai-engineer/README.md b/plugins/automated-ai-engineer/README.md
index 3ad5f42..9d3c127 100644
--- a/plugins/automated-ai-engineer/README.md
+++ b/plugins/automated-ai-engineer/README.md
@@ -74,15 +74,9 @@ subagents), so a prompt-injected survey cannot escalate to writes even in princi
 
 ## Delivery
 
-**Claude Code** and **Copilot CLI** load the plugin's `agents/` directory automatically on install, so
-all three agents are available with no manual step. **VS Code consumes agents but does not bundle them
-from a plugin** — copy each one into your workspace:
-
-```text
-.github/agents/automated-ai-engineer.agent.md
-.github/agents/portfolio-surveyor.agent.md
-.github/agents/agent-improver.agent.md
-```
+**Claude Code**, **Copilot CLI**, and **VS Code** all load the plugin's `agents/` directory
+automatically on install, so all three agents are available with no manual step — the `.agent.md`
+filename suffix is what makes them discoverable on the VS Code/Copilot surfaces.
 
 (See the root README's [Custom agents](../../README.md#custom-agents) section for the shared delivery
 model.)
diff --git a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
index 06a1bee..7fe8d32 100644
--- a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
+++ b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
@@ -9,10 +9,13 @@ description: >-
   against the Git manifests, and returns a structured diagnosis plus the exact
   human-applied fix. It never applies, reconciles, suspends, resumes, or deletes —
   hand any remediation back to the caller.
-# The MCP tools are listed in BOTH spellings on purpose: Claude Code allowlists them as
-# mcp__<server>__<tool>, VS Code / Copilot CLI as <server>/<tool>, and each tool ignores
-# allowlist entries it does not recognise — so one file serves all three tools.
-tools: Read, Grep, Glob, mcp__flux-operator-mcp__get_flux_instance, mcp__flux-operator-mcp__get_kubeconfig_contexts, mcp__flux-operator-mcp__get_kubernetes_api_versions, mcp__flux-operator-mcp__get_kubernetes_resources, mcp__flux-operator-mcp__get_kubernetes_logs, flux-operator-mcp/get_flux_instance, flux-operator-mcp/get_kubeconfig_contexts, flux-operator-mcp/get_kubernetes_api_versions, flux-operator-mcp/get_kubernetes_resources, flux-operator-mcp/get_kubernetes_logs
+# Every tool is listed in BOTH spellings on purpose: Claude Code names the built-ins
+# Read/Grep/Glob and allowlists MCP tools as mcp__<server>__<tool>, while VS Code /
+# Copilot CLI use lower-case built-in identifiers (read, search) and <server>/<tool>
+# for MCP. Each tool ignores allowlist entries it does not recognise — so one file
+# serves all three surfaces, and dropping either spelling would leave the agent unable
+# to read or search the repository on the surface that uses it.
+tools: Read, Grep, Glob, read, search, mcp__flux-operator-mcp__get_flux_instance, mcp__flux-operator-mcp__get_kubeconfig_contexts, mcp__flux-operator-mcp__get_kubernetes_api_versions, mcp__flux-operator-mcp__get_kubernetes_resources, mcp__flux-operator-mcp__get_kubernetes_logs, flux-operator-mcp/get_flux_instance, flux-operator-mcp/get_kubeconfig_contexts, flux-operator-mcp/get_kubernetes_api_versions, flux-operator-mcp/get_kubernetes_resources, flux-operator-mcp/get_kubernetes_logs
 model: sonnet
 ---
 

From 5e5ee3afc873a70d9b68b15d0cb7270068b8f689 Mon Sep 17 00:00:00 2001
From: Nikolai Emil Damm <nikolaiemildamm@icloud.com>
Date: Sat, 18 Jul 2026 21:26:53 +0200
Subject: [PATCH 5/5] docs: encode the tools allowlist as a YAML list and sync
 the .agent.md contract

Codex round-4 P2s: the VS Code / Copilot custom-agent schema documents the
list form for tools (a scalar may not create individual allowlist entries
there), and the repo's canonical AGENTS.md + ADR 0001 D3 contract still
said agents/*.md while the new CI guard rejects exactly that layout.
Claude Code documents the comma-separated scalar; per-surface hands-on
confirmation of the list form is folded into #74's 3-consumer
verification.
---
 AGENTS.md                                     |  4 ++-
 ...-bundling-mcp-servers-and-custom-agents.md |  6 +++--
 .../agents/flux-troubleshooter.agent.md       | 27 ++++++++++++++++---
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e2f59d1..c757662 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -112,7 +112,9 @@ membership) is authored here.
    any `plugin.json` that sets `skills`/`agents` to a non-array. Skill dirs sit at
    `plugins/<plugin>/skills/<skill>/` and each holds a conformant `SKILL.md` (CI discovers them at
    depth 4). A bundled `.mcp.json` is a `{ "mcpServers": { … } }` map whose every server carries a
-   `command` (stdio) or `url` (remote). A bundled `agents/` directory holds ≥1 `agents/*.md`, each with
+   `command` (stdio) or `url` (remote). A bundled `agents/` directory holds ≥1 `agents/*.agent.md` —
+   the `.agent.md` suffix is REQUIRED (VS Code/Copilot discover agents by it; a bare `.md` is
+   invisible there, and CI's suffix guard rejects it) — each with
    YAML frontmatter carrying a non-empty `name` and `description` (the neutral cross-tool core). See
    [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md) for the cross-tool delivery model.
 3. **agentskills.io spec.** Every bundled `SKILL.md` must validate against the
diff --git a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
index b81f524..68bbda3 100644
--- a/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
+++ b/docs/adr/0001-bundling-mcp-servers-and-custom-agents.md
@@ -176,8 +176,10 @@ check is added for MCP well-formedness:
      that is set to a non-array, so the Claude-Code-breaking bare-string form can never return.
    - `.mcp.json` present → it must be valid JSON with a non-empty `.mcpServers` object, and each server
      must have a `command` (stdio) **or** a `url` (remote). (New check.)
-   - `agents/` present → ≥1 `agents/*.md`, each with YAML frontmatter carrying `name` + `description`.
-     (New check.)
+   - `agents/` present → ≥1 `agents/*.agent.md`, each with YAML frontmatter carrying `name` +
+     `description`. (New check; the suffix requirement is the 2026-07-18 correction — VS Code/Copilot
+     discover agents by the `.agent.md` suffix, so the guard rejects a bare `agents/*.md` that would be
+     invisible on two of the three tools.)
 2. **`validate_readme_parity`** — generalize the README **Skills** column to a **Resources** column that
    lists the plugin's resources (skill dir names, MCP server names, and/or agent names), and match it
    against on-disk resources. Skill-only rows are unaffected in substance (the column simply lists the
diff --git a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
index 7fe8d32..af78cfb 100644
--- a/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
+++ b/plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md
@@ -12,10 +12,29 @@ description: >-
 # Every tool is listed in BOTH spellings on purpose: Claude Code names the built-ins
 # Read/Grep/Glob and allowlists MCP tools as mcp__<server>__<tool>, while VS Code /
 # Copilot CLI use lower-case built-in identifiers (read, search) and <server>/<tool>
-# for MCP. Each tool ignores allowlist entries it does not recognise — so one file
-# serves all three surfaces, and dropping either spelling would leave the agent unable
-# to read or search the repository on the surface that uses it.
-tools: Read, Grep, Glob, read, search, mcp__flux-operator-mcp__get_flux_instance, mcp__flux-operator-mcp__get_kubeconfig_contexts, mcp__flux-operator-mcp__get_kubernetes_api_versions, mcp__flux-operator-mcp__get_kubernetes_resources, mcp__flux-operator-mcp__get_kubernetes_logs, flux-operator-mcp/get_flux_instance, flux-operator-mcp/get_kubeconfig_contexts, flux-operator-mcp/get_kubernetes_api_versions, flux-operator-mcp/get_kubernetes_resources, flux-operator-mcp/get_kubernetes_logs
+# for MCP. Each loader tolerates allowlist entries it does not recognise (Claude Code
+# fails only if NO entry resolves) — so one file serves all three surfaces, and
+# dropping either spelling would leave the agent unable to read or search the
+# repository on the surface that uses it. The YAML LIST form is what the VS Code /
+# Copilot custom-agent schema documents; Claude Code documents a comma-separated
+# scalar but its loader accepts both (hands-on confirmation per surface is tracked
+# in #74's 3-consumer verification).
+tools:
+  - Read
+  - Grep
+  - Glob
+  - read
+  - search
+  - mcp__flux-operator-mcp__get_flux_instance
+  - mcp__flux-operator-mcp__get_kubeconfig_contexts
+  - mcp__flux-operator-mcp__get_kubernetes_api_versions
+  - mcp__flux-operator-mcp__get_kubernetes_resources
+  - mcp__flux-operator-mcp__get_kubernetes_logs
+  - flux-operator-mcp/get_flux_instance
+  - flux-operator-mcp/get_kubeconfig_contexts
+  - flux-operator-mcp/get_kubernetes_api_versions
+  - flux-operator-mcp/get_kubernetes_resources
+  - flux-operator-mcp/get_kubernetes_logs
 model: sonnet
 ---