Sync com o upstream

Este repositório é uma adaptação em português do Brasil de mattpocock/skills. O objetivo não é tradução literal: cada skill mantém o propósito, comportamento, fluxo e intenção da original, com linguagem, exemplos e contexto adequados ao público brasileiro.

O upstream é versionado com releases semver e mantém um CHANGELOG.md explicando cada mudança. A sincronização é feita release a release, nunca por acompanhamento contínuo de branch.

Fonte da verdade

UPSTREAM.md, na raiz deste repo:

• upstream-version: — última tag do upstream totalmente sincronizada;
• mapeamento de renames intencionais (identidade deste projeto);
• skills exclusivas deste repo (nunca remover — não têm correspondente no upstream);
• pendências conhecidas.

O remote upstream aponta para o repo do Matt. Se não existir: git remote add upstream https://github.com/mattpocock/skills.git.

Namespace de tags

As tags do upstream vivem sob upstream/* (ex.: upstream/v1.1.0); o namespace vX.Y.Z limpo pertence às releases deste repo. Isso é o que permite tagear um sync sem colidir com a tag homônima do Matt.

O remote já está configurado para isso. Se um clone novo não estiver:

git config remote.upstream.tagOpt --no-tags
git config --add remote.upstream.fetch "+refs/tags/*:refs/tags/upstream/*"

Nunca rode git fetch upstream --tags — isso despeja as tags do Matt no namespace limpo e reintroduz a colisão.

Processo

1. Descobrir o delta

git fetch upstream

• BASE = valor de upstream-version: em UPSTREAM.md (ex.: v1.1.0), lido como upstream/$BASE.
• ALVO = tag mais recente do upstream: git tag -l 'upstream/v*' | sort -V | tail -1.
• BASE == ALVO → nada a fazer, encerre.

2. Entender as mudanças — CHANGELOG primeiro, diff depois

1. Leia as seções do CHANGELOG.md do upstream entre BASE e ALVO (git show upstream/$ALVO:CHANGELOG.md). Ele explica o que mudou e por quê — use como esqueleto do relatório, não reconstrua do zero.

2. Gere o diff real, com detecção de renames:

   git diff -M upstream/$BASE..upstream/$ALVO -- skills/ .claude-plugin/plugin.json
   

   docs/ fica fora de propósito — veja as divergências deliberadas no UPSTREAM.md.

3. Cruze o diff com o mapeamento de nomes do UPSTREAM.md (ex.: mudanças em setup-matt-pocock-skills aplicam-se a setup-leandrocfe-skills).

3. Relatório e proposta — antes de tocar em qualquer arquivo

Apresente ao mantenedor:

• mudanças agrupadas por categoria (novas skills, renames, alterações, remoções);
• para cada uma: o que mudou, por que importa (cite o CHANGELOG) e o impacto nesta versão;
• proposta de adaptação, respeitando as regras abaixo;
• pontos que exigem decisão humana, destacados explicitamente.

Pare aqui e aguarde aprovação. Havendo ambiguidade, conflito entre versões ou mais de uma adaptação válida, pergunte antes de continuar.

4. Aplicar — somente após aprovação

• Adapte skill por skill; nunca copie e cole.
• Espelhe renames do upstream com git mv, exceto os listados no mapeamento do UPSTREAM.md.
• Atualize .claude-plugin/plugin.json: a lista de skills deve bater com os diretórios reais e o campo version deve espelhar a tag sincronizada. O hook "ARS scope guard" impede agents de escrever esse arquivo — entregue o conteúdo ao mantenedor para ele salvar à mão, ou peça que desligue o hook.
• Verifique as skills exclusivas deste repo (personal/) que encadeiam skills do upstream: um rename quebra as referências delas silenciosamente.
• Valide ao final: cada entrada do plugin.json existe em skills/; nenhum name: de frontmatter diverge do diretório; nenhuma referência a nome de skill morto sobrou (grep pelos nomes antigos); READMEs de bucket e top-level atualizados conforme o CLAUDE.md.

5. Fechar o sync

1. Atualize upstream-version: no UPSTREAM.md para ALVO e limpe pendências resolvidas.
2. Commit: sync: upstream ALVO.
3. Tag da release deste repo, espelhando a versão do upstream: git tag -a $ALVO -m "sync: upstream $ALVO". O namespace limpo está livre porque as tags do Matt vivem em upstream/*.
4. Confirme o push com o mantenedor antes de rodar git push origin $ALVO.
5. Feche a issue de sync aberta pelo workflow, se houver.
6. Opcional: traduza a seção do CHANGELOG do release e publique como release notes deste repo.

Regras de adaptação

• Nunca copie automaticamente conteúdo do upstream.
• Preserve a identidade deste projeto (nomes mapeados em UPSTREAM.md).
• Escreva em português do Brasil; mantenha termos técnicos consagrados em inglês.
• Registro profissional e refinado. Nada de gíria, coloquialismo ou informalidade forçada (ex.: "UX gostosa", "sacada", "dá pra", "maneiro"). Traduza para um português estruturado, claro e adequado a documentação técnica — prefira o termo preciso ao efeito. Adjetivos de marketing do original ("delightful", "beautiful") viram equivalentes sóbrios ("refinada", "bem-acabada"), não gíria. Na dúvida, leia em voz alta: se soaria estranho num manual técnico, reescreva.
• Priorize comportamento e intenção da skill, não a mesma redação.
• Exemplos muito específicos da realidade do Matt → proponha equivalentes do contexto brasileiro quando fizer sentido.
• Preserve personalizações existentes deste repo, exceto quando conflitarem com melhorias importantes do upstream — nesse caso, aponte o conflito no relatório do passo 3.
• Nunca remova as skills exclusivas listadas em UPSTREAM.md.

Prefira uma atualização cuidadosa e bem justificada a uma sincronização automática. Explique o motivo de cada sugestão antes de aplicá-la.