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
122 lines
6.2 KiB
Markdown
122 lines
6.2 KiB
Markdown
---
|
|
source_keys:
|
|
- context7-websites-code-claude
|
|
- claude-code-plugins-docs
|
|
- claude-code-subagents-docs
|
|
- context7-github-en-copilot
|
|
- github-custom-agents-configuration
|
|
---
|
|
|
|
# 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.bats` pins 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.sh` already 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.
|
|
|
|
## Auditing guidance
|
|
|
|
Flag as FAIL if:
|
|
|
|
- The body restates a procedure owned by a skill the agent can invoke — Fix: invoke `<skill>`
|
|
instead
|
|
- A sentence answers "no" to the core test — it is padding
|
|
- A decision point presents a menu of options with no default
|
|
- An instruction repeats content already in the description
|
|
- Frontmatter comments are template scaffolding rather than instruction, or are HTML comments at
|
|
plugin/APM scope
|
|
- A prescriptive sequence is used where flexibility is fine, or the reverse
|
|
|
|
Flag as SUGGESTION if:
|
|
|
|
- The body does not open with a direct role instruction
|
|
- The body specifies no error handling — nothing tells the agent what to do with malformed,
|
|
missing or contradictory input
|
|
- The job the agent describes is unbounded, or bounded only implicitly
|
|
- A rationale is missing from a rule the agent is expected to enforce — present but unexplained
|
|
- Comments are useful but verbose enough to bury the field they annotate
|