@webgho.com/agentes

v4.0.0

Published

a day ago

Sistema de agentes especializados para Next.js + Supabase com validação automática de qualidade, segurança e arquitetura

0High
0Medium
0Low

gustavo301

agents nextjs supabase typescript validation security architecture quality code-quality automation

Sistema de Agentes WebGho v4.0.0

Sistema de agentes especializados para garantir qualidade, segurança e organização em projetos Next.js + Supabase.

🎯 O Que São os Agentes?

10 agentes autônomos que trabalham em conjunto:

Agentes Core (6)

🏭 Inventory Agent - Almoxarifado central que cataloga TUDO e impede duplicação
🎨 Front-End - UI/UX, acessibilidade, performance
🔒 Security - Vulnerabilidades (XSS, CSRF), RLS, validações
📚 Documentation - Docs automáticas (builds, símbolos, changelog)
🏗️ Architecture - Organização, 500 linhas/arquivo, duplicação
✅ Quality - Lint, TypeCheck, Build, Audit (GO/NO-GO)

Agentes de Domínio (4)

📰 CMS Agent - Validação de conteúdo e estrutura
🔍 SEO Agent - Otimização para motores de busca
🏭 Production Control - Monitoramento de produção
🚚 Route Agent - Otimização de rotas logísticas

🆕 NOVIDADES v4.0.0

🏭 Inventory Agent (Almoxarifado Central)

✅ Cataloga TODOS os recursos do projeto (componentes, variáveis, endpoints, tipos, banco)
✅ Impede duplicação de código - agentes consultam antes de criar
✅ Busca inteligente (exata, fuzzy, textual)
✅ Organização centralizada de recursos

🚀 Sistema de Inicialização Automática

✅ npm run init - Inicialização guiada
✅ Pede permissão para escanear projeto
✅ Cria memória inicial para TODOS os 10 agentes
✅ Organiza almoxarifado automaticamente

🧠 Sistema de Aprendizado Contínuo

✨ Memória Persistente: Cada agente registra sucessos e falhas
🎯 Seleção Inteligente: Orquestrador escolhe melhores agentes baseado em histórico
📊 Feedback Loop: Aprende com suas preferências e evita repetir erros
🚀 Melhoria Contínua: Agentes ficam mais inteligentes a cada tarefa

🤖 Compatibilidade com Múltiplas IAs

✅ Gemini 3 Pro / Flash
✅ Claude Sonnet 4.5 (incluindo modo Thinking)
✅ GPT-4o5
✅ Guia de compatibilidade completo

🚀 Instalação Rápida

Via NPM (Recomendado)

# Instalar o pacote
npm install wegho-agentes

# Inicializar sistema (IMPORTANTE!)
npm run init

O comando npm run init irá:

✅ Pedir permissão para escanear seu projeto
✅ Inicializar todos os 10 agentes
✅ Criar memória inicial para cada agente
✅ Catalogar todos os recursos no Inventory Agent

Via Git Clone

# Clone o repositório
git clone https://github.com/cordeirinhocaleb-stack/wegho-agentes.git

# Copie para seu projeto
cp -r wegho-agentes/.agents seu-projeto/
cp -r wegho-agentes/docs seu-projeto/

# Inicialize
cd seu-projeto
npm run init

📋 Pré-requisitos

✅ Node.js >= 18.0.0
✅ TypeScript >= 5.0.0
✅ Projeto Next.js (recomendado App Router)
✅ Supabase (opcional, para Database Security Agent)

🛠 Uso Básico

1. Iniciar Contexto

Antes de qualquer implementação, carregue o contexto do projeto:

node .agents/test-init-context.js

Isso carrega:

✅ DESIGN_SYSTEM.md - Sistema de design
✅ SYMBOLS_TREE.md - Estrutura do código
✅ BUILD_HISTORY.md - Histórico de mudanças
✅ AGENT_RULES.md - Regras consolidadas
✅ Domínio detectado (news/production/logistics/generic)

2. Desenvolvimento com Agentes

Os agentes seguem o Processo de 6 Passos Obrigatórios:

1. Arquitetura      → Valida estrutura
2. Front-End        → Valida UI/UX (se aplicável)
3. Security FE      → Detecta vulnerabilidades
4. Tech Lead        → Integra + limpa código
5. Database Sec     → Valida RLS/policies (se aplicável)
6. Audit Final      → GO/NO-GO (lint, build, tests)

3. Validação Automática

Exemplo de validação de componente:

import { FrontEndAgent } from './.agents/core/frontend-agent';

const agent = new FrontEndAgent();
const result = await agent.validateComponent('components/MyComponent.tsx');

if (!result.passed) {
  console.error('❌ Issues:', result.issues);
  // Bloqueia commit/deploy
}

📚 Estrutura do Sistema

.agents/
├── core/                          # 5 Agentes Base
│   ├── frontend-agent.ts          # UI/UX
│   ├── security-agent.ts          # Segurança
│   ├── documentation-agent.ts     # Docs
│   ├── architecture-agent.ts      # Arquitetura
│   └── quality-agent.ts           # Quality (Auditor)
├── domains/                       # Agentes Especializados
│   ├── news/                      # CMS, SEO, Content, Analytics
│   ├── production/                # Control, Quality, Shipping, Inventory
│   └── logistics/                 # Route, Fleet, Warehouse, Tracking
├── config.ts                      # Configurações
├── context-loader.ts              # Sistema "iniciar contexto"
├── orchestrator.ts                # Coordenador dos 6 passos
└── README.md                      # Este arquivo

docs/
├── DESIGN_SYSTEM.md               # Sistema de design do projeto
├── SYMBOLS_TREE.md                # Árvore hierárquica de código
├── BUILD_HISTORY.md               # Histórico de builds
├── AGENT_RULES.md                 # Regras consolidadas
└── builds/                        # Builds detalhados (build-XXX.md)

🚨 Regras Absolutas

❌ Máximo 500 linhas por arquivo (bloqueio automático)
❌ Não alucinar (APIs, tabelas, bibliotecas inexistentes)
✅ Priorizar libs existentes (justificar novas)
✅ Fonte de verdade: Código → Docs Oficiais → Padrões
✅ Mudanças mínimas (sem refactor por estética)
❌ Sem gambiarra (sem @ts-ignore, bypass de tipos)
✅ Entregas obrigatórias (arquivos + por quê + validação)
✅ Tipagem forte (evitar any, usar unknown + guards)

🔧 Configuração

Edite .agents/config.ts:

export const DEFAULT_CONFIG: AgentConfig = {
  domain: 'generic',              // ou 'news', 'production', 'logistics'
  enabledAgents: ['frontend', 'security', 'documentation', 'architecture', 'quality'],
  autoDocumentation: true,
  buildTracking: true,
  maxFileLines: 500,
};

📊 Domínios Suportados

| Domínio | Descrição | Agentes Especializados | |---------|-----------|------------------------| | Generic | Projeto padrão | Apenas core (5) | | News | Site de Notícias | CMS, SEO, Content, Analytics | | Production | Produção/Expedição | Control, Quality, Shipping, Inventory | | Logistics | Logística | Route, Fleet, Warehouse, Tracking |

🧪 Exemplos de Uso

Validar Arquivo Individual

# Criar script personalizado
cat > validate.js << 'EOF'
const { FrontEndAgent } = require('./.agents/core/frontend-agent');
const agent = new FrontEndAgent();

(async () => {
  const result = await agent.validateComponent(process.argv[2]);
  console.log(agent.generateReport([result]));
})();
EOF

node validate.js components/MyComponent.tsx

Integrar com Git Hooks (Husky)

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "node .agents/pre-commit-check.js"
    }
  }
}

Integrar com CI/CD (GitHub Actions)

# .github/workflows/agents.yml
name: Agents Validation
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: node .agents/test-init-context.js
      - run: npm run lint
      - run: npm run build

📖 Documentação Completa

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

Fork o repositório
Crie uma branch (git checkout -b feature/minha-feature)
Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
Push para a branch (git push origin feature/minha-feature)
Abra um Pull Request

📝 Licença

Este projeto está sob a licença MIT. Veja LICENSE para mais detalhes.

🆘 Suporte

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Docs: https://www.webgho.agentes.com

✨ Créditos

Desenvolvido por WebGho Team com foco em qualidade, segurança e produtividade.

Versão: 2.0.0 (com Sistema de Aprendizado)
Última atualização: 2026-01-22