archify-vscode-ext/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
archify-vscode-ext	Author, validate, render and manage Archify diagrams (.archify YAML files of the kinds architecture, workflow, sequence, dataflow and lifecycle) and Archify models: a folder with main.archify on top, shared elements in *.archify-registry files, ref: components, diagram: links and C4-style folders, as read by the Archify Diagram Viewer VS Code extension. Bundles the Archify validator and renderer, so diagrams are checked and rendered to HTML without VS Code. Use this skill when asked to create, edit, fix, validate, render or organise .archify files, build a C4 or architecture model as code, add a shared element or a registry, scaffold a model folder, or explain why a diagram does not validate, even if the user only says "draw the architecture", "make a diagram of this system", "put the diagrams together" or "the diagram shows an error".	MIT	Requires Node.js 18+, bash and go-task (task). No network access; Archify is bundled under scripts/vendor.	author version origin-repository targets root-at-skic 1.0 https://gitea.lego-cloud.eu/vscode-extensions-skills/archify-vscode-ext.git Archify Diagram Viewer (root-at-skic.archify-vscode-ext)

Archify diagrams and models

Write diagrams as text next to the code, in the form the Archify Diagram Viewer extension opens as interactive pictures. One .archify file is one diagram. A folder with main.archify on top is a model: diagrams that belong together, shared elements defined once in a registry, and links between diagrams.

Overview

Archify (MIT, by tt-a1i) is the renderer and validator. The extension bundles it; so does this skill (scripts/vendor/archify), so every task here runs on plain Node and needs nothing installed. The model layer (registry, ref, diagram: links) is the extension's; this skill resolves it the same way the extension does before Archify sees a diagram. Every task prints YAML on stdout (success: true|false first) and logs to stderr.

Install with npx skills add https://gitea.lego-cloud.eu/vscode-extensions-skills/archify-vscode-ext.git --global, update with npx skills update --global; or clone and git pull. One copy per machine. All tasks run from this skill's scripts/ folder:

cd <this-skill>/scripts
task --list-all

Task	What it does
task model:validate -- --dir="<model or file inside>"	Registry, every diagram (refs resolved, Archify validator), every diagram: link. Exit 1 on any error. Works on a single diagram outside a model too.
task model:list -- --dir="<model>"	What the model page shows: metadata, diagrams by folder, registry elements with "used in N diagrams", decisions with status and the diagrams that reference them.
task model:scaffold -- --dir="<folder>" --id="<id>" --name="<name>" [--description="…"] [--c4]	Creates main.archify; with --c4 also registry/ and the 0100-context, 0200-containers, 0300-components folders with starter diagrams. Never overwrites.
task model:scaffold -- --dir="<folder>" --example="<name>" [--id="<id>"] [--name="<name>"] [--description="…"]	Copies a complete example model: c4-standard-web-app, c4-e-shop or c4-event-based-integration (the same three the extension offers under Archify | New Model…). Id, name and description default to the example's own. Never overwrites.
task model:resolve -- --file="<diagram>" [--out="<file.json>"]	The Archify JSON the extension hands to Archify, for the plain Archify CLI or CI.
task diagram:validate -- --file="<diagram>"	One diagram through Archify (refs resolved when inside a model).
task diagram:render -- --file="<diagram>" --out="<file.html>"	Standalone HTML page for people without VS Code.
task test	The skill's own checks against the examples and scaffolded models.
task sync	Refresh scripts/vendor/archify from an Archify checkout (maintainers only).

Options for validate and render: --quality=showcase (stricter composition checks), --repo-root=<checkout> for diagrams with meta.repository and sources.

Workflow

1. Diagram or model?

• One picture, no shared things: a single .archify file anywhere. Skip to step 4 and write inline elements (id, type, label).
• Several pictures of one system, the same elements in more than one of them, levels (context, containers, components), "click the API to see inside": a model. Start with step 2.

A diagram inside a model is still a plain diagram: it opens, renders and exports on its own.

2. Start a model

New folder:

task model:scaffold -- --dir="/path/to/online-shop" --id="online-shop" --name="Online Shop" --description="Web shop, API, workers and stores." --c4

Or start from a complete example and rename it (examples/ lists the three; C4 - Standard Web App, C4 - E-Shop, C4 - Event-Based Integration):

task model:scaffold -- --dir="/path/to/hub" --example="c4-event-based-integration" --id="hub" --name="Integration Hub"

Existing folder of diagrams: add main.archify with the model block (see references/formats.md); every .archify below it is now part of the model. --c4 is a convention, not a requirement: any folders, any depth.

The model's root is the nearest folder above a file that holds main.archify. Nothing else marks it. main.archify may also hold a diagram of its own (the overview), below the model block.

3. Add a shared element

Put it in a *.archify-registry file under the root (one file or many; registry/people, registry/systems, registry/containers is the C4 split). The key is the id, unique across all registry files:

schema_version: 1
elements:
  api:
    type: backend            # Archify component type, fixed for the element
    label: API
    sublabel: Node.js
    brand: node-js           # optional, an Archify brand id
    description: >
      Owns authentication, orders and the catalogue.
    diagram: 0300-components/api.archify   # the diagram that explains it, relative to the root

Fields that reach Archify: type, label, sublabel, tag, icon, brand, sources. description and diagram belong to the model only. Write description with > (a folded block): a plain scalar with : in it is a YAML error.

4. Write a diagram

schema_version: 1
diagram_type: architecture
meta:
  title: Containers
  output: containers.html      # required by Archify; relative .html path
components:
  - ref: api                   # from the registry; id defaults to "api"
    pos: [460, 160]
    size: [130, 60]
  - ref: db
    label: Orders DB           # label, sublabel, tag may be overridden
    pos: [670, 260]
    size: [130, 60]
  - id: cron                   # unshared, inline, as in any diagram
    type: backend
    label: Nightly job
    pos: [670, 460]
    size: [130, 60]
connections:
  - { from: api, to: db, label: SQL }

• ref plus the diagram's own geometry (pos, size, or row/col). id: db-replica with ref: db draws the same element under another id.
• Override only label, sublabel, tag. type, brand, icon, sources come from the registry; if they differ, it is a different element.
• A component may add diagram: <path> to link to another diagram; it wins over the registry's link.
• Connections, boundaries, lanes and everything else are plain Archify and use the ids.

Read references/authoring.md before writing a diagram of a kind you have not written in this session: the five kinds, fields, the position grid, labels, boundaries and the validator's error codes with their fixes.

5. Validate after every change

task model:validate -- --dir="/path/to/online-shop"

Read the output top down:

• summary.errors and summary.warnings; diagramsOk of diagrams.
• problems: model-level (duplicate ids across registries, a nested main.archify, bad links in registries).
• diagrams[].problems: per file, each with file, line, pointer (JSON pointer into the file, /components/3/ref), code for Archify's own diagnostics, and the message. Archify messages often end with a suggested fix (move "db" pos to [178, 70], labelAt); apply that value rather than guessing.

Fix in this order: YAML syntax, registry problems, unknown refs and forbidden overrides, schema errors (schema/…), node overlap and out-of-range placement, edges through nodes, crossings and corridors, label clearance. Run again until success: true. For one file, task diagram:validate -- --file=… is faster. --quality=showcase adds composition warnings; use it before a diagram is shown to people.

6. Render for people without VS Code

task diagram:render -- --file="/path/to/online-shop/0200-containers/online-shop.archify" --out="/tmp/containers.html"

A standalone HTML page with Archify's viewer (focus, search, export). Links to other diagrams are not followed outside VS Code. task model:resolve -- --file=… --out=x.json gives the resolved JSON when someone wants to run the plain Archify CLI (node scripts/vendor/archify/bin/archify.mjs validate architecture x.json --json).

Folder conventions

online-shop/
  main.archify                 model block (+ optional overview diagram)
  registry/*.archify-registry  shared elements, split any way
  0100-context/…               groups are folders; numbers only sort them
  0200-containers/…
  0300-components/…

Diagrams next to main.archify are listed first, ungrouped; deeper ones by folder path. Read references/folders.md for the layouts (single diagram, smallest model, grouped, C4 with 0400-code) and how levels hang together through diagram: links.

Gotchas

• Colons in plain scalars. description: Orders: the source of truth is a YAML error (nested mapping). Use description: > and indent the text, or quote it. The same for labels with : .
• The model block must not reach Archify. Archify's schemas set additionalProperties: false at every level; any unknown key (model, ref, description, diagram, a typo like colour) fails as schema/additionalProperties. The tasks strip the model keys; everything else must be a schema field.
• type and brand cannot be overridden on a ref component. The validator reports "type" of shared element "db" cannot be overridden. Change the registry or use a different element.
• Ids are unique per diagram. Two ref: db entries in one diagram clash; give the second id: db-replica.
• ref outside a model is an error. Without main.archify above the file there is no registry; the extension would show the component as external with the ref name. Define it inline or create the model.
• Overlapping labels need labelAt (or labelDx/labelDy). Archify reports label clearance with a suggested point; set exactly that. Shortening the label is the last resort, never deleting it.
• meta.output is required and must be a relative POSIX .html path (containers.html); it is not where the render task writes, --out is.
• Boxes need clear gaps. Components closer than 8px fail; labels wider than the box fail (6.5px per character plus 13). The grid in references/authoring.md keeps a standard layout clear.
• Links are relative to the model root, never to the file, and must end in .archify and exist. .. is refused.
• A second main.archify deeper down is reported, not nested. One model per tree.
• Diagram kinds other than architecture take ref too (workflow and dataflow nodes, sequence participants, lifecycle states), but the registry type must fit that kind: lifecycle states use their own type enum, and sequence participants have no tag.
• Decisions are files, ids are words. One *.archify-decision per decision (decision: block with id, title, status, date, elements, diagrams, supersedes; prose in context, decision, consequences). Diagrams point at them with decisions: [<id>] on the diagram, a node or an edge; the resolver strips the key. An unquoted numeric id (0001) is refused because YAML reads it as 1. When an agent changes the shape of a model (a new store, a new queue, a new boundary), it writes a decision and links the elements it touched.
• Descriptions stay in the registry. The extension shows an element's description as a tooltip in its Elements panel; nothing is generated into the diagram. Write cards: in a diagram only when you want text blocks below it.
• No em dashes or smart quotes in ids; ids match ^[a-zA-Z][a-zA-Z0-9_-]*$.

References

• Read references/authoring.md when writing or repairing a diagram: kinds, fields, grid, labels, boundaries, brands, validator codes and fixes.
• Read references/formats.md when writing main.archify, a registry, a ref or a link, or when unsure what the tasks strip before Archify runs.
• Read references/folders.md when laying out a model folder or explaining how the extension finds the root and groups diagrams.
• examples/c4-standard-web-app/, examples/c4-e-shop/ and examples/c4-event-based-integration/ are complete C4-style models that validate with 0 problems; copy their shape, or copy one with model:scaffold --example.