Agents

An agent is what a worker runs. Not a setting, not a mode: an ordered list of things to do and things to check, which you compose yourself or pick off a shelf.

Before this existed, a worker did one thing — write the change, then run six checks in a fixed order, then push and open a pull request. That is still what the default agent does. The difference is that it is now written down somewhere you can read, copy and change, instead of being the shape of the code.

Open Agents from the bottom of the sidebar.

Steps and gates

Two kinds of block, and the difference between them is the whole design.

A step does work. It is a separate call to the coding model, in a fresh session, with its own prompt, its own model and its own answer to what may this touch — or it is something the worker does itself, without any model: push the branch, open the pull request, merge it.

A gate refuses. It cannot change anything; it looks at what is there and either lets the run continue or stops it and hands the task to a person.

A step cannot refuse and a gate cannot write. That boundary is what keeps a composition readable: any block that could stop the run is a gate, and you can see all of them at a glance.

Why a step is its own session

The review gate has always been a second model with no memory of writing the code, because a model that has just spent forty minutes on a change is the worst possible judge of it. A step generalises that: two steps in one agent share the task and the worktree, and nothing else.

That is what makes analyse, then implement different from telling one model to do both. The second step reads what the first wrote, not what it was thinking.

Buckets

Four of them, read as one list from top to bottom:

Bucket	What belongs there
Analysis	Reading, planning, anything before a line is changed.
Implementation	The steps that write.
Verification	The gates.
Delivery	Push, pull request, merge.

The buckets are labels for the reader, not fences. A gate can sit in Implementation and a step in Verification; the run walks the sequence, and the sequence is every bucket end to end. They exist so that an agent with an empty Analysis bucket still says where analysis would go.

The blocks you start with

Steps

Block	What it does
Implement	Reads the task, makes the change, writes a test for it.
Push	Pushes the branch, so a human can reach the work.
Pull request	Opens the pull request.
Merge	Merges it. Leave it out and a person decides.

Gates

Block	Refuses when	Settings
Size	The change is larger than the limit.	Most lines, most files
Protected files	The change touches files a later step runs, or loads as its own instructions.	—
Test written	Code changed and no test did.	—
Builds	The build fails.	—
Tests pass	The suite fails.	—
Reviewed	A second model reads the change and rejects it.	Looking for, model

Looking for is worth knowing about. A Reviewed gate set to Security asks a different question from one set to Anything wrong, so an agent can carry both and get two genuinely different readings rather than paying twice for the same one.

Every gate’s settings belong to that block in that agent. Two Size gates with different limits are an ordinary thing to compose — a loose one early, a strict one before the merge.

The three shipped agents

Agent	What it is
Default	Exactly what a worker did before agents existed: write the change, every check, push, pull request.
With security review	The same, plus a model reading the change for security before delivery.
Merges its own work	The default, and it merges the pull request once every check has passed.

None of them runs until somebody picks it for a task — see Where an agent comes from.

Merging is a step, not a switch

There used to be a Merge automatically setting, and a rule that refused to let you have it without the review gate. Both are gone.

An agent merges because its sequence carries a Merge step. Nothing else decides. If you want a project to merge its own work, give it an agent that ends with Merge; if you do not, leave the step out and the run stops at the pull request.

The same fact is shown where an agent is chosen: on a task, the picker marks every agent with a Merge step Merges without a person, beside the description you gave it. Write that description for the person picking — what the agent does and where it stops.

The same goes for review: a change is reviewed because a Reviewed gate stands after the last step that writes. Not because a box is ticked.

This is a deliberate trade. A flag beside the composition would describe the same decision twice, and when the two disagreed the flag would win silently — you would be reading a sequence that is not what runs. Now what you see is what happens.

What that costs: an agent that merges without a review is composable, and the editor marks it clearly as risky rather than refusing to save it. The judgement is yours, and it is visible.

What the editor will not let you save

Some orders cannot mean anything, and are refused outright:

• Merge with no pull request before it. There is nothing to merge.
• A pull request on a branch that was never pushed.
• A writing step with no push after it. The work would sit in a worktree on somebody’s laptop where nobody can reach it.
• Builds or Tests pass over a change that Protected files has not read. Both run the repository’s own scripts, so a script the agent just wrote would execute before anything checked whether it was allowed to write it. Put a Protected files gate after every step that writes and before either of them.
• Anything after Merge. It judges a change that has already landed: it cannot stop it, and the board would report a merge as blocked for work that is on the base branch.

The last two are the interesting ones. They were guaranteed by the old fixed order — nobody could get them wrong because nobody could change them. Composing the order is what put them at risk, so they are now rules you can read rather than properties of the code.

What you may edit

The editor shows the palette, the drag handles, the remove buttons and Save only on an agent you may actually change:

• your own personal agents;
• a project’s agents, if you administer that project;
• the global ones, including the three shipped, if you administer the instance.

Everything else opens read-only. The controls are withheld rather than offered and refused afterwards — otherwise you could spend a minute rearranging an agent’s gates and discover on pressing Save that it was never yours to change. The catalog one screen up withholds its actions the same way.

Nothing you place is kept until you press Save, although a step appears in its phase the moment you add it. While there is something unsaved, Unsaved changes shows beside the button, and leaving asks first — a link, a task opened from search, signing out, a reload or a closed tab. The browser’s Back button is the exception: it cannot be held.

An agent with no steps

A new agent starts empty, and the editor saves it that way. That is on purpose: composing one is not something to finish in a single sitting, and a half-built agent is a draft rather than a mistake.

An empty agent is refused at the point it would matter — putting it on a task:

“Nightly sweep” has no steps in it yet, so a machine handed this task would have nothing to run. Add at least one step to it first.

The one case that gets past that is an agent emptied or deleted after a task already named it, or one naming a block this instance does not have. There the worker claims the task, finds nothing to run, and hands it straight back — spending an attempt rather than refunding it. After three the task is parked in the escalation column, where a person sees it. Spending the attempt is what bounds it: refunded, the task would return to the head of the queue, sort first again thirty seconds later, and every other claimable task on the board would wait behind it indefinitely.

Composing one without a mouse

Every block in the palette carries an Add button, which puts it in the right bucket without a drag at all — the quickest way to compose one, mouse or no mouse.

The order within a bucket is a drag, and the drag works from the keyboard too. Tab to a block, Space or Enter to pick it up, the arrow keys to move it — into a bucket from the palette, or up and down within one — then Space or Enter to drop it, or Esc to put it back. The screen announces each step as you go.

Where an agent comes from

From the task, and nowhere else. A task names an agent or it does not, and one that does not is never picked up: naming an agent is the gesture that hands the work to a machine, so a task without one is a task somebody is doing by hand.

There is no falling back. The project’s default is not consulted when the run starts, and neither is the shipped Default — a claim on a task that names no agent resolves to nothing and stops there.

What the project’s default is: the agent the picker offers first when you choose one on a task. A suggestion at the moment of choosing, which you can change, and which has no say afterwards.

Two rules narrow it further, and both are checked again where the work is picked up rather than only where it was chosen:

• A project agent runs only on that project’s tasks, whichever way it was chosen.
• A personal agent runs only on its composer’s machine. Somebody else’s machine refuses it and says so, rather than running a composition its owner never saw.

Both are refused when you try to save them, not silently later. A project agent on another board’s task, or somebody else’s personal agent, gives That agent cannot run on this project. Your own personal agent on a task assigned to a colleague gives A personal agent only runs on your own tasks. Assign this task to yourself, or pick one of the project’s agents — anybody may compose a personal agent, so the rule keeps an unvetted composition off a machine that is not its author’s.

The agent is copied onto the run when the task is claimed, not looked up as it goes. Edit an agent while a worker is halfway through it and that run finishes as the agent it started as — a run has to mean what it meant when it began.

What the worker keeps for itself

A block carries a prompt, a model and its settings, and all of those travel from the board to the machine. One thing never does: what a step may touch.

A step says Read only or Read and write, and the worker turns that into a tool list of its own. A read-only step cannot be given the ability to write by anything anyone types into the board, because the list is not a thing the board can express.

The same holds for gates. A gate’s kind names behaviour the worker implements; the board sends parameters, never commands. An agent naming a kind the machine does not implement stops the run and says so, rather than skipping it — a missing check looks exactly like a check that passed.