| name | bpmn-package-explorer |
| description | Generate, validate and view BPMN 2.0 process packages from a prose description, and render existing .bpmn / .dmn files. Turns a described business process into plain vendor-neutral BPMN semantics, auto-lays it out with a verifying layout guard (never emits a corrupt diagram), wires decisions (.dmn), forms (.form) and sub-processes through a sidecar package.yaml manifest, and serves a buildless offline bpmn-js / dmn-js viewer on the canvas. Use when the user wants to "model a business process", "make a BPMN diagram", "generate a process from this description", "draw the workflow", "view / open a .bpmn or .dmn file", "build a decision table", or asks in Hungarian to "csinálj egy folyamatábrát", "rajzold meg a folyamatot", "BPMN ábra", "folyamat modellezés", "döntési tábla", "nézd meg ezt a .bpmn fájlt", "folyamatcsomag". |
BPMN Package Explorer
Generate and view BPMN 2.0 process packages: a process plus the decisions its
rule tasks evaluate, the forms its user tasks present, and a manifest binding
them — kept as plain, vendor-neutral BPMN 2.0. Buildless and offline: it
vendors pre-built viewers and a self-contained Node layout bundle; generating or
rendering a package needs no npm install, no bundler and no network. Requires
Node ≥ 20.12 and a browser.
When to use
Model a business process from a prose description; make/view a BPMN diagram or a
DMN decision table; build a cross-linked process package. Hungarian triggers:
„csinálj egy folyamatábrát”, „rajzold meg a folyamatot”, „döntési tábla”,
„nézd meg ezt a .bpmn fájlt”.
The two guarantees
- Never a corrupt diagram. A language model can author correct BPMN
semantics but not a readable coordinate set.
bpmn-auto-layout fills that
gap but fails silently on sub-processes, pools and lanes (all outputs stay
schema-valid). A layout guard verifies every laid-out diagram against its
own semantics and aborts on any corruption, in strict mode.
- Vendor-neutral. The
.bpmn/.dmn/.form files carry no engine
extension. A sidecar package.yaml holds the link graph (bindings, roles),
so a package opens in Camunda Modeler, Signavio or any conformant tool.
Generation workflow
The agent authors the artifacts (guided by the references); the pipeline runs the
mechanical steps, each failing loudly:
- Author semantics — one or more semantics-only
.bpmn (no geometry),
applying the authoring envelope and identifier rules. Emit
<bpmn:incoming>/<bpmn:outgoing> on every connected flow node.
- Author artifacts — the
.dmn decisions and .form schemas.
- Write
package.yaml — the bindings and roles.
- Validate the manifest —
node scripts/generate-cli.mjs <packageDir>
runs the envelope check, manifest validation, layout + guard, and assembles a
render root; it stops before serving on any error.
- Serve + canvas — serve the printed render-root path with
node scripts/serve.mjs <renderRoot> [port] (CORS-enabled) and open the
printed URL on the canvas (never file://). Do not use serve_mockup
for canvas display: it omits Access-Control-Allow-Origin, so the viewer's
fetch('package-data.json') fails in the opaque-origin sandbox (“Failed to
fetch” → blank diagram).
Display / view workflow
- Package:
node scripts/generate-cli.mjs <packageDir> → node scripts/serve.mjs <renderRoot> → canvas.
- Standalone file (no manifest):
node scripts/view-cli.mjs <file.bpmn|.dmn>.
A file with DI renders as authored; a semantics-only .bpmn is laid out into a
separate render artifact (the source is never overwritten). A DI-less file
containing a rejected construct is refused with that construct's diagnostic.
Canvas / sandboxed-iframe rendering (if the viewer shows blank)
The dashboard opens a loopback canvas(kind:"url") target inside a
sandbox="allow-scripts" iframe with no allow-same-origin (opaque origin),
proxied under /live/<id>/. The vendored bpmn-js / dmn-js viewers are buildless
and offline, so they usually render fine — but if the canvas comes up blank
or 404s, it is almost always one of these, not a viewer bug:
- Absolute asset paths. Anything the served page references with a
leading-slash path (
/vendor/..., /main.js) resolves to the dashboard root
under the /live/<id>/ prefix → 404. Keep every path in the render root
relative (./vendor/...). Serve the render root with serve_mockup (never
file://) and open the returned URL on the canvas.
- Missing CORS on the static server → “Failed to load package: Failed to
fetch”. In the opaque-origin iframe every runtime request carries
Origin: null: the viewer's fetch('package-data.json') (and any
<script type="module">) is rejected unless the server answers with
Access-Control-Allow-Origin: *. serve_mockup does NOT set it, so serve
canvas render roots with node scripts/serve.mjs <renderRoot> (this skill's
CORS server) rather than serve_mockup.
- Self-verify by iframing your served render root with
sandbox="allow-scripts" and screenshotting before trusting the canvas — that
reproduces the exact dashboard sandbox.
Full rationale, the CORS static-server pattern, and adjacent pitfalls (IPv6-only
dev binds → ECONNREFUSED, kill %1 not persisting across tool calls) are in
the canvas-webapp skill (bundled with the pi-dashboard extension).
Rejected constructs → manifest substitutions
Inline subProcess → callActivity + separate .bpmn + kind: process
(drill-down). Pools (collaboration) → one .bpmn per participant +
kind: participant (switcher). laneSet → manifest roles (markers + legend).
messageFlow → unrepresentable (rejected). ≥2 boundary events on one activity →
rejected. See references/authoring-envelope.md.
Verify the toolchain
node scripts/fixtures.mjs — layout regression suite (catches upstream drift).node scripts/selftest.mjs — envelope / identifier / manifest / guard /
workflow unit tests.node scripts/vendor.mjs — verify vendored bundle hashes
(--rebuild re-vendors from pinned inputs).
References
references/authoring-envelope.md — generation contract + rejected constructs.references/identifiers.md — deterministic ids, Hungarian deburring,
uniqueness errors, authoring-vs-ingestion.references/package-manifest.md — the package.yaml contract, reconciliation.references/layout-envelope.md — the measured fixtures and outcomes.references/licensing.md — the bpmn.io watermark obligation and Apache 2.0.assets/VENDORED.md — pinned versions, hashes, the Node floor (20.12).
