Diagrams agents write and people read.

A deploy pipeline. columns names the columns, each node starts a new row unless row= puts it beside another, and from= and to= pick the sides an edge leaves and enters.

flow v0
columns fix main manual

pill push col=main tone=muted "push to main"
box build "compile and package"
box test "unit and integration tests"
box staging "deploy to staging"
box smoke "smoke tests"
box production "deploy to production"
end live "Live"

pill failed col=fix row=test tone=rework "checks failed"
box rollback col=fix row=production tone=rework "restore the last release"
panel approve col=manual row=smoke tone=stop
  strong "Release manager"
  muted "approves the release"

push --> build : on push
build --> test
test --> staging : green
staging --> smoke
smoke --> approve tone=stop : passed
approve --> production tone=stop from=bottom to=right label=end : approved
production --> live : healthy
build --> failed tone=rework to=top.2 : fails
test --> failed tone=rework : red
failed --> push tone=rework from=top.1 to=left label=end : fix and push
production --> rollback tone=rework : unhealthy

legend
  pill "event or state"
  box "automated job"
  panel "manual step"
  edge tone=rework "failure path"

The renderer never moves anything.

Automatic layout looks fine until someone edits the diagram, and then every node jumps. In ablauf the author places each node in a named column and a row, and picks the side each edge leaves and enters. Inserting a step moves what is below it down a row; every node keeps its column and its place in the order.

The renderer sizes the grid and draws. When a placement does not work, such as an edge crossing a node or two labels overlapping, it still draws the diagram and reports the problem with its line number. A diagram is done when it has no problems, which is something an agent can check without seeing the picture.

The output is one inert SVG with its own styles. It follows the reader's light or dark theme, or the host page's, through --ab-* custom properties, and the same source always gives the same bytes.

The first line of a diagram names its kind. More kinds are planned on the same grid.

• flow v0FlowRouted nodes and edges on a grid the author lays out: columns, rows and the sides each edge leaves and enters.
• fan-out v0Fan-outOne step and its ordered outcomes, each with a reason and a destination, for when why an outcome happens matters as much as where it goes.

Render it in a build script.

render(source, options?) returns the SVG and a list of problems, each with its line number. It needs Node.js 22.18 or newer and has no runtime dependencies.

import { readFile, writeFile } from "node:fs/promises";
import { render } from "@uberblick/ablauf";

const [input, output] = process.argv.slice(2);
const { svg, diagnostics } = render(await readFile(input, "utf8"));
await writeFile(output, svg);

for (const { line, severity, message } of diagnostics) {
  console.error(`${input}:${line} ${severity}: ${message}`);
}
process.exitCode = diagnostics.length ? 1 : 0;

Agents read the format primer, one page, before they write a diagram. To follow a page's own theme switch, see host page themes.