nwlnexus/agent-skills

GitNexus ohne Änderungschaos

GitNexus verursacht zwei Arten von wiederkehrendem Rauschen, wenn es naiv eingesetzt wird:

1. Veralteter Index. Der Index zeichnet den Commit auf, bei dem er erstellt wurde; jeder Commit macht ihn „N Commits hinterher" und der Claude-Hook drängt zur erneuten Ausführung von analyze.
2. Dokument-Überschreibungen. Ein bloßes gitnexus analyze injiziert volatile Symbolzahlen in den verwalteten <!-- gitnexus:start -->…<!-- gitnexus:end -->-Abschnitt von CLAUDE.md/AGENTS.md und installiert Skills neu, sodass jede Neuindizierung einen Diff erzeugt, der einen Commit verlangt.

Die Lösung ist in jedem Repository dieselbe: Git-Hooks halten den Index mit --index-only auf HEAD, und die Dokumente werden einmal mit --no-stats generiert und nur nach einem GitNexus-Upgrade neu erstellt. Wende es als einen chore(gitnexus): … PR an.

Schritt 0 – Voraussetzungen (schreibgeschützt)

command -v gitnexus && gitnexus --version          # muss installiert sein (mise/npm global); niemals auf npx verlassen
test -f .gitnexus/gitnexus.json && gitnexus status # indiziert? falls nicht: 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

Entscheide: Hook-Manager (husky → lefthook → pre-commit → plain), wo Repository-lokale Skripte leben (scripts/, tools/, bin/… dem Repository anpassen), wie das Repository Befehle bereitstellt (package.json-Skripte, Makefile, justfile, oder keins → den rohen Befehl dokumentieren).

Schritt 1 – Das Aktualisierungsskript installieren

Kopiere scripts/gitnexus-refresh.sh aus diesem Skill-Verzeichnis an den Skript-Speicherort des Repositorys (z.B. scripts/git-hooks/gitnexus-refresh.sh), chmod 755. Es ist Repository-unabhängig: Ermittelt das Git-Wurzelverzeichnis, beendet sich still, wenn gitnexus fehlt oder der Klon nicht indiziert ist, überspringt die Ausführung, wenn der Index bereits HEAD entspricht, und führt andernfalls gitnexus analyze --index-only im Hintergrund aus (Log in .gitnexus/refresh.log). Gabeln Sie es nicht pro Repository, es sei denn, die Repository-Konventionen verlangen es (z.B. ein anderes Skriptverzeichnis).

Schritt 2 – post-commit, post-merge, post-checkout, post-rewrite verdrahten

Hook-Rümpfe sind eine Zeile: sh <pfad>/gitnexus-refresh.sh. post-checkout muss nur für Branch-Checkouts ausgeführt werden, die HEAD verschieben: zuerst [ "$3" = "1" ] && [ "$1" != "$2" ] || exit 0.

• husky (.husky/ existiert): Füge .husky/post-commit, post-merge, post-checkout, post-rewrite hinzu (gleicher Shebang/Modus wie die vorhandenen Hooks; husky 9 führt sie mit sh -e aus).
• lefthook: Füge Abschnitte post-commit, post-merge, post-checkout, post-rewrite mit einem einzelnen gitnexus-refresh-Befehl hinzu; für post-checkout: run: sh <pfad>/gitnexus-refresh.sh {1} {2} {3}.
• pre-commit-Framework: Füge einen repo: local-Hook mit stages: [post-commit, post-merge, post-checkout, post-rewrite], always_run: true, pass_filenames: false hinzu; erinnere den Benutzer an pre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewrite.
• keiner: Erstelle ein committetes .githooks/ mit den vier Dateien und setze git config core.hooksPath .githooks im Setup-Skript/Makefile-Ziel des Repositorys (niemals auf ein nicht committetes .git/hooks verlassen).

Setze den Hook niemals unter pre-commit/pre-push: Diese müssen schnell bleiben und der Index sollte dem resultierenden HEAD folgen.

Schritt 3 – Die Dokumente stabil machen

1. Generiere den verwalteten Abschnitt einmal ohne Zählungen neu: gitnexus analyze --force --no-stats --skip-skills. Erwarte einen Diff, der nur die (N Symbole, …)-Kopfzählungen und die Tabelle der Zählungen pro Bereich entfernt. Wenn das Repository nie einen verwalteten Abschnitt hatte und keinen haben möchte, verwende überall --index-only und überspringe dies.

2. Lege zwei Befehle gemäß der Repository-Konvention offen:

   • Routinemäßige Aktualisierung → gitnexus analyze --index-only (z.B. pnpm gitnexus:index / make gitnexus-index)
   • Dokumentaktualisierung → gitnexus analyze --force --no-stats --skip-skills (z.B. gitnexus:refresh-docs), nur nach einem GitNexus-Upgrade, das seine Vorlage ändert.

3. Füge einen kurzen Abschnitt „GitNexus-Index-Hygiene" in CLAUDE.md (und AGENTS.md, falls vorhanden) außerhalb der Marker hinzu, an das Repository angepasst:

   Der Index (.gitnexus/, unversioniert) wird automatisch von den post-commit/post-merge/post-checkout/post-rewrite-Hooks (<pfad>/gitnexus-refresh.sh) aktualisiert: nur Index, im Hintergrund, Log in .gitnexus/refresh.log. Falls er immer noch meldet, dass er hinterher ist, führe <Index-Befehl> aus.

   • Führe KEIN bloßes gitnexus analyze (oder node .gitnexus/run.cjs analyze) aus: Es überschreibt CLAUDE.md, AGENTS.md und .claude/skills/gitnexus-*. Verwende <Index-Befehl>.
   • <Dokument-Befehl> generiert den verwalteten gitnexus:start…gitnexus:end-Abschnitt ohne volatile Zählungen neu; führe ihn nur nach einem GitNexus-Upgrade aus, committe das Ergebnis. Bearbeite niemals von Hand zwischen den Markern.

4. Falls das Repository noch das veraltete verschachtelte .claude/skills/gitnexus/<skill>/-Layout oder committete .claude/skills/generated/** hat, ersetze sie durch das flache .claude/skills/gitnexus-*-Layout, das GitNexus ≥1.6 schreibt (gitnexus analyze --skills --skip-agents-md generiert gitnexus-area-* neu; git rm die alten Verzeichnisse). Die Bereichs-Skills tragen Zählungen nur in ihren Körpern, was in Ordnung ist – sie werden nicht von den Hooks neu generiert.

Schritt 4 – Vor dem Öffnen des PRs überprüfen

git commit …                      # löst post-commit aus
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexiert == Aktuell, ✅ aktuell
git status --short                # muss sauber sein: kein CLAUDE.md/AGENTS.md/skills Diff

Dann pushen, PR, mergen (wenn autorisiert), main pullen – der Pull löst post-merge aus; gitnexus status erneut bestätigen.

Faustregeln

• --index-only für alles Automatisierte; --no-stats für alles, was die Dokumente berührt; niemals bloßes analyze.
• Die Indexaktualisierung ist günstig (Sekunden, inkrementell), aber schnelle Rebasing-Phasen reihen mehrere Läufe aneinander; gitnexus' eigene Sperre serialisiert sie – füge keine Sperre im Hook hinzu.
• Mehrere Worktrees haben jeweils ihr eigenes .gitnexus/; die Hooks behandeln jeden unabhängig.
• GitNexus über npx auszuführen ist langsam (Registry-Roundtrip, TLS-empfindlich) und kann das MCP-30-s-Connect-Timeout überschreiten – installiere es (mise/npm global) und referenziere die Binärdatei.
• Ändere nicht die benutzerspezifische GitNexus-MCP/Hook-Einrichtung von innerhalb eines Repositorys; diese lebt in der Claude-Konfiguration des Benutzers (nix-verwaltet für Nigel).