governance-agent: auditoria de governança como CLI local

Conforme você cria mais agentes no OpenCode, manter consistência entre eles vira um problema. Cada agente pode ter uma estrutura diferente, metadados faltando ou instruções incompletas. O governance-agent resolve isso — e agora também audita qualquer repositório com um comando.

O que ele faz

O validador percorre todos os agentes em ~/.config/opencode/agents/ e verifica 6 dimensões:

• Estrutura: arquivo existe e tem os campos obrigatórios (name, instructions, tools)
• Metadados: description, version e author presentes
• Instruções: arquivo de instruções existe e não está vazio
• Tools: todas as ferramentas listadas são conhecidas
• Polyfill: agentes com polyfill de ferramentas têm o script correspondente
• Cross-ref: ferramentas referenciadas por outros agentes existem

Auditoria como CLI local

Além do validador, o projeto agora inclui um wrapper governance que roda o agente de auditoria em qualquer repositório via OpenCode e salva o relatório em Markdown:

# Instalar o agente no OpenCode (ou Codex CLI com --codex)
./governance install

# Auditar repositório atual (escopo completo)
./governance audit .

# Auditar subdiretório com escopo restrito
./governance audit ./api "só segurança"

# Saída direta no terminal (sem arquivo)
./governance audit . --stdout | less -R

# Especificar modelo
./governance audit . --model openai/gpt-5

O agente cobre 5 domínios de governança:

| Domínio | O que verifica | |---------|----------------| | Licenças | Compatibilidade, LICENSE ausente, deps sem licença | | Dependências | Desatualizadas, deprecated, duplicadas, lockfiles | | Padrões de Código | Linter, formatação, type hints, código morto | | Segurança | Secrets vazados, .env no .gitignore, CVEs | | Arquitetura | SRP, tamanho de arquivos, acoplamento, testes |

Cada achado traz arquivo:linha exatos e um checklist priorizado (Must fix / Should fix / Nice to have).

Multi-ferramenta

O governance-agent suporta validar agentes de qualquer ferramenta OpenCode — não apenas do general. Basta configurar as tools válidas no config.yml:

valid_tools:
  general: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebSearch", "WebFetch"]
  custom: ["Read", "Write", "Bash"]

CI/CD integrado

O projeto já vem com GitHub Actions configurado: a cada push para main, roda os validadores e os testes (pytest), e em caso de sucesso gera automaticamente uma nova tag + release.

pytest -v --tb=short

Usando na prática

python src/validate_agent.py

A saída mostra cada agente validado, com checkmarks e indicadores de aprovado/reprovado em cada validador.

O código completo está no repositório: github.com/n8nfelipe/governance-agent.