STYLE

Agent Style Guide

> How to write an agent body that is useful, compact, and consistent with > the rest of the pack. Follow this when adding a new agent or materially > rewriting an existing one. > > This is a *companion* to `SCHEMA.md`. SCHEMA defines the **shape** every > file must conform to (frontmatter, category, tags, slug). STYLE defines > what the **body** should read like.

---

1. The two canonical shapes

There are exactly two shapes in this pack. Pick one and stay in it.

A. Strict shape (reviewers, scouts, orchestrators)

Short, reference-style, deterministic. Target: 40–80 non-blank body lines.

You are <role>. <One-sentence identity — what perspective you argue from>.

Your task:
1. <concrete, observable step>
2. <concrete, observable step>
3. ...

## <One or two domain checklists>
For every <input unit>, verify:
- <concrete check>
- <concrete check>

Do not <common anti-pattern>.

Return exactly:
- <field>
- <field>
- <field>

Templates in this family: `agents/review/qa-verifier.md`, `agents/review/security-reviewer.md`, `agents/review/bg-regression-runner.md`, `agents/orchestration/repo-scout.md`.

These agents participate in the orchestration contract and produce **structured output** the parent can parse. No flavour, no memory metaphors, no "I remember…" prose. They are machines.

B. Persona shape (specialists, write agents, coaches)

Longer, opinionated, domain-dense. Target: 80 non-blank lines of essentials plus any amount of deep-reference material cut off by `## Deep Reference`.

# <Display Name>

<!-- precedence: project-agents-md -->
> Project `AGENTS.md` (Invariants / Platform Stack / Modules) overrides
> any advice in this persona. When they conflict, follow the project
> rules and surface the conflict explicitly in your response.

You are **<Display Name>**, <one-sentence identity>.

## Core Mission

<2–4 sentences or bullets about what this agent exists to do. Concrete.
No "strategic", "world-class", "best-in-class" adjectives — describe the
deliverable, not the attitude.>

## Critical Rules

1. <Non-negotiable constraint, ideally one the domain frequently violates.>
2. <Rule that would prevent a common failure mode.>
3. <Rule that forces honesty: "if you didn't test X, say so instead of
   asserting it works".>
…

## Output / Deliverables

<What every typical invocation produces. Tables, templates, or a
structured report shape. Short. Concrete fields, not vibes.>

## Deep Reference

<Everything below is reference material: long templates, frameworks,
edge-case playbooks, scenario walkthroughs. The `--thin` converter cuts
here, so anything below this marker is NOT loaded on every invocation.>

## <Framework X>
…

## <Scenario: Y>
…

Use this shape for every persona agent.

---

2. What NOT to write

The audit pass that produced this guide found a recurring set of anti-patterns. Avoid all of them. If you're rewriting an old agent, these are the first things to cut.

2.1 Personality theatre

## 🧠 Your Identity & Memory
- **Personality**: Strategic, security-focused, scalability-minded,
  reliability-obsessed
- **Memory**: You remember successful architecture patterns, performance
  optimizations, and security frameworks
- **Experience**: You've seen systems succeed through proper architecture
  and fail through technical shortcuts

Zero signal. The model does not "remember" anything between invocations — memory lives in `.cursor/memory/`, not in a bulleted vibe block. Drop the whole section. Open with a single identity line: "You are Backend Architect — a senior backend architect focused on scalable systems and data integrity on high-traffic production platforms."

2.2 Adjective soup

"World-class", "senior", "expert-level", "best-in-class", "strategic", "experienced". These are free to type and free to ignore. Replace with a concrete constraint: "designs for ≥10k writes/s", "reviews every diff against OWASP Top 10", "requires evidence from logs / metrics / tests before signing off".

2.3 Emoji-prefixed section headings

`## 🧠 Your Identity & Memory`, `## 🎯 Your Core Mission`, `## 🚨 Critical Rules You Must Follow`. These make the body harder to parse for extractors, trip up `--thin` heuristics, and survive several encoding round-trips as mojibake (`=Ë ` instead of `📋`).

Use plain ASCII headings: `## Core Mission`, `## Critical Rules`, `## Output`, `## Deep Reference`. If you want a visual marker, put it in a prose sentence, not in the heading.

2.4 "Your Success Metrics" / "Advanced Capabilities"

Aspirational sections that describe what "success" would look like if the agent existed as a person. The agent doesn't have a career. The model doesn't optimise against these sentences — they cost tokens and add nothing. Cut them or fold the one useful bullet into Critical Rules.

2.5 Cross-Agent Collaboration lists

- **Evidence Collector**: Provide accessibility-specific test cases …
- **Reality Checker**: Supply accessibility evidence …
- **Frontend Developer**: Review component implementations …

Routing is done by the **orchestrator** via `index.json` / tags — the agent body is not where cross-agent hand-offs are declared. If two agents genuinely chain, that belongs in `distinguishes_from` + `disambiguation` (machine-readable) or in a playbook under `playbooks/runbooks/`, not in persona prose.

2.6 Re-stating the Precedence block

Every persona agent now carries the `<!-- precedence: project-agents-md -->` header. That's enough. Don't re-paraphrase it in Critical Rules, Workflow, or Communication Style.

---

3. What to include

3.1 One identity line

"You are <Role>, <the lens through which you argue>". That's it. The rest of the body is the job, not the personality.

3.2 A Mission that is disprovable

A mission sentence is useful only if you can read a diff and say "this did/did not satisfy it". "Ensure system reliability" fails this test. "Every wri