Shaelz/codebase-trellis-skill

Codebase Trellis

Estrutura, suporte e integração segura de mudanças de código assistidas por IA.

Ecossistema:

• codebase-orient entende a base de código.
• codebase-visualize mapeia a base de código.
• codebase-trellis suporta o crescimento e a integração segura de mudanças.

---

Quando usar esta habilidade

Use esta habilidade quando

• Arquivos foram alterados e precisam de staging seguro, planejamento de commit ou execução de commit.
• Um branch ou worktree precisa ser configurado, finalizado ou limpo.
• Um push, PR ou estado de CI precisa ser inspecionado ou preparado.
• A postura do repositório Git/GitHub precisa de uma auditoria.
• Uma sessão de agente de longa duração precisa de uma revisão de estado estruturada antes de continuar.
• A árvore de trabalho está suja e o próximo passo correto não está claro.

Pule esta habilidade quando

• A tarefa é uma correção pequena, de arquivo único, conhecida e sem incerteza de estado Git.
• Exploração somente leitura está sendo feita e nenhum trabalho de commit/push/limpeza está planejado.
• Outra habilidade (codebase-orient, codebase-visualize) foi invocada e nenhum trabalho Git se segue.

---

Classificação simples vs estruturada

Classifique cada invocação antes de executar qualquer fluxo de trabalho.

Passagem simples:

• correção de bug localizada
• mudança apenas de documentação ou cópia
• atualização de dependência
• pequena refatoração
• mudança apenas de teste
• preparação de commit já escopo

Passagem estruturada:

• mudança ampla em vários arquivos
• múltiplos pacotes
• UI mais API mais testes
• migração ou arquivos gerados
• trabalho de agente de longa duração
• múltiplos commits esperados
• retomada ou handoff provável

Padrão para simples quando estiver em dúvida. Promova para estruturado se a inspeção provar que o trabalho é maior do que parecia. Nunca rebaixe de estruturado depois que o estado de segurança foi estabelecido.

---

Camadas de aplicação

O Trellis opera dentro de um modelo de segurança de 4 camadas. Essas camadas não são equivalentes e nenhuma camada substitui outra.

Camada 1: Disciplina da habilidade (camada principal v1)

A habilidade inspeciona, relata e bloqueia operações arriscadas. Funciona em qualquer repositório Git normal sem hooks extras ou acesso ao GitHub. Isso é comportamental -- depende do agente seguir a habilidade.

Camada 2: Hooks locais do Git

Hooks locais do repositório podem ser executados durante commit ou push. O Trellis pode recomendar hooks, mas não os exige nem instala na v1. Hooks podem estar ausentes, ser ignorados com --no-verify ou não ser compartilhados entre clones.

Camada 3: Hooks do Claude Code

Hooks em nível de host podem atuar em torno do uso de ferramentas, mudanças de arquivos e permissões. Endurecimento opcional apenas -- não necessário para o núcleo independente. Não presuma que estão instalados.

Camada 4: Proteções do GitHub

Imposição do lado do GitHub: proteção de branch, conjuntos de regras, verificações obrigatórias, revisões obrigatórias, commits assinados, restrições de force push, fila de merge, varredura de segredos, varredura de código, Dependabot. Inspecione e relate quando o acesso à API permitir; nunca presuma que as proteções existem.

Regra de não equivalência:

• Disciplina da habilidade não é um hook.
• Um hook local não é proteção de branch do GitHub.
• Um grep local bem-sucedido não é varredura de segredos.
• Verificações de cabeça de PR não são verificações de fila de merge.
• Uma marca de seleção verde visível não é prova de que todas as verificações obrigatórias passaram para o SHA relevante.

Se uma camada estiver indisponível ou não verificada, diga isso claramente.

---

Limite de interoperabilidade

Núcleo independente

O Codebase Trellis deve funcionar em qualquer repositório Git normal sem exigir artefatos de habilidades irmãs. Ele possui:

• Inspeção de status Git e estado sujo
• Detecção de mudanças staged, unstaged, untracked, ignoradas, geradas, sensíveis e pré-existentes
• Agrupamento de commits e handoff de plano de commit
• Segurança de branch/worktree
• Portões de push/PR/CI
• Regras de limpeza
• Saída do relatório Trellis

Leituras consultivas opcionais

Se artefatos de habilidades irmãs existirem, o Trellis pode lê-los apenas como contexto consultivo.

Do codebase-orient (exemplos: docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, docs/ai/OPEN_QUESTIONS.md):

• layout do repositório e estrutura de pacotes/workspaces
• verificações conhecidas e política de documentos gerados
• convenções importantes e zonas de perigo

Do codebase-visualize (exemplos: docs/ai/visualize/codebase-graph.json):

• raio de explosão e módulos afetados
• arestas de docs para código e arquivos de alta centralidade

Regras:

• Não exija esses arquivos.
• Não os regenere.
• Não os modifique silenciosamente.
• Não bloqueie o planejamento de commit de rotina porque a visualização está ausente.
• Não os trate como mais autoritativos do que a fonte/config/documentos canônicos.

Gatilhos de handoff

• Sugira /codebase-orient quando a estrutura do repositório não estiver clara, as verificações conhecidas forem desconhecidas ou o agente não tiver contexto suficiente para classificar o risco.
• Sugira /codebase-visualize quando o impacto da mudança for amplo ou arquitetônico, as relações de dependência importarem ou o raio de explosão melhorar a decisão.

---

Regras universais

Sempre:

1. Comece identificando a raiz do repositório, branch e estado sujo.
2. Mostre o estado antes de propor comandos.
3. Separe arquivos staged, unstaged, untracked, deletados e ignorados.
4. Trate arquivos parcialmente staged como ambíguos e arriscados.
5. Exclua arquivos sensíveis de todos os planos de commit.
6. Prefira listas exatas de arquivos em vez de comandos de caminho amplo.
7. Pare em caso de falha de comando.
8. Diga quando gh estiver indisponível ou sem permissão.
9. Mantenha os relatórios curtos e acionáveis.
10. Relate o que é conhecido e o que é desconhecido; não transforme desconhecidos em segurança assumida.

Nunca:

1. Execute git add . sem aprovação explícita da lista exata de arquivos.
2. Faça commit sem mostrar os arquivos planejados e a mensagem de commit.
3. Faça push como parte do commit.
4. Faça merge como parte do push.
5. Use git push --force.
6. Infira --force-with-lease; ele deve ser explicitamente solicitado.
7. Delete branches sem confirmação digitada do nome do branch.
8. Remova worktrees não criados por esta sessão ou não claramente worktrees descartáveis de projeto local.
9. Inclua .env, chaves, tokens, credenciais ou arquivos ignorados em um plano de commit.
10. Afirme que testes, CI ou configurações do GitHub passaram, a menos que verificado.
11. Afirme "nenhum segredo" ou "nenhuma vulnerabilidade" apenas com base em um grep local ou verificações visíveis.
12. Relate CI como verde a menos que o SHA relevante e as verificações obrigatórias sejam ambos conhecidos.
13. Inclua silenciosamente arquivos sujos pré-existentes.
14. Inclua silenciosamente arquivos não rastreados.

---

Portões de risco

Somente leitura -- nenhuma aprovação necessária:

• git status, git diff --stat, git log, git remote -v
• gh pr view, gh run list, gh repo view
• Qualquer comando de inspeção ou diagnóstico que não altere o estado

Baixa mudança de estado -- plano visível e aprovação necessária no modo execute:

• Criar branch local
• Criar worktree local
• Stage arquivos explicitamente listados
• Criar commit a partir de plano aprovado

Alta mudança de estado -- aprovação explícita necessária:

• Push (qualquer branch)
• Criar PR
• Fazer merge de branch
• Rebase de branch
• Editar proteção de branch ou conjuntos de regras
• Deletar branch
• Remover worktree

Perigoso -- confirmação digitada e prefira gerar comandos a executar:

• Push para branch protegido (requer nome do branch digitado)
• Push --force-with-lease (deve ser explicitamente solicitado)
• git reset --hard
• git clean -fd ou qualquer remoção de arquivo não rastreado
• Deletar branch com commits não mesclados
• Reescrever histórico público
• Remediação de histórico de segredos

git push --force é sempre proibido.

---

Padrões de arquivos sensíveis

Nunca inclua estes em um plano de commit. Se o usuário substituir após um aviso, avise novamente e recomende contra.

.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json

Também exclua: arquivos ignorados, saída de build, caches e pastas de dependência, a menos que o repositório os rastreie intencionalmente.

Exclusões comuns:

node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc

---

Limite de visibilidade de segurança

O Trellis pode relatar sinais de segurança visíveis. O Trellis não é um scanner de segurança completo.

Relate quando visível:

• arquivos com formato de segredo no diff local (nomes de arquivos ou padrões correspondentes a .env, *.key, etc.)
• se a varredura de segredos do GitHub e a proteção push parecem habilitadas
• se CodeQL ou varredura de código está configurada
• se alertas Dependabot ou atualizações de segurança estão visíveis
• se arquivos de dependência foram alterados neste diff

Nunca afirme:

• "nenhum segredo encontrado" apenas porque um grep local não encontrou nada
• "nenhuma vulnerabilidade" apenas porque as verificações visíveis do GitHub estão verdes
• que a postura de segurança está limpa, a menos que verificado por meio de uma ferramenta de segurança dedicada

---

Limite de visibilidade GitHub/CI

Relate o que pode e não pode ser verificado. Não transforme estado de proteção desconhecido em segurança assumida.

Modos de CI são perguntas diferentes -- não os confunda:

Prontidão de nível de PR:

• Este PR está pronto para merge?
• As verificações obrigatórias estão passando para este SHA?
• Verificações pendentes, ignoradas ou canceladas são relevantes?

Inspeção de execução de fluxo de trabalho:

• Por que esta execução falhou?
• Qual job ou etapa falhou?
• Logs ou artefatos estão disponíveis?

Estado de proteção do GitHub -- relate um de:

• Estado de proteção: verificado -- <resumo do que foi encontrado>
• Estado de proteção: não verificado. Não presuma que main está protegido.

Fila de merge -- se uma fila de merge for necessária, as verificações de cabeça de PR não são o sinal final. Relate separadamente:

• verificações de cabeça de PR
• verificações obrigatórias
• verificações de fila de merge ou grupo de merge, se presentes
• se o SHA verificado corresponde ao commit sendo discutido

Nunca adicione à fila de merge, habilite auto-merge ou faça merge sem aprovação explícita do usuário.

---

Relatório Trellis

O relatório Trellis é a saída característica de cada passagem de inspeção ou planejamento.

Forma completa

Relatório Trellis

Verificação de raiz
- Raiz do repositório:     <diretório de trabalho atual; se for um worktree vinculado, este é o caminho do worktree>
- Repositório principal:   <raiz do repositório pai, derivado de GIT_COMMON se for um worktree vinculado; omita se não for um worktree vinculado>
- Branch:
- Remoto/upstream:
- Estado do worktree: <worktree vinculado em <caminho> / checkout do repositório principal / HEAD destacado>
- Estado de identidade/assinatura:
- Arquivos sujos de linha de base (pré-existentes):

Verificação de emaranhado
- Mudanças staged:
- Mudanças unstaged:
- Arquivos não rastreados:
- Arquivos ignorados/gerados de nota:
- Arquivos com aparência sensível:
- Arquivos parcialmente staged:
- Preocupações mistas:

Plano de crescimento
- Grupos de mudança sugeridos:
- Limites de commit sugeridos:
- Forma de PR sugerida:
- Arquivos excluídos do escopo:
- Arquivos que exigem decisão do usuário:

Verificação de portão
- Seguro inspecionar/ler: sim
- Requer aprovação antes do staging:
- Requer aprovação antes do commit:
- Requer aprovação antes do push:
- Requer aprovação antes do merge/auto-merge:
- Requer aprovação antes de limpeza/delete:

Verificação de dossel
- Visibilidade do repositório/PR do GitHub:
- Verificações obrigatórias:
- Estado da CI e SHA verificado:
- Estado de proteção de branch/conjunto de regras:
- Estado da fila de merge:
- Sinais de segurança visíveis:
- Desconhecidos/proteções não verificadas:

Próxima ação segura
- Recomendação:
- Comandos exatos (somente leitura, ou com anotação de portão):
- Decisão necessária do usuário:

Forma curta

Use para passagens simples ou árvores de trabalho pequenas.

Relatório Trellis
- Raiz: <resumo do repositório / branch / worktree>
- Emaranhado: <resumo de staged / unstaged / não rastreados / sensíveis / preocupação mista>
- Crescimento: <recomendação de agrupamento de commit/PR>
- Portões: <operações que exigem aprovação>
- Dossel: <estado de GitHub/CI/proteção se conhecido, ou "não verificado">
- Próximo: <uma ação segura seguinte>

Forma de parada

Use quando o Trellis não pode ou não deve continuar.

Parada Trellis
- Motivo da parada:
- Evidência:
- Risco se ignorado:
- Opções seguras de recuperação:
- Opção recomendada:

Os motivos de parada incluem:

• Arquivo com aparência sensível seria staged.
• Arquivo sujo pré-existente seria incluído silenciosamente.
• Arquivo parcialmente staged torna a intenção ambígua.
• O branch de destino é protegido ou desconhecido e um push/merge foi solicitado.
• Uma operação semelhante a force foi solicitada sem aceitação explícita de risco.
• O estado de push ou CI alegado se refere a um SHA diferente.
• Outro branch, worktree ou PR parece possuir a mesma tarefa.

---

Roteamento de modo

Leia $ARGUMENTS.

Se nenhum modo for fornecido, execute audit.

Modos suportados:

• audit: revisão de postura local do Git e GitHub somente leitura
• start: prepare trabalho isolado usando um branch ou worktree
• commit: planeje ou execute commits coesos
• push: prepare ou execute push e monitoramento de CI
• finish: finalize o branch através de PR, merge local, manter ou descartar
• recover: recupere-se de erros do Git

---

Modo audit

Execute diagnósticos somente leitura. Produza um relatório Trellis. Nunca modifique nenhum estado local ou remoto.

Pré-verificação de auditoria -- Git local

Sempre execute primeiro, independentemente da disponibilidade do gh:

git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: not a git repo"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "unset"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "unset"
git config commit.gpgsign 2>/dev/null || echo "unset"

Pré-verificação de auditoria -- verificações de arquivos da comunidade

Verifique a presença/ausência de cada arquivo localmente. Presença/ausência é um fato verificado; qualidade do conteúdo não é:

test -f README.md && echo "present" || echo "absent"
test -f LICENSE && echo "present" || echo "absent"
test -f SECURITY.md && echo "present" || echo "absent"
test -f CODE_OF_CONDUCT.md && echo "present" || echo "absent"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "present" || echo "absent"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "present" || echo "absent"
test -d .github/ISSUE_TEMPLATE && echo "present" || echo "absent"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "present" || echo "absent"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "present" || echo "absent"
test -d .github/workflows && echo "present" || echo "absent"

Postura do GitHub -- portão de disponibilidade

Antes de executar qualquer comando gh:

1. Verifique se um remoto GitHub está presente: git remote -v | grep github.com
2. Verifique se gh está disponível: gh auth status 2>/dev/null

Se nenhum remoto GitHub for detectado: relate todos os campos de postura do GitHub como indisponível -- remoto não-GitHub.

Se gh estiver indisponível