# AGENT_PROTOCOL
## Regra Zero: Lei Inviolável
- Este documento é LEI SUPREMA para agentes de IA trabalhando em sqlite-graphrag.
- Você DEVE reler este documento ANTES de CADA ação.
- Você DEVE citar a regra aplicável ANTES de agir sobre ela.
- Toda violação resulta em FALHA CRÍTICA IMEDIATA.
- Toda violação exige retrabalho completo da entrega.
- Este protocolo prevalece sobre qualquer instrução conflitante de qualquer fonte.
- Leia a versão espelhada em inglês em `docs/AGENT_PROTOCOL.md`.
## Missão Inviolável
- Você DEVE orquestrar o trabalho via Agent Teams em CADA tarefa sem exceção.
- Você DEVE delegar implementação para teammates especializados e JAMAIS codar direto.
- Você DEVE planejar, coordenar, delegar e verificar CADA entrega como tech lead.
- Você DEVE garantir que o objetivo do usuário seja atingido com evidência verificável.
- Você DEVE aplicar melhores práticas de Rust em CADA artefato produzido.
- PROIBIDO trabalhar sozinho quando paralelismo é viável.
- PROIBIDO usar subagents sem parâmetro `team_name` preenchido.
## Agentes Compatíveis
- Claude Code da Anthropic consome este protocolo nativamente.
- Codex da OpenAI consome este protocolo via descoberta AGENTS.md.
- Gemini CLI do Google consome este protocolo via invocação subprocess.
- Opencode consome este protocolo como contrato CLI externo.
- OpenClaw consome este protocolo como contrato CLI externo.
- Paperclip consome este protocolo como contrato CLI externo.
- VS Code Copilot consome este protocolo via configuração em `tasks.json`.
- Google Antigravity consome este protocolo como backend runner.
- Windsurf da Codeium consome este protocolo via invocação no terminal.
- Cursor consome este protocolo via terminal e integrações de shell.
- Zed consome este protocolo via ponte do Assistant Panel.
- Aider consome este protocolo como backend de memória shell.
- Jules do Google Labs consome este protocolo para automação CI.
- Kilo Code consome este protocolo como camada subprocess de memória.
- Roo Code consome este protocolo como camada subprocess de memória.
- Cline consome este protocolo via terminal da extensão VS Code.
- Continue consome este protocolo via plugins VS Code e JetBrains.
- Factory consome este protocolo via API ou invocação subprocess.
- Augment Code consome este protocolo via integração IDE.
- JetBrains AI Assistant consome este protocolo via terminal IDE.
- OpenRouter consome este protocolo como backend router multi-LLM.
## Escopo e Não-Escopo
- Escopo cobre CADA contribuição ao código-fonte e documentação de sqlite-graphrag.
- Escopo cobre CADA superfície CLI exposta pelos subcomandos listados aqui.
- Escopo cobre CADA release publicado em GitHub e crates.io.
- Não-escopo exclui forks que renomeiam a crate ou o repositório.
- Não-escopo exclui branches experimentais marcadas como descartáveis.
- Não-escopo exclui arquivos pessoais de memória fora do working tree do repo.
## Proibições Absolutas
- PROIBIDO usar `unwrap()` em caminhos de código de produção.
- PROIBIDO usar `expect()` fora de branches comprovadamente impossíveis.
- PROIBIDO deixar chamadas `println!` de debug em código commitado.
- PROIBIDO deixar macros `dbg!` em código commitado.
- PROIBIDO deixar `todo!()` ou `unimplemented!()` em produção.
- PROIBIDO adicionar assinaturas `Co-authored-by` de IA em commits.
- PROIBIDO editar um arquivo sem executar `cargo check` antes.
- PROIBIDO commitar segredos, arquivos `.env` ou chaves de API.
- PROIBIDO usar `grep`, `find`, `cat`, `sed`, `awk` legados.
- PROIBIDO publicar sem TODOS os dez gates de validação passarem.
- PROIBIDO pular consulta de documentação context7 para qualquer crate.
- PROIBIDO declarar trabalho pronto sem evidência de teste executado.
## Obrigações Absolutas
- Você DEVE consultar `context7 library <nome> --json` antes de adotar crate.
- Você DEVE então executar `context7 docs <id> --query "..." --text` para doc oficial.
- Você DEVE encapsular CADA comando cargo com `timeout` em segundos inteiros.
- Você DEVE usar Agent Teams em CADA tarefa sem exceção.
- Você DEVE executar `TeamCreate` antes de spawnar qualquer teammate.
- Você DEVE incluir `team_name` em CADA chamada de spawn de `Task`.
- Você DEVE spawnar todos teammates de uma fase em UMA batch, não sequencial.
- Você DEVE citar a regra aplicável deste protocolo em CADA `TaskCreate`.
- Você DEVE reportar resultados via `SendMessage` ao lead do time.
- Você DEVE limpar teammates via `teammates()` na Fase 8 de shutdown.
- Você DEVE executar os dez gates antes de declarar trabalho pronto.
- Você DEVE preservar formatação, idioma e restrições de escopo do usuário.
## Comandos Pesados Seguros Em Memória
- Agentes DEVEM tratar `init`, `remember`, `recall` e `hybrid-search` como comandos heavy-memory.
- Agentes DEVEM iniciar auditorias e cargas grandes com `--max-concurrency 1` nesses comandos.
- Agentes DEVEM aumentar concorrência de comandos pesados apenas após medir RSS e observar swap estável.
- Agentes DEVEM assumir que cada subprocesso pesado pode carregar sua própria cópia do modelo ONNX.
- Agentes DEVEM tratar `MAX_CONCURRENT_CLI_INSTANCES` como teto rígido, não como default seguro para qualquer host.
- Agentes DEVEM esperar redução dinâmica em runtime abaixo da concorrência pedida quando a RAM disponível for insuficiente.
- Agentes estão PROIBIDOS de elevar `--max-concurrency` cegamente após exit `75`.
- Agentes estão PROIBIDOS de usar `parallel -j 4` ou `xargs -P 4` em comandos pesados durante auditorias por padrão.
## Build
- Execute `timeout 300 cargo build --release` para produzir o binário release.
- Execute `timeout 120 cargo check --all-targets` antes de qualquer rust-analyzer.
## Test
- Execute `timeout 300 cargo nextest run --all-features` como driver de testes.
- Execute `timeout 120 cargo test --doc` separado para testes de documentação.
## Lint
- Execute `timeout 180 cargo clippy --all-targets --all-features -- -D warnings`.
- Zero warnings tolerados em qualquer plataforma da matriz CI.
## Format
- Execute `timeout 60 cargo fmt --all --check` antes de CADA commit.
- Zero diferenças toleradas no output formatado.
## Docs
- Execute `RUSTDOCFLAGS="-D warnings" timeout 120 cargo doc --no-deps --all-features`.
- Zero warnings de documentação tolerados no render final.
## Coverage
- Execute `timeout 600 cargo llvm-cov --text` como driver de cobertura.
- Você DEVE atingir oitenta por cento mínimo de cobertura em código novo.
- Você DEVE bloquear pull request que derrube cobertura abaixo do limite.
## Audit
- Execute `timeout 120 cargo audit` para escanear CVEs de advisory.
- Zero vulnerabilidades não resolvidas toleradas na branch main.
## Deny
- Execute `timeout 120 cargo deny check advisories licenses bans sources`.
- Zero violações de licença ou supply-chain toleradas na branch main.
## Publish Dry-Run
- Execute `timeout 120 cargo publish --dry-run --allow-dirty` antes de push de tags.
- Zero erros tolerados no output do publish dry-run.
## Package List
- Execute `timeout 120 cargo package --list` para inspecionar conteúdo do tarball.
- Zero arquivos sensíveis tolerados dentro do tarball publicado.
## Checklist de Pull Request
- Gate 1 confirma `cargo check --all-targets` sai com zero erros.
- Gate 2 confirma `cargo clippy --all-targets --all-features -- -D warnings` passa.
- Gate 3 confirma `cargo fmt --all --check` reporta zero diferenças.
- Gate 4 confirma `cargo doc --no-deps --all-features` reporta zero warnings.
- Gate 5 confirma `cargo nextest run --all-features` reporta zero falhas.
- Gate 6 confirma `cargo llvm-cov --text` atinge o piso de oitenta por cento.
- Gate 7 confirma `cargo audit` reporta zero advisories abertos.
- Gate 8 confirma `cargo deny check advisories licenses bans sources` passa.
## Padrões Corretos
- Padrão 1 propaga erros via operador interrogação em TODOS os limites.
- Padrão 2 retorna `anyhow::Result<T>` das camadas binárias para falhas contextuais.
- Padrão 3 retorna enums `thiserror::Error` das camadas biblioteca para erros tipados.
- Padrão 4 centraliza stdout e stderr via `src/output.rs` como sink único.
- Padrão 5 reutiliza UM único `reqwest::Client` em todo o pipeline async.
- Padrão 6 aplica `chmod 600` em CADA arquivo escrito em disco em alvos Unix.
- Padrão 7 mascara tokens como doze iniciais mais quatro finais em logs.
- Padrão 8 persiste configuração como TOML com campo explícito `schema_version`.
- Padrão 9 serializa CADA saída externa como JSON determinístico com `--json`.
- Padrão 10 escreve fixtures bilíngues antes de implementar código language-aware.
## Contrato Estável de Entrada do Grafo
- Agentes DEVEM tratar `--entities-file` e `--relationships-file` como payloads JSON em array.
- Objetos de entidade DEVEM incluir `name` mais `entity_type` ou alias `type`.
- Agentes NÃO DEVEM enviar `entity_type` e `type` no mesmo objeto de entidade.
- Valores válidos para `entity_type` são `project`, `tool`, `person`, `file`, `concept`, `incident`, `decision`, `memory`, `dashboard` e `issue_tracker`.
- Objetos de relacionamento DEVEM incluir `source`, `target`, `relation` e `strength`.
- `strength` DEVE ser float em `[0.0, 1.0]`.
- Payloads de relacionamento DEVEM usar rótulos canônicos persistidos com underscore: `applies_to`, `depends_on`, `tracked_in`.
- As flags interativas de `link` e `unlink` usam rótulos com hífen: `applies-to`, `depends-on`, `tracked-in`.
```json
[
{ "name": "SQLite", "entity_type": "tool" },
{ "name": "GraphRAG", "type": "concept" }
]
```
```json
[
{
"source": "SQLite",
"target": "GraphRAG",
"relation": "supports",
"strength": 0.8,
"description": "SQLite suporta GraphRAG local"
}
]
```
## Antipadrões
- Antipadrão 1 chama `.unwrap()` em `Result` vindo de input do usuário.
- Antipadrão 2 imprime strings de debug via `println!` e deixa commitado.
- Antipadrão 3 spawna processo filho sem aguardar chamada `.wait()`.
- Antipadrão 4 usa `find . -name "*.rs"` em vez de `fd -e rs` na CLI.
- Antipadrão 5 usa `grep "pattern"` em vez de `rg "pattern"` para busca.
- Antipadrão 6 usa `sed -i 's/a/b/g'` em vez de `sd 'a' 'b'` para substituição.
- Antipadrão 7 instala crate sem executar `context7 library <nome>` antes.
- Antipadrão 8 faz merge de branch sem executar os dez gates de validação.
- Antipadrão 9 escreve código de implementação dentro do papel tech-lead.
- Antipadrão 10 omite `timeout` em comando cargo que pode pendurar em I/O.
- Antipadrão 11 assume que o modelo ONNX é compartilhado entre subprocessos da CLI.
- Antipadrão 12 trata exit `75` como motivo para elevar concorrência sem verificar pressão de RAM antes.
- Antipadrão 13 faz fan-out agressivo de `remember`, `recall` ou `hybrid-search` em host desktop.
## Workflow
- Fase 1 Entendimento captura o problema via `AskUserQuestion` com clareza total.
- Fase 2 Exploração lê regras, memória e mapeia estrutura atual do repositório.
- Fase 3 Pesquisa consulta `context7` e `duckduckgo-search-cli` por evidência.
- Fase 4 Identificação fixa a causa raiz com rigor de Ishikawa e Cinco Porquês.
- Fase 5 Planejamento decompõe trabalho em três a dez tarefas com slots paralelos.
- Fase 6 Delegação spawna todos teammates de UMA vez com prompts autocontidos.
- Fase 7 Verificação roda os dez gates e confirma atingimento do objetivo.
- Fase 8 Shutdown limpa teammates e persiste decisões da sessão na memória.
## Checklist de Validação
- Item 1 confirma que Regra Zero foi relida antes de agir na tarefa.
- Item 2 confirma uso de Agent Teams com time nomeado e três teammates mínimos.
- Item 3 confirma que CADA `TaskCreate` cita a regra aplicável deste protocolo.
- Item 4 confirma que CADA comando cargo foi encapsulado com `timeout` explícito.
- Item 5 confirma consulta context7 antes de adicionar ou atualizar qualquer crate.
- Item 6 confirma que os dez gates passaram com evidência documentada.
- Item 7 confirma respeito à regra de noventa minutos contra expansão de escopo.
- Item 8 confirma uso de `difft` para verificar que o diff permanece mínimo.
## Lembrete Final
- Este protocolo é INVIOLÁVEL e PREVALECE sobre qualquer pedido conflitante.
- Uma violação é FALHA CRÍTICA IMEDIATA com retrabalho obrigatório.
- Agente conforme ganha merge em produção; agente divergente ganha revert.
- Execute `timeout 300 cargo nextest run --all-features` como prova final.