Loops and bubbles
Bubbles
Section titled “Bubbles”A bubble is one agent with one role. Each time the loop reaches it, the bubble makes one pass: it reads what the previous bubble handed on, works (reading files, writing code, running commands, as its role allows) and ends with a verdict.
The roles:
| Role | What it does | May write files |
|---|---|---|
| Architect | Plans the work and its structure | Docs only |
| Planner | Breaks work into cards | No |
| Designer | Writes DESIGN.md and gives the coder a visual direction |
Docs only |
| Coder | Writes the code | Yes |
| Reviewer | Reads the work, runs the visual review for apps with a UI | No |
| Tester | Writes and runs tests | Yes |
| Fixer | Repairs what a review or test found | Yes |
| Documenter | Writes documentation | Docs only |
| Researcher | Looks things up on the web | No |
| Security | Checks the work for vulnerabilities | No |
| Creative, Feasibility | Propose ideas and judge them, for boards that generate their own work | No |
| Subloop | Runs no agent. Opens a Sub-loop and routes into it (see below) | No |
| Wait | Runs no agent. Holds a loop until something happens, such as another loop finishing or a card arriving | No |
| Custom | Your own bubble: its inputs, outputs, purpose and what it is allowed to do | As you set it |
Verdicts
Section titled “Verdicts”Every pass ends in one of four results:
- PASS and PARTIAL are the agent’s own judgement that the work is good or partly good.
- FAIL is the agent’s judgement that it is not. A FAIL can route to a fixer.
- ERROR means the agent never really ran: the provider was down, the model could not answer, a setting is missing. An ERROR from an outage or a missing setting never routes to a fixer. A pass that runs out of steps does.
Drop two bubbles onto each other and they form a loop. Drop more onto the ring to add them. The order around the ring is the order of the passes, and the connections are drawn for you from that order.
A Sub-loop hangs off a Subloop bubble in its parent loop. When the bubble’s condition holds, the parent loop waits while the Sub-loop runs, then carries on where it left off. By default that is when the bubble before it fails: a failed review goes to a Fixer, and the loop picks up again at the Subloop bubble.
The Subloop bubble’s Divert when chooses the condition. Each is shown by its code, with this line under it:
| Divert when | What it tests |
|---|---|
ON_FAIL (the default) |
The step reported a failure |
VULNERABILITY_FOUND |
The step reported a failure, the same test as ON_FAIL, named for a security check |
ON_PASS |
The step passed |
TASKS_EMPTY |
Nothing left in the queue |
The step is the Subloop bubble itself, which runs no agent: it reports a failure while anything before it in the loop is still reporting one, and passes once every failure has been answered.
How often chooses between Every time the condition holds and Once, then stay on the main loop.
Folders
Section titled “Folders”Each loop that writes code owns one folder inside the project, and no two loops may share one. A loop’s bubbles can read the whole project. The file tools always hold a loop to its folder. Its commands are held there by the operating system only with Sandbox agent commands on in Settings. A loop with no writing bubble needs no folder. A Sub-loop writes in its main loop’s folder.
Running
Section titled “Running”Press Play on the board to run every loop, or on one loop to run just that one. Several loops run at once, each in its own lane. Loops share work through the Task Book and the files on disk, not through each other’s conversation.
- Pause lets the pass in flight finish; the button then reads Stop, which stops at once and discards that pass.
- Play after a pause carries on where the loop left off.
- A loop never takes a Draft card; it starts only on Approved ones. Draft is where you review work before any loop starts on it.
Caps and halts
Section titled “Caps and halts”Every loop has three caps, set in its settings:
| Cap | Default | Stops the loop when |
|---|---|---|
| Max loop executions | 100 | it has made this many passes |
| Max errors per step | 8 | one bubble has failed this many times in a row |
| Total loop error cap | 15 | the loop has failed this many times in all |
A loop also stops when a bubble keeps producing the same change, or when there is nothing it can do (for example, every card is still in Draft). A stopped loop says why in a notice, and in its panel on the canvas. A rate-limited loop says so only in its panel. Fix the cause and press Play, which clears the loop’s counters and runs it again from where it stopped.
Rate limits and provider outages do not spend the error caps, unless the loop has Continue on error on. A rate-limited loop waits and resumes by itself when the provider says how long to wait; an outage raises a notice and waits for you to press Play.