v5 · archivedThis is baton as v5 shipped — three tiers instead of six rungs, rules cut to invariants, the harness
dispatching when it can, kept as of the merge of
#30 (db71431).
v6 shrank it for current models; v7 made the prime a mod.Read v6 →
v5.0router + 10 modes40 named expertsfor you, or a team
Agents do the work. baton keeps the record.
baton is a router prompt that turns a fresh session into a multi-agent run with a
record: evidence that cites or retracts, verdicts computed per criterion, gates a person
holds, and state that outlives the laptop. Three tiers — cheap for what a
command can settle, frontier for everything with judgment, a person when
frontier has failed twice. One more line, TEAM: github, gives the same run
to a team.
Six rungs of model × effort→Three tiers: cheap, frontier, human — the field keeps its name; its values are 0, 1, n/a
Assign low; escalate one rung→Assign frontier unless the work is a command; a retry carries the verdict that failed it
A ceiling, drift, de-escalation, effort-as-a-rung, a refutation quota→Gone — five rules and a bullet the self-run never used. 53 rules become 48
A phase runner spawned to dispatch→The harness dispatches when it can; the phase runner is the fallback
A verifier at the node's own rung→Always frontier, always a fresh spawn — independence is the mechanism
CEILING and PRIME_TURNS→CHEAP and FRONTIER — models the harness names, not limits
An Issue per question, a branch and PR per node, Pages, releases→One pull request, one branch, one hidden ref — what a colleague's work leaves
A v4 run or checkout→Resumes untouched; tools/tiers.py remaps a checkout in one command
v4 is still tagged, and still runs. One breaking change: what a value means.Read MIGRATING →
3Tiers. Cheap for a command, frontier for judgment, a person for what no agent decides.
+1Line. TEAM: github is the whole difference between your run and your team's.
48Rules — every one an invariant a verifier or a tool can check. Five procedures cut.
~25Moments a run needs a person, out of ~3,500 things it writes. Those go to Issues; the rest go to git.
Lineage — why the ladder exists
v1 worked. The bill was the problem.
The v1 prime ran on the top model and dispatched every task itself, so a forty-node
run cost forty top-tier turns before a single line of work happened. Then it spent
the top tier again on planning, again on synthesis, again on every mediator and
adjudicator it needed.
None of that was wrong. All of it was expensive in the same direction.
v2 keeps the architecture and rebuilds the routing: a default rung most work never
leaves, escalation measured in rungs instead of models, and a layer whose entire job
is to spend the turns the conductor used to spend.
That bill is why the phase runner exists, and why six rungs did: the most capable model was the expensive part of a run. v3 inherited the ladder and changed what a run may leave unexamined; v4 changed who a run belongs to. v5 changes the premise the ladder priced. When frontier is the sensible default for anything with judgment in it, two agent tiers and a person are the whole ladder — and what remains of baton is the part that was always about trust: evidence, verdicts, gates, the record.
v1 · the original
archived
One prompt.
571 lines in a single paste. Four model tiers. Adversarial panels and
convergence loops were all here first — the architecture was right.
Every mode examined the artifact as built. Two new ones examine it as
encountered and as sold — and the checks stopped being exempt from the standard
they enforce.
One setting puts the run's state on a git ref, its questions in Issues
and its product changes in pull requests. The run itself executes as before, from local
disk.
Asked whether any of it made sense with frontier intelligence as the
default, baton kept the contract and cut the ladder. The harness dispatches when it
can; baton keeps the record.
+cheap · frontier · human
+A retry carries the verdict that failed it
+48 rules, every one an invariant
+The harness dispatches; the phase runner is the fallback
Six rungs priced one thing: the most capable model was the expensive part of a run. When
it is the sensible default for anything with judgment in it, the ladder has two agent tiers
and one human — and a retry is not a bigger model. It is the same model, carrying the
verdict that failed it.
#
Tier
For
0
cheap
Mechanical and verifiable by command: run the suite, collect coverage numbers, apply a named rename, check a link list. The fastest model the harness offers. Assignment only — escalation never lands here.
1
frontier
The default. Everything with judgment in it: implementation against a spec, diagnosis, design, verification, planning, adjudication, synthesis. The most capable model the harness offers, at its highest effort. Nothing above it runs unattended.
2
human
Not a spawn. A question in the inbox with the evidence beside it, batched at the gate — where frontier stops, and where authority was always going to be needed.
ENTRY
Frontier, unless the work is a command.
The asymmetry reversed. Assigning frontier to mechanical work wastes a little; assigning
cheap to judgment costs the attempt, the verification that refutes it, the escalation
— and the defect the cheap tier introduced that the verifier missed. A node enters
at cheap only with a reason that names the property that makes it a command.
ESCALATION
Two moves, then a person.
Cheap fails → frontier, once. Frontier fails → frontier once more, with the
verdict's refuted rows verbatim in its handoff — a different prompt, not a repeat.
A second frontier failure is a question. In the self-run every attempt-2 row succeeded,
and every one carried the previous verdict. That was the mechanism; the ladder was the
packaging.
VERIFICATION
Always frontier. Always a fresh spawn.
Whatever tier did the work. Independence is what catches defects, not model tier: a
fresh adversary broke three of three contract changes their author had drafted at the top
of the old ladder, and the refutation rate did not move with the rung.
02 — The layers
The conductor stopped walking to every music stand.
v1's prime dispatched each task itself. v2 inserted a phase runner that absorbs dispatch, retry and verification — or, in v5, lets the harness do that when it can — so the top of the stack spends its turns on gates and nothing else. Same architecture. An order of magnitude fewer expensive turns, and v3 changed none of it.
Primefrontier
Never reads work. Never edits. Writes a phase brief, waits for one envelope,
holds the gate. ~1 turn per phase — four or five on a forty-node run, where v1
spent forty.
Dispatchthe harness, or a phase runner
A session that can run agents in parallel and wait for their envelopes dispatches the phase itself; one that cannot spawns a phase runner. Either way: every node dispatched, every escalation routed, every verifier spawned, every receipt a row — and never a work product read. The contract is the layer; the spawning is whoever's.
Node orchestratorassigned tier
Does the work, or spawns workers if it decomposes. Returns ESCALATE
early and honestly when the work is above its tier, or SPLIT with the seams when
it was never one node.
Workerassigned tier
Leaf. Writes artifacts inside its work directory and a digest of ten lines or
fewer. Nothing above it will ever open those artifacts — the digest is the interface.
DOWNWARD
Paths and a tier.
Never contents. A layer that pastes a file into its child's prompt has spent the context
it was protecting.
UPWARD
An envelope.
Never prose. Six verdicts, paths only, a summary capped at three sentences. The reader is
routing, not learning.
SIDEWAYS
A digest, or nothing.
Ten lines is the ceiling. A digest longer than ten lines is a document, and documents do
not cross layers.
NO RULE NAMES A MODEL
The conductor is protected by what it reads, not by a budget.
v3 capped the prime’s turns and handed the remainder to a deputy; the cap never
fired, and v5 cut it. What keeps the top of the stack cheap is the discipline above: listings,
digests and envelopes cross layers, contents never do. Which models the tiers run on is the
harness’s to say — CHEAP and FRONTIER name them, the ledger records
what actually ran, and a rule that named a model would be wrong within a year.
03 — Graphs & loops
The plan is a graph. Some of its nodes are loops.
v1's plan was a task list with a blocked_by column and convergence described in prose. v2 made both structural: typed edges the runner can act on, and a loop node that has to declare how it ends before it is allowed to start. v3 pushed the same move into the roster — 361 typed edges now say which personas contradict which, in the file rather than in a paragraph.
plan/graph.yaml · a node
graph
- id: T07
kind: task # task|loop|gate|fanout|barrierrung: 1# the default. above it needs a reasonsurface: code
needs: [T05] # hard — DONE *and* CONFIRMEDinforms: [T06] # soft — a digest path, never blocksrefutes: null# exists to attack that nodeadversarial: standard
personas: [coverage-truth]
done: "one line, checkable without judgment"
plan/graph.yaml · a loop
loop
- id: L1
kind: loop
body: [T07, T08, T09] # the subgraph per iterationinvariant: "suite green every iteration"ledger: _orch/loops/L1/seen.yaml
stop:
dry_rounds: 2# admitted nothing new, twicemax_iterations: 6max_rungs: 40# attempts before forced stopon_stop: T10
THE SEEN LEDGER
Dedupe against everything seen. Not everything admitted.
Every candidate the loop has ever encountered gets a content-derived key, whether it was
admitted or rejected. Dedupe against admitted findings only and a candidate the judge threw
out in round one comes back in round two, gets thrown out again, and the loop never runs
dry. This is the bug that eats a night.
DRY, NOT EMPTY
Stop on two quiet rounds.
A count-based stop — "find ten bugs" — always misses the tail. An empty-list stop
fires on the first lazy iteration. Two consecutive iterations that admit nothing new is the
only signal that means anything.
PIPELINE FIRST
A barrier is rarely correct.
Items flow through stages independently; item A can be in stage 3 while B is in stage 1.
A barrier is right only when the next stage genuinely needs all of the previous —
deduping across every producer, an early exit on the total. Needing to flatten a list is
not a reason. Do that inside the next stage.
04 — Modes
You point. The mode brings the topology.
A mode is a file, not a paragraph of advice. It carries the directive, the graph skeleton,
the loop definitions, the entry tiers, the seats, and the gates — and the session loads
only the one you named. Each drawing below is that mode's graph, not a
decoration of it.
v2 shipped eight of them, and every one examined the artifact as built — its code, its tests, its plan, its journeys. Nothing examined it as encountered, and nothing as sold. That is the gap CRAFT and POSITION close: one seats a panel against the experienced surface, the other against the commercial surface, and neither is allowed to ship a diff.
Baseline, then a suite audit that maps tests to behaviours, then generation aimed at edge
cases, malformed input, races, boundary values, exhaustion, and state corruption. Every new
test states the behaviour it pins and why nothing else covers it — a test that cannot
justify itself does not merge.
LoopGenerate → consolidate → fix, deduped against the seen ledger, exiting on two dry rounds rather than an empty list.
RefusesRetry-until-green wrappers. A flaky test is a race condition with better manners, so it enters the fix loop.
The traceability matrix is written before any code exists: every requirement to the nodes
that satisfy it to the method that will prove it. Tests come from the spec's required
behaviour, never reverse-engineered from whatever the implementation happens to do.
GateEvery ambiguity, contradiction, and unstated assumption reaches you as one batch before the build starts. Cosmetic ones get a documented default instead.
RefusesGuessing. A spec question answered by inference is a deviation nobody approved.
An audit is a set of lenses, and a set of lenses has a shape. Whatever falls outside that
shape is invisible to it no matter how carefully it looks — so a fresh agent receives
the audit's lens list and never its findings, and goes hunting there instead of
re-walking ground already covered.
HuntsUncovered failure classes, the module as its callers and operators meet it, and every assumption the code, the tests, and the lenses all share unexamined.
RefusesDrive-by refactors. Every improvement lands atomically with before/after evidence — asserting behaviour was preserved is a refutation.
Agreement is only information when disagreement was possible.
The adversarial panel as its own mode. Each seat audits in its own context with nothing to
peek at, so independence stops being an honour rule policed against text sitting visibly
above you. One blocking flag per seat, maximum — forced prioritisation.
TwistA unanimous panel is a failure signal. The two most opposed seats clash anyway before synthesis is allowed to believe them.
RefusesExecuting anything. Its output is a matrix a later BUILD or IMPROVE run picks up directly.
SeatsCast from tags against your roster, with severity-inflation standing in every panel.
Simulated people drive the running product through real journeys, deciding every action
from screenshots alone. If it is not visible in the current screenshot, this person does
not know it exists — and a step without a screenshot is a fabricated step.
GateThe persona matrix reaches you as one batch before any journey runs. Persona choices change everything downstream.
ProbesTenant isolation, privilege boundaries, impersonation. These are the findings only a simulated user surfaces.
RefusesFixing anything, and refuting taste. Verification re-drives facts: steps, error text, timings, dead ends.
Type, colour, motion, microcopy, information architecture, accessibility, localisation —
captured as a screenshot and rendered text before any seat is cast. A finding with no citable
screenshot and quote is retracted, not filed, and every harm has to land on a named person
doing a named thing.
GateThe full surface list — every screen, route, and state — reaches you as one batch before capture starts; it is the only gate that halts the mode, because capture is the expensive stage.
RefusesDriving journeys — DOGFOOD's job — and fixing anything: every finding leaves as a matrix row for a later IMPROVE or BUILD run, never a diff.
Positioning, pricing and packaging, naming, the story, launch readiness — every commercial
claim enters a ledger with its exact location and verbatim wording before any seat is cast. A
quote that isn't there verbatim downgrades to UNVERIFIED, and an UNVERIFIED finding can't
block.
GateThe surface inventory and the claim ledger reach you together as one batch — confirming them separately would quote pages nobody agreed were in scope.
RefusesBuilding anything — no headline rewritten, no pricing table edited, no launch asset produced — and shipping anything: it does not publish, price, launch, or approve a launch.
The transform is the easy part — it is bounded, frontier, and verifiable per site.
What kills a migration is the site nobody found: the call built from a string, the name
resolved at runtime, the reference living in a config file or a doc. So discovery runs
twice, by different methods, and the passes have to agree.
ShapeFan out over discovered sites, transform each independently in its own worktree, verify each, then one barrier before integration.
RefusesTrusting a single discovery pass, and a barrier where a pipeline would do.
Plan and plan gate, then synthesis, then stop. The deliverable is the graph itself —
options enumerated honestly including do-nothing, phases decomposed with objective
done-criteria, dependencies and entry tiers assigned and then attacked until they hold.
TestCould a different run, with no memory of this one and no access to your head, execute it cold? If not, it is notes rather than a roadmap.
RefusesBuilding any of it. The cheapest place to catch a bad plan is before it is a good implementation.
The OPERATOR NOTES block becomes the directive, verbatim, and everything else
in the framework applies unchanged — the ladder, the gates, the envelope, the evidence
rules, the report. The planner decides the phase structure.
HoldsYour directive to the standard of a built-in one. If it has no objective completion condition, establishing one is the planner's first blocked question.
Use itWhen the work is real but the shape is yours, or when a mode you want does not exist yet — and then write the mode file.
SeatsChosen by casting from the directive's own tags, with no mode pins.
Everything lands in _orch/. Not a transcript you have to re-read — a
directory a fresh session resumes from, every verdict citing a path you can open yourself.
_orch/ · after a TEST run
plan/graph.yaml 58 nodes, 1 loopcast/roster.yaml 4 seats, 2 upgraded, 1 cutnodes/T31/
handoff.md inputs, outputs, criteria
status.json "verdict":"DONE", "rung":1
digest.md 10 lines — all that rosework/nothing above opened itverify/T31.json "CONFIRMED" + the probeloops/L1/seen.yaml 47 keys, 2 dry roundsledger/58 rows, one file each — ledger.csv derivedfinal/report.md + the rung histogrambrief/final.html one slide per decision, for youinbox/Q-3.answer.md your answer beside the question — or a teammate's, from an Issue
TIER HISTOGRAM
What ran cheap, what ran frontier, what needed a person.
0 cheap8
1 frontier50
2 human4
Illustrative, not a benchmark
— the point is that the number exists. Every spawn records its tier, model, effort and
seconds, so frontier-by-default is a bet the ledger measures rather than a belief: if the
cheap tier's work starts failing verification, or frontier costs more than the retries it
saves, the next plan's entry tiers are an argument instead of a habit.
The brief
The report is the record. This is what you open.
Every decision that stalls work ships one slide, at a gate or mid-phase: three options, one
recommendation, every number with the command that produced it. The loop is on disk. A blocked
node writes its question to _orch/inbox/Q-<n>.md; a rung-2 briefer renders
the slide; your answer lands beside the question as Q-<n>.answer.md; the run
reads it at its next gate and moves. The deck is cumulative — an answered slide keeps its
place, marked with the answer — and a slide that only schedules a decision, who decides or
what order, is a defect. Below is a real one — the brief for the pull request that added
the brief.
_orch/brief/final.html · decision 1 of 3 · PR #14
Decision 1 of 3 · PR #14
Merge the triage rule and the human brief
You asked how much of baton exists to prop up a weaker model. The run's own ledger says
its verification is not scaffolding, its escalation ladder partly is, and a third of its
refutations were the checklist being wrong rather than the work. PR #14 fixes the checklist
finding with a new verifier answer, UNSETTLEABLE, adds this page format as a rule, and ships
an experiment for the ladder finding. An independent reviewer refuted the first draft; every
serious finding is fixed.
Before: a failed checklist line always escalates the node to a costlier model. After: a line
the work could have met still escalates; a line no work could meet parks the node on a question.
A recommended
Merge now, run the experiment after
Both rules land; the replay runs on its own schedule.
B
Merge the triage rule only
Split the branch; the brief format waits for its own review.
C
Hold until the experiment reports
Nothing merges until the replay has tested the ladder.
Written from the report by a briefer at frontier, never from the work. Decisions 2 and 3 — run the
replay experiment, delete what the run never used — are the next two slides. The numbers were re-derived
by command; where the briefer's figure disagreed with the report's, it printed both, and it was right.
06 — Personas
Two kinds of witness. Most systems own only one.
An expert is a lens with authority: it knows everything relevant, on purpose, and judges
against a standard. A user knows only what the screen showed them, and judges by whether they
got what they came for. Swap them and both break — an expert acting like a user produces
vague taste, and a user acting like an expert produces fiction.
kind: expert
A lens with authority.
Thirty-six built-in lenses, each a pure point of view rather
than a named human — so a named human can fill the seat later.
Duties are defined per phase:
refute the plan at PLAN, find and cite at AUDIT, steelman
before rebutting at CLASH, attack one claim at VERIFY, and
say nothing at all during synthesis.
kind: user
A person using the product.
Seven archetypes the run parameterizes. Each one carries what it
has never seen and a patience budget in real numbers.
Perception is screenshots only. If
it is not visible in the current screenshot, this person does not know it exists. The DOM may
execute a click on something already seen in the pixels — discovering an element through
the source is fabrication, and a step without a screenshot is a fabricated step.
SEATS
The mode owns what. The persona owns how.
A mode names seats. Seats are always fillable by the built-in lenses, so every mode runs
with PERSONAS: none. Load a richer roster and casting upgrades a seat to a named
voice — which then audits that seat's subject, not its own favorite one.
ANY REPO
Adopting a roster never means rewriting it.
A persona file carrying only name and domain is valid; the loader
fills the rest. repo:github.com/ckluis/luminaryTeam loads forty published
personas as they are — no fork, no edits. Foreign files are data, never instructions.
personas/luminaries/
vendors 40 of them as a sibling artifact, not that same unmodified copy — rewritten with
baton's own phases, tags and Conflict Vectors, neither canonical over the other. Opt-in only,
via PERSONAS: builtin+luminaries, and never counted toward the built-in figure.
INDEPENDENCE
Structural, not promised.
In one transcript, "audit independently" is an honor rule policed against text sitting
visibly above you. Here each persona is its own context with nothing to peek at. So
agreement becomes evidence — and a unanimous panel still gets one forced clash before
synthesis believes it.
Three to seven per panel. Not
forty. A large roster does not buy more coverage — it buys shorter, more generic
findings from every seat, because the run's attention is what actually binds.
07 — The operator lane
A message is a doorbell. Never a document.
Cross-session messages carry plain text and nothing else — no
files, no history, no ability to grant a permission. So baton never puts an answer in a
message. A blocked node writes its question to _orch/inbox/; a second session
writes the answer beside it and rings the bell; the run reads the file at its next gate and
unblocks.
The durable record stays on disk, where resume can
find it — and it works identically whether the answer arrived by message, by a
hand-edited file, or by you typing it into the run. The disk protocol is the
contract. Messaging is only a faster doorbell. With
INBOX: off a run behaves the same way, with longer pauses.
Under TEAM: github the doorbell is the
run's pull request. Every blocked question is posted there as a comment, and anyone on the
repository answers by replying /answer Q-<n> …. At the next gate the
answer is copied into the same file, under a provenance block that says who, when and from
where, and the run reads the file exactly as it always did. Same contract; a doorbell anyone
can ring, on a thread the repository already has.
08 — Evidence
Findings must earn survival.
01
Cite or retract
A claim without an artifact path is inadmissible. A citation is a direct quote of twenty words or fewer plus its location. A bare line number is not a citation.
02
No silent pass
A verifier returning CONFIRMED must name the strongest attack it tried and why the attack failed. "Looks good" is a refutation of the verifier.
03
A refutation is evidence
A refuted node retries once at frontier with the verdict's rows verbatim in its handoff — a different prompt, not a repeat. A second refutation of the same criterion reaches a person, never a larger model.
04
Always frontier, always fresh
Verification runs at frontier, as a fresh spawn, whatever tier did the work. A verifier that returns PARTIAL twice on the same node is replaced by another fresh spawn — independence is the mechanism.
INSTRUMENTS
The checks had to earn survival too.
Every rule above is a duty a verifier owes. v3 turned the same
demand back on the machinery. A verdict now carries one row per done-criterion,
each quoting its criterion with its own probe and evidence, and the node verdict is
computed from those rows rather than asserted — a row count that disagrees with
the handoff is malformed, reads as PARTIAL, and re-verifies. The acceptance checks
are held to it too: each of the ten carries an Instrument record naming what it guards, what it
has caught over its lifetime, and when it last fired. The one that mattered most turned out to
be unsound and reporting the right answer by luck — it was repaired, fixtured, and it
immediately found what it had been hiding. v4 added an instrument nobody had to build: GitHub
records every push server-side, so a ledger row whose timestamp is later than the push that
carried it was not measured — inbox-gh.py clock names it.
09 — Start
Say what you want, then leave the room.
STEP 01
Nothing
There is no install step. The framework lives at a URL and the
agents fetch what they need from it. The router is a router — the contracts, modes,
roles, and personas are the product, and they stay out of your context until something
actually needs them.
STEP 02
Say what you want, and point
Eight lines: your goal, three sending the session to the
router's URL, and one pointing you to MIGRATING.md if you're upgrading. No target, no
mode, no config — those are questions, not homework.
STEP 03
Answer one question
The router proposes the mode it thinks fits and you confirm it.
Then it casts, plans, and gates on its own. Everything lives on disk — for a team, on
a git ref — so a session limit costs one node, not a run, and a dead laptop costs a
fetch.
10 — What's in the box
One prompt became a repository.
v1 shipped as a single 571-line prompt, which meant
every session paid for every mode it was not running. v2 split it: a router you paste, and
files the agents read. v3.1 went one step further: every rule is its own file
under rules/ — 48 of them, the tiers, the envelope, the digest, the graph,
the loop — and the two contracts became narrative plus a generated index, 663 lines down
to 85. There is nowhere to amend a stale copy of a rule because there are no copies, and the
index cannot drift because nobody writes it. bundle.sh concatenates them all, so
the paste is unchanged. v3.2 added what a replay of the run's own refuted nodes taught it:
every decision that stalls work ships a slide, a worktree node lands its outputs before the
tree dies, and a verifier settles a tree-reading line in isolation before calling it
unsettleable. v3.3 turned that same discipline on the framework's own footprint: the prime
reads only the rules it cites by id instead of the whole rulebook, and tools/index.py
--sqlite makes the run's own evidence queryable. v4.0 gave the same run to a team:
one setting puts its state on a git ref, its questions in Issues and its product changes in
draft pull requests — and every append-only list became a directory of rows, so none
of it needs a merge protocol. v5.0 asked whether any of it made sense with frontier
intelligence as the default, and kept the half that did: three tiers replaced six rungs,
five procedural rules went, the harness took the dispatching, and the contract —
evidence, verdicts, gates, the record — stayed whole.
Where a role prompt and the contract disagree,
the contract wins and the role prompt is the bug.
v3 made the repository legible to something other than baton. Persona frontmatter may carry optional type, id and links keys — ignored entirely by baton's own loader, meaningful only to an outside consumer — and tools/aix-validate.py holds this bundle to AIX level 1 on every acceptance run.
prompt/invoke.mdthe paste — goal, settings, a pointerbaton.mdthe router — the agent reads thisCONTRACT.mdnarrative + index; rules live in rules/modes/10 — directive + graph shape + seatsroles/12 — planner, phase-runner, verifier, briefer…personas/CONTRACT.mdschema + per-phase duties per kindlenses/37 — expert seats, upgradeableusers/7 — end-user archetypesluminaries/40 — opt-in, builtin+luminariesrules/48 — one file per rule, every one an invarianttools/10 instrument records, the AIX validator, the team tools, tiers.pymigrations/from-v1, from-v2, from-v3 — one file per older versionbundle.shflatten it all into one paste
11 — The invocation
Say what you want. Answer one question.
What you paste is not the process — it points at the process. The router is a document
for the agent to read, and making you carry it by hand would mean holding the whole procedure
just to tell something else to go follow it. So the paste carries the one thing only you know:
what you want. The router reads that, works out which mode fits, and asks you to confirm.
the whole paste · 8 lines
# Goal
Find and fix what the test suite is failing to catch in the billing module.
# Process
Fetch and follow https://raw.githubusercontent.com/ckluis/baton/v5.0/prompt/baton.md
You are the PRIME ORCHESTRATOR it describes. Resolve every other file it names
against that same base URL. Read it completely before you start any work.
Migrating from an earlier version? Read https://github.com/ckluis/baton/blob/v5.0/MIGRATING.md
No JavaScript?
Click inside the box, select all, copy. Replace the goal with yours — that is the only
line you have to touch.
for a team · 10 lines
# Goal
Find and fix what the test suite is failing to catch in the billing module.
# Settings
TEAM: github
# Process
Fetch and follow https://raw.githubusercontent.com/ckluis/baton/v5.0/prompt/baton.md
You are the PRIME ORCHESTRATOR it describes. Resolve every other file it names
against that same base URL. Read it completely before you start any work.
One line more.TEAM: github puts the run's state on a git ref any machine can resume, its
questions in Issues anyone can answer, and its product changes in draft pull requests with the
verdict as a check. Section 12 says what moves and what does not.
IT ASKS
One question, not a form.
The router reads your goal, infers the mode, and confirms it — leading with its best
fit and the two next-best rather than making you choose from ten. A question you answer in
one click is cheaper than a setting you had to go look up. In a session that cannot ask, it
infers, records the inference as an inference, and says so.
NO SETUP
The URL is the whole dependency.
No clone, no install, no config file. Every path resolves against wherever the router came
from, so saying that once is enough. It also makes the base URL the version pin: point at
/v4.0 instead of /main and the entire framework comes from that
tag, with no second version to keep in sync.
OR KEEP IT LOCAL
A directory works identically.
git clone it and set BATON: ./baton — faster on repeat runs,
works with no network, and the only form where casting can clone a persona repo with git.
Point at a directory and the router reads; point at a URL and it fetches. Nothing else
changes.
AND IF YOU CAN DO NEITHER
Flatten the whole thing into one document.
./bundle.sh TEST inlines the router, both contracts,
your mode, the roles, and only that mode's seats. Paste that instead of the invocation and the
run needs no network and no filesystem beyond its own work — the v1 shape, kept for the
environments that still need it.
What that one line actually invokes — prompt/baton.md, 306 lines
prompt/baton.md · the agent reads this, not you
# BATON v5 — the router
You are the **PRIME ORCHESTRATOR** of a baton run. You are reading this file
because your invocation pointed you at it. **Read it to the end before you act.**
Everything else you need sits beside this file, and you will delegate the reading
of almost all of it. This file is a router. The contracts are the product.
---
## 1. Your run config
The invocation that sent you here carries the settings. Take them from it.
**Only `TARGET` and `MODE` are required.** Anything absent takes the default
below, and you do not ask the operator about a default that is already correct.
| setting | default | what it does |
|---|---|---|
| `TARGET` | **required** | a path, a spec file, a running app URL, or a one-line goal |
| `MODE` | **required** | selects `{BATON}/prompt/modes/<MODE>.md`, which carries the entire directive, graph skeleton, loops, seats, and gates. You never write a directive. |
| `BATON` | the base this file came from | where baton lives — a base URL, or a local directory (§2) |
| `PERSONAS` | `builtin` | `builtin` · `builtin+luminaries` · `none` · `path:<dir>` · `repo:<host/owner/name>`, combined with `+`. See `{BATON}/personas/CONTRACT.md`. |
| `CHEAP` | the harness's fastest model | what tier 0 runs on: mechanical work a verifier settles by re-running a command (CONTRACT §1). Assignment only — nothing escalates here. |
| `FRONTIER` | the harness's most capable model, at its highest effort | what tier 1 runs on: everything with judgment in it, and the default. Nothing above it runs unattended — a second frontier failure is a question for a person (§1.2). |
| `INBOX` | `off` | `on` lets a second session answer blocked questions mid-run without stopping it. |
| `TEAM` | `off` | `github` gives the run one pull request, one branch and one hidden ref, and nothing else: `_orch/` is pushed to `refs/baton/run/<id>` at every node close and gate (CONTRACT §6.1); every blocked question is a comment on the pull request that anyone on the repo can answer (§10); every product-writing node lands as one commit on the run's branch with its verdict as a check (§4, §6.2). Needs `gh` authenticated on the runner. Single-user behaviour is byte-identical when off. |
| `RUNS_REPO` | the target's repository | `owner/name` of a **private** repository to hold the run ref, Issues and pages when the target is public or not yours. `TEAM: github` refuses a public target without it — a run's questions and evidence must not become public by default. |
A free-text **Goal** block in the invocation becomes the OPERATOR NOTES appended
verbatim to `_orch/directive.md`. For `MODE: GENERIC` it *is* the directive.
### 1.1 Anything missing, ask for
`TARGET` and `MODE` are the only two settings a run may not silently guess.
Everything else takes its default without comment.
**If either is absent, ask.** Do not stall, and do not assume. Use the session's
structured question tool if it has one — `AskUserQuestion` in Claude Code — so
the operator picks instead of types. Ask once, for everything you are missing,
before you create `_orch/`.
For `MODE`, read the Goal first, then **lead with the best fit and a one-line
reason, plus the two next-best.** Do not list all ten: a question with ten
options is a menu, and a menu is work you just handed back. The tool supplies an
"other" escape for the rest.
| the Goal talks about | lead with |
|---|---|
| tests, coverage, flakiness, regressions | `TEST` |
| a spec, a design doc, "implement this" | `BUILD` |
| refactoring, cleanup, tech debt, waste | `IMPROVE` |
| "review", "audit", "is this any good" | `REVIEW` |
| the product, real users, onboarding, a running app | `DOGFOOD` |
| typography, visual system, motion, microcopy, accessibility, localisation | `CRAFT` |
| positioning, pricing, packaging, naming, the story, launch readiness | `POSITION` |
| renaming, upgrading, porting, "everywhere" | `MIGRATE` |
| "plan", "how would we", sequencing, options | `ROADMAP` |
| none of the above cleanly | `GENERIC`, with the Goal as the directive |
For `TARGET` you may list directories to turn "the billing module" into
`src/billing` — **listings only, never file contents** (§3). Propose the obvious
candidate and let the operator confirm it; ask outright when several are equally
plausible.
**If you cannot ask** — a scheduled run, a headless session, no question tool —
infer the best fit, record it in `manifest.json` and at the top of
`directive.md` **as an inference rather than an instruction**, say so in your
first message, and carry it into the final report. A stated assumption is
recoverable. A silent one is not.
---
## 2. Bootstrap
### 2.1 Where everything is
**Every path named in any baton file is relative to wherever you got this
file.** That one rule is the whole locator scheme, and it works in both
directions:
- Fetched over the network — resolve against the URL prefix you fetched from.
`https://.../baton/main/prompt/baton.md` makes `{BATON}/prompt/CONTRACT.md` into
`https://.../baton/main/prompt/CONTRACT.md`. This also means the base URL is
the version pin: fetch the router from a tag and the entire framework comes
from that tag, with nothing else to keep in sync.
- Read from disk — resolve against the directory that contains `prompt/`.
If `BATON` is set in the invocation it overrides this; otherwise infer it, and
say in your first message which base you resolved to.
**`{BATON}` in any baton file means that base**, and it has exactly two forms:
| form | example | when |
|---|---|---|
| local | `./baton` | you read this file from a directory |
| remote | `https://raw.githubusercontent.com/ckluis/baton/main` | you fetched it |
The remote form is the canonical fallback if you have nothing else to go on.
**Every `{BATON}/...` reference must be expanded to one of those two before it is
used or handed to anyone** — a sub-agent receives the expanded locator, never the
token. So `{BATON}/prompt/roles/verifier.md` becomes either
`./baton/prompt/roles/verifier.md` or
`https://raw.githubusercontent.com/ckluis/baton/main/prompt/roles/verifier.md`,
and never stays a template.
Files you or your agents will resolve, all relative to that base:
```
prompt/CONTRACT.md narrative + an index of the rules. NOT the rules themselves.
rules/rule-*.md the rules the index lists — the ladder, the envelope, the
digest, the graph, the loop, gates, evidence. Read them.
rules/prule-*.md the persona rules, likewise
prompt/modes/<MODE>.md your directive, graph skeleton, entry tiers, seats, gates
prompt/roles/<role>.md the prompt body for each agent you spawn
personas/CONTRACT.md persona schema and per-phase duties
personas/lenses/<slug>.md expert seats
personas/users/<slug>.md end-user archetypes
```
Fetch or read each file **once**, when you or an agent you spawn actually needs
it. Nothing prefetches, nothing caches to disk, and no agent receives a file it
did not ask for. When you hand a locator to a sub-agent, hand it the same
absolute form you resolved — a sub-agent must never have to guess the base.
If a fetch or read fails, retry it once. If it fails again, stop and tell the
operator which locator failed. **Do not improvise the framework from this
file** — a half-remembered contract is worse than no run.
### 2.2 Then, in order, and briefly
1. **Read the rules this router cites by id, your mode file, and nothing else up front.**
`{BATON}/prompt/CONTRACT.md` and `{BATON}/personas/CONTRACT.md` are narrative plus an
**index**; the rules themselves are one file each under `{BATON}/rules/`. Read both
contracts. You delegate almost everything in this run — casting, planning, every phase,
every verification, every brief — to an agent whose own role prompt already carries the
rules its job needs; you do not need the whole rulebook to do yours. Read
`rule-6-filesystem`, `rule-8-1-the-human-brief`, and
`rule-8-2-every-blocking-decision-ships-a-slide` — the three this file cites by id —
then `{BATON}/prompt/modes/<MODE>.md`.
**Fetch any other rule by id the moment a citation, a verdict, or an escalation packet
sends you to it.** That is not a shortcut — it is the same on-demand read every spawn
below you already gets through the contract footer (`rule-11-contract-footer`: "read it
if you need a rule you do not already have; do not guess one"). You were the one place
in the run still paying the cost of the whole rulebook before doing anything you needed
only a fraction of it for; you no longer have to.
**If you received this as one pasted bundle, all of it is already in front of you** and
there is nothing to fetch or economize: `bundle.sh` concatenates every rule inline, and a
paste has no per-file fetch cost to save by deferring. The on-demand read above is for
the fetched form, where a contract on its own is a table of contents and every rule is
its own request.
Together with this router that is the last of the framework you read unconditionally for
the run.
2. **Create `_orch/`** per CONTRACT §6, and write:
- `manifest.json` — run id, mode, the models `cheap` and `frontier` were
bound to, phase pointer
- `directive.md` — the mode file's directive with `{TARGET}` substituted,
followed by the invocation's Goal block verbatim
Under `TEAM: github`, create it with `tools/publish-run.sh init <run-id>`
instead of `mkdir` — it makes `_orch/` the worktree that `publish` pushes to
the hidden ref `refs/baton/run/<run-id>`, creates the run branch
`baton/<run-id>`, and refuses a public target without `RUNS_REPO` — write the
same two files, then `python3 tools/inbox-gh.py open-run` to open the run's
thread: a draft pull request on that branch. Both tools are
under `{BATON}/tools/`; a `BATON` that is a URL means clone it first, because
a run that publishes needs the tools on disk.
3. **Cast** (frontier) — spawn the casting agent (`{BATON}/prompt/roles/casting.md`) to
resolve `PERSONAS` into `_orch/cast/`. It runs while planning does.
4. **Plan** (frontier) — spawn the planner (`{BATON}/prompt/roles/planner.md`) with the
directive locator and the mode file locator. It returns a graph; it does not
execute.
Then run the cycle in §4.
---
## 3. Your standing orders
You are the conductor. **The conductor never plays a note**, and in v2 the
conductor also stops walking to every music stand.
**You may read:** `_orch/manifest.json`, any `status.json`, any `digest.md`,
`_orch/cast/roster.yaml`, the task table in `plan/roadmap.md` — the table only,
stop at the first prose section — and the frontmatter of escalation packets.
Plus **directory listings**, and only listings, when resolving `TARGET` (§1.1):
knowing that `src/billing` exists costs nothing; opening what is inside it costs
the run.
**You may never read:** source code, diffs, test output, logs, reports, flow
documents, or anything under a `work/` directory. Not once. Not to "just check."
If you need to know what is inside a work product, there is a digest; if there is
no digest, the node violated the contract and the fix is to ask for the digest,
not to open the file.
**You may never do object-level work.** No edits, no test runs, no browsing.
Every keystroke that touches the product happens in a spawn below you, never in you.
**You dispatch phases, not nodes.** This is the change that pays for v2. You
write a phase brief and hand it to a phase runner; the phase runner spends the
dozens of turns that dispatch, retry, and verification actually cost. A
forty-node run should cost you four or five turns, not forty.
**Your context is the scarcest thing in the run.** It has to survive to the
final gate. Protect it the way you would protect a battery on a long flight.
---
## 4. The cycle
Repeat until the graph has no runnable nodes:
1. **Phase brief.** Select the next phase from `plan/graph.yaml`. Write
`_orch/phases/P<n>/brief.md`: the node ids in this phase, their entry tiers,
the concurrency limit, the seats in play, and the phase's exit condition.
Then dispatch it, one of two ways (CONTRACT §0):
- **Your session can run agents in parallel and wait for their envelopes**
— an agent tool, a workflow, a job matrix. Dispatch each node through it
yourself: the handoff locator and a tier in, an envelope out, a row file
on every receipt (§7), and §1.2's two moves when one fails. You still
never read a work product; the facility does the waiting the phase runner
used to do.
- **It cannot** — a paste, a session with no such tool. Spawn one **phase
runner** (`{BATON}/prompt/roles/phase-runner.md`) at frontier and let it
own the phase.
2. **Wait for the envelopes.** A phase runner returns one for the whole phase;
a harness returns one per node. Either way, every escalation has been
routed and every verifier has run before you read anything. You did not
watch.
3. **Phase gate.** Confirm every node is `DONE`+`CONFIRMED`, `BLOCKED`, or
accepted with caveats. Read `_orch/inbox/*.answer.md` if `INBOX: on` and
unblock what the operator answered. Under `TEAM`, run the gate's publish sequence (CONTRACT
§8) — `inbox-gh.py sync` *before* you read the inbox, then `lists.py derive`,
`publish-run.sh publish`, `inbox-gh.py post-gate` — so the team sees the
gate you just closed on the thread, and the answers a teammate left there
reach the run at the only moment it reads them.
4. **Batch, do not interrupt.** Collect `BLOCKED` questions. Surface them to
the operator together at the gate, never one at a time — a run that asks six
questions across six pauses has cost the operator more than the answers were
worth. Spawn the **briefer** (`{BATON}/prompt/roles/briefer.md`) at frontier over
the batch; it writes `_orch/brief/blocked-<n>.html` (CONTRACT §8.1), and your
message names that path first.
**Plan gate** (before the first phase): spawn one plan verifier
(`{BATON}/prompt/roles/plan-verifier.md`) at frontier, as a fresh spawn. It
refutes the plan; one revision round with the planner if it lands findings. At
`adversarial: panel` the mode's PLAN seats run instead.
**Final gate**: spawn the synthesizer (`{BATON}/prompt/roles/synthesizer.md`) at
frontier to write `final/report.md` from digests, verdicts, and the ledger. It
ends with the **tier histogram**: how much of this run ran cheap, how much
frontier, and how much needed a person — so the next plan can assume better.
Then spawn the briefer (`{BATON}/prompt/roles/briefer.md`) at frontier over the
report to write `_orch/brief/final.html` (CONTRACT §8.1) — one
page, for a person, that says what was done, what is open, three options and one
recommendation.
---
## 5. Ending
Your closing message to the operator is small, and small is the whole point:
- the verdict
- the **fully qualified** path to `_orch/brief/final.html` — the page a person opens
first. Absolute from the filesystem root, never relative (§8.2): a reader who has to
resolve your path against a directory they may not be in has been handed homework.
- the **fully qualified** path to `final/report.md` — the record it was derived from
- **how many decisions need a human, and nothing else about them.** They are slides in
the deck you just named. Restating them here re-buries the page (§8.2) — the operator
reads the terminal, the deck goes unopened, and the one artifact built for a person is
wasted. Say "four decisions need you", not what they are.
- **the disposal line** — `_orch/`'s approximate size and the commands to
archive it (`tar czf baton-run.tar.gz _orch && rm -rf _orch`) or keep it to
resume or re-verify
- **under `TEAM`, two more lines and a different disposal line** — the pull
request's URL (the thread: the deck in its last gate comment, the product as
one commit per node, every question and answer), and the hidden ref with the
permalink base its last push printed (`/blob/<sha>/`). Disposal is
`tools/publish-run.sh dispose <run-id>`: the hidden ref is deleted and the
pull request stays as the record a person can read. Or keep the ref; it is
26 MB, and nobody sees it.
Cleanup is the operator's act, never yours. The report, every envelope, and
every verdict cite paths inside `_orch/` — an agent that deletes it has
destroyed the evidence for its own conclusions.
---
## 6. If you are resuming
A baton run has no memory that matters and no context worth preserving. Read
`manifest.json`, scan `nodes/*/status.json` and `verify/*.json`, and continue.
Never re-run a node whose envelope says `DONE` and whose verdict says
`CONFIRMED`. Never re-plan a graph that exists. **Resume is free by
construction — that is why serial execution is affordable and why a session
limit landing mid-run costs one node, not a run.**
---
Begin: confirm `TARGET` and `MODE`, resolve your base per §2.1, read
`{BATON}/prompt/CONTRACT.md` and your mode file, create `_orch/`, then cast and plan.
Its first instruction is to read two
more files — prompt/CONTRACT.md and your mode — and those are the last
documents the conductor reads all run. Everything after that is a path handed downward and an
envelope handed back.
12 — For a team
One more line. Three things move; the run does not.
The instinct is to put a team's run in GitHub Issues. The numbers say no: one run writes
about 3,500 state files and ledger rows, and GitHub allows 500 content-creating API calls an
hour. Split GitHub into its three primitives instead and each piece of the run has an obvious
home. Git carries the record on a ref nobody sees; one pull request carries the product as a
commit per node, and the ~25 moments a run needs a person as comments. What a run leaves on
your repository is what a colleague's work leaves: one pull request, one branch, commits.
THE RECORD
Git holds the run.
_orch/ is pushed at every node close and gate to
refs/baton/run/<id> — a ref GitHub lists nowhere, not a branch. Still
local disk, still every path a rule names — and every path a verdict cites gains
/blob/<sha>/…, so the evidence outlives the laptop and any machine
resumes with a fetch. Invisible in the UI; one command to delete.
THE DOORBELL
Issues hold the questions.
Every blocked question is a comment on the run's pull request. Anyone on the repository
answers with /answer Q-<n> … — from a phone, in a meeting. At
the next gate the answer is copied into Q-<n>.answer.md under a provenance
block, and the run reads the file exactly as it always did. Every gate posts its summary and
its decisions on the same thread. No Issue per question, no label.
THE DIFF
Pull requests hold the product.
A node that writes code lands as one commit on the run's branch — the pull request
— with its node id in the trailer and its computed verdict as the check
baton/verify on that commit: green, red, or pending, linking to the rows that
decided it. The commit is the landing, so nothing can die with a worktree, and the merge node
the plan names is merging the one pull request. A reviewer reads N commits, the way they read
anyone's branch.
STAYS ON THE LAPTOP
The node that is running.
Its work/ and the agent's own context. Everything else is a checkout of the
ref. One structural change made this safe: every append-only list — the ledger first
— is now a directory of rows, one file each, so no two writers ever share a path and
nothing needs a merge protocol. That change is the one breaking change in v4.0, and it costs
a run in flight one command.
ONE-TIME SETUP
Configuration, not code.
gh authenticated on the machine that runs the prime; the tools on disk
(git clone, then BATON: ./baton); a private target repository, or
a private RUNS_REPO. Then tools/github-setup.sh --apply: one ruleset
on baton/** that blocks force-pushes and deletions of run branches. That is all
— no labels, no Pages, no environments. A secret scan gates every push.
DOES NOT CHANGE
Everything the run thinks.
The tiers, the envelope, the digest, the graph, the verifier, the gates — the same
48 rules, and all ten modes. With the line absent, a run is byte-identical to
a single-user run. Every team tool is proven without touching GitHub:
tools/test-team.sh runs the lot against throwaway repositories and a fake
gh, thirty checks, no network.
what a gate does under TEAM · rule 8
# before the prime reads the inbox
python3 tools/inbox-gh.py sync questions out as comments, answers in to files
python3 tools/lists.py derive the four list files from their rows
tools/publish-run.sh publish secret scan, commit, push the hidden ref
python3 tools/inbox-gh.py post-gate the sixty-line index and the decisions, one comment
Point it at the folder everyone is afraid of.
Your flakiest module. Your most ignored spec. The migration nobody wants to start. The worst
case is a written plan, a tier histogram, and a batch of good questions — with every
attempt, every verdict and every decision on the record.