Implements the three efficiency findings from the #310 pipeline
measurement (refs #35): ~691k subagent tokens / ~3.5 h for a
deliberately small cycle, with recon duplication as the single
biggest obligatory per-cycle cost.
1. Cycle recon (pipeline.md § Cycle recon; specify, planner,
brainstorm, boss, plan-recon): recon fan-out is budgeted per
cycle, not per phase. One full plan-recon dispatch — normally
specify Step 1, in a new pre-spec sources/recon_scope carrier
form — serves both the spec's concrete code shapes and the
plan's file-map. planner Step 2 becomes reuse-first (freshness /
quotability / coverage conditions) with narrowly-bounded delta
dispatches (new Delta dispatch contract in plan-recon.md);
broad Explore-type grounding sweeps are banned in every mode.
Field evidence: 151k (Explore) + 99k (plan-recon) with ~40 %
overlap in one bounded cycle.
2. Fieldtest probe tier (fieldtest, fieldtester, pipeline.md,
agent-template.md § model rule 2): a cycle whose user-visible
delta is a single narrow axis dispatches the per-cycle
fieldtest at tier: probe — 1-2 examples on exactly that axis,
~200-word report, explicit model:sonnet dispatch override (no
dispatch-level effort override exists; frontmatter effort
applies). Probe is a tier, not a skip; the milestone fieldtest
always runs full tier on the frontmatter model, keeping the
milestone-close gate's >=2-example floor unconditional.
3. Assumption economy (specify Step 3 + self-review item 6):
grounding-check cost scales with the spec's assumption count,
so specs state current-behaviour claims only where the change
relies on them (the gate's own falsity test), demote
context-only mentions to ledger citations, and keep iteration
scope tight — fewer restatements, never fewer reliances. The
gate itself is unchanged.
Design reviewed pre-implementation (opus plan review); diff
adversarially verified by a 3-lens review workflow (consistency,
operability, cross-reference), confirmed findings folded in.
refs #35
Effort joins model as a mandatory pin: an omitted field inherits the
session effort, coupling every dispatch's thinking budget to whatever
the user happens to be chatting at (often xhigh) — the same
session-state coupling the model pin removes. The assignment follows
the model split:
- xhigh on every opus agent (judgement roles are the pipeline's
quality floor and must not degrade with the session);
- high on every sonnet agent (tightly-scoped plan execution gains
little from xhigh but pays its latency per dispatch, and these are
the per-task in-loop roles — wall-clock is the efficiency metric;
not lower than high, since re-loops cost more than saved thinking);
- medium inline in the workflow scripts for schema-bound
extraction/verification stages that author no code (preflight,
plan-extract, mini-verify, tree-check, finalize, build/suite
verify).
Workflow agent() calls pass effort explicitly on every call — whether
frontmatter effort propagates through an agentType dispatch is
undocumented, so the scripts do not rely on it. Policy documented in
docs/agent-template.md § effort, mirroring § model.
Agents and workflows previously carried no model field, so every
dispatch inherited the session model — including fable, which is
banned for all plugin agents and workflows by owner decree. Every
dispatch now pins opus or sonnet explicitly.
- opus (low-volume judgment gates whose misses silently poison
downstream work): architect, bencher, debugger, fieldtester,
grounding-check, plan-recon, quality-reviewer, spec-skeptic,
tdd-author
- sonnet (mechanical scope, in-loop or fanned out): docwriter,
glossary-extractor, implementer, spec-reviewer, synthetic-user,
tester
- workflows: all 13 agent() call sites pin a model — sonnet
everywhere except the quality-reviewer gate in implement-loop,
the loop's last correctness check (spec-reviewer only gates
task-text correspondence; real-bug finding is the documented
opus strength)
- docs/agent-template.md: model is now a mandatory frontmatter
field, with the assignment rule and the fable ban recorded
An adversarial review of 08bc2aa found three gaps:
- templates/CLAUDE.md.fragment still described the OLD git-tracked /
git-rm-at-close model verbatim — the worst place to miss it, since new
projects import this fragment into their CLAUDE.md. Rewritten to the
gitignored / shell-rm / ledger-only model.
- INSTALL.md still cited "4-digit naming" — now slug-only.
- The fieldtest cross-cycle deletion rule was self-defeating: it keyed
the spare/delete decision on the permanent fieldtest- prefix, which
cannot encode "spare once, then delete." Because fieldtest runs only
AFTER audit closes, the fresh fieldtest spec never exists at the
cycle-close sweep, so the rule is simply "audit discards every
working-tree spec/plan"; the spent fieldtest spec present at N+1's
close was already consumed and goes with the rest. The prefix is now
only a working-tree label, not a delete discriminator. Reconciled
across audit, conventions, pipeline, fieldtest, fieldtester.
Per-cycle specs and plans stop being git-tracked commit-then-git-rm
artefacts and become git-ignored working files: created on disk for the
active cycle, read across sessions from the working tree, and shell-rm'd
at cycle close by audit. Nothing is committed, so there is no
git-history copy — the durable record of a cycle's intent is the design
ledger only, and no durable artefact (code, test, doc, ledger) may cite
a spec/plan by number or path.
- conventions/pipeline/design/README: invert the git-tracked -> git-rm
-> git-history-recovery model to gitignored -> shell-rm -> ledger-only.
- naming: drop the NNNN file counter; files are slug.md (fieldtest specs
keep a fieldtest- prefix as the cycle-close discriminator).
- cycle number: separated from the (now-gone) file number, sourced from
the feat(NNNN)/audit(NNNN) commit subjects, which cycle commits carry.
- specify/planner/fieldtest/fieldtester: no commit step; fieldtest splits
fixtures (committed as code) from its spec (gitignored), with the
cross-cycle rule that a fieldtest- spec belongs to the next cycle.
- boss: auto-sign auditability moves from the (boss-signed) commit
subject to the run's reference issue; rollback reverts only code.
- audit: new Step 5 shell-rm's the cycle spec+plan after the architect
reads them, sparing fieldtest- specs.
Companion machine config (outside this repo): the global git excludes
(~/.config/git/ignore) gains docs/specs/ and docs/plans/ so the ignore
applies to every project at once.
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing).
Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign.
Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
Authoritative carrier contract for the milestone fieldtest: scoped to
milestone_promise, scenarios derived top-down rather than as a union of
per-cycle axes.
A field test that runs a stale pre-built binary inverts its own
purpose — it reports the previously-shipped state as current, producing
false positives on already-fixed bugs and masking newly-introduced
ones. This bit an AILang raw-buf field test: the agent ran a
target/release binary built before a fix landed, reported a fixed bug as
still-broken, and masked a real check-clean/build-crash defect until
orchestrator re-verification against a fresh build.
Phase 2 now opens with a mandatory build-from-HEAD step (run
commands.build, or invoke the tool through the build system rather than
a path to a pre-existing artefact; build the release profile if the
examples invoke a release binary), and the agent records which build the
run exercised.
Apply the debug-skill pattern (commits 6410732..de42974) to the
remaining skills: the agent file is the single source for each
interface field's semantics; the SKILL.md copy is reduced to field
names plus a pointer, marking the agent's contract table
authoritative. Because SKILL.md loads into orchestrator context and
agents/*.md into the subagent's fresh system prompt with no
transclusion, duplicated field tables drift apart over time.
- brainstorm: carrier (spec_path/iteration_scope) -> grounding-check;
the absolute-path requirement now lives only in the agent.
- planner: carrier (spec_path/iteration_scope/focus_hint) ->
plan-recon, including the mandatory/optional markers and the
BLOCKED-on-missing rule SKILL.md had omitted.
- fieldtest: carrier + produced fields -> fieldtester; the skill-level
`status` roll-up (clean/friction_found/bugs_found/infra_blocked),
which is not part of the agent's run-status protocol, stays defined
in SKILL.md only.
- docwriter: carrier + produced fields -> docwriter agent.
- implement: carrier (iter_id scratch-dir/stats/not-a-branch
semantics) -> implement-orchestrator; per-task sub-status vocabulary
moved into the orchestrator-agent (it runs the loop in a fresh
context and could not read SKILL.md at runtime, yet referenced "the
sub-status table" by name); task_text_path single-sourced in
implementer with spec-reviewer cross-referencing.
audit was already the reference implementation (pointers, no restated
contracts) and is unchanged.
closes#2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fifth skill via the boss pattern. fieldtest empirically tests
whether a shipped cycle is usable by a downstream consumer
who has only the public interface.
Profile gains two slots:
- `paths.public_interface` — list of dirs/files the fieldtester
may read (the project's outward-facing surface: README, design
ledger, docs, examples)
- `paths.fieldtest_examples` — where the fieldtester writes its
fixtures
The forbidden zone is derived: everything not in
`paths.public_interface` (especially `paths.code_roots` and
`paths.bench_dir`) is closed to the fieldtester. This is the
load-bearing source-isolation discipline.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-fieldtester → fieldtester
- "AIL Surface form / .ail" → "the project's canonical
authoring or consumer form"
- "design/INDEX.md + design/models/" → `paths.public_interface`
- "crates/, runtime/, bench/" → `paths.code_roots`,
`paths.bench_dir`
AILang-specific bits dropped:
- The form-a-default-authoring milestone history (2026-05-13)
and the eight `.ail.json` carve-outs — AILang-specific
schema-migration detail; the universal rule is just
"canonical authoring form only"
- The ail check / ail build / ail emit-ir CLI commands — the
fieldtester now uses "the project's user-facing entry point"
- Per-iter journals reference — replaced with recent iter
commit bodies (universal)
- Example ideas calibrated to AILang (FizzBuzz, Newton's method
on Float, JSON-tree depth, ADT functors) — generalised to
"realistic tasks an end-user might be asked to do"
- `design/contracts/0004-feature-acceptance.md` cross-ref —
dropped (AILang-specific contract); the empirical-vs-
prospective brainstorm symmetry survives in prose
Universal substance preserved verbatim:
- All three Iron Law clauses (public-interface-only,
canonical-form-only, record-don't-fix)
- Five-phase process structure
- Four-class finding taxonomy (bug / friction / spec_gap /
working)
- Spec template
- Status protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT /
BLOCKED)
- All 8 Common Rationalisations rows (vocabulary-substituted)
- All 10 Red Flags bullets (vocabulary-substituted, with the
AILang-specific .ail.json hand-write bullet generalised to
"intermediate representations")
The source-isolation contract (Iron Law clause 1) is the
load-bearing discipline. Profile slot
`paths.public_interface` makes it machine-checkable; the
agent's hard limit on opening paths outside that list is the
discipline.
claude
Brummel