Hand a kanban column to a coding agent

A board in Cydonia is cards in columns, kept as files in the project. Since 0.2.0 a card or a whole column can be sent to a coding agent's session, and the agent reports back on the board itself: it tags the cards it is working on busy and moves them when they are done. Here is the whole loop, from an empty board to a column worked through.

Before you start

Open Settings › Features (⌘,) and turn on sessions, then install an agent from Settings › Agents. Boards are on in a fresh install; sessions are not, and ▶ does not appear until they are.

Then open Settings › MCP. Serve is on by default, and it is what gives the sessions Cydonia runs its tools. Agents may edit is off by default, and with it off an agent can read a board and not change it: the tools that tag a card busy, move it or set its blockers are left out of the agent's list. Turn it on for this tutorial. Agents may delete can stay off; nothing here deletes anything.

Make a board

File › New Board asks for a name and a key. The key is what the cards' handles are made from: a board keyed DEV numbers its cards DEV-1, DEV-2 and so on, and those handles are how you, an article or an agent name a card.

Add a column adds a lane. Make the stages the work goes through, say Todo, Doing and Done. A card's column is the whole of its status: a finished card is one moved to the column that says so.

Write the cards

Add a card at the foot of a lane opens the editor. A card is Markdown. Write each one as a unit of work an agent can finish on its own: what to change, where, and how to tell it is done. An agent reading the board sees each card by its handle and first line, so put the summary first.

Click a card to read it whole in the drawer at the foot of the pane. The pencil there edits it; Enter inserts a newline, and ✓ or ⌘Enter saves.

Describe the board

A board can carry a description: a guide for working its cards that every agent reads. Right-click the board's tab, or open ··· in its band, and choose Add description; it opens in the drawer. Put there what holds for every card: the commands that check a change, the column a finished card goes to, what to leave alone.

An agent gets the description first whenever it reads the board with board_read or a card with board_read_card, so it does not need repeating on each card.

Say which cards wait on which

Some cards cannot start until others are finished. Open the card that waits and click under its head to pick the cards it waits on. A blocker can be on any board of any open project: it is written DEV-12 in the same project and foo#DEV-12 in project foo.

A card with blockers shows blocked, and stays that way until they are taken off it or the card it waits on is deleted. A blocked card cannot be sent to a session.

Send the column

Hover a column's heading and press ▶. The menu lists the session that last held the card, then the project's sessions most recently used, then New session. Pick one.

What goes to the session is a link to each card in the column that is neither busy nor blocked, under the column's name. Cards that are busy or waiting on others are left out, and sending the column again sends whatever in it is neither at that moment. ▶ on a single card sends that card alone.

The session you picked is written down on each card as the one that last held it.

Watch the busy orbs

The board stays up while the agent works. A card the agent is on shows a busy orb. Hover the orb to see the session's name, or click it to open the session and follow the work in its transcript.

To keep the board and the session on screen together, drag the session's tab onto the edge of the pane to divide it, and step between the panes with ⌃⇥.

What the agent does

The agent works the cards through Cydonia's MCP tools. A session Cydonia runs is told its project, so its calls leave the project argument out.

• board_read and board_read_card read the board's description and the cards. board_read_card answers each card's whole text, its column, whether it is busy, the cards it waits on, the cards waiting on it and the session that last held it.
• board_set_card_busy tags a card busy, or several in one call. The tool asks the agent to tag a card before starting on it and take the tag off when the turn is over. Tagging from a session also links that session to the card, which is the session the orb opens.
• board_move_card carries a card, or several, to another column, another board or a board in another project. Its answer names the cards waiting on each card it moved, as DEV-1 blocks DEV-3, DEV-4.
• board_set_card_blockers replaces a card's list of blockers; an empty list clears it.

Moving a finished card to Done does not take it off the cards that wait on it. The move's answer names them, so the agent, or you, can clear their blockers with board_set_card_blockers and send them on.

Run it again

When the turn is over, the board is the status of the work: the cards the agent finished are in the column it moved them to, its busy tags are off, and a card that was waiting is either still blocked or free to send. Press ▶ on the column again to hand over what is left.

See Running several agents and Boards and tables for the rest, and MCP for every board tool.