okhp3-visual-process-modeling

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

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-beta code
• PNS contains ≥3 decision_points → also trigger decision-model-authoring for a DMN table

When NOT to use this skill

• PNS has not been validated (score < 75) — complete process-narrative-authoring first
• 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 |

DMN Trigger Rule

When the PNS has ≥3 decision_points, hand off to decision-model-authoring concurrently with diagram generation. The BPMN gateway labels must match the DMN rule IDs.

Generation Workflow

1. Load PNS — read activity_sequence, decision_points, roles, exception_paths
2. Map to bpmn-beta — assign each activity to a lane based on actor_role_id
3. Render gateways — use {condition?} for exclusive gateways; {+} for parallel
4. Connect flows — use --> for sequence flows; ~~> for message flows (top level only)
5. Add events — (( start )) and ([ end ]) for process boundaries; ((! error )) for exception paths
6. Validate — run scripts/validate-bpmn-beta.mjs; fix all errors
7. Normalise — run scripts/normalize-bpmn-beta.mjs for consistent whitespace and ordering
8. Lint — run scripts/lint-process-model.mjs for 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-beta keyword opens the diagram
• pool Name { } groups lanes; omit for flat (single-lane) diagrams
• lane 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 validation
• scripts/repair-bpmn-beta.mjs <file.mmd> — auto-fixes common structural errors
• scripts/normalize-bpmn-beta.mjs <file.mmd> — normalises whitespace, IDs, and ordering
• scripts/lint-process-model.mjs <file.mmd> — naming convention and pool structure lint

Handoff Instruction

Pass bpmn-beta.mmd to publication-and-handoff-packaging for bundle assembly. If ≥3 gateways, also pass pns.yaml to decision-model-authoring.

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 validation
• scripts/normalize-bpmn-beta.mjs — whitespace and ordering normalisation
• scripts/repair-bpmn-beta.mjs — auto-repair for common structural errors
• scripts/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

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.