Arquitectura — Los 4 pilares¶

Belico Stack se apoya sobre cuatro pilares. Los cuatro son necesarios: si uno falla, el pipeline científico se rompe. Esta página explica qué hace cada pilar, cómo interactúan, y por qué la separación es innegociable.

Pilar 1 — Orquestador (la cabeza)¶

Archivos: CLAUDE.md (Claude Code), GEMINI.md (Antigravity).

El orquestador es el único punto de contacto con el usuario. No escribe código, no escribe papers, no genera figuras. Su trabajo son cuatro verbos y ninguno más:

Verbo	Qué hace
Planifica	Decide qué fase del pipeline toca y en qué orden
Delega	Lanza un sub-agente con prompt corto (< 30 líneas)
Coordina	Lee resultados desde Engram, no del output crudo
Valida	Confirma que el gate pasó antes de avanzar

Prohibiciones: no Read en archivos > 50 líneas, no Edit/Write jamás, no generar contenido, no copiar archivos en prompts. Target de contexto: 10-15%.

Pilar 2 — Sub-agentes (el músculo)¶

Cada sub-agente tiene un prompt en .agent/prompts/ que el orquestador NO copia — el sub-agente lo lee él mismo. Esto mantiene el prompt de delegación corto y el contexto del orquestador limpio. Ver Sub-agentes.

Pilar 3 — Engram (el cerebro + bus)¶

Engram es SQLite + FTS5 + MCP tools viviendo en ~/.engram/engram.db (una sola DB, siempre). Cumple dos roles:

Rol 1 — Memoria persistente¶

Sobrevive a sesiones y compactaciones. Guarda decisiones, no datos. El contenido crudo está en git; Engram guarda el POR QUÉ.

Rol 2 — Bus inter-agente (5 pasos)¶

1. mem_save("task: agent — qué hacer")     ← orquestador
2. Agent(prompt corto < 30 líneas)          ← orquestador
3. mem_search("task: agent") + lee archivos ← sub-agente
4. mem_save("result: agent — resumen")      ← sub-agente
5. mem_search("result: agent")              ← orquestador (lee resultado, no output crudo)

Ver Convenciones de Engram.

Pilar 4 — GGA (el portero)¶

Gentleman Guardian Angel es un hook de pre-commit con IA que enforza las 11 reglas de AGENTS.md en cualquier commit que toque .py, .h, .sh. Bloquea: parámetros hardcodeados, datos fabricados, SSOT duplicada, edición de auto-generados, secretos, números sin trazabilidad. Ver Reglas.

Por qué esta arquitectura¶

Problema clásico de los agentes IA	Cómo lo resuelve Belico
El contexto se satura	Orquestador delega todo → contexto al 10-15%
Las sesiones empiezan de cero	Engram persiste decisiones y estado
Los agentes alucinan datos	GGA + Verifier + `validate_submission.py` bloquean
Parámetros duplicados	SSOT única en `params.yaml` + GGA enforza
Figuras IA rechazadas	Regla #12 — solo Mermaid/matplotlib/TikZ
Citaciones inventadas	Regla #13 — VERITAS pre-write

El flujo SDD¶

Los cambios sustanciales siguen Spec-Driven Development:

EXPLORE → PROPOSE → [SPEC ∥ DESIGN] → TASKS → COMPUTE → IMPLEMENT → VERIFY → FINALIZE → ARCHIVE

[SPEC ∥ DESIGN] corren en paralelo (ambas dependen solo de PROPOSE). Cada change vive en openspec/changes/<nombre>/. Ver El pipeline y Case studies.

Ver también¶

El pipeline · Sub-agentes · FMEA · Convenciones de Engram

Fuente canónica

Deriva de docs/shared/ARCHITECTURE.md.