# umple-diagram-generator

> Generate diagrams (state machines, class diagrams) from natural language requirements using Umple. Use when user requests: (1) State machine diagrams (2) UML class diagrams (3) Diagram generation from text descriptions, (4) Any mention of Umple diagram generation, (5) Visual representation of states, transitions, events, classes, or relationships. Outputs SVG diagrams with organized folder structure.

- Author: Elwin Liu
- Repository: ElwinLiu/agents
- Version: 20260124140033
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ElwinLiu/agents
- Web: https://mule.run/skillshub/@@ElwinLiu/agents~umple-diagram-generator:20260124140033

---

---
name: umple-diagram-generator
description: "Generate diagrams (state machines, class diagrams) from natural language requirements using Umple. Use when user requests: (1) State machine diagrams (2) UML class diagrams (3) Diagram generation from text descriptions, (4) Any mention of Umple diagram generation, (5) Visual representation of states, transitions, events, classes, or relationships. Outputs SVG diagrams with organized folder structure."
allowed-tools: Bash(npx -y bun:*), Bash(command -v umple:*), Bash(umple:*), Bash(mktemp:*), Bash(mkdir:*), Bash(cat:*), Bash(cp:*), Bash(command -v dot:*), Bash(dot:*), Bash(date:*)
---

# Umple Diagram Generator Skill

## Overview

Generate an Umple `.ump` model from user requirements and render it to SVG via Umple + Graphviz.

### Supported Diagram Types & Guidance

| Diagram Type | Umple Generator | Guidance File | When to Use |
|--------------|-----------------|---------------|-------------|
| State Machine | `GvStateDiagram` | `references/state-machine-guidance.md` | User requests state machine diagram |
| Class Diagram | `GvClassDiagram` | `references/class-diagram-guidance.md` | User requests class diagram |
| Unsupported | - | - | Inform user it's not yet supported |

## Script

Entry point: `scripts/main.ts` (run with Bun via `npx -y bun`).

## Quick Start

```bash
# Folder mode: organized output with all files (.ump, .gv, .svg)
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "light-controller"

# Exact path mode: save SVG to specific file path
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./my-diagram.svg

# Class diagram with custom name
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "user-system" --type class-diagram
```

Replace `${SKILL_DIR}` with the absolute path to this skill directory.

### Script Options

| Option | Description |
|--------|-------------|
| `-i, --input <path>` | Input `.ump` file (required) |
| `-o, --output <path>` | Output path: directory for folder mode, or `.svg` file for exact path (required) |
| `-n, --name <name>` | Diagram name for folder mode (optional, triggers folder mode) |
| `-t, --type <type>` | Diagram type: `state-machine` (default), `class-diagram` |
| `-s, --suboption <opt>` | GvStateDiagram suboption (repeatable) |
| `--json` | JSON output with details |
| `-h, --help` | Show help |

### Output Modes

**Folder Mode** (when `--name` is specified or `--output` is a directory):
- Creates organized folder with timestamped name
- Includes all files: `.ump` (source), `.gv` (graphviz), `.svg` (diagram)

**Folder naming**:
- With `--name`: `<sanitized-name>_<timestamp>/`
- Without `--name`: `<diagram-type>_<timestamp>/`

**Example**:
```
diagrams/
└── light-controller_20260121_183045/
    ├── model.ump
    ├── model.gv
    └── model.svg
```

**Exact Path Mode** (when `--output` ends with `.svg`):
- Saves only the SVG file to the exact specified path
- Useful when user specifies a specific output location

**Example**:
```bash
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output /path/to/my-diagram.svg
# Result: /path/to/my-diagram.svg (only SVG, no folder created)
```

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Missing dependencies (umple or dot) |
| 2 | Umple validation/compilation failed |
| 3 | SVG generation failed or unsupported diagram type |

## Pre-flight checks (must do before running Umple)

### Dependencies

| Dependency | Check Command | Installation | Required |
|------------|---------------|--------------|----------|
| Umple CLI | `command -v umple` | [Download](https://cruise.umple.org/umpleonline/download_umple.shtml) | Yes |
| Graphviz | `command -v dot` | `brew install graphviz` | Yes |

If dependencies are missing, stop and inform the user.

## Workflow (do this every time)

### Step 1 — Clarify only what you must

If ambiguous, propose your plan and ask minimal clarifying questions:

| Diagram Type | Key Questions |
|--------------|---------------|
| State Machine | Initial state? Events? Final states? Guards/actions? |
| Class Diagram | Main entities? Attributes? Relationships? Multiplicities? |

### Step 2 — Write the Umple model

**Critical**: Read the appropriate guidance file from the table above before writing code.

### Step 3 — Determine output path and generate the diagram

**Agent should choose the appropriate mode**:
- **Folder mode** (recommended): Use when generating for user review/documentation
- **Exact path mode**: Use only when user explicitly specifies a file path

**Folder mode example**:

```bash
tmpdir="$(mktemp -d)"
cat >"$tmpdir/model.ump" <<'EOF'
// (generated Umple goes here)
EOF

npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output <output-dir> --name "<meaningful-name>" --type [state-machine|class-diagram]
```

**Folder naming guidelines**:
- Use `--name` with a descriptive name derived from user requirements (e.g., "user-authentication", "order-workflow")
- If no clear name from requirements, omit `--name` to use auto-generated name
- The script automatically adds timestamp to prevent conflicts

**Exact path mode example** (when user specifies):

```bash
npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output /path/specified/by/user.svg --type [state-machine|class-diagram]
```

### Step 4 — Validate output correctness

Check exit code (see table above). If non-zero, read error output, fix Umple, and retry up to 3 times.

## Repair loop (required)

On each failure:
1. Identify the root cause from script output (syntax error, unknown state, missing semicolon, etc.).
2. Apply a focused fix to the Umple model.
3. Re-run: `npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output <output-dir> --name "<name>" --type [state-machine|class-diagram]`

## Output contract

1. Specify which diagram type was generated.
2. Show the generated Umple code (single `umple` code block).
3. Confirm the exact command you ran.
4. **Folder mode**: Provide the output folder path and SVG file location.
   **Exact path mode**: Provide the SVG file path.

## Guardrails (do not skip)

- Never invent Umple syntax: if unsure, prefer a smaller model that is valid.
- Use **exact path mode** only when the user explicitly provides an `.svg` path; otherwise use folder mode.
- If `umple` or `dot` is missing, stop and ask the user to install them (do not try to install system deps).
- Keep Umple “code” inside Umple actions/guards minimal (no secrets, no real credentials, no I/O).

## Notes

- Prefer folder mode unless the user explicitly provides an `.svg` output path.
- Keep references one level deep (use `references/*` files directly from this doc).