Initial SeConectai briefing system

2026-10-04 10:42:23 -03:00
commit 45cd8d2f03
163 changed files with 12659 additions and 0 deletions
@@ -0,0 +1,260 @@
+# Vibe Frontend Agents — Orquestrador Principal
+
+Este arquivo é a fonte central de regras para qualquer IA/agente que trabalhe neste projeto.
+Ele deve ser lido **antes de qualquer alteração**. Os arquivos em `agents/`, `skills/`, `prompts/`
+e `checklists/` complementam estas instruções e devem ser carregados conforme a tarefa.
+
+---
+
+## 1. Missão
+
+Melhorar ou construir interfaces sem comprometer regras de negócio, integrações, autenticação,
+segurança, dados, contratos de API ou estabilidade do sistema.
+
+O objetivo não é apenas “deixar bonito”. O objetivo é produzir uma interface:
+- clara;
+- coerente;
+- acessível;
+- responsiva;
+- rápida;
+- reutilizável;
+- testável;
+- previsível;
+- simples de manter;
+- segura para evoluir.
+
+---
+
+## 2. Regra de ouro: analisar antes de modificar
+
+Antes de editar qualquer arquivo de um projeto existente:
+
+1. Identifique a stack, framework, gerenciador de pacotes e processo de build.
+2. Mapeie a estrutura de pastas e responsabilidades principais.
+3. Identifique rotas, layouts, componentes, hooks/composables, stores, serviços e estilos.
+4. Localize autenticação, autorização, chamadas de API, contratos de dados e integrações.
+5. Verifique se existe design system ou biblioteca de componentes já adotada.
+6. Verifique lint, typecheck, testes, Storybook, E2E e comandos de validação.
+7. Entenda exatamente o escopo solicitado pelo usuário.
+8. Determine quais agentes especializados realmente precisam participar.
+9. Só então altere o código.
+
+Nunca reescreva grandes partes do projeto apenas porque uma solução diferente parece mais elegante.
+
+---
+
+## 3. Proteção obrigatória do sistema
+
+Quando a solicitação for de frontend, UI, UX, responsividade, acessibilidade, SEO ou performance,
+NÃO altere os itens abaixo sem necessidade técnica real e autorização explícita:
+
+- banco de dados;
+- migrations;
+- seeds;
+- entidades persistidas;
+- schemas de banco;
+- contratos públicos de API;
+- endpoints;
+- controllers do backend;
+- services de regra de negócio;
+- autenticação;
+- autorização;
+- roles e permissões;
+- tokens, sessões e cookies de segurança;
+- webhooks;
+- filas;
+- workers;
+- integrações externas;
+- configuração de infraestrutura;
+- deploy;
+- Docker/Compose/Kubernetes;
+- DNS;
+- variáveis de ambiente reais;
+- segredos;
+- CI/CD.
+
+### Exceção
+
+Se a alteração de frontend exigir mudança em uma dessas áreas:
+1. não faça a alteração silenciosamente;
+2. explique a dependência;
+3. proponha a menor mudança possível;
+4. preserve compatibilidade retroativa quando viável;
+5. só implemente se a tarefa autorizar.
+
+---
+
+## 4. Arquivos que devem ser carregados por tipo de tarefa
+
+### Toda tarefa em projeto existente
+Leia primeiro:
+- `agents/00-project-analyzer.md`
+- `agents/01-codebase-guardian.md`
+
+### UI/UX ou melhoria visual
+Leia:
+- `agents/02-ui-ux.md`
+- `agents/03-design-system.md`
+- `agents/04-frontend.md`
+
+### Formulários, cadastro, edição, filtros ou autenticação
+Leia também:
+- `agents/05-forms.md`
+
+### Tabelas, painéis, ERP, CRM, SaaS administrativo
+Leia também:
+- `agents/06-dashboard.md`
+
+### Site institucional, landing page, página comercial
+Leia também:
+- `agents/07-landing-page.md`
+- `agents/10-seo.md`
+
+### Mobile/responsividade
+Leia:
+- `agents/08-responsive.md`
+
+### Acessibilidade
+Leia:
+- `agents/09-accessibility.md`
+
+### Performance
+Leia:
+- `agents/11-performance.md`
+
+### Revisão final
+Leia sempre ao finalizar alteração relevante:
+- `agents/12-visual-qa.md`
+- `agents/13-regression-check.md`
+
+---
+
+## 5. Pipeline padrão
+
+### Fase A — Descoberta
+1. Ler este `AGENTS.md`.
+2. Ler `00-project-analyzer.md`.
+3. Ler `01-codebase-guardian.md`.
+4. Inspecionar o projeto.
+5. Registrar stack, arquitetura, riscos e escopo.
+
+### Fase B — Planejamento
+1. Classificar a tarefa.
+2. Selecionar somente os agentes necessários.
+3. Identificar componentes afetados.
+4. Identificar dependências e riscos de regressão.
+5. Elaborar um plano mínimo de mudança.
+
+### Fase C — Implementação
+1. Reutilizar padrões existentes.
+2. Alterar o menor número razoável de arquivos.
+3. Preservar contratos existentes.
+4. Tratar estados de UI.
+5. Evitar duplicação.
+6. Não adicionar dependências sem justificativa.
+
+### Fase D — Validação
+1. Build.
+2. Typecheck.
+3. Lint.
+4. Testes disponíveis.
+5. Navegação principal.
+6. Mobile e desktop.
+7. Estados loading/erro/vazio/sucesso.
+8. Acessibilidade básica.
+9. Console sem erros relevantes.
+10. Revisão visual.
+11. Checagem de regressão.
+
+### Fase E — Entrega
+Explique:
+- o que foi alterado;
+- por que foi alterado;
+- arquivos principais envolvidos;
+- validações executadas;
+- riscos ou limitações restantes;
+- sugestões opcionais, sem misturá-las ao escopo concluído.
+
+---
+
+## 6. Seleção inteligente de agentes
+
+Não execute todos os especialistas mecanicamente.
+
+Exemplos:
+- Ajuste de espaçamento em um componente: analyzer + guardian + frontend + visual QA.
+- Página de cadastro: analyzer + guardian + UI/UX + design system + frontend + forms + responsive + accessibility + regression.
+- Dashboard: analyzer + guardian + UI/UX + design system + frontend + dashboard + responsive + accessibility + performance + regression.
+- Landing page: analyzer + guardian + UI/UX + design system + frontend + landing page + responsive + accessibility + SEO + performance + visual QA.
+
+---
+
+## 7. Regras de implementação
+
+### Preserve o que já existe
+- Não renomeie arquivos ou componentes sem benefício claro.
+- Não troque framework, biblioteca ou padrão arquitetural sem solicitação.
+- Não converta JS para TS, CSS para Tailwind, Redux para Zustand etc. como efeito colateral.
+- Não faça “limpeza geral” fora do escopo.
+
+### Dependências
+Antes de instalar uma dependência:
+1. verifique se o projeto já oferece solução equivalente;
+2. verifique se a plataforma/framework tem recurso nativo;
+3. avalie custo de bundle e manutenção;
+4. justifique a instalação.
+
+### Componentização
+Crie componente quando houver pelo menos um destes motivos:
+- reutilização real;
+- responsabilidade visual/funcional clara;
+- redução de complexidade;
+- necessidade de teste isolado;
+- padronização de comportamento.
+
+Não crie componentes microscópicos sem ganho prático.
+
+---
+
+## 8. Estados obrigatórios de interface
+
+Sempre que aplicável, considere:
+- inicial;
+- carregando;
+- sucesso;
+- vazio;
+- erro;
+- sem permissão;
+- indisponível;
+- ação em andamento;
+- ação concluída;
+- confirmação antes de ação destrutiva.
+
+Nunca exiba uma tela quebrada apenas porque uma API retornou array vazio ou falhou.
+
+---
+
+## 9. Regras de dados
+
+- Não invente métricas reais.
+- Não fabrique dados de produção.
+- Não altere valores financeiros, permissões ou status de negócio para fins visuais.
+- Diferencie mock, fixture e dado real.
+- Respeite locale, moeda, fuso e formatação existente.
+- Não exponha secrets ou tokens no frontend.
+
+---
+
+## 10. Critério de pronto
+
+Uma alteração só pode ser considerada concluída quando:
+- atende exatamente ao pedido;
+- funcionalidade existente continua funcionando;
+- não alterou regra de negócio indevidamente;
+- desktop e mobile foram considerados;
+- estados relevantes foram tratados;
+- acessibilidade básica foi verificada;
+- build/typecheck/lint/testes aplicáveis passam, ou falhas preexistentes foram documentadas;
+- não existem erros novos óbvios no console;
+- o código segue padrões do projeto;
+- o resultado é sustentável para manutenção.