wegho-agentes 5.0.0 → 6.1.0

package/.cursorrules

@@ -1,18 +1,1118 @@
-# WEGHO Agentes - AI Instructions
+# SISTEMA DE AGENTES WEGHO v5.0.0
 
-You are an expert developer working on the WEGHO Agentes project. You MUST follow these rules strictly.
+## HIERARQUIA OBRIGATÓRIA
 
-## 🚨 ABSOLUTE RULES
-1. **Rule #1: 500 Lines Limit** - NEVER create or allow a file to exceed 500 lines. Refactor immediately if this happens.
-2. **Rule #2: No Hallucinations** - Do not invent APIs or database schemas. Always verify against the existing code and documentation.
-3. **Rule #3: 6-Step Workflow** - Every task MUST follow the 6 steps defined in `docs/AGENT_RULES.md`.
-4. **Rule #4: Source of Truth** - Follow priorities: 1. Project Code, 2. `docs/AGENT_RULES.md`, 3. Official Documentation.
+### NÍVEL 1: ORQUESTRADOR
+IntelligentOrchestrator (.agents/orchestrator.ts)
 
-## 🛠️ HOW TO WORK
-- **Check Inventory**: Always use the `InventoryAgent` logic to avoid code duplication.
-- **Save History**: Every change must be documented in a build file under `docs/builds/`.
-- **Language**: Communication and reports must be in **Português (Brasil)**. Code must be in **English**.
+Responsabilidades OBRIGATÓRIAS:
+1. Receber tarefa do usuário
+2. Invocar TaskAnalyzerAgent
+3. Distribuir para agentes especializados
+4. Executar em paralelo quando possível
+5. Consolidar resultados
+6. Triggerar BuildManager
+7. Retornar relatório final
 
-## 📖 REFERENCE
-Always keep `docs/AGENT_RULES.md` and `docs/DESIGN_SYSTEM.md` in your context.
-If using Gemini, PAY DOUBLE ATTENTION to the constraints in `AGENT_RULES.md` as they are non-negotiable.
+Componentes Integrados:
+- TaskAnalyzerAgent (análise e roteamento)
+- MemorySystem (memória compartilhada)
+- BuildManager (builds incrementais)
+- PerformanceTracker (métricas)
+- FeedbackCollector (aprendizado)
+- AgentParallelizer (execução paralela)
+
+Fluxo OBRIGATÓRIO:
+1. orchestrate(task) → TaskAnalysis
+2. selectBestAgents() → AgentAssignment[]
+3. executeWithAgent() → AgentReport[]
+4. buildManager.createBuild() → buildNumber
+5. generateFinalReport() → FinalReport
+
+### NÍVEL 2: TASK ANALYZER
+TaskAnalyzerAgent (.agents/task-analyzer-agent.ts)
+
+Função: Detectar áreas e selecionar agentes
+Método Principal: analyzeTask(description)
+
+FASE 1: Detecção de Áreas (detectAreas)
+- Analisa keywords na descrição
+- Retorna: string[] de áreas
+
+Áreas Possíveis:
+- nextjs → Next.js, App Router
+- uiux → Design, Interface
+- backend → API, NestJS
+- database → PostgreSQL, Prisma
+- ai-agents → Autonomous agents
+- rag → Vector DB, LLM
+- pentest → Security testing
+- devops → Docker, CI/CD
+- cloud → AWS, GCP, Azure
+- testing → TDD, Playwright
+- cro → Conversion optimization
+- automation → Workflow automation
+- frontend → React, componentes
+- security → Vulnerabilidades
+- architecture → Estrutura
+- quality → Code review
+- documentation → Docs
+
+FASE 2: Seleção de Agentes (determineRequiredAgents)
+- Mapeia áreas → agentes
+- Adiciona agentes core (architecture, quality)
+- Retorna: string[] de agent names
+
+FASE 3: Criação de Assignments (createAgentAssignments)
+- Define prioridades (1 = primeiro)
+- Define dependências
+- Retorna: AgentAssignment[]
+
+### NÍVEL 3: AGENTES ESPECIALIZADOS (20+)
+
+#### WEB DEVELOPMENT (3 agentes)
+
+NextJSAgent (.agents/core/nextjs-agent.ts)
+- Herda: BaseAgent
+- Skills: nextjs-best-practices, react-best-practices, vercel-deployment
+- Keywords: nextjs, next.js, app router, server component
+- Responsabilidades: App Router, Server Components, Server Actions, Image optimization, SEO metadata
+
+UIUXAgent (.agents/core/uiux-agent.ts)
+- Herda: BaseAgent
+- Skills: ui-ux-pro-max, mobile-design, canvas-design
+- Keywords: ui, ux, design, interface, mobile design, acessibilidade
+- Responsabilidades: Design systems, Mobile responsiveness, Accessibility (a11y), User experience
+
+FrontendAgent (.agents/core/frontend-agent.ts)
+- Herda: BaseAgent
+- Skills: react-patterns, component-design
+- Keywords: frontend, react, component
+- Responsabilidades: React components, Estado e props, Hooks patterns, Performance
+
+#### BACKEND/DATABASE (2 agentes)
+
+BackendAgent (.agents/core/backend-agent.ts)
+- Herda: BaseAgent
+- Skills: backend-dev-guidelines, nodejs-best-practices, nestjs-expert, api-patterns
+- Keywords: backend, api, nestjs, microservices, graphql
+- Responsabilidades: API design (REST/GraphQL), NestJS architecture, Microservices, Rate limiting
+
+DatabaseAgent (.agents/core/database-agent.ts)
+- Herda: BaseAgent
+- Skills: database-design, postgres-best-practices, prisma-expert
+- Keywords: database, postgres, prisma, sql, migration
+- Responsabilidades: Schema design, Migrations, Query optimization, RLS policies
+
+#### AI/ML (2 agentes)
+
+AIAgentsAgent (.agents/core/ai-agents-agent.ts)
+- Herda: BaseAgent
+- Skills: autonomous-agents, autonomous-agent-patterns, ai-agents-architect
+- Keywords: agent, autonomous, multi-agent, orchestrat
+- Responsabilidades: Agent patterns (ReAct, Chain-of-Thought), Multi-agent systems, Tool integration, Agent orchestration
+
+RAGAgent (.agents/core/rag-agent.ts)
+- Herda: BaseAgent
+- Skills: rag-implementation, rag-engineer, llm-app-patterns
+- Keywords: rag, vector, embedding, llm, retrieval
+- Responsabilidades: RAG implementation, Vector databases (Pinecone, Weaviate), Embedding strategies, LLM integration
+
+#### SECURITY (2 agentes)
+
+SecurityAgent (.agents/core/security-agent.ts)
+- Herda: BaseAgent
+- Skills: security-best-practices, owasp-top-10
+- Keywords: security, vulnerabilidade, auth
+- Responsabilidades: XSS/CSRF detection, Authentication, Data sanitization, Security headers
+
+PentestAgent (.agents/core/pentest-agent.ts)
+- Herda: BaseAgent
+- Skills: ethical-hacking-methodology, pentest-checklist, webapp-testing
+- Keywords: pentest, vulnerability, owasp, sql injection, xss
+- Responsabilidades: Penetration testing, OWASP Top 10, SQL injection testing, Security tools (Burp Suite)
+
+#### DEVOPS/CLOUD (2 agentes)
+
+DevOpsAgent (.agents/core/devops-agent.ts)
+- Herda: BaseAgent
+- Skills: docker-expert, deployment-procedures, github-workflow-automation
+- Keywords: docker, ci/cd, pipeline, deployment
+- Responsabilidades: Docker containerization, CI/CD pipelines, Infrastructure as Code, Deployment automation
+
+CloudAgent (.agents/core/cloud-agent.ts)
+- Herda: BaseAgent
+- Skills: aws-serverless, gcp-cloud-run, azure-functions
+- Keywords: aws, gcp, azure, serverless, cloud
+- Responsabilidades: AWS services, GCP deployment, Azure functions, Serverless architecture
+
+#### TESTING/MARKETING (2 agentes)
+
+TestingAgent (.agents/core/testing-agent.ts)
+- Herda: BaseAgent
+- Skills: test-driven-development, tdd-workflow, playwright-skill
+- Keywords: test, tdd, playwright, e2e, unit test
+- Responsabilidades: TDD workflow, Unit tests, Integration tests, E2E with Playwright
+
+CROAgent (.agents/core/cro-agent.ts)
+- Herda: BaseAgent
+- Skills: ab-test-setup, form-cro, page-cro, signup-flow-cro
+- Keywords: conversion, cro, a/b test, onboarding, signup
+- Responsabilidades: Conversion optimization, A/B testing, User onboarding, Growth hacking
+
+#### TOOLS/AUTOMATION (1 agente)
+
+AutomationAgent (.agents/core/automation-agent.ts)
+- Herda: BaseAgent
+- Skills: workflow-automation, browser-automation, mcp-builder
+- Keywords: automation, workflow, mcp, browser automation
+- Responsabilidades: Workflow automation, Browser automation, Tool building, MCP development
+
+#### CORE AGENTS (4 agentes sempre ativos)
+
+ArchitectureAgent (.agents/core/architecture-agent.ts)
+- SEMPRE incluído em todas as tarefas
+- Valida: Estrutura de arquivos, limite 500 linhas, padrões
+- Prioridade: 1 (executa primeiro)
+
+QualityAgent (.agents/core/quality-agent.ts)
+- SEMPRE incluído em todas as tarefas
+- Valida: Code quality, clean code, best practices
+- Prioridade: 4 (executa por último)
+
+DocumentationAgent (.agents/core/documentation-agent.ts)
+- Ativado quando: documentation, readme, docs
+- Gera: README, comentários, documentação
+
+InventoryAgent (.agents/core/inventory-agent.ts)
+- Ativado quando: inventory, scan, almoxarifado
+- Previne: Duplicação de recursos
+
+### NÍVEL 4: BASE AGENT
+BaseAgent (.agents/core/base-agent.ts)
+Classe abstrata que TODOS os agentes herdam
+
+Propriedades OBRIGATÓRIAS:
+- agentName: string
+- memory: MemorySystem
+- skillManager: SkillManager
+- workflowSteps: WorkflowStep[]
+
+Métodos OBRIGATÓRIOS:
+
+executeWithMemory(task, context)
+1. Consulta memória (query)
+2. Executa executeTask()
+3. Salva resultado (store)
+4. Aprende (learnFromFeedback)
+
+executeTask(task, context) [ABSTRATO]
+- Cada agente implementa sua lógica
+
+recordOutcome(task, context, result)
+- Salva na memória
+
+consultReferenceRepositories()
+- Busca em repos de referência
+
+Sistema de Memória:
+- Localização: .agents/memory/{agentName}/
+- Arquivo: executions.json
+- Estrutura: {task, success, timestamp, recommendations, issues}
+
+### NÍVEL 5: BUILD MANAGER
+BuildManager (.agents/core/build-manager.ts)
+Responsabilidade: Rastrear TODAS as mudanças de arquivos
+
+Estrutura de Dados:
+- .builds/history.json: {currentVersion, currentBuild, builds[]}
+- .builds/snapshots/{version}/{filepath}/build-{number}.{ext}
+
+Métodos OBRIGATÓRIOS:
+
+createBuild(files, agent, success, description)
+1. Incrementa buildNumber
+2. Cria snapshots de arquivos
+3. Registra no history.json
+4. Retorna buildNumber
+
+createSnapshot(filePath, buildNumber)
+- Salva cópia do arquivo
+
+restoreFromBuild(filePath, buildNumber)
+- Restaura versão anterior
+
+incrementVersion(type: major|minor|patch)
+- Atualiza versão do projeto
+
+Trigger Automático:
+- Quando: Agentes executam com sucesso
+- Condição: context.files.length > 0
+- Ação: buildManager.createBuild()
+
+### NÍVEL 6: MEMORY SYSTEM
+MemorySystem (.agents/core/memory-system.ts)
+Função: Armazenar e consultar execuções anteriores
+
+Estrutura por Agente:
+.agents/memory/{agentName}/executions.json
+
+Métodos:
+- store(entry: MemoryEntry): Salva execução
+- query(taskDescription: string): Busca execuções similares
+- getStats(agentName: string): Retorna taxa de sucesso
+
+MemoryEntry: {id, task, success, timestamp, agentName, recommendations, issues}
+
+## FLUXO COMPLETO OBRIGATÓRIO
+
+1. ENTRADA: npm run agent "Criar API Next.js com PostgreSQL"
+
+2. ORQUESTRADOR: IntelligentOrchestrator.orchestrate(task)
+
+3. TASK ANALYZER:
+- detectAreas() → [nextjs, backend, database]
+- determineRequiredAgents() → [architecture-agent, nextjs-agent, backend-agent, database-agent, quality-agent]
+- createAgentAssignments() → [{agentName, priority}...]
+
+4. EXECUÇÃO PARALELA:
+- Grupo 1 (priority 1): architecture-agent.executeWithMemory()
+- Grupo 2 (priority 2): nextjs-agent, backend-agent (PARALELO)
+- Grupo 3 (priority 3): database-agent
+- Grupo 4 (priority 4): quality-agent
+
+5. BUILD AUTOMÁTICO:
+buildManager.createBuild(files, agents, success)
+→ Build 781 criado
+→ Snapshot: .builds/snapshots/0.0.1/src/api/route.ts/build-781.ts
+→ History: .builds/history.json atualizado
+
+6. RESULTADO: FinalReport {taskDescription, overallSuccess, buildNumber, agentReports}
+
+## SKILLS (200+)
+nextjs-best-practices, react-patterns, postgres-best-practices, rag-implementation, docker-expert, tdd-workflow, +194 outras
+
+## REGRAS OBRIGATÓRIAS
+
+1. SEMPRE use npm run agent para tarefas complexas
+2. NUNCA pule o sistema de agentes
+3. CONFIE na memória - agentes aprendem
+4. DEIXE builds automáticos funcionarem
+5. USE keywords específicas nas tarefas
+6. CONSULTE histórico antes de recriar
+
+v5.0.0 | 20+ Agentes | 200+ Skills | Status: OPERACIONAL
+
+## 📐 HIERARQUIA OBRIGATÓRIA DO SISTEMA
+
+### NÍVEL 1: ORQUESTRADOR (Controlador Principal)
+```
+IntelligentOrchestrator (.agents/orchestrator.ts)
+├── Responsabilidades OBRIGATÓRIAS:
+│   ├── 1. Receber tarefa do usuário
+│   ├── 2. Invocar TaskAnalyzerAgent
+│   ├── 3. Distribuir para agentes especializados
+│   ├── 4. Executar em paralelo quando possível
+│   ├── 5. Consolidar resultados
+│   ├── 6. Triggerar BuildManager
+│   └── 7. Retornar relatório final
+│
+├── Componentes Integrados:
+│   ├── TaskAnalyzerAgent (análise e roteamento)
+│   ├── MemorySystem (memória compartilhada)
+│   ├── BuildManager (builds incrementais)
+│   ├── PerformanceTracker (métricas)
+│   ├── FeedbackCollector (aprendizado)
+│   └── AgentParallelizer (execução paralela)
+│
+└── Fluxo OBRIGATÓRIO:
+    1. orchestrate(task) → TaskAnalysis
+    2. selectBestAgents() → AgentAssignment[]
+    3. executeWithAgent() → AgentReport[]
+    4. buildManager.createBuild() → buildNumber
+    5. generateFinalReport() → FinalReport
+```
+
+### NÍVEL 2: TASK ANALYZER (Roteamento Inteligente)
+```
+TaskAnalyzerAgent (.agents/task-analyzer-agent.ts)
+├── Função: Detectar áreas e selecionar agentes
+├── Método Principal: analyzeTask(description)
+│
+├── FASE 1: Detecção de Áreas (detectAreas)
+│   ├── Analisa keywords na descrição
+│   ├── Retorna: string[] de áreas
+│   └── Áreas Possíveis:
+│       ├── 'nextjs' → Next.js, App Router
+│       ├── 'uiux' → Design, Interface
+│       ├── 'backend' → API, NestJS
+│       ├── 'database' → PostgreSQL, Prisma
+│       ├── 'ai-agents' → Autonomous agents
+│       ├── 'rag' → Vector DB, LLM
+│       ├── 'pentest' → Security testing
+│       ├── 'devops' → Docker, CI/CD
+│       ├── 'cloud' → AWS, GCP, Azure
+│       ├── 'testing' → TDD, Playwright
+│       ├── 'cro' → Conversion optimization
+│       ├── 'automation' → Workflow automation
+│       ├── 'frontend' → React, componentes
+│       ├── 'security' → Vulnerabilidades
+│       ├── 'architecture' → Estrutura
+│       ├── 'quality' → Code review
+│       └── 'documentation' → Docs
+│
+├── FASE 2: Seleção de Agentes (determineRequiredAgents)
+│   ├── Mapeia áreas → agentes
+│   ├── Adiciona agentes core (architecture, quality)
+│   └── Retorna: string[] de agent names
+│
+└── FASE 3: Criação de Assignments (createAgentAssignments)
+    ├── Define prioridades (1 = primeiro)
+    ├── Define dependências
+    └── Retorna: AgentAssignment[]
+```
+
+### NÍVEL 3: AGENTES ESPECIALIZADOS (20+ Agentes)
+
+#### 3.1 WEB DEVELOPMENT (3 agentes)
+```
+NextJSAgent (.agents/core/nextjs-agent.ts)
+├── Herda: BaseAgent
+├── Skills: nextjs-best-practices, react-best-practices, vercel-deployment
+├── Keywords: nextjs, next.js, app router, server component
+├── Responsabilidades:
+│   ├── App Router patterns
+│   ├── Server Components
+│   ├── Server Actions
+│   ├── Image optimization
+│   └── SEO metadata
+└── Método: executeTask(task, context) → TaskResult
+
+UIUXAgent (.agents/core/uiux-agent.ts)
+├── Herda: BaseAgent
+├── Skills: ui-ux-pro-max, mobile-design, canvas-design
+├── Keywords: ui, ux, design, interface, mobile design, acessibilidade
+├── Responsabilidades:
+│   ├── Design systems
+│   ├── Mobile responsiveness
+│   ├── Accessibility (a11y)
+│   └── User experience
+└── Método: executeTask(task, context) → TaskResult
+
+FrontendAgent (.agents/core/frontend-agent.ts)
+├── Herda: BaseAgent
+├── Skills: react-patterns, component-design
+├── Keywords: frontend, react, component
+├── Responsabilidades:
+│   ├── React components
+│   ├── Estado e props
+│   ├── Hooks patterns
+│   └── Performance
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.2 BACKEND/DATABASE (2 agentes)
+```
+BackendAgent (.agents/core/backend-agent.ts)
+├── Herda: BaseAgent
+├── Skills: backend-dev-guidelines, nodejs-best-practices, nestjs-expert, api-patterns
+├── Keywords: backend, api, nestjs, microservices, graphql
+├── Responsabilidades:
+│   ├── API design (REST/GraphQL)
+│   ├── NestJS architecture
+│   ├── Microservices
+│   └── Rate limiting
+└── Método: executeTask(task, context) → TaskResult
+
+DatabaseAgent (.agents/core/database-agent.ts)
+├── Herda: BaseAgent
+├── Skills: database-design, postgres-best-practices, prisma-expert
+├── Keywords: database, postgres, prisma, sql, migration
+├── Responsabilidades:
+│   ├── Schema design
+│   ├── Migrations
+│   ├── Query optimization
+│   └── RLS policies
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.3 AI/ML (2 agentes)
+```
+AIAgentsAgent (.agents/core/ai-agents-agent.ts)
+├── Herda: BaseAgent
+├── Skills: autonomous-agents, autonomous-agent-patterns, ai-agents-architect
+├── Keywords: agent, autonomous, multi-agent, orchestrat
+├── Responsabilidades:
+│   ├── Agent patterns (ReAct, Chain-of-Thought)
+│   ├── Multi-agent systems
+│   ├── Tool integration
+│   └── Agent orchestration
+└── Método: executeTask(task, context) → TaskResult
+
+RAGAgent (.agents/core/rag-agent.ts)
+├── Herda: BaseAgent
+├── Skills: rag-implementation, rag-engineer, llm-app-patterns
+├── Keywords: rag, vector, embedding, llm, retrieval
+├── Responsabilidades:
+│   ├── RAG implementation
+│   ├── Vector databases (Pinecone, Weaviate)
+│   ├── Embedding strategies
+│   └── LLM integration
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.4 SECURITY (2 agentes)
+```
+SecurityAgent (.agents/core/security-agent.ts)
+├── Herda: BaseAgent
+├── Skills: security-best-practices, owasp-top-10
+├── Keywords: security, vulnerabilidade, auth
+├── Responsabilidades:
+│   ├── XSS, CSRF detection
+│   ├── Authentication
+│   ├── Data sanitization
+│   └── Security headers
+└── Método: executeTask(task, context) → TaskResult
+
+PentestAgent (.agents/core/pentest-agent.ts)
+├── Herda: BaseAgent
+├── Skills: ethical-hacking-methodology, pentest-checklist, webapp-testing
+├── Keywords: pentest, vulnerability, owasp, sql injection, xss
+├── Responsabilidades:
+│   ├── Penetration testing
+│   ├── OWASP Top 10
+│   ├── SQL injection testing
+│   └── Security tools (Burp Suite)
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.5 DEVOPS/CLOUD (2 agentes)
+```
+DevOpsAgent (.agents/core/devops-agent.ts)
+├── Herda: BaseAgent
+├── Skills: docker-expert, deployment-procedures, github-workflow-automation
+├── Keywords: docker, ci/cd, pipeline, deployment
+├── Responsabilidades:
+│   ├── Docker containerization
+│   ├── CI/CD pipelines
+│   ├── Infrastructure as Code
+│   └── Deployment automation
+└── Método: executeTask(task, context) → TaskResult
+
+CloudAgent (.agents/core/cloud-agent.ts)
+├── Herda: BaseAgent
+├── Skills: aws-serverless, gcp-cloud-run, azure-functions
+├── Keywords: aws, gcp, azure, serverless, cloud
+├── Responsabilidades:
+│   ├── AWS services
+│   ├── GCP deployment
+│   ├── Azure functions
+│   └── Serverless architecture
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.6 TESTING/MARKETING (2 agentes)
+```
+TestingAgent (.agents/core/testing-agent.ts)
+├── Herda: BaseAgent
+├── Skills: test-driven-development, tdd-workflow, playwright-skill
+├── Keywords: test, tdd, playwright, e2e, unit test
+├── Responsabilidades:
+│   ├── TDD workflow
+│   ├── Unit tests
+│   ├── Integration tests
+│   └── E2E with Playwright
+└── Método: executeTask(task, context) → TaskResult
+
+CROAgent (.agents/core/cro-agent.ts)
+├── Herda: BaseAgent
+├── Skills: ab-test-setup, form-cro, page-cro, signup-flow-cro
+├── Keywords: conversion, cro, a/b test, onboarding, signup
+├── Responsabilidades:
+│   ├── Conversion optimization
+│   ├── A/B testing
+│   ├── User onboarding
+│   └── Growth hacking
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.7 TOOLS/AUTOMATION (1 agente)
+```
+AutomationAgent (.agents/core/automation-agent.ts)
+├── Herda: BaseAgent
+├── Skills: workflow-automation, browser-automation, mcp-builder
+├── Keywords: automation, workflow, mcp, browser automation
+├── Responsabilidades:
+│   ├── Workflow automation
+│   ├── Browser automation
+│   ├── Tool building
+│   └── MCP development
+└── Método: executeTask(task, context) → TaskResult
+```
+
+#### 3.8 CORE AGENTS (4 agentes sempre ativos)
+```
+ArchitectureAgent (.agents/core/architecture-agent.ts)
+├── SEMPRE incluído em todas as tarefas
+├── Valida: Estrutura de arquivos, limite 500 linhas, padrões
+└── Prioridade: 1 (executa primeiro)
+
+QualityAgent (.agents/core/quality-agent.ts)
+├── SEMPRE incluído em todas as tarefas
+├── Valida: Code quality, clean code, best practices
+└── Prioridade: 4 (executa por último)
+
+DocumentationAgent (.agents/core/documentation-agent.ts)
+├── Ativado quando: 'documentation', 'readme', 'docs'
+└── Gera: README, comentários, documentação
+
+InventoryAgent (.agents/core/inventory-agent.ts)
+├── Ativado quando: 'inventory', 'scan', 'almoxarifado'
+└── Previne: Duplicação de recursos
+```
+
+### NÍVEL 4: BASE AGENT (Classe Pai)
+```
+BaseAgent (.agents/core/base-agent.ts)
+├── Classe abstrata que TODOS os agentes herdam
+│
+├── Propriedades OBRIGATÓRIAS:
+│   ├── agentName: string
+│   ├── memory: MemorySystem
+│   ├── skillManager: SkillManager
+│   └── workflowSteps: WorkflowStep[]
+│
+├── Métodos OBRIGATÓRIOS:
+│   ├── executeWithMemory(task, context)
+│   │   ├── 1. Consulta memória (query)
+│   │   ├── 2. Executa executeTask()
+│   │   ├── 3. Salva resultado (store)
+│   │   └── 4. Aprende (learnFromFeedback)
+│   │
+│   ├── executeTask(task, context) [ABSTRATO]
+│   │   └── Cada agente implementa sua lógica
+│   │
+│   ├── recordOutcome(task, context, result)
+│   │   └── Salva na memória
+│   │
+│   └── consultReferenceRepositories()
+│       └── Busca em repos de referência
+│
+└── Sistema de Memória:
+    ├── Localização: .agents/memory/{agentName}/
+    ├── Arquivo: executions.json
+    └── Estrutura:
+        {
+          "task": "descrição",
+          "success": true/false,
+          "timestamp": "ISO date",
+          "recommendations": [],
+          "issues": []
+        }
+```
+
+### NÍVEL 5: BUILD MANAGER (Versionamento)
+```
+BuildManager (.agents/core/build-manager.ts)
+├── Responsabilidade: Rastrear TODAS as mudanças de arquivos
+│
+├── Estrutura de Dados:
+│   ├── .builds/history.json
+│   │   ├── currentVersion: "0.0.1"
+│   │   ├── currentBuild: 780
+│   │   └── builds: BuildEntry[]
+│   │
+│   └── .builds/snapshots/{version}/{filepath}/
+│       └── build-{number}.{ext}
+│
+├── Métodos OBRIGATÓRIOS:
+│   ├── createBuild(files, agent, success, description)
+│   │   ├── 1. Incrementa buildNumber
+│   │   ├── 2. Cria snapshots de arquivos
+│   │   ├── 3. Registra no history.json
+│   │   └── 4. Retorna buildNumber
+│   │
+│   ├── createSnapshot(filePath, buildNumber)
+│   │   └── Salva cópia do arquivo
+│   │
+│   ├── restoreFromBuild(filePath, buildNumber)
+│   │   └── Restaura versão anterior
+│   │
+│   └── incrementVersion(type: 'major'|'minor'|'patch')
+│       └── Atualiza versão do projeto
+│
+└── Trigger Automático:
+    ├── Quando: Agentes executam com sucesso
+    ├── Condição: context.files.length > 0
+    └── Ação: buildManager.createBuild()
+```
+
+### NÍVEL 6: MEMORY SYSTEM (Aprendizado)
+```
+MemorySystem (.agents/core/memory-system.ts)
+├── Função: Armazenar e consultar execuções anteriores
+│
+├── Estrutura por Agente:
+│   .agents/memory/
+│   ├── nextjs-agent/
+│   │   └── executions.json
+│   ├── backend-agent/
+│   │   └── executions.json
+│   └── ... (20+ agentes)
+│
+├── Métodos:
+│   ├── store(entry: MemoryEntry)
+│   │   └── Salva execução
+│   │
+│   ├── query(taskDescription: string)
+│   │   └── Busca execuções similares
+│   │
+│   └── getStats(agentName: string)
+│       └── Retorna taxa de sucesso
+│
+└── MemoryEntry:
+    {
+      "id": "uuid",
+      "task": "descrição",
+      "success": boolean,
+      "timestamp": "ISO",
+      "agentName": "string",
+      "recommendations": string[],
+      "issues": string[]
+    }
+```
+
+## 🔄 FLUXO COMPLETO OBRIGATÓRIO
+
+```
+1. ENTRADA DO USUÁRIO
+   └─> npm run agent "Criar API Next.js com PostgreSQL"
+
+2. ORQUESTRADOR RECEBE
+   └─> IntelligentOrchestrator.orchestrate(task)
+
+3. TASK ANALYZER ANALISA
+   ├─> detectAreas("Criar API Next.js com PostgreSQL")
+   │   └─> ['nextjs', 'backend', 'database']
+   │
+   ├─> determineRequiredAgents(areas)
+   │   └─> ['architecture-agent', 'nextjs-agent', 'backend-agent', 
+   │        'database-agent', 'quality-agent']
+   │
+   └─> createAgentAssignments(agents)
+       └─> [
+             {agentName: 'architecture-agent', priority: 1},
+             {agentName: 'nextjs-agent', priority: 2},
+             {agentName: 'backend-agent', priority: 2},
+             {agentName: 'database-agent', priority: 3},
+             {agentName: 'quality-agent', priority: 4}
+           ]
+
+4. ORQUESTRADOR EXECUTA (PARALELO)
+   ├─> Grupo 1 (priority 1): architecture-agent
+   │   └─> executeWithMemory()
+   │       ├─> Consulta memória
+   │       ├─> Executa validações
+   │       └─> Salva resultado
+   │
+   ├─> Grupo 2 (priority 2): nextjs-agent, backend-agent (PARALELO)
+   │   ├─> nextjsAgent.executeWithMemory()
+   │   │   └─> Recomendações Next.js
+   │   └─> backendAgent.executeWithMemory()
+   │       └─> Recomendações API
+   │
+   ├─> Grupo 3 (priority 3): database-agent
+   │   └─> databaseAgent.executeWithMemory()
+   │       └─> Recomendações DB
+   │
+   └─> Grupo 4 (priority 4): quality-agent
+       └─> qualityAgent.executeWithMemory()
+           └─> Validação final
+
+5. BUILD AUTOMÁTICO
+   └─> buildManager.createBuild(
+         files: ['src/api/route.ts'],
+         agent: 'orchestrator (nextjs, backend, database)',
+         success: true
+       )
+       └─> Build 781 criado
+           ├─> Snapshot: .builds/snapshots/0.0.1/src/api/route.ts/build-781.ts
+           └─> History: .builds/history.json atualizado
+
+6. RESULTADO CONSOLIDADO
+   └─> FinalReport {
+         taskDescription: "...",
+         overallSuccess: true,
+         buildNumber: 781,
+         agentReports: [...]
+       }
+```
+
+## 📚 SKILLS (200+)
+
+Cada agente carrega skills de `skills/`:
+- nextjs-best-practices/
+- react-patterns/
+- postgres-best-practices/
+- rag-implementation/
+- docker-expert/
+- tdd-workflow/
+- +194 outras
+
+## ⚡ REGRAS OBRIGATÓRIAS PARA IA
+
+1. **SEMPRE use npm run agent** para tarefas complexas
+2. **NUNCA pule** o sistema de agentes
+3. **CONFIE na memória** - agentes aprendem
+4. **DEIXE builds automáticos** funcionarem
+5. **USE keywords específicas** nas tarefas
+6. **CONSULTE histórico** antes de recriar
+
+**Versão**: 5.0.0 | **Agentes**: 20+ | **Skills**: 200+ | **Status**: ✅ OPERACIONAL
+
+Este projeto possui um **sistema completo de 20+ agentes especializados** com memória individual e build incremental automático.
+
+---
+
+## 📋 Como Usar os Agentes
+
+### Comando Principal
+```bash
+npm run agent "sua tarefa aqui"
+```
+
+### Exemplo
+```bash
+npm run agent "Criar API Next.js com autenticação e PostgreSQL"
+```
+
+**O que acontece**:
+1. TaskAnalyzer detecta áreas: `nextjs`, `backend`, `database`, `security`
+2. Orquestrador seleciona agentes: NextJSAgent, BackendAgent, DatabaseAgent, SecurityAgent
+3. Cada agente executa com memória (consulta histórico, executa, salva resultado)
+4. Build automático é criado se houver mudanças
+5. Relatório consolidado é gerado
+
+---
+
+## 🤖 Agentes Disponíveis (20+)
+
+### Web Development
+- **NextJSAgent**: Next.js, App Router, Server Components, Vercel
+  - Keywords: `nextjs`, `next.js`, `app router`, `server component`
+  
+- **UIUXAgent**: UI/UX, mobile design, acessibilidade
+  - Keywords: `ui`, `ux`, `design`, `interface`, `mobile design`
+
+- **FrontendAgent**: React, componentes, estados
+  - Keywords: `frontend`, `react`, `component`
+
+### Backend/Database
+- **BackendAgent**: Node.js, NestJS, API, GraphQL, microservices
+  - Keywords: `backend`, `api`, `nestjs`, `microservices`, `graphql`
+
+- **DatabaseAgent**: PostgreSQL, Prisma, migrations, schema
+  - Keywords: `database`, `postgres`, `prisma`, `sql`, `migration`
+
+### AI/ML
+- **AIAgentsAgent**: Autonomous agents, multi-agent systems, orchestration
+  - Keywords: `agent`, `autonomous`, `multi-agent`, `orchestrat`
+
+- **RAGAgent**: RAG, vector databases, embeddings, LLM
+  - Keywords: `rag`, `vector`, `embedding`, `llm`, `retrieval`
+
+### Security
+- **SecurityAgent**: Vulnerabilidades, XSS, CSRF, sanitização
+  - Keywords: `security`, `vulnerabilidade`, `auth`
+
+- **PentestAgent**: Penetration testing, OWASP, SQL injection
+  - Keywords: `pentest`, `vulnerability`, `owasp`, `sql injection`, `xss`
+
+### DevOps/Cloud
+- **DevOpsAgent**: Docker, CI/CD, pipelines, deployment
+  - Keywords: `docker`, `ci/cd`, `pipeline`, `deployment`
+
+- **CloudAgent**: AWS, GCP, Azure, serverless
+  - Keywords: `aws`, `gcp`, `azure`, `serverless`, `cloud`
+
+### Testing/QA
+- **TestingAgent**: TDD, Playwright, e2e, unit tests
+  - Keywords: `test`, `tdd`, `playwright`, `e2e`, `unit test`
+
+### Marketing/SEO
+- **SEOAgent**: SEO, otimização, search engine
+  - Keywords: `seo`, `otimização`, `search engine`
+
+- **CROAgent**: Conversion optimization, A/B testing, onboarding
+  - Keywords: `conversion`, `cro`, `a/b test`, `onboarding`, `signup`
+
+### Tools/Automation
+- **AutomationAgent**: Workflow automation, browser automation, MCP
+  - Keywords: `automation`, `workflow`, `mcp`, `browser automation`
+
+### Core Agents
+- **ArchitectureAgent**: Estrutura de arquivos, padrões, limite 500 linhas
+- **QualityAgent**: Code review, clean code, best practices
+- **DocumentationAgent**: Documentação, README, comentários
+- **InventoryAgent**: Scan de recursos, anti-duplicação
+
+---
+
+## 🧠 Sistema de Memória
+
+**Cada agente tem memória individual** em `.agents/memory/{agent-name}/`
+
+**Fluxo com Memória**:
+1. Agente consulta: "Já fiz essa tarefa antes?"
+2. Usa aprendizados anteriores
+3. Executa tarefa
+4. Salva resultado (sucesso/falha)
+5. Aprende continuamente
+
+**Exemplo**:
+```json
+{
+  "task": "Criar API Next.js",
+  "success": true,
+  "timestamp": "2026-01-25T00:00:00",
+  "agentName": "nextjs-agent",
+  "recommendations": [...]
+}
+```
+
+---
+
+## 📦 Build Incremental Automático
+
+**BuildManager** rastreia todas as mudanças:
+
+**Estrutura**:
+```
+.builds/
+├── history.json (histórico completo)
+└── snapshots/
+    └── 0.0.1/
+        └── src/api/route.ts/
+            ├── build-001.ts
+            ├── build-002.ts
+            └── build-780.ts
+```
+
+**Quando é criado**:
+- Automaticamente após execução bem-sucedida de agentes
+- Quando arquivos são modificados
+- Snapshot de cada arquivo é salvo
+
+**Como usar**:
+```typescript
+import { BuildManager } from './.agents/core/build-manager';
+
+const buildManager = new BuildManager();
+
+// Ver histórico
+console.log(buildManager.generateReport());
+
+// Restaurar de build anterior
+await buildManager.restoreFromBuild('src/api/route.ts', 780);
+```
+
+---
+
+## 🎯 Quando Usar Cada Agente
+
+### Para Desenvolvimento Web
+```bash
+npm run agent "Criar página de login com Next.js"
+# Ativa: NextJSAgent, UIUXAgent, SecurityAgent
+```
+
+### Para APIs
+```bash
+npm run agent "Criar API REST com autenticação JWT"
+# Ativa: BackendAgent, SecurityAgent, DatabaseAgent
+```
+
+### Para Database
+```bash
+npm run agent "Criar schema PostgreSQL com RLS"
+# Ativa: DatabaseAgent, SecurityAgent
+```
+
+### Para AI/ML
+```bash
+npm run agent "Implementar RAG com vector database"
+# Ativa: RAGAgent, AIAgentsAgent, DatabaseAgent
+```
+
+### Para DevOps
+```bash
+npm run agent "Configurar Docker e CI/CD"
+# Ativa: DevOpsAgent, CloudAgent
+```
+
+### Para Testes
+```bash
+npm run agent "Criar testes e2e com Playwright"
+# Ativa: TestingAgent, QualityAgent
+```
+
+---
+
+## 📚 Skills Integradas (200+)
+
+Cada agente tem acesso a skills específicas em `skills/`:
+
+**Exemplos**:
+- `skills/nextjs-best-practices/` - Melhores práticas Next.js
+- `skills/react-patterns/` - Padrões React
+- `skills/postgres-best-practices/` - PostgreSQL
+- `skills/rag-implementation/` - RAG
+- `skills/docker-expert/` - Docker
+- `skills/tdd-workflow/` - TDD
+- +190 outras skills
+
+---
+
+## 🚀 Regras para IA
+
+### 1. **Sempre use os agentes para tarefas complexas**
+```bash
+# ❌ NÃO fazer manualmente
+# Criar arquivo, escrever código, validar...
+
+# ✅ USAR agentes
+npm run agent "Criar componente de autenticação"
+```
+
+### 2. **Confie na memória dos agentes**
+Os agentes aprendem com cada execução. Se já fizeram algo similar, vão usar esse conhecimento.
+
+### 3. **Deixe o build tracking trabalhar**
+Não precisa versionar manualmente. O BuildManager cria snapshots automaticamente.
+
+### 4. **Use keywords específicas**
+Quanto mais específico, melhor o roteamento:
+- ✅ "Criar API Next.js com PostgreSQL e autenticação JWT"
+- ❌ "Fazer backend"
+
+### 5. **Consulte o histórico de builds**
+```typescript
+const buildManager = new BuildManager();
+console.log(buildManager.generateReport());
+```
+
+### 6. **Aproveite a paralelização**
+O orquestrador executa agentes em paralelo quando possível. Não precisa otimizar manualmente.
+
+---
+
+## 📊 Estrutura do Projeto
+
+```
+wegho-agentes/
+├── .agents/
+│   ├── core/
+│   │   ├── nextjs-agent.ts
+│   │   ├── uiux-agent.ts
+│   │   ├── backend-agent.ts
+│   │   ├── database-agent.ts
+│   │   ├── ai-agents-agent.ts
+│   │   ├── rag-agent.ts
+│   │   ├── pentest-agent.ts
+│   │   ├── devops-agent.ts
+│   │   ├── cloud-agent.ts
+│   │   ├── testing-agent.ts
+│   │   ├── cro-agent.ts
+│   │   ├── automation-agent.ts
+│   │   ├── build-manager.ts
+│   │   └── base-agent.ts
+│   ├── memory/ (memória de cada agente)
+│   ├── orchestrator.ts
+│   └── task-analyzer-agent.ts
+├── .builds/ (builds incrementais)
+├── skills/ (200+ skills)
+└── scripts/
+    └── test-build-system.ts
+```
+
+---
+
+## 🎓 Exemplos Práticos
+
+### Exemplo 1: Full Stack App
+```bash
+npm run agent "Criar aplicação Next.js com:
+- Autenticação com Supabase
+- Dashboard com gráficos
+- API REST
+- PostgreSQL com RLS
+- Deploy na Vercel"
+```
+
+**Agentes ativados**: NextJS, UIUX, Backend, Database, Security, Cloud
+
+### Exemplo 2: AI Application
+```bash
+npm run agent "Implementar chatbot com:
+- RAG usando Pinecone
+- LLM integration
+- Vector embeddings
+- Chat history"
+```
+
+**Agentes ativados**: RAG, AIAgents, Database, Backend
+
+### Exemplo 3: DevOps Setup
+```bash
+npm run agent "Configurar infraestrutura:
+- Docker containers
+- GitHub Actions CI/CD
+- Deploy automático AWS
+- Testes automatizados"
+```
+
+**Agentes ativados**: DevOps, Cloud, Testing
+
+---
+
+## ⚡ Performance
+
+- **Execução Paralela**: Agentes independentes rodam em paralelo
+- **Memória Otimizada**: Cada agente consulta apenas sua memória
+- **Build Incremental**: Apenas arquivos modificados são salvos
+- **Skills On-Demand**: Skills carregadas apenas quando necessário
+
+---
+
+## 🔍 Debugging
+
+### Ver logs de agente específico
+```bash
+cat .agents/memory/nextjs-agent/executions.json
+```
+
+### Ver histórico de builds
+```bash
+cat .builds/history.json
+```
+
+### Testar build system
+```bash
+npm run test:build
+```
+
+---
+
+## 📖 Documentação Completa
+
+- **Walkthrough**: Ver `.gemini/antigravity/brain/.../walkthrough.md`
+- **Resumo Executivo**: Ver `.gemini/antigravity/brain/.../resumo_executivo.md`
+- **Task Progress**: Ver `.gemini/antigravity/brain/.../task.md`
+
+---
+
+**Versão**: 5.0.0  
+**Status**: ✅ Sistema Completo e Operacional  
+**Agentes**: 20+  
+**Skills**: 200+  
+**Cobertura**: ~95%