claude
8ad396116e
The owner reviewed the recorded design-review dissent on the probe tier's sonnet override and agreed with it: field evidence is a rule-2 judgement role, and the probe cut lacks the deterministic measurement + verify gate the issue-#30 override rests on. The probe tier keeps its scope economy (1-2 examples on the single delta axis, capped report) and drops the model override; agent-template rule 2 loses the conditioned exception. refs #35
294 lines
11 KiB
Markdown
294 lines
11 KiB
Markdown
# 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. This rule covers the fieldtest's probe tier too:
|
||
a probe narrows *scope*, never the model (a sonnet probe
|
||
override was ratified and same-day retracted on review
|
||
grounds — issue #35).
|
||
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".
|