GUÍA PARA EMPEZAR · 10 MIN

¿Qué es hornero y por qué lo usamos?

Hornero convierte lo que se pide en reuniones en especificaciones versionadas, código construido por agentes, y un rastro auditable de punta a punta — todo adentro del repo git, con una persona aprobando cada paso.

Pensalo como un asistente de producto que vive en tu repo: lee las notas que le dejás, propone qué cambió en los requerimientos, espera tu OK en la terminal, y deja todo escrito donde ya trabajás — sin Jira, sin wiki externa, sin otro sistema que sincronizar.

EL PROBLEMA — por qué existe

Los requerimientos nacen en conversaciones y mueren en documentos. Tres sprints después nadie sabe si algo se hizo, quién lo aprobó, ni por qué el código quedó así.

SIN HORNERO

  • Lo pedido queda en notas sueltas; el rastro se pierde.
  • Los specs (si existen) se desactualizan del código en semanas.
  • Un agente de código recibe instrucciones vagas y alucina contexto.
  • “¿Por qué este código es así?” — nadie recuerda.

CON HORNERO

  • Cada nota se compara contra los specs y propone deltas con evidencia textual.
  • El spec ES el tracker: su estado vive en el archivo, versionado en git.
  • Los agentes reciben un contrato verificable, no un “hacé esto”.
  • Podés navegar: señal → delta → spec → tarea → PR → merge.

CÓMO SE USA — el loop, paso a paso

Esto es un día normal con hornero. Avanzá con Siguiente o hacé click en cada etapa — la terminal de la izquierda muestra lo que verías de verdad.

EL VALOR — qué gana cada uno

PARA VOS (DEV)

  • Contexto instantáneo: entrás a cualquier repo y la wiki + los specs te orientan en minutos.
  • No re-descubrís caminos muertos: los DRs guardan qué se intentó y por qué se descartó.
  • Menos “preguntale a la persona que estuvo” — el repo recuerda.

PARA EL EQUIPO

  • Trazabilidad completa: cada línea de código se explica hasta la reunión que la originó.
  • Los prompts y reglas de agentes se sincronizan entre repos como dependencias, con lockfile.
  • Nada se aprueba solo: el humano decide siempre, y queda registrado.

PARA EL NEGOCIO

  • Reportes HTML auto-generados: qué hace el producto hoy, sin preguntarle a nadie.
  • Auditoría real de qué construyeron los agentes de IA y con qué autorización.
  • Cero infraestructura: no hay servidor que operar ni SaaS que pagar.

GLOSARIO MÍNIMO — 8 términos y ya podés seguir cualquier conversación

señal (signal)
Cualquier texto que entra: notas de reunión, un doc, una idea. Se deja en .hornero/inbox/.
delta
Un cambio de requerimiento propuesto: algo NUEVO, CAMBIADO, OBSOLETO o DUPLICADO respecto de los specs.
evidencia verbatim
Cada delta debe citar la fuente textual, carácter por carácter. Si la cita no coincide, el delta se descarta — así se frena la alucinación.
HITL (human-in-the-loop)
La revisión humana en la terminal: aprobar / rechazar / editar / saltar. Sin terminal interactiva, no se escribe nada.
spec
Un requerimiento como archivo markdown en sdd/specs/. Su frontmatter lleva el estado: proposed → approved → building → review → done.
dispatch
Enviar un spec aprobado a un agente de código para que lo construya. El resultado vuelve como PR al mismo repo.
trace / DR
El trace graba cada acción del agente; el Decision Record lo resume con citas verificadas a esos eventos. Narrativa nunca sin evidencia.
drift / diverged
Estado de los archivos del toolkit vs. su upstream. diverged = cambió en ambos lados → lo resuelve un humano, nunca una heurística.

TUS PRIMEROS 15 MINUTOS

git clone github.com/jelitox/hornero && uv pip install -e .

Python ≥ 3.11. Una sola dependencia de runtime.

cd un-repo-de-prueba/ && hornero init

Crea .hornero/ y el layout sdd/. Es idempotente: correrlo dos veces no rompe nada.

echo "los usuarios piden exportar el reporte a CSV" > .hornero/inbox/nota.md

Tu primera señal. Cualquier texto sirve.

hornero reconcile --dry-run

Mirá qué deltas propondría. Garantizado: no escribe nada (verificalo con git status).

hornero reconcile → aprobá el delta → hornero build && hornero report

Abrí sdd/reports/traceability.html y seguí la cadena completa de tu nota hasta el PR simulado.

REGLAS DE ORO — si recordás solo esto, ya estás

1

La evidencia es literal o el delta muere. Nunca “arregles” una cita que no coincide — descartala.

2

Sin humano no hay escritura. Si reconcile no te pregunta, no aplicó nada. Eso es una feature, no un bug.

3

El spec manda. Si el código y el spec se contradicen, gana el spec — y se anota la discrepancia.

4

diverged = pará y preguntá. Nunca fuerces un merge de archivos del toolkit; usá --theirs o --ours a conciencia.

5

Nada facturado por sorpresa. El backend api solo corre si alguien lo escribió explícitamente primero en la config.

github.com/jelitox/hornero · MIT · dudas → canal del equipo el hornero construye su casa capa por capa 🪶