pi-config/skills/project-diagramming-archify/SKILL.md

name, description, version

name	description	version
project-diagramming-archify	Create or update an interactive Archify architecture map for a project. Accept plain-language requirements or pasted Mermaid (flowchart/sequence/stateDiagram) and compile typed JSON IR into a self-contained interactive HTML diagram (architecture, workflow, sequence, dataflow, lifecycle) under the project's docs/ directory. Use when the user asks for architecture/flow/data visualization, or the diagrams were just created/updated with project-diagramming-mermaid. Per-project only — never global.	1.0.0

project-diagramming-archify

Create polished, validated, interactive architecture diagrams as standalone HTML (with inline SVG, dark/light themes, pan/zoom, search, route tracing, PNG/SVG/WebM export) from typed JSON IR, using the bundled archify.mjs renderer. Everything lands under the project's docs/ directory.

When to use

• User asks for a client-facing / interactive architecture or flow visualization.
• The mermaid flow just completed (project-diagramming-mermaid) and the user said yes to the follow-up prompt.
• User asks to update an existing Archify map.

The skill asset

The renderer/vendor skill lives at ~/.agents/skills/archify/ (Archify v2.14, MIT, from tt-a1i/archify). It is self-contained: pure Node ≥18, zero npm deps. Key entry point:

node ~/.agents/skills/archify/bin/archify.mjs <command> ...

Commands (from the vendored skill's fast authoring path):

• guide "<scenario>" --json — when unsure which diagram type fits the ask.
• validate <type> <candidate.json> --quality showcase --json — iterate during authoring; showcase pass = 9 artifact checks, 0 composition errors, 0 warnings.
• deliver <type> <candidate.json> <output.html> --quality showcase --json — final acceptance (freezes spec bytes, atomically commits HTML, reports SHA-256 + byte counts).
• visual-check <output.html> --json — best-effort screenshot/containment evidence; needs Chrome/Chromium, exit 2 = skipped gracefully (e.g. .13 has no chrome). Never claim visual inspection you did not perform.

Canonical workflow (per project)

1. Scope + type — map the ask to a type: architecture (components/services/boundaries), workflow (processes/gates), sequence (API/request chains), dataflow (pipelines/ETL/lineage), lifecycle (state transitions). If ambiguous: node ~/.agents/skills/archify/bin/archify.mjs guide "<scenario>" --json.
2. Author JSON IR — read one matching schema (schemas/<type>.schema.json + schemas/common.schema.json) and one matching example (examples/<type>.*.json) from the vendored skill. Author fresh JSON: new stable IDs, domain wording, layout. ≤ 12 primary nodes; one obvious main path; sparse labels. Set meta.quality_profile to "showcase" unless the user explicitly asks for a dense standard map.
3. Accept Mermaid input (common path — after project-diagramming-mermaid): read the Mermaid for topology & meaning, then author fresh Archify JSON (do not mechanically copy styling):
   • flowchart / graph → workflow, or architecture for a component map.
   • sequenceDiagram → sequence (participants → semantic participants, arrows → messages).
   • stateDiagram → lifecycle (states & transitions keep meaning).
4. Validate-iterate: validate after every candidate edit and immediately before handoff. Fix only diagnosed issues; if two consecutive rounds don't improve the error count, stop and report truthfully.
5. Deliver: deliver <type> <candidate.json> <output.html> --quality showcase --json. Non-zero exit is never success.

Output locations (per-project, always under the project's docs/)

• JSON IR source (single source of truth): <project>/docs/archify/<topic>.<type>.json
• Interactive HTML map: <project>/docs/<topic>-map.html
• Schemas/examples to consult: ~/.agents/skills/archify/schemas/, ~/.agents/skills/archify/examples/.

Create <project>/docs/ (+ docs/archify/) if missing. Never write artifacts outside the project directory.

Publish to the central maps site (optional but recommended)

After a successful deliver, offer to publish the project's docs/ to the LAN maps site:

~/.agents/skills/project-diagramming-archify/publish-maps.sh [<project-dir>]

• Uploads docs/ to Caddy on .35 → https://maps.lab.audasmedia.com.au/<project>/docs/ (site index at https://maps.lab.audasmedia.com.au/ — Caddy file_server browse, no auth, read-only static hosting).
• Incremental + atomic (rsync -az): only changed blocks transfer; no half-written files on failure.
• Excludes *.visual-check.* sidecars automatically (keeps the browse index clean).
• Works from any machine with ssh key access to .35 (all three pi machines have it).
• publish-maps.sh --list shows what's already published.
• Wait for visual-check to pass first; publish-maps.sh does NOT re-run it.

Authoring rules (subset of the vendored skill — read SKILL.md for full invariants)

• Omit meta.visual_preset, meta.subtitle, meta.legend, meta.engineering_profile by default.
• Match authored strings to the user's language; preserve exact product names / commands / API paths / env names.
• Automatic routes own their endpoint sides; never accept an edge crossing an unrelated opaque node.
• Sequence: omit meta.column_fit (fixed); use "spread" when participants don't fit.
• Component types: frontend, backend, database, cloud, security, messagebus, external. Variants: default, emphasis, security, dashed.

Per-project activation

Activated per project with /config-add skill project-diagramming-archify (and the vendor skill archify is the renderer asset). If not available in the current project, that's expected — assets activate per project to keep context lean.

Related

• project-diagramming-mermaid — Mermaid flow that feeds into this skill (and the user-facing prompt to come here).
• pi-mermaid extension — ASCII preview of Mermaid in-chat.
• nixos-workflow skill — asset management (Gitea pi-config).
• system-architect skill — infra reference.

Obsidian documentation

Tools documented at 300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md (+ the network & container docs link it). Do not recreate diagram versions of those docs.