bpmn-workflow
Generate and maintain BPMN 2.0 diagrams linked to Gherkin scenarios
How do I install this agent skill?
npx skills add https://github.com/wellapp-ai/well --skill bpmn-workflowIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a workflow for generating and maintaining BPMN 2.0 process diagrams based on Gherkin feature specifications. It utilizes a specialized MCP server to handle diagram generation, Gherkin linking, and system-wide diagram composition. No malicious patterns were detected; the 'low' verdict reflects the standard attack surface for indirect prompt injection inherent in skills that process external documentation files.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
BPMN Workflow Skill
Generate BPMN 2.0 process diagrams from feature specifications, link them to Gherkin scenarios, and compose a system-wide workflow diagram.
When to Use
- After completing Ask mode (feature exploration) to visualize the flow
- When documenting system processes for stakeholders
- Before Plan mode to ensure all scenarios are captured
- When updating existing features with new scenarios
Prerequisites
- Feature has been explored in Ask mode with wireframes
- User flows have been identified
- API endpoints (if any) have been specified
Instructions
Phase 1: Gather Feature Context
Step 1.1: Check for existing .feature files
Glob docs/bpmn/features/**/*.feature
If found, parse existing scenarios:
CallMcpTool:
server: "bpmn-mcp"
toolName: "read-feature"
arguments: { "featurePath": "docs/bpmn/features/{feature-id}/{feature-id}.feature" }
Step 1.2: If no .feature file exists, generate scenarios from:
- Ask mode wireframes (each screen = potential scenario)
- User flow descriptions
- API endpoints defined (CRUD operations = scenarios)
- Edge cases identified (error states, empty states)
Phase 2: Generate Gherkin (if needed)
If generating new scenarios, structure them as:
Feature: [Feature Name]
As a [user type]
I want to [action]
So that [benefit]
Scenario: [Happy path name]
Given [precondition]
When [action]
Then [expected result]
Scenario: [Error case name]
Given [precondition]
When [invalid action]
Then [error handling]
Scenario naming conventions:
- Happy path:
Successful [action],[Action] completes - Validation:
[Action] with invalid [field] - Error:
[Action] when [error condition] - Edge:
[Action] with [edge case]
Phase 3: Generate BPMN
Call the generate-bpmn MCP tool:
CallMcpTool:
server: "bpmn-mcp"
toolName: "generate-bpmn"
arguments: {
"featureId": "{feature-id}",
"featureName": "{Feature Name}",
"scenarios": [
{
"id": "{scenario-id}",
"name": "{Scenario Name}",
"steps": [
{ "keyword": "Given", "text": "{step text}" },
{ "keyword": "When", "text": "{step text}" },
{ "keyword": "Then", "text": "{step text}" }
]
}
],
"outputPath": "docs/bpmn/features/{feature-id}/{feature-id}.bpmn"
}
Phase 4: Create Manifest Link
Link BPMN elements to Gherkin scenarios:
CallMcpTool:
server: "bpmn-mcp"
toolName: "link-gherkin"
arguments: {
"featureId": "{feature-id}",
"featureName": "{Feature Name}",
"bpmnFile": "docs/bpmn/features/{feature-id}/{feature-id}.bpmn",
"featureFile": "docs/bpmn/features/{feature-id}/{feature-id}.feature"
}
This creates docs/bpmn/features/{feature-id}/manifest.json with traceability links.
Phase 5: Compose System Diagram
Update the master system diagram:
CallMcpTool:
server: "bpmn-mcp"
toolName: "compose-system"
arguments: {
"systemName": "Well Platform",
"featuresDir": "docs/bpmn/features",
"outputPath": "docs/bpmn/system.bpmn"
}
Output Format
After completing all phases, present:
## BPMN Workflow Generated
### Files Created/Updated
| File | Status | Description |
|------|--------|-------------|
| `docs/bpmn/features/{id}/{id}.feature` | Created/Updated | [N] scenarios |
| `docs/bpmn/features/{id}/{id}.bpmn` | Created | Process diagram |
| `docs/bpmn/features/{id}/manifest.json` | Created | [N] links |
| `docs/bpmn/system.bpmn` | Updated | Added {Feature Name} pool |
### Scenarios Mapped
| Scenario | BPMN Element | Steps |
|----------|--------------|-------|
| [Name] | Task_{id} | [N] |
### System Diagram
[ASCII representation of system pools]
┌─────────────────┐ ┌─────────────────┐
│ Auth │────▶│ Workspaces │
│ • Login │ │ • Create │
│ • Register │ │ • Switch │
└─────────────────┘ └─────────────────┘
BPMN Element Mapping
| Gherkin Concept | BPMN Element |
|---|---|
| Scenario | UserTask |
| Given steps | Documentation (preconditions) |
| When steps | Documentation (action) |
| Then steps | Documentation (expected) |
| Feature | Process |
| Background | Subprocess (shared) |
Storage Structure
docs/bpmn/
├── README.md # Documentation
├── system.bpmn # Master system diagram
└── features/
└── {feature-id}/
├── {feature-id}.bpmn # Feature process diagram
├── {feature-id}.feature # Gherkin scenarios
└── manifest.json # BPMN ↔ Gherkin links
Related Skills
- problem-framing - Defines the problem before BPMN generation
- competitor-scan - Research how competitors document workflows
- design-context - Ensures BPMN aligns with existing patterns
Troubleshooting
No MCP server available:
- Ensure bpmn-mcp is configured in
.cursor/mcp.json - Check that
@wellapp/bpmnpackage is built
Invalid BPMN generated:
- Validate with
validate-bpmntool - Check scenario IDs are unique
- Ensure step keywords are valid (Given/When/Then/And/But)
Manifest links broken:
- Re-run
link-gherkinafter updating scenarios - Ensure scenario IDs match between .feature and manifest
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wellapp-ai/well/bpmn-workflow">View bpmn-workflow on skillZs</a>