nwlnexus/agent-skills

GitNexus sans churn

GitNexus provoque deux types de bruit récurrent lorsqu'il est utilisé naïvement :

1. Index obsolète. L'index enregistre le commit sur lequel il a été construit ; chaque commit le rend « N commits behind » et le hook Claude insiste pour relancer analyze.
2. Réécriture des docs. Une gitnexus analyze nue injecte des décomptes de symboles volatils dans la section gérée <!-- gitnexus:start -->…<!-- gitnexus:end --> de CLAUDE.md/AGENTS.md et réinstalle les compétences, donc chaque ré-indexation produit un diff qui demande un commit.

La correction est la même dans tous les dépôts : les hooks git maintiennent l'index à HEAD avec --index-only, et les docs sont générées une fois avec --no-stats et ne sont régénérées qu'après une mise à jour de gitnexus. Appliquez-la en un seul PR de type chore(gitnexus): ….

Étape 0 — préconditions (lecture seule)

command -v gitnexus && gitnexus --version          # doit être installé (mise/npm global) ; ne jamais compter sur npx
test -f .gitnexus/gitnexus.json && gitnexus status # indexé ? sinon : 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

Décider : gestionnaire de hooks (husky → lefthook → pre-commit → brut), où se trouvent les scripts locaux du dépôt (scripts/, tools/, bin/… selon les conventions du dépôt), comment le dépôt expose les commandes (package.json scripts, Makefile, justfile, ou rien → documenter la commande brute).

Étape 1 — installer le script de rafraîchissement

Copier scripts/gitnexus-refresh.sh depuis ce répertoire de compétence vers l'emplacement des scripts du dépôt (p. ex. scripts/git-hooks/gitnexus-refresh.sh), chmod 755. Il est agnostique au dépôt : il résout la racine git, se termine silencieusement si gitnexus est manquant ou si le clone n'est pas indexé, ignore le cas où l'index correspond déjà à HEAD, sinon exécute gitnexus analyze --index-only en détaché (log dans .gitnexus/refresh.log). Ne pas dupliquer par dépôt sauf si les conventions du dépôt l'exigent (p. ex. un répertoire de scripts différent).

Étape 2 — brancher post-commit, post-merge, post-checkout, post-rewrite

Les corps des hooks sont d'une seule ligne : sh <chemin>/gitnexus-refresh.sh. post-checkout doit s'exécuter uniquement pour les changements de branche qui déplacent HEAD : [ "$3" = "1" ] && [ "$1" != "$2" ] || exit 0 d'abord.

• husky (.husky/ existe) : ajouter .husky/post-commit, post-merge, post-checkout, post-rewrite (même shebang/mode que les hooks existants ; husky 9 les exécute avec sh -e).
• lefthook : ajouter les sections post-commit, post-merge, post-checkout, post-rewrite avec une seule commande gitnexus-refresh ; run: sh <chemin>/gitnexus-refresh.sh {1} {2} {3} pour post-checkout.
• pre-commit framework : ajouter un hook repo: local avec stages: [post-commit, post-merge, post-checkout, post-rewrite], always_run: true, pass_filenames: false ; rappeler à l'utilisateur de lancer pre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewrite.
• aucun : créer un dossier .githooks/ versionné avec les quatre fichiers et définir git config core.hooksPath .githooks dans le script de configuration du dépôt / la cible Makefile (ne jamais compter sur un .git/hooks non versionné).

Ne jamais placer le hook sous pre-commit/pre-push : ceux-ci doivent rester rapides et l'index doit suivre le HEAD résultant.

Étape 3 — rendre les docs stables

1. Régénérer une fois la section gérée sans décomptes : gitnexus analyze --force --no-stats --skip-skills. Attendez-vous à un diff qui ne supprime que les en-têtes (N symbols, …) et le tableau de décomptes par zone. Si le dépôt n'a jamais eu de section gérée et n'en veut pas, utilisez --index-only partout et sautez cette étape.

2. Exposer deux commandes selon la convention du dépôt :

   • rafraîchissement courant → gitnexus analyze --index-only (p. ex. pnpm gitnexus:index / make gitnexus-index)
   • rafraîchissement des docs → gitnexus analyze --force --no-stats --skip-skills (p. ex. gitnexus:refresh-docs), uniquement après une mise à jour de gitnexus qui modifie son modèle.

3. Ajouter une courte section « Hygiène de l'index GitNexus » dans CLAUDE.md (et AGENTS.md si présent) en dehors des marqueurs, adaptée au dépôt :

   L'index (.gitnexus/, non tracé) est rafraîchi automatiquement par les hooks post-commit/post-merge/post-checkout/post-rewrite (<chemin>/gitnexus-refresh.sh) : index-only, en arrière-plan, log dans .gitnexus/refresh.log. S'il se déclare encore en retard, exécutez <commande index>.

   • NE PAS exécuter une gitnexus analyze nue (ni node .gitnexus/run.cjs analyze) : elle réécrit CLAUDE.md, AGENTS.md et .claude/skills/gitnexus-*. Utilisez <commande index>.
   • <commande docs> régénère la section gérée gitnexus:start…gitnexus:end sans décomptes volatils ; exécutez-la seulement après une mise à jour de gitnexus, committez le résultat. Ne jamais éditer manuellement entre les marqueurs.

4. Si le dépôt a encore la disposition obsolète avec .claude/skills/gitnexus/<skill>/ imbriqué ou des .claude/skills/generated/** versionnés, remplacez-les par la disposition plate .claude/skills/gitnexus-* que GitNexus ≥1.6 écrit (gitnexus analyze --skills --skip-agents-md régénère gitnexus-area-* ; git rm les anciens dossiers). Les compétences de zone contiennent des décomptes dans leurs corps uniquement, ce qui est acceptable — elles ne sont pas regénérées par les hooks.

Étape 4 — vérifier avant d'ouvrir le PR

git commit …                      # déclenche post-commit
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexed == Current, ✅ à jour
git status --short                # doit être propre : pas de diff sur CLAUDE.md/AGENTS.md/skills

Puis push, PR, merger (si autorisé), tirer main — le pull déclenche post-merge ; confirmer gitnexus status à nouveau.

Règles de base

• --index-only pour tout ce qui est automatisé ; --no-stats pour tout ce qui touche aux docs ; jamais analyze nu.
• Le rafraîchissement de l'index est rapide (secondes, incrémental) mais des rebases rapides mettent plusieurs exécutions en file ; le verrou interne de gitnexus les sérialise — ne pas ajouter de verrouillage dans le hook.
• Chaque worktree a son propre .gitnexus/ ; les hooks les gèrent chacun indépendamment.
• Exécuter gitnexus via npx est lent (aller-retour vers le registre, sensible au TLS) et peut dépasser le délai de connexion MCP de 30 s — installez-le (mise/npm global) et référencez le binaire.
• Ne pas modifier la configuration MCP/hook GitNexus de l'utilisateur depuis l'intérieur d'un dépôt ; celle-ci se trouve dans le config Claude de l'utilisateur (géré par nix pour Nigel).