Files

T

Brummel a75a821a29 fix(implement-loop): guard plan-extract against silent truncation on big plans

The plan-extract step pulled every requested task's verbatim block through a
single schema-bound agent() response. On a large plan that response self-limits
and returns a well-formed PREFIX (commonly just task 1); the only guard rejected
an empty list, so a truncated non-empty subset ran to a clean DONE with the
missing tasks never attempted, yet the end-report read as a completion.

Replace the single-shot dump with an enumerate pass + per-task extraction,
guarded by cardinality checks (issue #22 suggested either direction; this does
both, plus a backstop the issue did not scope):

- plan-index enumerates ids + one-line titles only (bounded output, self-limits
  far later than a verbatim dump) and reports total_tasks, the whole-plan count
  computed from the fully-readable plan text independently of the emitted list.
- plan-extract:<id> carries one task's verbatim block per agent() call, removing
  the across-all-tasks output ceiling. Calls fan out via parallel() (which
  honours the concurrency cap on a big plan); the requested id is bound inside
  each thunk and results are re-associated by it, never by array position, so
  the mapping holds regardless of the order parallel() resolves in.
- Cardinality guards: (a) the whole-plan enumerate must list exactly total_tasks
  (the only backstop the no-range path can have without a caller range); (b) a
  task_range must be well-formed and covered exactly by the plan; (c) every
  expected id must extract non-empty text. Any breach is a hard BLOCKED with a
  precise "got N of M" reason, never a silent short run.

Known residual (documented in-code): a single task whose own verbatim body
overflows its dedicated response still returns an accepted prefix — bounded only
by the planner's bite-sized-task invariant, far narrower than the closed vector.

Verified by driving the real script through 11 extraction scenarios in a stubbed
harness plus an order- and self-id-independence association test, and an
adversarial three-lens review of the diff.

closes #22

2026-07-06 14:14:36 +02:00

8.9 KiB

Raw Blame History

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 — 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 (possibly fable — banned for all plugin agents and workflows, by owner decree). Pinning removes that coupling.

Assignment rule, in priority order:

Consequence of a miss — agents whose errors silently poison downstream work (adversarial gates, root-cause diagnosis, architecture judgment) run opus. Opus is the documented strength for code review, debugging, and deep reasoning.
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).
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 1 overrides (currently only quality-reviewer, the loop's last correctness gate).

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

The same rule binds Workflow scripts: every agent() call passes an explicit model: option (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 opus agent. The judgement roles are the pipeline's quality floor; their thinking budget must not silently degrade because the session runs lower.
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, mini-verify, tree-check, finalize, 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."

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

8.9 KiB Raw Blame History Unescape Escape