All pages
Many agents at once · Lesson 2.1 · 12 min
The board is the queue
Cards agents can read, claim and move, and dependencies that order the work.
After this lesson you can write cards an agent can finish without asking you anything, order them with dependencies so work is taken in the right sequence, and have several agents pull from one board without two of them taking the same card.
Time: 12 minutes · Works on: macOS app. Every agent that reaches TRMNLY's tools, including Claude Code over MCP, uses the same board through the kanban_* tools.
One queue, written down
When you run one agent, the queue of work lives in your head and you hand it over one prompt at a time. With several agents, that breaks. You become the scheduler, and every agent waits on you to say what's next.
Move the queue out of your head and onto the board. Each card is a unit of work. The order is written as dependencies, not remembered. Claims say who is on what. Then any agent can ask the board "what can I start?" and get an answer that doesn't depend on you being there.
This lesson assumes you know the board itself from The Kanban board. Here we're concerned with writing it so agents can work it.
Write cards an agent can finish
An agent that picks up a card has nothing but the card. When a fleet worker takes one, its brief is built from the card's title, its notes, its checklist and its labels, and nothing else. If it isn't on the card, the agent doesn't know it.
So a card is a task brief (see Write a task brief), written small.
Title: the outcome, as a command. "Add a --json flag to export", not
"Export improvements".
Notes: the context and the edges. Where the code lives, what's out of bounds, and what "done" means:
Where: src/cli/export.ts and its tests.
Done when: `app export --json` prints the same rows as the table output,
as a JSON array, and `npm test -- export` passes with a new test for it.
Out of scope: changing the table output. Don't add dependencies.
Checklist: the steps you'd check off in review. "Parse the flag", "Write the JSON branch", "Add the test". The agent can tick them as it goes, and you can see how far it got.
Labels: the lane. cli, api, docs. Agents can filter on a label, so
one Claude Code session can take only docs cards.
Size cards to one branch
A good card ends in one branch you can review in one sitting. If you can't imagine the diff, the card is too big. Split it. If a card takes a sentence to do, it's probably a checklist step on a bigger card.
Watch for cards that need a decision. "Choose a charting library and add a chart" asks the agent to make a call you'll probably overrule. Make the decision yourself and write it on the card, or make a separate card to compare the options and report back.
Order with dependencies, not prose
"Do this after the migration" in a card's notes is an instruction nobody enforces. A dependency is enforced: a card isn't ready until every card it depends on is done, and an agent asking for ready work never sees it before then.
A worked decomposition for "let users export their data":
| Card | Title | Blocked by |
|---|---|---|
| #11 | Add an exports table and migration |
none |
| #12 | Write the export job that fills exports |
#11 |
| #13 | Add the GET /exports/:id endpoint |
#11 |
| #14 | Add the Export button to Settings | #13 |
| #15 | Document exports in the API reference | #13 |
On day one, only #11 is ready. When it's done, #12 and #13 are both ready, and two agents can take them at once. The dependencies say where the work can run in parallel, and where it can't.
Claim before you start
A claim is how agents keep off each other's cards. An agent claims a card before working on it. A second agent's claim on the same card is refused and told who holds it. That refusal means "someone got there first", so the second agent should pick another card, not retry.
Claims carry a lease, 15 minutes by default. An agent working a long card renews it. If the agent crashes or its session ends, the lease runs out and the card goes back on the queue by itself. Moving a claimed card into a done column, or archiving it, ends the claim at once.
Unrelated problems become cards
An agent working #12 notices a flaky test in another module. Fixing it there makes the branch about two things. The better habit, and the one TRMNLY's fleet workers are told to follow, is to file it as a new card and carry on. The board grows as agents learn about the code, and your review stays focused.
Do it in TRMNLY
- Give the work its own board if it needs one. Open Tasks from More ▾. If this stream of work should stay apart from the rest, use the board menu's Boards → New Board…. Without a board name, agents work on the board the Tasks tab is showing.
- Have the agent decompose the job. In the Agent tab, give it the
feature and ask: "Break this into cards on the board, one branch each, with
notes that say where, done-when and out of scope, and record which cards
block which." It creates cards with
kanban_add(title, notes, labels, priority and checklist steps) and orders them withkanban_depend. A dependency loop is refused, and the error names the cards in it. - Read every card before anything works it. Open each one with Return or a double-click. Fix titles that aren't outcomes and notes that don't say when it's done. Check Blocked By matches the order you want.
- Turn on the ready filter. Click the bolt button in the filter bar. The
board shows only cards that are unfinished, unclaimed and unblocked. This is
the same rule
kanban_readyand the fleet use, so what you see is what an agent will be offered. - Ask the board what's next. In the Agent tab or a Claude Code session,
ask "What's ready on the board?" The agent calls
kanban_ready, which lists ready cards best first (priority, then board order) and explains an empty answer. "Everything is claimed" and "everything is blocked" are different problems. To keep one agent to one lane, tell it to pass a label, such as only cards labelleddocs. - Have each agent claim before it works. Tell each Claude Code session:
"Take the top ready card with
kanban_claim, work it in your own worktree, and move it to Done when the branch is committed." The claimed card's row shows who holds it. A second session asking for the same card is told it's taken. Each session holds its own claims, so two sessions of the same client still can't take each other's cards. - Add and claim from a plain shell, too.
trmnly task add "Fix the flaky export test" --priority highfiles a card from any pane, andtrmnly task listshows the board. There's notrmnly taskverb for claiming, so a script usestrmnly call kanban_claimand passes a stable handle asas. Eachtrmnlyinvocation is its own connection, andasis how the claim survives between calls. - Watch the queue drain. As cards move to Done, their dependents appear under the bolt filter. A card whose branch has an open pull request is held back. It isn't offered again, and it doesn't unblock its dependents until the PR is merged.
- Feed it from anywhere.
wish_submitturns a request in plain words into ordered cards, after reading the code and the board. It returns nothing, with a reason, if the request is already covered or is really a question. It only creates cards, so a misread wish costs you some cards to delete.
Check yourself
- Each ready card names where the work is, when it's done and what's out of scope.
- The bolt filter shows exactly the cards you expect to be startable.
- Two agents asked for work at the same time got different cards.
- You know why a refused claim means "pick another card", not "retry".
- A problem an agent noticed became a new card instead of part of its branch.
Go further
- The Kanban board — cards, columns, the keyboard and claims
- Kanban reference — claims, leases and every
kanban_*tool - Run a fleet — workers that take ready cards on their own
- Agents that talk — the room where agents discuss the cards they hold
- The trmnly command and scripting — adding cards from a shell