tt-a1i/archify

Archify is an agent skill that takes a codebase or a plain-text system description and produces a self-contained, interactive HTML diagram — not a Mermaid snippet, not a whiteboard export, but a typed JSON intermediate representation that gets validated before anything reaches the viewer. The validation step is the real design decision here. Before a new artifact replaces the previous one, schema checks, layout rules, HTML/SVG integrity, route probes, and label-to-route clearance all have to pass. If they don't, the last known-good diagram stays visible and the failure comes back as machine-readable JSON with stable rule codes, the exact offending subject, and a constrained list of supported fixes — not a stack trace, not a vague retry suggestion.

Five diagram types cover different communication needs: Architecture for components and trust boundaries, Workflow for CI/CD and approval chains, Sequence for API call traces, Data Flow for pipelines and sensitivity zones, and Lifecycle for state machines with retries and terminal outcomes. Each has its own schema. The agent picks the type; the CLI has a guide command that recommends one given a plain-language description.

The interaction model inside the generated HTML is more considered than most diagramming tools bother with. Keyboard shortcuts let you trace upstream and downstream authored reach from any node, probe the shortest directed path between two points, compare semantic roles side by side, and play finite named stories through the diagram. All of these operations work strictly on authored relationships — the README is explicit that the tool does not invent topology or claim runtime impact. Source-backed nodes can open Git-verified file ranges pinned to a specific commit, but only when that feature is explicitly requested; ordinary artifacts carry no source links.

The Architecture Delta mode is worth noting separately. It compares two validated JSON snapshots and produces a Before/Delta/After view with a machine receipt enumerating exactly what was added, removed, changed, moved, and rerouted. That's a concrete answer to the question of what changed in a system diagram across a PR, which is a gap most teams currently fill with screenshots and guesswork.

The install surface is broad: Claude Code, Codex CLI, Cursor, opencode, and Raven all get the full renderer and validation workflow via npx skills add. A community DeepSeek Harness integration exists at developer-preview status. Claude.ai upload works but depends on Node.js sandbox access. The README explicitly excludes automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing from current scope — a useful boundary to know before reaching for it.

The portable-by-default output format — one HTML file with PNG, SVG, WebM, and 1200×630 share card exports — means the artifact travels without a viewer dependency. That's a practical choice for teams where diagrams end up in wikis, READMEs, and Slack threads rather than living in a dedicated tool.