The process in the code, not the one in your head

Every team has two processes: the one people think the system runs and the one the code actually runs. PRDs, refinement meetings and onboarding usually describe the first. Incidents happen in the second.

Over the past week I built a tool to close that gap: a Claude Code skill that reads an application's code and reconstructs the business processes behind it as BPMN diagrams - validated, versionable, and ready to open in bpmn.io or Camunda Modeler. This post covers what it does, what it's for, and how it got here, which included opening a PR on Mermaid and then closing it.

Why BPMN, and why as text

BPMN is the standard notation for business processes. Someone in product, operations or compliance can read it: who takes part, where the decisions are, what happens when something goes wrong. It isn't a sequence diagram or a flowchart of functions. It's the process.

The problem is the tooling. BPMN usually lives in visual editors and in XML files nobody reviews in a pull request. A diagram that isn't reviewed goes stale, and a stale diagram is worse than none, because people trust it.

So I chose to write BPMN as text, Mermaid-style:

bpmn LR
  pool "Shop"
    start message s1 "Receive order"
    task:user t1 "Review order"
    xor g1 "Items available?"
    end e1 "Order shipped"
    end e2 "Order backordered"
  s1 --> t1 --> g1
  g1 -- "Yes" --> e1
  g1 -->|default| e2

Text goes into git, shows up in a diff, can be reviewed in a PR and - the part that matters most today - can be written by a language model.

What the skill does

You open the repository in Claude Code and ask it to map a business flow. The skill:

• discovers the flows from routes, queue consumers, scheduled jobs, status enums, webhooks and external integrations;
• models the business process, not the call graph: actors become pools and lanes, decisions become gateways, waits become timer events;
• validates the diagram, and when something is wrong the error message says how to fix it, so the agent iterates until it's valid;
• runs a style lint: gateways phrased as questions, named outcomes, parallel paths that join back, labels in business language rather than function names;
• builds a rules catalogue where every decision, limit and timeout points to the file and line it came from;
• exports BPMN 2.0 XML to open in bpmn.io or Camunda.

That catalogue is the part I care about most. A diagram without evidence is an opinion. A diagram where every gateway cites a line of code is a receipt.

Where it's already been used

I used the skill at a company I work with to map a flow that spans several services: an overview plus seven stages, with around 80 business rules, each tied to where it lives in the code. The map is now going into the team's docs, and I'm starting to use the same approach to discuss PRDs.

The most useful outcome wasn't the drawing. It was the list of gaps. When every rule has to name a file and a line, the ones that can't stand out: behaviour nobody documented, values that live outside the repository, decisions the team needs to confirm. That's exactly the kind of ambiguity I'd rather find before an incident than during one.

The Mermaid PR, and why I closed it

The original goal was native BPMN in Mermaid, so diagrams would render straight on GitHub. I implemented a bpmn diagram type with what I call an AI-first layer - a tolerant grammar, errors that suggest the fix, a spec ready to paste into a prompt - plus an export to BPMN 2.0 XML, and opened it as a draft on the official repository (mermaid-js/mermaid#8313).

Then Filip Sajdak commented. He'd been building bpmn-beta for weeks, in a series of PRs more complete than mine in almost every way: real swimlanes with pools and lanes, boundary events, subprocesses. Our PRs collided, and only one could merge without rework. The part he didn't have was exactly mine: the XML export and the AI-first layer.

Competing made no sense. I moved the AI-first layer onto his work, as a PR on his fork, and closed mine. He chose to hold that PR until the maintainers set a direction for BPMN in Mermaid, with a few design decisions that change what I did - and that's right: it's his work and his grammar. The XML export is on offer for the stage where the project decides where it should live (discussion on #2623).

It's the same lesson as always, now in open source: optimise the system, not my part of it.

Built in public

I published the skill and posted about it on X. Two replies became features the same day. One critique pointed out that several style rules lived only in the skill's instructions, not in code - that became the automatic lint. One question asked whether the skill regenerates the whole map on every run or only what changed - that became incremental mode: each map records the commit it came from, and the next run re-traces only the diagrams the change touched, keeping the same ids, so the diff shows only what really changed.

How to use it

The skill is open source (MIT) and installs as a Claude Code plugin:

claude plugin marketplace add rwspatin/bpmn-skill
claude plugin install bpmn-mapper@rwspatin

Then, inside a repository, something like: "Use the bpmn-mapper skill to map this service's order flow to BPMN."

Where I've seen the most value:

• PRDs: map what exists first, then plan the change on the same diagram, so the discussion is about the flow and not about a paragraph;
• onboarding: understand a system by its process before understanding it by its folders;
• audits and reviews: see where the rules are, and where they should be but aren't.

Two honest caveats. The syntax isn't in upstream Mermaid yet (it lives in my fork), so GitHub won't render a bpmn block. For now, commit the SVG and the .bpmn. And the diagram is a reconstruction by AI: the validator guarantees the structure, not that the process is right. Human review is still part of the method.

Repository, docs and examples: github.com/rwspatin/bpmn-skill.

• Renan