Defame1297
0dd044a782
#89's grilling session surfaced a real upstream gap: APM's agent primitive has no per-target compile integrator, so tools: and every Claude-only field (isolation, maxTurns, effort, memory, permissionMode) would verbatim-copy into Copilot's file with an incompatible or unrecognized shape. Omitting them entirely is the only option that never ships a wrong value to a real harness. Scoped to plugin-scope agent-author only — project/user scope keep today's Claude+Copilot pair model unchanged. Partially supersedes ADR-0005 and ADR-0008's plugin-scope clauses (addenda appended to both); ADR-0009's field-inventory.md mechanism is unaffected, only its plugin-scope content shape changes. Refs: #89
23 lines
2.2 KiB
Markdown
23 lines
2.2 KiB
Markdown
# agent-audit takes a single file path and derives the counterpart by scope detection
|
|
|
|
`agent-audit` validates agent definition file pairs (Claude Code `.md` + Copilot `.agent.md`). The skill accepts a path to either file and derives the counterpart using scope detection rather than requiring the caller to name both files or supply a root directory.
|
|
|
|
## Considered options
|
|
|
|
**Directory input (rejected)** — analogous to `skill-audit <skill-dir>`. Rejected because agents have no per-agent directory. At plugin scope both files are flat in `agents/`; at project scope they are in completely different directories (`.claude/agents/` and `.github/agents/`). No single directory contains both files across all scopes.
|
|
|
|
**`<name> <root>` signature (rejected)** — mirrors `new-agent.sh <name> <root>`. Rejected because it requires the caller to supply two pieces of information when one (the file path) is sufficient. The file path already implies the agent name (filename stem) and the root (found by walking up). Forcing the caller to re-supply what the script can infer is the kind of convention knowledge the script exists to encapsulate.
|
|
|
|
## Consequences
|
|
|
|
- The unit of validation is the pair. A missing counterpart is always a FAIL — an orphan file is incomplete by definition.
|
|
- Scope detection walks up from the input file: first directory containing `plugin.json` → plugin scope; first directory containing `.git` without `plugin.json` → project scope; path under `~` with neither → user scope.
|
|
- At user scope the derivation crosses filesystem locations (`~/.claude/agents/` ↔ `~/.copilot/agents/`); the script must handle the home directory case explicitly.
|
|
- The invocation signature is the public contract. Changing it is a breaking change to any caller — treat it as such.
|
|
|
|
**Update (ADR-0016):** the plugin-scope clause above is superseded. Plugin scope is no longer
|
|
detected via `plugin.json`, and there is no counterpart to derive — a directory containing
|
|
`apm.yml` produces a single `.apm/agents/<name>.agent.md` file, and `agent-audit` validates it
|
|
directly with no pair-consistency check. Project scope and user scope keep the pair-derivation
|
|
mechanism described above unchanged. See ADR-0016.
|