bpmn-package-explorer
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, aut
SKILL.mdpackages/pi-forms-bpmn/.pi/skills/bpmn-package-explorer/SKILL.md
GitHubBPMN 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-layoutfills 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/.formfiles carry no engine extension. A sidecarpackage.yamlholds 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
.dmndecisions and.formschemas. - Write
package.yaml— thebindingsandroles. - 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 (neverfile://). Do not useserve_mockupfor canvas display: it omitsAccess-Control-Allow-Origin, so the viewer'sfetch('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.bpmnis 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 withserve_mockup(neverfile://) 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'sfetch('package-data.json')(and any<script type="module">) is rejected unless the server answers withAccess-Control-Allow-Origin: *.serve_mockupdoes NOT set it, so serve canvas render roots withnode scripts/serve.mjs <renderRoot>(this skill's CORS server) rather thanserve_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 (--rebuildre-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— thepackage.yamlcontract, 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).