# Kanban boards

> Page: https://docs.plotwork.dev/kanban-boards. Index of every page: https://docs.plotwork.dev/llms.txt

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](#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

```text
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.
```

```text
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.

**Diagram source**

```diagram
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"
}
```

*Picture: Release 2.4: 7 cards in 4 columns. Work for the 2.4 release: two cards wait, two are in progress, and the in-progress column is at its limit.*

**Text description**

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

**Diagram source**

```diagram
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
}
```

*Picture: Incident 4521 follow-up: 6 cards in 4 columns. The actions from the checkout outage review, by owner and priority. The column in progress is at its limit.*

**Text description**

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

**Diagram source**

```diagram
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
}
```

*Picture: Hiring: platform engineer: 6 cards in 4 columns. Candidates by stage. Names are the people who own the next step.*

**Text description**

**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](https://docs.plotwork.dev/migrating-from-mermaid.md) 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.

```mermaid-source
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:

```plotwork
kanban
column 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](https://docs.plotwork.dev/writing-diagrams.md) | The rules every kind shares |
| [Examples to copy](https://docs.plotwork.dev/examples.md) | Finished diagrams with the prompt that gets an agent to write each one |
| [Migrating from Mermaid](https://docs.plotwork.dev/migrating-from-mermaid.md) | Convert existing Mermaid diagrams, and what is dropped |
| [Swimlane diagrams](https://docs.plotwork.dev/swimlane-diagrams.md) | Steps of a process in lanes by who does them |
| [Gantt charts](https://docs.plotwork.dev/gantt-charts.md) | The same work along a calendar |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every kind, option and diagnostic |