bpmn — Claude Code plugin for BPMN 2.0

A Claude Code plugin that lets Claude work with BPMN 2.0 process diagrams (.bpmn XML): read and explain them in plain language, and create or edit them so they come out valid and visually clean in any modeler (Camunda Modeler, bpmn.io, Cawemo…).

The model does the semantic reasoning (what the process means, what to change); a small bundled Node script does the deterministic mechanics — parsing, regenerating layout, validating, and linting control flow.

What it can do

• Explain a .bpmn: happy path, decision points, exception/timeout handling.
• Create / edit processes from a description (you never hand-write diagram coordinates), with full layout coverage: collaborations (all pools + message flows), swimlanes, sub-process drill-down pages, and data objects/annotations.
• Edit non-destructively: layout is safe by default — on a file that already has a diagram it preserves the layout (hand-tuned positions, Camunda multi-diagram sub-process pages) and only prunes shapes for deleted elements and places shapes for new ones. A full re-layout happens only with --rebuild.
• Validate: well-formed XML, every node/edge has a shape, no overlaps (checked per diagram plane).
• Lint control flow: catches bugs that are valid XML but wrong behaviour — deadlock (parallel join after an exclusive split), double execution (exclusive join after a parallel split), stuck-token gateways (all branches conditioned, no default), unreachable nodes, dead ends, and a missing start/end event.
• Compare & search: diff two versions (As-Is vs To-Be or edit review) and find elements by name or type.

Requirements

• Claude Code
• Node.js >= 18 and npm — on first use the skill runs npm install in its own folder to fetch bpmn-moddle and bpmn-auto-layout (deps are not committed).

Install

This repository is both the plugin and a one-plugin marketplace:

/plugin marketplace add architawr/claude-bpmn-skill
/plugin install bpmn@bpmn-tools
/reload-plugins

The skill is model-invoked: once installed, Claude uses it automatically when you work with .bpmn files or ask to model/review a process. It is namespaced as bpmn (the plugin name).

Or, for local development without installing:

claude --plugin-dir ./claude-bpmn-skill

Commands

The skill is model-invoked automatically, but the plugin also adds explicit slash commands (namespaced /bpmn:):