tt-a1i/archify

Archify is an agent skill that takes a codebase or a plain-text system description and produces a validated, self-contained HTML diagram — not a rough sketch, but a typed artifact with a machine-readable validation receipt attached. The core design decision is that the agent writes JSON IR, a bundled validator checks it against schema and layout rules, and only a passing candidate atomically replaces the previous output. If validation fails, the last known-good diagram stays visible and the diagnostics object tells the agent exactly which node or edge to fix, with a list of supported repairs. The agent is explicitly told not to rewrite the whole diagram and not to exceed two focused correction rounds. That constraint is doing real work: it keeps iterative chat-based refinement from drifting into full regeneration on every failure.

Five diagram types are supported — Architecture, Workflow, Sequence, Data Flow, and Lifecycle — each with its own schema. The README is candid about what is out of scope: no Mermaid parsing, no general-purpose auto-layout, no hosted sharing, no WYSIWYG editor. The tool makes a specific bet that layout judgment belongs to the agent, not to a force-directed algorithm, and that deterministic checks are more useful than a flexible renderer that silently accepts bad input.

The "truthful interaction" framing is the most interesting design claim. Focus, route tracing, upstream/downstream reach, and role comparison all operate on authored nodes and relationships — the viewer cannot invent topology or claim runtime impact it did not receive from the source. Source-backed nodes can optionally open Git-verified file ranges pinned to a specific commit, but only when that evidence was explicitly requested; ordinary diagrams carry no such claims. The Architecture Delta mode compares two validated snapshots and produces a receipt listing exactly what was added, removed, changed, moved, or rerouted — without inferring merge safety or risk.

Installation targets Raven, Cursor, Claude Code, Codex CLI, and opencode, plus a community DeepSeek Harness integration. The output is a single portable HTML file; exports include PNG, SVG, WebM, and 1200×630 share cards for routes and reach views. The preview loop binds only to localhost on a random port, watches one JSON file, and stops with Ctrl-C — it adds nothing to the generated HTML.

The practical value for anyone building agent workflows is the validation contract itself. Most diagram-generation tools give you output and leave correctness to visual inspection. Archify's validate --json and deliver --json always emit exactly one JSON object, even on failure, which means a calling agent can parse the result programmatically rather than scraping error text. That is a small but meaningful interface decision.