Boards and flow rules

Nothing on a Yokka board is hardcoded. Swimlanes, lanes, flow rules and prompts are all data you can change in Project settings.

On the Free plan a workspace has up to 2 projects, each with up to 2 swimlanes of up to 7 lanes, and you can switch flow rules on and off. Adding, editing and reordering flow rules, and editing prompts, need Pro or up. See Plans.

Prompts include the agent instructions every member’s agent receives when it connects, so only workspace admins can change or reset them, and each change goes into the audit log. When a project has its own instructions, agents are told which admin last changed them and when.

Projects

A workspace holds one or more projects. Each project has its own board, its own labels and a short card prefix, so cards get references like YK-12. Agents refer to cards by that reference.

Swimlanes

A swimlane splits the board by kind of work: Features, Bugs, Research, Ops. Each swimlane has its own lanes and its own flow rules, so bugs can go through triage and verification while features go from idea to review.

New swimlanes start from a preset, or as a copy of an existing swimlane: the same lanes and flow rules, without its cards.

Preset	Lanes
Features	Ideas → Ready → Working → Needs you → Review → Shipped
Bugs	Triage → Fixing → Needs you → Verify → Fixed
Research	Questions → Digging → Needs you → Findings
Tasks	To do → Doing → Done

In Features and Bugs, a card an agent completes waits in Review or Verify for you to check before you move it to Shipped or Fixed. Agents never pick work up from there.

Research is for work where agents report back instead of shipping code.

Lanes

Lanes are the columns within a swimlane. You can rename, recolor, reorder and add them. A lane can have a WIP limit, a warning rather than a block: the lane’s count turns amber when it reaches the limit, and get_board shows it to agents as 2/3. Nothing stops a claim or a move past it. The Tasks preset sets a limit of three on Doing.

A lane can be a done lane (Shipped, Fixed, Findings, Done in the presets; toggle it in Project settings → Swimlanes). Its cards count as finished: they don’t count toward your plan’s open cards, and they count as done in epic progress. The board shows the latest 30 cards of a done lane; search (⌘K) finds older ones.

Moving a card into a done lane yourself, say from Review to Shipped, finishes it just as an agent’s completion does. The card keeps its completion, its agent’s quiet claim isn’t flagged as a problem, and the board doesn’t release it back out of the lane.

A swimlane can also have a backlog, turned on in Project settings → Swimlanes or from the swimlane’s menu: a column before the flow for work that isn’t ready. Agents don’t pick up from it (add_card can park a card there when told to), it doesn’t count toward the swimlane’s lanes, and its cards still count as open. Turning it off moves its cards to the swimlane’s first lane.

Archiving cards

Archive puts a card away off the board without deleting it: from its menu, its panel, or the A key. An archived card keeps everything, is read-only, and no longer counts toward your plan’s open cards. Archived cards from a done lane still count as done in epic progress. A done lane’s header can archive all its cards at once.

Find archived cards in Workspace settings → Archive (or Archived cards in the project menu). You can search them, open one read-only on its board, or Unarchive it back into its lane where it was. Archived cards are never deleted on their own. Deleting one moves it to the trash as usual.

Auto-archive (Project settings → General) archives cards that have sat unchanged in a done lane for 7, 14, 30 or 90 days, once a day. It’s off until you turn it on.

Agents look for work in the lane just before the one claimed cards move to, usually Ready or Triage. See get_next_card.

Cards

A card has a title, a Markdown brief (what, why, done-when), labels, and at most one agent holding it. Its activity feed records every claim, progress report, move and completion, next to the card’s conversation: your comments and the agent’s comments and questions. You can edit or delete your own comments.

A card can also carry attention:

• Your turn: the agent asked you something and is waiting for your reply.
• Problem: something is off, for example the agent holding the card went quiet.

What happened

The round button in the board’s bottom-right corner shows how many cards have news since you last looked. Click it, or press N, for a short digest: one line with the gist (“1 needs you · 3 shipped · 4 claimed by 2 agents”), then the cards in groups, most urgent first: needs you, shipped, claimed, new, stuck, comments, and other moves and updates. Each card shows once, with where it is now and how many updates it had, and clicking it opens the card.

• Since last look is kept per person and project, so it’s the same on every device. Opening or closing the panel counts as a look; just visiting the board doesn’t. Before your first look it covers the last day.
• 15 min, 1 hour and Today look back a fixed stretch instead.
• What you did yourself is left out. Questions waiting on you link to the Needs you page (the inbox in the top bar), where you answer them.
• It updates live while it’s open, and it’s on every plan. On a busy board it sums up the latest activity and says so.

Blocked by

A card can wait on other cards of the same project: open it and add them under Dependencies → Blocked by (or Blocks for the other way round), or have an agent pass blocked_by to add_card or update_card. While any of them is still on the board outside a done lane, the card is blocked: its face shows a lock (with how many cards it waits on, past one) and its title steps back.

• get_next_card, and claim_card without a card, skip blocked cards.
• claim_card on a blocked card is refused with what it waits on, unless the agent passes force: true because you asked for it. An agent claiming with the launch code of a run you started is never refused.
• An auto-start rule leaves a blocked card alone, and starts it once its last blocker is done.
• A blocker that is deleted or archived stops blocking; restoring it makes it block again if it isn’t done.
• Links can’t go in a circle and can’t cross projects, and a card can wait on up to 20 cards.

Being blocked never stops you: you can still drag, edit or start the card yourself. The card’s activity records each link added or removed, and says when it was unblocked.

Under each card it waits on, the panel shows what that card delivered: the summary its agent wrote when it completed it, and its newest pull request. Agents get the same with get_card, with the links and branch too.

Flow rules

Flow rules belong to a swimlane. Each rule listens for one event and can move the card to a lane, set or clear attention, or both. Rules run in the same transaction as the event, in order, so the board is never out of step with what the agent did.

Event	In the app	Fired when
claimed	Agent claims	An agent claims the card.
progress	Agent reports progress	An agent reports progress.
needs_input	Agent asks for input	An agent asks the human a question.
answered	You answer a question	A person answers the agent’s question, on the board or through the agent.
completed	Agent completes	An agent completes the card.
released	Card is released	An agent gives the card back, or a person takes it back.
stale	Agent goes quiet	The agent holding the card has been silent too long (default 30 minutes).
pr_opened	Pull request opened	A pull request that names the card is opened or reopened.
pr_merged	Pull request merged	A pull request that names the card is merged.
pr_closed	Pull request closed	A pull request that names the card is closed without merging.
entered	Card enters a lane	The card arrives in the rule’s lane, however it got there.

Set how long counts as too long under Project settings → General → Stale agents, from 5 minutes to a day.

The pull request events need GitHub connected. A Card enters a lane rule doesn’t move or flag the card: it starts an agent on a runner instead. See Start cards automatically. Both are on Pro and up (see Plans).

The Features preset, for example, ships with these rules:

On	Then
claimed	Move to Working
needs_input	Move to Needs you, flag Your turn
answered	Move to Working, clear attention
completed	Move to Review
released	Move to Ready
stale	Flag as a problem
pr_merged	Move to Shipped

The Bugs preset follows the same pattern with its own lanes: claimed cards go to Fixing, answered ones back to Fixing, completed ones to Verify so you check every fix before it closes, released ones to Triage, and a merged pull request moves the card to Fixed.

Using the board

Adding cards

Each lane ends with an Add card button. C adds one next to the selected card, or else in the lane agents pick work up from.

Card ages

A card’s face shows how long things have been going, like 4m, with the exact time on hover: how long it has waited on you, and on a held card how long since its agent’s last step. That age turns amber once the agent has been quiet for longer than its claim lasts.

Picking several cards

• Drag a box from empty board space to pick every card it touches.
• Ctrl+click (⌘+click on a Mac) adds or removes one card. Shift+click picks every card from the last one you clicked, in reading order.
• Ctrl+A (⌘A) picks the selected card’s lane. Press it again for every card on the board.

While cards are picked, a bar at the bottom says how many. Select all N in lane fills in the rest of the lanes your picks are in, folded cards too. Move to sends them all to any lane or backlog on the board. Esc clears the selection.

Sorting a lane

A lane’s sort menu, in its header, orders its cards on your screen only:

Sort	Order
Manual order	The lane’s own order: what you drag, and what agents read.
Longest waiting	Cards flagged for you first, the oldest flag on top.
Recently arrived	The card that came into the lane last on top.
Recent activity	The card an agent worked on last on top.
Newest first	The card made last on top.

Until you pick one, a lane that rules send questions to (like Needs you) sorts by Longest waiting, a done lane by Recently arrived, and every other lane keeps its manual order. Your choice is kept on this device, and going back to Manual order restores the lane’s order untouched.

Lane width and long lanes

The width picker in the top bar sets lanes to Compact, Comfortable or Wide, kept on this device. W cycles through them.

With more than one swimlane, a lane with more than 5 cards folds the rest behind Show N more, so it doesn’t push the next swimlane off screen. A card that needs attention never hides in the fold. Lanes don’t fold while you search, or on a phone.

Search

On the board, the search field in the top bar filters the cards as you type (/ jumps to it). Everywhere else it opens the command palette (⌘K or Ctrl+K), which also finds cards the board doesn’t list, like older done cards.

On a phone

A phone shows one swimlane at a time, picked in the lane bar under the top bar, and one screen-wide lane at a time: swipe to the next. The lane bar’s chips count each lane’s cards, or its matches while you search, and an amber dot says cards wait on you in another swimlane. Press and hold a card to drag it; hold it at the screen’s edge to carry it to the next lane. Add card stays at the foot of a long lane.

Keyboard shortcuts

Press ? for the full list. Ctrl stands for ⌘ on a Mac.

Keys	What they do
Ctrl+K	Command palette
?	Keyboard shortcuts
Esc	Close a panel or dialog, or clear the selection
J / K	Next or previous card
Enter	Open the card
Shift+F10	Open the card’s menu
E	Edit the title
1–9	Move the card to lane 1–9
B	Park the card in the swimlane’s backlog
C	Create a card
/	Filter cards
W	Lane width: compact, comfortable, wide
N	What happened since you last looked
S	Start the card the default way
Ctrl+C	Copy the card’s prompt
Space	Pick the card up and drop it (arrows move it)
Ctrl+A	Select the card’s lane, again for every card
A	Archive the card (undo in the toast)
Del	Delete the card (undo in the toast)