holocron/docs/adr/0010-agent-sources-relocated-outside-agents-dir.md

Plugin-scope agent provenance file moves to <plugin-root>/sources.md

Partially supersedes: ADR-0005 (agent-author dual-provider scaffold) — specifically the claim that "both files share a single agents/sources.md for provenance." The rest of ADR-0005 (dual-provider generation, scope detection, single-root script interface) is unaffected and remains in force.

claude plugin validate --strict auto-discovers every .md file directly under a plugin's agents/ directory and treats it as an agent definition requiring YAML frontmatter (name, description, etc.). A flat provenance file at agents/sources.md — no frontmatter, by design, since it is not an agent — fails validation with a missing-frontmatter warning that --strict promotes to an error.

This was first hit in plugins/git/agents/sources.md (added by the git-plugin skill suite). It failed the validate-plugins pre-push hook. The stopgap in commit 0239b00 added throwaway agent frontmatter to unblock the push:

---
name: git-agents-sources
description: Provenance record for the git plugin's agents, not an invokable agent. Do not invoke.
tools: none
---

That workaround is now reverted — the file no longer lives where it needs to impersonate an agent to pass validation.

Considered options

Exclude via an explicit agents manifest array (rejected) — plugin.json supports "agents": ["./agents/reviewer.md"] as an alternative to "agents": "agents/". The hypothesis was that listing only real agent files would stop the validator from also discovering sources.md in the same directory. Tested empirically on a scratch copy of the git plugin: claude plugin validate --strict still auto-discovered and failed on the unlisted sources.md, regardless of the explicit array. The manifest field controls what Claude Code loads as agents at runtime; it does not control what the validator scans on disk. There is no manifest-level or CLI-flag mechanism to exclude a file from agents/ auto-discovery.

Keep the frontmatter workaround permanently (rejected) — cheapest fix, already applied, but semantically wrong: it makes a plain provenance record indistinguishable from a real invokable agent to any tooling or UI that lists available agents (e.g. it could appear as a callable agent in the /agents picker), which is confusing and incorrect.

Consequences

• The provenance file moves to <plugin-root>/sources.md — a flat file, plugin-root relative, sitting outside any directory that Claude Code or its validator auto-scans. No frontmatter is needed or added.
• agent-author's new-agent.sh now writes <root>/sources.md instead of <root>/agents/sources.md at plugin scope.
• agent-audit's validate-provenance.sh now looks for <plugin-root>/sources.md when checking source_keys provenance chains.
• All doc and template references to agents/sources.md (agent-author SKILL.md, agent-audit SKILL.md/README.md, both provider templates) are updated to sources.md.
• plugins/git/agents/sources.md is relocated to plugins/git/sources.md and the 0239b00 frontmatter workaround is removed.