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.

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, 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.

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:

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

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.

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	Fired when
claimed	An agent claims the card.
progress	An agent reports progress.
needs_input	An agent asks the human a question.
completed	An agent completes the card.
released	An agent gives the card back.
stale	The agent holding the card has been silent too long (default 30 minutes).

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

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

On	Then
claimed	Move to Working
needs_input	Move to Needs you, flag for the owner
completed	Move to Shipped
released	Move to Ready
stale	Flag as a problem

The Bugs preset is the same except completed moves the card to Verify, so you check every fix before it closes.