hackathon · ai agents · meshharmes

Una fábrica de agentes
con las reglas en código.

Diseño y arnés de una fábrica personal de agentes: un solo propietario especifica, construye y evalúa agentes sobre su propio equipo. El proyecto de hackathon donde probé hasta dónde llega un sistema multiagente cuando las reglas del juego no viven en un prompt.

propósito

Qué problema resuelve

Los asistentes de IA fallan de forma silenciosa: dicen que una tarea está hecha sin haberla verificado, olvidan el estado entre sesiones y no distinguen una acción reversible de una que no lo es. Este repositorio invierte el orden: en vez de confiar en el prompt, escribe las reglas del juego en código — una puerta de entrada que decide si se puede trabajar, un backlog con criterios de aceptación explícitos y una puerta de permisos para las acciones que no se deshacen.
Tipo
Arnés de IA + paquete de diseño
Agentes
24 agentes Python deterministas
Stack
uv · pytest · RAG local · graphify
arquitectura

Las piezas del arnés

init.sh — la puerta de entrada
gate
Qué hace
Verifica entorno, estructura del arnés y que los tests pasan en verde. Si algo falla, el agente para: no se trabaja sobre un proyecto roto.
Por qué importa
La regla que no se salta: ninguna feature se cierra sin que la puerta pase en verde. El agente demuestra su trabajo, no lo declara.
comando
  • make init — comprueba que se puede trabajar
  • make check — lint + typecheck + test + arnés
harness/featureslist.json — el backlog
backlog
Qué hace
Cada feature tiene criterios de aceptación explícitos: qué, cómo y qué evidencia la cierra. Sin criterios no hay feature.
Dueño
El agente harness. Ningún humano ni asistente lo edita a mano: se modifica ejecutando el agente.
harness/progress/ — la memoria
memory
Qué hace
Guarda la tarea actual y el histórico fuera de la ventana de contexto del asistente. El estado sobrevive entre sesiones.
Por qué importa
Un agente no puede «recordar» lo que hizo ayer. La memoria vive en el repositorio, no en el modelo.
agents/permissions.py — la puerta de permisos
permissions
Qué hace
Matriz de permisos, datos y secretos. Las acciones irreversibles (publicar, borrar, desplegar) requieren aprobación explícita.
Por qué importa
Un agente no distingue por sí solo una acción reversible de una que no lo es. La distinción está en código.
agentes

24 agentes con contrato

Cada agente tiene un rol definido y sabe exactamente qué hace, qué no hace y qué evidencia debe aportar. Los cuatro subagentes del ciclo trabajan juntos:
lider
Dirige el ciclo y elige la siguiente feature del backlog.
explorer
Investiga en solo lectura, sin modificar nada.
implementer
Escribe código y tests con criterios de aceptación.
reviewer
Aprueba o rechaza el trabajo del implementer.
documentación
Mantiene CHANGELOG, README y docs al día.
seguridad
Detecta y rota secretos expuestos en el código.
uso

Cómo se usa

El ciclo es siempre el mismo: verificar, leer el backlog, implementar, revisar y cerrar. Nada se marca como terminado sin evidencia.

$ make init # ¿se puede trabajar?
$ make run # estado del backlog
$ make check # lint + tipos + tests + arnés
$ git commit_feature --dry-run # propone, tú confirmas

El protocolo completo vive en AGENTS.md, el punto de entrada que lee cualquier asistente. El proyecto incluye además un vault de conocimiento en vault/ con indexación RAG local opcional.

enlaces

Repositorio y documentación