archify × Agent Squad

Herramienta de diagramación como skill de agente

Documentar el substrato, generado por el modelo, verificado por el código.

archify convierte una descripción (o Mermaid pegado) en un diagrama técnico HTML autocontenido — SVG inline, toggle dark/light, export PNG/SVG 4×. Por dentro es un IR JSON tipado → validación ajv → renderer con motor de geometría y layout-checks que fallan-rápido. Su moat: Claude-in-the-loop del layout, no "Mermaid más bonito". Sus 5 tipos calzan casi 1:1 con los subsistemas reales de Agent Squad — abajo, los 3 primeros ya generados y verificados en la caja.

tipos de diagrama

schemas JSON (2020-12)

diagramas verificados

libs en el HTML de salida

4×

export PNG/SVG nativo

Cómo funciona por dentro

pipeline determinista · loop cerrado de auto-reparación

NL / Mermaid

descripción o diagrama pegado

→

Claude

re-hace el layout desde cero

→

IR JSON

tipado · schema_version 1

→

ajv

valida draft 2020-12

→

renderer

geometría + layout-checks

→

HTML + SVG

dark/light · export 4×

→

post-check

SVG único · ortogonal · legend

el moat: layout lo elige el modelo regla dura: corregir el JSON, nunca el renderer falla-rápido con mensajes accionables

Los 3 diagramas — en vivo

generados con el CLI real de archify · validate / render / check ✅

Topología del substrato architecture

dentro del diagrama: T tema · E export abrir ↗

Mapeo tipo-diagrama → Agent Squad

filtrá por tipo · verificado por grep contra el código

filtrar:

Subsistema de Agent Squad	Tipo archify	Por qué
Topología del substrato	architecture	Mapa estático de componentes + boundaries (bearer / PII / box Hetzner), sin tiempo ni estado.
Ciclo de un pedido — Nova y los 4 desenlaces	workflow	Decisión ramificada (MATCH/PLAN/FORGE/CANNOT) + swimlanes + happy path + exception lanes.
Executor durable — estados de Trace/Intent	lifecycle	State machine con wait state durable (`awaiting_human`) y salidas terminales.
FORGE — forja de capacidades	workflow	Runbook con loop de reintentos en sandbox + la exception lane más rica (ok/red/infra).
Read-path Q&A — `document.query`	sequence	Cadena temporal de llamadas con returns + dependencia externa que degrada (RRF + Cohere).
Pipeline de privacidad PII — custodia dual	dataflow	Ingesta con bifurcación de custodia + etiquetado + consumidores; fail-safe a cuarentena.
Frontera oficina ↔ substrato	dataflow	Movimiento / ownership / proyección de datos en una sola dirección, sin sync bidireccional.
Continuidad / DR — restore desde R2	workflow	Runbook operativo con guardas (anti-prod-viva) + exception lane (faltan secrets → abort).

Qué NO cubre archify

forzarlo daría un diagrama que miente — resolver con ER / tabla / prosa

Grafo relacional (ER)

intents→…→claims con PK/FK, cardinalidad y clave de partición. Ningún tipo modela esquema relacional.

Linaje por-instancia

artifact←claims←step←trace de una corrida concreta — un grafo por-run, no etapas fijas. Es lo que imprime trace-run.ts.

Plan como DAG paramétrico

Cada plan es un DAG topo-ordenado que cambia por template; workflow/sequence dibujan un flujo fijo.

Taxonomía conceptual

operation vs PlanTemplate vs Workflow vs SuperSkill vs Skill + los 4 desenlaces = mapa conceptual. No hay tipo "concept map".

Matrices de decisión / ADRs

FORGE nativo vs Eve, tiers DR con RPO/RTO, retry R1/R2/R3, HA A/B/C = tablas comparativas.

Anotaciones cuantitativas

RPO ~min, RTO ~1h, gate ≤72h, MemoryMax 4G, CPUWeight 800 — no son ciudadanos de primera clase.

Correlación cross-tool

trace_id = Langfuse = Inngest run_id atraviesa 3 herramientas; es un mapeo de identidad, no un diagrama.

Semántica de política

El porqué (catálogo cerrado, fail-closed del clearance, red-denegada bwrap) es prosa/ADR; solo las boundaries aparecen.

Decisiones de arquitectura clave

del ROADMAP · lo que declinaron es tan revelador como lo que hicieron

JSON IR, no YAML

El IR lo genera un LLM y el YAML tiene alto "looks-right, parses-wrong" por whitespace/quoting. JSON: parsing inambiguo + JSON Schema maduro.

ADR-1

NO auto-layout ni Mermaid-parser

Un experimento A/B/C sobre 5 flowcharts falló: CSS sobre dagre no cierra la brecha estética. El layout hand-placed es el producto.

ADR-2 · el experimento que falló

ajv opcional, degrada a no-op

Sin npm install warnea y sigue con solo los layout-checks. Trade-off: se pierde toda la validación de schema.

ADR-3

Claude-in-the-loop = moat

Renderers "constrained layout assistant", no motor de grafos. Si la capacidad espacial del modelo se degrada, el moat se erosiona sin fallback.

ADR-4

Adopción

instalado y verificado en la caja

✅ Adoptar como skill de repositorio

Ya está instalada en ~/.claude/skills/archify/ con ajv (sin modo degradado). El loop canónico:

Leer el schemas/<type>.schema.json + el examples/*.json
Escribir <name>.<type>.json
archify render <type> in.json out.html
archify validate y check out.html
Si falla → corregir el JSON, nunca el renderer

Caveat honesto: el "zero deps" del README no es literal — el HTML linkea el webfont JetBrains Mono (fallback a mono local). Y las cards no tienen layout-check: strings largos unidos por · se desbordan (usar comas+espacios).

Primeros diagramas por ROI

Topología del substrato (architecture) — el que más se pide y se desactualiza · hecho ✅
Ciclo Nova / 4 desenlaces (workflow) — la narrativa para stakeholders y onboarding
Pipeline PII (dataflow) — documenta una invariante de seguridad crítica
Estados del Trace (lifecycle) — el wait state durable · hecho ✅

Análisis completo + specs reusables en docs/tooling/archify-analysis.md · archify-examples/