Defame1297
311e7cd22c
Six defects, each one a place where two files that an author reads in the same sitting told them different things — or where the trim dropped a rule and nothing noticed because no gate covers prose. **"Use proactively" contradicted itself across the pair.** All three agent templates said to add it where the runtime should delegate unprompted, while `agent-audit`'s `KyberforgeCopilot.ProactivePhrase` rule grades it a hard FAIL in any `*.agent.md` — which is the Copilot half of every project/user pair *and* the vendor-neutral plugin-scope file, since that compiles to a real Copilot agent downstream. Following the template produced a file the repo's own gate rejects. The phrase is now permitted in exactly one place, the Claude Code `.md`, and `references/contract.md` carries the per-file table plus the consequence authors ask about next: a pair whose CC half has it and whose Copilot half does not is correct, because `agent-audit` checks that both halves describe the same job, not that they match word for word. **The output-schema rule contradicted itself inside one file.** `contract.md` said any content only one branch reaches moves to `references/`, and then offered an "Output format template" body pattern with no qualification. Stated once now, so it is not re-litigated: an output schema stays in the body only when every flow produces it and it is roughly 50 words or less. No third option. **Gotchas tiers disagreed with the script.** `validate.sh` emits the entry count through `suggest()` and exits 0, while `skill-author` and `skill-audit` both called more than five entries a FAIL. Whether a given gotcha earns its place is judgment, so the prose moves to the script's tier rather than the reverse. The paraphrase rule stays a FAIL and is explicitly marked as the auditor's call — no script detects it. **The dispatch exemplar was cited at the wrong number.** `apm-workflow`'s body is 421 words; 554 is its whole-file count. Both `contract.md` and `body-discipline.md` cited 554 while describing a body budget, so an author calibrating against the exemplar overshot by ~30% — the exact whole-file/body-only conflation those two sections exist to warn against, reproduced inside the warning. **"Error handling" came back as a required body element.** It was one of four and is the one that gets dropped, and dropping it is not neutral: an agent handed malformed input with no instruction invents a recovery, and a subagent's invented recovery is invisible to its caller until the output is wrong. Restored in `agent-audit`'s rubric as a SUGGESTION, in `agent-author`'s contract and both scope checklists as a required element, and as an `## Errors` section in all three templates. **`skill-author` Step 4 gains the one check the audit misses.** An empty body reports `PASS SKILL.md body word count 0` — a word gate cannot tell "concise" from "absent". Step 4 now hand-checks for a non-empty section, and its commit verification is conditioned on actually being inside a git worktree, which a skill under `~/.claude/skills/` is not. Also here: absolute repo paths removed from `skill-author`'s SKILL.md and contract.md in favour of naming the skill (`zoom-out`'s description is quoted inline instead of pointed at), the boundary-target universe documented to match the resolver, a two-hops-from-SKILL.md limit on reference chains, and `new-agent.sh`'s next-steps output naming the description budget and the deliberate absence of an agent body gate. Refs: ADR-0020
3.7 KiB
3.7 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.- 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.