@bpmnkit/docspack 0.0.1

package/.llms/chunks/guides.ai-agents.the-aiagent-plan-step.md

@@ -0,0 +1,62 @@
+# AI Agents — The `aiAgent` plan step
+
+```json
+{
+  "kind": "aiAgent",
+  "id": "triage_agent",
+  "name": "Triage agent",
+  "provider": "anthropic",
+  "model": "claude-sonnet-5",
+  "providerInputs": {
+    "provider.anthropic.authentication.apiKey": "{{secrets.ANTHROPIC_API_KEY}}"
+  },
+  "systemPrompt": "You triage support tickets and post updates to Slack.",
+  "userPrompt": "=ticketText",
+  "tools": [
+    {
+      "id": "notify_slack",
+      "description": "Post a status update to the #support-escalations Slack channel.",
+      "connector": {
+        "template": "io.camunda.connectors.Slack.v1",
+        "values": {
+          "method": "chat.postMessage",
+          "token": "{{secrets.SLACK_OAUTH_TOKEN}}",
+          "data.channel": "#support-escalations",
+          "data.text": "placeholder"
+        }
+      },
+      "params": [
+        { "name": "message", "description": "The status update to post", "type": "string", "target": "data.text" }
+      ]
+    },
+    {
+      "id": "escalate",
+      "description": "Escalate the ticket to a human agent.",
+      "jobType": "escalate:1",
+      "params": [{ "name": "reason", "description": "Why this needs a human" }]
+    }
+  ],
+  "errorBoundary": {
+    "errorCode": "AGENT_FAILED",
+    "steps": [{ "kind": "end", "id": "agent_failed", "errorCode": "AGENT_FAILED" }]
+  }
+}
+```
+
+Compile it like any other plan:
+
+```sh
+casen synth support-triage.plan.json --output support-triage.bpmn
+casen lint lint support-triage.bpmn --profile deploy
+```
+
+Key points:
+
+- **Every tool needs an `id` and a `description`** written for the LLM to read, like briefing a teammate.
+- **A tool is either connector-backed (`connector`) or a plain job-worker (`jobType`)** — never both. Search the connector catalog first (`casen connector search`), fall back to `jobType` (with a scaffolded worker) only when no connector exists.
+- **A `params[].target` matching a connector value's key overrides it** — the standard way to let the LLM control one field of an otherwise-fixed connector call, as in `notify_slack` above: the channel is fixed, but the message text is supplied by the agent at call time. Give the overridden key a placeholder value in `connector.values`, not a real one.
+- **Always give the agent step an error boundary** — an unhandled agent/tool failure needs somewhere to go.
+- **Secrets always use `{{secrets.NAME}}`** — never a literal API key or token.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-agents/

package/.llms/chunks/guides.ai-implement.deploying.md

@@ -0,0 +1,49 @@
+# Building Processes with AI — Deploying
+
+```
+Deploy to local Reebe, deploy to Camunda 8, or skip?
+```
+
+- **Local Reebe** — deploys via `ZEEBE_ADDRESS` (default `http://localhost:26500`). Start Reebe first: `casen reebe start --port 26500`.
+- **Camunda 8** — deploys using the active `casen` profile. Set one up with `casen profile create`.
+- **Skip** — leaves the plan and BPMN file on disk for manual review and deployment.
+
+
+## Implementing workers
+
+Each scaffolded worker uses `@bpmnkit/worker-client`'s real polling API:
+
+```typescript
+// workers/validate-invoice/index.ts
+import { createWorkerClient } from "@bpmnkit/worker-client"
+
+const client = createWorkerClient({ workerName: "validate-invoice-worker" })
+
+for await (const job of client.poll("validate-invoice:1")) {
+  try {
+    // TODO: implement invoice validation
+    await job.complete({ /* output variables */ })
+  } catch (err) {
+    await job.fail(String(err))
+  }
+}
+```
+
+Start a worker for development:
+
+```sh
+cd workers/validate-invoice
+npm install
+npm start
+```
+
+Or start all workers at once:
+
+```sh
+casen worker start
+```
+
+See [Standalone Workers](/guides/workers-standalone/) for deployment options.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-implement/

package/.llms/chunks/guides.ai-implement.extending-an-existing-process.md

@@ -0,0 +1,10 @@
+# Building Processes with AI — Extending an existing process
+
+```
+/bpmnkit:extend invoice-approval.bpmn add a timeout boundary event to the approval task
+```
+
+This lifts the process back into plan form (`casen plan extract`), writes a small delta plan touching only the changed step, and merges it in (`casen synth --merge`) — the diff is reported at the element level, not as an XML diff.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-implement/

package/.llms/chunks/guides.ai-implement.lightweight-alternative-casen-skills-install.md

@@ -0,0 +1,28 @@
+# Building Processes with AI — Lightweight alternative: `casen skills install`
+
+If you don't want the full plugin, four minimal slash commands are available directly from the CLI — see [AIKit Skills](/cli/skills/):
+
+```sh
+casen skills install
+```
+
+This installs `/implement`, `/review`, `/test`, `/deploy` into `.claude/commands/`. Same underlying pipeline, less scaffolding around it (no `/extend`/`/agent`/`/connect`, no generated reference docs).
+
+
+## What gets created
+
+```
+project/
+  invoice-approval.plan.json         ← the source of truth — edit this, not the XML
+  invoice-approval.bpmn              ← compiled by casen synth
+  invoice-approval.bpmn.tests.json   ← scenarios, if the plan had a `tests` array
+  workers/
+    validate-invoice/
+      index.ts                       ← implement the job logic here
+      package.json
+      tsconfig.json
+      README.md
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-implement/

package/.llms/chunks/guides.ai-implement.md

@@ -0,0 +1,32 @@
+# Building Processes with AI
+
+BPMNKit's AI pipeline never asks an LLM to write BPMN XML. Every process is authored as a
+`ProcessPlan` JSON file and compiled deterministically by `casen synth` — this is what makes
+generated processes reliably valid, deployable, and easy to diff. The LLM's job is narrower and
+more reliable: write the plan, resolve connectors, and fix reported problems.
+
+
+## The pipeline
+
+```
+"implement X" (natural language)
+        │
+        ▼
+  ProcessPlan JSON  ──casen synth──▶  laid-out, deployable .bpmn
+        │                                    │
+        │                            casen lint --profile deploy
+        │                                    │
+        └──casen plan extract◀────────  casen test
+                (for later edits)
+```
+
+1. **Check for a reusable domain pattern** — `casen pattern list`/`get` (see [Pattern Library](/guides/patterns/)) surfaces domain context (regulations, conventions) and realistic worker specs, used as reference while writing the plan below — not pasted in as a `ProcessPlan` directly.
+2. **Resolve external interactions** — `casen connector search "<system>"` / `casen connector show <template-id>` find the right Camunda connector template and its required inputs, instead of guessing property keys.
+3. **Write the plan** — a `ProcessPlan` JSON file (`casen plan schema` prints the full format reference).
+4. **Compile** — `casen synth <plan>.json --output <file>.bpmn`. Problems are reported keyed by JSON path (e.g. `steps[2].connector.values.token`) — fix the plan, never the XML, and re-run.
+5. **Test** — a `tests` array in the plan compiles to a `<file>.bpmn.tests.json` sidecar automatically; run it with `casen test <file>.bpmn`.
+6. **Deploy-readiness gate** — `casen lint <file>.bpmn --profile deploy` must report zero errors before deploying.
+7. **Deploy** — `casen deploy deploy <file>.bpmn` (local Reebe) or `--target camunda8`.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-implement/

package/.llms/chunks/guides.ai-implement.the-claude-code-plugin.md

@@ -0,0 +1,21 @@
+# Building Processes with AI — The Claude Code plugin
+
+The richest way to drive this pipeline is the `bpmnkit` Claude Code plugin:
+
+```sh
+/plugin marketplace add github:bpmnkit/monorepo
+/plugin install bpmnkit
+```
+
+It's **CLI-first**: every skill drives `casen` via Bash — no MCP server, no proxy daemon. Each skill reads the relevant generated/hand-written reference doc (plan format, connector catalog, agentic pattern, FEEL syntax, modeling conventions) before authoring a plan.
+
+```
+/bpmnkit:implement an invoice approval process for accounts payable
+```
+
+Claude works through: resolve connectors → write the plan → compile → test → scaffold missing workers → present a summary → ask where to deploy.
+
+Related skills: `/bpmnkit:extend <file> <change>` (lift an existing process to a plan, apply a targeted delta, merge), `/bpmnkit:agent` (design an AI Agent Sub-process — see [AI Agents](/guides/ai-agents/)), `/bpmnkit:connect <file> <step> <service>` (wire an existing step to a connector), `/bpmnkit:review`, `/bpmnkit:test`, `/bpmnkit:deploy`.
+
+---
+Source: https://docs.bpmnkit.com/guides/ai-implement/

package/.llms/chunks/guides.ai.claude-api-example.md

@@ -0,0 +1,41 @@
+# AI Integration — Claude API Example
+
+Using the Anthropic SDK to generate a process from a description:
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { Bpmn, expand } from "@bpmnkit/core";
+import type { CompactDiagram } from "@bpmnkit/core";
+
+const anthropic = new Anthropic();
+
+async function generateProcess(description: string): Promise<string> {
+  const response = await anthropic.messages.create({
+    model: "claude-opus-4-6",
+    max_tokens: 2048,
+    system: `You are a BPMN process designer. Return only valid JSON matching the
+CompactDiagram schema. No explanation, no markdown — raw JSON only.`,
+    messages: [
+      {
+        role: "user",
+        content: `Create a BPMN process for: ${description}`,
+      },
+    ],
+  });
+
+  const json = response.content[0];
+  if (json?.type !== "text") throw new Error("Unexpected response type");
+
+  const compact = JSON.parse(json.text) as CompactDiagram;
+  const definitions = expand(compact);
+
+  return Bpmn.export(definitions);
+}
+
+const xml = await generateProcess(
+  "An invoice approval process where invoices over $10,000 need manager approval"
+);
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/ai/

package/.llms/chunks/guides.ai.mcp-server.md

@@ -0,0 +1,20 @@
+# AI Integration — MCP Server
+
+BPMN Kit ships with a Model Context Protocol (MCP) server that exposes process editing
+tools to any MCP-compatible AI client (Claude Desktop, Cursor, etc.):
+
+```sh
+# Start the MCP server
+casen mcp
+```
+
+Available MCP tools:
+- `get_diagram` — returns the current diagram as CompactDiagram JSON
+- `update_diagram` — applies a CompactDiagram diff
+- `add_service_task` — adds a single service task with Zeebe config
+- `add_http_call` — adds a pre-configured Camunda HTTP connector task
+- `apply_layout` — re-runs auto-layout on the current diagram
+- `validate` — validates the diagram and returns any schema errors
+
+---
+Source: https://docs.bpmnkit.com/guides/ai/

package/.llms/chunks/guides.ai.md

@@ -0,0 +1,32 @@
+# AI Integration
+
+BPMN Kit is designed from the ground up to work with AI agents. The compact intermediate
+format lets a complete process diagram fit in a single LLM prompt, and the builder API
+produces valid BPMN without requiring the AI to write raw XML.
+
+
+## The Compact Format
+
+Raw BPMN XML is far too verbose for LLMs — a simple three-node process generates ~60 lines.
+The compact format represents the same information as a small JSON object:
+
+```typescript
+import { Bpmn, compactify, expand } from "@bpmnkit/core";
+
+// Parse some BPMN XML
+const definitions = Bpmn.parse(existingXml);
+
+// Convert to compact format
+const compact = compactify(definitions);
+// compact is ~500 tokens for a typical approval workflow
+
+// Send to your LLM, get back a modified compact object
+const modified = await llm.modify(compact, "Add a parallel notification step after approval");
+
+// Convert back to full BPMN
+const updatedDefinitions = expand(modified);
+const updatedXml = Bpmn.export(updatedDefinitions);
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/ai/

package/.llms/chunks/guides.ai.minimal-empty-diagram.md

@@ -0,0 +1,32 @@
+# AI Integration — Minimal Empty Diagram
+
+When an AI agent needs to start fresh, use `Bpmn.makeEmpty()` to get a valid starting point
+with a single start event:
+
+```typescript
+import { Bpmn } from "@bpmnkit/core";
+
+// Returns a valid BPMN XML string — one start event, ready for an agent to extend
+const xml = Bpmn.makeEmpty("my-process", "My Process");
+```
+
+
+## Prompting Strategy
+
+For best results, give the LLM the compact diagram and a clear instruction. A good system
+prompt excerpt:
+
+```
+You are a BPMN process designer. The user will describe a business process and you will
+return a CompactDiagram JSON object.
+
+Rules:
+- Use camelCase IDs
+- Every service task needs a taskType string (the Zeebe worker subscription)
+- Use FEEL expressions for gateway conditions (start with "= ")
+- Always include a start event and at least one end event
+- Do not add fields that are not part of the CompactDiagram schema
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/ai/

package/.llms/chunks/guides.ai.openai-function-calling.md

@@ -0,0 +1,40 @@
+# AI Integration — OpenAI Function Calling
+
+Use function/tool calling for reliable structured output:
+
+```typescript
+import OpenAI from "openai";
+import { expand, Bpmn } from "@bpmnkit/core";
+
+const openai = new OpenAI();
+
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [
+    {
+      role: "user",
+      content: "Create a customer onboarding process with email verification and KYC check",
+    },
+  ],
+  tools: [
+    {
+      type: "function",
+      function: {
+        name: "create_bpmn_process",
+        description: "Create a BPMN process diagram",
+        parameters: compactDiagramJsonSchema, // export from @bpmnkit/core
+      },
+    },
+  ],
+  tool_choice: { type: "function", function: { name: "create_bpmn_process" } },
+});
+
+const toolCall = response.choices[0]?.message.tool_calls?.[0];
+if (!toolCall) throw new Error("No tool call");
+
+const compact = JSON.parse(toolCall.function.arguments);
+const xml = Bpmn.export(expand(compact));
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/ai/

package/.llms/chunks/guides.building-processes.boundary-events.md

@@ -0,0 +1,47 @@
+# Building Processes — Boundary Events
+
+### `.withBoundary()` — recommended
+
+`.withBoundary()` attaches a boundary event to the preceding task, lets you build the
+error/timeout path inline, then **automatically restores the cursor to the original task**
+so the main flow continues naturally:
+
+```typescript
+.serviceTask("charge", { name: "Charge Card", taskType: "payment-charge" })
+.withBoundary("on-fail", { errorCode: "PAYMENT_FAILED", cancelActivity: true }, (p) =>
+  p
+    .serviceTask("notify", { taskType: "send-email" })
+    .endEvent("end-failed"),
+)
+// cursor is back on "charge" — main flow continues here
+.serviceTask("fulfill", { name: "Fulfill Order", taskType: "warehouse-pick" })
+.endEvent("end-ok")
+```
+
+Timer boundaries work the same way:
+
+```typescript
+.serviceTask("slow-task", { taskType: "long-job" })
+.withBoundary("on-timeout", { timerDuration: "PT30S", cancelActivity: false }, (p) =>
+  p.serviceTask("escalate", { taskType: "alert" }).endEvent("escalated"),
+)
+.serviceTask("next-task", { taskType: "continue" })
+```
+
+### `.boundaryEvent()` — lower-level
+
+Use `.boundaryEvent()` directly when you need precise cursor control. It moves the
+builder cursor to the boundary event itself:
+
+```typescript
+.serviceTask("process-order", { taskType: "order-processor" })
+.boundaryEvent("timeout", {
+  attachedTo: "process-order",
+  cancelActivity: true,
+  timer: { timeDuration: "PT30M" },
+})
+.endEvent("timed-out")
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.call-activities.md

@@ -0,0 +1,47 @@
+# Building Processes — Call Activities
+
+Invoke a separate (reusable) process definition:
+
+```typescript
+.callActivity("run-subprocess", {
+  name: "Run Fulfillment Sub-Process",
+  calledElement: "fulfillment-process",
+  propagateAllChildVariables: false,
+  inputMappings: [
+    { source: "= orderId", target: "orderId" },
+  ],
+  outputMappings: [
+    { source: "= trackingNumber", target: "trackingNumber" },
+  ],
+})
+```
+
+
+## Multi-Process Diagrams
+
+`Bpmn.createDiagram()` assembles multiple processes into a single definitions document.
+This is useful for caller/callee pairs or any workflow that references another process:
+
+```typescript
+import { Bpmn } from "@bpmnkit/core";
+
+const defs = Bpmn.createDiagram("OrderSystem")
+  .process("order-flow", (p) =>
+    p
+      .startEvent("start")
+      .callActivity("run-payment", { processId: "payment-flow" })
+      .endEvent("end"),
+  )
+  .process("payment-flow", (p) =>
+    p
+      .startEvent("s")
+      .serviceTask("charge", { name: "Charge", taskType: "payment-charge" })
+      .endEvent("e"),
+  )
+  .build();
+
+const xml = Bpmn.export(defs); // both processes in one XML file
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.events.md

@@ -0,0 +1,57 @@
+# Building Processes — Events
+
+### Start Events
+
+```typescript
+// None start
+.startEvent("start")
+
+// Timer start (runs on a schedule)
+.startEvent("start-daily", {
+  timer: { timeCycle: "R/PT24H" },   // ISO 8601 repeating interval
+})
+
+// Message start
+.startEvent("start-on-order", {
+  message: { name: "order-received", correlationKey: "= orderId" },
+})
+```
+
+### Intermediate Events
+
+```typescript
+// Catch a timer (delay)
+.intermediateCatchEvent("wait-1h", {
+  timer: { timeDuration: "PT1H" },
+})
+
+// Catch a message (wait for external signal)
+.intermediateCatchEvent("wait-for-payment", {
+  message: { name: "payment-confirmed", correlationKey: "= orderId" },
+})
+
+// Throw a message
+.intermediateThrowEvent("notify-warehouse", {
+  message: { name: "order-ready" },
+})
+```
+
+### End Events
+
+```typescript
+// Normal end
+.endEvent("end")
+
+// Error end (triggers error boundary event)
+.endEvent("end-error", {
+  error: { code: "PAYMENT_FAILED", message: "Payment processing failed" },
+})
+
+// Message end
+.endEvent("end-notify", {
+  message: { name: "process-complete" },
+})
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.multi-instance.md

@@ -0,0 +1,20 @@
+# Building Processes — Multi-Instance
+
+Run a task or sub-process once per item in a collection:
+
+```typescript
+.serviceTask("notify-all", {
+  name: "Notify Each Customer",
+  taskType: "send-email",
+  multiInstance: {
+    parallel: true,                          // false = sequential
+    inputCollection: "= customers",
+    inputElement: "customer",
+    outputCollection: "results",
+    outputElement: "= { sent: true, email: customer.email }",
+  },
+})
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.service-tasks.md

@@ -0,0 +1,39 @@
+# Building Processes — Service Tasks
+
+A service task represents work done by a system. In Camunda 8 / Zeebe, a job worker picks up
+the task and completes it:
+
+```typescript
+.serviceTask("charge-card", {
+  name: "Charge Credit Card",
+  taskType: "payment-charge",       // worker subscribes to this type
+  taskHeaders: {
+    retries: "3",
+  },
+  inputMappings: [
+    { source: "= amount", target: "chargeAmount" },
+    { source: "= card.token", target: "token" },
+  ],
+  outputMappings: [
+    { source: "= transactionId", target: "paymentTransactionId" },
+  ],
+})
+```
+
+
+## User Tasks
+
+A user task waits for a human actor. Optionally attach a Camunda form:
+
+```typescript
+.userTask("review-order", {
+  name: "Review Order",
+  assignee: "= initiator",           // FEEL expression
+  candidateGroups: "approvers",
+  formKey: "camunda-forms:bpmn:review-form",
+  dueDate: "= now() + duration(\"P2D\")",
+})
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.sub-processes.md

@@ -0,0 +1,40 @@
+# Building Processes — Sub-Processes
+
+Embed a child process inline. Sub-processes support the full builder API including
+gateways and branching:
+
+```typescript
+.subProcess("handle-payment", (sub) =>
+  sub
+    .startEvent("sub-start")
+    .serviceTask("charge", { taskType: "payment-charge" })
+    .exclusiveGateway("charge-ok?")
+    .branch("success", (b) =>
+      b.condition("= success").serviceTask("receipt", { taskType: "send-receipt" }).endEvent("sub-end")
+    )
+    .branch("failure", (b) =>
+      b.defaultFlow().endEvent("sub-failed", { error: { code: "CHARGE_FAILED" } })
+    )
+)
+```
+
+### Event Sub-Processes
+
+An event sub-process starts when a boundary event fires:
+
+```typescript
+.eventSubProcess("compensation", {
+  triggeredByEvent: true,
+  startEvent: {
+    interrupting: false,
+    error: { code: "PAYMENT_FAILED" },
+  },
+}, (sub) =>
+  sub
+    .serviceTask("refund", { taskType: "issue-refund" })
+    .endEvent("refunded")
+)
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

package/.llms/chunks/guides.building-processes.task-defaults.md

@@ -0,0 +1,18 @@
+# Building Processes — Task Defaults
+
+`.defaults()` sets process-wide defaults applied to all subsequent task calls.
+Useful when every service task in a process should share the same retry policy:
+
+```typescript
+Bpmn.createProcess("my-flow")
+  .defaults({ serviceTask: { retries: "5" } })
+  .startEvent("s")
+  .serviceTask("t1", { name: "Task 1", taskType: "worker-a" })  // retries: "5"
+  .serviceTask("t2", { name: "Task 2", taskType: "worker-b" })  // retries: "5"
+  .serviceTask("t3", { name: "Task 3", taskType: "worker-c", retries: "1" })  // override
+  .endEvent("e")
+  .build()
+```
+
+---
+Source: https://docs.bpmnkit.com/guides/building-processes/

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

@@ -0,0 +1,24 @@
+# Claude Code Plugin — Ambient Hooks
+
+The plugin installs two background hooks:
+
+| Hook | Trigger | What it does |
+|---|---|---|
+| SessionStart | Every Claude Code session | Checks `casen` is installed |
+| PostToolUse | After any Write or Edit | Silently lints any `.bpmn` file that was written |
+
+The PostToolUse hook means every `.bpmn` file you (or Claude) writes is automatically
+checked against the BPMNKit optimizer — zero extra steps.
+
+---
+
+
+## No MCP server required
+
+Unlike earlier versions of this plugin, none of the skills above call an MCP tool — they
+call `casen` directly via Bash. The separate `@bpmnkit/proxy` MCP server (`bpmn-aikit`)
+still exists for Claude Desktop, Cursor, or other MCP-only hosts, but it's unrelated to
+this plugin.
+
+---
+Source: https://docs.bpmnkit.com/guides/claude-code-plugin/