Brummel
7a58a530b1
The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.
Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
a verification/enumeration axis ahead of the settled-vs-fork question.
Each lighter arm carries a positive trigger matched by signature, not
reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
that propagates mechanically. Observe-then-bounce — make the edit,
build, run the suite; clean build AND suite green unchanged commits;
a hole bounces up (specify for a design choice, tdd for discovered
test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
mechanical/forwarding -> compiler-driven; encodes new behaviour ->
tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
not a heavy new skill ("the largest concrete win is small").
Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
phase (implementer -> spec-compliance -> quality, + tester for E2E) is
a separate top-level agent() call, so a single phase is independently
invokable and inter-phase aggregation/re-loop is code. Retires the
implement-orchestrator agent's inline-role-switch workaround (the four
phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
only the autonomous/mechanical loops moved. try-and-error is deferred.
Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.
Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).
closes #7
194 lines
5.9 KiB
Markdown
194 lines
5.9 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>
|
|
---
|
|
|
|
> 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.
|
|
|
|
## 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."
|
|
|
|
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".
|