navori AI harness
A fondo

Qué aporta navori
por dentro.

navori no es un scaffolder genérico. Es un harness opinado, pensado para código que ya vive en producción —con dependencias legacy y migraciones a medias, no repos de laboratorio—. Convierte a Claude Code en un equipo con estándares no negociables, memoria que persiste y un mismo estándar en todos tus repos. Aquí está, capa por capa, por qué es la base sobre la que vale la pena construir.

¿Nuevo en términos como harness, skill o SDD? Empieza por el diccionario rápido ↓

Antes de empezar

Diccionario rápido

Sin jerga. Toca cualquier término para ver qué significa en una frase.

Harness

El 'arnés' de trabajo: el conjunto de reglas, agentes y automatizaciones que rodean al asistente de IA para que trabaje como tu equipo espera, no a su antojo.

Agente / subagente

Un asistente con un rol específico (explorar, escribir, revisar). El agente principal reparte el trabajo entre subagentes especializados.

Skill

Una guía reutilizable para una tarea concreta ('cómo crear un endpoint', 'cómo verificar antes de dar algo por hecho'). El agente la carga cuando la necesita.

Hook

Una automatización que se dispara en un momento fijo —por ejemplo, correr los tests antes de cada commit— sin que nadie tenga que acordarse.

Quality gate

La barrera de calidad: los comandos (lint, tests) que deben pasar para dar un cambio por terminado.

SDD

Spec-Driven Development: en vez de que las reglas vivan en la cabeza de alguien, se escriben y se versionan junto al código, y se actualizan con un comando.

Preset

Un paquete de configuración por tipo de stack (Vite + React, NestJS, monorepo…). navori detecta tu stack y elige el preset adecuado.

Engram

La memoria persistente: guarda decisiones y aprendizajes para que el asistente los recuerde en la siguiente sesión.

Bloque managed

Un fragmento de CLAUDE.md marcado como 'gestionado por navori': se actualiza solo, sin pisar lo que tú escribiste alrededor.

legacyPaths

Las carpetas de código viejo que marcas para que los agentes las traten con cuidado y no les impongan reglas nuevas.

01 · Orquestación

Un equipo de agentes, no un solo hilo.

El agente principal encarna al orchestrator —el centro de gravedad—. En lugar de hacer todo en un mismo hilo, descompone la tarea y la reparte entre subagentes que trabajan en paralelo y devuelven solo su conclusión. Cada uno tiene un rol estricto y el modelo justo para él.

Toca una tarjeta para ver a qué se dedica cada rol ↓

Orchestrator

opus

Lo encarna el agente principal, no un subagente aparte — es el centro de gravedad de la sesión. Lee el ticket, decide en cuántas subtareas se parte, lanza a los trabajadores en paralelo y al final integra sus resultados en una sola solución coherente. Usa el modelo más capaz (opus) porque su trabajo es razonar y decidir, no leer archivos.

Cada rol, su modelo — eficiencia en tiempo y tokens

haiku Publicar

publisher

Rápido y barato para tareas mecánicas.

sonnet Leer, escribir y auditar

scout · implementer · reviewer · auditor

Equilibrio entre calidad y costo.

opus Decidir

orchestrator

El músculo donde el criterio importa.

Todo configurable en config.models. No pagas un modelo caro por leer archivos: el músculo va donde se decide, la velocidad donde se explora.

el orchestrator, en una tarea compleja 
orchestrator › descompone el ticket en 3 subtareas
  ├─ scout       → mapa del módulo        (contexto propio · sonnet)
  ├─ scout       → ¿cómo se valida hoy?   (contexto propio · sonnet)
  └─ implementer → aplica el cambio      → quality gate ✓  (sonnet)
       └─ reviewer → aprueba contra CLAUDE.md            (sonnet)
orchestrator › sintetiza y delega el commit → publisher   (haiku)
02 · El terreno real

Hecho para producción, no para demos.

Casi todas las herramientas asumen un repo limpio y greenfield. navori parte de la realidad de un equipo: código que ya corre en producción, dependencias legacy y migraciones a medias. Desde el init eliges el terreno, y esa decisión moldea cómo trabajan los agentes.

Modo del proyecto, desde el init

Eliges el terreno: greenfield (muévete rápido), en producción (cuida regresiones) o migración legacy (cuida la compatibilidad legacy↔nuevo). La decisión moldea cómo trabajan los agentes.

legacyPaths que los agentes respetan

Marcas las carpetas legacy y el orchestrator, el implementer y el reviewer lo saben: ahí aplican reglas distintas y no imponen convenciones nuevas sobre código que no les toca.

auditor antes de migrar

Ante una migración estructural (legacy → nuevo backend, monolito → microservicios), el agente diseca causa raíz, áreas afectadas y compatibilidad antes de que nadie escriba código.

Skills conscientes de la migración

verify-before-done, debug-failure y review-diff detectan estados inconsistentes cuando conviven código legacy y nuevo — el error más caro de una migración a medias.

navori init — modo del proyecto 
? ¿En qué terreno estás?
    greenfield   — código nuevo, muévete rápido
  › production   — en producción, cuida regresiones
    migration    — migración legacy, cuida
                   la compatibilidad legacy↔nuevo

→ legacyPaths: [ "src/old-api", "legacy/" ]
  el orchestrator, el implementer y el reviewer
  tratan esas rutas con otras reglas.
03 · Eficiencia

Menos tokens por diseño.

La orquestación no es solo velocidad: es economía de contexto. El hilo principal se mantiene limpio porque el trabajo pesado ocurre en ventanas aisladas —cada una con su modelo— que solo devuelven lo esencial.

Contexto aislado por subagente

Cada subagente corre en su propia ventana y devuelve solo la conclusión. El hilo del orchestrator nunca se llena con el volcado de los archivos que leyó.

Un modelo por rol

Cada agente usa el modelo justo: uno ligero para leer y explorar, el potente solo para decidir y revisar. No pagas un modelo caro por leer archivos.

Lectura por extractos

Scout lee los fragmentos relevantes, no archivos completos. Localiza, no fotocopia.

Skills bajo demanda

El catálogo de skills se referencia por índice; el contenido pesado se carga solo cuando la tarea lo pide.

Bloques managed compactos

El orden canónico ordena y deduplica las reglas en CLAUDE.md. Sin copias pegadas ni ruido que se acumula sesión tras sesión.

El contraste

sin harness

Un solo hilo lee archivos enteros, acumula todo en el contexto y lo arrastra turno tras turno hasta saturarse.

con navori

Los subagentes exploran en paralelo y devuelven conclusiones. El orchestrator razona sobre resúmenes, no sobre volcados. Engram guarda lo que hay que recordar fuera del contexto.

04 · Memoria

Engram: memoria que persiste.

El contexto de un LLM es efímero: se cierra la sesión y se olvida. Engram es la memoria persistente que navori habilita por default. Las decisiones, los bugs con causa raíz y las convenciones se guardan y se recuperan entre sesiones —y sobreviven a las compactaciones—.

  • Sobrevive a cierres de sesión y a las compactaciones de contexto.
  • mem_save guarda decisiones, bugs con causa raíz y convenciones; mem_search los recupera al arrancar.
  • El protocolo se inyecta en el orchestrator: guarda de forma proactiva, sin que se lo pidas.
  • Va siempre con navori (always-on). No re-explicas el contexto de la semana pasada.
sesión de hoy · sesión de la próxima semana 
# hoy — tras arreglar un bug
mem_save "El reporte 360 falla si languages[] viene vacío.
          Causa raíz: falta el guard en report.py. Fix: default []."

# la próxima semana — sesión nueva, contexto en cero
mem_search "reporte 360 languages"
→ recupera la decisión, la causa raíz y el fix.
  No lo re-explicas.
05 · Escala de organización

Un workspace, todos tus repos.

Cuando manejas 15 repos, no quieres 15 estándares. El workspace es una capa cross-repo: defines el quality gate, la branch base y las convenciones de tu organización una vez, y cada repo las hereda. El equipo trabaja igual, sin importar en qué proyecto esté.

  • Config cross-repo en ~/.navori/workspaces/<org>.json, fuera de cada repo.
  • Defaults de organización: quality gate, branch base y convenciones compartidas.
  • Tickets como archivos versionables dentro del workspace.
  • workspace render aplica el estándar a todos los repos registrados de una pasada.
el estándar de la org, a todos los repos 
$ navori workspace init acme
$ navori workspace set-default acme \
    --branch-base main --commits conventional-es
$ navori workspace add-repo acme ./web-app
$ navori workspace add-repo acme ./api-core
  … 13 repos más

$ navori workspace render acme
✓ 15 repos renderizados con el mismo estándar
06 · Guardarraíles

Estándares y gates que protegen el trabajo.

Un agente con permiso de escritura necesita barreras. navori trae estándares no negociables —simplicidad, tipado estricto— y gates de seguridad y calidad como parte del harness, no como un extra opcional. Y los mantiene versionados junto al resto de la config.

Simplicidad > cleverness

El estándar antes de escribir una línea: ¿es lo más simple? ¿legible en 6 meses? ¿mantiene el patrón existente? Nada de soluciones ingeniosas que nadie entiende después.

any prohibido

unknown + narrowing, tipado explícito. La única excepción es un // any justificado: <razón> — último recurso, no atajo que se vuelve deuda.

Semgrep · gate de seguridad

Análisis estático de patrones peligrosos, atado al reviewer. Los problemas de seguridad se atrapan en la revisión, no en producción.

jscpd · gate de duplicación

Detecta código copy-paste antes de que se multiplique. Menos superficie que mantener, menos lugares donde un bug se esconde.

Hooks defensivos

guard-destructive intercepta comandos peligrosos; quality-gate corre lint + tests antes de cada commit.

Permisos deny / ask

Las operaciones sensibles se bloquean o piden confirmación explícita. Defensa en profundidad, no una sola barrera.

07 · La diferencia

Por qué navori, y no un scaffolder genérico.

Hay muchas formas de darle instrucciones a un asistente de IA. Pocas sobreviven al segundo mes, a un equipo de verdad o a un repo con historia. Esto es lo que navori hace y las alternativas no —o no tan pulido—.

No es copy-paste de .claude/

Una fuente de verdad versionada y render idempotente. Copiar carpetas entre repos no escala ni sobrevive a una actualización; navori sí.

No es una plantilla estática

Detecta tu stack real —Mantine, Redux, NestJS, monorepo pnpm— y arma el preset. Los estándares no se erosionan porque están versionados y se actualizan con un comando.

Producción y legacy de primera clase

La mayoría de las herramientas asumen un repo limpio. navori parte de la realidad: código que ya corre, dependencias legacy y migraciones a medias.

Batería incluida y cableada

Memoria persistente, gates de seguridad y duplicación, orquestación multi-agente y estándar cross-repo. Todo pulido y conectado, no un README con pasos manuales.

08 · Para tu equipo

Súmate a un repo que ya usa navori.

Tú subes la config una vez a cada repo; el equipo solo la sigue. Nadie arma un harness a mano ni copia .claude/ entre proyectos. Estos son los comandos que corre cada quien al entrar.

Ten los requisitos

Node.js 20+, Claude Code y —si el repo usa memoria persistente— el binario de engram. En el paso 3, doctor te dice exactamente qué falta. 

node --version   # v20 o superior
# Claude Code instalado en tu equipo

Clona y reconstruye el harness

El repo ya trae navori.config.json (la fuente de verdad). Un solo comando reconstruye todos los engines configurados de forma idéntica para el equipo. Idempotente: correrlo dos veces no cambia nada. 

$ git clone <repo> && cd <repo>
$ npx navori render --apply

✓ engines configurados reconstruidos desde la config

Verifica con doctor

doctor confirma que todo está al día y, si te falta una herramienta (por ejemplo engram), te da el comando exacto para instalarla. Sin adivinar. 

$ npx navori doctor

◇ Todo al día — sin acciones pendientes.
⇡ engram — falta en PATH:
   brew install gentleman-programming/tap/engram \
     && claude plugin install engram

Trabaja normal

Abre Claude Code y listo: mismos agentes, mismas skills, mismo quality gate y la misma memoria de equipo. Cuando alguien actualice la config, corre sync para ponerte al día sin tocar tu código. 

# ya productivo con el harness del equipo

# cuando cambie la config del repo:
$ npx navori@latest sync

En resumen para el equipo: clone → npx navori render --apply → npx navori doctor y a trabajar con el mismo harness que tú.

De la teoría al repo, en un minuto.

Todo esto se materializa con un solo comando de adopción. El resto es renderizar cuando cambies algo.

Ver el Quickstart Referencia de comandos
Créditos

Hombros de gigantes.

navori no nació en el vacío: integra herramientas excelentes y sintetiza ideas de proyectos y estándares abiertos. El mérito de cada pieza es de quien la construyó.

Se apoya en

Ideas y estándares

Proyectos que lo inspiraron

De estos proyectos navori tomó ideas; a codegraph además lo integra como plugin. Las notas por proyecto viven en docs/inspiration.md.

Construido con clack citty zod Astro Tailwind CSS