agent-review

name	agent-review
description	Audit of agent files: frontmatter, triggers, voice, length, duplication. TRIGGER when: authoring/reviewing a .claude/agents/*.md or plugins/*/agents/*.md change, or auditing trigger accuracy across the roster. DO NOT TRIGGER when: editing SKILL.md (use skill-review), editing CLAUDE.md/AGENTS.md/memory files (use ai-instruction-and-memory-files), or reviewing non-agent files.
user-invocable	false

Agent Review — Architecture & Checklist

1. What makes an agent load

An agent file is claude/.claude/agents/<name>.md (stowed user-scope) or plugins/<plugin>/agents/<name>.md (plugin-scoped). The harness scans .claude/agents/ and ~/.claude/agents/ recursively, and each plugin's agents/ directory. Identity comes from the name frontmatter field — the filename does not have to match.

Required frontmatter:

• name — lowercase letters and hyphens; unique across the whole tree. Duplicates within one scope: the harness keeps one and discards the other without warning.
• description — what the agent does and when to dispatch it. The dispatcher reads this to decide delegation.

Optional frontmatter:

• tools — comma-separated allowlist (restrictive). When omitted, the agent inherits every tool from the main conversation. Beware confusion with skill allowed-tools: skill allowed-tools is additive; agent tools is restrictive. They have opposite defaults — mixing them silently breaks the cap.
• disallowedTools — comma-separated denylist. Applied before tools when both are present.
• model — sonnet, opus, haiku, a full model ID, or inherit. Defaults to inherit.
• maxTurns — integer cap on agentic turns. Must be a YAML integer (maxTurns: 20), not a string (maxTurns: "20") — strings are silently ignored and the cap does not apply.
• permissionMode — default, acceptEdits, auto, dontAsk, bypassPermissions, or plan. Ignored for plugin subagents.
• mcpServers — list of MCP servers scoped to the agent. Ignored for plugin subagents.
• hooks — frontmatter-scoped lifecycle hooks. Ignored for plugin subagents.
• skills — skills to preload into the agent's context at startup (full body content is injected, not just the description).
• memory — user, project, or local. Enables a persistent memory directory.
• isolation — set to worktree for a temporary git worktree.
• color — one of red, blue, green, yellow, purple, orange, pink, cyan.
• background — true to always run in the background.
• effort — low, medium, high, xhigh, max; available levels depend on the model.
• initialPrompt — auto-submitted as the first user turn when the agent runs as the main session agent.

Description text is always-loaded context budget; agent bodies are lazy — paid only when the harness dispatches the agent. Overspend in the description costs more than overspend in the body.

2. Trigger design

Format the description with two parallel lists:

TRIGGER when: <specific situation>; <another>; <another>.
DO NOT TRIGGER when: <obvious misfire>; <adjacent agent or skill's surface>; <out of scope>.

Specificity sources, in priority order:

1. File globs (.claude/agents/*.md, *.tsx) — most reliable; the harness can match them exactly.
2. Action verbs (editing, auditing, restructuring, reviewing) — second-most reliable; pin the trigger to a what-the-user-is-doing shape.
3. Context cues (deciding which file a rule belongs in, debating length) — weakest; only fire when the verbs aren't enough.

DO NOT TRIGGER carries equal weight. Over-broad triggers dispatch the agent into turns its system prompt can't help with; over-narrow leaves it dormant. Name the adjacent agents and skills whose surfaces overlap.

Executor-style carve-out. Invocation-context agents whose description names a single dispatch shape — e.g., code-writer ("dispatch for delegated code changes") — may use narrower trigger language than routed reviewers. Do not relax trigger discipline for routed reviewer agents (staff-*, ciso-reviewer); their dispatcher matches on description shape and they fire across many surfaces.

3. Voice and structure

• Imperative second person. "Review the change," "Apply the checklist," not "The reviewer reviews the change."
• Declarative numbered items for checklist content.
• Section headers are domain or step labels ("Scope," "Review checklist") — never "Introduction," "Background," "Conclusion."
• Tables for matrices, prose for narratives, bullets for parallel options.

4. Length and the behavior test

Target under 200 lines per file (diminishing returns past 300).

The behavior test. For every line: does removing this line change the agent's behavior on at least one realistic input? If no, cut.

Lines that almost always pass the test:

• Anti-pattern descriptions the agent can pattern-match against a diff.
• Rationale that arms the agent to judge edge cases not enumerated in the rule (the why lets the rule generalize).
• Trade-off framing that resolves an otherwise-ambiguous call.

Lines that almost always fail the test:

• "This agent was created after a production incident where..."
• "This is a contentious choice; reasonable engineers disagree..."
• Narrative case studies that retell a past PR.
• Audience-persuasion language ("It's important to remember that...").

5. Operational vs narrative content

Replace narrative with imperative. Agent bodies are operational instructions to the agent, not design documents.

Tone marker	Operational	Narrative (cut)
Subject	"Check whether..."	"We've found that..."
Tense	imperative present	past, retrospective
Audience	the agent, mid-task	a human reading cold
Specificity	concrete pattern	generalized lesson

6. Cross-references vs duplication

Cross-reference (default) when another skill's or agent's triggers already cover the file path or situation being edited. Example: code-review points at agent-review for .claude/agents/*.md rather than restating this checklist inline.

Duplicate (defense-in-depth) only when all three hold:

1. The content is critical — getting it wrong has real consequences.
2. The two locations reach the agent through different load paths (e.g. always-loaded CLAUDE.md vs on-demand agent body).
3. One path could silently fail (agent not dispatched, file not loaded for a particular file type, etc.).

If not all three hold, point at the canonical source.

7. Review checklist

1. Frontmatter contract — name matches the agent's identity slug; description present and contains both TRIGGER when: and DO NOT TRIGGER when: blocks. tools vs allowed-tools: agent files use tools (restrictive allowlist); skill files use allowed-tools (additive). Mixing them silently breaks the cap. Verify the field name matches the file type.

2. Description scope — the description's TRIGGER list matches what the system prompt actually covers. An overpromising description dispatches the agent into work it can't do.

3. Trigger specificity — TRIGGER conditions use file globs or action verbs, not vague context cues alone. Executor-style exemption: invocation-context agents (code-writer) may use narrower trigger language; do not relax for routed reviewer agents (staff-*, ciso-reviewer).

4. DO NOT TRIGGER coverage — adjacent-agent and adjacent-skill surfaces are named explicitly; verify every domain-adjacent agent and skill appears.

5. disallowedTools recognition — any disallowedTools entry is a recognized field name (not a misspelling of tools), and its value lists actual tool names.

6. maxTurns integer validation — maxTurns: 20, not maxTurns: "20". Strings are silently ignored; the cap will not apply.

7. model field discipline — check against ~/.claude/CLAUDE.md "Model Routing". Reviewer, code-writing, and specialist agents pin model: sonnet; routinely-dispatched subagents do not pin opus.

8. Length — under the 200-line target. Flag anything that drifts past 200 (and especially past 300) without a load-bearing reason.

9. Behavior test per line — every line should change the agent's behavior on at least one realistic input. Cut narrative, editorial meta-commentary, and incident retellings.

10. Voice — imperative second person; numbered items for checklists; section headers that label domains or steps.

11. Cross-reference correctness — referenced agent and skill names exist; referenced section anchors (§2, §3) match the target file's structure. Renames in the target break these silently.

12. Duplication justification — content duplicated across agents passes the three-condition test in §6. Otherwise, replace the duplicate with a pointer.

13. Redaction — no real project, organization, codename, or private-tracker-ID references in examples or rationale. Use PROJ-<digits> or TICKET-<digits> for tracker-shaped placeholders. (Repo-specific; see repo-root CLAUDE.md.)

14. Behavioral-equivalence audit (compression diffs) — for any diff that removes or shortens lines, before declaring the review complete:

    Removed/shortened text	Surviving line	Behavior-preserving?
    (quote)	(cite)	Y — (quote surviving line) / N — (what is lost)

    Y requires citing the specific surviving line that carries the same instruction. "The meaning is the same" is not sufficient. Any N is a finding; restore the instruction.

    Compression that drops a forbidden-action callout ("do not X"), an imperative directive, an escape-hatch exception, or a verification command fails this audit even when the summary reads as equivalent.

15. Reviewer-agent output contract (staff-* and ciso-reviewer only) — verify the agent carries Write in its frontmatter tools list, and has a ### File-based output section in its ## Output format body. Both are required for findings_path dispatch from the code-review dispatcher. An agent missing either falls back to full inline output and can trigger the heredoc-abort-on-large-findings failure the canary guards against.

16. Platform-genericness — the reviewed agent's own body prescribes no tool-invocation verb as a mandatory instruction step, and cites no source-material bias anchor (a named team's or org's practice given as the reason a rule holds, instead of the rule's own rationale); extract every hit mechanically — do not rely on noticing during read-through. Vendor or product names naming a staff-* persona's recognized domain landscape (Terraform, Snowflake, Fivetran, Sentry, and similar) are not violations: staff-* bodies are domain-expert review personas whose job is enumerating that landscape, so it is load-bearing domain knowledge in the reviewed agent's own body, not platform lock-in. Flag any hit not justified as deliberate or illustrative; agent bodies have no <skill>-<project> layer to relocate content to, so an unjustified hit is generalized or removed from the reviewed agent's body directly. (Repo-specific; the tool-verb and bias-anchor rationale applies to agent bodies for the same reason it applies to skill bodies — see repo-root CLAUDE.md "Global skill bodies stay platform-agnostic.")