--- name: Draw.io BPMN slug: draw-io-bpmn category: Automation description: Draw.io BPMN produces BPMN swimlane diagrams in draw.io for business processes, workflows, and role-based phase maps. It uses the declarative layout engine, validates BPMN rules and geometry, and runs a render-based vision check. github: "https://github.com/sparklabx/drawio-ai-kit/tree/main/skills/drawio-bpmn" language: JavaScript stars: 633 forks: 111 install: "npx degit https://github.com/sparklabx/drawio-ai-kit/tree/main/skills/drawio-bpmn ~/.claude/skills/drawio-bpmn" installs_to: ~/.claude/skills/drawio-bpmn source_path: skills/drawio-bpmn/SKILL.md collection_size: 6 category_size: 1523 collection_url: "https://dirskills.com/collections/sparklabx/drawio-ai-kit" added: 2026-08-24T05:18:06.042Z last_synced: 2026-08-24T05:18:06.042Z canonical_url: "https://dirskills.com/skills/draw-io-bpmn" --- # Draw.io BPMN Draw.io BPMN produces BPMN swimlane diagrams in draw.io for business processes, workflows, and role-based phase maps. It uses the declarative layout engine, validates BPMN rules and geometry, and runs a render-based vision check. **Install:** ```bash npx degit https://github.com/sparklabx/drawio-ai-kit/tree/main/skills/drawio-bpmn ~/.claude/skills/drawio-bpmn ``` ## README # Draw.io BPMN Produce correct BPMN (Business Process Model and Notation) swimlane diagrams in draw.io. This skill is a thin frontend; the deterministic engine, validator, and rules live in the `drawio-ai-kit` package, reached via the `drawio-ai` CLI. ## 0. Preflight — the CLI must be installed ```bash command -v drawio-ai >/dev/null 2>&1 || echo "Install the Kit first: npm i -g github:sparklabx/drawio-ai-kit" ``` If `drawio-ai` is **not** on PATH, stop and tell the user to run `npm i -g github:sparklabx/drawio-ai-kit`. **Never run `npm i -g` yourself** — nothing mutates the user's global environment without their say-so. ## 1. Delegate the build (preferred when your harness supports it) If your harness can spawn autonomous subagents that run shell commands AND read images (e.g. Claude Code's Task tool, a general-purpose agent), run the whole build loop in a subagent — the rules, icon searches, and every render/fix iteration then cost this conversation nothing. If it can't (or the subagent can't read images), skip to **Inline path** below — same loop, same rules. **Before spawning**, resolve what the subagent cannot ask about: diagram scope, output directory (absolute path under the user's project), filename. Run the preflight above yourself. For a multi-diagram request, spawn one subagent per diagram in parallel with distinct filenames. **Model routing** — if your harness lets you choose the subagent's model, route by task weight: a **fast/cheap tier** (Claude Haiku-class — must support vision) when the request matches a template from the rules' Templates table (reproduction is mechanical; the validator's advice strings teach every fix), your **default strong model** for free-hand or novel architectures. If a cheap subagent returns VALIDATE not ok or ITERATIONS > 3, respawn ONCE on the strong model before taking over inline. Multi-diagram requests: route each diagram independently. Subagent prompt (fill every `<...>`): ```text Build a BPMN swimlane .drawio diagram with the drawio-ai CLI. Request: Output: /.drawio — never write inside the Kit, never into cwd. Follow exactly: 1. Set ROOT="$(drawio-ai root)". Read $ROOT/docs/api-cheatsheet.md — the full layout-engine API in one file; never read library source. 2. Run `drawio-ai workflow` and `drawio-ai principles --mode bpmn` — the source of truth. (Fallback if a command is blocked: read $ROOT/rules/*.md directly.) 3. Look up every icon with ONE batched `drawio-ai search "a, b, c"`; never recolor icons. 4. Scaffold, don't write: `drawio-ai scaffold --list`, pick the closest template, then `drawio-ai scaffold .mjs -o /build.mjs` — the script arrives runnable (absolute imports, self-validating, self-rendering with an issues list). Edit only the deltas. If no template is close AND you'd change more than half of it, Write a new script instead (keep the scaffold's self-check tail). Layout engine only (group/frame/grid/icon/box + renderTree), NO hand-written coordinates. 5. Each `node build.mjs` run prints validate JSON AND the render's machine-readable `issues` list. Fix from THAT checklist — all issues in one Edit round — then re-run. Loop until issues is empty. 6. Only when issues is empty: Read the PNG once as final visual confirmation (list any remaining visual problems, fix ALL in one round). Target <= 2 PNG reads total. Then render once WITHOUT --check for the final deliverable PNG. Do NOT invoke any drawio skill — this prompt already contains the full procedure. Do not ask questions — make the standard choice and record it under ASSUMPTIONS. Return EXACTLY this block, nothing else: DRAWIO: PNG: VALIDATE: ICONS: ITERATIONS: SUMMARY: ASSUMPTIONS: ``` Relay `DRAWIO`, `PNG` and `SUMMARY` to the user verbatim; do NOT re-read the .drawio or PNG in this conversation — the subagent already ran the vision self-check. If `VALIDATE` is not ok, take over via the Inline path (the build .mjs and .drawio are on disk at the returned paths). ## Inline path (no subagent support) ### 1. Shared Workflow ```bash drawio-ai workflow ``` Prints the build → validate → render → write-to-project-path loop every diagram follows. Read it; it is the source of truth for the process. ### 2. Domain rules ```bash drawio-ai principles --mode bpmn ``` Returns the BPMN rules + shared principles + catalog shape groups. ### 3. Build with the engine, then validate + render Resolve the Kit's install dir, then `import` the engine by absolute path (the Shared Workflow shows the exact pattern): ```bash ROOT="$(drawio-ai root)" # absolute path to the installed Kit ``` Build with the declarative layout engine (NO hand-written coordinates) using the `src/bpmn.mjs` creators and the `pool()` primitive, then: `drawio-ai validate ` → `drawio-ai render -o .png` (`Read` the PNG for the vision self-check) → write the `.drawio` to an **absolute path under the user's project** (never the Kit, never `cwd`). ## Domain notes Structure: `pool → lanes (roles) × phases (milestones)`. Use the creators in `src/bpmn.mjs` — `start`, `intermediate`, `end`, `gateway` (exclusive/parallel/ inclusive/event), typed tasks (`userTask`, `serviceTask`, `manualTask`, `scriptTask`, `businessRuleTask`), plain `task`, `subProcess`. Each node carries `{ lane, col }` cell tags; the engine places them automatically. A gateway MUST split (≥2 outgoing) or merge (≥2 incoming) — never neither. Red accent ONLY for blocker end events (error/cancel/terminate); everything else is monochrome. Sequence flow: solid lines, rounded corners. One start event (no incoming flow); end events on the right (no outgoing flow). Horizontal by default; pass `orientation: "vertical"` to `pool()` for vertical swimlanes. ## Self-check (before delivering) - [ ] Built with the layout engine — no hand-written coordinates. - [ ] `drawio-ai validate` → ok, no warnings, no advice. - [ ] Every icon came from `drawio-ai search` (category colors intact). - [ ] `drawio-ai render` vision self-check passed. - [ ] Output written under the user's project, not the Kit.