bpmn-generator

BPMN Generator Skill v2.0 — Enterprise Edition

Converts natural language process descriptions into OMG BPMN 2.0.2 compliant XML files and SVG previews via a 4-phase pipeline. All visual rendering follows the bpmn-js reference implementation.

Pipeline Overview

User Text
   ↓  [Phase 1] Intent Extraction  (Claude LLM)
JSON Logic-Core
   ↓  [Phase 2] Validation          (rules + deadlock detection + structural soundness)
Validated JSON
   ↓  [Phase 3] Auto-Layout         (ElkJS Sugiyama layered algorithm)
JSON + Coordinates (edge endpoints clipped to shape boundaries)
   ↓  [Phase 4] Serialization       (pipeline.js)
BPMN 2.0 XML + SVG

The LLM never handles coordinates. Layout is 100% algorithmic.

Modes: Document (IST) vs. Optimize (Soll)

Two distinct intents — keep them separate:

• Document mode (default, IST / as-is): the user describes a process and wants it captured faithfully as BPMN. No judgment, no improvement suggestions. This is the default for every entry point (CLI, runPipeline, HTTP, MCP).
• Optimize mode (Soll / to-be): the user wants a better process. Enables the opt-in Optimization Advisory layer, which flags graph-detectable redesign opportunities (Reijers 2005 heuristics + BABOK Lean metrics) as non-blocking advisories — never auto-applied.

Select the mode consistently across entry points:

• CLI: node bpmn/pipeline.js in.json out --optimize
• Programmatic: runPipeline(lc, { mode: 'optimize' })
• HTTP: { "logicCore": {...}, "mode": "optimize" } on /api/v1/generate|validate|orchestrate
• MCP: mode: "optimize" on generate_bpmn / validate_bpmn / orchestrate_bpmn

Advisories are review suggestions with trade-off tags (time/cost/quality/flexibility); they are heuristics, not proofs — present them as options, never silently apply them. Each advisory is an object { id, transform, targets, message, tradeoff, ref, judgment } (see references/api-reference.md); message is the human-readable line, transform names the matching intervention in the toolbox below.

Redesign Toolbox

In optimize mode, an advisory's transform field names a concrete, mechanical intervention. The interventions live in scripts/bpmn/redesign.js; each has a preview* function (what would be feasible, and why not) and an apply* function that performs it:

• parallelize — puts a linear, same-lane task chain into a parallel-gateway split/join. Tasks only: a chain containing a subprocess, a call activity, an intermediate event or a gateway is refused, because parallelising a scope or a branch changes the process logic rather than the order of its steps. This is also why O04 never nominates a subprocess chain — the detector (optimize.js) is scoped to the same leaf-task set as the transform, so it cannot advise something the toolbox is guaranteed to refuse. If you want such a chain parallelised, that starts with a decision about the transform, not with the advisory
• mergeTasks — folds a linear task chain into one task; requires an explicit name — naming the result is a judgment call the toolbox refuses to make for you
• relane — moves one node to a different lane
• reorderKnockouts — reorders a chain of exclusive-gateway "knock-out" checks; requires an explicit order — it is never computed
• isolateException — turns an inline exception branch into a boundary event on the owning task; requires explicit marker and cancelActivity, and, when the exception end has more than one incoming edge, an explicit edgeIds naming which ones belong to this task — it refuses rather than guess

No-language-model guarantee: the toolbox is purely deterministic. scripts/bpmn/redesign-core.js may not import agents/llm-provider.js, directly or transitively — no LLM call, no API key. Verify with grep -rn "^import.*llm-provider" scripts/redesign*.js (no hit; a plain grep -rn "llm-provider" also matches the comment stating this rule, so it is not a useful check on its own).

Rollback: every apply* re-checks its result against a fixed, profile-independent soundness gate (soundness + workflow-net layers, always on — scripts/bpmn/redesign-core.js: SOUNDNESS_GATE) and rolls back (throws, writes nothing) on structural errors. Style warnings never block; they come back in the result's warnings array instead.

What it will not decide for you: the toolbox never decides whether an intervention should happen — that's the caller's call. Where a transform lacks the information to act safely (no proven data-independence between two tasks, no supplied ordering, no supplied marker/cancelActivity, an ambiguous set of incoming edges) it refuses with a specific reason instead of guessing. Not every transform currently has a matching automatic advisory either: O01→isolateException, O02→reorderKnockouts, O03→relane, O04→parallelize are detected by optimize.js; mergeTasks has no detector and is reachable only by direct/manual invocation.

Protection lists (policy.protectNodes / policy.protectLanes) match a node or lane by id and by display name, and resolve lane membership whether the model expresses it via node.lane or via Lane.nodeIds. Transforms also maintain both representations: a transform that deletes a node removes it from any Lane.nodeIds, and one that creates a node adds it — so the two never contradict each other. Purely Format-A models are left untouched (no nodeIds arrays are introduced).

Every apply* returns a change record with three arrays — added, removed, modified — that together name every element (node, edge, or lane) that differs between input and result.

CLI (preview is the default; nothing is written without --apply; a refusal exits non-zero and writes nothing):

node bpmn/redesign-cli.js <input.json> <parallelize|mergeTasks|relane|reorderKnockouts|isolateException> \
  [--nodes a,b,c] [--name "..."] [--lane X] [--order g2,g1] [--end xend] [--attach-to task] \
  [--marker timer] [--cancel-activity true|false] [--edges j2,j5] [--policy '{"protectNodes":[...]}'] \
  [--apply] [-o out.json]

Reference Files

Read these when needed:

• references/logic-core-schema.md — Full JSON schema, type table, all examples → read before extracting JSON
• references/prompt-template.md — LLM prompt templates for extraction, review, amendment → read before prompting

Supported BPMN 2.0 Elements

Events

Activities

Activity Markers (bottom-center)

Gateways

Data & Artifacts

Connections

When to use which mode

Phase 1 — Intent Extraction

Read references/logic-core-schema.md and references/prompt-template.md first.

Use the Master Extraction Prompt template. Key rules to enforce:

Naming Conventions (BA-Quality)

• Tasks: Objekt + Verb (Infinitiv) — "Antrag prüfen" ✓ / "Prüfung" ✗
• XOR Gateways: Question form — "Antrag gültig?" ✓ / "Entscheidung" ✗
• AND/OR Gateways: Empty or brief label — "" ✓ (these are sync points)
• Gateway edges: Always labeled — "Ja"/"Nein", "genehmigt"/"abgelehnt"
• Lanes: Functional roles — "Sachbearbeiter" ✓ / "Max Müller" ✗
• Events: Noun phrase — "Antrag eingegangen" ✓

Granularity Rules

• Max 7–10 nodes per level. Use subProcess for groups with >3 logical steps.
• Never create "God-Tasks" (a single task hiding a whole sub-process).
• Prefer more granular over too abstract.

Happy Path

• Mark the main success flow edges with "isHappyPath": true
• ElkJS will lay these out on the horizontal axis (left→right)
• Exception/error paths branch vertically

Gateway Direction (OMG spec §10.5.1)

• has_join: true → pipeline sets gatewayDirection="Converging" in XML
• Split gateways get gatewayDirection="Diverging" automatically
• Mixed (split+join) gateways get gatewayDirection="Mixed"

Event Markers

• Set marker explicitly when the event type is clear from context
• If not set, pipeline infers from event name (e.g. "Frist abgelaufen" → timer)

Phase 2 — Validation

The pipeline validates automatically. These checks run:

Errors (block pipeline):

• At least one startEvent exists per process
• At least one endEvent exists per process
• All edge.source and edge.target reference existing node IDs
• No XOR-split path merging at an AND-join (deadlock detection)
• Message flows reference valid node/pool IDs

Warnings (report but continue):

• XOR gateways not named as questions
• Tasks not following Objekt + Verb (Infinitiv) pattern (M01)
• Nodes with no edges (isolated)
• XOR gateway outgoing edges without labels
• Nodes with no outgoing flow (may not terminate)

Use the Reviewer Agent Prompt from references/prompt-template.md for additional automated review.

Pre-Delivery Gate (MANDATORY — do not skip)

A first draft is expected to be wrong. Never present a diagram as finished until it passes this gate. Warnings are not noise — they are the alarm.

1. Read references/logic-core-schema.md first. It is the field-by-field contract (every node type, marker, edge, message flow, black-box pool). Fill the input file against it — do not guess field names or values.
2. Validate the draft against the schema and run it strictly:

   node bpmn/pipeline.js <input>.json <output> --strict
   

   • The schema-gate (references/input-schema.json) rejects malformed structure with a precise field path and exits non-zero — fix every reported field.
   • --strict makes every warning fatal (exit non-zero, no files written), across three independent checks: rule-engine warnings, diagram (DI) integrity, and BPMN serialisation (the round trip of the generated XML through bpmn-moddle — this is what catches an invalid element, e.g. an annotation carrying an illegal attribute).
3. Resolve every warning and re-run until --strict exits 0. Delivering a diagram with unresolved warnings is not allowed.
4. Only then present the output. If a warning is a deliberate, justified exception, say so explicitly to the user — do not silently ship past it.

Phase 3 + 4 — Script Execution (Claude Code)

Setup (first time only)

cd scripts/
npm install   # installs runtime + dev dependencies (see package.json)

Run pipeline

# From JSON file:
node bpmn/pipeline.js my-process.json my-process

# From stdin (inline JSON):
echo '{ ... }' | node bpmn/pipeline.js - output

# Outputs:
#   output.bpmn  — BPMN 2.0 XML with full DI coordinates
#   output.svg   — SVG preview (open in browser)

OMG Compliance Guarantees

The generated BPMN 2.0 XML ensures:

• Single <laneSet> per process (spec §10.5)
• Correct gatewayDirection attribute (Diverging/Converging/Mixed)
• conditionExpression as child element, not attribute (spec §10.3.1)
• <incoming> and <outgoing> references on all flow nodes
• Event definition child elements (messageEventDefinition, timerEventDefinition, etc.)
• Loop/multi-instance characteristics as child elements
• Boundary events with attachedToRef and cancelActivity
• Valid isHorizontal="true" on pool/lane shapes
• Edge endpoints clipped to actual shape boundaries

Inline Mode (Claude.ai — no script execution)

When Claude Code is not available, generate outputs directly in the conversation:

1. Extract the Logic-Core JSON (show to user for confirmation)
2. Apply validation rules mentally (check for deadlocks, naming, completeness)
3. For the SVG: render as an HTML artifact using inline SVG
   • Use the exact OMG dimensions: 36px events, 100×80 tasks, 50×50 gateways
   • Use ElkJS-compatible manual positioning: elements spaced 60px between layers, 40px between nodes
   • Apply stroke widths: 2 (start), 4 (end), 1.5 (intermediate), 2 (task), 5 (call activity)
4. For the BPMN XML: generate as a code artifact following all OMG compliance rules

Show the Logic-Core JSON to the user before generating final files.

Note: Inline mode coordinates are manually estimated. For production-quality layout, use Claude Code with the pipeline script.

Amendment Flow (editing existing diagrams)

When user wants to modify an existing diagram:

1. Load the existing Logic-Core JSON
2. Use the Amendment Prompt from references/prompt-template.md
3. Apply only the atomic changes requested
4. Re-validate (Phase 2)
5. Re-run pipeline (Phase 3+4)

Never regenerate the entire Logic-Core from scratch for small edits — preserve all existing IDs.

Two-Agent Pattern (production quality)

For enterprise output, run Modeler + Reviewer in loop:

Modeler (Claude):  Text → Logic-Core JSON (draft)
     ↓
Reviewer (Claude): Logic-Core → Issues JSON
     ↓
  No issues? → Run pipeline
  Issues?    → Modeler applies fixes → repeat (max 3 iterations)

Use prompts from references/prompt-template.md for both roles.

Output Artifacts

Error Handling

Quick-Reference: Node Types

Round-Tripping (BPMN Import)

Import existing BPMN 2.0 XML files to extract a Logic-Core JSON for editing.

Claude Code

cd scripts/
node bpmn/import.js existing-diagram.bpmn extracted.json

Workflow

Existing .bpmn file
   ↓  [import.js] Parse XML → extract nodes, edges, lanes, message flows
Logic-Core JSON
   ↓  [User/LLM edits]  Amendment flow
Modified Logic-Core
   ↓  [pipeline.js]  Layout + render
New .bpmn + .svg

Supported on import: Processes, collaborations, lanes, message flows, collapsed pools, gateways (with direction), all task/event types, boundary events, loop/MI markers, data objects, associations, process documentation, default flows.

Inline Mode (Claude.ai — with ElkJS)

When Claude Code is not available, use the inline template from references/inline-template.md to create a self-contained HTML artifact:

1. Extract the Logic-Core JSON
2. Show to user for confirmation
3. Create an HTML artifact with the template
4. Replace __LOGIC_CORE_JSON__ with the actual JSON

The template runs ElkJS from CDN in the browser — no manual coordinate estimation. It produces orthogonal layouts with proper BPMN shapes.

Note: The inline renderer is simplified (no task type icons, no event markers). For full rendering fidelity, use Claude Code with pipeline.js.

Collapsed Pools (Black-Box Participants)

Best Practice (Bruce Silver Method & Style): A diagram should have one expanded pool (your process in scope) and collapsed pools for external participants (customers, suppliers, authorities).

Schema

{
  "collapsedPools": [
    { "id": "Pool_Kunde", "name": "Versicherungsnehmer" },
    { "id": "Pool_Gutachter", "name": "Externer Gutachter" }
  ]
}

Rendering

• SVG: Thin horizontal band (600×60) with centered label
• XML: <participant> without processRef (OMG spec §9.3)
• Message flows target the collapsed pool ID directly

Associations (Data Objects + Annotations)

Connect Data Objects, Data Stores, and Text Annotations to flow nodes:

{
  "associations": [
    { "id": "assoc1", "source": "task_erfassen", "target": "do_akte", "directed": true },
    { "id": "assoc2", "source": "ann_hinweis", "target": "task_pruefen" }
  ]
}

• SVG: Dotted line (strokeDasharray 0.5,5)
• XML: <association> element with associationDirection, placed in <artifacts> alongside any TextAnnotation/Group it connects to — never in <flowElements> (§10.7). Endpoint resolution has to look in both collections: an association's source or target is very often an artifact, not a flow node.

OMG Compliance Checklist (v3)

Why the three artifact rules above matter if you ever hand-write XML (inline mode): an Artifact (TextAnnotation, Group, Association) extends BaseElement, which declares only id — name is introduced further down by FlowElement, and Artifacts never inherit from it. Most XML libraries write the attribute anyway without complaint, so a name on a TextAnnotation produces no error and an empty box in every real BPMN tool. This shipped once; see references/omg-compliance.md §10.7 for the full mapping.