bpmn-generator

What this skill does

# BPMN 2.0 XML Generator

## Overview

This skill transforms process descriptions into fully compliant BPMN 2.0 XML files. It operates in two modes:

| Mode | Trigger | Workflow |
|------|---------|----------|
| **Interactive** | Natural language description, no file provided | Structured Q&A to gather requirements |
| **Document Parsing** | Markdown file path provided | Parse document structure, extract elements |

The generated XML includes:
- Complete process definitions with all BPMN elements
- Proper namespace declarations for BPMN 2.0 compliance
- Diagram Interchange (DI) data for visual rendering
- Phase comments for PowerPoint generation compatibility
- Layouts compatible with Draw.io, Camunda, Flowable, and bpmn.io

---

# MODE DETECTION

## Automatic Mode Selection

Determine the operating mode based on user input:

```text
IF user provides a markdown file path (.md):
    → Document Parsing Mode
ELSE IF user provides a natural language description:
    → Interactive Mode
```

### Document Parsing Mode Indicators
- File path ending in `.md`
- "convert this document", "parse this file"
- "generate BPMN from [filename]"
- Markdown content pasted directly

### Interactive Mode Indicators
- Brief process description without file
- "create a BPMN for...", "model a process that..."
- Questions about process design
- No structured document provided

### Preview Mode

Both modes support an optional `--preview` flag:

When `--preview` is specified:
1. Generate the complete BPMN XML in memory
2. Validate structure (namespace, elements, flows)
3. Display summary:
   ```
   Preview: /bpmn-generator
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Process: Order Fulfillment
   Source: Interactive mode

   Structure Summary:
     Pools: 1
     Lanes: 3 (Sales, Operations, Shipping)
     Tasks: 8 (5 user, 3 service)
     Gateways: 2 (1 exclusive, 1 parallel)
     Events: 2 (1 start, 1 end)

   Validation: PASSED
   Output file: order-fulfillment.bpmn
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   Save this file? (y/n):
   ```
4. Wait for user confirmation before saving
5. On 'n' or 'no': Exit without saving

---

# PART 1: INTERACTIVE MODE

Use this mode when the user provides a natural language description without a structured document.

## Interactive Question Framework

### Purpose

Initial process descriptions are rarely sufficient for optimal BPMN generation. This mode uses a structured clarification process to gather complete requirements before generating XML.

### Question Format

For EVERY clarifying question, use this EXACT format:

```markdown
## Question [N]: [Topic Category]

[Clear, specific question about the process]

### Options:

**A) [Recommended]**: [Specific answer]
   *Why*: [2-3 sentence reasoning explaining why this is the best choice]

**B)** [Alternative answer 1]
**C)** [Alternative answer 2]
**D)** Provide your own answer
**E)** Accept recommended answers for all remaining questions (auto-accept mode)

---
Your choice (A/B/C/D/E):
```

### Auto-Accept Mode

When the user selects option **E**:
1. Set internal flag: `AUTO_ACCEPT_MODE = true`
2. For all subsequent questions, automatically use the recommended answer
3. Log each auto-accepted decision
4. Before generating XML, present a summary:

```markdown
## Auto-Accepted Decisions Summary

| Question | Topic | Decision |
|----------|-------|----------|
| Q3 | Gateway Type | Exclusive Gateway (XOR) |
| Q4 | Error Handling | Boundary Error Event |
| ... | ... | ... |

Proceeding with XML generation using these decisions.
```

### Question Phases

Process questions in this specific order:

#### Phase 1: Process Scope (Questions 1-3)
- Process name and identifier
- Process trigger (start event type)
- Process completion states (end event types)

#### Phase 2: Participants (Questions 4-5)
- Single process vs. collaboration (multiple pools)
- Lanes/roles within pools

#### Phase 3: Activities (Questions 6-10)
- Main activities/tasks identification
- Task types for each activity
- **Task descriptions/documentation** (CRITICAL for PowerPoint generation)
- Task sequencing and dependencies
- Subprocess candidates

#### Phase 4: Flow Control (Questions 11-15)
- Decision points requiring gateways
- Gateway types (exclusive, parallel, inclusive, event-based)
- Default flows
- Loop/cycle detection

#### Phase 5: Events & Exceptions (Questions 16-19)
- Intermediate events (timer, message, signal)
- Boundary events on tasks
- Error handling approach
- Compensation requirements

#### Phase 6: Data & Integration (Questions 20-22)
- Data objects needed
- External system integrations
- Message flows (for collaborations)

#### Phase 7: Optimization Review (Question 23)
- Final review of proposed structure
- Opportunity for adjustments

### Session Commands

Support these standard session commands during Interactive mode:

| Command | Aliases | Action |
|---------|---------|--------|
| `help` | `?`, `commands` | Show available session commands |
| `status` | `progress` | Show current phase and questions completed |
| `back` | `previous`, `prev` | Return to previous question |
| `skip` | `next`, `pass` | Skip current question (use recommended) |
| `quit` | `exit`, `stop` | Exit without generating BPMN |

**When user types `help`:**
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session Commands
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  help      Show this help message
  status    Show current phase and progress
  back      Return to previous question
  skip      Skip question (uses recommended answer)
  quit      Exit without generating BPMN

Press E at any question to accept recommended
answers for all remaining questions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Implementation notes:**
- Commands are case-insensitive
- Check for session commands before processing input as an answer choice
- Unknown input that is not A/B/C/D/E should trigger the help message

### Adaptive Questioning

Skip questions that don't apply:
- Skip participant questions for simple single-pool processes
- Skip data questions if no data dependencies mentioned
- Skip error handling if process is straightforward
- Always ask critical questions: start event, main tasks, end events

---

# PART 2: DOCUMENT PARSING MODE

Use this mode when the user provides a markdown file containing a structured business process document.

## Document Analysis Steps

### Step 1: Identify Document Structure

Analyze the markdown document for structural elements that map to BPMN constructs. Key patterns: H1 = process name, H2/H3 "Phase/Step" = phase comments, numbered lists = tasks, role tables = lanes, conditional language = gateways, "begins when" = start events, "completes when" = end events. See `../references/markdown-parsing-guide.md` for the complete document structure mapping table.

### Step 2: Extract Process Metadata

From the document, extract:

```yaml
process_name: [from H1 or title]
process_id: [sanitized process_name, e.g., "SocialMediaCommunityManagement"]
description: [from executive summary or overview section]
version: [from document metadata if present]
roles: [list of all mentioned roles/actors]
phases: [ordered list of phase names from section headings]
```

### Step 3: Map Roles to Lanes

Use the lane mapping configuration in `../templates/lane-mapping.yaml` to assign colors. Read `references/bpmn-elements.md` for the complete role-to-lane color mapping table (Sales, Legal, Finance, IT, Implementation, Training, Customer Success, Support, Customer).

### Step 4: Parse Phases and Tasks

#### Phase Detection Patterns

Match headings like "## Step 1:", "### Phase 2:", or "## 1.1 Section" using H2-H4 with step/phase/stage keywords or numbered sections. See `../references/markdown-parsing-guide.md` for regex patterns.

#### Task Type Inference

Use the task type selection table in `references/bpmn-elements.md` to map markdown language to BPMN task types. Common shortcuts: "reviews/approves" = userTask, "system/API" =