AGENT SKILL

edgy-diagram

Create EDGY-notation diagrams as draw.io XML (multi-page mxfile) or PlantUML source and export them to PNG/SVG/PDF. Generator-first workflow (edgy_generator.py) with core-link pair validation, an influence-verb vocabulary, a drawio linter (edgy_lint.py) and a CLI-free SVG/PNG preview (edgy_render.py) that the agent must look at before delivery. Uses the EDGY facet model with draw.io CLI or the plantuml-stdlib `<edgy/edgy>` library for rendering. Architecture views from one model (application map, value chain and swimlane process maps, capability view, capability × application and CRUD matrices) and a self-contained offline presentation of every view. Discussion-led presentation guidance and a versioned API for targeting model elements from a composition.

License 许可
Apache-2.0
所属仓库
Rahola/edgy-skills
最近更新
2026-10-19
Stars
★ 2
Forks
0

01 前言 Front Matter

name
edgy-diagram
tags
[ "diagram", "drawio", "visualization", "documentation", "edgy", "enterprise-design", "fi", "en", "fr", "de" ]
agents
[ "claude-code", "cursor", "vibe", "generic" ]
inputs
[ { "name": "facet", "type": "enum", "values": [ "identity", "architecture", "experience", "all" ], "description": "EDGY facet (Identity, Architecture, Experience or All)" }, { "name": "map_type", "type": "enum", "values": [ "capability", "organisation", "outcome", "journey", "activity", "process", "purpose", "brand", "product", "object", "asset", "channel", "content", "people", "story", "task", "reference", "summary" ], "required": false, "description": "Map type (overrides facet layout). 16 EDGY map types backed by layout strategies (grid / tree / sequence / hub-and-spoke / hierarchy / role model / area containers) plus two EDGY-extension layouts: `reference` (layered reference architecture with lanes) and `summary` (stakeholder picture). Note: pairwise deep-dive diagrams are documented separately and generated via direct XML by the edgy-deep-dive skill — they are not handled by edgy_parser.py.\n" }, { "name": "elements", "type": "text", "description": "List of EDGY elements and their relationships" }, { "name": "format", "type": "enum", "values": [ "drawio", "png", "svg", "pdf", "plantuml", "puml" ], "default": "drawio", "description": "Output format. `drawio` = draw.io XML; `plantuml`/`puml` = PlantUML source using `<edgy/edgy>` stdlib; `png`/`svg`/`pdf` = rendered image (engine selected via --engine).\n" }, { "name": "engine", "type": "enum", "values": [ "drawio", "plantuml", "native" ], "default": "drawio", "description": "Render engine for png/svg/pdf. `drawio` uses draw.io CLI; `plantuml` uses plantuml.jar or `plantuml` binary (one image per page for multi-page input); `native` is the pure-Python SVG renderer with PNG through headless Chromium when available (approximate, no pdf). Ignored when format is drawio/plantuml/puml.\n" }, { "name": "language", "type": "enum", "values": [ "fi", "en", "fr", "de" ], "default": "fi" } ]
outputs
[ { "type": "file", "description": "Generated EDGY diagram file (drawio, png, svg or pdf)" } ]
version
2.10.0
category
documentation
examples
[ { "input": "examples/identity-facet.txt", "output": "examples/expected-identity.drawio" }, { "input": "examples/full-edgy-map.txt", "output": "examples/expected-full-edgy.drawio" }, { "input": "examples/multipage-map.txt", "output": "examples/expected-multipage.drawio" }, { "input": "examples/capability-areas-map.txt", "output": "examples/expected-capability-areas.drawio" }, { "input": "examples/capability-areas-nested-map.txt", "output": "examples/expected-capability-areas-nested.drawio" }, { "input": "examples/channel-matrix-map.txt", "output": "examples/expected-channel-matrix.drawio" }, { "input": "examples/reference-architecture-map.txt", "output": "examples/expected-reference-architecture.drawio" }, { "input": "examples/archimate-positioned.txt", "output": "examples/expected-archimate-positioned.drawio" } ]
languages
[ "fi", "en", "fr", "de" ]
description
Create EDGY-notation diagrams as draw.io XML (multi-page mxfile) or PlantUML source and export them to PNG/SVG/PDF. Generator-first workflow (edgy_generator.py) with core-link pair validation, an influence-verb vocabulary, a drawio linter (edgy_lint.py) and a CLI-free SVG/PNG preview (edgy_render.py) that the agent must look at before delivery. Uses the EDGY facet model with draw.io CLI or the plantuml-stdlib `<edgy/edgy>` library for rendering. Architecture views from one model (application map, value chain and swimlane process maps, capability view, capability × application and CRUD matrices) and a self-contained offline presentation of every view. Discussion-led presentation guidance and a versioned API for targeting model elements from a composition.

02 资源文件 260

03 SKILL.md 正文

EDGY Diagram Skill

Purpose

This skill generates draw.io diagrams with EDGY notation and exports them to the desired format. It uses the EDGY facet model and draw.io CLI for diagram generation and export.

Use this skill when:

  • You need an EDGY-notation diagram for enterprise architecture
  • You want to visualise EDGY facet model elements and their relationships
  • You need a diagram that follows the EDGY 23 standard

IMPORTANT: Use the relationship verb matching the language parameter from the core links table below.

Agent Instructions

Generation workflow: generator → lint → preview

Use the generator whenever Python 3 is available. Write the TXT input, generate, lint, preview, deliver. Write draw.io XML by hand only when Python cannot run, and then only for diagrams under ~15 cells — still lint it later.

  1. Parse the user's elements and relationships; verbs come from the core-link and influence vocabularies, never invented. No core link fits → influence verb (dashed), never a new solid Link.
  2. Write <name>.txt (Input Format below).
  3. python3 scripts/edgy_generator.py <name>.txt --output <name>.drawio --preview — read every warning on stderr (wrong pair, unknown verb, layout notes); input errors (unknown facet / map_type) exit 2.
  4. python3 scripts/edgy_lint.py <name>.drawio — 0 errors required.
  5. Open the preview (<name>.svg / .png), walk the Preview loop checklist, fix the input, regenerate. Never deliver a diagram you have not looked at.
  6. Export png/svg/pdf if asked (Export section).

XML essentials (details: references/xml-reference.md)

  • Every mxCell is a direct child of <root>; containment is parent="…" with geometry relative to the parent. Never nest <mxCell> elements.
  • Every edge has <mxGeometry relative="1" as="geometry"/>; ids are unique; XML special characters escaped once; UTF-8.
  • Shapes follow the base type: Outcome → rounded rectangle (rounded=1;arcSize=10), Activity → pentagon (shape=mxgraph.arrows2.arrow), Object → rectangle, People → person. Brand / Product / Organisation are rectangles.
  • Palette: Identity #80ffb7, Architecture #a6c0ff, Experience #ff99bd, Brand #ffd580, Product #e599ff, Organisation #80eaff; white stroke, width 2, bold 14 px label.
  • Edge styles: Link endArrow=classic;endFill=1, Flow endArrow=open;endFill=0, Tree endArrow=none, Influence endArrow=open;endFill=0;dashed=1; all edgeStyle=orthogonalEdgeStyle;rounded=1.
  • The generator wraps pages in an uncompressed <mxfile>; a bare <mxGraphModel> is also valid.
  • A legend (element colours + line styles) is mandatory; the generator adds it.

Validation — run the linter before delivery

python3 scripts/edgy_lint.py <name>.drawio                       # 0 errors required
python3 scripts/edgy_lint.py --warnings-as-errors <name>.drawio  # strict (shipped examples)
python3 scripts/edgy_lint.py --visual <name>.drawio              # W111–W114, W130, W131 only, JSON with coordinates
python3 scripts/edgy_lint.py --series a.drawio b.drawio c.drawio   # one delivery: W121 when the files differ in layout
python3 scripts/edgy_lint.py --no-layout-quality <name>.drawio   # switch W117–W120 off for a run
python3 scripts/edgy_qa.py --require-approvals <name>.qa.json     # the manifest: lint and approvals on separate lines

The linter checks structure (flat mxCell tree, edge geometry, dangling source/target, duplicate ids), layout (no negative / off-page coordinates with parent chains resolved, no overlaps > 30 %, text fits), notation (legend, palette, intersection shapes, no type word in labels) and semantics (core-link verb only on an allowed pair, non-core verb never in core-link style, verbs from the vocabulary). Exit 1 = fix before delivery; warnings do not block but must be read.

Visual rules (W111–W114, W130, W131) run on the same resolved geometry the preview draws (edgy_geometry.py: ports, orthogonal joins, waypoints, label boxes), so a clean structural lint is no longer mistaken for a readable picture: W111 an edge passes through an element that is not its source or target, W112 an edge label lies on an element, W113 a label lies on another label (a parent → children fan with one verb is one bus and is allowed), W114 a label or edge end leaves the page, W130 a line runs under another edge's label (the label reads as that line's), W131 two edges with no common end share a stretch of line. W111 also covers a trace "+N more" card and a route back through its own end. They are warnings: fix them by moving the element, adding via: waypoints, changing from:/to:, or using label: source|target; --visual gives the cell ids and coordinates for a script to act on. A delivery should have none; --warnings-as-errors enforces that.

Layout quality (W117–W120, on by default). Measured, never a taste judgement, and every finding carries its numbers: W117 elements of one type under one parent differ in width or height by more than 25 %; W118 two containers (or two top-level elements of one type sharing a row or column) are near-aligned — 1–12 px apart — or the gaps between containers in one row or column differ by more than 20 %; W119 on a page the generator had to grow beyond 1200 × 900 the content leaves one side more than 35 % of the page empty while the other side is full, or covers less than 45 % of a page grown in both directions; W120 content larger than 1200 px whose bounding box is wider than 4.5 : 1 or taller than 1 : 4.5 (a sequence of pentagons is exempt). The generator's defaults keep its own output clean (equal_cards, the uniform 60 px content margin); the rules catch hand-edited files and layouts that the options below should fix: card_width, equal_cards, group_columns, cards_per_row, equal_group_width, align_groups: grid. --no-layout-quality switches them off for a run; a delivery records whether they ran. W122 (always on) flags a container coloured with a facet colour that none of the elements inside it carries — an area is coloured by what it holds. W123 flags a status badge (maturity / rating extension) whose colour has no key in the legend. W128 flags a header text (band header, matrix key, title) covered by a legend cell. W121 (--series) checks the files of one delivery against the first: legend placement, content margin, card width of every shared type and label font sizes must agree on every page of every file — generate the series with the same options.

Language (W116). With language: set, the generator renders the legend and every vocabulary verb in that language (contains → sisältää, requires → vaatii; the model keeps the canonical verb) and the linter reads the map language from the legend title (--language overrides). W116 fires when an edge label is a vocabulary verb of another language — an English contains left in a Finnish map, for example. Free text is never flagged.

QA manifest (qa.json). edgy_generator.py --qa (on by default with --preview, --no-qa to skip) writes <name>.qa.json next to the .drawio: per page the element and edge counts, the structural lint (errors, warnings, rules), the visual rules W111–W114, W130 and W131, the layout rules W117–W120 and whether they ran, the language check W116, the text-size check W115 at the preset's reference width, the preview image size and orientation, and the generator warnings. Three fields are never set by the tooling: visual_approval, semantic_approval, delivery_notes — a person fills them in after looking at the preview, as "<name or role>, YYYY-MM-DD", and null (or anything else) means not approved. edgy_qa.py --require-approvals reports lint and the approvals on separate lines and exits 1 while either approval is null; edgy-eval.py and the edgy-assessment Phase 5 read the manifest instead of re-linting. Schema: assets/qa.schema.json.

Semantic review. Notation and geometry say nothing about meaning: a purpose map can lint clean while its "purposes" are development actions. python3 scripts/edgy_semantic_review.py <name>.txt (or edgy_generator.py … --semantic-review) raises the questions a reviewer must answer — S001 action as a Purpose, S002 Outcome measures nothing, S003 / S004 missing provenance ([confirmed] / [analytical] / [proposed], {status: confirmed|proposed} on Outcomes), S005 contains that may be an influence, S006 metric in a Purpose name — with the reason and the question for each. It flags; it never decides: exit 0 unless --strict, and zero findings is not an approval. The sign-off is a person's (edgy-framework, Purpose map semantic review). On every page the same tool also asks about capabilities, tasks and outcomes: S007 a capability named after a system, tool or unit, S008 phrased as a verb, S009 shaped like a project or a dated change, S010 a task in the organisation's voice, S011 an outcome phrased as an action, S012 (hint) an outcome without a measure while others on the page have one (edgy-framework, Formulating tasks, outcomes and the Experience facet). --qa records the rule set in the manifest.

If the linter cannot run, check by hand that the file has more than the two structural cells, one vertex per element, one edge with geometry per relationship, and is larger than 1000 bytes.

Generator reference

edgy_generator.py in.txt --output out.drawio [--preview] [--bare] [--lenient] [--publication] [--qa|--no-qa]
edgy_generator.py in.txt --format svg|png --engine native --output out      # CLI-free render
edgy_generator.py in.txt --output out.drawio --preview --preset publication|presentation   # native preset (below)
edgy_generator.py in.txt --format png|svg|pdf [--engine drawio|plantuml|native] [--preset presentation|print|web]
edgy_generator.py in.txt --format plantuml --output out.puml
edgy_render.py out.drawio [--out DIR] [--no-png] [--publication]            # preview an existing file
edgy_lint.py out.drawio [--warnings-as-errors] [--visual] [--scale 0.4]     # lint; W115 below 6 pt at that scale
edgy_lint.py --series a.drawio b.drawio [--no-layout-quality]              # W121 across a delivery; W117–W120 off
edgy_generator.py in.txt --output out.drawio --graph graph.json            # document graph (extension contract 1)
edgy_generator.py in.txt --output out.drawio --present presentation.html   # self-contained offline presentation
edgy_present.py out.drawio [-o presentation.html] [--graph graph.json]     # same, from an existing file

Realisation trace (2.9.0). A page map_type: trace + expand: trace writes a clickable trace: an index and one page per element with an id, from journeys through tasks / channels, products, capabilities, processes / assets / people to organisations, each card linking to its own page; W129 reports an empty band below an element with the W127 evidence statuses. Read references/architecture-views.md (Realisation trace); example examples/trace-map.txt; from a model, edgy_model_to_txt.py --views trace. In the presenter the trace is one Trace card with drill-through, breadcrumb and browser back.

--present writes one HTML file with every page (card wall → zoom, cross-view highlight, ⌘K search, current ↔ target over {change:} annotations, paging and deep links, print). It has no network access (CSP connect-src 'none') and inlines the native preview; it may carry the model, so keep it in the engagement folder like the .drawio. Style markers, graph JSON and SVG data-* attributes are a public contract for extensions: references/extension-contract.md.

Discussion-led presentations (2.10.0). For an executive introduction, workshop or interactive narrative, read references/discussion-presentations.md. Compose a claim/evidence/question path; keep optional detail and reliable return without imposing a visual template. Use window.EDGY_PRESENT navigation API 1 (references/extension-contract.md §7) to target explicit model IDs and provide local Back in srcdoc embeddings. This extends paging/deep links, not the five atlas effects. Human facilitation/accessibility acceptance is separate from tests.

--publication crops the native SVG/PNG to the content (shapes, routes, arrowheads, labels, legend) instead of the editor page and prints an orientation hint (landscape / portrait / square) per page — use it for the image that goes into a report, the plain preview for editing. The native presets go one step further for --preview and --engine native: --preset publication (24 px margin, legend: strip unless the input says otherwise, W115 tested at a 160 mm report column = 605 px at 96 dpi) and --preset presentation (48 px margin, legend: box, W115 at a 1920 px slide); both crop to the content and draw the title: band above and the footnote: band below when the input sets them. With legend: fixed in the input, the same input rendered with the two presets differs only in that frame; otherwise the legend placement follows the preset too. The draw.io CLI presets (presentation, print, web) keep their names and semantics; with --engine drawio and a PNG/PDF/SVG format presentation is the CLI preset. Text is measured with glyph tables (scripts/edgy_text.py, Helvetica/Arial metrics) in the generator, the preview and the linter alike, so box widths, wrapping and W101 agree; a long name widens the box up to 280 px and then wraps — text is never shrunk silently.

Output is an uncompressed <mxfile> with one <diagram> per page (--bare gives a bare mxGraphModel, single page only). The vocabulary the generator validates against is generated from skills/_shared/edgy-core-links.yaml into scripts/edgy_core_links.py — change the YAML, run tools/render-core-links.py, never edit the module or the tables.

EDGY Facet Model (summary)

Three facets, each with one Outcome / Activity / Object element: Identity (Purpose, Story, Content — why), Architecture (Capability, Process, Asset — how), Experience (Task, Journey, Channel — what role in people's lives). Three intersection elements bridge them: Organisation (Identity ↔ Architecture), Product (Architecture ↔ Experience), Brand (Identity ↔ Experience). Four base elements (People, Activity, Outcome, Object) apply to every facet; Outcome carries KPIs. facet: identity includes Brand and Organisation, architecture Organisation and Product, experience Brand and Product, all all three. Full tables: references/vocabulary.md.

Input Format

Formal Syntax

facet: identity | architecture | experience | all
map_type: capability | organisation | journey | purpose   # optional, overrides facet layout
legend: box | strip                                       # optional; strip = one band along the bottom, page as tall as the content
language: fi | en | fr | de                               # optional; legend, generated headings and vocabulary verbs render in this language
translate_verbs: true | false                             # optional (default true): with language: set, a vocabulary verb written in another language is rendered translated ("contains" → "sisältää"); the model keeps the canonical verb
rating_palette: label=#rrggbb, …                          # optional: colours of {rating: label} badges (extension)
title: <text>                                             # optional: title band above the content in native presets (--preset publication|presentation)
footnote: <text>                                          # optional: footnote band below the content in native presets
stages: Plan, Buy, Ride                                   # optional, map_type: task — journey stages as columns; a task picks its column with {stage: Buy} (with lanes: lanes × stages; without: one column container per stage)
columns: A, B, C                                          # optional, any grid-like map — same as stages:; an element picks its column with {column: B}
rows: X, Y                                                # optional — matrix rows (bands); an element picks its row with {row: Y}; with columns: a rows × columns matrix
equal_cards: true | false                                 # optional (default true): elements of one type on a page take the widest width (≤ 280) and the tallest height of their type
card_width: N                                             # optional: every box is N px wide (60–600; a size class S/M/L may be wider; the person shape is exempt); long names wrap
group_columns: N                                          # optional: containers in N columns (map-type and single-facet layouts)
cards_per_row: N                                          # optional: N cards per row inside every container
equal_group_width: true | false                           # optional (default false): containers share the widest container's width
align_groups: grid | none                                 # optional: containers on exact rows and columns — column width = widest in the column, row height = tallest, containers stretch to the row
group_style: official | light                             # optional: official = official EDGY 23 areas (area in the facet colour, white sub-groups); light = grey structure tint. Default official when groups are nested, light otherwise

elements:
  - <element_type>: "<name>"
  - <element_type>: "<name> - <description>" [tags] {id: X, change: new, size: M, primary: true, metric: value}
  - <element_type>: "<name>" {maturity: 3, rating: differentiating, row: Digital, column: Plan}   # badge (extension), matrix cell
  - <element_type>: "<name> | <subtext>"
  - group: "<area name>"              # container; the indented elements below are its children
    - <element_type>: "<name>"
    - group: "<sub-area name>"        # nested container (any depth); its elements sit inside it
      - <element_type>: "<name>"
  - lane: "<layer name>"              # borderless band; the indented elements sit on it (task map: one lane per stakeholder)
    - <element_type>: "<name>"

relationships:
  - "<source name>" -> "<target name>": "<verb>"
  - "<source name>" -> "<target name>": "<verb>" {from: right, to: left, via: [(x,y)], change: replace, label: source, label_dx: -30, label_dy: 20}
  # OR by type (only works if there is exactly one element of that type):
  - <source_type> -> <target_type>: "<verb>"

Names are matched on the part before - / | (the name), so a relationship can say "Ticketing" for "Ticketing - sell and validate fares".

The layout options give a standard-sized, aligned map without hand editing: equal_cards is on by default (one size per element type and page), and a balanced capability map is group_columns: 2, cards_per_row: 2, equal_group_width: true, align_groups: grid. The content's top-left corner is at (60, 60) in every layout except the planned triad ring (whose slot table is fixed), so the maps of one series share their margins (lint --series). Invalid values warn and keep the default.

Multi-page input (pages:) and positions from an earlier view (layout_from:)

facet: architecture              # document-level default for every page
pages:
  - name: "Roles and actors"
    elements: …
    relationships: …
  - name: "Systems"
    map_type: asset
    elements: …

Each page gets its own layout and legend and becomes a draw.io tab; previews are written per page (<base>-<page>.svg). Example: examples/multipage-map.txt.

layout_from: current-state.archimate#View name [scale=1.5 dx=0 dy=0] keeps every element that matches a view element by name at the view's (scaled) position — "same place = same responsibility" when a target state is shown next to an existing ArchiMate current state. Unmatched elements go below; view elements missing from the input are reported (mark them remove or add them). Standard-library XML parsing, no Archi needed. Example: examples/archimate-positioned.txt.

Status badges — maturity and rating (EDGY extension)

A heat map keeps the facet fill. {maturity: 1–5} or {rating: <label>} on an element draws a small badge at the bottom of the card (a child cell, so it moves with the card in draw.io) and a legend row "Maturity (extension)" / "Rating (extension)" listing only the values used. Maturity uses a fixed five-step scale (red → green); ratings get colour-blind-safe colours in order of first use, or the colours of rating_palette: label=#rrggbb, …. The card grows to fit the badge. Lint W102 still flags a hand-coloured fill (with this advice) and W123 flags a badge whose colour has no legend key. Example: examples/capability-heatmap-map.txt.

layout_from: delivered.drawio#Page name [scale dx dy] does the same from a draw.io page — typically the previous delivery after a reviewer moved boxes in draw.io. Top-level elements and areas (group: / lane:) are matched by name; an area keeps the generated arrangement inside it, so moving a whole area survives regeneration, moving a card inside an area does not. The file type decides the reader (.archimate, .drawio, .xml); any other type warns and the generator's own layout is used. This is how "edit in draw.io" and "regenerate from TXT" stay one loop: never patch the XML, move the areas, then regenerate with layout_from: pointing at the edited file.

Grouping, Lanes and Nesting

Containment is the parent attribute with geometry relative to the parent; the generator handles it:

  • group: → container (container=1): capability areas, blocks with nested capabilities, any Tree with more than three children. Members in a 2–4-column grid or as a tidy tree when they have tree relationships; groups are placed in rows with one fixed gap between rows.
  • Nested group: (indented under another group:, any depth) → a container inside the container: the three tiers of the official capability map (area → sub-area → capability). Direct elements of an area come first, its sub-groups below in rows (group_columns, else 1–3 in one row, 4 in two, more in three); the sub-groups of one row share the row height. Nesting switches group_style: official on: an area takes the facet colour of everything inside it (a neutral tint when they mix facets), sub-groups are white without a border, a top-level container without sub-groups is white with a facet-coloured border. group_style: light keeps the grey tint. A lane: inside a group becomes a nested group and a group: inside a lane goes to the top level, both with a warning. Example: examples/capability-areas-nested-map.txt (40 capabilities in 8 sub-areas).
  • lane: → borderless band with a title; members sit on it at root level so edges may cross lane borders. Lanes stack top-down; edges between non-adjacent members of a row are routed over the top.
  • Facet containers are automatic: facet: all → Identity / Architecture / Experience containers with Organisation between the first two, Product between the last two, Brand below; a single facet → one container plus the intersection elements below, three per row. Your own group:s take over.

Groups and lanes are structure, not EDGY elements (no relationships, light tint / light grey). Examples: examples/capability-areas-map.txt, examples/lanes-map.txt; XML in references/routing.md.

Relationship Source/Target Matching Logic

In relationships, source and target are matched to elements in the following order:

  1. Exact match — value matches the element name completely (preferred)
  2. Prefix match — value matches the element name prefix before - separator
  3. Type match — value matches the element type (e.g. purpose)

IMPORTANT: Use the element's exact name in quotes for relationships. This prevents incorrect matches when two elements have similar names (e.g. "Test" and "Test System").

Labels: name, subtext, id, tags and metrics

Label standard. The element shows its name in bold on the first line. Everything else is small subtext: [ID] and the description on the second line, tags and metrics on a third. The element's width follows the name, its height grows with the subtext lines — so long descriptions no longer overflow. Do not repeat the element type in the name ("Capability Ticketing"): the type is shown by shape and colour, and the linter warns (W109).

elements:
  - capability: "Ticketing - sell and validate fares in every channel" {id: CAP-05}
  - asset: "Fare engine | runs on-prem until 2027" [application, owned] {cost: high, size: M}
  - task: "Registration" [functional] {satisfaction: ok}

Reserved keys inside {…} (not rendered as metrics):

Key Values Effect
id any short code (PUR-01, CAP-05, ADR-004) rendered as [ID] in the subtext; use it for cross-references in documents
change keep, new, change, replace, remove, decide (fi/fr/de synonyms accepted) transition overlay — see below
size S 120×60 (map), M 200×90 (card), L 270×120 (block) minimum size class
highlight yes dark 4 px border, e.g. first-round decision units (same as the [focus] tag)

Everything else in {…} is a metric and is colour-coded as before:

Recommended tags per element type (in-house/outsourced, differentiating/commodity, application/data, digital/physical …) and metric colour coding (good/ok/bad, low/high in four languages) are listed in references/vocabulary.md.

Comments and Empty Lines

  • Comments start with # and are ignored
  • Empty lines are allowed anywhere

Relationship Types

EDGY 23 defines four relationship types:

Type Visual Style When to Use
Link (core link) Solid line, directional arrow Official 24 core links (below)
Flow Solid line, open arrowhead Data/information/value/material transfers concretely
Tree Solid line, no arrowhead Hierarchy: decomposition, portfolios, organisational structures
Influence Dashed line, open arrowhead Other influence/guidance (default)

Influence verbs (for everything that is not a core link)

Influence is the default relationship type: a dashed line with an open arrowhead. Use one of these verbs (matching the language parameter) whenever the pair is not one of the 24 core links — for example capability → purpose or process → outcome. Do not invent a new solid Link relationship, and do not reuse a core-link verb on a pair it does not belong to: the generator and the linter flag such edges and draw them as influence.

<!-- edgy-links:begin format=influence -->

EN FI FR DE Typical use
enables mahdollistaa permet ermöglicht A makes B possible
guides ohjaa guide steuert A steers or constrains B
influences vaikuttaa influence beeinflusst generic influence when nothing more specific fits
offers tarjoaa offre bietet A makes B available (non-core product/channel pairs)
manages hallinnoi gère verwaltet A administers B (organisation → asset, organisation → product portfolio)
reflects heijastaa reflète spiegelt B mirrors A (content → brand, task → purpose)
strengthens vahvistaa renforce stärkt A reinforces B
defines määrittelee définit definiert A sets the scope or rules of B
depends on riippuu dépend de hängt ab von A cannot exist without B (non-core pairs; core pairs use requires)
produces tuottaa produit bringt hervor process → outcome: a process yields a measurable result
measures mittaa mesure misst outcome → purpose: an outcome (KPI) measures a purpose
contributes to edistää contribue à trägt bei zu capability → purpose or outcome: bridge when no core link exists
stores tallentaa stocke speichert asset (application) → asset (data): the application is the system of record
accesses käsittelee accède à greift zu auf process → asset (data): reads or changes data; {crud: R
interacts with asioi interagit avec interagiert mit people / organisation → asset (application): an actor works with an application (core uses is task → channel only)
<!-- edgy-links:end -->

supports/tukee is the core link brand → task; on any other pair it is reported as a wrong pair — use enables or strengthens instead.

Core links, flow and tree keywords (tables: references/vocabulary.md)

The 24 official core links (four languages, allowed pairs), the flow and tree keywords, the recommended tags per element type and the natural-language → element table live in references/vocabulary.md. Rule of thumb: a core-link verb is valid only for its listed source → target pair (requires / vaatii for three pairs, everything else for one); flow = flows, transfers, produces data, returns; tree = contains, comprises, decomposes. Element types: purpose content story capability asset process task channel journey brand product organisation people activity outcome object.

Relationship options

- "Platform" -> "Legacy engine": "depends on" {from: top, to: bottom, via: [(760, 300)], change: replace, label: source}

from / to override the automatic exit and entry side; via adds explicit waypoints (page coordinates — use after a first preview); change colours the edge with the transition overlay; label moves the verb towards the source or target. Two relationships between the same pair are merged into one edge labelled verb1 / verb2. Full rules by diagram size: references/routing.md.

Routing and space usage by diagram size

Size Cells Rules
Small < 10 automatic: edgeStyle=orthogonalEdgeStyle;rounded=1, distributed anchors, ≥ 80 px horizontal and ≥ 60 px vertical spacing, coordinates on the 10 px grid
Medium 10–25 set {from:, to:} where the automatic side is wrong; share a channel with via:; {label: source} for short verbs
Large > 25 lane: bands, one integration bus ({size: L} Asset) instead of n×m edges, vertical channels, feedback loops with explicit waypoints; move influence edges to a second page

Details and XML patterns (waypoints, lanes, invisible anchors, bus, containers): references/routing.md. Whatever the size: preview, look, fix the input.

EDGY Facet Model Layout (facet: all)

Three facet containers side by side; the intersection elements sit between the facets they bridge, so core links stay short:

┌ Identity ──┐         ┌ Architecture ─┐          ┌ Experience ┐
│ Purpose    │ [Org]   │ Capability    │ [Product]│ Task       │
│ Content    │         │ Asset         │          │ Channel    │
│ Story      │         │ Process       │          │ Journey    │
└────────────┘         └───────────────┘          └────────────┘
                 [ Brand — Identity ↔ Experience bridge ]
                 [ base elements: people, activity, outcome, object ]

Container width follows the widest member; Tree relationships inside a facet are laid out as a tree inside the container. A single facet (identity, architecture, experience) gives one container with a 2–4-column grid and the intersection elements below it, three per row.

Map Types

map_type overrides the facet layout. Thresholds come from the official EDGY 23 example maps (examples/official/decoded/PATTERNS.md); below Min the parser warns.

Map type Layout Min Recommended
capability area containers (group:) in rows, three tiers with nested group: (official style); grid + tree without groups 8 15–30
organisation role model when Process elements exist (roles as columns, actors under the role they perform); tree otherwise 8 15–30
purpose hierarchy: top purposes → sub-purposes (contains) → Outcomes (measures); Organisation and Brand in the top row, Content left, Story right 6 10–15
outcome web: layered left → right by link direction (causes left, effects right) when outcomes have directed links, ≤ 15 elements; grid + tree otherwise 5 7–10
journey, activity, process sequence (pentagon row, left → right) 4 6–8
process + process_view: chain | swimlane value chain (L1 row, L2 stacked, {band:} rows) or swimlane (one lane per performer, staircase, asset chips) — references/architecture-views.md 4 6–20
application application map: domains (group:), domains × layers (rows:), or group_by: capability areas with a Shared strip; TIME and hosting badges, routed integrations 6 15–40
capability-view one capability (focus: / expand: per-capability) with actors, processes, resources, data (CRUD) and products in five bands; W127 for empty bands 1 5–15
capability-matrix capabilities × applications (● / ◉ primary) or, with matrix: crud, processes × data with CRUD letters 2 any
brand, product, object tree (portfolio, brand architecture, object parts) when they have tree relationships (contains); hub-and-spoke otherwise 5–6 7–15
asset, channel, content, people, story grid (cols ≈ √N) 5–8 7–30
task stakeholder inventory when lanes exist or a People / Organisation element has relationships to the tasks: one lane per stakeholder (a related stakeholder becomes the lane and is not drawn as a box), stages: as columns with {stage: …}; it has no edges because its input has no other relationships (one written between two tasks is drawn); path when tasks link to a journey (is part of) or channels (uses): journeys above, tasks in input order, channels below; stage columns (official task map) when stages: is set without lanes or stakeholder relationships: one column container per stage, tasks stacked, a task without a known stage below with a warning; grid otherwise 5–8 7–30
reference (extension) lanes top-down, Organisation/People left, [external] right, overlay strokes, one integration bus 8 10–25
summary (extension) who / does what / what results; warns above 4 boxes per row 3 6–10
triad (extension) planned ring for facet: all or one facet: one primary element per type carries the core links ({primary: true}, else the first of its type), straight border-to-border lines, two links detour along the page edge; the other elements sit in "Further <type>" panels without lines and their links are reported, not drawn; strip legend by default 6 12 primaries + any number of further

Matrix (any grid-like map). rows: and columns: (or stages:) with {row: …, column: …} per element give a rows × columns matrix: the channel map's physical / digital × synchronous / asynchronous, a journey touchpoint map (columns = journey stages, rows = channels or people), a transition roadmap (columns = waves, rows = areas, change: on every block). columns: alone gives one column container per value. An element without a known row or column is placed after the matrix with a warning; an empty row or column is not drawn. Not for triad, purpose, reference, summary. Examples: examples/channel-matrix-map.txt, examples/transition-roadmap-map.txt.

The two task-map variants are documented pages of one input (examples/task-stakeholder-map.txt): the inventory answers who does what at which stage and carries no relationships in its input — a map is never given a link just to look connected; the path answers which journey and channels a task touches. Never model focus areas as Story in a purpose map; formulate capabilities as system-independent result nouns, 6–12 areas and 40–80 leaves (edgy-framework, Formulating capabilities). Input/layout sketches per strategy and the pairwise map spec used by edgy-deep-dive: references/map-types.md. Examples: examples/purpose-hierarchy-map.txt, examples/organisation-roles-map.txt, examples/reference-architecture-map.txt, examples/summary-map.txt.

Architecture views (application, process, capability view, matrices)

Applications and data are EDGY Assets with {kind: application | platform | integration | data} — the views add layouts, not a notation. One draw: false model page with explicit {id:}s feeds the document graph; a view page of map_type: application, process or capability-matrix without elements of its own is derived from it, and capability-view always is. expand: per-capability | per-application | per-process (with where: ids | highlight | top) writes one page per element. From an assessment model: edgy_model_to_txt.py MODEL.json --views all (edgy-assessment, model format 1.9). New rules: E014 conflicting or duplicate id, E015 relationship to an unknown id, W124 application without an owner, W125 integration without a data asset, W126 band mismatch on a value chain, W127 empty capability-view band with its evidence status ({gaps: band=status}, written to qa.json model_gaps[]). C4 diagrams of one application come from the separate edgy-c4 skill (0.1.0, claude-code and generic installs): pages with notation: c4, level: context (derived from this document's graph) or level: container, drawn by its notation handler and kept out of the EDGY graph. Without edgy-c4 installed, notation: c4 is E013 — say so and offer the application map or a capability view. Read references/architecture-views.md before drawing any of these maps; examples: examples/application-map.txt, examples/application-by-capability-map.txt, examples/process-chain-map.txt, examples/process-swimlane-map.txt, examples/capability-view-map.txt.

Transition Overlay (EDGY extension — current → target state)

EDGY 23 has no notion of change; this overlay colours the stroke only, the fill stays the facet colour, so the map stays valid EDGY. Say "EDGY extension" in the delivery. {change: …} on elements (stroke width 4) and on relationships (width 1.5, edge takes the colour of its change); the legend gains a "Transition (extension)" block automatically.

change fi stroke
keep säilyy #6b778c grey
new (strengthen) uusi / vahvistuu #006644 green
change (merge, extend) muuttuu #b26b00 amber
replace korvautuu #c25100 orange
remove poistuu #bf2600 red
decide (open, see ADR) päätettävä #bf2600 red, dashed

Example: examples/transition-overlay.txt.

Preview loop (mandatory before delivery)

Lint finds structural and semantic errors; only a picture shows overlaps, cut text, spaghetti routing and labels on boxes. Generate with --preview (or run edgy_render.py), open the PNG/SVG and check:

  • [ ] no edge passes through a box and no edge label lies on a box or another label — edgy_lint.py --visual must report nothing (W111–W114 = 0)
  • [ ] cards of one type are one size, groups sit on exact rows and columns, the content is balanced on the page — the layout rules W117–W120 report nothing (or each finding is answered); the files of one delivery pass --series
  • [ ] every edge visibly starts and ends at an element; no diagonal end segments on orthogonal routes
  • [ ] nothing cut off or overlapping; text fits its element
  • [ ] legend clear of content; page height ≤ 1.5 × width (otherwise pages or another map type)
  • [ ] no element twice; intersection elements between the facets they bridge
  • [ ] a stakeholder could explain it in a minute — otherwise reduce or split

Fix the input (order, shorter names, map_type, fewer relationships, pages) and regenerate; never patch the XML. Without Chromium the SVG opens in any browser or IDE; the render is approximate but enough for this list. Record in the delivery which preview was used.

Error Handling

  • Unknown element type → Use white rectangle: fillColor=#ffffff;strokeColor=#262626 (warning)
  • Relationship source/target not found → Skip relationship and warn user
  • Missing facet value → Default: identity
  • Unknown facet or map_type value (e.g. all-facets) → error, generator exits 2; fix the input (--lenient forces generation for debugging only)
  • Core-link verb on a pair that is not a core link → warning, drawn as influence; change the verb or the pair
  • Verb outside the vocabulary → warning, drawn as influence; pick a verb from the influence table
  • Preview cannot be written (--preview) → error, generator exits 3 after writing the .drawio; a missing PNG (no Chromium) is not an error — the SVG is enough for the preview loop

Export

Need Command
draw.io file (default) edgy_generator.py in.txt --output out.drawio
preview SVG/PNG, no CLI --preview or edgy_render.py out.drawio
publication PNG/SVG/PDF `--format png
PlantUML source / render --format plantuml, or --format png --engine plantuml (uses <edgy/edgy> stdlib)
approximate PNG/SVG without CLI or Java `--format png
report image cropped to content, orientation hint --publication with --preview, --engine native or edgy_render.py; legend: strip in the input keeps the page tight

Details, output naming, PlantUML macro mapping, the official EDGY 23 stencils and draw.io CLI locations: references/export.md.

Delivery

One diagram = one .drawio (all pages inside) plus one preview image per page, named <subject>_<diagram>_v<N>.<ext>. Remove superseded versions when a new one is accepted so readers never find two truths. Readers without a draw.io plug-in see the image, so always ship the PNG (draw.io CLI export or the native preview) next to the .drawio. Write into wikis, trackers or other external systems only when the user asks, and then place each diagram next to the section it belongs to. Say in the delivery which layouts are EDGY extensions (transition overlay, reference, summary).

External standards. EDGY 23 is the language of every map. Classifications from outside EDGY — Gartner TIME, CRUD, the management / core / support process bands, the swimlane layout, maturity and hosting badges, the ArchiMate export, and C4 (the separate edgy-c4 skill) — are registered with their rationale, limits and source in references/external-standards.md. Name the ones a delivery uses, credit the source (the legends do), and never use a classification that is not in the register: propose an entry instead.

Dependencies

  • Python 3.7+ and xml.etree.ElementTree (standard library) — for edgy_generator.py, edgy_lint.py, edgy_render.py (SVG), the shared edgy_geometry.py / edgy_text.py and the generated edgy_core_links.py; Pillow is used for text measurement only when it happens to be installed together with a Liberation/Arimo/Arial font, never required
  • Headless Chromium / Chrome — optional, for PNG previews from edgy_render.py (EDGY_CHROMIUM=<binary> overrides detection)
  • draw.io CLI (for draw.io export to png/svg/pdf)
  • PlantUML (plantuml.jar + Java, or plantuml binary) — optional, only required when rendering PlantUML output to png/svg/pdf. .puml source generation has no extra dependencies.

04 同仓库更多 Skills