Cada repo, su propio harness
Copias y pegas .claude/ de un proyecto a otro. Mantenerlo sincronizado es manual y propenso a errores.
open source · 6 engines
El harness multi-agente para cualquier repo.
Agentes, skills, hooks, permisos y memoria — versionados en un solo config y reconstruibles con un comando. Se renderiza a Claude Code, Codex, Cursor, Copilot y AGENTS.md sin pisar una línea de lo tuyo.
$
npx navori init
MIT
Node ≥ 22.12
0 runtime deps
Claude Code
$ navori init --recommended
✓ stack: Next.js · pnpm
✓ engines: claude · codex
✓ plugins: engram · gh
→ renderizando recursos managed
✓ CLAUDE.md · AGENTS.md
✓ .claude/ agents · skills · hooks
✓ .claude/settings.json permisos
✓ Listo — 34 creados · 0 sobrescritos
29 comandos 13 presets 5 plugins 6 engines 8 agentes 66 skills
MIT Node ≥ 22.12 0 deps runtime
v0.12.2
Anatomía de una sesión
Sigue un prompt por dentro del harness
Sin harness, tu frase llega sola a un modelo que decide por su cuenta. Esto es todo lo que navori pone en el camino — ocho paradas, de la frase al commit, y de vuelta a la memoria.
tu prompt
arregla el bug del login que reportó soporte
Escribes una frase. Todavía no piensa nadie.
Antes de que el modelo lea tu prompt, un hook de arranque ya corrió. Es la diferencia entre un asistente que empieza en blanco cada mañana y uno que abre la sesión sabiendo dónde está parado.
El recorrido avanza solo. Toca una parada para saltar a ella.
El problema
Cada repo reinventa lo mismo
Si trabajas con varios proyectos y agentes de IA, sabes a qué nos referimos.
Cada engine, su propia config
Claude tiene .claude/, Cursor tiene .cursor/, Copilot tiene .github/copilot-instructions.md. La misma intención, tres archivos.
El SDD se erosiona
Las skills, los hooks y las convenciones de Spec-Driven Development se pierden con el tiempo si no hay una forma de versionarlas y actualizarlas.
Alcances
El harness ya no vive solo en el repo
Dos alcances aditivos, cada uno opt-in. El workspace se suma al repo sin degradarlo.
por repo
El repo
navori.config.json checked-in es la fuente de verdad. render reconstruye CLAUDE.md, .claude/ y progress/ desde ahí, idempotente y sin tocar lo que escribiste tú.
navori.config.json
navori init por organización
El workspace
Defaults de toda la org —quality gate, branch base, convenciones— y el Dominio: los hechos durables que cruzan repos y no caben en el CLAUDE.md de ninguno. Un modelo de datos, un contrato entre servicios, un gotcha compartido.
~/.navori/workspaces/<org>/
navori workspace · navori dominio Huella cero sin opt-in: sin el init correspondiente, navori no escribió un solo byte fuera de tu repo.
Cómo funciona
5 capas en cascada, una sola fuente de verdad
Cada capa se compone sobre la anterior. Tú decides cuánto control quieres a nivel proyecto.
- navori
Core
El baseline gestionado por navori: agentes, skills, hooks y los bloques de doctrina. Siempre presente.
- preset
Preset
Configuración por stack — Next.js, NestJS, Astro, Expo, Medusa, monorepos y más. ¿Falta el tuyo? Creas uno local con `navori preset init`.
- org
Workspace
Reglas de toda tu organización compartidas entre repos, más el Dominio del workspace.
- you
Project
Lo específico del repo en navori.config.json: quality gate, áreas críticas, rutas legacy y los plugins que habilitas.
- engine
Adapters
Renderizado por engine para Claude Code, Codex, Cursor, Copilot y AGENTS.md, todos sobre el mismo pipeline.
navori.config.json
source of truth
{
"$schema": "https://ulisescm.github.io/navori-harness/schema/navori.config.v1.json",
"name": "your-app",
"engines": ["claude", "codex"],
"preset": "nextjs",
"branchBase": "main",
"commits": "conventional-es",
"qualityGate": {
"full": "pnpm lint && pnpm test"
},
"plugins": {
"engram": { "enabled": true },
"codegraph": { "enabled": true },
"tgrep": { "enabled": true },
"gh": { "enabled": true }
},
"project": {
"criticalAreas": ["auth", "billing"],
"legacyPaths": ["src/legacy"]
},
"audit": { "mode": "always" }
} En vivo
Mira qué aporta cada capa
Haz click en una capa para resaltar qué parte del harness genera. Los adapters lo materializan en el formato nativo de cada engine.
Selecciona una capa para ver su aporte.
Engine adapters → .claude/ + CLAUDE.md
output
CLAUDE.md
- idioma-rol · formato-respuesta · tipado-fuerte · cierre-sesion core
- engram-protocol project
.claude/agents/
- orchestrator · implementer · reviewer · scout · … core
.claude/skills/
- verify-before-done · debug-failure core
- nextjs-app-router · nextjs-data-fetching preset
.claude/settings.json
- permisos + hooks base core
- hooks de plugins (engram, gh) project
.claude/hooks/quality-gate-pre-commit.sh
- qualityGate.fast heredado workspace
progress/
- current.md · history.md core
Caja de herramientas
navori no ejecuta las herramientas, le enseña a usarlas
Cada plugin es un bundle: trae su skill, su bloque de protocolo, sus permisos y su check de doctor. Habilitas el que quieres y el harness sabe cuándo recurrir a él — y cuándo no.
acli externo Jira
Lectura y escritura de tickets por acli, con la cuenta correcta. El intake de un ticket empieza por el ticket, no por una descripción pegada a mano.
codegraph búsqueda Buscar por estructura
Un grafo AST local del repo. Dónde vive un símbolo, quién lo llama y qué se rompe si lo cambias — una consulta en vez de una ronda de greps y lecturas.
engram contexto Memoria persistente
Decisiones, causas raíz y convenciones que sobreviven al cierre de sesión y a las compactaciones de contexto. No vuelves a explicar el lunes lo que decidiste el viernes.
gh externo GitHub
Issues, PRs y checks por gh. El agente lee el ticket, abre el PR con el formato del repo y sabe leer un CI en rojo.
tgrep búsqueda Buscar por contenido
Índice de trigramas sobre el repo. Qué archivos contienen esta cadena, con el contrato de exit code intacto y sin pelear con el motor que tenga la máquina.
navori genera el harness; no corre grep, ni los tests, ni el linter por el agente. Dicta qué herramienta usar y con qué doctrina — el resto lo ejecuta quien corresponde.
Observabilidad
El harness que se audita a sí mismo
Escribir doctrina es fácil; saber si alguien la siguió, no. navori audit responde las dos preguntas que ninguna otra cosa responde: a dónde se fueron los tokens y qué instrucciones nadie obedeció.
$ navori audit --session latest◇ navori-harness · 2026-09-12 ─────────╮│ 1 sesiones · 19 agentes ││ facturable 2.3M tok ││ arranque 346k tok ││ hallazgos 1 alto · 3 medio │╰──────────────────────────────────────╯→ report.md · report.json
A dónde se fueron los tokens
Facturable, arranque y por agente. El costo del harness deja de ser una intuición y pasa a ser un número que puedes atacar.
Qué instrucciones nadie siguió
Hallazgos con severidad sobre el ruteo real: la skill que se ignoró, la búsqueda que fue por el camino caro, la delegación que no ocurrió.
Tres fuentes que no se sustituyen
El log que escriben los hooks (qué hizo el harness), el transcript (el único lugar donde viven los tokens) y los eventos OTel del host (qué permiso se aprobó y qué skill estaba activa).
Opt-in y por sesión
Sin un --start previo no hay log que auditar y navori no observa nada. El reporte queda en markdown y JSON dentro de ~/.navori/audits/, y --snapshot/--compare permiten contrastar rangos: describen, no declaran mejoras.
Comandos
El ciclo completo, comando a comando.
Todos los subcomandos que el CLI registra, agrupados por el momento en que los necesitas. Cada uno tiene su página de referencia.
Empezar
- navori init Inicializa un repo con navori. Detecta el stack, hace unas preguntas y deja todo listo en un minuto.
- navori adopt Toma un archivo del harness que escribiste a mano y lo pone bajo gestión de navori, sin cambiar lo que dice.
- navori add Registra un plugin en navori.config.json, o sugiere qué agregar según tu stack.
- navori remove Desactiva un plugin y limpia lo que había dejado: bloques managed, sub-bloques inyectados y scripts.
- navori preset Scaffolda un preset local en .navori/presets/ para cuando tu stack no tiene un preset oficial.
- navori configure Modifica secciones de navori.config.json después del init. Cada sección es un subcomando.
Renderizar y actualizar
- navori render Reconstruye todos los engines configurados desde navori.config.json. Idempotente. Preview por default.
- navori sync Trae cambios del bundle a todos los engines configurados sin pisar tus ediciones.
- navori update Actualiza la CLI de navori a la última versión de npm y luego corre 'navori refresh' con el binario nuevo.
- navori refresh El 'ponme al día' de un solo tiro: vuelve a detectar el repo, ofrece los cambios de config y corre sync.
- navori migrations El respaldo del harness previo cuando 'init' adopta navori en modo replace. Reversible.
- navori backup La red de seguridad: cada sync o render que modifica archivos deja antes un snapshot en ~/.navori/backups/.
Operar
- navori doctor Audit del proyecto: config, plugins, drift, invariants y próximos pasos sugeridos.
- navori status Snapshot rápido: config, plugins habilitados, drift y próximos pasos. El '¿cómo quedó esto?' en un comando.
- navori scan Vuelve a detectar los workspaces de un monorepo y agrega al config los que aparecieron desde el init.
- navori registry Registro global de todos los repos con navori de esta máquina. Es lo que hace posible 'render --all'.
- navori bench Mide render sobre N corridas y reporta p50/p95. Para detectar regresiones locales antes de commitear.
- navori codex Aprueba los hooks de Codex del proyecto en ~/.codex/config.toml. Codex no carga nada del repo (ni siquiera AGENTS.md) hasta que el proyecto es de confianza.
- navori receipt Firma o verifica los bytes revisados antes de publicar un cambio.
- navori gate Corre el quality gate del proyecto con la salida completa en un log y solo un veredicto compacto en stdout.
- navori plan Clasifica la complejidad de una tarea y valida su workplan (spec 0032).
- navori spec Clasifica el tasks.md de una spec y valida su estructura de entregas (spec 0044).
- navori handoff Valida el handoff del implementer antes de que el orquestador despache al siguiente rol.
- navori master Plan maestro de proyecto: gestiona etapas, fases, partes y cierre (spec 0034).
Escalar
- navori workspace Config y tickets compartidos entre varios repos: defaults que aplican a todos y un render de la flota completa.
- navori dominio La base de conocimiento del workspace: los hechos canónicos que cruzan repos y no caben en el CLAUDE.md de ninguno.
- navori ticket Tickets como archivos dentro de un workspace, para que el trabajo que cruza repos tenga un lugar común.
- navori tools Comando de máquina del hook SessionStart: avisa una vez que hay una versión estable más nueva de una herramienta con latestRelease en su manifest (hoy, engram).
Multi-engine
Una config, seis engines.
El mismo harness materializado en el formato nativo de cada uno, sobre un solo pipeline de render. Agregar el sexto cuesta una tabla declarativa, no reescribir nada.
disponible
Claude Code
.claude/
agentes · skills · hooks · settings.json con permisos
Codex
.codex/ + .agents/skills/
agentes propios · skills · hooks · servidores MCP
AGENTS.md
AGENTS.md
spec universal · la leen Cursor, Codex, Gemini y Copilot
disponible
Cursor
.cursor/rules/
reglas .mdc · contexto de proyecto
disponible
Copilot
.github/copilot-instructions.md
instrucciones de workspace
Pi
.pi/
extensión, agentes y hooks · requiere Pi >= 1.1.0
Novedades
Qué cambió, versión por versión
Lo que ganas al actualizar, en lenguaje llano.
- v0.12
Pi de primera clase, un gate más barato y retiros con migración
- Pi es un engine de primera clase y ya se ofrece en el wizard de init y en configure engines. Llega con paridad de guardas y hooks con Claude Code, y las acciones sensibles piden una aprobación escrita (yes, run it). Requiere Pi >= 1.1.0.
- Nuevo navori gate <fast|full>: salida compacta con el veredicto en la primera línea y el log completo en .navori/state/gate/. Además, un gate scoped (qualityGate.scoped) que corre solo lo que tocó el diff, y un hook nativo del gate (qualityGate.nativeHooks) que evita correrlo dos veces.
- navori update consulta npm, instala la última versión de la CLI tras tu confirmación y luego corre navori refresh, que es el update de antes (re-sincroniza el harness). Sin alias: si tus scripts usaban navori update para refrescar el harness, cámbialos a navori refresh.
- Retiros incompatibles: el comando navori global y el colector launchd ya no existen, doctor --json deja de emitir globalScope, y los plugins jscpd y semgrep salen del producto. Migra con navori render --apply, que poda sus assets si son de navori, y navori doctor, que reporta lo que quede.
- Node >= 22.12 es el mínimo. progress/current.md tiene tope (el hook bloquea commits de agente que lo hagan crecer y doctor avisa) y harnessVersion funciona como piso anti-retroceso.
Parches destacados
- v0.12.1 — Corrige clasificación, evidencia y escalamiento de planes; incorpora mejoras del master plan y controles de aprobación y perfiles de Codex. La integración de Codex continúa en validación.
- v0.12.2 — Un ciclo de desarrollo más rápido: el gate reutiliza resultados por identidad de contenido y corre el gate del repo destino, con suite de pruebas más veloz y hooks más ligeros. El scribe puede correr en paralelo (opt-in), el despacho de Codex se aísla por sesión y doctor avisa cuando el CLAUDE.md global excede su tope de contexto o usa rutas de workspace obsoletas. Además corrige el tope de progress, el cierre de specs sobre el límite, los diagnósticos del plan-gate de Pi, el shebang del CLI y la base real del PR en el reviewer.
- v0.11
Estado del harness por checkout y un master plan guiado
- El estado efímero del harness vive por checkout y sin atarse a un engine, en .navori/state/handoffs/. plan gate, plan check y receipt check buscan ahí los workplans y recibos, con el .claude/progress/ anterior como lectura de respaldo. Es una migración que conviene notar.
- Codex avanza hacia la paridad operativa, aunque todavía parcial: permisos por defecto, salida de hooks validada, permisos de revisión cruzada y un plan-gate que aconseja en Codex.
- Nueva skill master-plan: guía un plan maestro por etapas para trabajo grande, con una spec propia.
- Nuevas skills de librerías: amqplib para RabbitMQ, los patrones de Mantine en cualquier repo con @mantine/core, y fastapi y pytest para repos Python, con detección de dependencias de desarrollo de Python.
- Los gates de pre-commit, semgrep y jscpd ya no corren el gate del repo ancla sobre commits que caen en otro repositorio, e init infiere el workspace cuando uno ya registra el repo. Además, jscpd bloquea solo clones nuevos y hay arreglos en check-links, recibos, activación de tailwind-v4, variables extra de plugins y la convivencia en init.
Parches destacados
- v0.11.1 — Claude first: el harness deja de emitir lo que Claude Code ya trae de forma nativa, navori audit mide rangos y compara instantáneas, y llegan un guard de ruteo de búsqueda, confirmación cuando un gate no puede dar veredicto, soporte para Pi y un aviso diario de versión nueva.
- v0.11.2 — Paridad de Codex (spec 0041), verificada en vivo en Codex 0.160.0 con una tabla de garantías: role-guard y guard de spawn, plan-gate con archivo de despacho para multi-agente V2, confirmaciones por deny en publicación y general-purpose, master-plan y context-intake, guard de tgrep y consejo ante fallos repetidos de Bash. Los modelos de Codex se resuelven solos por familia desde el catálogo local (sol, luna, astra) y doctor revisa la confianza de Codex por worktree y avisa de un navori global desactualizado. Arreglos de render: navori:if en los agentes de Codex y poda de huérfanos.
- v0.11.3 — Entregas funcionales para specs: spec classify y spec check, sdd.deliveries con entregas, milestones y tareas, un gate completo por PR y un master-plan que reparte sus partes con las mismas reglas. sync reemplaza archivo por archivo (también los que no tienen marcadores), con --accept-new-files y diff para conservar o aceptar; monorepo.workspaceHarness suma el modo root. navori tools avisa de versiones nuevas de herramientas externas y doctor advierte de versiones con problema conocido (engram < 3.0.0). navori audit une resultados de revisión y recibo, mide disponibilidad, compara cohortes y calcula eficiencia por tarea. Hooks más seguros: el guard bloquea descartes de árbol completo con trabajo sin commitear, el publisher no reescribe historia, plan-gate pide confirmación y los bloqueos dicen qué hacer. Codex recibe un AGENTS.md más delgado y un guard de escrituras de engram, y ya no degrada el modelo renderizado.
- v0.10
Planificación por niveles y un harness más difícil de romper
- Los cambios se planifican por niveles: un clasificador decide cuánta planeación necesita cada tarea antes de despachar trabajo.
- El agente scribe puede quedarse con todo el Markdown del repo, para que los demás agentes no lo toquen.
- Se elimina toda atribución de IA en commits, PRs y código, y la regla aplica también a los comentarios.
- doctor verifica que el binario coincida con la versión fijada en el manifest y que el cableado MCP sea coherente.
- Nuevas skills: Supabase, escribir skills propias, back-offices, y utilidades para rebase y limpieza de worktrees.
Parches destacados
- v0.10.1 — Nueve skills nuevas de librerías, un guard que también bloquea rutas absolutas a archivos managed, y avisos de binarios de plugins faltantes al iniciar.
Quickstart
De cero a productivo en tres pasos
Instala
Sin instalación global. Usa npx.
npx navori init
Inicializa
Responde unas preguntas y obtén navori.config.json + el harness renderizado.
? Project › my-app ? Engine › claude ? Preset › nextjs ✓ Done — 5 created
Renderiza cuando cambies algo
Edita el config, corre 'render --apply' y commitea. Todo idempotente.
$ vim navori.config.json $ npx navori render --apply $ git add . && git commit
Preguntas frecuentes
Lo que probablemente te estás preguntando
¿Y si ya tengo un .claude/ que armé a mano?
navori coexiste. init detecta tu harness existente y solo agrega bloques managed con marcadores; tu contenido personalizado queda intacto. Si quieres que navori se haga cargo de un archivo tuyo, 'navori adopt' lo envuelve sin cambiar una palabra de lo que dice. Y si tu setup ya trae su propia orquestación o SDD, blocks.exclude deja que navori opte por no renderear esos bloques para no competir con los tuyos.
¿Qué engines soporta hoy?
Seis, todos entregados: Claude Code (.claude/), Codex nativo (agentes, skills, hooks y MCP), AGENTS.md universal, Cursor (.cursor/rules/), Copilot y Pi (.pi/, con extensión, agentes y hooks; requiere Pi >= 1.1.0). Corren sobre el mismo pipeline de render, así que un arreglo llega a todos a la vez en lugar de divergir en silencio.
¿Necesito Claude Code para usar navori?
No. navori es un scaffolder: genera el harness y se sale del camino. La herramienta corre en cualquier Node 22.12+ y renderiza a seis engines distintos.
¿Qué tan invasivo es? ¿Puedo revertirlo?
render hace preview por default: sin --apply no toca disco. Cuando escribe, deja antes un snapshot restaurable con 'navori backup', y la escritura es atómica. Fuera del repo no existe nada que no hayas pedido por su nombre: sin 'global init' no hay capa global, sin '--start' no hay auditoría.
¿Cómo actualizo mi proyecto cuando sale una versión nueva?
npx navori@latest sync. Actualiza solo los bloques managed sin tocar tu código; con --interactive resuelves bloque por bloque lo que hayas editado a mano. 'navori refresh' te dice antes qué cambiaría.
¿No sale caro correr un harness multi-agente?
Menos de lo que parece, y ya no hace falta creerlo: 'navori audit' te dice a dónde se fueron los tokens de una sesión real. Cada agente corre con su modelo y su effort — el músculo solo donde hay juicio, lo mecánico en un modelo ligero — y cada subagente devuelve su conclusión en vez del volcado de lo que leyó.