code-compass

Planejar e manter documentação técnica do projeto (README, quickstart, ADRs, docs internas, exemplos de tool calls e troubleshooting) alinhada ao código; usar quando o pedido exigir clareza documental e não usar para implementar lógica de runtime ou infraestrutura.

Definir e validar decisões arquiteturais cross-cutting no Code Compass (Node/NestJS MCP Server, Python Indexer/Worker, Qdrant e Docker Compose), incluindo contratos, boundaries, rollout/rollback, performance, segurança e operabilidade; usar quando houver mudança estrutural ou risco irreversível e não usar para bugfix local, refactor restrito, UI/estilo ou documentação editorial sem impacto arquitetural.

Planejar e implementar mudanças na camada vetorial Qdrant (collections, distance metric, vector size, payload filters, upsert/delete e migração de schema); usar quando o pedido tocar modelagem ou operação de vetor e não usar para lógica do indexador, handlers MCP, infra geral ou documentação.

Planejar e implementar mudanças no indexador Python (chunking, embeddings, indexação full/incremental, IDs de chunk e payload rico); usar quando o pedido tocar `apps/indexer` ou pipeline RAG de ingestão e não usar para handlers MCP, schema Qdrant, infra ou documentação.

Executar testes de mudança específica no Code Compass com reprodução de bug antes/depois, testes de regressão unit/integration/e2e, smoke suite e evidências objetivas de validação quando houver bugfix, mudança de contrato API, indexação/busca, schema/payload Qdrant, UX crítica ou pipeline de ingestão; não usar para governança transversal de qualidade/CI/gates e política global de cobertura (usar `developer-quality`), nem para mudanças só de doc/markdown, renome sem efeito, cosmética visual, arquitetura ou refactor sem bug/feature.

Governar qualidade técnica transversal do Code Compass (gates de entrega, política de testes/contratos, lint, typecheck, cobertura e estabilidade de CI) quando o objetivo principal for elevar confiabilidade sistêmica entre módulos; não usar para bugfix com repro antes/depois, regressão localizada de mudança pontual ou smoke e2e de alteração específica (usar `developer-tester`) nem para implementação de feature de domínio.

Planejar e implementar mudanças no servidor MCP em Node/NestJS (tools, handlers, validação, allowlist, contratos de retorno com evidência e performance P95); usar quando o pedido tocar `apps/mcp-server` ou integração MCP e não usar para indexação Python, schema Qdrant, infra ou documentação.

Planejar e implementar mudanças de infraestrutura local e operacional (docker-compose, env vars, make targets, bootstrap, logs e métricas) para o Code Compass; usar quando o pedido tocar execução/observabilidade e não usar para lógica de MCP, indexação, modelagem vetorial ou documentação editorial.