Archify: 91k Stars for a Gate Chain, Not a Diagram Tool

Archify Is a Verification Harness, Not a Renderer

Archify is not a diagram renderer; it is a verification harness that lets an LLM author layout and routing, then enforces determinism through a four-stage gate chain that must pass before any artifact is published (repository).

Its defensible contribution is not the picture. Mermaid, D2, PlantUML and Graphviz already produce deterministic layout for free; what Archify builds instead is a receipted production pipeline for a probabilistic author — a shape we last examined in our earlier piece on structured-output verification harnesses. The engineering question is whether pushing determinism into a post-hoc verification layer, rather than into the renderer, earns its cost. The honest answer has to carry the project’s own numbers.

How This Review Was Researched

This review is based on primary sources fetched on 2026-10-29 — the repository, its releases page, SKILL.md, and the project’s own benchmark suites — and we did not run it hands-on. Star counts, forks and commit totals come from the GitHub API on that date.

Everything below is source analysis: repository metadata, tagged release notes, skill instructions, benchmark protocols and tracker threads. Where we describe behaviour — gate ordering, receipt shape, delivery semantics — we are describing what SKILL.md and the schemas specify, not what we observed on a live run. Vendor adoption claims are labelled as vendor claims. Last reviewed: October 2026.

What Archify Actually Is

Archify is a JavaScript, Apache-2.0 skill for AI coding agents — created 2026-04-15, last pushed 2026-10-29, and standing at 91,264 stars, 6,207 forks and 1,751 commits on main (repository).

It also carries 228 subscribers and 266 open issues. As of v3.1.0 it ships ten native diagram types: architecture, workflow, sequence, dataflow, lifecycle, erd, class, tree, timeline and waterfall. Each type carries a JSON schema in archify/schemas/ and a checked example in archify/examples/ — the schema is the validation contract the pipeline enforces, not documentation.

Release cadence is fast for a project seven months old: v3.0.0 and v3.0.1 both landed 2026-09-28, v3.1.0 on 2026-10-14, v3.2.0 on 2026-10-18 with its GitHub release published a day later, plus a DeepSeek Harness plugin, archify-dsh-v1.0.0, on 2026-10-04 (releases). Hosts span Claude Code, Codex CLI, Cursor, OpenCode, Claude.ai zip upload, the DeepSeek Harness plugin and an opt-in Hermes Agent community skill (hermes skills install skills-sh/tt-a1i/archify/archify -y). The packaging follows the skill-as-packaged-instructions model Anthropic describes in equipping agents for the real world with Agent Skills.

The Gate Chain: validate, deliver, check, browser-check

The command is the product surface: finalize <type> <candidate.json> <output.html> --quality showcase --json. It runs validate (schema and layout rules), deliver (render plus atomic replace), a strict provenance check, then a real-browser browser-check (releases). SKILL.md is unambiguous: “A passing receipt proves the included validate, deliver, strict check, and real-browser browser-check gates passed.”

The design rule underneath that sentence is the one worth caring about: non-zero exit is never success. A harness for a probabilistic author has to be legible to a process that does not read carefully, so the exit code, not the prose, is the contract. The final gate is not a parser but a real browser performing layout, because the two header-overflow defect classes — title-overflow and subtitle-overflow — can only be measured by rendering.

Repair receipts are the second half of the contract. On failure, validate --json and deliver --json emit one JSON object whose diagnostics[] entries each carry a stable rule code, the exact subject path, measured evidence, and only supportedFixes. Stable codes give the model a discrete symbol to condition on instead of free-form prose; measured evidence keeps the correction anchored in the artifact rather than in the model’s guess about what went wrong. The README states a repair limit of two correction rounds — a deliberate constraint, and one the self-correction literature supports, since models do not reliably fix their own output without external feedback (Huang et al., ICLR 2024, Kamoi et al., TACL 2024).

Delivery is last-good. The render goes to a same-directory candidate, and only a passing artifact atomically replaces the target. preview binds loopback-only on 127.0.0.1 with a random port, reloads only after the latest candidate passes every gate, and keeps the previous verified diagram visible when a save is invalid. The failure mode this eliminates — a partially written file silently replacing a good one — is precisely the class of unguarded state mutation that makes unverified agent output hard to trust in the stateful-agent paradox.

Two quality profiles govern strictness: showcase (default) and standard (dense), whose stated crossover is a schema-first ERD over roughly 8 tables or 50 fields. ERD rules are table-first: entities[].attributes carries every physical column, key roles such as ["pk","fk"], references like "orders.id", and each domain renders as one solid rectangle of grid cells — with a renderer diagnostic erd/domain-not-drawn raised rather than an unnamed domain published. Read the chain as a whole and the shape is clear: schema-constrained generation at the API layer (OpenAI structured outputs) constrains what a model can emit; Archify concedes that freedom and constrains what ships.

Rendering Is a Solved Problem

Rendering quality is already solved and free: Mermaid (90,918 stars), D2 (25,753), Excalidraw (134,778), PlantUML (13,386) and Structurizr (507) publish deterministic layout engines or direct-manipulation canvases (Mermaid). In all of them the source declares topology and the tool owns placement.

D2 and PlantUML end up with coherent routing because the graph is a constraint the layout engine satisfies, not a series of assertions an author made; Excalidraw gets there by leaving the mouse with a human. Structurizr sits closest to Archify’s philosophy — the author declares a C4 model and views are generated — but it publishes a bounded, deterministic view set rather than arbitrary visual output. mingrammer/diagrams (42,763 stars) generates cloud topology from Python and belongs squarely in the deterministic camp.

Archify is the one row where a model owns placement, and the four gates are what it pays for that.

Evidence-Backed Nodes and the Provenance Edge Case

An Architecture node in Archify can mark itself SRC n and open a Git-verified file with a line range pinned to one public commit, including on self-managed GitLab hosts (repository). Ordinary artifacts stay source-free.

The README’s worked example traces mco-org/mco at commit 9f1a1cf: the node claims a fact, and the claim resolves to a file and line range at a pinned SHA, not to a branch that can drift. This is the correct shape for agent-authored documentation, and the part of Archify most transferable to other harnesses.

It is also under active repair, which is the more interesting finding. Tracker item #1129, repository evidence accepts annotated tag object IDs as commit SHAs, describes the provenance gate itself accepting an identifier that is not a commit. A verification layer that mishandles its own identity model is the standard failure mode of receipt systems: the gate is only as strict as its weakest comparison. That #1129 is filed and visible rather than silently closed counts in the project’s favour.

v3.2.0 Explainer Mode: The Same Contract on a Wider Surface

Explainer mode, shipped in v3.2.0 on 2026-10-18, extends Archify from a single diagram to a conclusion-first one-page answer authored as Markdown at candidate.archify.md, one question per panel, with numbered citations (releases).

Export covers PNG, WebP and JPG long-image formats plus PDF; styling is four styles — clean, editorial, product, Swiss — each in light and dark. patch explainer revises a single panel by ID, which matters: the artifact is addressable at panel granularity, so a correction does not force a full re-author or invalidate panels that already passed.

The interesting detail is what the gates do to a wider artifact class. Explainer delivery runs validate, deliver and check — three of the four gates, without the browser pass that the diagram path gets — so the harness generalises unevenly: the receipt discipline carries over, the last gate does not. That asymmetry is worth knowing before you assume every Archify artifact arrives with the same evidence.

The Benchmarks: Self-Published, Rigorous, and Inconclusive

Archify’s own benchmarks are self-published, carefully specified and inconclusive: the maintainers write that the sample “does not demonstrate an overall uplift”, and no suite contains an unassisted baseline to measure an uplift against (suites).

ordinary-model-floor runs 5 bounded tasks. firstPassUsable means usability after one complete agent invocation, which may include repairs — it is not first-draft success. The first complete three-model run (commit 66414c7, results/2026-07-26-pi-three-models.json) reported 10/15 under that era’s calibrated verifier, with five deterministic visual-quality failures and zero semantic or operational failures. Re-scored under the current, stricter verifier — which additionally requires a lifecycle’s recoverable failure to author a real retry transition — both the original matrix and the matched post-fix run (generation commit 2dce766) score 8/15, and the maintainers state plainly that “the single sample does not demonstrate an overall uplift”. The post-fix distribution was MiniMax 4/5, DeepSeek 2/5, Qwen 2/5. A quality-first run with no latency cutoff (commit 7eef4db) also scored 8/15 (MiniMax 3/5, Qwen 3/5, DeepSeek 2/5), with lifecycle improving 0/3 → 1/3 and architecture 2/3 → 3/3 while workflow and data-flow regressed. Reference fixtures are explicitly not benchmark evidence.

repair-rounds injects 8 deterministic defect classes — meta-missing-output, node-invalid-type, node-long-label, node-duplicate-id, edge-dangling-target, viewbox-oversized, title-overflow, subtitle-overflow — and measures rounds to pass, first-round disclosure rate, first-detection stage (validate / deliver / check / browser-check / undetected), late discovery rate, actionability and observable token cost, a deterministic lexical estimate rather than a provider tokenizer. It compares a rules mode (receipt-only consumer) against an oracle upper bound, with a default cap of 8 rounds. Two caveats matter: the suite is synthetic — its injected defects and rules-only repairer are not real agent behaviour — and the cap mismatch is real, since the shipped skill allows two correction rounds while the suite allows eight. The suite states it borrows multi-turn feedback efficiency, failure attribution by pipeline stage and observable token accounting, crediting ConvCodeWorld (ICLR 2025), HAL (ICLR 2026) and TALE (ACL 2025 Findings), and it makes no latency claims. For how badly agent benchmarks usually handle attribution, see our SWE-bench proxy critique.

real-repo-generation is a pilot protocol only: “no generation runs or quality results yet.” Five pinned public projects — OpenPI delegation, Hive workers, MCO provider orchestration, Squad task coordination, SkillRoster filesystem changes; 10 sessions for a single-type change and 20 for shared authoring/repair/delivery behaviour; a declared 20-minute budget per session; first-draft JSON captured before its first validation attempt; full session export plus 1440×900 screenshots. The design is sound — capturing the first draft before validation is the only way to measure first-pass behaviour honestly — and it currently contains no results, a distinction worth holding alongside our Terminal-Bench v2.1 benchmark study.

The Coverage Vacuum

No independent technical review of Archify could be fetched on 2026-10-29 — no third-party analysis, no Hacker News thread, no blog post — so the only adoption claims available are the project’s own (homepage). We treat that as the review’s most important negative finding.

To be fair to the project, coverage is linked from the README, just not independently verifiable here: a QbitAI feature and an interview from September 2026, and a midudev post. The unverified vendor claims are “130K+ installs on skills.sh” and “#1 on GitHub Trending’s weekly all-language repository list”, the latter resting on a creator X post dated 2026-09-01. Sponsors are Kimi Work, Supercode, OpenLux, PackyCode, AICodeMirror, Infistar and EverMind/Raven, several with affiliate links. None of it is verified here.

The tracker is more informative. #1130 records the explainer check receipt truncating at ~8 KiB on macOS when stdout is a pipe — a real failure mode for machine consumers, since a truncated receipt is a lying receipt. #1128 notes that GitHub Markdown source citations omit the plain view for line anchors, and #1127 that class rendering changes commas inside quoted parameter literals. PR #140 proposes a Mermaid flowchart importer for the typed architecture IR even though the README lists automatic Mermaid parsing as outside current scope — ambition outrunning the stated contract is a normal state for a fast-moving skill, and it is where the earned trust has to come from tests rather than promises.

The Bottom Line

Archify’s defensible contribution is the receipted gate chain, not the picture it draws: the four gates, the atomic last-good replace and the diagnostic receipts are the product, and no benchmark yet shows the artifact quality improving over the project’s own earlier generation (benchmarks).

Decision rule. Adopt if agents in your stack publish diagrams or one-pagers into shared artifacts that other systems or humans consume, and you need atomic last-good guarantees, machine-readable defect disclosure and a non-zero-exit contract you can wire into CI. Skip if a person draws the diagrams, or if your agents already emit schema-constrained output into a deterministic renderer — the gates buy correctness you may already have, at the cost of a browser in the loop. Watch three things before betting on it: whether real-repo-generation ever produces results, whether a larger sample turns 8/15 into a measurable effect, and whether the two-correction-round cap survives contact with the 8-round repair suite.

FAQ

Isn’t this just Mermaid with extra steps?

No: Mermaid (90,918 stars) owns layout and routing inside a deterministic engine (Mermaid), while Archify lets the model author both and pushes determinism into a post-hoc verification layer. The extra steps — validate, deliver, check, browser-check — are the product. They are only redundant if you already own layout determinism.

Do the benchmarks prove agents produce better diagrams with Archify?

No. No suite has an unassisted baseline to compare against, and the maintainers write that “the single sample does not demonstrate an overall uplift” (suites). The 8/15 figures measure delivery and defect disclosure under a verifier the project wrote.

What happens to my diagram when a save is invalid?

Nothing is lost. Archify renders to a same-directory candidate, and only a passing artifact atomically replaces the target (repository). The loopback-only preview on 127.0.0.1 with a random port reloads only after every gate passes, so the previous verified diagram stays on screen.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
• Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows
• NiteAgent — AI agent development, frameworks, and production patterns

Cross-links automatically generated from CodeIntel Log.