Kanban boards
A kanban board shows work as cards in columns by stage, so a reader sees at a glance what is waiting, what is in progress, and what is done, who owns each piece, and where a stage holds more than it should. Use it for a sprint or a release in a status update, an incident's follow-up actions, or a hiring pipeline. It is for anyone reporting the state of work, and for an agent asked to summarise a tracker.
TL;DR
| Question | Answer |
|---|---|
| What is it for? | Work in stages: a sprint, a release, incident actions, candidates in a pipeline. |
| How do I start one? | Write kanban "Title", then a column block for each stage with a card line for each piece of work inside it. |
| What goes on a card? | A title, and optionally owner=, ticket=, priority=, tags=, a sub= note, a tone=, and an icon=. |
| What is a limit? | limit=3 on a column is its work-in-progress limit: the heading shows 2 / 3, and turns amber when the column holds more. |
| What does Mermaid convert? | kanban: columns, tasks, and each task's assigned, ticket, and priority. See From Mermaid. |
| How big can it be? | At most 16 columns and 300 cards. Warnings start at 8 columns or 15 cards in one column. |
Ask your agent
Use Plotwork to draw a kanban board of the 2.4 release: To do, In progress (limit 2), In review and Done. Put each ticket on a card with its owner, its ticket key and its priority.Use Plotwork to draw the follow-up actions from the checkout incident review as a kanban board, with an owner and a priority on each action and a limit of two on the column in progress.Example
A release board. The column in progress is at its limit of two, so its count reads 2 / 2; one more card would turn its heading amber.
kanban "Release 2.4" desc="Work for the 2.4 release: two cards wait, two are in progress, and the in-progress column is at its limit."
column todo "To do" icon=lucide:clipboard-list { card notes "Write the release notes" owner="Ann Lee" ticket="REL-212" priority=medium card perf "Profile the parser on large files" ticket="REL-219" priority=low tags="parser, performance"}column doing "In progress" tone=blue limit=2 icon=lucide:loader { card export "PNG export endpoint" owner="Ben Ortiz" ticket="REL-204" priority=highest tags="api" card sso "Okta sign-in" owner="Cara Diaz" ticket="REL-207" priority=high}column review "In review" tone=violet icon=lucide:eye { card fit "Text never touches a box edge" owner="Dev Patel" ticket="REL-199" priority=high}column done "Done" tone=green icon=lucide:circle-check { card icons "Icon shards" owner="Ann Lee" ticket="REL-190" card cli "Command line 0.2" owner="Ben Ortiz" ticket="REL-188"}To do (2 cards):
- Write the release notes (REL-212): owner Ann Lee; medium priority.
- Profile the parser on large files (REL-219): low priority; tags parser, performance.
In progress (2 cards, limit 2):
- PNG export endpoint (REL-204): owner Ben Ortiz; highest priority; tag api.
- Okta sign-in (REL-207): owner Cara Diaz; high priority.
In review (1 card):
- Text never touches a box edge (REL-199): owner Dev Patel; high priority.
Done (2 cards):
- Icon shards (REL-190): owner Ann Lee.
- Command line 0.2 (REL-188): owner Ben Ortiz.
An incident follow-up
Actions from a review, by owner and priority. The column in progress is at its limit of three; a fourth card would turn its heading amber, and lint would warn that the team is taking on too much there.
kanban "Incident 4521 follow-up" desc="The actions from the checkout outage review, by owner and priority. The column in progress is at its limit."column new "New" icon=lucide:inbox { card alert "Alert on queue depth, not only on errors" owner="Mo" priority=highest tags="monitoring" card runbook "Runbook for a stuck payment worker" priority=high}column doing "Doing" tone=blue limit=3 icon=lucide:loader { card dash "Checkout dashboard per region" owner="Priya Shah" ticket="OPS-88" priority=high icon=lucide:chart-line card retry "Retry budget on the payment client" owner="Tom" ticket="OPS-91" priority=medium tone=amber card load "Load test at twice the peak" owner="Priya Shah" ticket="OPS-93" priority=low sub="Book the staging cluster first"}column blocked "Blocked" tone=red icon=lucide:pause {}column done "Done" tone=green icon=lucide:check { card status "Status page wording" owner="Mo" ticket="OPS-80" priority=lowest}New (2 cards):
- Alert on queue depth, not only on errors: owner Mo; highest priority; tag monitoring.
- Runbook for a stuck payment worker: high priority.
Doing (3 cards, limit 3):
- Checkout dashboard per region (OPS-88): owner Priya Shah; high priority.
- Retry budget on the payment client (OPS-91): owner Tom; medium priority.
- Load test at twice the peak (OPS-93): owner Priya Shah; low priority; Book the staging cluster first.
Blocked (0 cards): no cards.
Done (1 card):
- Status page wording (OPS-80): owner Mo; lowest priority.
A hiring pipeline
Stages of a pipeline as columns, with the person who owns the next step on each card.
kanban "Hiring: platform engineer" desc="Candidates by stage. Names are the people who own the next step."column applied "Applied" icon=lucide:file-text { card c1 "Candidate 14" tags="referral" card c2 "Candidate 15"}column screen "Phone screen" icon=lucide:phone limit=3 { card c4 "Candidate 11" owner="Rae" priority=high card c5 "Candidate 12" owner="Rae"}column onsite "Interviews" tone=violet icon=lucide:users { card c6 "Candidate 9" owner="Jon Bell" sub="Systems design on Thursday"}column offer "Offer" tone=green icon=lucide:handshake limit=1 { card c7 "Candidate 4" owner="Head of platform" priority=highest}Applied (2 cards):
- Candidate 14: tag referral.
- Candidate 15.
Phone screen (2 cards, limit 3):
- Candidate 11: owner Rae; high priority.
- Candidate 12: owner Rae.
Interviews (1 card):
- Candidate 9: owner Jon Bell; Systems design on Thursday.
Offer (1 card, limit 1):
- Candidate 4: owner Head of platform; highest priority.
The language
The header
kanban "Title" starts the board. desc= is the plain-language description, for assistive technology.
Statements
| Statement | Meaning | Example |
|---|---|---|
column <id> "<Title>" { | A column, with its cards inside and } on its own line. | column doing "In progress" limit=3 { |
card <id> "<Title>" | A card, inside a column, in the order written. | card api "Export" owner="Ben" |
desc "<text>" | The description, the same as desc=. | desc "Work for 2.4." |
Columns and cards share one set of ids, so a card cannot have the id of a column.
Columns and limits
| Option | Values | Meaning |
|---|---|---|
tone= | any tone | Washes the column, and its heading a step stronger. |
icon= | any bundled icon | Drawn before the name in the heading. |
limit= | a whole number | The work-in-progress limit. The heading counts the cards against it, and a column over it has an amber heading and a warning. |
A column with no cards shows a dashed "No cards" slot. Every column is as tall as the tallest, so the board reads as one block.
Cards
| Option | Values | Meaning |
|---|---|---|
owner= | text | Drawn at the bottom right as the name and a round badge of initials. A person has the same colour wherever they appear. |
ticket= | text | The ticket key, at the bottom left. |
priority= | highest, high, medium, low, lowest | A mark before the ticket: chevrons up in red and orange for urgent work, two amber bars for medium, chevrons down in blue and grey for work that can wait. |
tags= | "api, export" | One line after a tag icon. |
sub= | text | A note under the title. |
tone= | any tone | Tints the card's outline. |
icon= | any bundled icon | Drawn before the title. |
A title wraps to three lines and a note to two. When the owner does not fit beside the ticket, they take a row of their own. Text that is still too long is cut with warning W203; the full text stays in the text description.
Ticket links
A Plotwork picture is a static image with no links inside it, so a ticket is drawn as text. Link the tickets in the text around the board if readers need them.
Limits and warnings
| Limit | What happens |
|---|---|
| More than 16 columns or 300 cards | Refused with E140 before any layout. |
| A column over its limit | W200 at the column. |
| More than 8 columns, or 15 cards in one column | W200: a board that long is a backlog. Draw the work in play. |
| The same ticket on two cards | W200. |
| A board with no cards | W200. |
| Text cut to fit | W203. |
From Mermaid
Mermaid kanban converts to a kanban board. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full. Indentation is the structure: the lines as far in as the first are columns, and the lines indented under a column are its cards.
kanban todo[To do] docs[Write the release notes] perf[Profile the parser]@{ ticket: REL-219, priority: 'Low' } doing[In progress] export[PNG export endpoint]@{ assigned: 'Ben', ticket: REL-204, priority: 'Very High' } done[Done]The converter writes a block for each column and a card for each task, with its details as options:
kanbancolumn todo "To do" { card docs "Write the release notes" card perf "Profile the parser" ticket="REL-219" priority=low}column doing "In progress" { card export "PNG export endpoint" owner="Ben" ticket="REL-204" priority=highest}column done "Done" {}| Mermaid | Plotwork | Report |
|---|---|---|
kanban | kanban "<title>" | none |
Front matter title: | The header title | none |
id[Title] at the first indent, or [Title], or a bare word | column id "Title" { | none |
id[Text] indented under it | card id "Text" | none |
@{ assigned: 'x' } | owner="x" | none |
@{ ticket: X } | ticket="X" | none |
@{ priority: 'Very High' } | priority=highest | none |
| A node with no id | An id made from its text | none |
| An id used twice | Numbered | M206 |
Other @{ } keys, an unknown priority, details on a column | Dropped | M203 |
| HTML in a title | Removed | M205 |
Front matter config:, such as ticketBaseUrl | Dropped | M200 |
| More than 16 columns or 300 tasks | Nothing is converted. | M102 |
| A line that cannot be read | Nothing is converted, or the line is skipped when the conversion is lenient. | M110, or M218 |
See also
| Doc | Why |
|---|---|
| Writing diagrams | The rules every kind shares |
| Examples to copy | Finished diagrams with the prompt that gets an agent to write each one |
| Migrating from Mermaid | Convert existing Mermaid diagrams, and what is dropped |
| Swimlane diagrams | Steps of a process in lanes by who does them |
| Gantt charts | The same work along a calendar |
| Language reference | Every kind, option and diagnostic |