Brummel
cbd460e242
Add `pipeline.boss.spec_auto_sign` (default off). With it on, a /boss run may sign a spec in the user's place — but only through a gate built to never rely on the orchestrator's own confidence: all objective gates green (precondition, parse, grounding-check PASS with no human override) AND a unanimous five-lens adversarial spec-skeptic panel (criterion, grounding, scope-fork, ambiguity, plan-readiness). Any single BLOCK falls back to the human sign-off pause. On a clean sign the orchestrator commits the spec ((boss-signed) in the subject), fires a mandatory informational-with-veto notify, and proceeds to planner without stopping. A later veto is a forward correction, never a history rewind. - new agent: specify/agents/spec-skeptic.md (read-only, one lens per dispatch) - specify Step 6 + Iron Law: approval may come from the auto-sign gate, never from model self-confidence - boss: third notify category, §"Spec auto-sign", rationalisations, red flags - profile-schema + template: the opt-in slot - pipeline.md, agent-template.md, README: the auto-sign path documented
5.5 KiB
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,
spec-skeptic, 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, spec-skeptic, 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 verbatimdiff— for reviewers, the diff to reviewhypothesis— for the bencher, what it should testbug_symptom— for the debugger, the observable misbehaviourdrift_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".