State diagrams

TL;DR

Ask your agent

Say what the states are and what moves the thing from one to the next, then ask for an icon on every state and a color for what each state means. The agent writes the rest.

Use Plotwork to draw the lifecycle of an online order as a state diagram. An order starts as Pending, waiting for payment. A valid card payment moves it to a stock check, and nothing within 24 hours cancels it. If the item is in stock, it is picked and packed in a Fulfilment state and then delivered. If it is sold out, the order is cancelled and the money refunded. Give every state an icon, color the states by what they mean, and add a note that refunds stay open for 30 days.

Use Plotwork to draw the run of an AI agent as a state diagram. The agent plans a step, then runs it with a tool, or waits for a person to approve it when the step is risky. A tool error is retried after a backoff while retries are left, and the run fails when they run out or when a person denies a step. The run is Done when the goal is met. Put an icon on every state, and use green for success, amber for waiting, and red for failure.

Use Plotwork to draw the lifecycle of a subscription as a state diagram. A customer starts a 14 day trial, and is charged when it ends if a card is on file, or cancelled if not. An active subscription renews each period. A failed payment makes it Past due and is retried on days 3, 5, and 7, and after 21 days the subscription is cancelled and access is revoked. Give each state an icon and a tone that shows how healthy it is.

Example

This is the order lifecycle from the first prompt. It shows a composite state with an icon of its own (Fulfilment, with its own start and end), a choice, transition labels that carry an event, a guard and an action, and a note.

PictureSourceOutline

Make it readable

A state diagram reads fastest when the picture says how things stand before anyone reads a word. Four habits do that, and an agent can write all of them in one line per state, as the order lifecycle above does.

Keep a state name to a few words and move detail into sub= or a note: text wider than a card is cut with warning W203. Do not rely on color alone. The name and the icon say the same thing, so the diagram still reads for someone who cannot tell two tones apart. An icon name must exist, so ask search_icons or map_icons for it, and never invent one.

An AI agent run

An agent run shows tones that say how each step is going, a loop back to planning, and guards that choose between two transitions out of one state.

PictureSourceOutline

A subscription lifecycle

A subscription shows a transition from a state to itself (the renewal), several ways into one state (Cancelled), and labels that carry an event, a guard and an action.

PictureSourceOutline

A release pipeline

A release pipeline shows a fork and a join around checks that run in parallel, a choice on the result, and the brand icons of the tools from the simple set.

PictureSourceOutline

A connection that remembers its state

A live connection shows a composite state with a history marker, so a reconnect returns to Idle or Streaming, whichever was active when the network dropped.

PictureSourceOutline

A download with two regions

A download shows regions, two parts of one state that run side by side, and a transition from a state to itself.

PictureSourceOutline

The language

A line is one statement. A # starts a comment. Ids are words such as pending, in-stock or _x, labels are in double quotes, and options are written key=value. The first line is the header.

The header

state "Order lifecycle" direction=right desc="How an order moves from payment to delivery."

Statements

tone= takes neutral, blue, violet, aqua, orange, green, amber, or red, and icon= takes a name from the closed list of icons, such as lucide:play, status:success or simple:github. A diagram cannot set a color: the theme chooses every color, in light and dark. Make it readable says which tone and icon to choose.

The transition label

The label of a transition reads event [guard] / action, as in UML. The parser splits it, so the picture sets the event in the primary ink and the guard and the action in the secondary ink, and the text description says "on the event, if the guard, then the action".

A slash starts the action only when a space follows it, and brackets are a guard only when they are the last thing before the action or the end of the label. So GET /orders and array[0] access are events. Text wider than 300 px is cut with an ellipsis and warning W203; the full text stays in the text description.

Start, end, and scopes

A scope is the top level of the diagram, a composite state, or one region.

Regions

A region goes directly inside a composite state, and a composite state holds either states or regions, never both (E362). A region outside a composite state, or inside another region, is E363. Each region has its own start and end markers. A diagram that reads sideways stacks its regions, a diagram that reads up or down puts them in a row, and a dashed line crosses the whole frame between two of them. A download with two regions draws this.

1state sync "Syncing" {2  region "Upload" {3    start -> sending4    state sending "Sending" icon=lucide:cloud-upload5  }6  region "Download" {7    start -> receiving8    state receiving "Receiving" icon=lucide:cloud-download9  }10}

Forks, joins, and choices

A fork splits one path into parallel paths and a join brings them together, so use them when several things must all happen. A choice splits one path on conditions, so give every branch out of it a guard. A release pipeline uses both.

1fork split2join merge3choice green "All green?"4
5split -> lint6split -> test7lint -> merge8test -> merge9merge -> green10green -> deploy : "[yes]"11green -> fix : "[no]"

History

A history marker sits inside a composite state. A transition into it returns to the state that was active last, and deep=on makes it remember the state of nested composite states too. It is an error outside a composite state (E366). A connection that remembers its state draws this.

1state player "Player" {2  history last deep=on3  start -> stopped4  state stopped "Stopped"5  state playing "Playing" icon=lucide:play6  stopped -> playing : "play"7  playing -> stopped : "stop"8}9state off "Off"10
11start -> player12player -> off : "power"13off -> last : "power"

Notes

A note sits across the reading direction, so a transition, which runs along it, never meets one. side= is a request: a side along the reading direction moves to the nearest side across it.

Notes on one side stack in the order they are written, nearest first, and a dotted line joins each note to its state. A note on a composite state has no free side, so it sits inside the frame, under what the frame holds, with no connector. A note on a start or end marker is error E367.

Limits and warnings

Warnings never stop a diagram from being drawn. Errors do.

Layers skipped counts how far transitions jump over the rest of the diagram: a transition that passes over many layers makes the layout work much harder than the number of states suggests, so that number is limited, not only the number of states. The limits are checked from the text alone, so a diagram that is too big is refused at once with a hint on how to split it.

W330 is checked only when the top level has a start marker, and a composite state with no start of its own begins wherever nothing leads into it. W331 looks at one scope at a time: a state is a dead end only when its own scope has an end marker and neither it nor a composite state around it has a transition out.

From Mermaid

stateDiagram and stateDiagram-v2 convert into a state diagram. Before the state kind existed they were converted into a flow diagram, with the start and end as nodes and each composite state as a group. The converter now writes a state diagram, checks it, and returns nothing for one that would not validate. Call convert_mermaid on one diagram, or sync_markdown with convertMermaid for a whole file, as the migration guide describes. The conversion adds no icons and keeps no colors, apart from a tone taken from a class name such as error, so choose a tone and an icon for each state afterwards, as Make it readable describes.

1---2title: Print job3---4stateDiagram-v25  [*] --> Queued6  Queued --> Printing : printer free7  Printing --> Done8  Printing --> Failed : jam9  Failed --> Queued : retry10  Done --> [*]11  state Printing {12    [*] --> Warming13    Warming --> Spooling14    Spooling --> [*]15  }16  note right of Failed : Paper jams are the usual cause17  classDef bad fill:#f9618  class Failed bad

The converter writes this, and reports two warnings M200 for the dropped classDef and class lines:

1state "Print job"2
3state Queued "Queued"4state Printing "Printing" {5  state Warming "Warming"6  state Spooling "Spooling"7
8  start -> Warming9  Warming -> Spooling10  Spooling -> end11}12state Done "Done"13state Failed "Failed"14
15start -> Queued16Queued -> Printing : "printer free"17Printing -> Done18Printing -> Failed : "jam"19Failed -> Queued : "retry"20Done -> end21
22note Failed : "Paper jams are the usual cause" side=right

What is kept

What is dropped or changed

The old conversion differed in ways that matter if you kept its output. A state was node id step "Label" and is now state id "Label", with no node types. The start and end were terminal nodes with ids such as start_Active and are now markers written as transitions. A note and a -- were dropped and are now kept, as a note and as regions. A transition into a composite state was redrawn to its start node, and is now kept as written. <<fork>> and <<join>> were plain steps and are now bars.

See also