diagrams-drawio/references/capabilities.md

diagrams-drawio — Capabilities

This file lists all capabilities an agent can use from this skill. The seven capability families below use the same headings and order as the list at the top of SKILL.md.

---

Capability 1 — Deterministic YAML generation

Build native .drawio XML from a validated semantic Diagram IR (CLI action build, task generate):

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. The agent authors the mxGraphModel XML directly and then runs the mandatory validate action (task validate).

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

---

Capability 3 — 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). Only the actions marked --page below honour it; actions marked "page 0 only" always analyse the first page, and all-page actions ignore it.
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

Inventory

Action	Scope	Description
summary	All pages	Full inventory of shapes + edges for every page/tab
page-summary	--page	Full inventory of shapes + edges for one page
page-hierarchy	--page	Recursive containment tree with totalLevels (nesting depth count)
page-hierarchy-full	--page	Same as page-hierarchy + full geometry (x, y, width, height) per shape at each nesting level
page-connectors-summary	page 0 only	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 only	Connector-shape overlaps + connector crossings + corner-port, header-edge, and single-port violations
page-labels-validation	page 0 only	Empty labels, duplicate labels, labels > 80 chars
page-shape-bbox-validation	page 0 only	Non-containment bounding box overlaps between shapes
page-orphans	page 0 only	Isolated shapes (no edges) + dangling connectors (missing endpoints)

Layout

Action	Scope	Description
page-recommendations	page 0 only	Smallest standard page size (A4→A3→A2→A1→custom) that fits content with 80 px margin
page-negative-space-summary	--page	Free horizontal corridors (negative space) per nesting level, bbox-based and text-aware; input for connector routing and negative-space-diagram.md

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

---

Capability 4 — 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. Every action below also has a same-named task wrapper (task import, task edit, …).

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

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

---

Capability 5 — Safe source importers

Library only — not reachable as a CLI action. Import from dist/services/source-importers/index.js (source scripts/src/services/source-importers/index.ts):

import { importSource } from "<skill>/scripts/dist/services/source-importers/index.js";

importSource({ sourceKind, path, input }) performs conservative, bounded topology extraction with diagnostics and no code execution for python, javascript, typescript, go, rust, terraform, kubernetes, docker-compose, sql, openapi, and ci inputs, returning a Diagram IR v2 plus diagnostics and provenance.

---

Capability 6 — Toolbox transforms

Library only — not reachable as a CLI action. Modules under dist/services/ (source scripts/src/services/):

Module	Exports	Purpose
themes/theme-service.js	applyTheme, validateTheme, contrastRatio	Five validated built-in themes, immutable IR application
shape-catalog/shape-catalog.js	searchShapes	Offline generic shape search (exact/alias/fuzzy)
transforms/reverse.js	diagramIRToMermaid, diagramIRToStructuredMarkdown	Reverse Mermaid / Markdown from IR
transforms/semantic-diff.js	semanticDiff	Added/removed/changed/moved/rerouted classification between two IR models
transforms/relabel.js	relabelDiagram	Strict complete-map relabeling preserving structure
transforms/heatmap.js	applyMetricsHeatmap	Accessible bounded metric heatmaps with legend metadata

---

Capability 7 — Specialized profiles

Library only — not reachable as a CLI action. Import from dist/services/profiles/index.js (source scripts/src/services/profiles/index.ts):

import { projectC4, createSequenceDiagram, createTubeMap, compressExecutiveView,
         createRunbookHtml, createArchitectureTimelapse, createBuildup }
  from "<skill>/scripts/dist/services/profiles/index.js";

C4 projection, sequence diagram layout, tube map routing, executive-view compression, runbook HTML, architecture timelapse, and dependency-ordered build-up frames.

---

Capabilities 5–7 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.