Archify, vendored the way we vendor Chroma

Why Care?

A hand-drawn architecture diagram is a claim about the code. A generated one is a description of it. The first goes out of date silently; the second goes out of date visibly, when regeneration produces a diff.

That distinction is the whole reason to be careful here. The obvious objection to any natural-language diagram tool is that an LLM drawing a plausible picture is just a hand-drawn diagram with extra steps — it inherits the same silent-rot problem it claims to solve. So the bar for adopting one is not "does it make pretty output." It's does it read the code, and does it refuse bad geometry.

Archify clears both, and the second one it clears loudly.

Archify-generated architecture diagram of Augment-It open in an editor, showing one shell hosting four grouped microfrontend clusters, three backend service groups behind a NATS bus, and SurrealDB Cloud as the canonical layer, with the context-v diagrams folder expanded in the file tree — The first real use: augment-it's forty deployable units rendered as twelve boxes, validated at showcase quality and browser-verified in both themes.

What's New?

archify/ — a nested git submodule pointing at tt-a1i/archify (MIT, skill v2.17). Creates polished, validated architecture, workflow, sequence, data-flow, and lifecycle diagrams as self-contained HTML with inline SVG, dual themes, optional trace motion, and PNG / JPEG / WebP / SVG / WebM export. It also accepts pasted Mermaid (flowchart, sequenceDiagram, stateDiagram) as input, which makes converting existing diagrams cheap.
The name ambiguity, resolved and recorded. Two distinct projects ship under "Archify" — tt-a1i/archify (a CLI / agent skill) and Harrison-Yuan/archify-webui (a self-hostable web UI). Our own watchlist in self-host-stack had flagged this and asked that whoever revisited it say which one was meant. It is tt-a1i/archify.
Installed on the Chroma pattern, deliberately not the skills manager. The documented path is npx skills add tt-a1i/archify -g. We ran it, watched it copy ~8MB into ~/.claude/skills/ and five other agent directories (Devin, .agents, Hermes, Trae, Windsurf) — none of them in this tree, none version-controlled — then removed all six and did it properly.

How it's wired

Identical in shape to how chroma-agent-skills has been carried since August:

.gitmodules
  [submodule "chroma-agent-skills"]  → chroma-core/agent-skills.git
  [submodule "archify"]              → tt-a1i/archify.git     ← new

Tracked as a gitlink (160000), so none of the vendor's bytes enter our history and a teammate gets it with git submodule update --init.

It needs a hand-made symlink, exactly as chroma-local and chroma-cloud do, because the skill sits one level inside a wrapper repo:

BASH

ln -sfn "$PWD/archify/archify" ~/.claude/skills/archify

sync-skills-symlinks.sh only scans direct children of agent-skills/ for a top-level SKILL.md — archify/archify/SKILL.md is one level too deep, the same reason the two Chroma skills are hand-linked. Confirmed with --dry-run that re-running the sync script leaves it alone. Updates come from git -C archify pull, not from an installer.

Runs with no npm install — zero runtime dependencies — and node bin/archify.mjs doctor reports all fifteen checks green.

Notes

The first real use was augment-it's architecture, and the authoring loop turned out to be genuinely adversarial. The first candidate returned eleven errors — not style notes, coordinate-level geometry proofs:

"prompt-bus" shares a 133px corridor with "store-canonical"
  at [1085, 300] -> [1085, 433] (minimum 8px)

Label "row + workspace reads" overlaps component "fe-resolvers"
  label rect: [720, 173, 111, 14]
  component rect: [510, 180, 220, 66]
  Suggested fix: labelAt [775, 260] or labelDy +77 (below)

Restructuring the layout took it to two. Then one of our repairs was wrong — shifting a label 44px left pushed it into a different component, and the validator caught that too. A 16px nudge on the other axis cleared it. Final: 9/9 artifact checks, 0 errors, 0 warnings, delivered with SHA-256 receipts for both spec and artifact, then browser-verified at 1440×900 and 2048×1320 in both themes.

Two capabilities matter more than the picture, and both bear on why this was worth vendoring rather than bookmarking:

--repo-root makes the architecture type inspect repository evidence rather than accept a description. This is the answer to the hand-drawn-with-extra-steps objection.
compare architecture <base> <head> --receipt diffs two specs, so a diagram can announce its own staleness instead of rotting quietly.

The durable artifact is the typed JSON spec; the HTML is a render of it. Worth keeping in mind when deciding what to commit — the spec diffs, the 800KB HTML does not.