---
title: "BA code-to-BPMN skills"
description: "Install and use Cursor Agent Skills and MCP servers to reverse-engineer Propay Laravel projects into BPMN 2.0 process models, business rules, user flows, and draw.io architecture diagrams."
canonical_url: "https://handbook.propay.co.za/analysis/ba-code-to-bpmn"
---
# BA code-to-BPMN skills

> Install and use Cursor Agent Skills and MCP servers to reverse-engineer Propay Laravel projects into BPMN 2.0 process models, business rules, user flows, and draw.io architecture diagrams.

## 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

<table>
<thead>
  <tr>
    <th>
      Layer
    </th>
    
    <th>
      Skill / tool
    </th>
    
    <th>
      Role
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Orchestration
    </td>
    
    <td>
      <code>
        propay-ba-code-to-bpmn
      </code>
    </td>
    
    <td>
      Seven-phase BA workflow (this handbook)
    </td>
  </tr>
  
  <tr>
    <td>
      Code discovery
    </td>
    
    <td>
      <code>
        spec-miner
      </code>
    </td>
    
    <td>
      Reverse-engineer code → EARS requirements
    </td>
  </tr>
  
  <tr>
    <td>
      Process model
    </td>
    
    <td>
      <code>
        bpmn
      </code>
    </td>
    
    <td>
      Create, layout, validate, lint <code>
        .bpmn
      </code>
      
       files
    </td>
  </tr>
  
  <tr>
    <td>
      Process QA
    </td>
    
    <td>
      <code>
        bpmn-inspector
      </code>
      
       MCP + <code>
        bpmn-review
      </code>
    </td>
    
    <td>
      Render PNG, detect layout issues
    </td>
  </tr>
  
  <tr>
    <td>
      Architecture visuals
    </td>
    
    <td>
      <code>
        drawio-skill
      </code>
      
       + <code>
        drawio
      </code>
      
       MCP
    </td>
    
    <td>
      <code>
        .drawio
      </code>
      
       diagrams and browser preview
    </td>
  </tr>
  
  <tr>
    <td>
      User stories (optional)
    </td>
    
    <td>
      <code>
        propay-jira-user-story
      </code>
    </td>
    
    <td>
      Turn gaps into Jira-ready stories
    </td>
  </tr>
</tbody>
</table>

**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:

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

Verify draw.io CLI (macOS):

```bash
/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](https://cursor.com/docs/context/skills) enabled

To edit `.bpmn` files manually, install [Camunda Modeler](https://camunda.com/download/modeler/) or the VS Code **BPMN Editor** extension.

## Install (recommended: sync script)

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

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

This installs into `~/.cursor/skills/`:

<table>
<thead>
  <tr>
    <th>
      Skill
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        propay-ba-code-to-bpmn
      </code>
    </td>
    
    <td>
      Handbook (<code>
        agent-skills/propay-ba-code-to-bpmn/
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        drawio-skill
      </code>
    </td>
    
    <td>
      <a href="https://github.com/Agents365-ai/drawio-skill" rel="nofollow">
        Agents365-ai/drawio-skill
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bpmn
      </code>
    </td>
    
    <td>
      <a href="https://github.com/architawr/claude-bpmn-skill" rel="nofollow">
        architawr/claude-bpmn-skill
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bpmn-review
      </code>
    </td>
    
    <td>
      <a href="https://github.com/Djaler/bpmn-inspector-mcp" rel="nofollow">
        bpmn-inspector-mcp
      </a>
    </td>
  </tr>
</tbody>
</table>

Override the skills directory if needed:

```bash
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):

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

<table>
<thead>
  <tr>
    <th>
      MCP server
    </th>
    
    <th>
      Tools
    </th>
    
    <th>
      When to use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        bpmn-inspector
      </code>
    </td>
    
    <td>
      <code>
        render_bpmn
      </code>
      
      , <code>
        validate_bpmn_layout
      </code>
    </td>
    
    <td>
      Visual QA after creating or editing <code>
        .bpmn
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        drawio
      </code>
    </td>
    
    <td>
      <code>
        open_drawio_xml
      </code>
      
      , <code>
        search_shapes
      </code>
    </td>
    
    <td>
      Open architecture diagrams in draw.io without CLI
    </td>
  </tr>
</tbody>
</table>

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

## Manual install

If you prefer step-by-step control:

### Propay orchestrator skill

```bash
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

```bash
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

```bash
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

```bash
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:

```text
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

```text
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

```bash
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

<table>
<thead>
  <tr>
    <th>
      Need
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Camunda/bpmn.io editable process
    </td>
    
    <td>
      <code>
        .bpmn
      </code>
      
       via <strong>
        bpmn
      </strong>
      
       skill
    </td>
  </tr>
  
  <tr>
    <td>
      Deadlock / stuck-token detection
    </td>
    
    <td>
      <strong>
        bpmn
      </strong>
      
       skill lint
    </td>
  </tr>
  
  <tr>
    <td>
      Layout overlap checks
    </td>
    
    <td>
      <strong>
        bpmn-inspector
      </strong>
      
       MCP
    </td>
  </tr>
  
  <tr>
    <td>
      System architecture, C4, sequence
    </td>
    
    <td>
      <strong>
        drawio-skill
      </strong>
      
       → <code>
        .drawio
      </code>
    </td>
  </tr>
</tbody>
</table>

## 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:

```bash
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

<table>
<thead>
  <tr>
    <th>
      Symptom
    </th>
    
    <th>
      What to check
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Skill not found in Cursor
    </td>
    
    <td>
      Restart Cursor; confirm <code>
        ~/.cursor/skills/{name}/SKILL.md
      </code>
      
       exists and folder name matches skill <code>
        name
      </code>
      
       in frontmatter
    </td>
  </tr>
  
  <tr>
    <td>
      BPMN lint fails on gateway
    </td>
    
    <td>
      Add a default sequence flow on exclusive gateways (one unguarded outgoing flow)
    </td>
  </tr>
  
  <tr>
    <td>
      draw.io export fails
    </td>
    
    <td>
      Install draw.io desktop; use full path <code>
        /Applications/draw.io.app/Contents/MacOS/draw.io
      </code>
      
       on macOS
    </td>
  </tr>
  
  <tr>
    <td>
      MCP tools unavailable
    </td>
    
    <td>
      Check <code>
        ~/.cursor/mcp.json
      </code>
      
      ; restart Cursor; confirm <code>
        npx
      </code>
      
       is on PATH
    </td>
  </tr>
  
  <tr>
    <td>
      bpmn npm errors
    </td>
    
    <td>
      Run <code>
        npm install
      </code>
      
       in <code>
        ~/.cursor/skills/bpmn/scripts/
      </code>
    </td>
  </tr>
</tbody>
</table>

## Related

- [Analysis introduction](https://handbook.propay.co.za/analysis/introduction)
- [Jira user story skill](https://handbook.propay.co.za/analysis/jira-user-story-skill) — draft stories from discovered gaps
- [Jira MCP in Cursor](https://handbook.propay.co.za/analysis/jira-mcp) — live Jira context while documenting
- [Figma MCP in Cursor](https://handbook.propay.co.za/analysis/figma-mcp) — design context for UI flows
- [Testing](https://handbook.propay.co.za/laravel/tests) — tie acceptance criteria to Pest tests

## Edit the orchestrator skill

1. Change files under `analysis/propay-ba-code-to-bpmn/` in [PropaySystems/handbook](https://github.com/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](https://github.com/PropaySystems/handbook/blob/main/analysis/propay-ba-code-to-bpmn/SKILL.md)


## Sitemap

See the full [sitemap](https://handbook.propay.co.za/sitemap.md) for all pages.
