Defame1297
fc305ba7d9
Five documents told authors that a prose-form dangling routing target blocks. The
gate reports it as a SUGGESTION and exits 0. Verified on fixtures: `-> name` and
`/name` are blocking ERRORs, the prose form is SUGGESTION-tier unless a second
resolving target in the same sentence corroborates it. ADR-0020 and gates.md were
right; contract.md, retrofit.md, description-quality.md, finding-criteria.md and
agent-author's contract.md were wrong — and they are what an author and an auditor
actually read. The whole 39-skill corpus was retrofitted against them.
skill-audit was also self-contradictory: it imports validate.sh's SUGGESTIONs into
the Structure dimension verbatim while its own rubric grades the same target a FAIL,
so one target got reported twice at two tiers. The script owns the grade; the rubric
now says so.
The YAML-fold trap that broke gitea-labels-milestones (#100) was warned about only
in retrofit.md, reachable only from the improve flow when a budget is exceeded. It
is now in both contract.md files, which SKILL.md mandates on the create flow too.
agent-audit loaded both rubrics unconditionally on every run — 3,323 words for a
clean audit against skill-audit's 1,636. dac9cad fixed exactly this in skill-audit
and edited agent-audit in the same commit without applying it. Same treatment: the
criteria move to a new finding-criteria.md and load per dimension. Clean run now
2,083 words, a 37% cut.
Routing: apm-workflow's description shed dependency installation while still owning
the flow, and apm-install's boundary did not exclude it, so "install my apm
dependencies" matched the CLI-binary skill with no route back. Fixed on both sides.
forge regains two of the three phrasings the retrofit deleted.
forge Step 1 called grill-with-docs unconditionally — a skill in plugins/bin, which
kyberforge does not declare as a dependency. It resolves here only because the
walk-up sweeps sibling plugins; a standalone install dead-ends. Step 1 now names
the cross-plugin dependency and gives an inline fallback. Declaring it properly in
apm.yml remains the better fix.
Also: both audit SKILL.md files now grade exit 2 as "did not run, dimension
unverified" rather than as findings; skill-audit's README row described content that
moved, which its own finding-criteria.md grades a FAIL; and body-discipline.md's
`git show <sha>:plugins/...` command is fenced, since an installed plugin cache has
no repo and file-structure.md makes a bare repo path a FAIL.
Refs: #100, #101, #125
ADR: 0020
5.5 KiB
source_keys
| source_keys | |||||
|---|---|---|---|---|---|
|
Body, Delegation and Comment Discipline Reference
Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents configuration. House contract: ADR-0020, the context budget.
Read this when judging the body, delegation and comment-discipline dimensions.
The core test
For every sentence in the body, ask: "Would the agent get this wrong without this instruction?"
If no — cut it. The agent already knows it from general training. Adding it wastes tokens and dilutes the signal of what matters.
Agents take no body word gate
ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body at nothing. The two are not the same construct: a skill body is loaded into the caller's live context and competes with the conversation already there, while an agent body becomes the system prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does not transfer, so:
- Never report an agent body as too long on a word count. There is no number to cite.
- Never add such a gate to
scripts/validate.sh.tests/validate.batspins its absence with a body far past 900 words that must still pass, and adding one would contradict the ADR. - The one length signal that does apply is the Copilot runtime's 30,000-character body limit, which
validate.shalready reports as a SUGGESTION because content past it is silently truncated.
Length is judged through the delegation check below instead, which is the defect a word count was standing in for anyway.
The delegation check
A plugin-scope agent is a single .apm/agents/<name>.agent.md file with no sibling references/
directory. It cannot progressively disclose to itself — it can only delegate to skills. So a
procedure spelled out in an agent body that a skill the agent invokes already owns is not a
shortcut: it is a second copy of that procedure, and the second copy drifts. This is the
characteristic agent defect, the way a stale README row is the characteristic skill defect.
An agent body that restates a procedure owned by a skill it can invoke is a FAIL. The Fix is
always the same shape: invoke <skill> instead.
How to apply it: for each procedural block in the body — a rule list, a numbered sequence, a constraint table — ask which skill owns that procedure. If the agent names that skill anywhere (its dispatch table, its routing prose, its frontmatter), the block is a restatement and the skill is already there to be invoked.
Worked example. The three *-orchestrate agents exist to compose domain skills — git-orchestrate
(933 body words), gitea-orchestrate (1,199) and apm-orchestrate (1,080) — so any step they
spell out that the composed skill already owns is the defect. git-orchestrate:24-31 carries a
"Hard rules" list (Conventional Commits types, atomic commits, never commit secrets, git trailers)
that git-commits owns and that git-orchestrate:44 routes to by name; :39 concedes the point
outright, noting the sub-skills "carry their own local copies of these rules". Two copies, one
authority, and nothing keeping them in step.
What is not a finding under this rule, because no skill owns it:
- The dispatch table itself — which operation routes to which skill.
- Safety gates the agent enforces before dispatching, and refusals it makes on its own authority.
- The input contract and the structured output the agent's caller consumes.
- Session state the agent carries across skill invocations.
What the body is for
Include what the fresh context lacks:
- A direct role instruction opening the prompt:
You are a [role]. When invoked, [action]. - One bounded job, stated so the agent knows what it must refuse.
- The dispatch, gates, inputs and outputs listed above.
- Error handling — what the agent does on malformed, missing or contradictory input: stop and report, or degrade to a named fallback. Absent it, the agent invents a recovery, and a subagent's invented recovery is invisible to its caller until the output is wrong.
- Non-obvious environment facts and project-specific conventions it cannot infer.
- One default per decision point with one escape hatch.
Do not include at all:
- Concepts the agent already knows (what JSON is, how HTTP works, what a CSV is)
- Exhaustive option lists — pick a default; the agent does not benefit from choosing
- Steps the agent handles independently — over-specifying leads to unproductive paths
- Restatements of the description, which is already in context
Comment discipline
Inspect every comment block in the YAML frontmatter and apply the core test to each: would the
agent get this wrong without this comment? Template scaffolding — # Optional. <long explanation>, more than a line or two of inline guidance per field — belongs to development, not
to a shipped file. At plugin/APM scope the stakes are higher than tidiness: apm compile copies
frontmatter verbatim to every target, <!-- ... --> is not valid YAML, and validate.sh FAILs a
frontmatter block that still contains one.
Where the criteria live
Every FAIL and SUGGESTION criterion for these dimensions is in references/finding-criteria.md,
which Step 3 reads on every run. This file is the reasoning behind them, loaded only when that file
puts the body, delegation or comment-discipline dimension in play.