---
name: okhp3/okhp3-visual-process-modeling
source: https://app.decimal.ai/s/okhp3-okhp3-visual-process-modeling@1/SKILL.md
source_sha256: 5a8da692441d
---

# okhp3-visual-process-modeling

**OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://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](https://overkillhill.com) · [OverKill Hill P³](https://overkillhill.com)
Published at [github.com/OKHP3](https://github.com/OKHP3)
Part of the [OKHP3/skillz](https://github.com/OKHP3/skillz) Agent Skill library.
MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.