Archify: A Type System for the Model-to-Human Interface — The Industrialized Sequel to show-me

One-line summary

Archify (github.com/tt-a1i/archify — #1 on GitHub Trending, 21k stars in 4.5 months, MIT) looks like "read a codebase, auto-generate architecture diagrams," but reading the repo reveals something far more precise: it inserts a type system between the LLM and the human eye. Agents no longer produce diagrams directly; they produce a typed JSON IR (five schemas: architecture / workflow / sequence / dataflow / lifecycle), and a deterministic compiler renders it into interactive HTML/SVG. The IR must pass JSON Schema validation plus layout/routing/label-gap checks (the showcase tier requires all 9 checks to pass with 0 errors, 0 warnings before delivery), and validation receipts are checked in as artifacts. Two weeks after HumanLayer's show-me taught agents to "draw first, show later," Archify welded that discipline into the pipeline: diagrams pass the type system before a human sees them.

1. Pipeline anatomy: understanding belongs to the LLM, representation to the type system

The README's self-description is a single technical statement: "Agents produce typed JSON IR; Archify deterministically compiles it into HTML/SVG." That split is the key to the whole piece:

• Understanding (what is this code's runtime architecture?) — still the LLM's job; nothing replaces it
• Representation (what form the understanding reaches human eyes in) — taken over by the type system: five schemas, stable IDs, deterministic rendering, themes/exports (PNG/SVG/WebM/1200×630 share cards)

Why is this split valuable? Recall show-me's residual problem: Dex himself admitted Mermaid diagrams were "sometimes they're still slop" — free-text diagram formats remain fluent nonsense, just graphic slop instead of prose slop. Archify's answer is to attach predicates to the output: schema validation is a real ajv-style validator (type/enum/pattern/minItems reported item by item with structured diagnostic codes), and layout/routing/label gaps are decidable geometric checks. "Atomic validation before delivery" — a candidate must pass every check before replacing the last-known-good output. This is blue-green deployment discipline, applied to diagrams.

Three disciplines from SKILL.md are worth quoting — they are the engineering version of show-me's "skip the preamble":

1. Artifact first — "the next tool action must be writing the candidate file; do not plan coordinates in prose." show-me said don't explain; Archify says don't even plan — write directly 2. Use the example for field shape, not facts — learn field shapes from reference examples, never copy facts. This is precise immunity against context contamination (a classic hallucination source) 3. Freeze after pass — once final validation passes, freeze; no further edits. Acceptance means immutability

2. "Authored reach": a productized answer to the static/dynamic debate

My warning in the show-me piece was: diagrams are static beliefs; retries, dual writes, and races live in dynamic behavior and are naturally invisible to them. Archify doesn't solve this (nothing short of actually running the system can), but it does something more honest: it writes the epistemic boundary into the product's vocabulary. The Reach Share Card copy says verbatim: "captures that exact authored reading without claiming runtime impact" — every reachability edge is labeled *authored* (who calls whom as written in code), refusing to claim *runtime* (what actually happens at runtime). Add revision pinning (the example map cites mco-org/mco @ 9f1a1cf): the diagram answers not for "the current code" but for "the code at some commit" — commits don't rot, so the diagram is permanently true. Most architecture diagrams rot silently; Archify's answer is to make them expire precisely (pinned to a revision).

3. Before/Delta/After: mechanizing the review map

show-me's third checkpoint was "a review map after completion." Archify turned it into a feature: compare two validated snapshots and output Before/Delta/After with "exact added, removed, changed, moved, rerouted facts" — the diff of an architecture change is a list of facts, not a feeling. The most expensive part of PR review (which edges did this change touch, which components moved) is mechanized; humans judge only the fact list. This is the direct payoff of validation-bandwidth economics: the review burden compresses from "read two full diagrams" to "walk through the changed facts."

4. A failed pre-registered experiment

The most interesting folder in the repo is experiments/v3-mermaid-validation: the author pre-registered a hypothesis ("Mermaid input + Claude layout + archify CSS significantly better than vanilla Mermaid"), designed an A/B/C blind test (vanilla / themed / hand-authored archify), and wrote explicit pass criteria (B average ≥7/10 and at least 4 of 5 diagrams closer to C) — the verdict was FAIL. The v3.0 roadmap shrank on the spot: "Mermaid collapses to JSON IR for stable iteration only," and the README explicitly moves automatic Mermaid parsing out of scope. An open-source project running a controlled experiment on its own roadmap assumptions and checking the failure into the main branch is another sample of OmniScientist-style "rigour as code" spreading from research ethics into engineering management.

5. Ecosystem note: a third data point for Agent Skills

Distribution is npx skills add tt-a1i/archify -g — the same channel as HumanLayer's show-me (skills CLI), covering four agent platforms (Cursor / Claude Code / Codex / OpenCode) plus a DeepSeek Harness plugin. With Mistral's starter app bundling .agents/skills/, "the skill as the distribution unit of agent software" is now a cross-vendor de facto standard. Notably, the skill's form has changed: it's no longer just "a prompt for the agent" but a typed contract between the agent and the toolchain — SKILL.md specifies which schemas to read, which validation commands to run, what counts as passing, and what is forbidden after passing. show-me was a declaration of discipline; Archify is a contract of discipline.

6. A sober footnote

1. The validator checks well-formedness, not faithfulness. The nine checks guarantee legal IR structure, non-overlapping layout, non-colliding labels — but not that the topology matches the codebase. A perfectly formatted call arrow pointing the wrong direction passes all-green. Truth-checking still falls to manual spot checks of revision-verified source links (click a node, read the code); the last mile of validation bandwidth is still human. 2. Single maintainer (tt-a1i), 34 open issues — there is tension between 21k stars of attention and one person's capacity. It also evolved from Cocoon-AI v1.0 (credited in the README — that part is clean). 3. The showcase tier recommends at most ~12 primary nodes — deliberate lossy compression. The diagram is a curated story, not the system itself; show-me's reflexive risk that "simplicity itself can manufacture false confidence" applies here too. 4. sequence/dataflow diagrams are generated from static reading; the dynamic-behavior blind spot remains. Archify honestly marks this boundary with its authored vocabulary, but doesn't eliminate it.

7. Back to the main thread: the three-stage evolution of the model-to-human interface

Within the five-interface framework, the "model→human interface" has completed three steps in two months: prose (RLHF-optimized "sounds right") → free-form diagrams (show-me: gradeable externalized belief, but still high-risk slop territory) → typed IR diagrams (Archify: verifiable, diffable, with receipts). OmniScientist proved scientific claims can be predicate-checked; Archify proves architectural claims can be schema-checked — the same principle landing in two domains: the output shifts from "what the model wants to say" to "what the type system lets through." Structures surviving at the interface now have a machine gatekeeper. The unsolved question is exactly the one Archify admits: the type system can guard form, not truth — beyond the completeness boundary of formal validation, human validation bandwidth still rules.

---

*Sources: github.com/tt-a1i/archify (21k stars, MIT, v2.16.0-dev) · SKILL.md / validator.mjs / experiments/v3-mermaid-validation/RESULT.md / DESIGN.md verified file by file.*