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 checker | Checks the work for vulnerabilities | No |
| Creative head, Feasibility gate | Propose ideas and judge them, for boards that generate their own work | No |
You can also write your own custom bubble: its inputs, outputs, purpose and what it is allowed to do. And there is a Wait bubble, which runs no agent and holds a loop until something happens, such as another loop finishing or a card arriving.
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 never routes to a fixer.
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-ring is a detour. It hangs off a loop at a junction bubble and is entered on a condition:
| Condition | Enters when |
|---|---|
| On fail | the previous bubble returned FAIL |
| Vulnerability found | a security check found a problem |
| On pass | the previous bubble returned PASS or PARTIAL |
| Tasks empty | the loop has no work left |
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 but write only inside their own folder. A loop with no writing bubble needs no 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, pressed once, lets the pass in progress finish and then stops. Pressed again, it stops at once.
- Play after a pause carries on where the loop left off.
- A loop only takes Approved cards. 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 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. Fix the cause and press Play.
Rate limits and provider outages do not spend the error caps. A rate-limited loop waits and resumes by itself when the provider says how long to wait; an outage waits for you to press Play.