@bpmnkit/docspack 0.0.1

package/.llms/chunks/guides.claude-code-plugin.configuration.md

@@ -0,0 +1,126 @@
+# Claude Code Plugin — Configuration
+
+When the plugin is enabled, Claude Code prompts for two optional values:
+
+| Config key | Description |
+|---|---|
+| `camunda_endpoint` | Camunda 8 REST API endpoint (leave blank for local Reebe) |
+| `camunda_token` | Camunda 8 OAuth2 token (leave blank for local Reebe) |
+
+Leave both blank to use the local [Reebe engine](/cli/reebe).
+
+---
+
+
+## Skills
+
+### `/bpmnkit:implement <description>`
+
+The main entry point — natural language to a compiled, tested BPMN process.
+
+```
+/bpmnkit:implement order fulfillment with payment and inventory check
+/bpmnkit:implement employee onboarding process with HR approval
+```
+
+Resolves connectors, writes a `ProcessPlan`, compiles it with `casen synth`, tests it,
+scaffolds any missing workers, and asks where to deploy.
+
+---
+
+### `/bpmnkit:extend <file> <change request>`
+
+Extend an existing process from a natural-language change.
+
+```
+/bpmnkit:extend order-fulfillment.bpmn add a timeout boundary on the payment step
+```
+
+Lifts the process to plan form (`casen plan extract`), writes a small delta plan, and
+merges it in (`casen synth --merge`) — the summary is at the element level, not an XML diff.
+
+---
+
+### `/bpmnkit:agent [file] <description>`
+
+Design and add a Camunda AI Agent Sub-process.
+
+```
+/bpmnkit:agent add a support-triage agent with tools: search KB (http), escalate to human (user task)
+```
+
+Works out the provider/model, prompts, and tools (each mapped via connector search or an
+existing worker job type), then compiles and mock-tests the agent step. See
+[AI Agents](/guides/ai-agents/) for the full pattern.
+
+---
+
+### `/bpmnkit:connect <file> <step> <service>`
+
+Wire an existing plan step to an external system via a Camunda connector template.
+
+```
+/bpmnkit:connect order-fulfillment.bpmn notify_ops slack
+```
+
+---
+
+### `/bpmnkit:review [file.bpmn]`
+
+Run the full static analyzer and report deploy-readiness.
+
+```
+/bpmnkit:review
+/bpmnkit:review order-fulfillment.bpmn
+```
+
+Reports findings grouped by severity and ends with an explicit "Deploy-ready: yes/no" verdict.
+
+---
+
+### `/bpmnkit:test [file.bpmn]`
+
+Run scenario tests and report path/branch coverage.
+
+```
+/bpmnkit:test
+/bpmnkit:test order-fulfillment.bpmn
+```
+
+---
+
+### `/bpmnkit:deploy [file.bpmn] [--local|--camunda]`
+
+Gate on deploy-readiness, then deploy to local Reebe or Camunda 8.
+
+```
+/bpmnkit:deploy
+/bpmnkit:deploy order-fulfillment.bpmn --camunda
+```
+
+---
+
+### `/bpmnkit:instances [process-id] [--active|--failed]`
+
+List running process instances.
+
+```
+/bpmnkit:instances
+/bpmnkit:instances order-process --failed
+```
+
+---
+
+### `/bpmnkit:incidents [--process-id X]`
+
+List open incidents with suggested resolution actions.
+
+```
+/bpmnkit:incidents
+/bpmnkit:incidents --process-id order-process
+```
+
+---
+
+---
+Source: https://docs.bpmnkit.com/guides/claude-code-plugin/

package/.llms/chunks/guides.claude-code-plugin.md

@@ -0,0 +1,47 @@
+# Claude Code Plugin
+
+The bpmnkit Claude Code plugin adds BPMN-aware slash commands, autonomous agents, and
+ambient quality hooks directly into Claude Code. It's **CLI-first**: every skill drives
+`casen` via Bash — no MCP server, no proxy daemon. Every process is authored as a
+`ProcessPlan` JSON file and compiled deterministically by `casen synth`; no skill ever
+writes BPMN XML by hand.
+
+
+## Prerequisites
+
+Install the BPMNKit CLI globally:
+
+```sh
+npm install -g @bpmnkit/cli
+```
+
+That's it — nothing else needs to be running.
+
+
+## Installation
+
+### Local (development or team)
+
+```sh
+claude --plugin-dir ./plugins-claude/bpmnkit-claude
+```
+
+Or add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": [
+    { "path": "./plugins-claude/bpmnkit-claude", "scope": "project" }
+  ]
+}
+```
+
+### Via marketplace
+
+```sh
+/plugin marketplace add github:bpmnkit/monorepo
+/plugin install bpmnkit
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/claude-code-plugin/

package/.llms/chunks/guides.claude-code-plugin.reference-docs.md

@@ -0,0 +1,61 @@
+# Claude Code Plugin — Reference docs
+
+Every skill reads the relevant reference doc before authoring a plan:
+
+| File | Contents |
+|---|---|
+| `references/plan-format.md` | The `ProcessPlan` JSON schema + annotated, tested examples |
+| `references/connectors.md` | The 116-template Camunda connector catalog index |
+| `references/agentic.md` | The AI Agent Sub-process pattern, binding keys, a full example |
+| `references/feel.md` | FEEL syntax crib sheet + the `"="`-means-expression convention |
+| `references/modeling-style.md` | Camunda naming/structure conventions |
+
+---
+
+
+## Agents
+
+### `process-builder`
+
+Builds a complete BPMN process end-to-end from a description. Invoke directly:
+
+```
+Build me an invoice approval process for accounts payable
+```
+
+**What it does:**
+
+1. Asks clarifying questions (error paths, user tasks, deploy target)
+2. Checks domain patterns (`casen pattern list`/`get`)
+3. Resolves connectors, writes the plan
+4. Compiles it with `casen synth`
+5. Shows a preview and **waits for your approval**
+6. Tests the process, fixing failures by adjusting the plan
+7. Scaffolds a worker stub for every job type with no connector
+8. Gates on `casen lint --profile deploy`, then deploys to the chosen target
+9. Reports the process ID, files created, and next steps
+
+---
+
+### `incident-resolver`
+
+Triages and resolves open Camunda incidents. Invoke directly:
+
+```
+Investigate and resolve the open incidents
+```
+
+**What it does:**
+
+1. Fetches all open incidents (`casen incident list`)
+2. Groups by process + error type, sorted by count
+3. Investigates root cause per group
+4. **Proposes a fix and waits for your approval** before executing
+5. Executes approved fixes (retry jobs, resolve incidents, migrate instances)
+6. Verifies the count dropped
+7. Reports a resolution summary
+
+---
+
+---
+Source: https://docs.bpmnkit.com/guides/claude-code-plugin/

package/.llms/chunks/guides.deployment.ci-cd-deploy-on-push.md

@@ -0,0 +1,47 @@
+# Camunda 8 Deployment — CI/CD: Deploy on Push
+
+A typical GitHub Actions step:
+
+```yaml
+- name: Deploy BPMN processes
+  run: node scripts/deploy.mjs
+  env:
+    CAMUNDA_CLIENT_ID: ${{ secrets.CAMUNDA_CLIENT_ID }}
+    CAMUNDA_CLIENT_SECRET: ${{ secrets.CAMUNDA_CLIENT_SECRET }}
+    CAMUNDA_AUDIENCE: ${{ secrets.CAMUNDA_AUDIENCE }}
+    CAMUNDA_TOKEN_URL: ${{ secrets.CAMUNDA_TOKEN_URL }}
+```
+
+```typescript
+// scripts/deploy.mjs
+import { Bpmn } from "@bpmnkit/core";
+import { CamundaClient } from "@bpmnkit/api";
+import { readdir, readFile } from "node:fs/promises";
+
+const client = new CamundaClient({
+  baseUrl: "https://api.cloud.camunda.io",
+  auth: {
+    type: "oauth2",
+    clientId: process.env.CAMUNDA_CLIENT_ID,
+    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
+    audience: process.env.CAMUNDA_AUDIENCE,
+    tokenUrl: process.env.CAMUNDA_TOKEN_URL,
+  },
+});
+
+const files = await readdir("./processes");
+const resources = await Promise.all(
+  files
+    .filter((f) => f.endsWith(".bpmn"))
+    .map(async (f) => ({
+      name: f,
+      content: await readFile(`./processes/${f}`, "utf8"),
+    }))
+);
+
+const result = await client.process.deploy({ resources });
+console.log(`Deployed ${result.deployments.length} processes`);
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/deployment/

package/.llms/chunks/guides.deployment.deploying-a-process.md

@@ -0,0 +1,52 @@
+# Camunda 8 Deployment — Deploying a Process
+
+```typescript
+import { Bpmn } from "@bpmnkit/core";
+import { CamundaClient } from "@bpmnkit/api";
+
+const xml = Bpmn.export(
+  Bpmn.createProcess("invoice-approval")
+    .startEvent("start")
+    .userTask("review", { name: "Review Invoice" })
+    .endEvent("end")
+    .withAutoLayout()
+    .build()
+);
+
+const result = await client.process.deploy({
+  resources: [
+    { content: xml, name: "invoice-approval.bpmn" },
+  ],
+});
+
+console.log("Deployed version:", result.deployments[0]?.processDefinition?.version);
+```
+
+
+## Starting Process Instances
+
+```typescript
+const instance = await client.process.startInstance({
+  bpmnProcessId: "invoice-approval",
+  variables: {
+    invoiceId: "inv-1234",
+    amount: 2500,
+    submittedBy: "alice@example.com",
+  },
+});
+
+console.log("Instance key:", instance.processInstanceKey);
+```
+
+### With a Specific Version
+
+```typescript
+const instance = await client.process.startInstance({
+  bpmnProcessId: "invoice-approval",
+  version: 2,
+  variables: { invoiceId: "inv-5678" },
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/deployment/

package/.llms/chunks/guides.deployment.handling-jobs.md

@@ -0,0 +1,50 @@
+# Camunda 8 Deployment — Handling Jobs
+
+Register a long-poll job worker to process service tasks:
+
+```typescript
+const subscription = await client.jobs.activateAndProcess({
+  type: "send-email",
+  maxJobsToActivate: 5,
+  timeout: 30_000,
+  worker: "email-service",
+
+  handler: async (job) => {
+    const { to, subject, body } = job.variables;
+
+    await sendEmail({ to, subject, body });
+
+    await client.jobs.complete({
+      jobKey: job.key,
+      variables: { sent: true, sentAt: new Date().toISOString() },
+    });
+  },
+});
+
+// Stop the worker
+subscription.close();
+```
+
+
+## Querying Instances
+
+```typescript
+// List running instances
+const instances = await client.process.listInstances({
+  bpmnProcessId: "invoice-approval",
+  state: "ACTIVE",
+});
+
+// Get a specific instance
+const instance = await client.process.getInstance({
+  processInstanceKey: "2251799813685249",
+});
+
+// Get variables
+const variables = await client.variables.list({
+  processInstanceKey: instance.key,
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/deployment/

package/.llms/chunks/guides.deployment.managing-incidents.md

@@ -0,0 +1,33 @@
+# Camunda 8 Deployment — Managing Incidents
+
+```typescript
+// List open incidents
+const incidents = await client.incidents.list({
+  state: "ACTIVE",
+});
+
+// Resolve an incident (after fixing the underlying issue)
+await client.incidents.resolve({ incidentKey: incident.key });
+```
+
+
+## Lifecycle Events
+
+Use the TypedEventEmitter to react to API events:
+
+```typescript
+client.on("request", (e) => {
+  console.log(`→ ${e.method} ${e.url}`);
+});
+
+client.on("response", (e) => {
+  console.log(`← ${e.status} in ${e.durationMs}ms`);
+});
+
+client.on("error", (e) => {
+  metrics.increment("camunda.api.error", { url: e.url });
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/deployment/

package/.llms/chunks/guides.deployment.md

@@ -0,0 +1,49 @@
+# Camunda 8 Deployment
+
+The `@bpmnkit/api` package is a fully-typed Camunda 8 REST API client. Use it to deploy
+processes, start instances, and manage your cluster from Node.js scripts, backend services,
+or CI/CD pipelines.
+
+
+## Setup
+
+### SaaS (Camunda 8 Cloud)
+
+```typescript
+import { CamundaClient } from "@bpmnkit/api";
+
+const client = new CamundaClient({
+  baseUrl: "https://api.cloud.camunda.io",
+  auth: {
+    type: "oauth2",
+    clientId: process.env.CAMUNDA_CLIENT_ID,
+    clientSecret: process.env.CAMUNDA_CLIENT_SECRET,
+    audience: process.env.CAMUNDA_AUDIENCE,
+    tokenUrl: process.env.CAMUNDA_TOKEN_URL,
+  },
+});
+```
+
+### Self-Managed
+
+```typescript
+const client = new CamundaClient({
+  baseUrl: "http://localhost:8080",
+  auth: {
+    type: "bearer",
+    token: process.env.ZEEBE_TOKEN,
+  },
+});
+```
+
+### No Auth (local dev)
+
+```typescript
+const client = new CamundaClient({
+  baseUrl: "http://localhost:8080",
+  auth: { type: "none" },
+});
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/deployment/

package/.llms/chunks/guides.gateways.branching-inside-sub-processes.md

@@ -0,0 +1,27 @@
+# Gateways & Branching — Branching Inside Sub-Processes
+
+The full gateway and branching API works inside `subProcess()` callbacks too:
+
+```typescript
+.subProcess("handle-request", (sub) =>
+  sub
+    .startEvent("s")
+    .exclusiveGateway("route")
+    .branch("fast-path", (b) =>
+      b.condition("= priority == \"high\"")
+        .serviceTask("express", { taskType: "express-handler" })
+        .endEvent("done-fast"),
+    )
+    .branch("normal", (b) =>
+      b.defaultFlow()
+        .serviceTask("standard", { taskType: "standard-handler" })
+        .endEvent("done-normal"),
+    )
+)
+```
+
+Auto-join gateway insertion applies inside sub-processes the same way it does at the
+top level — converging branches automatically get a matching join gateway.
+
+---
+Source: https://docs.bpmnkit.com/guides/gateways/

package/.llms/chunks/guides.gateways.exclusive-gateway-xor.md

@@ -0,0 +1,41 @@
+# Gateways & Branching — Exclusive Gateway (XOR)
+
+Only one outgoing path is taken — the first branch whose condition evaluates to `true`.
+One branch should always be the default to handle the fallthrough case:
+
+```typescript
+import { Bpmn } from "@bpmnkit/core";
+
+const xml = Bpmn.export(
+  Bpmn.createProcess("approval-flow")
+    .startEvent("start", { name: "Request Submitted" })
+    .userTask("review", { name: "Review Request" })
+    .exclusiveGateway("approved?", { name: "Approved?" })
+    .branch("yes", (b) =>
+      b.condition("= approved")
+        .serviceTask("notify", { taskType: "send-email", name: "Send Approval" })
+        .endEvent("done")
+    )
+    .branch("no", (b) =>
+      b.defaultFlow()
+        .endEvent("rejected", { name: "Request Rejected" })
+    )
+    .withAutoLayout()
+    .build()
+);
+```
+
+### Conditions
+
+Branch conditions are [FEEL expressions](https://docs.camunda.io/docs/components/modeler/feel/):
+
+```typescript
+.branch("high-value", (b) =>
+  b.condition("= amount > 10000")
+    .serviceTask("manual-review", { taskType: "escalate" })
+    .endEvent("escalated")
+)
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/gateways/

package/.llms/chunks/guides.gateways.inclusive-gateway-or.md

@@ -0,0 +1,43 @@
+# Gateways & Branching — Inclusive Gateway (OR)
+
+One or more outgoing paths are taken based on conditions. All active paths converge at the
+matching inclusive join:
+
+```typescript
+.inclusiveGateway("options")
+.branch("express", (b) =>
+  b.condition("= expressShipping").serviceTask("fedex", { taskType: "fedex-ship" })
+)
+.branch("gift-wrap", (b) =>
+  b.condition("= giftWrap").serviceTask("wrap", { taskType: "wrap-items" })
+)
+.branch("standard", (b) =>
+  b.defaultFlow().serviceTask("standard-ship", { taskType: "usps-ship" })
+)
+.inclusiveGateway("join")
+.endEvent("end")
+```
+
+
+## Event-Based Gateway
+
+Waits for the _first_ of several events to occur, then takes that path:
+
+```typescript
+.eventBasedGateway("wait-for-event")
+.branch("payment", (b) =>
+  b.intermediateCatchEvent("payment-received", {
+    message: { name: "payment-confirmed", correlationKey: "= orderId" },
+  })
+  .endEvent("paid")
+)
+.branch("timeout", (b) =>
+  b.intermediateCatchEvent("payment-timeout", {
+    timer: { timeDuration: "PT24H" },
+  })
+  .endEvent("cancelled")
+)
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/gateways/

package/.llms/chunks/guides.gateways.nested-branching.md

@@ -0,0 +1,27 @@
+# Gateways & Branching — Nested Branching
+
+Branches can contain further gateways:
+
+```typescript
+.exclusiveGateway("route")
+.branch("enterprise", (b) =>
+  b.condition("= tier == \"enterprise\"")
+    .parallelGateway("enterprise-split")
+    .branch("account-mgr", (b2) =>
+      b2.userTask("assign-am", { name: "Assign Account Manager" })
+    )
+    .branch("onboarding", (b2) =>
+      b2.serviceTask("kick-off", { taskType: "onboarding-kit" })
+    )
+    .parallelGateway("enterprise-join")
+    .endEvent("enterprise-done")
+)
+.branch("self-serve", (b) =>
+  b.defaultFlow()
+    .serviceTask("auto-setup", { taskType: "self-serve-setup" })
+    .endEvent("self-serve-done")
+)
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/gateways/

package/.llms/chunks/guides.gateways.parallel-gateway-and.md

@@ -0,0 +1,26 @@
+# Gateways & Branching — Parallel Gateway (AND)
+
+All outgoing paths run concurrently. A matching parallel join gateway waits for all paths
+to complete before continuing:
+
+```typescript
+const xml = Bpmn.export(
+  Bpmn.createProcess("order-fulfillment")
+    .startEvent("start")
+    .parallelGateway("split")
+    .branch("warehouse", (b) =>
+      b.serviceTask("pick", { taskType: "warehouse-pick", name: "Pick Items" })
+    )
+    .branch("payment", (b) =>
+      b.serviceTask("charge", { taskType: "payment-charge", name: "Charge Card" })
+    )
+    .parallelGateway("join")   // waits for all branches
+    .serviceTask("ship", { taskType: "shipping", name: "Ship Order" })
+    .endEvent("end")
+    .withAutoLayout()
+    .build()
+);
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/gateways/

package/.llms/chunks/guides.patterns.how-matching-works.md

@@ -0,0 +1,17 @@
+# Pattern Library — How matching works
+
+`casen pattern get <query>` (via `findPattern()`) scores each pattern by counting how
+many of its keywords appear in the request. The highest-scoring pattern is selected.
+Exact pattern ID matches take priority over keyword scoring.
+
+Examples:
+
+| Request | Matched pattern |
+|---|---|
+| "invoice approval workflow" | `invoice-approval` |
+| "employee onboarding with Okta and Jira" | `employee-onboarding` |
+| "on-call incident escalation" | `incident-response` |
+| "custom blockchain process" | _(no match — Claude works from scratch)_ |
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/

package/.llms/chunks/guides.patterns.md

@@ -0,0 +1,26 @@
+# Pattern Library
+
+The pattern library (`@bpmnkit/patterns`) provides domain knowledge for common business
+processes. When you run `/bpmnkit:implement`, Claude checks the library for a matching
+pattern (`casen pattern list`/`get`) and uses its readme and worker specs as context while
+writing the `ProcessPlan` — the pattern's own `template` field predates the plan/synth
+pipeline and is a rough structural reference, not something pasted in directly.
+
+Patterns are hints, not templates. Claude adapts them to the specific request and ignores
+them entirely when nothing relevant matches.
+
+
+## Available patterns
+
+| Pattern ID | Domain | Typical use |
+|---|---|---|
+| `invoice-approval` | Finance / accounts payable | Multi-level invoice review and ERP payment trigger |
+| `employee-onboarding` | HR | Account provisioning, orientation scheduling, system access |
+| `supplier-contract-review` | Procurement / legal | Contract classification, risk scan, CLM storage, e-signature |
+| `incident-response` | IT / ops | Severity classification, on-call paging, post-mortem creation |
+| `loan-origination` | Financial services | Identity verification, credit check, risk scoring, disbursement |
+| `content-moderation` | Trust & safety | AI scan, action enforcement, CSAM reporting, user notification |
+| `order-fulfillment` | E-commerce / supply chain | Inventory validation, payment, warehouse order, shipment tracking |
+
+---
+Source: https://docs.bpmnkit.com/guides/patterns/