navori 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# navori
+
+Multi-agent harness + SDD scaffolder for Claude Code (and other AI engines).
+
+`navori` lleva tu setup de Claude Code (agentes, skills, hooks, CLAUDE.md, AGENTS.md) a múltiples repos con un solo comando — sin perder customización local, sin sobrescribir lo que ya tenías.
+
+## Instalación
+
+```bash
+npm i -g navori
+# o sin instalar
+npx navori init
+```
+
+## Quick start
+
+```bash
+# Modo opinado: cero preguntas, todo configurado
+cd ~/tu-repo
+navori init --recommended
+
+# O wizard interactivo con detección de stack
+navori init
+```
+
+El `init` detecta automáticamente del repo:
+- **Nombre** del proyecto (de `package.json`, `pyproject.toml`, `Cargo.toml`, git remote o basename)
+- **Stack**: framework (Next.js, Vite, NestJS, Expo, etc.), UI, forms, state, test
+- **Preset sugerido** basado en el stack (ej. `vite-react-ts-mantine`, `nextjs-apollo`, `bun-keystone`)
+- **Quality gate** compuesto de los scripts del `package.json`
+- **Branch base** del git (`origin/HEAD`, fallback main/master/develop)
+- **Infraestructura Claude existente** (`.claude/`, `CLAUDE.md`, `AGENTS.md`, agents, skills) — ofrece coexistir o reemplazar con backup
+
+Y genera:
+- `navori.config.json` — fuente de verdad del repo
+- `CLAUDE.md` con managed blocks que el CLI mantiene sincronizados
+
+## Comandos
+
+| Comando | Qué hace |
+|---|---|
+| `init` | Bootstrap del repo con detección automática + wizard |
+| `add <plugin>` | Activa un plugin + opcionalmente instala la tool externa |
+| `configure <section>` | Ajusta una sección del config sin re-correr el wizard |
+| `update` | Re-detecta el repo, refresca config y corre sync en un paso |
+| `render` | Genera CLAUDE.md con los managed blocks |
+| `sync` | Refresca managed blocks con conflict resolution + backups |
+| `doctor` | Inspecciona config + reporta procedencia de cada managed block |
+| `workspace <sub>` | Gestiona workspaces cross-repo (init, ls, show, add-repo) |
+| `ticket <sub>` | Gestiona tickets-as-files en un workspace (new, list, show) |
+
+## Plugins disponibles
+
+| Plugin | Para qué | External tool |
+|---|---|---|
+| `engram` | Memoria persistente entre sesiones | `engram` binary |
+| `acli` | Leer tickets de Jira desde la terminal | `acli` |
+| `gh` | GitHub Issues, PRs y workflow runs | `gh` |
+| `jscpd` | Detección de duplicación en el diff | `jscpd` (opt-in) |
+| `semgrep` | Security gate local | `semgrep` (opt-in) |
+| `cognitive` | Guardrails de complejidad cognitiva | (ninguna) |
+
+Activar uno:
+```bash
+navori add engram          # te ofrece instalar la tool externa si falta
+navori add engram --skip-install   # solo registra el plugin
+```
+
+## Workspace + tickets cross-repo
+
+Si un ticket toca varios repos (frontend + backend + microservicio), el workspace te da un punto único:
+
+```bash
+# Crear workspace
+navori workspace init bonum --description "Bonum platform"
+
+# Registrar repos del workspace
+navori workspace add-repo bonum --name webapp --path ~/dev/bonum/webapp --stack vite-react-ts-mantine
+navori workspace add-repo bonum --name backend --path ~/dev/bonum/nexus --stack nestjs
+
+# Crear ticket
+navori ticket new bonum BNM-123 --title "Checkout flow rebuild"
+
+# En cada repo que tocás el ticket, agregá una referencia:
+# echo "ticket: BNM-123" >> progress/current.md
+
+# Ver el ticket + en qué repos aparece
+navori ticket show bonum BNM-123
+```
+
+El workspace también guarda defaults heredables:
+```bash
+navori init --workspace bonum    # hereda engines, plugins, branchBase, etc.
+```
+
+Storage: `~/.navori/workspaces/<name>/` (manifest + tickets/ + backups/).
+
+## Managed blocks con versionado
+
+Cada bloque que `navori` inyecta en tu `CLAUDE.md` lleva metadata:
+
+```html
+<!-- navori:managed id="idioma-rol" hash="3fbef743" version="0.0.1" source="@navori/core" -->
+contenido sincronizado
+<!-- /navori:managed id="idioma-rol" -->
+```
+
+- **`hash`**: detecta si vos editaste el bloque (sync te avisa antes de pisar)
+- **`version`**: cuando se publica una nueva versión de `@navori/core` o un plugin, `sync` reporta "update available"
+- **`source`**: qué paquete es dueño del bloque (`doctor` te muestra la procedencia de cada uno)
+
+Si modificás un managed block a mano y después corrés `sync`, vas a ver:
+```
+Conflict in 'idioma-rol':
+  - tu versión
+  + versión del Core
+```
+Y elegís: `skip-conflicts` (mantener tu edit), `apply-all` (pisar) o `abort`.
+
+Backups automáticos en `~/.navori/backups/<timestamp>/` antes de cada `sync` (retención 30 días).
+
+## Customización quirúrgica
+
+Cambiar una sola cosa sin re-init:
+
+```bash
+navori configure plugins              # multiselect de plugins activos
+navori configure quality-gate         # nuevo comando de quality gate
+navori configure language en          # switch a inglés (fallback a es)
+navori configure engines              # multiselect: claude / agents-md / cursor / copilot
+navori configure workspace bonum      # asociar a un workspace
+```
+
+## Filosofía
+
+- **Cero opinión sobre tu proceso**. El CLI detecta y propone; vos decidís.
+- **Coexiste con harness existente**. Modo `coexist` no toca nada que ya tenías.
+- **Nunca pisa silenciosamente**. Hash en el marker + backups antes de cada write.
+- **Output legible siempre**. Texto + `--json` para piping en CI.
+- **Bilingüe ready**. Schema soporta `language: es | en`. Hoy solo `es` está full; `en` cae en fallback honesto.
+
+## Licencia
+
+ISC.

package/dist/assets/core/core-assets/managed/cierre-sesion.md

@@ -0,0 +1,9 @@
+## Cierre de sesión
+
+Antes de cerrar la sesión:
+
+1. **Quality gate**: corré `{{qualityGate.full}}` y confirmá que pasa (o documentá deuda en `progress/current.md`).
+2. **History**: agregá entrada en `progress/history.md` con `## YYYY-MM-DD HH:MM <agente> — <resumen>` + cambios + estado del gate.
+3. **Vaciar current**: dejá `progress/current.md` en estado `idle` o con el siguiente paso explícito.
+4. **Sin temporales**: borrá scratch files, no dejes `console.log`, `debugger`, ni código comentado.
+5. **Commit Conventional**: `feat|fix|chore|docs(scope): mensaje`, español MX, atómico. Nunca commitear `.claude/` ni `CLAUDE.md`.

package/dist/assets/core/core-assets/managed/formato-respuesta.md

@@ -0,0 +1,12 @@
+## Formato de respuesta
+
+**Bug fix** (sin intro ni cierre):
+CAUSA: <1 línea> / ARCHIVO: <path>:<línea> / FIX: <diff mínimo>
+
+**Code review**:
+[CRÍTICO] ... # rompe build, security o pérdida de datos
+[ALTO]    ... # bug funcional, regresión
+[MEDIO]   ... # legibilidad, naming
+
+**Generación**: diff si modifica; archivo completo solo si es nuevo.
+**Commits**: Conventional (`feat(scope): ...`), español MX, atómicos.

package/dist/assets/core/core-assets/managed/idioma-rol.md

@@ -0,0 +1,4 @@
+## Idioma y rol
+
+- Código/JSDoc: inglés. Chat: español MX.
+- Rol Tech Lead Senior. Antes de codear: ¿lo más simple? ¿legible en 6 meses? ¿mantiene patrón existente? Simplicidad > cleverness.

package/dist/assets/core/core-assets/managed/tipado-fuerte.md

@@ -0,0 +1,5 @@
+## Tipado fuerte
+
+`any` prohibido. Usar `unknown` + narrowing. Tipar explícitamente: parámetros, retornos, callbacks, eventos, props, hooks y responses de services.
+
+Excepción: `// any justificado: <razón>` — último recurso, no atajo. Si no hay razón clara, no es justificado.

package/dist/assets/core/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@navori/core",
+  "version": "0.0.1",
+  "description": "Universal harness primitives — managed core assets",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./assets/*": "./core-assets/*"
+  },
+  "files": [
+    "src",
+    "core-assets"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/dist/assets/plugins/acli/managed/acli-protocol.md

@@ -0,0 +1,10 @@
+## Tickets de Jira (acli)
+
+Para leer tickets de Jira usá **acli** (no el MCP de Atlassian).
+
+- Ver un ticket: `acli jira workitem view <KEY>` (ej. `acli jira workitem view BNM-123`)
+- Buscar tickets: `acli jira workitem search --jql "<JQL>"`
+- Listar comentarios: `acli jira workitem comment list --key <KEY>`
+- Listar transiciones: `acli jira workitem transition list --key <KEY>`
+
+El MCP de Atlassian/Rovo queda como fallback si `acli` falla o no está disponible.

package/dist/assets/plugins/acli/plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "acli",
+  "name": "Atlassian CLI (Jira tickets)",
+  "description": "Lectura de tickets de Jira desde la terminal sin abrir el browser",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "acli-protocol",
+      "file": "managed/acli-protocol.md",
+      "recommendedAgent": "researcher"
+    }
+  ],
+  "externalTool": {
+    "name": "acli",
+    "checkBinary": "acli",
+    "install": {
+      "darwin": "brew install atlassian-labs/acli/acli",
+      "linux": "curl -fsSL https://acli-releases.atlassian.com/install.sh | bash"
+    }
+  }
+}

package/dist/assets/plugins/cognitive/managed/cognitive-protocol.md

@@ -0,0 +1,9 @@
+## Complejidad cognitiva (SonarJS)
+
+Antes de aprobar un cambio, verificar que las funciones tocadas no exceden el umbral de complejidad cognitiva.
+
+- Threshold por default: `cognitive-complexity: ["error", 15]` (ESLint SonarJS).
+- Si una función excede el umbral: **refactorizar antes de aprobar** (extraer funciones, simplificar condicionales, dividir responsabilidades).
+- Casos válidos donde se relaja: state machines explícitas, parsers, switch/case sobre un enum cerrado. Documentar con `// cognitive-complexity-allowed: <razón>` antes del bloque.
+
+Tool externa no requerida — la regla corre dentro del lint del proyecto si está configurada. Si no, este protocolo es informativo y debe leerse en code review.

package/dist/assets/plugins/cognitive/plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "cognitive",
+  "name": "Cognitive complexity guardrails",
+  "description": "Detección de complejidad cognitiva alta via ESLint rule SonarJS",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "cognitive-protocol",
+      "file": "managed/cognitive-protocol.md",
+      "recommendedAgent": "reviewer"
+    }
+  ]
+}

package/dist/assets/plugins/engram/managed/engram-protocol.md

@@ -0,0 +1,5 @@
+## Engram
+
+- `mem_save` proactivo tras decisión / bug-fix-con-root-cause / convención / discovery / preferencia confirmada.
+- `mem_search` al inicio si el primer mensaje referencia el proyecto. Verificar en código que lo recordado siga existiendo antes de afirmarlo.
+- `mem_session_summary` obligatorio antes de "listo": Goal · Discoveries · Accomplished · Next Steps · Relevant Files.

package/dist/assets/plugins/engram/plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "engram",
+  "name": "Engram persistent memory",
+  "description": "Memory persistence across Claude Code sessions via MCP server",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "engram-protocol",
+      "file": "managed/engram-protocol.md",
+      "recommendedAgent": "leader"
+    }
+  ],
+  "externalTool": {
+    "name": "engram",
+    "checkBinary": "engram",
+    "install": {
+      "darwin": "brew install gentleman-programming/tap/engram",
+      "linux": "curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/engram/main/scripts/install.sh | bash"
+    },
+    "postInstall": "claude plugin install engram"
+  }
+}

package/dist/assets/plugins/gh/managed/gh-protocol.md

@@ -0,0 +1,12 @@
+## GitHub CLI (gh)
+
+Para interactuar con GitHub (issues, PRs, repos) usá **gh**:
+
+- Ver issue: `gh issue view <number>` o `gh issue view <number> --comments`
+- Buscar issues: `gh issue list --search "<query>"` o `gh issue list --label bug --state open`
+- Crear PR: `gh pr create --title "..." --body "..."`
+- Ver PR + checks: `gh pr view <number> --checks` o `gh pr checks <number>`
+- Listar PRs: `gh pr list --state open`
+- Ver workflow runs: `gh run list --limit 5` o `gh run view <id> --log-failed`
+
+`gh auth status` muestra si está autenticado. Si falla, correr `gh auth login`.

package/dist/assets/plugins/gh/plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "gh",
+  "name": "GitHub CLI (issues + PRs)",
+  "description": "Acceso a Issues, PRs y repos de GitHub desde la terminal",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "gh-protocol",
+      "file": "managed/gh-protocol.md",
+      "recommendedAgent": "commit-pr-pilot"
+    }
+  ],
+  "externalTool": {
+    "name": "gh",
+    "checkBinary": "gh",
+    "install": {
+      "darwin": "brew install gh",
+      "linux": "(see https://github.com/cli/cli/blob/trunk/docs/install_linux.md)",
+      "win32": "winget install --id GitHub.cli"
+    },
+    "postInstall": "gh auth status || gh auth login"
+  }
+}

package/dist/assets/plugins/jscpd/managed/jscpd-protocol.md

@@ -0,0 +1,10 @@
+## Duplicación de código (jscpd)
+
+Antes de aprobar un cambio, correr jscpd sobre el diff vs la branch base.
+
+- Solo sobre archivos modificados:
+  ```
+  git diff --name-only $BRANCH_BASE...HEAD | grep -E '\.(ts|tsx|js|jsx)$' | xargs jscpd --silent
+  ```
+- Si reporta clones >0 con threshold del proyecto: **no aprobar** el cambio sin justificar (los reviewers deben pedir refactor o extracción).
+- Skip silencioso si `jscpd` no está en `PATH` (no bloquear si el dev no tiene la tool instalada).

package/dist/assets/plugins/jscpd/plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "jscpd",
+  "name": "jscpd (code duplication detector)",
+  "description": "Detección de duplicación de código en el diff vs branch base",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "jscpd-protocol",
+      "file": "managed/jscpd-protocol.md",
+      "recommendedAgent": "reviewer"
+    }
+  ],
+  "externalTool": {
+    "name": "jscpd",
+    "checkBinary": "jscpd",
+    "install": {
+      "darwin": "pnpm add -g jscpd",
+      "linux": "pnpm add -g jscpd",
+      "win32": "pnpm add -g jscpd"
+    }
+  }
+}

package/dist/assets/plugins/semgrep/managed/semgrep-protocol.md

@@ -0,0 +1,14 @@
+## Security gate local (semgrep)
+
+Antes de cerrar un cambio relevante (auth, RBAC, secrets, input validation), correr semgrep sobre el diff.
+
+- Scan rápido del diff:
+  ```
+  git diff --name-only $BRANCH_BASE...HEAD | xargs semgrep --config=auto --severity=ERROR
+  ```
+- Scan completo del proyecto (más lento, opt-in):
+  ```
+  semgrep --config=auto --error
+  ```
+- Reglas custom: ver `.semgrep.yml` en la raíz del repo si existe.
+- Skip silencioso si `semgrep` no está instalado (no bloquear si el dev no lo tiene).

package/dist/assets/plugins/semgrep/plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "semgrep",
+  "name": "semgrep (security + pattern analysis)",
+  "description": "Detección de vulnerabilidades y patrones inseguros local opt-in",
+  "version": "0.0.1",
+  "managed": [
+    {
+      "id": "semgrep-protocol",
+      "file": "managed/semgrep-protocol.md",
+      "recommendedAgent": "reviewer"
+    }
+  ],
+  "externalTool": {
+    "name": "semgrep",
+    "checkBinary": "semgrep",
+    "install": {
+      "darwin": "brew install semgrep",
+      "linux": "pipx install semgrep"
+    }
+  }
+}