diagrams-drawio/references/capabilities.md

diagrams-drawio — Capabilities

This file lists all capabilities an agent can use from this skill.

---

Capability 1 — Deterministic YAML generation

Build native .drawio XML from a validated semantic Diagram IR:

node dist/cli/commands.js --action build --file architecture.yaml --output architecture.drawio

IR v1 remains compatible. IR v2 adds multiple pages, containers and semantic kinds, explicit geometry, waypoints, provenance/properties/extensions, and linear, layered, tree, grid, or manual layout. Dependency-aware placement and obstacle-aware orthogonal routing are deterministic. The builder rejects reserved/duplicate IDs, unknown parents/endpoints, malformed geometry, and unsupported versions before writing output. See schemas/diagram-ir-v2.schema.json and examples/platform-v2.yaml.

---

Capability 2 — Direct XML generation

Create .drawio files (and optionally export to PNG/SVG/PDF) from a description or requirements.

See SKILL.md for the generation workflow, XML format, page sizes, element shapes, and well-formedness rules. See rules-layout.md for mandatory connector and layout rules.

---

Capability 3 — Semantic lifecycle

The native TypeScript core supports loss-aware Draw.io import and deterministic round trips; transactional stable-ID edit batches; linked audience views; semantic query, architecture policy, and failure what-if analysis; three-way synchronization; accessible self-contained story HTML; and a non-launching doctor report.

See semantic-lifecycle.md for command contracts, safety behavior, built-in policy identifiers, and examples.

---

Capability 4 — Diagram analysis (drawio-tools CLI)

A TypeScript / Node.js CLI tool for programmatic analysis of .drawio files.
Entry point: node dist/cli/commands.js (run from the skill's scripts/ directory), or task run -- --file=… --action=….

Usage

cd <skill>/scripts
node dist/cli/commands.js --file <path> --action <action> [--page <index>] [--output <path>]
# short flags: -f, -a, -p, -o, -h

--page selects the diagram tab (0-based, default 0). Ignored by summary (processes all pages).
Always prints YAML to stdout. Exit code 0 on success, 1 on error.

Actions

Authoring

Action	Scope	Description
build	YAML Diagram IR	Validate and convert a YAML specification to native .drawio; requires --output

Semantic lifecycle

Action	Scope	Description
import	Bare or wrapped Draw.io	Preserve semantic and unknown XML information in validated IR v2; requires YAML/JSON --output
edit	Diagram IR v2	Apply one atomic stable-ID batch from --spec; supports --dry-run and Draw.io/YAML/JSON output
views	Diagram IR v2	Project linked executive, system, deployment, dataflow, and security pages
query	Diagram IR v2	Filter by --kind/--property, or find a deterministic path with --from and --to
test	Diagram IR v2	Execute built-in architecture policy rules; --strict treats warnings as failures
what-if	Diagram IR v2	Calculate outgoing impact from --fail, honoring failure-isolating edges
sync	Base/manual/incoming IR	Three-way synchronization with explicit --prune and --dry-run
story	Diagram IR v2	Write self-contained accessible offline HTML; optional --fail overlay
doctor	Local environment	Report optional backend availability without launching processes or requiring a model file

Inventory

Action	Scope	Description
summary	All pages	Full inventory of shapes + edges for every page/tab
page-summary	Single page (--page)	Full inventory of shapes + edges for one page
page-hierarchy	Page 0	Recursive containment tree with totalLevels (nesting depth count)
page-hierarchy-full	Page 0	Same as page-hierarchy + full geometry (x, y, width, height) per shape at each nesting level
page-connectors-summary	Page 0	Per-connector details: type, label, waypoints, source/target names

Validation

Action	Scope	Description
validate	All pages	Mandatory final gate — XML well-formedness + maxGraph compile + sanity check (vertices/edges > 0). Run before finishing any diagram work
quality	All pages	Objective clipping, overflow, placeholder, external-asset, palette, page-density, and edge-density checks with explicit severity
page-connectors-validation	Page 0	Connector-shape overlaps + connector crossings
page-labels-validation	Page 0	Empty labels, duplicate labels, labels > 80 chars
page-shape-bbox-validation	Page 0	Non-containment bounding box overlaps between shapes
page-orphans	Page 0	Isolated shapes (no edges) + dangling connectors (missing endpoints)

Layout

Action	Scope	Description
page-recommendations	Page 0	Smallest standard page size (A4→A3→A2→A1→custom) that fits content with 80 px margin

For install/build instructions, source structure, and how to add new actions, see maintenance.md.

---

Capability 5 — Native service libraries

The package includes additional strict TypeScript APIs under scripts/src/services/:

• source-importers/ — conservative, bounded source/configuration topology extraction with diagnostics and no code execution;
• themes/ and shape-catalog/ — five validated themes and an offline generic shape catalog;
• transforms/ — reverse Mermaid/Markdown, semantic diff, complete-map relabeling, and accessible bounded heatmaps;
• profiles/ — C4, sequence, tube map, compression, runbook, timelapse, and build-up profiles.

These services are covered by the native test suite but are not registered CLI actions. Their exact peer-relative coverage and deliberate omissions are listed in agents365-capability-coverage.md.