Defame1297
996d9be428
`claude plugin validate --strict` auto-discovers every .md under a plugin's agents/ directory as an agent requiring frontmatter, so the provenance file there always needs fake agent frontmatter to pass validation. Confirmed empirically that an explicit `agents` manifest array can't suppress this discovery. Move the file to <plugin-root>/ sources.md instead, and update agent-author/agent-audit accordingly. Adds ADR-0010, partially superseding ADR-0005's `agents/sources.md` convention. Fixes #63. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
---
|
|
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.
|