OKHP3 okhp3-visual-process-modeling
BP-SKILL: Business Process Agent Skill Suite · part of mermaid-diagram-bpmn · OverKill Hill P³
Purpose
Generate a Mermaid-native bpmn-beta diagram from a validated PNS. The diagram uses the BPMN 2.0 Descriptive Conformance Sub-Class node set (tasks, gateways, events, message flows, pools, and lanes) expressed in the readable bpmn-beta DSL.
When to use this skill
- PNS has
validation.ready_for_bpmn_modeling: true - User wants a visual process diagram in Mermaid syntax
- User wants to validate or normalise existing
bpmn-betacode - PNS contains ≥3 decision_points → also trigger
okhp3-decision-model-authoringfor a DMN table
When NOT to use this skill
- PNS has not been validated (score < 75): complete
okhp3-process-narrative-authoringfirst - User wants a non-BPMN diagram (flowchart, sequence diagram): use standard Mermaid syntax
- Do not claim full BPMN 2.0 XML conformance: this is a descriptive subset for human-readable process modeling
PNS → bpmn-beta Mapping
| PNS field | bpmn-beta element |
|---|---|
activity_sequence.activities[] |
Task nodes ([task label]) |
decision_points[] |
Gateway nodes ({condition?}) |
exception_paths[] |
Error/intermediate event paths |
roles_and_raci.roles[] |
Lane labels |
process_box.trigger |
Start event ((( ))) |
process_box.outputs[] consumer |
End event or message flow |
| Multiple departments | Pool blocks |
Representation trace convention
When this skill generates a diagram from a PNS, place a comment immediately before each traceable task, event, or gateway node:
# pns:act-001
task:user t1 "Submit purchase request"
Use the stable PNS activity, event, or gateway identifier after pns:. These
comments support reverse observation and alignment checks; they are not proof
that the referenced business fact is still current, complete, or approved.
If no trusted PNS identifier exists, leave the mapping unresolved rather than
inventing one.
DMN Trigger Rule
When the PNS has ≥3 decision_points, hand off to okhp3-decision-model-authoring concurrently with diagram generation. The BPMN gateway labels must match the DMN rule IDs.
Generation Workflow
- Load PNS: read activity_sequence, decision_points, roles, exception_paths
- Map to bpmn-beta: assign each activity to a lane based on
actor_role_id - Render gateways: use
{condition?}for exclusive gateways;{+}for parallel - Connect flows: use
-->for sequence flows;~~>for message flows (top level only) - Add events:
(( start ))and([ end ])for process boundaries;((! error ))for exception paths - Validate: run
scripts/validate-bpmn-beta.mjs; fix all errors - Normalise: run
scripts/normalize-bpmn-beta.mjsfor consistent whitespace and ordering - Lint: run
scripts/lint-process-model.mjsfor naming conventions and pool structure
bpmn-beta DSL Quick Reference
bpmn-beta
title Purchase Order Approval
pool Finance {
lane Requester {
(( start )) --> [Submit PO Request] --> {Approved?}
{Approved?} -- yes --> [Release to Vendor] --> ([ end ])
{Approved?} -- no --> [Return with Comments] --> ([ end ])
}
lane Finance Manager {
[Review PO Request] --> {Approved?}
}
}
Rules:
bpmn-betakeyword opens the diagrampool Name { }groups lanes; omit for flat (single-lane) diagramslane Name { }defines a swimlane- Message flows
~~>must be at top level, outside pool/lane blocks }closes the most recently opened pool or lane
Validation and Repair
scripts/validate-bpmn-beta.mjs <file.mmd>: schema and structural validationscripts/repair-bpmn-beta.mjs <file.mmd>: auto-fixes common structural errorsscripts/normalize-bpmn-beta.mjs <file.mmd>: normalises whitespace, IDs, and orderingscripts/lint-process-model.mjs <file.mmd>: naming convention and pool structure lint
Handoff Instruction
Pass bpmn-beta.mmd to okhp3-publication-handoff-packaging for bundle assembly. If ≥3 gateways, also pass pns.yaml to okhp3-decision-model-authoring.
Execution contract
Apply this contract on every run so the artifact is trustworthy and reusable:
- State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.
- Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.
- Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.
- Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.
- Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.
If any of the four scripts cannot run, check the diagram by hand against references/bpmn-beta-syntax.md, and state in the output which of validation, normalisation, repair, or linting was not run.
References
Load on demand:
references/bpmn-beta-syntax.md: complete bpmn-beta DSL keyword reference, element types, and flow operator rules
Scripts
scripts/validate-bpmn-beta.mjs: structural and schema validationscripts/normalize-bpmn-beta.mjs: whitespace and ordering normalisationscripts/repair-bpmn-beta.mjs: auto-repair for common structural errorsscripts/lint-process-model.mjs: naming and pool structure lint
Assets
assets/fixtures/process-model-example.yaml: metadata fixture for a purchase-approval bpmn-beta diagram
Evaluation and release status
This skill's output format is the one root-level evals/ category that is not broken: evals/bpmn-traceability/ checks that every task/event node in a bpmn-beta.mmd diagram carries a # pns:<activity-id> trace comment on the preceding line, using an inline validator in ../../scripts/run-eval-suite.mjs rather than an external module import (so it has no stale-path problem, unlike the four categories documented against okhp3-process-intake-and-scope and okhp3-process-narrative-authoring). It runs against two fixtures: bpmn-all-steps-traced.bpmn-beta.mmd (expected pass) and bpmn-orphan-task.bpmn-beta.mmd (expected fail). This was verified by static inspection of ../../scripts/run-eval-suite.mjs in this session, not by an actual live run, so it is labeled analytical, not live — but it is real, working eval design, and the one bright spot in G-1 of the maturity assessment. Note that the # pns:<activity-id> trace-comment convention this eval enforces is not currently documented anywhere in this SKILL.md or in references/bpmn-beta-syntax.md; an agent following only this package would not know to add it. That gap is worth closing in a future pass once the eval is confirmed live.
No dedicated evals/evals.json exists in this skill's own package. Evidence status: not-run (live) / analytical (the working-eval finding above, verified statically) for task quality and skill uplift.
Version 0.2.0 (this pass) added the compatibility declaration, per-script fallback instructions, and a sharper discovery-time boundary against non-BPMN diagram requests. Classified minor per the versioning table, not patch. No live regression run backs this bump; that limitation is disclosed, not implied away.
About
Part of the BP-SKILL: Business Process Agent Skill Suite, published in overkillhill/mermaid-diagram-bpmn. MIT License.