6.0 KiB
drawio-main — 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/andshape-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.