Defame1297
ede3f06689
Diffing each retrofitted SKILL.md against its replacement references/ files found rules that existed on main and now existed nowhere — relocated in intent, deleted in fact. A trim that loses a rule is not progressive disclosure, it is data loss with a smaller word count. Three had no survivor. The least-privilege guidance for `tools` kept its mechanics and lost the "restrict to what the agent needs" half, so the remaining text read as encouragement to omit the field. The improve flow lost its regression check, so nothing compared the closing audit against the pre-edit state and a PASS quietly becoming a SUGGESTION went unnoticed — restored on both halves of the author pair, since agent-author had dropped its equivalent too. And agent bodies lost "would the agent get this wrong without it?", which mattered more than it looks: ADR-0020 deliberately sets no body word gate for agents, three of the four already sit between 933 and 1,199 words, and the delegation check only fires on procedure a skill already owns. That heuristic was the only brake left. Two more were reachable only from the wrong scope. agent-author tells the reader to load only the file for the resolved scope, but the mcp__ glob syntax for disallowedTools and the five tools no subagent ever receives had both landed in project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM scope, so the scope that needs the syntax most could not reach it, and a plugin-scope run could write a body telling the agent to ask the user a question. Two documents were actively wrong rather than merely thin. agent-audit told auditors that validate.sh resolves boundary targets for skills only; it runs at both scopes, so the auditor was hand-resolving what the script had already decided and could contradict it. And skill-audit routed to its script-troubleshooting reference whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal outcome for the whole #99 population, so 1,302 words loaded on nearly every audit. A context-budget regression inside the skill that enforces the context budget. Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an adjacent rubric called it a hard ERROR. LESSONS.md records the reference-chain depth rule flipping from "one level deep" to "two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on the diff; the looser rule is what mandatory dispatch requires. Refs: #99 ADR: 0020 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
4.1 KiB
source_keys
| source_keys | ||
|---|---|---|
|
Plugin/APM scope — the single vendor-neutral file
One file, no counterpart: <package-root>/.apm/agents/<name>.agent.md. apm compile emits it to
both the Claude Code and the Copilot CLI target. The .agent.md extension here is convention, not
a Copilot marker — the file is vendor-neutral.
Frontmatter
The permitted keys are the apm-agent-allowlist section of agent-audit's
references/field-inventory.md. Read them from there as data — that section is the single source
of truth, agent-audit's validate.sh parses it at load time, and it changes. Any restatement of
the roster, here or in a template or in script output, goes stale one step further out than the
list itself.
name— kebab-case, must equal the filename stem, unique within the scope.description— write it againstreferences/contract.md.- Everything else — check the allowlist section before adding a key. A key outside it fails the audit.
Why the list is narrow. apm compile copies frontmatter verbatim to every target with no
per-target integrator, so a harness-specific value is wrong on at least one of them (ADR-0016).
The rule is about a field's shape, not a fixed roster:
-
toolsis an allowlist whose vocabulary differs per harness — Claude Code names its own tools, Copilot CLI uses aliases (execute/read/edit/search/agent/web) — so one value is wrong on one target. It stays out. Omitting it means inherit-all-tools on both, which is never wrong. -
disallowedToolsis a denylist, and denying by name cannot fail that way: a name the other harness does not recognise denies nothing, so the worst case is a missing fence, never a wrongly granted capability. That asymmetry is the whole exception (ADR-0016's 2026-08-14 amendment). Claude Code honours it for plugin subagents; the three fields plugin agents do silently ignore arehooks,mcpServersandpermissionMode, and this is not one of them. Copilot's handling of the key is unconfirmed, which ADR-0016 accepts as a stated risk.Its syntax is the same at every scope, and this is the one scope that cannot reach it anywhere else: MCP tools are denied as
mcp__<server>,mcp__<server>__*ormcp__*; both a YAML list and a delimited string are accepted, and this repo writes the comma-separated string form (disallowedTools: Edit, Write, NotebookEdit) — match it. -
The Claude-only knobs (
isolation,maxTurns,effort,memory,permissionMode,skills,color,initialPrompt,background,hooks,mcpServers) have no Copilot equivalent and are never written to this file at all. "Silently ignored at plugin scope" is the wrong framing: they are absent, not tolerated. To use any of them, copy the agent to.claude/agents/(project scope) or~/.claude/agents/(user scope).
Write disallowedTools on every read-only plugin-scope agent — and say the agent is read-only in
the body as well, because the fence does not cover the inherited Bash tool.
source_keys is provenance metadata, not a runtime field: both harnesses ignore it. Add it only
when research sources informed the agent, with slugs matching H2 headings in the package root's
sources.md.
Body
Follow the Body section of references/contract.md: role instruction, one job, and delegation
to installed skills instead of transcribed procedure.
Before invoking agent-audit
namekebab-case, matching the filename stem, unique in scopedescriptionwritten toreferences/contract.md- Every frontmatter key present in the
apm-agent-allowlistsection — in particular notools - No
FILL IN:placeholder and no<!-- ... -->template comment anywhere in the file - System prompt body non-empty, and a read-only agent says so in prose as well as in
disallowedTools - Body covers all four required elements: inputs expected, process steps, output format, error handling — what the agent does on malformed, missing or contradictory input
Then return to the flow reference you came from.