🧩 Tramalia

Gobierno y evidencia verificable para desarrollar con múltiples agentes IA. Repo-first.

Define las reglas del proyecto, ordena la colaboración entre agentes, valida cada cambio y deja un registro verificable — versionado en el repo.

Español · English · 📚 Documentación

---

Git gobierna la colaboración humana; Tramalia gobierna la colaboración agéntica. Es el control de cambios + pista de auditoría para cuando varios agentes IA trabajan un proyecto real: reglas comunes, validaciones obligatorias y evidencia verificable de cada cierre.

Tabla de contenidos

• ¿Qué es?
• Definición
• Características
• Instalación rápida
• Uso
• Tramalia sola o con tus herramientas
• Cómo funciona
• Comparación con el ecosistema
• Requisitos
• Documentación
• Contribuir
• Licencia

¿Qué es?

Cuando trabajas un proyecto con varios agentes IA (Claude Code, Codex, Cursor, Antigravity…), cada uno pierde contexto entre sesiones, usa sus propias reglas y no deja evidencia de lo que hizo. Tramalia resuelve esto usando el repositorio como fuente de verdad: deja una convención versionada que cualquier agente lee, y asegura que el trabajo se haga de forma controlada, trazable y consistente.

Su foco no es configurar tus agentes (eso lo hacen Gentle-AI y similares) ni ser un motor de memoria (eso es Engram). Su foco es gobernar el repo: reglas, gates, evidencia y handoff.

Definición

Tramalia es una capa repo-first de gobierno y evidencia para desarrollo con múltiples agentes IA. Su objetivo no es configurar agentes ni reemplazar motores de memoria, sino asegurar que cualquier agente que intervenga un proyecto trabaje bajo las mismas reglas, ejecute validaciones, documente sus decisiones, deje evidencia verificable y entregue un handoff claro para la siguiente sesión o revisor.

Lo hace orquestando herramientas externas en vez de reimplementarlas.

Características

• Cierre gobernado (close) — corre los gates, escribe sus salidas en el evidence pack y genera el handoff en un solo paso; bloquea el cierre si un gate falla (salvo excepción documentada).
• Pista de auditoría (log) — historial verificable de cierres: qué tarea, qué gates pasaron, qué evidencia.
• Quality gates — build, test, lint, seguridad, base de datos y UX/UI.
• Memoria del proyecto — AGENTS.md único + docs/ai/ + intentos fallidos + handoff tipado.
• doctor — diagnostica qué herramientas necesita tu proyecto y cómo instalarlas.
• Ahorro de tokens (interop) — contexto derivado (Repomix) + navegación semántica (Serena).
• Fan-out de reglas (interop) — propaga AGENTS.md a Cursor/Copilot/… con rulesync.
• Fachada MCP + memoria N2 opcional (Engram) — expone/persiste sin reinventar.

Instalación rápida

pip install -e ".[pretty]"   # solo requiere Python 3.10+
tramalia init                # genera la convención en tu repo
tramalia doctor              # te dice qué más instalar

Uso

tramalia menu        # menú interactivo
tramalia init        # genera la convención (AGENTS.md, docs/ai, mise.toml…)
tramalia doctor      # diagnostica herramientas (y cómo instalarlas)
tramalia close       # cierra una tarea: gates → evidence → handoff (con enforcement)
tramalia log         # pista de auditoría de los cierres
tramalia gates       # corre los quality gates
tramalia sync        # propaga AGENTS.md a otros agentes (interop, rulesync)
tramalia update      # actualiza todo (mise + copier + skills)

Tramalia sola o con tus herramientas

El núcleo de gobierno funciona standalone, solo con Python: init, doctor, close, log, evidence, handoff y las reglas/docs/ai. No necesita nada más para gobernar el repo.

Las herramientas externas son interoperabilidad opcional, no requisitos: mise (corre los gates), Repomix/Serena/codebase-memory-mcp (contexto), rulesync (fan-out), Engram (memoria N2), Headroom (compresión). Si no están, Tramalia sigue gobernando y lo registra como excepción documentada.

Cómo funciona

Tres capas:

1. El CLI fino (lo que ejecutas) — una cara única que hace shell-out a las herramientas reales.
2. La convención (lo que queda en tu repo) — AGENTS.md, docs/ai/, mise.toml… El valor real.
3. Lo externo (se actualiza desde sus repos) — mise, Serena, Repomix, Semgrep, rulesync, los agentes.

Comparación con el ecosistema

No compiten de frente; se complementan. Cada uno ocupa un espacio distinto:

Proyecto	Rol
Gentle-AI	prepara el ecosistema de agentes: modelos, skills, memoria, perfiles, configuración
Engram	aporta memoria persistente entre sesiones
Headroom	comprime contexto y outputs para ahorrar tokens
Serena · Repomix · codebase-memory-mcp	inteligencia de código / contexto (navegación, snapshot, grafo estructural)
Tramalia	gobierna el trabajo dentro del repo: reglas, gates, evidencia, handoff, auditoría e intentos fallidos

En conjunto: Gentle-AI habilita con qué agentes trabajar, Engram ayuda a recordar, Headroom abarata el contexto, Serena/Repomix/codebase-memory-mcp dan inteligencia de código, y Tramalia asegura que el repo se mantenga controlado, trazable y consistente. Todas son interop opcional; ninguna toca el núcleo de Tramalia (close, log, evidence pack, handoff). Detalle en la página de ecosistema.

Requisitos

• Tramalia: solo Python 3.10+ (sin dependencias Node).
• Recomendado: mise, git, uv (bootstrap que instala el resto).
• Node 18+ solo si usas sync, el gate ux o context con Repomix. tramalia doctor lo marca como "requiere Node".

Tabla completa en el Manual de usuario.

Documentación

• Sitio (ES/EN): https://MscottB.github.io/tramalia/ — visual, con diagramas
  • Ecosistema · Flujo completo · Arquitectura · Integraciones · Herramientas
• Manual de usuario
• Documento de diseño consolidado

Contribuir

Las contribuciones son bienvenidas. Lee la guía de contribución: abre un issue para cambios grandes; para cambios chicos, un PR directo. Ejecuta los tests con pip install -e ".[dev]" && pytest.

Licencia

Apache-2.0 © 2026 Michael Jim Scott Bravo — ver LICENSE. Análisis de licencias del ecosistema (y por qué las copyleft de las tools externas no afectan a Tramalia): LICENSES.md.