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>
model: <opus | sonnet>
effort: <xhigh | high>
---

> 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 — the fixed always list (`CLAUDE.md`
plus `git log -10 --format=full`), the per-role standing reading the
project lists in its CLAUDE.md project facts, and the project's glossary
if it has one>

## 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, spec-skeptic, plan-recon, spec-reviewer, quality-reviewer.

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, spec-skeptic, plan-recon): Read, Glob, Grep, Bash
• Implementation (implementer, tester, debugger, docwriter, fieldtester, bencher): Read, Edit, Write, Bash, Glob, Grep

The autonomous execution loops are Workflow scripts, not agents (implement/workflows/): they orchestrate the implementation phase agents from the top level via agent() calls. The agents they dispatch still carry no Agent tool — the no-nested-dispatch rule is unchanged; the workflow simply does the orchestration the retired implement-orchestrator agent used to fake with inline role-switches.

model

Mandatory. Every agent pins an explicit model — fable, opus or sonnet, nothing else. An omitted field means the agent inherits the session model, which routes the dispatch to whatever the user happens to be chatting on — an unintended tier for every role that has not earned its pin. Pinning removes that coupling.

Assignment rule, in priority order:

1. Cycle-reach singleton gates — agents that run at most a couple of times per cycle or bug AND whose miss silently ratifies or poisons an entire cycle run fable (owner-ratified 2026-07-20): architect (the drift verdict steering the next iteration), grounding-check (the autonomous sign-off signature under /boss), tdd-author (the RED executable-spec the GREEN side builds on), debugger (the root-cause a full RED→GREEN cycle rides on). Fable is the scarcest tier and shares its budget with a fable main session, so the set is CLOSED — extending it requires a fresh owner ratification — and a fable agent is never dispatched per-task inside a loop or in a parallel fan-out. Workflow scripts stay fable-free entirely; the implement-loop quality gate caps at opus.
2. Consequence of a miss — the remaining judgment roles — errors still silently poison downstream work, but the role either fans out, runs per-task, or feeds a decider rather than gating a cycle (adversarial lenses, plan recon, field/bench evidence, the in-loop quality review) — run opus. Opus is the documented strength for code review, debugging, and deep reasoning.
3. Mechanical scope — tightly-scoped execution of a pre-made plan, recon, extraction, compliance-diffing run sonnet (near-opus coding quality at lower latency and cost).
4. Volume × wall-clock — agents dispatched per-task inside loops or fanned out in parallel swarms multiply their model's latency; they run sonnet unless rule 2 overrides (currently only quality-reviewer, the loop's last correctness review). That override is itself size-conditioned (issue #30): consequence-of-a-miss scales with diff size, so the implement-loop dispatches the quality phase at sonnet/high when the spec-reviewer independently measured the diff at ≤25 changed lines touching no contract-referenced path, and at opus/xhigh otherwise (including whenever the measurement is missing). The deterministic end-verify/mini-verify suite gate is what makes the lower tier defensible; the agent-file frontmatter keeps the opus default.

Current distribution: fable — architect, debugger, grounding-check, tdd-author. opus — bencher, fieldtester, plan-recon, quality-reviewer, spec-skeptic. sonnet — docwriter, glossary-extractor, implementer, spec-reviewer, synthetic-user, tester.

The same rule binds Workflow scripts: every agent() call passes an explicit model: option, and fable is never a valid value there — rule 1's gates are frontmatter agents, not workflow stages (see the model-policy header comments in implement/workflows/*.js).

effort

Mandatory. Every agent pins an explicit reasoning effort — one of the harness levels low | medium | high | xhigh | max, of which the plugin uses two. An omitted field means the agent inherits the session effort, coupling every dispatch's thinking budget to whatever the user happens to be chatting at — the same session-state coupling the model pin exists to remove. Effort follows the model split:

• xhigh on every fable and opus agent. The judgement roles are the pipeline's quality floor; their thinking budget must not silently degrade because the session runs lower. The fable gates deliberately stay at xhigh, not max — the marginal thinking is not worth the extra latency and scarce-budget burn.
• high on every sonnet agent. Tightly-scoped execution of a pre-made plan gains little from xhigh but pays its latency on every dispatch — and these are exactly the roles dispatched per-task inside loops (wall-clock is the pipeline's efficiency metric). Not lower than high: a sloppy in-loop step triggers re-loops that cost more wall-clock than the saved thinking.

Workflow scripts pin a third tier inline: schema-bound extraction/verification stages that author no code (preflight, plan-index, plan-extract[-all], snapshot, mini-verify, the standard end-verify, build/suite verify) run medium via the agent() call's effort: option. As with model:, every agent() call passes effort: explicitly — whether frontmatter effort propagates through an agentType dispatch is undocumented, so the scripts do not rely on it (see the policy header comments in implement/workflows/*.js).

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 composes this list and passes it to the agent via the carrier. It is built from a fixed always list — CLAUDE.md plus git log -10 --format=full, binding on every role — extended by the per-role standing reading the project lists in its CLAUDE.md project facts. The agent's body says, prosaically: "Read everything in the standing reading list before doing anything else."

The always list binds every role (agent file). The anonymous schema-bound stages inside implement/workflows/*.js are tiered below it (issue #31): verify-type stages read only the project-facts build/test commands, tree/extraction stages read nothing — see conventions.md § Standing reading.

When the project's CLAUDE.md project facts name a glossary path, that glossary is implicitly part of the always list, so every role reads the project glossary without a per-role entry.

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