Sistema de Agentes WebGho v6.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?

20+ agentes autônomos que trabalham em conjunto:

Agentes Core (6)

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

Novos Agentes Especializados (12)

• Web: NextJS, UIUX, Frontend
• Backend: API, Database (Postgres/Prisma)
• Security: Pentest, Security
• DevOps: Cloud, DevOps (Docker/CI)
• AI: AI Agents, RAG
• Tools: Automation, CRO, Testing

🆕 NOVIDADES v5.0.0

🤖 20+ Agentes Especializados

• ✅ Cobertura Total: De frontend a DevOps, cada área tem um especialista
• ✅ Roteamento Inteligente: TaskAnalyzer detecta qual agente usar
• ✅ Skills Integradas: 200+ skills (melhores práticas) carregadas sob demanda

📦 Sistema de Build Incremental

• ✅ Builds Automáticos: Criados após cada sucesso
• ✅ Snapshots: Histórico arquivo-por-arquivo
• ✅ Restore: Volte para qualquer versão anterior
• ✅ Rastreabilidade: Saiba exatamente quem mudou o que

🧠 Memória Individual

• ✨ Cérebro Próprio: Cada agente tem sua memória persistente
• 🎯 Aprendizado: Agentes lembram de sucessos e evitam erros passados
• 📊 Feedback: Sistema de auto-melhoria contínua

🚀 Automação Completa

• ✅ npm run agent "tarefa" - Só pedir e o sistema orquestra tudo

🚀 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á:

1. ✅ Pedir permissão para escanear seu projeto
2. ✅ Inicializar todos os 10 agentes
3. ✅ Criar memória inicial para cada agente
4. ✅ 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)

📂 Onde Ficam os Arquivos do Sistema?

Todos os arquivos gerados pelo sistema ficam isolados dentro do pacote wegho-agentes:

node_modules/wegho-agentes/
├── .agents/          # Código dos agentes
├── .system/          # Dados gerados (isolado)
│   ├── builds/       # Histórico de builds
│   ├── checkpoints/  # Pontos de restauração
│   ├── reports/      # Relatórios de execução
│   └── logs/         # Logs de debug
└── docs/             # Documentação

Seu projeto permanece limpo! ✨
Apenas .clinerules e .cursorrules ficam na raiz do seu projeto.

🛠 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

1. ❌ Máximo 500 linhas por arquivo (bloqueio automático)
2. ❌ Não alucinar (APIs, tabelas, bibliotecas inexistentes)
3. ✅ Priorizar libs existentes (justificar novas)
4. ✅ Fonte de verdade: Código → Docs Oficiais → Padrões
5. ✅ Mudanças mínimas (sem refactor por estética)
6. ❌ Sem gambiarra (sem @ts-ignore, bypass de tipos)
7. ✅ Entregas obrigatórias (arquivos + por quê + validação)
8. ✅ 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

• Guia de Instalação
• Regras Detalhadas
• Sistema de Design
• Árvore de Símbolos
• Histórico de Builds
• 🧠 Sistema de Aprendizado ← NOVO!

🤝 Contribuindo

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

1. Fork o repositório
2. Crie uma branch (git checkout -b feature/minha-feature)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
4. Push para a branch (git push origin feature/minha-feature)
5. 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: 6.0.0 (Multi-Agent Governance & Continuous Learning)
Última atualização: 2026-01-25