Diagram authoring

Generate architecture/workflow diagrams via Archify. Generate diagram artifacts (architecture, workflow, sequence, dataflow, lifecycle) as self-contained interactive HTML. This is the class-level umbrella / coordination layer: it tells you which tool to reach for and carries the operational pitfalls discovered in real use. The tool-specific reference manuals live in their own packages (see note below).

Tool selection

Need	Tool	Home
Rich, validated, interactive diagram; real-code provenance; Mermaid beautify	Archify (primary)	~/.hermes/skills/archify — load its SKILL.md first
Quick dark-theme SVG architecture card by hand	architecture-diagram (bundled, manual SVG)	~/.hermes/skills/creative/architecture-diagram
Hand-drawn whiteboard / sketch style	excalidraw	bundled
Mermaid source to pretty diagrams	Archify Mermaid input path	same

The Archify package's own SKILL.md and references/ are the authoritative authoring guide and are user-owned (installed from a git URL) — do not edit them. This umbrella exists because the operational reality (exact valid fields, gotchas, acceptance criteria) is spread across that package's docs and was only fully discovered in practice. Read references/archify-usage.md here for the condensed, battle-tested workflow and pitfalls.

Quick workflow (Archify)

1. Pick type (architecture | workflow | sequence | dataflow | lifecycle).
2. Read one matching schema + one matching example from the package for field shapes. Give the spec meta.repository.{url,revision} (40-char git SHA) ONLY if you are attaching per-component sources evidence — otherwise OMIT it. Two traps: (a) a token-embedded clone origin (https://x-access-token:<TOKEN>@...) never matches the plain https://github.com/... URL, so validate --repo-root fails origin-mismatch — just drop the field; (b) the dataflow schema rejects meta.repository entirely, so always remove it for dataflow. Validate against the actual repo:

   node bin/archify.mjs validate <type> <spec>.json --quality showcase --repo-root /path/to/repo --json

3. Fix exactly what the geometry diagnostics call for, revalidate, then accept with deliver (showcase = 9/9 artifact checks, 0 errors, 0 warnings). Ship + verify with check.
4. Always give the user the spec path alongside the HTML so it can be re-rendered.

Non-negotiable pitfalls

• --repo-root is required whenever the spec declares sources — otherwise validate fails repository-evidence/root-required.
• meta.repository is optional — omit it unless you attach per-component sources. A token-embedded clone origin breaks --repo-root validation (origin-mismatch), and the dataflow schema rejects repository entirely. See the workflow step 2.
• dataflow rows are capped 0..4 (5 lanes) and nodes need an explicit width for long sublabels; keep labels short and pin them with labelAt in the narrow stage gaps.
• Dense architecture diagrams fail showcase — reduce the graph before adding routing controls: drop low-value edges and widen column gaps, then pin remaining labels. More via/labelAt on a crowded graph just produces more crossing/label-route-clearance errors.
• deliver resolves a RELATIVE output path relative to the skill package dir, not your cwd — copy the artifact to the intended repo location afterward.
• engineering_profile: deployment-ownership forces a region boundary around every deployment component and requires any private security-group to sit inside exactly one shared region — add a region wrapping the whole cluster, then nest the group.
• Acceptance = deliver + check (geometry). Prove honesty: state whether you actually opened the artifact in a browser; validate/deliver/check do NOT equal visual review.

See references/archify-usage.md for the full validated field set and the repair recipes.

---

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/creative/diagram-authoring/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/creative/diagram-authoring/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · license MIT.

Published by Muse · 2026-10-04.