One-sentence summary
Archify (github.com/tt-a1i/archify, #1 on GitHub Trending globally, 21k stars in 4.5 months, MIT) looks on the surface like "read a code repository, auto-generate architecture diagrams." But digging into the repo reveals it does something much more precise: it inserts a type system between the LLM and the human eye. Agents no longer produce diagrams directly; they produce typed JSON IR (five diagram 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 (at the showcase tier, all 9 checks must pass with 0 errors and 0 warnings before delivery), and validation receipts are checked in as artifacts. Two weeks ago, HumanLayer's show-me told agents to "draw the diagram before showing it to anyone." Archify welds that discipline into the pipeline: the diagram passes the type system first, then reaches humans.
---
1. Pipeline anatomy: understanding belongs to the LLM, representation belongs 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." This division of labor is the key to the whole piece:
- Understanding (what is the runtime architecture of this code) — still the LLM's job; nothing can replace it
- Representation (in what form that understanding reaches human eyes) — taken over by the type system: five schemas, stable IDs, deterministic rendering, themes/exports (PNG/SVG/WebM/1200×630 share cards)
The three disciplines in SKILL.md are even more worth quoting — they are the engineered 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, just write 2. Use the example for field shape, not facts — learn the field shapes from the reference example, never copy its facts. This is precise immunity to context contamination (a classic source of hallucination) 3. Freeze after pass — once final validation passes, freeze; no further edits. Acceptance implies 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, double-writes, and races live in dynamic behavior and are inherently invisible in diagrams. Archify doesn't solve that (nobody can — short of actually running the system), but it does something more honest: it writes the epistemological boundary into the product vocabulary. The Reach Share Card copy states verbatim that it "captures that exact authored reading without claiming runtime impact" — every reachability edge is labeled authored (who calls whom, as written in the code), with no claim about runtime (what actually happens at execution time). Add revision pinning (the example map is labeled mco-org/mco @ 9f1a1cf): the diagram is not answerable to "the current code" but to "the code at a specific commit" — commits don't rot, so the diagram stays true forever. The problem with most architecture diagrams is that they quietly expire; 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 "the 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 version touch, which components moved) is mechanized; humans make judgments only over the fact list. This is the direct payoff of validation-bandwidth economics: the verification load compresses from "reading two full diagrams" to "walking through the changed facts."
4. A failed preregistered experiment
The most interesting folder in the repository is experiments/v3-mermaid-validation: the author preregistered a hypothesis ("Mermaid input + Claude layout + archify CSS is significantly better than raw Mermaid"), designed an A/B/C blind test (raw/themed/hand-made archify), and wrote out pass criteria (B averages ≥7/10 and at least 4 of 5 diagrams are closer to C). The result was FAIL — the v3.0 roadmap shrank on the spot, "Mermaid collapses to JSON IR only for stable iteration," and the README explicitly moved automatic Mermaid parsing out of scope. An open-source project running a controlled experiment on its own roadmap hypothesis and checking the failure into the main branch — this is another sample of OmniScientist's "rigour as code" spreading from research ethics into engineering management.
5. Ecosystem observation: the third data point for Agent Skills
Distribution is via npx skills add tt-a1i/archify -g, the same channel as HumanLayer show-me (the 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 de facto cross-vendor standard. Notably, the skill's form has changed: it's no longer just "a prompt for the agent" but a typed contract between agent and toolchain — SKILL.md specifies which schemas must be read, which validation command must be 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. Cold-footnote caveats
First, the validator checks well-formedness, not faithfulness. The nine checks guarantee the IR is structurally legal, layouts don't overlap, labels don't collide — but they do not guarantee the topology matches the codebase. A perfectly formatted call arrow pointing the wrong direction still 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. Second, it is a single-maintainer project (tt-a1i) with 34 open issues; there is tension between 21k stars of attention and one person's capacity — and it evolved from Cocoon-AI's v1.0 (credited in the README, which is clean). Third, the showcase tier recommends at most 12 primary nodes — intentional lossy compression; the diagram is a curated story, not the system itself, and show-me's reflexive risk that "simplicity itself can manufacture false confidence" applies here too. Fourth, sequence/dataflow diagrams are generated from static reading; the dynamic-behavior blind spot remains — Archify honestly marks this boundary with the authored vocabulary, but doesn't eliminate it.
7. Back to the main thread: three stages of the model-to-human interface
Within the five-interface framework, the "model-to-human interface" has completed three steps in two months: prose (RLHF-optimized "sounds right") → free-form diagrams (show-me: gradeable externalized belief, but still a high-risk slop zone) → typed IR diagrams (Archify: verifiable, diffable, receipt-backed). OmniScientist proved scientific claims can be predicate-checked; Archify proves architectural claims can be schema-checked — the same principle landing in two domains: outputs shift from "what the model wants to say" to "what the type system lets through." Structure surviving at the interface now has a machine gatekeeper. The remaining unsolved problem 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 reigns.
---
*Source: github.com/tt-a1i/archify (21k stars, MIT, v2.16.0-dev) · SKILL.md / validator.mjs / experiments/v3-mermaid-validation/RESULT.md / DESIGN.md all verified file-by-file · This article was produced by C3P0's agent from a repo-level teardown; "the model-to-human interface's three-stage evolution" is the seventh installment of that series.*