BA code-to-BPMN skills

What it is

The BA code-to-BPMN stack helps business analysts document existing Propay Laravel codebases by producing:

• Native BPMN 2.0 (.bpmn) AS-IS process flows — editable in Camunda Modeler or bpmn.io
• Business rules and system rules tables grounded in code evidence
• End-to-end user flows (HTTP/UI → backend → side effects)
• draw.io context and architecture diagrams (.drawio)

The Propay orchestrator skill propay-ba-code-to-bpmn ties the workflow together. It is published in this handbook under analysis/propay-ba-code-to-bpmn/.

Tool stack

Canonical process format: .bpmn (BPMN 2.0 XML). draw.io BPMN shapes are for informal stakeholder visuals only — not Camunda interchange.

Prerequisites

Install on your Mac before running the sync script:

brew install --cask drawio
brew install graphviz   # optional; needed for codebase autolayout in drawio-skill

Verify draw.io CLI (macOS):

/Applications/draw.io.app/Contents/MacOS/draw.io --version

You also need:

• Node.js >= 18 and npm (for the bpmn skill scripts)
• curl and git (for the install script)
• Cursor with Agent Skills enabled

To edit .bpmn files manually, install Camunda Modeler or the VS Code BPMN Editor extension.

Install (recommended: sync script)

From any machine with curl, git, and Node.js:

curl -sL https://handbook.propay.co.za/sync-ba-code-to-bpmn-skills.sh | bash

This installs into ~/.cursor/skills/:

Override the skills directory if needed:

SKILLS_DIR=/custom/path/.cursor/skills curl -sL https://handbook.propay.co.za/sync-ba-code-to-bpmn-skills.sh | bash

Restart Cursor after install so skills are discovered.

MCP configuration

Add these servers to ~/.cursor/mcp.json (merge with your existing entries):

{
  "mcpServers": {
    "bpmn-inspector": {
      "command": "npx",
      "args": ["-y", "bpmn-inspector-mcp"]
    },
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Confirm both servers show as connected in Cursor Settings → MCP.

Manual install

If you prefer step-by-step control:

Propay orchestrator skill

git clone --filter=blob:none --sparse https://github.com/PropaySystems/handbook.git
cd handbook
git sparse-checkout set analysis/propay-ba-code-to-bpmn
cp -R analysis/propay-ba-code-to-bpmn ~/.cursor/skills/propay-ba-code-to-bpmn

Or download from the handbook mirror:

https://handbook.propay.co.za/agent-skills/propay-ba-code-to-bpmn/SKILL.md

drawio-skill

git clone --depth 1 https://github.com/Agents365-ai/drawio-skill.git /tmp/drawio-skill
cp -R /tmp/drawio-skill/skills/drawio-skill ~/.cursor/skills/drawio-skill

bpmn skill

git clone --depth 1 https://github.com/architawr/claude-bpmn-skill.git /tmp/claude-bpmn-skill
cp -R /tmp/claude-bpmn-skill/skills/bpmn ~/.cursor/skills/bpmn
cd ~/.cursor/skills/bpmn/scripts && npm install

bpmn-review skill

npx bpmn-inspector-mcp install-skill --dest ~/.cursor/skills/bpmn-review

How to use

Open a Propay Laravel project in Cursor, then prompt the agent:

Using propay-ba-code-to-bpmn, document the payment capture flow:
- AS-IS BPMN 2.0 process
- business rules and system rules
- end-to-end user flow
- architecture context diagram in draw.io
Save outputs under docs/ba/payment-capture/

Seven-phase workflow

The orchestrator skill runs these phases:

1. Scope — Pick module/feature; list routes, Livewire, Vue, jobs, webhooks.
2. Discover — Trace code paths; write EARS requirements with file:line evidence (spec-miner).
3. Extract rules — business-rules.md and system-rules.md tables.
4. Model AS-IS — Create as-is-process.bpmn with pools, lanes, gateways (bpmn skill).
5. Validate — Run bpmn-tool.mjs validate + lint; use bpmn-inspector for layout QA.
6. Visuals — C4 context diagram in draw.io (drawio-skill).
7. Bundle — README.md index linking all artifacts.

Deliverable layout

docs/ba/{project}/{feature}/
├── README.md
├── as-is-process.bpmn
├── business-rules.md
├── system-rules.md
├── user-flows.md
├── reverse-spec.md
└── diagrams/
    ├── context.drawio
    └── context.drawio.png

Commit these to the application repo so BA documentation lives with the code.

Validate BPMN manually

node ~/.cursor/skills/bpmn/scripts/bpmn-tool.mjs validate docs/ba/my-feature/as-is-process.bpmn
node ~/.cursor/skills/bpmn/scripts/bpmn-tool.mjs lint docs/ba/my-feature/as-is-process.bpmn

Open the .bpmn file in Camunda Modeler for manual refinement.

draw.io vs native BPMN

Example output

A pilot documenting the handbook cursor-rules-sync flow lives in this repo at docs/ba/handbook/cursor-rules-sync/ — use it as a reference for structure and quality.

Updating

Re-run the sync script after handbook deploys or when upstream skills release updates:

curl -sL https://handbook.propay.co.za/sync-ba-code-to-bpmn-skills.sh | bash

Compare versions in analysis/propay-ba-code-to-bpmn/CHANGELOG.md.

Troubleshooting

Related

• Analysis introduction
• Jira user story skill — draft stories from discovered gaps
• Jira MCP in Cursor — live Jira context while documenting
• Figma MCP in Cursor — design context for UI flows
• Testing — tie acceptance criteria to Pest tests

Edit the orchestrator skill

1. Change files under analysis/propay-ba-code-to-bpmn/ in PropaySystems/handbook.
2. Bump the version in CHANGELOG.md.
3. Open a PR; after merge and deploy, BAs re-run sync-ba-code-to-bpmn-skills.sh.

Raw files:

• SKILL.md on GitHub