# 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: description: tools: model: effort: --- > Violating the letter of these rules is violating the spirit. ## What this role is for ## Standing reading list ## Carrier contract ## Iron Law ## The Process ## Status protocol ## Output format ## Common Rationalisations | Excuse | Reality | |--------|---------| | … | … | (Calibrated to the past failure modes of this role.) ## Red Flags — STOP - If you're about to do , 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. One conditioned exception (issue #35): the per-cycle fieldtest's **probe tier** — the cycle's user-visible delta is a single narrow axis — is dispatched by the `fieldtest` skill with an explicit `model: sonnet` dispatch override; the one-axis scope bounds the judgement surface and the orchestrator triages every finding anyway. The frontmatter keeps the opus default, which the milestone fieldtest always runs. (The direct agent-dispatch surface has no per-dispatch *effort* override, so the frontmatter effort applies unchanged on a probe.) 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".