feat: bundle the first custom agent (agents/) into a plugin — Theme 1

[devantler]

🤖 Generated by the Daily AI Assistant

Part of #38 (Theme 1 — realize "not skills-only"). Follows the MCP prove-out
(#42 → #44, flux-operator-mcp bundled into gitops-kubernetes) and the
design decision in ADR 0001 (#43). This is the custom-agent (agents/)
bundling child the ADR explicitly deferred.

Problem

The marketplace is designed to bundle three resource kinds — skills, MCP servers,
and custom agents — and the tooling is already in place: validate-manifests.sh
enumerates and validates an agents/ directory (a plugin declares ≥1 resource;
agent names must appear in the README Resources column), with self-tests
covering the agent path (35/35 on main). But no plugin bundles a custom agent
yet, so the "not skills-only" capability is proven for MCP only, not for agents.
Theme 1 is not complete until a real, useful custom agent ships in a plugin.

Proposed direction

Bundle one genuinely useful, tool-neutral custom agent into an existing plugin
— not a placeholder — so the agent bundling path is proven end-to-end the way #44
proved MCP.

Recommended first agent: a flux-troubleshooter read-only diagnostic agent in
the gitops-kubernetes plugin. It is the natural pairing: that plugin already
bundles the flux-operator-mcp server (#44) and the gitops-cluster-debug /
gitops-repo-audit / gitops-knowledge skills, so a delegatable sub-agent whose
system prompt specializes it in diagnosing a live Flux/GitOps cluster (inspect
Flux resource status, trace dependency chains, read controller logs via the MCP,
apply the skills' procedures) is high-value and generic to any Flux user. It is
distinct from the skills (procedural knowledge) — it is a delegatable persona that
uses them — so it is not a duplicate.

• On-disk: plugins/gitops-kubernetes/agents/flux-troubleshooter.md — YAML
  frontmatter (name, description, and a read-only tools allow-list) +
  a focused system prompt.
• Manifests: keep .claude-plugin/marketplace.json and .github/plugin/marketplace.json
  in byte-for-byte parity; add the optional "agents": "agents/" to the plugin's
  plugin.json (or rely on the default per ADR §D1).
• README Resources column updated to list the agent (validator enforces parity).

Alternatives / open sub-decision (make the call in the PR, don't block on it):
if a gitops-kubernetes agent feels premature, an equally valid first bundle is a
generic read-only reviewer/explorer agent in another skills plugin — but the
flux-troubleshooter is the strongest concrete fit and is recommended.

Acceptance criteria

• One real, generic, tool-neutral custom agent bundled in an existing plugin
  (recommended: flux-troubleshooter in gitops-kubernetes).
• agents/<name>.md carries valid frontmatter (name, description, and a
  read-only tools allow-list) and a substantive system prompt (not a stub).
• Both marketplace manifests updated in parity; plugin.json resource
  declaration correct; README Resources column lists the agent.
• ./scripts/validate-manifests.sh ✓ and ./scripts/validate-manifests.test.sh
  (≥35) ✓ and shellcheck clean; CI green.

Rough size

Small–Medium. No new script capability needed (agent validation already shipped in
#44); the work is authoring one good agent + the manifest/README/plugin.json wiring.