Editable product swimlanes that survive the next revision.
product-swimlane-drawio turns a confirmed product or business process into a native .drawio file. The agent handles semantics; a deterministic local engine handles layout, routing, validation, and safe incremental updates. Your latest locally saved Draw.io file remains the canonical source.
Semantic → Deterministic → Editable → Incremental → Validated
Generation requires neither Draw.io MCP nor the Draw.io application. Draw.io Desktop or diagrams.net is only needed when you want to visually edit or export the result.
Quick navigation: Why this exists · Example · Quick start · Install · Use · Incremental editing · Conservative migration · Validation · Scope
A language model is good at understanding owners, order, decisions, and returns. It is less reliable when asked to invent every coordinate and connector waypoint directly in Draw.io XML.
| Direct AI-generated XML | product-swimlane-drawio |
|---|---|
| Semantics and geometry are mixed in one fragile output | The process is first captured as a strict semantic model |
| Layout and routes vary between generations | A deterministic engine rebuilds the same input consistently |
| Manual edits are easily discarded | Stable IDs and geometry-aware patches preserve compatible local edits |
| A file opening successfully is treated as proof | Strict diagnostics and visual review are reported separately |
The result is built for the common product workflow: AI creates the first 80%, a person adjusts it locally, and later revisions preserve the work already done.
- Editable: native, uncompressed
.drawio; full-height vertical lanes; local drag-and-drop editing. - Reliable: confirmed main path; deterministic layout; orthogonal routing; separate return and retry channels; phase bands.
- Maintainable: stable semantic IDs;
inspect,patch, andcompare; geometry-preserving defaults; safe lane and node changes. The conservative migration interface adds an explicit path for eligible old managed diagrams. - Verifiable: strict schema; structured diagnostics; routing and label checks; atomic output receipts with SHA-256.
The fictional request review example uses the v3 approval-loop pattern with four lanes, one decision, a compact rework loop, long-form spacing, and a phase rail. It includes the prompt, semantic specification, and exported preview.
The semantic specification deterministically generates a native editable .drawio file locally and passes strict validation with zero warnings. Generated .drawio files stay outside the repository; the committed PNG is the GitHub-ready preview.
Install the Skill:
npx skills add zz-zed/product-swimlane-drawioThen ask your agent:
Use product-swimlane-drawio to create an editable vertical swimlane diagram.
First confirm the lane order, main path, branches, returns, and assumptions.
Do not generate files until I approve the structure.
All installation paths use the same canonical Skill under skills/product-swimlane-drawio. Python 3.10+ is required at runtime; Node.js is needed only when installing with npx skills. The complete Skill directory is the runtime unit: do not copy only the CLI script, because its adjacent private modules are required. No pip installation or PYTHONPATH setup is needed.
npx skills add zz-zed/product-swimlane-drawioThe installer detects compatible agents and asks where to install. Add -g for a shared user-level installation. The repository contains one Skill, so no --skill argument is needed.
Run inside Claude Code:
/plugin marketplace add zz-zed/product-swimlane-drawio
/plugin install product-swimlane-drawio@product-swimlane-drawio
codex plugin marketplace add zz-zed/product-swimlane-drawio
codex plugin add product-swimlane-drawio@product-swimlane-drawioTell Codex, Claude Code, or another Agent Skills-compatible coding agent:
Please install
product-swimlane-drawiofromgithub.com/zz-zed/product-swimlane-drawio. Prefer this agent's native Plugin Marketplace; otherwise usenpx skills.
The agent may ask for the installation scope and permission before running commands.
Use npx skills list for a project installation or npx skills list -g for a user-level installation. Marketplace installations can be checked with claude plugin list or codex plugin list.
For a new process:
Use product-swimlane-drawio to turn this process into an editable Draw.io swimlane.
Confirm the participants, normal path, decisions, exception paths, and completion state first.
After I approve, build, strictly validate, export a preview, and report visual-review status separately.
For an existing compatible diagram:
Use product-swimlane-drawio to update this .drawio file.
Treat the latest saved file as canonical. Preserve unrelated geometry and manual waypoints.
Apply only the requested semantic changes, then strictly validate and compare the result.
Natural-language process
↓ confirm semantics
Versioned JSON model
↓ deterministic build
Native editable .drawio
↓ strict validation + preview
Local human editing
↓ inspect latest file
Geometry-preserving semantic patch
The engine supports a confirmed top-to-bottom main path, decisions, cross-lane calls, returns, retries, same-rank interactions, and optional horizontal phases. It plans mutable connector ports as one bounded batch, routes the main path first, and keeps exceptional traffic visually distinct where geometry allows.
Local editing is part of the design, not an escape hatch.
- Open the generated
.drawioin Draw.io Desktop or diagrams.net. - Adjust wording, node positions, lane sizes, or connectors and save the file.
- Give the latest saved file back to the agent.
- The agent runs
inspect, checks the artifact state, binds the patch to the reported input SHA-256, prepares the smallest semantic patch, preserves unrelated geometry, validates, and compares the result.
Safe patching depends on semantic metadata, a matching semantic-model hash, stable IDs, and the exact inspected input file. A patch can insert, resize, rename, or safely remove lanes, and v3 patch-added nodes can use lane-local slots and note anchors without rebuilding the diagram. Dependent lane shifts, label updates, label moves and route changes are reported separately. Label-only updates preserve saved ports and points, including editor changes still marked automatic; invalidated saved paths need an explicit reroute request. Reviewed direct semantic edits can establish a new baseline explicitly; malformed or manually created .drawio files may require migration or a controlled rebuild. Explicit manual waypoints are never silently simplified, and reroute: true alone does not replace them. Native label geometry is measured from the saved file; unsupported styles are reported as unavailable and fail strict validation. Managed XML extensions and opaque whitespace are included in preservation checks.
Automatic build and explicit reroute reject infeasible or unsupported native candidates before final validation, including without --strict; an empty label does not hide an unsupported path. Saved-file commands and diagnostic severity conventions remain, but a saved v2 or v3 automatic cross-lane return no longer needs a vertical corridor inside the target lane, so its warnings or strict result can change. Same-lane return checks and explicit or saved geometry remain protected. In v3 only, a same-lane downward decision branch prefers a bottom exit when that bottom is not reserved by the main path; explicit ports still win.
Use the same tool version for a patch and its comparison. In 0.6.0, reviewing a patch already completed by 0.5.1 may fail solely because its producing-tool stamp differs; this does not mean the diagram was damaged. Editing a supported old input with the current tool and comparing with that same version is the normal workflow. A failed comparison is not waived, and read-only review must not rewrite stamps or automatically patch/rebuild files. See the compatibility matrix.
This integrated candidate interface is not a formal release. It covers an older managed, single-page diagram whose process identity and same-schema semantics already exist, but whose metadata has a narrow, provable omission. It is not an importer, a schema upgrade, an identity-adoption tool, or a way to repair a diagram by guessing from layout or labels. The established build, inspect, patch, validate, and default compare contracts remain unchanged.
Start read-only. A dry run neither writes XML nor creates an output directory or candidate file:
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
migrate --input old.drawio --dry-runThe receipt records the input SHA-256, existing managed state, classification, reasons, same-schema semantic summary, exact planned changes, strict-validation evidence, and whether this invocation can write. The five migration classifications concern metadata eligibility, not a quality pass:
| Classification | Meaning |
|---|---|
not-needed |
Nothing eligible needs repair. No output copy is created, even when the producing stamp is old or absent. |
automatic |
A valid stored hash permits uniquely filling an absent derived lane order and/or hash-rule version. |
confirmation-required |
The historical hash is absent but all other required raw facts are valid. The user must explicitly accept the current semantic model as a new baseline for that one invocation. |
unsafe |
Existing hash drift, unsupported hash/schema rule, empty or invalid metadata, or missing/contradictory core facts prevents a repair. |
unsupported |
The drawing, raw XML payload, or required semantic adoption is outside this conservative scope. |
An acceptance flag never overrides unsafe or unsupported, and a dry run does not authorize a later write. An eligible repair requires a new output path, the SHA you reviewed, and—only for the missing-hash classification—the narrow acceptance flag:
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
migrate --input old.drawio --output migrated.drawio \
--expected-input-sha256 "<sha256-from-dry-run-or-inspect>" \
--accept-unverified-baselineThere is no migration --force, in-place overwrite, non-strict mode, target-schema conversion, or model-drift acceptance alias. The candidate rejects input/output aliases and an existing destination; it rechecks the input before atomic, no-clobber delivery. It writes only after projected and serialized strict validation, exact preservation checks, and an independently recomputed migration comparison. A successful not-needed result remains written: false; a strict failure is not turned into delivery by the classification.
At most four attributes on the identified pool may differ, and only when their individual conditions hold: an absent data-lane-order, absent data-model-hash-version, an accepted absent data-model-hash, and data-tool-version when another allowed repair actually occurs. This is an exact change plan—not an allowlist for arbitrary pool differences. All process semantics, geometry, routes, unknown XML payload, text/tails, and sibling order remain protected.
Verify a delivered migration independently; this mode is mutually exclusive with patch changes and never writes:
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
compare --before old.drawio --after migrated.drawio --migrationcompare --migration recomputes the before-plan and rejects an incorrect target value, wrong cell, missing or extra field, or any semantic, geometry, XML-payload, text, or order change. A passing migration comparison proves preservation within this rule; it does not prove a user accepted a missing-hash baseline, nor does it replace strict validation.
Historical-source reconstruction and reproducible neutral mutations can establish format rules, but they are not evidence that a real historical missing-field artifact is compatible. Historical editor saves, current editor saves, exports, Agent visual review, and human acceptance are separate evidence. In particular, a real historical missing-field original remains unverified until such an artifact is tested.
Strict validation checks the semantic model, main-path continuity, decisions, retries, phases, fixed-aspect nodes, text fit, ports, lane-boundary clearance, node crossings, short segments, excessive bends, hairpins, reciprocal ambiguity, supported arrowhead terminal-run clearance, label placement, connector overlap, and phase Z-order. Arrowhead coverage can be partial or not_available for unsupported styles or shapes; that is incomplete evidence, not an inferred pass.
Automated validation and visual review are different evidence:
| Review capability | What it supports | Required disclosure |
|---|---|---|
| Text-only agent | Structural and routing confidence from strict validation | Report model visual review as not_available |
| Multimodal agent | Additional inspection for clipping, collisions, hidden arrows, and excessive detours | Report validation, preview export, and visual review separately |
| Multimodal agent plus human review | Recommended before important publication or operational use | Review the final exported preview and retain the editable source |
This project does not claim a measured accuracy percentage for model-produced diagrams. A successful preview export is not proof that a model inspected the image, and multimodal review can still miss defects.
| Supported | Not a goal |
|---|---|
| Editable product and business vertical swimlanes | General-purpose diagram generation |
| Roles or systems as lanes | Strict BPMN conformance |
| Main paths, decisions, branches, returns, and retries | UML, C4, ERD, network, or infrastructure topology |
| New diagrams and safe updates to compatible diagrams | Free-form presentation graphics |
Read Architecture for the component and data-flow model, and Design principles for the decisions that keep semantic generation, deterministic rendering, local editing, and validation separate. Maintainers can continue with Process IR v3, the Layout contract, the Round-trip contract, and the Benchmark plan.
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
build --spec process.json --output process.drawio --strict
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
validate --input process.drawio --strict
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
inspect --input process.drawioPatch and compare:
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
patch --input process.drawio --expected-input-sha256 "<sha256-from-inspect>" --changes changes.json --output process-updated.drawio --strict
python3 skills/product-swimlane-drawio/scripts/drawio_swimlane.py \
compare --before process.drawio --after process-updated.drawio --changes changes.jsonFor migration commands and receipt, see conservative migration and the semantic schema and patch contract.
See the semantic schema and patch contract.
The Skill runs local scripts with the invoking agent's permissions. Review the Skill and scripts before installation. The published Skill package contains no user data, organization names, proprietary terminology, generated diagrams, or domain-specific sample flows. Task artifacts belong outside the Skill directory.
See SECURITY.md for vulnerability reporting.
Released under the MIT License. Draw.io and diagrams.net are third-party products; this project is not affiliated with or endorsed by their maintainers.