nwlnexus/agent-skills

GitNexus sin ruido

GitNexus provoca dos tipos de ruido recurrente cuando se usa de forma ingenua:

1. Índice desactualizado. El índice registra el commit en el que se construyó; cada commit lo deja "N commits detrás" y el hook de Claude insiste en re-ejecutar analyze.
2. Reescrituras de documentos. Un gitnexus analyze simple inyecta conteos de símbolos volátiles en la sección gestionada <!-- gitnexus:start -->…<!-- gitnexus:end --> de CLAUDE.md/AGENTS.md y reinstala skills, por lo que cada re-índice produce un diff que pide un commit.

La solución es la misma en todos los repositorios: los hooks de git mantienen el índice en HEAD con --index-only, y los documentos se generan una vez con --no-stats y solo se regeneran tras una actualización de gitnexus. Aplícalo como un único PR chore(gitnexus): ….

Paso 0 — prerequisitos (solo lectura)

command -v gitnexus && gitnexus --version          # debe estar instalado (mise/npm global); nunca confíes en npx
test -f .gitnexus/gitnexus.json && gitnexus status # ¿indexado? si no: gitnexus analyze --index-only
git config core.hooksPath; ls .husky lefthook.yml .lefthook.yml .pre-commit-config.yaml 2>/dev/null
ls CLAUDE.md AGENTS.md; grep -c 'gitnexus:start' CLAUDE.md AGENTS.md 2>/dev/null
ls package.json Makefile justfile 2>/dev/null

Decide: gestor de hooks (husky → lefthook → pre-commit → plano), dónde viven los scripts locales del repositorio (scripts/, tools/, bin/… que coincida con el repo), cómo expone el repo los comandos (package.json scripts, Makefile, justfile, o ninguno → documenta el comando directo).

Paso 1 — instalar el script de refresco

Copia scripts/gitnexus-refresh.sh de este directorio de skill a la ubicación de scripts del repositorio (ej. scripts/git-hooks/gitnexus-refresh.sh), chmod 755. Es agnóstico del repositorio: resuelve la raíz de git, sale silenciosamente si gitnexus falta o el clon no está indexado, se salta cuando el índice ya coincide con HEAD, en otro caso ejecuta gitnexus analyze --index-only en segundo plano (log en .gitnexus/refresh.log). No lo bifurques por repositorio a menos que las convenciones del repo lo exijan (ej. un directorio de scripts diferente).

Paso 2 — conectar post-commit, post-merge, post-checkout, post-rewrite

Los cuerpos de los hooks son de una línea: sh <ruta>/gitnexus-refresh.sh. post-checkout solo debe ejecutarse para checkouts de rama que muevan HEAD: primero [ "$3" = "1" ] && [ "$1" != "$2" ] || exit 0.

• husky (.husky/ existe): añade .husky/post-commit, post-merge, post-checkout, post-rewrite (mismo shebang/modo que los hooks existentes; husky 9 los ejecuta con sh -e).
• lefthook: añade secciones post-commit, post-merge, post-checkout, post-rewrite con un solo comando gitnexus-refresh; run: sh <ruta>/gitnexus-refresh.sh {1} {2} {3} para post-checkout.
• pre-commit framework: añade un hook repo: local con stages: [post-commit, post-merge, post-checkout, post-rewrite], always_run: true, pass_filenames: false; recuerda al usuario que ejecute pre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewrite.
• ninguno: crea un directorio .githooks/ con los cuatro archivos y establece git config core.hooksPath .githooks en el script de configuración/target del Makefile del repositorio (nunca confíes en un .git/hooks sin commitear).

Nunca pongas el hook bajo pre-commit/pre-push: esos deben seguir siendo rápidos y el índice debe seguir al HEAD resultante.

Paso 3 — hacer la documentación estable

1. Regenera la sección gestionada una vez sin conteos: gitnexus analyze --force --no-stats --skip-skills. Espera un diff que solo elimine los conteos de cabecera (N símbolos, …) y la tabla de conteos por área. Si el repositorio nunca tuvo una sección gestionada y no quiere una, usa --index-only en todas partes y salta esto.

2. Expón dos comandos usando la convención del repositorio:

   • refresco rutinario → gitnexus analyze --index-only (ej. pnpm gitnexus:index / make gitnexus-index)
   • refresco de docs → gitnexus analyze --force --no-stats --skip-skills (ej. gitnexus:refresh-docs), solo tras una actualización de gitnexus que cambie su plantilla.

3. Añade una breve sección "Higiene del índice GitNexus" a CLAUDE.md (y a AGENTS.md si existe) fuera de los marcadores, adaptada al repositorio:

   El índice (.gitnexus/, no rastreado) se refresca automáticamente mediante los hooks post-commit/post-merge/post-checkout/post-rewrite (<ruta>/gitnexus-refresh.sh): solo índice, en segundo plano, log en .gitnexus/refresh.log. Si aún se reporta atrasado, ejecuta <comando de índice>.

   • NO ejecutes un gitnexus analyze simple (ni node .gitnexus/run.cjs analyze): reescribe CLAUDE.md, AGENTS.md y .claude/skills/gitnexus-*. Usa <comando de índice>.
   • <comando de docs> regenera la sección gestionada gitnexus:start…gitnexus:end sin conteos volátiles; ejecútalo solo tras una actualización de gitnexus, haz commit del resultado. Nunca edites a mano entre los marcadores.

4. Si el repositorio aún tiene el diseño obsoleto .claude/skills/gitnexus/<skill>/ anidado o .claude/skills/generated/** con commit, reemplázalos con el diseño plano .claude/skills/gitnexus-* que GitNexus ≥1.6 escribe (gitnexus analyze --skills --skip-agents-md regenera gitnexus-area-*; git rm de los directorios antiguos). Las skills de área llevan conteos solo en sus cuerpos, lo cual está bien — los hooks no las regeneran.

Paso 4 — verificar antes de abrir el PR

git commit …                      # dispara post-commit
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexado == Actual, ✅ al día
git status --short                # debe estar limpio: sin diff en CLAUDE.md/AGENTS.md/skills

Luego haz push, PR, merge (si autorizado), haz pull de main — el pull dispara post-merge; confirma gitnexus status de nuevo.

Reglas prácticas

• --index-only para todo lo automatizado; --no-stats para todo lo que toque los documentos; nunca analyze simple.
• El refresco del índice es barato (segundos, incremental) pero los rebases rápidos encolan varias ejecuciones; el propio candado de gitnexus las serializa — no añadas bloqueo en el hook.
• Cada worktree tiene su propio .gitnexus/; los hooks manejan cada uno independientemente.
• Ejecutar gitnexus mediante npx es lento (viaje de ida y vuelta al registro, sensible a TLS) y puede exceder el tiempo de espera de conexión de MCP de 30 s — instálalo (mise/npm global) y referencia el binario.
• No cambies la configuración de MCP/hook de GitNexus por usuario desde dentro de un repositorio; eso vive en la configuración de Claude del usuario (gestionada con nix para Nigel).