navori
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, skillo 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 y documentar

publisher · scribe

Rápido y barato para tareas mecánicas.

sonnet Leer, escribir y auditar

scout · implementer · reviewer · auditor

Equilibrio entre calidad y costo.

opus Decidir y diseñar

orchestrator · architect

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 architect corre además con el esfuerzo más alto (xhigh): el costo queda acotado porque solo entra en tareas de nivel 2 y 3, y ese nivel lo decide classify, no el modelo.

el orchestrator, en una tarea compleja 
orchestrator › splits the ticket into 3 subtasks
  ├─ scout       → map the module        (own context · sonnet)
  ├─ scout       → how is it validated?  (own context · sonnet)
  └─ implementer → applies the change   → quality gate ✓  (sonnet)
       └─ reviewer → approves against CLAUDE.md          (sonnet)
orchestrator › synthesizes and delegates the commit → publisher  (haiku)

Antes de delegar, un nivel de plan — proporcional al riesgo

El orchestrator clasifica cada tarea con navori plan classify — una complejidad de 0 a 10 desde señales verificables, nunca prosa suelta en el chat — y elige el nivel de plan correspondiente.

Nivel Cuándo Artefacto
0 Complejidad ≤ 3, a lo sumo un archivo no trivial, sin piso de área crítica. Ninguno — cambio directo, con exención confirmada por classify.
1 El caso común: la mayoría de las tareas con plan caen aquí. Workplan simple (skill plan-simple): objetivo, criterios A<n> con comando y salida esperada, fuera de alcance, archivos, progreso, decisiones.
2 Complejidad ≥ 8, o un piso de área crítica, dinero/credenciales/PII, multi-repo, dependencia nueva, contrato compartido o migración. Workplan avanzado (skill plan-advanced) + el architect explora alternativas y recomienda; el usuario elige antes del veredicto.
3 El usuario aceptó una spec. specs/<feature>/{requirements,design,tasks}.md — el architect escribe design.md, sin workplan aparte.

Un hook PreToolUse niega el despacho del implementer si la tarea no trae un workplan que pase navori plan check, o una exención de nivel 0 confirmada por classify . Dos rechazos del reviewer (CHANGES_REQUESTED) exigen los artefactos del nivel siguiente antes de un tercer despacho — en nivel 2 o 3, el gate escala al usuario en vez de un tercer intento.

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 
? What terrain are you on?
    greenfield   — new code, move fast
  › production   — in production, guard regressions
    migration    — legacy migration, watch
                   legacy↔new compatibility

→ legacyPaths: [ "src/old-api", "legacy/" ]
  the orchestrator, implementer, and reviewer
  treat those paths with different rules.
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 
# today — after fixing a bug
mem_save "The 360 report breaks if languages[] is empty.
          Root cause: missing guard in report.py. Fix: default []."

# next week — new session, context at zero
mem_search "360 report languages"
→ recalls the decision, the root cause, and the fix.
  You don't re-explain it.
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 more repos

$ navori workspace render acme
✓ 15 repos rendered with the same standard
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.

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 22.12+, 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   # v22.12 or higher
# Claude Code installed on your machine

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

✓ configured engines rebuilt from the 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

◇ All good — nothing pending.
⇡ engram — missing from 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. 

# already productive with the team's harness

# when the repo config changes:
$ 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