Archify

What It Does

Archify is an agent skill, derived from Cocoon-AI/architecture-diagram-generator v1.0 (the lineage is declared in the SKILL.md frontmatter), that turns a system description or a repository into an interactive, self-contained HTML diagram. An agent authors a small typed JSON specification in one of five modes (architecture, workflow, sequence, dataflow, lifecycle), and the bundled zero-dependency Node CLI validates it against JSON Schemas plus measurable layout and composition rules, then renders a single HTML file with inline SVG, dark and light themes, optional motion, guided stories, and export to PNG, SVG, WebM, and 1200x630 share cards. A separate compare command diffs two validated architecture snapshots into a Before, Delta, and After proof with a machine receipt, aimed at pull-request review. The audience is developers who want their coding agent to produce diagrams that can be checked rather than guessed at, and the repo is explicit that this is not a general drawing editor or a Mermaid theme.

The Good

Validation is the product, and it is measurable. A showcase-profile validate run does not just parse JSON: it renders the candidate, then reports 9 artifact checks (single_svg, finite_svg, orthogonal_arrows, label_route_clearance, relationship_crossings, relationship_corridors, and friends) plus a composition block with hard numbers. On the bundled agent-tool-call workflow example: 0 proper crossings, 0 ambiguous corridors, minimum label-to-route clearance 52.1px, maximum 2 bends per relationship, maximum stretch 1.257 against a 1.35 limit, and zero routes over any suggested limit. This turns "the diagram looks fine" into numbers an agent or a CI can assert on.

Failures return machine-readable repair receipts, and the negative cases behave exactly as documented. I fed the CLI a workflow file with sequence-style keys and got exit 1 with seven diagnostics, each carrying a stable code (schema/required, schema/additionalProperties), severity, the exact JSON path, the evidence keyword, and a supportedFixes array with the precise action ("add required property \"schema_version\""). A second file with the correct shape but an edge pointing at a nonexistent ghost-node was rejected at the layout stage with two diagnostics naming both the dangling edge and a mainPath pair with no matching edge. The README's claim that failures "identify the exact local repair in machine-readable JSON" is accurate.

Delivery is atomic and deterministic, with receipts. The deliver command freezes the specification bytes into a same-directory snapshot, renders and checks the candidate, and only then replaces the target, reporting SHA-256 and byte counts for both spec and artifact. My deliver run on the cache-miss sequence example returned a 4,345-byte spec and a 640,506-byte artifact, and the artifact was byte-identical to the repo's own checked-in rendered example (verified with cmp). Identical input plus identical code yields identical output, which is what makes the whole validate-then-commit pipeline trustworthy. A dedicated check-release-identity gate confirms version consistency (2.14.0 across package.json, SKILL.md metadata, and CHANGELOG) and passed here.

The test suite is deeper than most skill repos' entire codebase. npm test ran 628 tests with 628 pass, 0 fail, and 0 skip in 44 seconds across 77 bundled test modules (15,269 lines of test code against 11,399 lines of non-test source). Coverage includes renderer golden files, CLI behavior, degraded environments, the preview contract, share cards, and even the GitHub Pages gallery build. CI runs the matrix on Node 18, 20, 22, and 24, with separate workflows for the DeepSeek Harness integration and releases.

Zero runtime dependencies, and the install path works end to end. The skill package declares no dependencies at all (ajv appears only as a devDependency for validator code generation, and the generated validators are checked in, which is why validate works on a fresh clone before any npm install). In an isolated HOME, npx skills add tt-a1i/archify --skill archify landed the complete 5.7MB skill into .claude/skills/archify and, with --agent hermes-agent, into .hermes/skills/archify; the installed copy passed doctor (15 of 15 checks) and rendered the demo from its own directory. Node 18 or newer is the only requirement.

The benchmark and process artifacts show unusual honesty for a 12.8K-star repo. The benchmarks/ordinary-model-floor harness measures whether an ordinary model can produce a usable diagram on attempt 1, publishes evidence JSONs pinned to a repository commit and a package SHA-256 with an explicit freeze policy, and states in its README that "reference fixtures are not benchmark evidence and must not be published as model results." The 88KB CHANGELOG follows Keep a Changelog, every entry ends with an explicit list of what was NOT added, and the docs directory contains 49 dated rounds of visual-evolution research. The one prior art dependency is credited in the frontmatter, and the MIT license file ships both at the root and inside the skill package.

The Bad

Four of the five shipped rendered examples fail the project's own visual-check containment gate. Version 2.14.0 (2026-08-11, four days before this review) added visual-check, which measures first-screen containment at 1440x900, 1600x1000, 1920x1080, and 2048x1320. Running it against the repo's own checked-in examples: web-app-rendered.html passes, but the sequence, workflow, lifecycle, and dataflow examples all fail with vertical overflow at every viewport (the sequence example scrolls 1,611px against a 900px viewport at 1440x900; the dataflow example 1,312px). The tool reports the failures honestly (exit 1, visualReview "pending"), and the examples predate the gate, but the SKILL.md instructs agents that delivered showcase artifacts must satisfy exactly this containment contract. The showcase artifacts the project ships do not meet the newest bar the project sets, which is a self-consistency gap until they are re-authored or re-rendered.

Hermes and OpenClaw installs work but are undocumented. The README's installation table and the generated start-page switcher cover Cursor, Claude Code, Codex CLI, OpenCode, and Raven, plus a Claude.ai upload path. The skills CLI the README tells you to use actually supports more than 70 agents, including hermes-agent and openclaw, and I verified both install targets land a working skill. But nothing in the README says so, and the agent id is hermes-agent rather than hermes, so a Hermes user's first guess at the flag fails with "Invalid agents: hermes" and a wall of valid names.

Layout-stage diagnostics contradict the SKILL.md's own repair instructions. The skill contract tells the agent to "choose from supportedFixes" when a validation fails, and schema-stage diagnostics populate that field properly. But both layout/constraint diagnostics in my dangling-reference test returned an empty supportedFixes array and an empty evidence object, with the repair guidance buried in the message text instead. An agent following the contract has nothing to choose from at the layout stage. This is an inconsistency between the contract and the receipt format, not a correctness bug.

Small CLI rough edges. There is no --version flag: the CLI answers "Unknown command" with a usage dump and exit 2, so the version is only discoverable from package.json, the README badge, or the release page. The demo subcommand rejects --quality with a usage dump while validate, deliver, and preview all accept it. The package-smoke script fails if you run npm install inside the skill directory (it demands the packaged tree contain no node_modules), which is correct for release staging but easy to trip during evaluation; the shipped zip itself contains zero node_modules entries across its 78 files.

Bus factor and monetization signals. Six contributors are credited, but 138 of roughly 145 commits belong to tt-a1i, so this is effectively a single-author project despite 12,801 stars and 945 forks. The README leads with a paid sponsor block (an APINEBULA affiliate link with a discount code) above the first content section, plus an EverMind/Raven sponsorship; both are disclosed, but the affiliate link sits above the fold of an MIT project's front page.

Smoke Test Results

Tested on the macOS host (aarch64, macOS 26.5.2), Node v24.13.1, npm 11.8.0, with Google Chrome available for visual-check. The repo was shallow-cloned (45MB with depth 1) into an isolated directory, and installs were exercised in an isolated HOME so nothing touched the real agent configuration.

Run A. Fresh clone, no dependencies installed

$ git clone --depth 1 https://github.com/tt-a1i/archify.git /tmp/archify-review

PASS (clone completes, 45MB)

$ cd archify && node bin/archify.mjs doctor

[ok] Node.js v24.13.1 (requires >=18)

[ok] Core template ... [ok] Standalone schema validators

[ok] architecture/workflow/sequence/dataflow/lifecycle renderer, schema, and example

Archify is ready.

PASS (15 of 15 doctor checks, no npm install needed)

$ node bin/archify.mjs demo /tmp/archify-demo

Demo ready: /tmp/archify-demo/archify-demo.html (637,933 bytes)

PASS (self-contained HTML produced)

$ node bin/archify.mjs guide "Show an API request with Redis cache miss"

Recommendation: API request chain [sequence], Confidence: high

PASS (router works with copy-ready prompt)

$ node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

"composition": { "status": "pass", "summary": { "errors": 0, "warnings": 0 } }

PASS (validators are pre-generated and checked in, so validation works pre-install)

Pass rate: 5 of 5. The skill is runnable the moment it is cloned; nothing needs installing for the core validate, demo, and guide path.

Full fresh log →

Run B. With deps installed (npm install, single devDependency)

$ npm install --no-audit --no-fund

added 5 packages in 524ms

PASS (ajv and friends only; runtime stays dependency-free)

$ npm run check:validators

PASS (generated validators match schemas)

$ npm run check:release-identity

release identity ok: 2.14.0

PASS (version consistent across package.json, SKILL.md, CHANGELOG)

$ node test/golden.mjs

PASS (golden render fixtures)

$ node ../scripts/run-tests.mjs

tests 628, pass 628, fail 0, duration 44.3s

PASS (full suite green)

$ node ../scripts/package-smoke.mjs

Error: packaged skill must not contain node_modules

FAIL (self-inflicted: running npm install inside the skill dir trips the packaging guard; the shipped archify.zip contains zero node_modules entries in 78 files)

Pass rate: 5 of 6. The only failure is an environment-ordering artifact of the test itself, not the shipped package: the smoke script is written for a clean staging tree and correctly detects that node_modules does not belong in a packaged skill.

Full functional log →

Run C. Functional verification (does it do what it claims?)

$ node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

ok: True, composition: pass, errors: 0, warnings: 0, 9 of 9 artifact checks

PASS (positive case: showcase profile fully green, with measured composition metrics)

$ node bin/archify.mjs validate workflow /tmp/archify-negative/workflow-broken.json --quality showcase --json

ok: False, exit 1, 7 diagnostics with code/subject/evidence/supportedFixes

PASS (negative case 1: wrong-shape input rejected with exact repair actions)

$ node bin/archify.mjs validate workflow /tmp/archify-negative/workflow-dangling.json --quality showcase --json

ok: False, exit 1, diagnostics: Edge "GET /api/data" references unknown target "ghost-node"; mainPath pair has no matching edge

PASS (negative case 2: semantic dangling reference caught at layout stage)

$ node bin/archify.mjs deliver sequence examples/cache-miss-request.sequence.json out.html --quality showcase --json

ok: True, spec sha256 4bbaa6ca... (4,345 bytes), artifact sha256 738d651b... (640,506 bytes), 9 of 9 checks

cmp out.html examples/sequence-cache-miss-request.html -> BYTE-IDENTICAL

PASS (deterministic render matches the repo's own shipped artifact exactly)

$ node bin/archify.mjs compare architecture base.json head.json delta.html --receipt r.json --json

ok: True, completeness: complete, proofLevel: authored

components: added 1, changed 1, removed 1, moved 1; connections: added 1, changed 2, removed 1, rerouted 1

PASS (delta receipt classifies every change kind it documents)

$ node bin/archify.mjs visual-check examples/web-app-rendered.html --json

"ok": true, containment pass at all four viewports

PASS (containment gate works and passes on the architecture example)

$ for f in sequence/workflow/lifecycle/dataflow examples; visual-check each

web-app PASS; sequence FAIL (scrollHeight 1611 vs 900); workflow FAIL; lifecycle FAIL; dataflow FAIL (1312 vs 900)

PASS as a tool-behavior test (exit 1 with truthful receipt), but it exposes that 4 of 5 shipped examples fail the project's own newest gate

Functional pass rate: 7 of 7. Every claim tested held: schema-gated validation with repair receipts, atomic deterministic delivery with hashes, delta classification, and an honestly reporting visual gate (whose current results on the repo's own older examples are the review's main finding).

Full functional log →

What the runs tell you

The scripts and validators work from a bare clone with zero installs, the full test suite is green, and the render pipeline is deterministic to the byte. What could not be verified here is the skill's other half: the SKILL.md is a behavioral contract for a coding agent (bounded reading, two-round repair limit, honest failure reporting), and exercising that requires a live agent session, as does clicking through the viewer's exports and stories in a real browser.

Setup Walkthrough

1. Install with the skills CLI: npx skills add tt-a1i/archify -g (adds a global install for whichever agent it detects). For an explicit target: npx -y skills add tt-a1i/archify --skill archify --agent claude-code --copy --yes. On Hermes, use --agent hermes-agent.
2. Sanity-check the install: cd /archify && node bin/archify.mjs doctor. You want "Archify is ready." plus 15 ok lines.
3. Render a first artifact without authoring anything: node bin/archify.mjs demo /tmp/archify-demo, then open the HTML.
4. Ask your agent for one bounded view, for example: "Use archify to map this repository's runtime architecture. Show 8-12 core components, one primary path, external dependencies, and trust boundaries."
5. The agent authors typed JSON, then runs node bin/archify.mjs validate .json --quality showcase --json until clean, and finally deliver to produce the checked HTML with a receipt.

Gotchas: the only requirement is Node 18 or newer. The demo subcommand takes no --quality flag. If you run npm install inside the skill directory, the packaging smoke will (correctly) complain about node_modules; the runtime never needs it. Chrome must be installed for visual-check, which reports a truthful skip otherwise.

Alternatives

1. Mermaid (mermaid-cli) - the default text-to-diagram tool; far smaller outputs and broader tooling, but no typed IR, no validation gates, and no repair receipts, so layout quality depends on luck and manual tweaks.
2. Structurizr / PlantUML with the C4 model - diagram-as-code aimed at humans writing code; richer notations for software architecture, but steeper syntax, no agent-first contract, and no measurable composition checks.
3. pbakaus/impeccable - complementary rather than competing: it polishes and lints the visual quality of generated frontend HTML. Archify's own docs site dogfoods it (there is a .impeccable directory in the repo).
4. Graphify-Labs/graphify - for querying a codebase as a graph from an agent; produces text answers about structure rather than shareable visual communication artifacts.