Skip to content
Skills Library
Programming · Building & coding

setup-bpmn-to-code

/setup-bpmn-to-code

Sets up bpmn-to-code in an existing project with the Gradle plugin, the Maven plugin or the CLI, so the build generates a type-safe Process API from the BPMN models, with an optional GitHub Actions check that the committed API is up to date. Use when adding bpmn-to-code or BPMN code generation to a project, or a CI check for a stale generated API.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Sets up bpmn-to-code in an existing project with the Gradle plugin, the Maven plugin or the CLI, so the build generates a type-safe Process API from the BPMN models, with an optional GitHub Actions check that the committed API is up to date. Use when adding bpmn-to-code or BPMN code generation to a project, or a CI check for a stale generated API.

Arguments

/setup-bpmn-to-code [gradle|maven|cli]
Original author description

Sets up bpmn-to-code in an existing project with the Gradle plugin, the Maven plugin or the CLI, so the build generates a type-safe Process API from the BPMN models, with an optional GitHub Actions check that the committed API is up to date. Use when adding bpmn-to-code or BPMN code generation to a project, or a CI check for a stale generated API.

How it works

  1. IMPORTANT
  2. Step 1: Detect the stack
  3. Step 2: Ask what is left
  4. Step 3: Look up the version
  5. Step 4: Draft, confirm, apply
  6. Step 5: Verify
  7. Step 6: Point to the next step
Original SKILL.md headings · 83 lines, 650 words
SKILL.md preview
---
name: setup-bpmn-to-code
description: "Sets up bpmn-to-code in an existing project with the Gradle plugin, the Maven plugin or the CLI, so the build generates a type-safe Process API from the BPMN models, with an optional GitHub Actions check that the committed API is up to date. Use when adding bpmn-to-code or BPMN code generation to a project, or a CI check for a stale generated API."
argument-hint: "[gradle|maven|cli]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(./gradlew *), Bash(mvn *), Bash(./mvnw *), Bash(bpmn-to-code *)
---

# Skill: setup-bpmn-to-code

Configure bpmn-to-code once per project. The build-tool specifics live in `resources/`; read only the one that matches.

## IMPORTANT

- Show a draft of every change and wait for confirmation before editing.
- Never overwrite an existing bpmn-to-code configuration without asking. If one exists, offer to fix it instead, including a missing CI drift check.
- Use one version for every bpmn-to-code artifact (plugin, runtime, testing).
- Never edit generated files. They are rewritten on every run.

## Step 1: Detect the stack

1. **Build tool**, by the first match in the project root (or `$ARGUMENTS`):

   | Found | Resource |
   |---|---|
   | `build.gradle.kts` or `build.gradle` | [resources/gradle.md](resources/gradle.md) |
   | `pom.xml` | [resources/maven.md](resources/maven.md) |
   | a `*.csproj` | [resources/dotnet.md](resources/dotnet.md) |
   | neither, or a `package.json` | [resources/cli.md](resources/cli.md) |

   In a multi-module build, ask which module holds the BPMN files and set it up there.

2. **BPMN files:** Glob `**/*.bpmn`, excluding `build/`, `target/` and `node_modules/`. Derive `filePattern` from their common directory.
3. **Engine**, from the namespace the BPMN files use, not from the engine name:

   | Namespace in the BPMN files | `processEngine` | Typical engines |
   |---|---|---|
   | `xmlns:zeebe` | `ZEEBE` | Camunda 8 |
   | `xmlns:camunda` | `CAMUNDA_7` | Camunda 7, CIB seven, Fluxnova, Operaton models kept in the Camunda namespace |
   | `xmlns:operaton` | `OPERATON` | Operaton |

   If files use different namespaces, one task or execution per group is needed (see the resource).
4. **Output language:** `src/main/kotlin` → `KOTLIN`, `src/main/java` only → `JAVA`, a `*.csproj` → `CSHARP` (experimental), a `package.json` with TypeScript sources → `TYPESCRIPT` (experimental). The NuGet and npm packages are not published yet; tell the user before setting up either.
5. **Package:** suggest `<base package>.adapter.process` (or `.process` if the project has no `adapter` package). Look up the base package from existing sources.
6. **CI:** a `.github/workflows/` folder means GitHub Actions. Note the workflows that already run on pull requests.

## Step 2: Ask what is left

Ask only for what Step 1 could not settle, with the detected value as the default:

- Package of the generated code.
- **Where the generated code goes:**
  - **committed in the source folder** (`src/main/<lang>`, for .NET a folder like `Generated/`): visible in reviews, needs a CI drift check.
  - **in the build directory** (for .NET `obj/`): never committed, always fresh.
- Whether to add the **model validation test** with `bpmn-to-code-testing` (recommended). For .NET, offer the `BpmnToCodeValidate` target from [resources/dotnet.md](resources/dotnet.md) instead.
- With committed code and GitHub Actions: whether to add the **CI drift check** (recommended).

## Step 3: Look up the version

Read `<release>` from `https://repo1.maven.org/maven2/io/miragon/bpmn-to-code-runtime/maven-metadata.xml`. All artifacts and the CLI share that version.

## Step 4: Draft, confirm, apply

Read the matching resource and build the draft from it:

1. the plugin or CLI call
2. the runtime dependency where the resource says it is needed
3. the hook into the build
4. the testing dependency and the test, if wanted
5. the drift check from [resources/github-actions.md](resources/github-actions.md), if wanted

Show the draft and ask: *"Apply these changes? (yes / edit / cancel)"*. Then apply them.

## Step 5: Verify

1. Run the generation command from the resource.
2. List the generated files: `<Process>ProcessApi`, `ServiceTasks`, `Messages`, `ProcessVariables`, …
3. Run the model validation test if one was added.
4. If the drift check was added, tell the user it passes only once the generated files are committed.

If generation fails, read the reported rule violation and point to the element id. Do not disable rules to make it pass.

## Step 6: Point to the next step

- Hardcoded element ids, task types or message names in the code: `/migrate-to-bpmn-to-code-apis`.
- New engine glue:
  - `/create-worker` for a service task
  - `/create-process-adapter` for a start, message, signal or user task call
- Generated code committed in a project without GitHub Actions: recommend a CI job that regenerates and fails on `git status --porcelain`, see https://miragon.github.io/bpmn-to-code/guide/verify-in-ci.
Files in this package (6)
  • SKILL.md 5 KB
  • resources/cli.md 3 KB
  • resources/dotnet.md 2 KB
  • resources/github-actions.md 3 KB
  • resources/gradle.md 4 KB
  • resources/maven.md 3 KB

Versions

The database has no other skills named setup-bpmn-to-code.

Database snapshot: 13.11.2026 · package version 0a46a6cf874d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100migrate-to-bpmn-to-code-apis
    Replaces hardcoded BPMN element ids, job types and message names with references to the generated Process API, or rewrites 5.x API references to 6.x with --from-5x. Use when moving code onto the Process API or upgrading to bpmn-to-code 6.
  • 100create-quarkus-project
    Create a new Quarkus project (Maven or Gradle) with the Quarkus CLI, code.quarkus.io API or Maven plugin, choose extensions, and run it in dev mode. Use when asked to scaffold, bootstrap or start a Quarkus application or REST API.
  • 100bpmn
    Writes valid bpmn diagram source for uml-mcp (diagram_type=bpmn). Business Process Model and Notation Use when the user asks for bpmn or that notation; then call validate_uml / generate_uml / generate_uml_image.
  • 100bpmn-generator
    Generate BPMN 2.0 compliant XML files from natural language process descriptions OR from structured markdown business process documents. Use this skill when a user wants to create a BPMN workflow, convert a business process to BPMN XML, model a workflow diagram, or generate…
  • 100generate-rule-to-enforce-bpmn-styleguide
    Turns one rule of a BPMN_STYLE_GUIDE.md into a Kotlin validation rule for bpmn-to-code-testing and registers it in the model validation test. Use when a modeling convention should be enforced in the build.
  • 100automate-process
    Change an executable CIB seven BPMN model of this repo (bike-leasing.bpmn, cancel-bike-order.bpmn) and wire its glue code across the hexagon: edit the model with bpmn-cli, regenerate the typed process API, add ports, services, delegates and process-adapter methods, cover the new…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.