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".