camunda

Use when implementing, fixing, or reviewing Zeebe engine code in zeebe/engine/ — BPMN process execution, DMN decision evaluation, job lifecycle, user/identity management, batch operations, variables, deployments, signals, messages, timers, multi-tenancy, or authorization. Also when modifying or reviewing processors, event appliers, state classes, record value types, intents, or engine tests.

Parse and compare async-profiler CPU flamegraphs from Camunda/Zeebe brokers — benchmark nodes or production. Use when investigating a CPU regression or outlier with .html flamegraphs (e.g. from dashboard.benchmark.camunda.cloud daily runs, or pulled from a live cluster/customer incident) — attribute a node's CPU to Zeebe subsystems and diff a suspect run against a healthy baseline.

Diagnose failing GitHub Actions runs and propose fixes. Use when given a GHA run/job URL, or asked why CI failed, why a job failed, what broke in a run, or to fix a red check on a PR.

Authors and refactors GitHub Actions workflows and composite actions for this monorepo using required conventions, minimal permissions, pinned SHAs, and observability steps. Use when creating or restructuring CI workflows.

Use when adding support for a new event or metric in the analytics exporter at zeebe/exporters/analytics-exporter/ — creating handlers, adding AnalyticsAttributes, registering in the HandlerRegistry, and writing tests. Also use when modifying existing handlers or attributes.

Triages a flood of CI incidents in camunda/camunda. Use when multiple CI incidents open in a short window and the medic needs to orient fast — find the shared pattern, identify outliers, and know what to do next. Re-runnable as new incidents arrive.

Shepherd one or more camunda/camunda PRs through flaky CI and the merge queue to merged. Accepts a list of PRs (e.g. a merge plus its backports). Use when asked to babysit, shepherd, watch, drive, or "get merged" one or more PRs, or to keep retrying CI until they land.

Use when migrating any Operate page from operate/client/ to the orchestration cluster webapp. Always read frontend-migrator first — this skill adds Operate-specific overrides, the migration loop protocol, and page-by-page context.

Use this skill to model and configure AI agents in Camunda 8 BPMN using the AI Agent Sub-process connector — an LLM driver applied to an ad-hoc subprocess with tools as BPMN activities. Use for: shaping the ad-hoc subprocess that hosts the agent, defining tools as service/script/user tasks or sub-processes, declaring LLM-supplied parameters via fromAi(), writing system/user prompt FEEL strings, wiring toolCallResult outputs, setting model and call limits, enabling multi-turn agent context, debugging tool-call resolution. Do not use for: the older AI Agent Task variant (see references/ai-agent-task.md), or generic BPMN authoring outside the agent host (use camunda-bpmn). **Workflow skill** — model the agent host, its tools, prompts, and limits. Covers c8ctl element-template apply for the AI Agent connector template.

Use this skill to install, configure, and operate c8ctl (the Camunda 8 CLI), the foundation the other camunda-* skills build on. Use for: starting a local cluster via c8run, connecting to Camunda 8 SaaS or Self-Managed via already-configured profiles, switching between connection profiles, managing connector secrets for the local cluster, switching c8ctl output modes for AI and scripting use, and any time another camunda-* skill calls c8ctl — load this first for the conventions (flags, profiles, output modes) shared across commands. Do not use for: writing BPMN (use camunda-bpmn), writing FEEL (use camunda-feel), or deploying and operating running processes (use camunda-process-mgmt — that skill builds on c8ctl). **Utility skill** — the foundation other camunda-* skills build on. Covers c8ctl cluster, c8ctl use profile, and the four default c8ctl plugins.

Use this skill to create, edit, and validate BPMN 2.0 process diagrams for Camunda 8 (Zeebe). Use for: new BPMN processes, modifying existing diagrams, adding tasks/gateways/events/subprocesses, configuring Zeebe extensions (taskDefinition, ioMapping, loop characteristics), validating BPMN XML. Do not use for: writing FEEL expressions inside BPMN (use camunda-feel), designing form schemas (use camunda-forms), or deploying and running processes (use camunda-process-mgmt). **Workflow skill** — multi-step BPMN authoring. Covers c8ctl bpmn lint for validation.

Use this skill to browse, configure, and apply pre-built Camunda connectors (REST, Slack, Kafka, AWS, etc.) via element templates (also known as connector templates). Use for: discovering available connector templates, inspecting their properties, applying a template to a service task or message event, configuring input mappings (URLs, request bodies, secrets) and result expressions, understanding the element template schema, debugging connector configuration in BPMN. Do not use for: writing free-form REST calls in service tasks (this skill is specifically for templated connectors), or modelling the BPMN structure itself (use camunda-bpmn). **Workflow skill** — discover, inspect, then apply. Covers c8ctl element-template search, info, get-properties, apply, get, sync.

Use this skill FIRST for any Camunda 8 integration or BPMN step that talks to another system — Slack, REST/HTTPS, webhooks, Kafka, S3, internal microservices, AI/LLM agents. The right implementation can't be read off the request's keywords (a "webhook" might be an OOTB connector or a custom inbound one; "LLM" a custom worker or the AI Agent connector); this skill weighs the full requirements (reusability, throughput, in-process state, transport, decision style) and hands off to camunda-connectors, camunda-connectors-development, camunda-job-workers, or camunda-ai-agents. Do not use for the actual build — switch to the focused skill it points to.

Use this skill to author and run Camunda Process Test (CPT) suites that cover every BPMN gateway branch, DMN rule, and error boundary to 100%. Use for: scaffolding the `camunda-process-test-spring` harness, planning the minimum set of test segments for full element coverage, authoring `.test.json` instruction-based scenarios, running `mvn test`, parsing the CPT coverage report, deduplicating redundant segments. Do not use for: authoring the BPMN (use camunda-bpmn), writing FEEL or DMN expressions (use camunda-feel), deploying to a live cluster (use camunda-process-mgmt), UI or E2E tests against Operate or Tasklist. **Workflow skill** — segment-based authoring loop covering `mvn test`, coverage report parsing, and scenario deduplication.

Use this skill to build a custom Camunda 8 connector — outbound or inbound — when the OOTB catalog doesn't cover the integration. Two paths: a JSON-only element template on a protocol connector (no Java), or a Java connector via the Connectors SDK with annotation-driven template generation. Use for: choosing Path A (JSON-only protocol-connector template) vs Path B (custom Java); element template JSON; `OutboundConnectorProvider` + `@Operation` for outbound; `InboundConnectorExecutable` for webhook / subscription / polling inbound; SPI vs Spring-Bean registration; SaaS / SM / Hybrid hosting; element-template-generator Maven plugin. Do not use for: applying an OOTB connector (use camunda-connectors), worker-vs-connector decisions (use camunda-development), or job-worker handlers (use camunda-job-workers). **Workflow skill** — pick a path, write the template (and Java if Path B), register, host. Java 17+ on Path B.

Use this skill to look up Camunda 8 documentation. The official docs at docs.camunda.io are the source of truth for current behavior — FEEL function signatures, BPMN extension attribute shapes, REST API endpoints, version requirements, feature availability. Trigger any time you need to verify a Camunda specific against the current docs, including when you think you already know the answer — Camunda 8 evolves fast and training data drifts. If you start with a conceptual explanation and find yourself about to state specifics (defaults, names, syntax, version requirements), stop and invoke before writing those specifics.

Add or modify CI integration-test scenarios — new persistence layers, scenario entries in the composable registry (test/ci/registry/), features, shortnames, and lifecycle hooks (pre-install fixtures/scripts, post-deploy, pre-upgrade) with the TestLifecycleFixtures contract. Use when adding a new test scenario or persistence backend, wiring pre-install prerequisites like TLS secrets or a CloudNativePG cluster, or adding upgrade-flow cleanup hooks.

Debug a deployed Camunda cluster — kubectl recipes for failing pods, port-forwarding, secrets; inspecting effective Spring Boot config via /actuator/configprops; headless JVM remote debugging with jdb over JDWP. Use when pods are Pending/CrashLoopBackOff/ImagePullBackOff, a configmap or env var is not taking effect, or you need to inspect live JVM state in a pod.

Deploy Camunda 8 Self-Managed to Kubernetes with the deploy-camunda CLI — single scenarios, layered values composition, configuration profiles, CI matrix operations, SNAPSHOT image tags, offline rendering, and live deploy watching. Use when deploying a chart to a cluster, running or listing matrix scenarios, debugging values-layer merging, or watching a stuck install.

Run Camunda e2e/smoke tests against a deployed cluster — generate .env credentials with render-e2e-env.sh or deploy-camunda, run Playwright suites via c8e2e (distributed on-cluster runner) or --test-e2e, test multiple environments in parallel, and reproduce CI e2e failures locally. Use when running or debugging e2e/smoke tests, generating test credentials for a namespace, or reproducing a failing CI e2e job.

End-to-end fix verification on a live GKE cluster — pre-flight checklist (Docker credentials, kubectl context, helm dependencies, ingress hostname), deploy the exact CI scenario, watch it, generate credentials, reproduce the failure on main, verify the fix on the branch, clean up. Use when a chart change needs live-cluster verification before a PR, or when asked to reproduce/verify a fix against GKE.

Diagnose Helm values-merge surprises in subchart overrides — Helm's replace-arrays-wholesale merge vs deploy-camunda's name-keyed merge, neutralizing parent-chart array defaults, and Bitnami env-var source chains where duplicate names silently win. Use when a subchart value or env var override is not taking effect, an env var renders twice, or a parent-chart default needs to be removed.

Validate a PR locally before marking it Ready-for-Review — map the diff to CI tier-1/tier-2 scenarios, decode shortnames, run the minimum correct scenario set via deploy-camunda matrix run, verify tier-2 scenarios before merge, complete the RFR checklist, optionally self-check with crev. Use when preparing to mark a PR ready, asked which scenarios to run for a change, or validating tier-2 scenario changes the merge queue would otherwise catch.

Use when the user wants to track a phase of work within a feature, says "create an epic for phase X", "track this phase", or needs to group related tasks under a milestone. Epics sit between features and tasks in the hierarchy.

Use when the user asks to write an ADR, says "create an ADR for X", "document this decision", "we need an ADR", or whenever you're about to make a significant design choice — introducing a port/adapter/SPI, picking between viable approaches, altering data flow, adding a dependency, or establishing a project-wide convention. Default to invoking this skill for any architectural change.

Use when the user wants an orientation to this repo, says "tour", "show me around", "what can I do here", "how does this repo work", "I'm new here", or wants to know the available slash commands and project structure

Use when the user asks to track a task, says "create a task for X", "break this feature into tasks", "we need to implement X", or wants a small, self-contained unit of work captured as an issue (standalone or as part of a feature)

Use when the user reports a bug, says "track this bug", "this is broken", "the behavior should be X", or describes unexpected behavior they want fixed

Use when the user asks to document something in the codebase, says "document this", "add docs for", "write documentation for", or wants code-level documentation created or updated

Use when the user requests a new capability, says "we should be able to", "add support for", "I want to be able to", or describes functionality that doesn't exist yet

Use when applying a docs change to one or more older versioned releases. Covers finding equivalent files across versions, handling doc ID divergence, updating versioned sidebars, and PR conventions for backports.

Use when opening a pull request in camunda-docs. Covers reading the PR template, marking applicable checklist items, choosing labels, constructing the gh pr create command with --body-file, and adding the PR to the Documentation Team project.

Drive one or more pull requests to a review-ready state by pausing CI, requesting a GitHub Copilot review, fixing every finding, re-requesting until the review is clean, then re-running the tests and appending the exact ` [ready]` tag (leading space) to the end of the PR title. USE WHEN: the user invokes "/review-loop", or says "pause the CI and get a Copilot review", "run the review loop", "fix what Copilot says and re-review", "drive this PR to ready", "mets le PR en ready". INVOKES: gh CLI (pr/api/run), the ci-feedback-loop skill for test triage. DO NOT USE FOR: merging PRs, or one-off log fetching (use ci-feedback-loop directly).

Iterate on a feature by fetching GitHub Actions CI logs, statuses, and artifacts to debug failures locally. USE WHEN: a PR has failing CI checks, the user asks to "debug CI", "fix the pipeline", "why is the test failing in CI", "fetch the CI logs", "check the CI", or wants to set up a fix-push-recheck loop. INVOKES: gh CLI (run list/view/download), local zip/json parsing. DO NOT USE FOR: triggering new runs, modifying workflows themselves, or general code review.

Use this when migrating or converting a Camunda 7 / camunda-bpm project to Camunda 8 — both Java/Spring code (JavaDelegates, ExternalTaskWorkers, ProcessEngine/RuntimeService client code, execution/task listeners, application.properties/application.yaml with camunda.* keys) and BPMN/DMN models (diagrams with the camunda: namespace). Handles code migration, model migration, or both.