git:20260509.89e2ac8 to git:20261026.9c0b42f

75 added, 28 removed. Audit A to B.

# CLAUDE.md

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

## What this repository is

- This is a **Claude Code skill** for generating valid BPMN 2.0 XML files compatible with BPMN 2.0-compliant process engines. It has no build system, test runner, or application code — it is entirely documentation and skill configuration.

+ A **Claude Code / Cline skill** that generates BPMN 2.0 XML for a target process engine. It is mostly

+ documentation (the skill's instructions), plus a small Node.js toolchain the skill runs to validate and

+ lay out what it generates. There is no application to build.

- The skill is registered at `.claude/skills/bpmn-xml-generator/` and is invoked automatically when users ask to create, model, or convert a business process or BPMN diagram.

+ The skill lives in `.claude/skills/bpmn-xml-generator/` and is invoked when users ask to create, model,

+ convert, migrate, fix or validate a business process / BPMN diagram.

## File structure

```

.claude/skills/bpmn-xml-generator/

- SKILL.md # Entry point: skill frontmatter + all authoring rules

- references/

- elements.md # Full attribute reference for every supported element

- examples.md # 4 complete valid BPMN examples (ready-to-upload)

- validation-errors.md # bpmn-moddle parse errors and fixes

+ SKILL.md # Entry point: workflow and engine-agnostic authoring rules

+ references/ # CORE layer — OMG BPMN 2.0 only, no engine extensions

+ elements.md # element reference, XSD child order

+ patterns.md # advanced patterns (multi-instance, compensation, …)

+ examples.md # complete engine-agnostic examples

+ validation-errors.md # validator messages, fixes, ID naming conventions

+ profiles/ # ENGINE layer — one file per engine

+ _contract.md # mandatory sections of a profile

+ stateway.md | camunda8.md | flowable.md

+ scripts/ # Tooling run by the skill (Node.js ≥ 20, pinned deps)

+ validate.mjs # namespaces → bpmn-moddle → OMG XSD (xmllint) → bpmnlint

+ layout.mjs # bpmn-auto-layout + post-processing

+ profiles.mjs # per-engine config: namespaces, moddle descriptors, lint rules, support matrix

+ moddle/*.json # moddle descriptors for stateway: and flowable:

+ lint-rules/*.cjs # local bpmnlint rules

+ xsd/*.xsd # OMG BPMN 2.0 schema

+ tests/

+ run-examples.mjs # validates every ```xml block in the skill docs

+ check-install-manifest.mjs # install.sh must list exactly the skill's files

+ .github/workflows/validate.yml # CI: both tests on Node 20 and 22

+ install.sh # curl | sh installer (file manifest + optional npm ci)

```

## Architecture and design constraints

- ### Engine-compatibility constraints

- - Parser: **`bpmn-moddle`** (bpmn-io library) against OMG BPMN 2.0 schema

- - Expression syntax: `{{variables.fieldName}}` — never FEEL (`#{}`) or UEL (`${}`)

- - Timer values: ISO 8601 only — `{{...}}` is not valid inside timer expressions

- - Camunda namespace (`xmlns:camunda="http://camunda.org/schema/1.0/bpmn"`) required for `userTask` attributes (`assignee`, `candidateGroups`, `dueDate`, `formKey`) and `callActivity`/`businessRuleTask` variable passing

- - `<process isExecutable="true">` is mandatory

- - `targetNamespace` on `<definitions>` is mandatory (any valid URI; value is not read by the engine — `http://bpmn.io/schema/bpmn` is the conventional default for new files)

- - `<message>` and `<signal>` elements must be declared as siblings of `<process>` inside `<definitions>`, not inside `<process>`

- - NOT supported: CMMN, Choreography, Conversation, DataStore

+ ### Two layers

+ - **Core** (`SKILL.md`, `references/`) knows only the OMG BPMN 2.0 spec. It never contains engine

+ extensions (`stateway:`, `zeebe:`, `flowable:`, `camunda:`) — the validator's `core` profile rejects them.

+ - **Profiles** (`profiles/<engine>.md` + the matching entry in `scripts/profiles.mjs`) add the engine's

+ namespace, expression language, extension mapping, support matrix and deployment notes.

+ Every profile follows `profiles/_contract.md`.

+ - Supported profiles: `stateway`, `camunda8`, `flowable` (+ `core` for documentation-only models).

+ - Out of scope for now: pools, lanes, collaborations, message flows, Camunda 7.

- ### Output conventions

- - Process IDs: kebab-case (becomes the process identifier/key in the engine)

- - Flow IDs: `flow_{source}_to_{target}`

- - Gateway IDs: `gw_{purpose}`

- - All `<sequenceFlow>` elements grouped at the bottom of `<process>` after all nodes

- - 2-space indentation throughout

+ ### Engine facts that are easy to get wrong

+ - **Stateway** uses its own namespace `https://stateway.io/schema/bpmn/1.0` (`stateway:taskDefinition`,

+ `taskHeaders`, `ioMapping`, `assignmentDefinition`, `decisionRef`, `eventCorrelation`,

+ `variableFilter`) — not `camunda:`. Expressions `{{…}}`; ioMapping targets are bare names; timers

+ literal ISO 8601; no retries; `scriptTask`, `receiveTask`, `eventBasedGateway` are parse-only.

+ Deploy with `POST /v1/definitions`. Source: https://docs.stateway.io.

+ - **Camunda 8**: `zeebe:` extensions, FEEL with `=` prefix, support depends on the 8.x version

+ (validator `--engine-version`, default 8.10).

+ - **Flowable**: `flowable:` extensions, JUEL `${…}`; DMN via `serviceTask flowable:type="dmn"`

+ (`businessRuleTask` is Drools).

+ ### Output conventions

+ - Process ids: kebab-case starting with a letter. Flow ids: `flow_{source}_to_{target}`.

+ Gateway ids: `gw_{purpose}`. Full table: `references/validation-errors.md` §5.

+ - Children in XSD order (`documentation`, `extensionElements`, `incoming`, `outgoing`, type-specific).

+ - All `<sequenceFlow>` elements at the bottom of their container, after the nodes. 2-space indentation.

+ - `<message>`, `<signal>`, `<error>`, `<escalation>` are siblings of `<process>`.

- ### Information gathering (skill behavior)

- The skill must ask before writing whenever the process description is incomplete. Required: process key, name, happy-path steps, human tasks with assignees, service tasks with implementation type, and any gateway conditions. All missing items are asked in a single response.

+ ### Skill behavior

+ The skill must ask before writing whenever the description is incomplete — always including the target

+ engine profile — and ask all missing items in a single response. It must run `scripts/validate.mjs`

+ before delivering and fix every error.

## Editing guidelines

- - `SKILL.md` is the authoritative source of truth for skill behavior. All rules, patterns, and constraints live there.

- - `elements.md` is reference-only — update it when supported engine extensions change.

- - `examples.md` examples must remain valid BPMN that can be uploaded via `POST /v1/definitions`. Do not add examples that would fail `bpmn-moddle` parsing.

- - `validation-errors.md` — add new entries when new error patterns are discovered; keep error codes sequential.

+ - `SKILL.md` is the source of truth for the workflow and the core authoring rules.

+ - Engine-specific content goes **only** in `profiles/`. When a profile's support matrix changes, update

+ both the table in `profiles/<engine>.md` and the matrix in `scripts/profiles.mjs`.

+ - When the engine docs do not cover something, mark it `unverified` and cite the page; never invent syntax.

+ - Every complete XML example is fenced as ```` ```xml profile=<core|stateway|camunda8|flowable> ```` and

+ must pass `node tests/run-examples.mjs` with zero errors and zero warnings (before and after layout).

+ Plain ```` ```xml ```` fences are snippets and only need to be well-formed.

+ - New/renamed files under the skill directory must be added to the `FILES` list in `install.sh`

+ (`node tests/check-install-manifest.mjs` enforces it).

+ - `validation-errors.md`: keep codes grouped by layer and sequential within a group.

- XML escaping in examples: `&&` → `&&`, `<` → `<` inside element content and attribute values.

+ - Dependencies are pinned in `scripts/package.json` / `package-lock.json`; bump deliberately and re-run the tests.

+ ## Commands

+ ```sh

+ npm ci --prefix .claude/skills/bpmn-xml-generator/scripts # install validator deps

+ node tests/run-examples.mjs # validate all doc examples

+ node tests/check-install-manifest.mjs # installer manifest check

+ node .claude/skills/bpmn-xml-generator/scripts/validate.mjs <file.bpmn> --profile <p> [--engine-version 8.x] [--json]

+ node .claude/skills/bpmn-xml-generator/scripts/layout.mjs <file.bpmn> [out.bpmn]

+ ```