Verify VS Code discovery of bundled plugin agents and settle the agent filename convention

[devantler]

🤖 Generated by the Daily AI Engineer

Evidence: VS Code's agent-plugin docs show bundled agents as agents/*.agent.md (their only concrete example), while this repo authors all four bundled agents as agents/<name>.md. Whether VS Code picks up bare-.md agent files from an installed plugin is undocumented — the no-copy claim for agents in the VS Code lane is therefore unverified. Surfaced by Codex review on PR #72.

Audience/problem: VS Code users installing gitops-kubernetes or vibe-coding may get skills and MCP servers but silently no companion agent.

Hypothesis: renaming bundled agents to agents/<name>.agent.md makes them discoverable in VS Code without breaking the other consumers (agent names come from frontmatter name:, not the filename, in Claude Code — verified against its sub-agents docs; Copilot CLI needs the same check).

Success signal: an install test in real VS Code shows the bundled agent appearing in the agent picker, and Claude Code + Copilot CLI still list the agent under its unchanged name.

Smallest useful change: rename the four bundled agent files to *.agent.md, verify all three consumers, update README/ADR 0001 accordingly.

Acceptance criteria:

• VS Code discovery of a bundled plugin agent verified hands-on (agent-picker evidence).
• Claude Code loads the renamed files with unchanged agent names (verified, not assumed).
• Copilot CLI ditto.
• README + ADR 0001 updated to state the verified behaviour.

Size: S (rename + three-consumer verification + docs).

Part of #38.

[devantler]

🤖 Generated by the Daily AI Engineer

Scope update: the rename itself landed on PR #72 (21e63f0) while this issue was being filed — this issue now tracks the verification half only: hands-on discovery checks in VS Code, Claude Code, and Copilot CLI for the renamed agents/*.agent.md files (the first two ACs and the Copilot one). The docs AC is satisfied by #72 itself.

[devantler]

🤖 Generated by the Daily AI Engineer

Scope addition from #72's round-3 review: the hands-on 3-consumer verification should ALSO confirm the built-in tool identifiers per surface. flux-troubleshooter now lists read, search alongside Read, Grep, Glob (both-spellings pattern), but portfolio-surveyor still carries only the Claude Code spellings (Bash, Read, Grep, Glob) — on VS Code / Copilot CLI it would lack its shell and read tools, and the correct lower-case identifier for the shell tool needs verifying hands-on rather than guessing (a wrong allowlist name fails silently).

[devantler]

🤖 Generated by the Daily AI Engineer

Upstream doc research — the two lanes are documented asymmetrically

This issue has been parked as "needs an interactive probe". Part of it is answerable from upstream documentation, so recording that here to narrow what actually still needs a probe.

Workspace lane — bare .md IS discovered, explicitly. VS Code's custom-agents doc states it "detects any .md files in the .github/agents folder of your workspace as custom agents", with .claude/agents also a default location.

Plugin lane — undocumented, and only .agent.md is ever shown. The agent-plugins doc gives the bundle layout as agents/test-reviewer.agent.md, and plugin.json's agents field is "Path(s) to agent directories. Defaults to agents/." Nowhere does it state whether a bare .md in a plugin's agents/ folder is discovered. Every example uses .agent.md.

So the issue's premise holds: the no-copy claim for the VS Code plugin lane is genuinely unverified, and .agent.md is the only form upstream ever demonstrates for plugins.

What this does NOT settle

The hypothesis is that renaming to <name>.agent.md fixes VS Code "without breaking the other lane" — and that second half is still unverified. Claude Code discovers .claude/agents/*.md; a file named foo.agent.md still matches *.md, but whether the agent is then addressed as foo or foo.agent is exactly the kind of thing that needs to be observed rather than reasoned about. I am not going to assert it from the docs.

Suggested narrowing

The remaining probe is one question, not two: does Claude Code still resolve a bundled agent by its intended name after the .agent.md rename? If yes, the rename is strictly safe and can proceed on documentation alone, since the VS Code plugin lane has no documented bare-.md support to lose.

Sources: custom agents, agent plugins

[devantler]

🤖 Generated by the Agentic Engineer

Rechecked the remaining verification scope on 2026-09-06. The agent files already use .agent.md; this is still a hands-on discovery and tool-identifier check, not a pending rename. This environment exposes VS Code Insiders, but neither Claude Code nor Copilot CLI is available on PATH or the checked common executable locations. Claude Desktop is present and does not establish Claude Code behavior. The VS Code inspection produced no agent-picker evidence.

The three-consumer acceptance criteria therefore remain unverified. Completing them requires observable installed-agent discovery and a read/shell tool probe in each supported consumer; static filename checks do not discharge those criteria. No installed plugin caches or application configuration were changed during this assessment. Related README onboarding work is independently addressed by #203.