agent-verify

O que agent-verify faz?

Torne a coisa que você constrói verificável pelo mecanismo mais barato que possa falsificá-la. Verifique via CLI por padrão. O modelo deve ler ~20 tokens (PASS / FAIL: linha), nunca um dump de DOM ou uma screenshot.

A única regra

Use o mecanismo mais leve que pode provar que uma funcionalidade está errada. Escalone apenas quando ele não conseguir.

assert in-process  →  CLI / curl + código de saída  →  teste de banco (TAP)  →  navegador headless (visual apenas, último)
   mais barato                                                            mais caro

90% do que os agentes constroem (lógica, dados, contratos de API, fluxos) é verificável sem navegador. Reserve o navegador para pixels.

Loop (por funcionalidade)

1. Detecte uma vez. Execute scripts/detect-stack.sh. Ele imprime o executor de testes e o stack em algumas linhas. Não imponha um novo framework — use o que já existe.
2. Construa a funcionalidade.
3. Escreva UM cheque token-mínimo usando o primitivo in-process / CLI do stack (veja reference/stacks/). O cheque deve imprimir PASS ou uma única linha FAIL: — nunca dumps.
4. Adicione uma linha ao VERIFICATION_MAP.md: funcionalidade | comando | sinal-de-passagem. Este é o contrato que o agente lerá na próxima vez.
5. Execute scripts/verify.sh [funcionalidade] e leia apenas o resultado. Edite → verifique → repita com base no resultado, não nos logs.

O que NÃO fazer

• Não use Playwright/navegador para verificar lógica, dados ou respostas de API. Esse é o vazamento de tokens que esta skill existe para parar.
• Não prescreva um ritual TDD. Mostre qual verificação prova esta funcionalidade, não um procedimento. (Procedimento sem contexto direcionado, de forma mensurável, sai pela culatra — veja reference/patterns.md.)
• Não retorne saída bruta para o contexto. Filtre no sandbox, exiba o resultado. (console.log(resultado), não as 10 mil linhas.)
• Não deixe as verificações crescerem. Uma funcionalidade, uma verificação determinística rápida. Mantenha VERIFICATION_MAP.md curto — mapas curtos superam os longos.

Contrato de saída (sempre)

PASS auth-login
FAIL create-invoice: esperado 201, recebido 500

Saída 0 = tudo passou. Diferente de zero = algo falhou. Isso é tudo que o modelo precisa.

Quando o navegador for inevitável

Apenas para UI genuinamente visual (layout, estilo, regressão visual) e apenas bem no final. Mesmo assim: uma execução headless, retorne um PASS/FAIL ou um veredito de diff — nunca uma screenshot completa ou DOM dentro do contexto. Veja reference/stacks/nextjs.md.

Arquivos

• scripts/detect-stack.sh — imprime o stack + executor, token-mínimo.
• scripts/verify.sh — executa as verificações mapeadas, emite apenas PASS/FAIL + linha de falha.
• VERIFICATION_MAP.md — o mapa curto funcionalidade→comando (o agente o mantém).
• reference/stacks/ — receitas copie-e-cole: FastAPI (TestClient in-process), Supabase (seed + reset + pgTAP), Next.js (manipuladores de rota + último recurso visual).
• reference/patterns.md — padrões de verificação token-mínima + as evidências por trás deles.
• reference/anti-patterns.md — testes instáveis, PASS falso, proteções de engenharia excessiva.
• templates/ — pontos de partida para o mapa, um teste FastAPI, um seed Supabase.