# 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.