/bpmn

name: bpmn
description: >-
  Read, explain, create, and edit BPMN 2.0 business-process diagrams (.bpmn XML).
  Use this whenever the user opens, reviews, summarizes, models, or modifies a
  process/workflow as BPMN - including swimlanes, pools, lanes, gateways, tasks,
  events, sequence flows, or boundary events. Trigger even when the user does not
  say "BPMN" explicitly but works with a .bpmn file, a process model/diagram, a
  workflow description they want turned into a diagram, or Camunda/Zeebe/Flowable/
  bpmn.io models. Produces valid BPMN 2.0 XML with a clean, auto-generated layout.
compatibility: Requires Node.js >= 18 and npm. On first use, run `npm install` in the skill folder to fetch bpmn-moddle and bpmn-auto-layout.

BPMN 2.0: read and edit process diagrams

What this skill does

Helps you understand existing `.bpmn` files in plain language and produce new or edited ones that are **valid and visually clean** when opened in any modeler (Camunda Modeler, bpmn.io, Cawemo, etc.).

The job splits cleanly:

• **You** do the semantic reasoning: what the process means, what to add or change.
• **The bundled script** does the deterministic mechanics: parsing, regenerating

layout, and validating. Lean on it instead of hand-rolling these each time.

The one idea that makes BPMN tractable: two layers

A `.bpmn` file holds two layers in one XML document:

1. **Semantics** - the actual process: `bpmn:process` with tasks, gateways, events, and `sequenceFlow`s connecting them. This is the meaning. 2. **Diagram interchange (DI)** - `bpmndi:BPMNDiagram` with x/y coordinates for every shape and waypoints for every edge. This is only the picture.

Editing DI by hand is where BPMN work goes wrong: coordinates drift, shapes overlap, edges cross. **So we never hand-write DI.** You edit semantics; the `layout` command owns the DI. That is exactly what makes the diagram "clear" - a tidy left-to-right layout, generated deterministically.

`layout` is **non-destructive by default**, which is the rule that keeps you out of trouble: on a file that already has a diagram it *preserves* the existing layout and only syncs it to your edit (prune shapes for deleted elements, place shapes for new ones). On a file with no DI it generates a fresh layout. It only throws the whole diagram away and rebuilds from scratch when you pass `--rebuild`. So the habit is simple: **after editing semantics, always run `layout`; it never destroys a good diagram.**

Setup (once per machine)

The script needs two npm packages. From the skill's own directory:

npm install --prefix "<SKILL_DIR>"

`<SKILL_DIR>` is the folder containing this SKILL.md. After that, the four commands below are available. If a run fails with "Cannot find package", the install step was skipped - run it and retry.

Reading / explaining a diagram

1. Get a structured outline (don't try to read raw DI coordinates):

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" summarize path/to/file.bpmn

This prints pools/lanes, start/end events, activities (with their type), gateways (with direction), boundary events (host + interrupting?), and every sequence flow as `source -> target [condition]`. Add `--json` if you want to process it programmatically.

2. Explain it the way a person would understand the process: the happy path first, then decision points (what each gateway branches on), parallel work, and exception/boundary handling. Name real business steps, not element IDs. Match the user's language.

The summarize output is your source of truth for "what does this diagram do" - read from it rather than eyeballing the XML, especially for anything non-trivial.

To **locate** a specific element before an edit, use `find <file> <term>` (matches name or type). To **compare** two diagrams - As-Is vs To-Be, or to show exactly what an edit changed - use `diff <a> <b>`; it reports elements added, removed, renamed, or retyped and any sequence flows that were rewired.

When the user wants a **review** ("is this correct?", "find the bug", "why does it hang?"), also run `lint`. It catches control-flow bugs that are valid XML and pass `validate` but are wrong behavior - the kind that are easy to miss by eye:

node "<SKILL_DIR>/scripts/bpmn-tool.mjs" lint path/to/file.bpmn

It flags: a parallel (AND) join fed by an exclusive (XOR) split (**deadlock**); a parallel split merged by an exclusive join (runs **twice**); an exclusive gateway whose conditions can all be false with no default (**stuck token**); **unreachable** nodes; **dead ends** (non-end node, no outgoing); a missing start/end; an **implicit split** (non-gateway node with several outgoing flows); **misdirected events** (start with an incoming flow, end with an outgoing one); a boundary event on a **non-activity**; a node in **no lane** when the process uses lanes; and a message flow that stays **inside one pool**. Read its finding, confirm it against the model, then explain it in plain terms.

Creating or editing a diagram

Before writing XML for a *new* process, think like a business analyst and pin down the structure - it's what separates a clear model from a box-and-arrow mess. If any of these is unclear from the request, ask:

• **Trigger** - what starts the process (and is it a plain start, a message, a

timer?).

• **Participants** - who does what. Multiple actors usually means lanes (one

pool) or pools + message flows (separate processes).

• **Happy path** - the main sequence of activities when nothing goes wrong.
• **Decision points** - where the path forks, on what condition, and which

gateway fits (exclusive = either/or, parallel = all, inclusive = one-or-more).

• **Exceptions / alternatives** - timeouts, rejections, errors; often boundary

events or extra branches.

• **End states** - the distinct ways the process can finish.

If the user is documenting current vs future state, treat **As-Is** and **To-Be** as separ