/FlowForge

name: FlowForge
description: >
  TRIGGER when: user asks to draw, illustrate, or visualize any process, structure, or concept — "画个流程图",
  "draw an architecture diagram", "帮我画个对比图", "visualize this process", "make a diagram for this doc",
  or mentions 流程图/架构图/示意图/对比图/时序图/泳道图/时间线.
  Also trigger when user provides a document/article and asks for illustrations or diagrams.
  DO NOT trigger for: chart/plot requests (bar charts, line graphs — those need a charting library, not draw.io),
  or artistic image requests (logos, mascots, drawings of objects/people — those need an image tool).

FlowForge — Draw.io Diagram Skill

Generate professional diagrams as draw.io XML files. Supports 13 diagram types: flows, comparisons, layer stacks, cycles, trees, hub-and-spoke, columns, matrices, funnels, timelines, sequence diagrams, and swimlanes.

Usage

/FlowForge "OAuth 2.0 authorization code flow"
/FlowForge path/to/design-doc.md
/FlowForge "CI/CD pipeline" --type loop
/FlowForge "Monolith vs Microservices" --type compare --theme morandi
/FlowForge "System Architecture" --lang en

---

Workflow

Step 1: Understand & Propose (one confirmation, not three)

**If given a document:** read it fully, identify 1–3 places that benefit from a diagram, and for each note the insert position, the topic (one sentence), and the recommended type (see Diagram Type Reference).

**If given a concept directly:** identify the core message and pick the type via the Selection Guide.

Then present **one combined proposal** and ask for confirmation **once**. The proposal contains:

• Diagram type and theme (default: **tech-blue**; other options: morandi, mint, terracotta, indigo)
• An ASCII sketch: all nodes with labels, arrow directions and labels, grouping, color-role tags, layout direction

Example sketch:

Direction: left-to-right | Nodes: 4 | Type: flow | Theme: tech-blue

[primary] Code Commit  →  [process] Build  →  [process] Test  →  [accent] Deploy
                                                    ↓ (fail)
                                              [error] Alert

**Skip the confirmation entirely** when the request already pins everything down (user gave `--type`/`--theme` or an unambiguous description), or when no human can respond (subagent, batch, CI). In that case proceed with defaults and state your assumptions in the final report.

Step 2: Generate draw.io XML

1. Read [references/layouts.md](references/layouts.md) — the layout algorithm for the chosen type — and compute all coordinates from its formulas 2. Apply theme colors from [themes.md](themes.md) 3. Use element templates from [xml-reference.md](xml-reference.md) 4. For an unfamiliar type, read the matching example file listed in [examples.md](examples.md)

Step 3: Validate (mandatory)

python3 {skill_dir}/scripts/validate.py <file.drawio> --theme <theme>

This deterministically checks: XML well-formedness, unique ids, dangling arrow references, orthogonal edge style, canvas bounds, node overlap, z-order (containers before children), font sizes, text-fit estimates, and theme color compliance. **Fix every ERROR and re-run until clean.** WARNs are heuristics — judge each one, fix the real ones.

Step 4: Visual self-check (when draw.io CLI is available)

bash {skill_dir}/scripts/render.sh <file.drawio>   # writes a .png next to the file

If the script reports draw.io is not installed, skip this step (the user can enable it once with `brew install --cask drawio`). Otherwise **Read the PNG and inspect it with fresh eyes**: text overflowing nodes, crowded regions, arrows colliding with nodes, color rhythm, overall balance. Fix and re-render until it looks right — this catches what rules can't.

Step 5: Save & Deliver

Save the `.drawio` file to the output directory (see Configuration). After saving, report:

• File path (and the rendered PNG path if Step 4 ran)
• How to open: draw.io desktop app or https://app.diagrams.net

Iteration

If the user wants changes after viewing: 1. Read the current `.drawio` file 2. Modify the XML per feedback 3. Save as `{name}_v2.drawio` (preserve previous version), then re-run Steps 3–4

---

Configuration

Optional per-project config file `./.flowforge.json` (in the working directory, **never inside the skill directory** — the skill directory may be read-only or shared across projects):

{
  "defaultTheme": "tech-blue",
  "outputDir": "./diagrams",
  "language": "auto"
}

If the file is absent, use exactly these defaults — do not interview the user. `"language": "auto"` means match the user's language; technical abbreviations (API, LLM, CI/CD) stay in English regardless. Per-invocation flags (`--theme`, `--lang`) override config.

---

Diagram Type Reference

Core Types

| Type | Code | Best For | Example | |------|------|----------|---------| | Linear Flow | `flow` | Sequential steps A→B→C | API call flow, data pipeline | | Vertical Flow | `flow-vertical` | Top-down processes | Decision process, approval chain | | Comparison | `compare` | A vs B side by side | Traditional vs AI approach | | Layer Stack | `layers` | Tech stack, tiers | System architecture layers | | Cycle | `loop` | Iterative processes | ML training loop, CI/CD | | Tree | `tree` | Hierarchies, taxonomies | Org chart, decision tree | | Hub & Spoke | `hub` | Core concept + branches | Product feature map |

Extended Types

| Type | Code | Best For | |------|------|----------| | Parallel Columns | `columns` | 3+ parallel concepts | | Matrix | `matrix` | Multi-dimension comparison | | Funnel | `funnel` | Filtering, conversion | | Timeline | `timeline` | Version evolution, history | | Sequence | `sequence` | Component interactions | | Swimlane | `swimlane` | Cross-role processes (who does what) |

Selection Guide

| Content Pattern | Recommended Type | |----------------|-----------------| | Sequential steps | `flow` or `flow-vertical` | | Two things co