[navori](https://ulisescm.github.io/navori-harness/es/deep-dive) · Español Qué aporta navori por dentro: orquestación multi-agente, un modelo por rol, memoria persistente con engram, workspaces de organización, estándares y gates — pensado para código en producción y migraciones legacy. 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 ↓](https://ulisescm.github.io/navori-harness/es/deep-dive#glossary) 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 main · orquestador El cerebro de la operación: descompone la tarea, reparte el trabajo y junta las piezas. ### Scout sonnet read-only El que mapea un área o responde una pregunta puntual buscando en el código. ### Auditor sonnet análisis / read-only El que estudia un ticket difícil o audita a fondo un módulo antes de que nadie toque código. ### Architect opus diseño / read-only El que explora alternativas y recomienda por encaje con el proyecto — siempre activo en tareas de nivel 2 y 3. ### Implementer sonnet escribe El que escribe el código: toma UNA tarea acotada y la deja lista. ### Reviewer sonnet gate El que revisa y aprueba o rechaza. No edita: juzga. ### Publisher haiku git/gh El que redacta el commit, abre el Pull Request y publica comentarios en Jira/GitHub. ### Scribe haiku documentación El único que escribe Markdown: serializa evidencia ya verificada en el artefacto que toca. ### 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 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//{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/.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: — ú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. 01 ### 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 ``` 02 ### 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 && cd $ npx navori render --apply ✓ configured engines rebuilt from the config ``` 03 ### 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 ``` 04 ### 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](https://ulisescm.github.io/navori-harness/es/quickstart) [Referencia de comandos](https://ulisescm.github.io/navori-harness/es/docs/init) 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 - [Claude Code ↗ Anthropic El runtime de agentes que navori materializa.](https://claude.com/claude-code) - [engram ↗ Gentleman-Programming Memoria persistente entre sesiones vía MCP.](https://github.com/Gentleman-Programming/engram) - [GitHub CLI ↗ GitHub Issues y PRs desde la terminal.](https://cli.github.com/) - [Atlassian CLI ↗ Atlassian Tickets de Jira como fuente de trabajo.](https://developer.atlassian.com/cloud/acli/) - [codegraph ↗ colbymchenry Grafo de código sobre MCP: localizar y medir impacto sin leer archivos.](https://github.com/colbymchenry/codegraph) ### Ideas y estándares - [AGENTS.md ↗ La spec universal de instrucciones para agentes — la base multi-engine.](https://agents.md/) - [Subagentes de Claude Code ↗ El patrón de orquestador + trabajadores en contexto aislado.](https://docs.claude.com/en/docs/claude-code/sub-agents) - Spec-Driven Development Versionar skills, reglas y convenciones como parte del repo. ### 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. - [gentle-ai ↗ Gentleman-Programming Configurador de ecosistema con SDD, memoria persistente y routing orgánico por complejidad de tarea.](https://github.com/Gentleman-Programming/gentle-ai) - [gstack ↗ garrytan Skills encadenadas por rol; auto-detección de host con un config por host; cross-model review.](https://github.com/garrytan/gstack) - [harness-sdd ↗ betta-tech Notación EARS, trazabilidad requisito↔test y el filesystem como máquina de estados de la spec.](https://github.com/betta-tech/harness-sdd) - [ejemplo-harness-subagentes ↗ betta-tech El patrón Orchestrator/Implementer/Reviewer y el estado en disco: por chat solo pasan referencias.](https://github.com/betta-tech/ejemplo-harness-subagentes) - [superpowers ↗ obra Subagent-driven development: agente fresco por tarea y specs que un junior puede seguir.](https://github.com/obra/superpowers) - [ponytail ↗ DietrichGebert La escalera de decisión anti-over-engineering: flojo en la solución, nunca en la lectura.](https://github.com/DietrichGebert/ponytail) - [codegraph ↗ colbymchenry Contexto quirúrgico vía grafo pre-indexado en vez de loops de grep/read.](https://github.com/colbymchenry/codegraph) - [graphify ↗ Graphify-Labs Knowledge graph determinista de código y docs, commiteado al repo como los managed assets.](https://github.com/Graphify-Labs/graphify) - [caveman ↗ JuliusBrussee Eficiencia de tokens como skill transversal: brevedad sin perder exactitud técnica.](https://github.com/JuliusBrussee/caveman) - [Goose ↗ Agentic AI Foundation Recipes portables en YAML para compartir workflows en equipo y CI/CD.](https://goose-docs.ai/) - [Pi ↗ Earendil Primitivas, no features: skills on-demand y extensibilidad sobre workflows horneados.](https://pi.dev/) Construido con [clack](https://github.com/bombshell-dev/clack)[citty](https://github.com/unjs/citty)[zod](https://zod.dev/)[Astro](https://astro.build/)[Tailwind CSS](https://tailwindcss.com/) ## Orchestrator 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. ## Scout Antes de un refactor o una feature grande, el orchestrator lo manda a mapear un módulo —qué archivos existen, cómo se conectan y por dónde entra el flujo— o a investigar un dato puntual —'¿cómo se valida hoy el login?'—. Lee solo extractos —no archivos enteros— y escribe sus hallazgos en un archivo aparte en vez de llenar el hilo principal: un mapa o una respuesta puntual, nunca exploración abierta ni un volcado. ## Auditor Cubre tres encargos: auditar un ticket (causa raíz, áreas afectadas, plan de partición) antes de implementar; auditar un área sin ticket de por medio (bugs, huecos de seguridad, rendimiento, violaciones de arquitectura, casos borde) antes de refactorizarla; o desafiar ("challenge") el diseño de una spec en contexto fresco. Nunca edita código de producción: entrega un reporte o veredicto en disco para que el implementer no arranque a ciegas. ## Architect Entra en toda tarea de nivel 2 (workplan avanzado) o nivel 3 (spec completa): explora al menos tres caminos — patrón existente, extensión, abstracción nueva —, descarta en una línea los que no encajan con su evidencia, y recomienda el que mejor cumple los criterios de decisión del proyecto, no el más barato por default. Nunca decide por sí solo ni descompone en tareas: presenta las opciones con la recomendada primero, el usuario elige y el orchestrator arma el workplan después. Siempre habilitado, con el modelo y el esfuerzo más altos (opus, esfuerzo xhigh) — explorar alternativas y sopesar tradeoffs es su único trabajo. ## Implementer Recibe una subtarea bien definida del orchestrator, la implementa respetando las reglas del repo (CLAUDE.md) y no la da por terminada hasta dejar el quality gate en verde: lint y tests pasando. Un modelo intermedio (sonnet) equilibra calidad de código y costo. ## Reviewer Revisa el trabajo del implementer contra las reglas del proyecto y los gates. Aprueba o rechaza con motivos concretos. Es una segunda opinión estricta antes de que el código avance — por eso usa un modelo capaz de juzgar con criterio. ## Publisher Cuando el trabajo está aprobado, escribe el mensaje de commit con el formato del repo (Conventional) y abre el PR con título y descripción. Corre chequeos contra git/gh antes de tocar la red, y publica comentarios informativos siempre con borrador previo. Tarea mecánica y acotada: un modelo ligero basta. ## Scribe Cuando el harness tiene activo `harness.scribeOwnsMarkdown`, es el único rol que toca archivos `.md`: convierte la evidencia estructurada de otro agente en su reporte Markdown, o redacta la prosa que un `markdownRequest` pide, en un commit propio y separado. No investiga ni inventa reclamos — solo lo que la evidencia ya sostiene.