bro flow convoy
Intentional group planning — a molecule's needs-DAG executed by claiming steps.
bro flow next is grab-anything mode: the top ready bead, whoever gets there
first. A convoy is the opposite — planned group work. A molecule
pours a formula into beads: steps are child issues, blocks edges are
the DAG, and every agent works the graph through convoy next/done
instead of freelancing the backlog.
A convoy survives session restarts, compaction, and parallel agents —
all state lives in beads, so bro flow convoy status reconstructs
everything.
Running a convoy
bro flow convoy pour <formula> [--var K=V]… → molecule root id
bro flow convoy next → what to do now (step / gate / blocked / complete)
bro flow convoy claim <step> → atomic lease — refused if another agent holds it
bro flow convoy done <step> --result "…" → close it, emit the new nextRepeat next → claim → work → done until next reports
"state": "complete". --result is the handoff future steps read —
write what the next step needs, not a diary.
Commands
| Command | What it does |
|---|---|
bro flow convoy pour <formula> | Instantiate a formula as a molecule |
bro flow convoy status [mol] | The DAG — ✓ done / ◐ in progress / ▸ ready / · blocked |
bro flow convoy next [mol] | Scheduler as code — the next executable step as JSON |
bro flow convoy claim <step> [--mol ID] | Atomic claim before starting — required with parallel agents |
bro flow convoy done <step> --result T [--mol ID] | Close the step, hand the result downstream |
bro flow convoy list | Open molecules in this workspace |
bro flow convoy run — the molecule queue
run is the bro-native runner: it drives each molecule to complete,
spawning a worker agent per ready step instead of doing the work in this
session.
| Command | What it does |
|---|---|
bro flow convoy run <mol>… | Run each molecule to complete, one at a time |
bro flow convoy run --open | Every open molecule, in pour order |
--attempts N | Per-molecule attempt cap (default 4) |
--poll SEC | Agent-state poll interval (default 15) |
--retry-delay SEC | Spacing between crash retries (default 60) |
--json | One JSON verdict line per molecule |
With several open molecules, pass --mol <id> — no-arg resolution errors
on ambiguity rather than guessing.
Human gates
A type = "human" step is a gate — it exists to stop the machine.
next reports it as gate and surfaces every ready gate in gates[];
the convoy waits there for a person, not for an agent to improvise an
answer.
Declaring convoys
Formulas are TOML — formulas/*.formula.toml — with steps, needs
edges, and agent/human types. A kind = "convoy" plan
pours several molecules at once under one gate policy (gates = "forbid"
rejects any human gate — the unattended-run contract).
kind = "convoy"
[[molecules]]
formula = "ship-bead"
[molecules.vars]
bead = "bro-1234"