nwlnexus/agent-skills

GitNexus sem retrabalho

O GitNexus causa dois tipos de ruído recorrente quando usado ingenuamente:

1. Índice desatualizado. O índice registra o commit em que foi construído; a cada commit ele fica "N commits atrás" e o hook do Claude avisa para reexecutar analyze.
2. Reescritas de documentos. Um gitnexus analyze simples injeta contagens voláteis de símbolos na seção gerenciada <!-- gitnexus:start -->…<!-- gitnexus:end --> de CLAUDE.md/AGENTS.md e reinstala skills, então cada reindexação produz um diff que exige um commit.

A correção é a mesma em todo repositório: hooks git mantêm o índice em HEAD com --index-only, e os documentos são gerados uma vez com --no-stats e só regenerados após uma atualização do gitnexus. Aplique como um PR chore(gitnexus): ….

Passo 0 — pré-condições (somente leitura)

command -v gitnexus && gitnexus --version          # deve estar instalado (mise/npm global); nunca confie em npx
test -f .gitnexus/gitnexus.json && gitnexus status # indexado? se não: 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

Decida: gerenciador de hooks (husky → lefthook → pre-commit → simples), onde os scripts locais do repositório ficam (scripts/, tools/, bin/… siga o repositório), como o repositório expõe comandos (package.json scripts, Makefile, justfile, ou nenhum → documente o comando bruto).

Passo 1 — instalar o script de atualização

Copie scripts/gitnexus-refresh.sh deste diretório de skill para o local de scripts do repositório (ex.: scripts/git-hooks/gitnexus-refresh.sh), chmod 755. Ele é agnóstico ao repositório: resolve a raiz git, sai silenciosamente se gitnexus estiver faltando ou o clone não estiver indexado, pula quando o índice já corresponde a HEAD, caso contrário executa gitnexus analyze --index-only em segundo plano (log em .gitnexus/refresh.log). Não faça fork por repositório a menos que as convenções do repo exijam (ex.: um diretório de scripts diferente).

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

Os corpos dos hooks são uma linha: sh <caminho>/gitnexus-refresh.sh. post-checkout deve executar apenas para checkouts de branch que movem HEAD: primeiro coloque [ "$3" = "1" ] && [ "$1" != "$2" ] || exit 0.

• husky (.husky/ existe): adicione .husky/post-commit, post-merge, post-checkout, post-rewrite (mesmo shebang/modo dos hooks existentes; husky 9 os executa com sh -e).
• lefthook: adicione seções post-commit, post-merge, post-checkout, post-rewrite com um único comando gitnexus-refresh; run: sh <caminho>/gitnexus-refresh.sh {1} {2} {3} para post-checkout.
• pre-commit framework: adicione um hook repo: local com stages: [post-commit, post-merge, post-checkout, post-rewrite], always_run: true, pass_filenames: false; lembre o usuário de pre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewrite.
• nenhum: crie um .githooks/ commitado com os quatro arquivos e defina git config core.hooksPath .githooks no script de configuração do repositório/alvo do Makefile (nunca confie em um .git/hooks não commitado).

Nunca coloque o hook sob pre-commit/pre-push: estes devem permanecer rápidos e o índice deve seguir o HEAD resultante.

Passo 3 — tornar os documentos estáveis

1. Regere a seção gerenciada uma vez sem contagens: gitnexus analyze --force --no-stats --skip-skills. Espere um diff que apenas remova as contagens de cabeçalho (N symbols, …) e a tabela de contagens por área. Se o repositório nunca teve uma seção gerenciada e não quer uma, use --index-only em todos os lugares e pule isso.

2. Exponha dois comandos usando a convenção do repositório:

   • atualização de rotina → gitnexus analyze --index-only (ex.: pnpm gitnexus:index / make gitnexus-index)
   • atualização de documentos → gitnexus analyze --force --no-stats --skip-skills (ex.: gitnexus:refresh-docs), apenas após uma atualização do gitnexus alterar seu modelo.

3. Adicione uma curta seção "Higiene do índice GitNexus" a CLAUDE.md (e AGENTS.md se presente) fora dos marcadores, adaptada ao repositório:

   O índice (.gitnexus/, não rastreado) é atualizado automaticamente pelos hooks post-commit/post-merge/post-checkout/post-rewrite (<caminho>/gitnexus-refresh.sh): apenas índice, em segundo plano, log em .gitnexus/refresh.log. Se ainda se reportar atrasado, execute <comando de índice>.

   • NÃO execute um gitnexus analyze simples (ou node .gitnexus/run.cjs analyze): ele reescreve CLAUDE.md, AGENTS.md e .claude/skills/gitnexus-*. Use <comando de índice>.
   • <comando de documentos> regenera a seção gerenciada gitnexus:start…gitnexus:end sem contagens voláteis; execute-o apenas após uma atualização do gitnexus, commite o resultado. Nunca edite manualmente entre os marcadores.

4. Se o repositório ainda tiver o layout obsoleto aninhado .claude/skills/gitnexus/<skill>/ ou .claude/skills/generated/** commitados, substitua-os pelo layout plano .claude/skills/gitnexus-* que GitNexus ≥1.6 escreve (gitnexus analyze --skills --skip-agents-md regenera gitnexus-area-*; git rm os diretórios antigos). As skills de área carregam contagens apenas em seus corpos, o que é aceitável — elas não são regeneradas pelos hooks.

Passo 4 — verificar antes de abrir o PR

git commit …                      # aciona post-commit
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexed == Current, ✅ up-to-date
git status --short                # deve estar limpo: sem diff em CLAUDE.md/AGENTS.md/skills

Em seguida, push, PR, merge (se autorizado), pull main — o pull aciona post-merge; confirme gitnexus status novamente.

Regras gerais

• --index-only para qualquer coisa automatizada; --no-stats para qualquer coisa que toque nos documentos; nunca analyze simples.
• A atualização do índice é barata (segundos, incremental), mas rebases rápidos enfileiram várias execuções; o próprio lock do gitnexus as serializa — não adicione bloqueio no hook.
• Vários worktrees têm cada um seu próprio .gitnexus/; os hooks lidam com cada um independentemente.
• Executar gitnexus via npx é lento (round-trip de registro, sensível a TLS) e pode exceder o timeout de conexão de 30 s do MCP — instale-o (mise/npm global) e referencie o binário.
• Não altere a configuração MCP/hook do GitNexus por usuário de dentro de um repositório; isso vive na configuração do Claude do usuário (gerenciado por nix para Nigel).