From bpmn-to-code
Interactively creates a project-specific BPMN style guide handbook covering naming, allowed elements, IDs, topics, and engine-specific special cases.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bpmn-to-code:build-bpmn-styleguideThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Interactively author `BPMN_STYLE_GUIDE.md` — a **human-readable handbook** that documents how the team models BPMN processes. The document teaches developers what good models look like; embedded YAML annotations make the same document machine-parseable so `/validate-bpmn-style` and `/generate-rules-to-enforce-bpmn-styleguide` can enforce the rules.
Interactively author BPMN_STYLE_GUIDE.md — a human-readable handbook that documents how the team models BPMN processes. The document teaches developers what good models look like; embedded YAML annotations make the same document machine-parseable so /validate-bpmn-style and /generate-rules-to-enforce-bpmn-styleguide can enforce the rules.
bpmn-to-code-testing, which CI runs what). Consumers decide.BPMN_STYLE_GUIDE.md already exists, ask whether to overwrite, extend, or abort.AskUserQuestion for every user decision. Default to [RECOMMENDED] answers; let the user accept in one keystroke.resources/example-bpmn-style-guide.md before emitting. It is the canonical shape to copy.Load these files as needed during the wizard. They're part of the skill, not the project.
resources/example-bpmn-style-guide.md — canonical output shape. Emit files that match its structure.resources/engines/camunda-7.md — C7 supported elements, service-task kinds, async triple, variables, timers, transaction-boundary best practices.resources/engines/operaton.md — Operaton deltas vs. C7 (namespace).resources/engines/cib-7.md — CIB-7 deltas vs. C7 (none; uses C7 namespace).resources/engines/zeebe.md — Zeebe support matrix, job-worker model, correlation keys, FEEL timer expressions.The emitted file is Markdown that reads like documentation. Each rule block has:
Prose: the convention, the rationale, examples of good and bad.
A YAML annotation immediately after the prose:
<!-- rule:<kebab-case-slug> -->
```yaml
category: business-modeling | technical-configuration
severity: error | warning | info
applies-to: [<BpmnElementType...>]
validation: deterministic | llm | hybrid
pattern: "<regex>" # required when validation includes deterministic
engine: [CAMUNDA_7, ...] # optional; defaults to the file's top-level Engine:
The <!-- rule:slug --> HTML comment is invisible when the Markdown is rendered but survives in source — tools find rules by this anchor. Any YAML block not preceded by such a comment is ignored.
validation fielddeterministic — fully checkable by regex or a structural check on the domain model. /generate-rules-to-enforce-bpmn-styleguide picks it up; /validate-bpmn-style runs the regex.llm — requires semantic judgement (naming quality, layout, notation choices). Only /validate-bpmn-style enforces it.hybrid — has both. The regex catches the shape; the AI linter also checks the semantic half using the rule's prose as the brief. Code generation emits only the deterministic half.**/*.bpmn (exclude build/, target/, node_modules/).serviceTask_Xxx, Activity_Xxx).xmlns:camunda → CAMUNDA_7 / CIB-7; xmlns:zeebe → ZEEBE; xmlns:operaton → OPERATON.resources/engines/<engine>.md. This tells you which elements, implementation kinds, and attributes the engine supports — don't propose rules for features the engine lacks (e.g. asyncBefore on Zeebe; JAVA_DELEGATE on Zeebe).AskUserQuestion for:
Engine: header but mention the distinction in prose).Write the document header: title, Engine: …, Language: …, and an intro paragraph that previews the three sections.
Elicit the mental model. These rules are mostly validation: llm.
Ask about (grouped into one or two AskUserQuestion calls):
User Task for human work, Message Catch Event for external input, etc.).[RECOMMENDED] is to include these as severity: info rules.For each rule, emit prose + <!-- rule:slug --> + YAML.
Mostly validation: deterministic or hybrid.
Ask about (one AskUserQuestion is usually enough, since most teams have a fixed opinion):
type_DescriptionInCamelCase.process_ prefix, no version suffix.<serviceName>.<myState>. Offer hybrid if the team wants the semantic half ("serviceName matches bounded context") enforced too.<serviceName>.<elementIdWithoutPrefix>. Same hybrid offer.EXTERNAL_TASK. Skip for Zeebe.llm info-level guidance.Emit each rule with prose (schema + good/bad examples) + YAML annotation.
Engine-specific patterns. Don't just offer — analyze the user's models first, then ask them to choose.
resources/engines/camunda-7.md. That table (external service tasks: no async; start / user / boundary / intermediate-catch: asyncAfter=true) is the default. Non-external service-task kinds (JAVA_DELEGATE, DELEGATE_EXPRESSION, EXPRESSION) have no default — don't emit a rule for them.AskUserQuestion. Four options:
asyncBefore on service tasks, encode that).<!-- rule:async-continuations --> block in the Special Cases section with validation: deterministic (per-element attribute check). Use the example file's Special Cases section as the prose template.Default: every <bpmn:message> has a <zeebe:subscription correlationKey="…">. Analyze existing messages, then ask via AskUserQuestion: adopt default / use detected (maybe the team has a relaxed rule) / skip.
If the user declines everything, omit the ## ⚠️ Special Cases section entirely.
Engine: + Language: header## 🎨 Business Modeling with the emitted rule blocks## 🔧 Technical Configuration with its rule blocks## ⚠️ Special Cases (if any)## Validation Reference (the field schema table — copy from the example verbatim)AskUserQuestion asks for confirmation or adjustments.BPMN_STYLE_GUIDE.md to the project root./validate-bpmn-style to lint BPMN files against the guide./generate-rules-to-enforce-bpmn-styleguide to generate deterministic rules for the testing module.validation: llm, the prose IS the rule (there's no regex). Make the prose concrete enough that /validate-bpmn-style has a clear brief.validation: hybrid, the prose should make the two halves explicit ("The shape is enforced by regex; the semantics are checked by the AI linter — it verifies that…").npx claudepluginhub miragon/bpmn-to-code --plugin bpmn-to-codeCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.