Skills/docs/agent-template.md

# Agent template

Every agent file follows the same structure. Deviations need a
named reason in the agent's own body. The template was distilled
from the AILang in-tree agents and refined to remove project-
specific identifiers.

## File layout

```
---
name: <agent-slug>
description: <third-person, "Use when…" or role description>
tools: <comma-separated tool list>
---

> Violating the letter of these rules is violating the spirit.

## What this role is for

<one short paragraph naming the failure mode the agent exists
to prevent>

## Standing reading list

<list of always-binding documents — derived from the project
profile's `standing_reading.always` plus `standing_reading.by_role.<this-role>`>

## Carrier contract

<what the dispatching skill hands the agent: task_text, diff,
hypothesis, etc. Agents do NOT open the project's plan or spec
directories directly — context curation lives at the skill level>

## Iron Law

<the non-negotiable rules of this role, as a code-fenced block of
short imperative lines>

## The Process

<numbered steps>

## Status protocol

<which terminal states this agent uses, and what evidence each
state requires>

## Output format

<word-budgeted, structured>

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| … | … |

(Calibrated to the past failure modes of this role.)

## Red Flags — STOP

- If you're about to do <X>, stop.
- …
```

## Frontmatter conventions

### `name`

The agent slug, lowercase kebab-case. No project prefix (the
old `ailang-*` prefix was an AILang-only convention; the
plugin's agent path is enough disambiguator).

Examples: `architect`, `bencher`, `debugger`, `implementer`,
`tester`, `fieldtester`, `docwriter`, `grounding-check`,
`plan-recon`, `spec-reviewer`, `quality-reviewer`,
`implement-orchestrator`.

### `description`

One sentence. Third-person. Either "Use when…" or a role
description. This is what the orchestrator (or a skill) reads
to decide whether to dispatch the agent — keep it sharp.

### `tools`

Comma-separated list of Claude Code tool names. No agent
receives `Agent` in its tools (no nested subagent dispatch).
The dispatching skill composes; agents do not call other
agents.

Common tool sets:

- Read-only review (architect, spec-reviewer, quality-reviewer,
  grounding-check, plan-recon): `Read, Glob, Grep, Bash`
- Implementation (implementer, tester, debugger, docwriter,
  fieldtester, bencher): `Read, Edit, Write, Bash, Glob, Grep`
- Orchestrator (implement-orchestrator): `Read, Edit, Write,
  Bash, Glob, Grep` — same as implementer; the orchestration
  happens via sequential role-switches within its own context

## Sections in detail

### Spirit-letter lead-in

The single line `> Violating the letter of these rules is
violating the spirit.` is mandatory at the top. It exists to
forestall the "well, technically I didn't break the rule" class
of rationalisation.

### What this role is for

One short paragraph. Names the failure mode the agent exists to
prevent — not the success mode it enables. Failure-mode framing
is sharper for the model: "this role exists because past attempts
to do X without a dedicated reviewer led to Y" reads more
forcefully than "this role helps with X".

### Standing reading list

The plugin's skill body computes this from the project profile
(`standing_reading.always` + `standing_reading.by_role.<role>`)
and passes the resolved list to the agent via the carrier. The
agent's body says, prosaically: "Read everything in the standing
reading list before doing anything else."

A set `paths.glossary` is implicitly part of `always`, so every role
reads the project glossary without a per-role entry (see
`profile-schema.md` § `paths`).

The agent file itself does not hardcode file paths.

### Carrier contract

The carrier is the small payload the skill hands the agent. It
typically includes:

- `task_text` — the spec excerpt or plan task verbatim
- `diff` — for reviewers, the diff to review
- `hypothesis` — for the bencher, what it should test
- `bug_symptom` — for the debugger, the observable misbehaviour
- `drift_focus` — for the architect, what part of the ledger to
  check

Agents do **not** open the project's plan or spec directories
directly to fish for context. Context curation lives at the
skill level so the orchestrator can see exactly what each agent
was told.

### Iron Law

A code-fenced block of short, imperative rules. These are the
rules the agent will violate if it rationalises. Calibrate to past
failure modes — abstract rules don't land; rules anchored to a
named past mistake do.

### The Process

Numbered steps. Each step is concrete — "Read X", "Run Y",
"Write to Z" — not abstract phases like "explore" or "synthesise".

### Status protocol

Specifies which terminal states the agent uses (see
`pipeline.md`) and what evidence each state requires. For
example: `DONE` requires "build green AND tests green AND no
new warnings".

### Output format

Word-budgeted. Structured — usually a small set of named
sections the orchestrator can quote in its commit body. The
budget prevents agent reports from drowning the orchestrator's
context.

### Common Rationalisations

A table of excuse → reality. Calibrated to the past failure modes
of this role. The point is to short-circuit the rationalisation
before it derails the agent's process.

### Red Flags — STOP

Bullet list of "if you're about to do this, stop" signals.
Concrete, not abstract. "If you're about to write a fix without
a failing test, stop" beats "be disciplined".