claude-bpmn-skill: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A Claude Code plugin (and a one-plugin marketplace, bpmn-tools) for working with BPMN 2.0 process diagrams. The shipped artifact is the skill at skills/bpmn/; commands/*.md are slash-command wrappers that invoke it. The plugin is consumed by a model, but all real mechanics are deterministic Node code you can run and test directly.

Commands

All Node work happens in skills/bpmn/ (deps are not committed — run install first):

cd skills/bpmn && npm install      # one-time: fetches bpmn-moddle + bpmn-auto-layout
npm test                           # full suite (node --test, files in test/*.test.mjs)
node --test test/resync.test.mjs   # one test file
node --test --test-name-pattern "prunes" test/resync.test.mjs   # one test by name

The CLI (run from skills/bpmn/):

node scripts/bpmn-tool.mjs summarize <file.bpmn> [--json]
node scripts/bpmn-tool.mjs layout    <in.bpmn> [out.bpmn] [--rebuild]
node scripts/bpmn-tool.mjs validate  <file.bpmn>
node scripts/bpmn-tool.mjs lint      <file.bpmn>
node scripts/bpmn-tool.mjs diff      <a.bpmn> <b.bpmn>
node scripts/bpmn-tool.mjs find      <file.bpmn> <term>

Architecture

Two layers in every .bpmn. Semantics (bpmn:process / bpmn:collaboration — tasks, gateways, flows) and Diagram Interchange (bpmndi:BPMNDiagram — x/y coordinates). The whole design rests on: the model edits semantics; the script owns the DI. Never hand-write coordinates.

scripts/lib.mjs is the single source of truth. Every mechanic (layoutModel, validateModel, lintModel, summarizeText/Json, diffModels, findModel) lives here as a function over data. scripts/bpmn-tool.mjs is a thin CLI that only formats output and sets exit codes. Add logic to lib.mjs, not the CLI.

The layout safety contract (do not regress this). layoutModel(xml, {rebuild}):

• If the file already has DI and rebuild is falsy → resync: preserve all existing geometry, pruneDI (drop shapes/edges whose element was deleted — a deleted element leaves a bpmnElement === undefined dangling ref), addDI (auto-place shapes/edges for new elements), then placeExtras.
• If there's no DI, or rebuild is true → generate from scratch. Layout is non-destructive by default. The historical bug this fixed: the old code always regenerated and ran a collapseSubProcessDI that deleted sub-process drill-down pages, emptying them. Do not reintroduce a destructive default or sub-process collapsing.