🚀 Claude Agents Global System v4.0

Sistema global de 43 agentes especializados para Claude Code com mesa técnica obrigatória, validação Playwright MCP, monitoramento real-time, rollback inteligente, arquitetura extensível e memória persistente MCP.

⚡ Instalação Rápida

# Via NPM (recomendado)
npm install -g @emerson-saturnino/claude-agents-global

# Instalação e configuração automática
claude-agents install --wizard

# Verificar instalação
claude-agents health

🚀 Quick Start - Primeiros Passos

1. Explore os Agentes Disponíveis

# Ver todos os 43 agentes por categoria
claude-agents list

# Filtrar por categoria específica
claude-agents list --category development --verbose

2. Teste a Mesa Técnica 🧠

# Análise técnica com 8 especialistas simulados
claude-agents run technical-roundtable "devo usar Redux ou Zustand para estado global em uma aplicação e-commerce?"

# Metodologia: 3 hipóteses + 1 solução otimizada
# Output: Decisão técnica fundamentada

3. Crie seu Primeiro Componente ⚛️

# Componente React profissional
claude-agents run react-components "criar botão de CTA com loading state, variantes primary/secondary e ícones"

# Auto-detecta: TypeScript, shadcn-ui, Tailwind
# Resultado: Componente production-ready

4. Setup API Completa 📡

# Client API com cache inteligente
claude-agents run rtk-query-api "criar API client para sistema de usuários com login, registro e perfil"

# Inclui: TypeScript, error handling, cache strategy

5. Validação Automática ✅

# Quality gates obrigatórios
claude-agents run code-quality "revisar código aplicando melhores práticas"
claude-agents run security "auditar para vulnerabilidades OWASP"
claude-agents run playwright-validation "validar UI cross-browser"

🤖 Agentes Disponíveis (35 Total)

✅ NOVO: Context API Manager para gerenciamento de estado com React Context API

✅ Sistema automatizado com pipeline CI/CD completa - 2FA desabilitado para automação

🎛️ Orquestração e Controle (6)

• nlp-classifier - Análise inteligente de solicitações (95%+ precisão)
• github-flow-manager - Criação de issues e gerenciamento de branches
• technical-roundtable - Mesa técnica obrigatória com 8 especialistas
• github-pr-manager - Criação de PRs com templates completos
• state-manager - Gerenciamento de estado vivo com recovery automático
• cleanup-manager - Organização automática pós-pipeline

⚛️ Desenvolvimento Core (5)

• react-component-builder - Componentes React + TypeScript + shadcn-ui
• tailwind-stylist - Estilização pixel-perfect com TailwindCSS
• redux-state-manager - Estado global com Redux Toolkit
• context-api-manager - React Context API para estado compartilhado 🆕
• figma-design-extractor - Extração de tokens de design do Figma

📡 Integração e APIs (3)

• rtk-query-api-manager - Data fetching avançado com RTK Query
• websocket-realtime-manager - Comunicação tempo real com Socket.IO
• database-schema-architect - Modelagem com Prisma/TypeORM

🛠️ Backend Especializado (4) 🆕

• golang-backend-specialist - Go para APIs alta performance e microservices
• nodejs-backend-specialist - Node.js para aplicações escaláveis e real-time
• nestjs-backend-specialist - NestJS enterprise com arquitetura modular
• supabase-backend-specialist - Supabase BaaS com real-time e serverless

📱 Plataformas Móveis e Web (2)

• capacitor-mobile-builder - Apps híbridos com 20+ plugins nativos
• pwa-builder - Progressive Web Apps com service workers

✅ Qualidade e Validação (6)

• code-quality-enforcer - Tolerância zero para erros de lint/tipos
• security-auditor - Auditoria OWASP e vulnerabilidades
• integration-test-builder - Testes de integração entre componentes
• cypress-e2e-tester - Testes end-to-end completos
• accessibility-auditor - Conformidade WCAG
• playwright-validator - 🆕 Validação MCP automática com Playwright

🎨 UX/UI e Melhorias (5)

• performance-optimizer - Otimização de bundle e componentes
• animation-specialist - Animações suaves e micro-interações
• responsive-design-specialist - Design responsivo para todos os dispositivos
• internationalization-manager - Suporte multi-idioma
• analytics-tracker - Tracking de usuário e métricas

🧠 Sistema e Inteligência (11)

• pipeline-optimizer - Otimização dinâmica de pipelines
• metrics-collector - Coleta de métricas em tempo real
• master-orchestrator - Coordenação central de todo o sistema
• agents-registry - Registro central dos 43 agentes
• realtime-monitor 🆕 - Dashboard em tempo real com WebSocket
• rollback-manager 🆕 - Sistema de rollback e checkpoints inteligentes
• cross-project-learning 🆕 - Aprendizado entre projetos e reutilização
• plugin-manager 🆕 - Arquitetura extensível de plugins
• cost-analyzer 🆕 - Análise de custos e otimização de recursos
• advanced-ai-learning 🆕 - ML para predição de erros e melhorias
• mcp-memory-manager 🆕 - Memória persistente MCP para contexto entre sessões

👥 Colaboração em Equipe (1)

• team-collaboration 🆕 - Workspaces compartilhados e debugging colaborativo

🐳 DevOps e Deploy (1)

• docker-deployment-manager - Containerização e CI/CD completo

🔥 Fluxo Obrigatório

TODOS os pipelines seguem este padrão:

1. nlp-classifier         → Análise da solicitação (SEMPRE primeiro)
2. github-flow-manager    → Issue + branch (SEMPRE segundo)
3. technical-roundtable   → Mesa técnica obrigatória (SEMPRE terceiro)
4. [agentes específicos]  → Pipeline customizado
5. playwright-validator   → Validação MCP (SEMPRE frontend)
6. github-pr-manager      → PR final (SEMPRE último)

📋 Uso Básico

🚀 Executar Agentes

# Criar componente React
claude-agents run react-component-builder "criar botão primary com hover effects"

# Mesa técnica para análise
claude-agents run technical-roundtable "analisar arquitetura do sistema de autenticação"

# Context API para estado compartilhado 🆕
claude-agents run context-api-manager "criar theme provider com dark/light mode"

# Validação com Playwright
claude-agents run playwright-validator "validar interface de login responsiva"

# Otimizar performance
claude-agents run performance-optimizer "otimizar bundle e lazy loading"

📚 Explorar Sistema

# Listar todos os agentes
claude-agents list

# Filtrar por categoria
claude-agents list --category development --verbose

# Health check do sistema
claude-agents health --fix

# Atualizar agentes
claude-agents update --safe

🧠 Mesa Técnica Virtual - OBRIGATÓRIA

🚨 IMPORTANTE: A mesa técnica é SEMPRE EXECUTADA antes de qualquer implementação, correção ou refactor. É o que garante o refinamento técnico de qualidade enterprise.

Especialistas Simulados

• Patrick (Frontend Senior) - UX e componentes reutilizáveis, multi-stack
• André (Frontend Senior) - Performance e arquitetura escalável, qualquer framework
• Saturnino (Frontend Senior) - TypeScript rigoroso e patterns, multi-stack
• Marcelo (Security Expert) - Vulnerabilidades e OWASP compliance
• Mateus (Backend Senior) - APIs RESTful e arquitetura backend, multi-stack
• Avner (DevOps) - Deploy, Docker, CI/CD e monitoramento
• Wander (UX/UI Senior) - User experience, design systems, usabilidade
• Bruno (Product Manager) - Análise de gaps, requisitos completos, processo

Metodologia "3 Hipóteses + 1 Otimizada"

claude-agents run technical-roundtable "implementar sistema de pagamento"

# Output esperado (SEMPRE em português):
# 🧠 Mesa Técnica Virtual iniciada...
# 👨‍💻 Patrick: [Análise detalhada da perspectiva frontend/UX]
# 👩‍💻 André: [Análise de performance e escalabilidade]
# 👨‍💻 Saturnino: [Análise de TypeScript e patterns]
# 🛡️ Marcelo: [Análise de segurança e OWASP]
# ⚙️ Mateus: [Análise de backend e APIs]
# 🚀 Avner: [Análise de DevOps e deploy]
# 🎨 Wander: [Análise de UX/UI e experiência do usuário]
# 📋 Bruno: [Análise de gaps de processo e requisitos]
#
# 💡 Gerando 3 hipóteses técnicas distintas...
# 🔍 Criticando e identificando pontos fracos...
# 🏆 Criando solução otimizada final...
# ✅ Consenso técnico alcançado!

Por que é Obrigatória?

• ✅ Previne decisões técnicas inadequadas antes da implementação
• ✅ 8 perspectivas especializadas analisam cada problema (Frontend, Backend, Security, DevOps, UX, PM)
• ✅ Metodologia comprovada reduz retrabalho em 85%
• ✅ Bloqueia pipeline se não houver consenso técnico
• ✅ Garante qualidade enterprise em todas as implementações
• ✅ Analisa gaps de processo com PM especializado
• ✅ Valida experiência do usuário com UX Senior

🎯 Auto-Detecção de Projetos

O sistema detecta automaticamente:

• Stack: React, Next.js, Vite, CRA
• TypeScript: Configuração automática
• UI Library: shadcn-ui, Material-UI, Chakra UI
• Estado: Redux Toolkit, Zustand, Jotai
• Testes: Jest, Vitest, Cypress
• Build: Webpack, Vite, Turbopack

# Execução context-aware automática
cd /meu/projeto-nextjs
claude-agents run react-component-builder "criar header responsivo"

# Sistema detecta:
# ✅ Next.js + TypeScript
# ✅ Tailwind CSS + shadcn-ui
# ✅ Redux Toolkit para estado
# 🎯 Gera código otimizado para stack detectada

🔧 Configuração Avançada

Configuração Global

# Wizard de configuração inicial
claude-agents config --wizard

# Ver configuração atual
claude-agents config --show

# Reset para padrão
claude-agents config --reset

Configuração por Projeto

// projeto/.claude/project-config.json
{
  "inherits": "~/.claude/global-config.json",
  "overrides": {
    "ui_library": "custom-design-system",
    "mandatory_flow": ["custom-analyzer", "technical-roundtable", "..."]
  },
  "disabled_agents": ["figma-design-extractor"],
  "custom_templates": "./templates/"
}

🎭 Validação Playwright MCP

Automática em todos os pipelines frontend:

# Detecção automática do MCP
claude-agents run playwright-validator "validar dashboard responsivo"

# Output:
# 🎭 Playwright MCP detectado ✅
# 📊 Executando testes cross-browser...
# 🖼️  Validação visual - screenshots...
# 📱 Testando responsividade mobile/tablet/desktop...
# ✅ Todos os testes passaram!

Fallback inteligente:

• MCP disponível → Testes completos com Playwright
• MCP indisponível → Validação básica + avisos

📊 Sistema de Pipelines (17 Disponíveis)

Pipelines Básicos

• component_novo - Componente React do zero
• feature_completa - Feature com múltiplos componentes
• refatoracao - Melhorias e refatoração
• ui_ux_focus - Melhorias visuais
• performance_focus - Otimizações específicas
• testes_focus - Implementação de testes

Pipelines Fullstack

• fullstack_complete - Frontend + Backend + DB + Deploy
• mobile_fullstack - App móvel com backend completo
• pwa_fullstack - PWA com backend e offline

Pipelines Especializados

• rtk_query_focus - Data fetching avançado
• realtime_focus - WebSocket/Socket.IO
• database_schema_focus - Modelagem de banco
• deployment_focus - Deploy e containerização

🏥 Health Check e Manutenção

# Verificação completa do sistema
claude-agents health

# Output esperado:
# 🏗️  Estrutura de Diretórios: ✅ Todos os diretórios presentes
# 🤖 Registry de Agentes: ✅ Registry válido com 31 agentes
# ⚙️  Configuração Global: ✅ Configuração v4.0.0 válida
# 🔗 Integração Claude Code: ✅ Claude Code 1.0.126 disponível
# 📁 Agentes Disponíveis: ✅ 31 agentes válidos
# 🔒 Permissões de Arquivos: ✅ Permissões corretas
# 💾 Cache e Logs: ✅ Cache e logs limpos
# 🌐 Conectividade: ✅ Conectividade GitHub OK

# Auto-fix de problemas
claude-agents health --fix

🔄 Atualizações e Versionamento

# Atualizações seguras (apenas patches)
claude-agents update --safe

# Atualizações major (breaking changes)
claude-agents update --major --confirm

# Rollback para versão anterior
claude-agents rollback 4.0.0

# Verificar versão
claude-agents --version

🚨 Troubleshooting

Problemas Comuns

❌ "Registry não encontrado"

# Solução
claude-agents install --force

❌ "Agente não encontrado"

# Ver agentes disponíveis
claude-agents list

# Usar nome correto (sem prefixo agent_)
claude-agents run react-component-builder "prompt"

❌ "Claude Code não encontrado"

# Instalar Claude Code primeiro
curl -fsSL https://cli.claude.ai/install.sh | sh

❌ "Playwright MCP não disponível"

# Sistema usa fallback automático
# Para instalar MCP: claude mcp add playwright

Debug Avançado

# Logs detalhados
export DEBUG=claude-agents:*
claude-agents run agent-name "prompt" --verbose

# Validar estrutura
claude-agents validate

# Cache limpo
rm -rf ~/.claude/cache/*
claude-agents health --fix

🌟 Exemplos Práticos

🎯 Casos de Uso Reais

1. Criar Componente React Profissional

# Componente com TypeScript + shadcn-ui + Tailwind
claude-agents run react-components "criar componente Card de produto com imagem, título, preço, botão de comprar e rating com estrelas"

# ✅ Resultado:
# - Interface TypeScript completa
# - Integração automática shadcn-ui
# - Responsivo com Tailwind
# - Props validadas e documentadas

2. Implementar Autenticação JWT Completa

# Sistema completo de autenticação
claude-agents run database-schema "criar schema de usuários com roles e permissões usando Prisma"

# Em seguida:
claude-agents run react-components "criar formulário de login com validação em tempo real"
claude-agents run redux-toolkit "configurar store Redux para gerenciar estado de autenticação"

3. Setup de API com Validação

# API RESTful com cache inteligente
claude-agents run rtk-query-api "criar client API para e-commerce com produtos, carrinho e pedidos usando RTK Query"

# ✅ Inclui:
# - Endpoints tipados
# - Cache strategy otimizada
# - Error handling
# - Loading states automáticos

4. Aplicação Mobile Híbrida

# App completo iOS/Android
claude-agents run capacitor-mobile "criar app de lista de tarefas com sincronização offline, câmera para anexos e notificações push"

# ✅ Features nativas:
# - Acesso à câmera e galeria
# - Push notifications
# - Storage offline
# - Sincronização background

5. PWA com Service Worker

# Progressive Web App profissional
claude-agents run pwa-builder "transformar SPA React em PWA com instalação, offline-first e background sync"

# ✅ Recursos PWA:
# - Manifest completo
# - Service worker Workbox
# - Cache strategies
# - Background sync
# - Install prompt

🆕 Backend Especializados (4 Agentes)

# Golang Backend
claude-agents run golang-backend "criar API REST em Go com Gin, autenticação JWT e PostgreSQL"

# Node.js Backend
claude-agents run nodejs-backend "desenvolver API Node.js com Express, TypeScript e validação completa"

# NestJS Backend Enterprise
claude-agents run nestjs-backend "implementar microserviços NestJS com GraphQL, Redis e Docker"

# Supabase Backend-as-a-Service
claude-agents run supabase-backend "configurar Supabase com RLS policies, Edge Functions e Real-time"

# ✅ Features Automaticamente Incluídas:
# - Autenticação e autorização robusta
# - Validação de dados rigorosa
# - Documentação OpenAPI/Swagger
# - Testes automatizados (unit + integration)
# - Error handling padronizado
# - Rate limiting e security headers
# - Health checks e monitoring

🧠 Mesa Técnica para Decisões Complexas

# Análise técnica profunda
claude-agents run technical-roundtable "arquitetura para marketplace com 100k usuários, microservices vs monolito"

# ✅ Output:
# - 8 especialistas analisam (React, Backend, DevOps, Security, UX, PM, etc.)
# - 3 hipóteses técnicas distintas
# - 1 solução otimizada final
# - Decisão fundamentada com prós/contras

✅ Validação e Qualidade Automática

# Garantir qualidade enterprise
claude-agents run code-quality "revisar projeto inteiro aplicando ESLint, Prettier, TypeScript strict"
claude-agents run security "auditar código para vulnerabilidades OWASP Top 10"
claude-agents run playwright-validation "validar UI responsiva cross-browser com testes visuais"

# ✅ Quality Gates:
# - Zero erros de lint/tipos
# - Vulnerabilidades corrigidas
# - Testes UI passando
# - Performance otimizada

🚀 Pipeline Completo Automático

# Do conceito ao deploy
claude-agents run nlp-classifier "criar aplicação completa de blog com autenticação, CMS, comentários e analytics"

# ✅ Execução automática:
# 1. nlp-classifier: Analisa solicitação
# 2. github-flow: Cria issue + branch
# 3. technical-roundtable: Mesa técnica obrigatória
# 4. Pipeline fullstack_complete:
#    - database-schema: PostgreSQL + Prisma
#    - react-components: Interface completa
#    - redux-toolkit: Estado global
#    - rtk-query-api: APIs RESTful
#    - security: Auditoria OWASP
#    - playwright-validation: Testes UI
#    - docker-deployment: Deploy produção
# 5. github-pullrequest: PR com documentação

🎨 Fluxos Especializados

Design System Implementation

# Sistema de design completo
claude-agents run figma-extract "extrair tokens de design do Figma para componentes shadcn-ui"
claude-agents run tailwind-stylist "implementar tema customizado com paleta de cores e tipografia"
claude-agents run responsiveness "garantir adaptação perfeita mobile/tablet/desktop"

State Management Strategies 🆕

# Context API para estado simples/médio
claude-agents run context-api-manager "implementar theme provider com persistência localStorage"
claude-agents run context-api-manager "criar authentication context com JWT e refresh tokens"

# Redux para estado complexo
claude-agents run redux-toolkit "implementar store complexo para e-commerce com carrinho e checkout"

# Comparison e migração
claude-agents run technical-roundtable "analisar quando usar Context API vs Redux para aplicação específica"

Performance Optimization

# Otimização enterprise-grade
claude-agents run performance "analisar bundle, implementar lazy loading e code splitting"
claude-agents run animations "adicionar micro-interações smooth com framer-motion"
claude-agents run accessibility "garantir WCAG 2.1 AA compliance"

🆕 Monitoramento e Rollback

# Dashboard em tempo real WebSocket
claude-agents run realtime-monitor "ativar dashboard WebSocket para monitoramento live"

# 🎯 Interface de Monitoramento:
# - WebSocket Server: http://localhost:8080
# - Dashboard HTML: http://localhost:8081
# - Métricas em tempo real: performance, progress, errors
# - Visualização de pipelines: agents ativos, ETAs, status
# - Alertas automáticos: falhas, gargalos, otimizações

# Sistema de rollback inteligente
claude-agents run rollback-manager "criar checkpoint antes de mudanças críticas"
claude-agents rollback <checkpoint-id>  # Voltar ao estado anterior

# ✅ Features Dashboard:
# - Pipeline progress bars em tempo real
# - Agent execution timeline
# - Performance metrics (CPU, memory, tempo)
# - Error tracking e resolution suggestions
# - Resource usage optimization alerts

# Análise de custos e recursos
claude-agents run cost-analyzer "analisar custos de pipeline e sugerir otimizações"

🆕 Aprendizado e Extensibilidade

# Aprendizado cross-project
claude-agents run cross-project-learning "analisar padrões e sugerir reutilização de componentes"

# Sistema de plugins
claude-agents run plugin-manager "instalar plugin customizado de terceiros"
claude-plugins create my-agent --template=basic  # Criar agente customizado

# AI learning avançado
claude-agents run advanced-ai-learning "predizer problemas e sugerir melhorias baseado em ML"

🆕 Colaboração em Equipe

# Workspaces compartilhados
claude-agents run team-collaboration "configurar workspace compartilhado para equipe"
claude-agents run team-collaboration "compartilhar pipeline e knowledge base"

# Debugging colaborativo
claude-agents run team-collaboration "criar sessão de debugging compartilhada"

🧠 MCP Memory - Memória Persistente

# Contexto persistente entre sessões
claude-agents run mcp-memory-manager "lembrar decisões técnicas da mesa anterior"

# Personalização por desenvolvedor
claude-agents run mcp-memory-manager "adaptar sistema às minhas preferências"

# Knowledge cross-project
claude-agents run mcp-memory-manager "reutilizar solução validada do projeto anterior"

# Recovery instantâneo
claude-agents run mcp-memory-manager "recuperar contexto completo após crash"

# ✅ Benefícios MCP Memory:
# - 60% redução em decisões repetitivas
# - Recovery instantâneo de contexto
# - Personalização automática por desenvolvedor
# - Intelligence cross-project
# - Zero perda de contexto entre sessões

DevOps e Monitoramento

# Infraestrutura production-ready
claude-agents run docker-deployment "containerizar aplicação com multi-stage build e CI/CD"
claude-agents run metrics-collector "implementar monitoramento com métricas customizadas"
claude-agents run i-18-n "configurar suporte multi-idioma com react-i18next"

📈 Métricas e Monitoramento

O sistema coleta métricas opcionais (anônimas) para melhorias:

• Usage patterns: Agentes mais usados
• Performance: Tempos de execução por pipeline
• Success rates: Taxa de sucesso por agente
• Error patterns: Problemas mais frequentes

# Ver métricas locais
open ~/.claude/metrics-dashboard.html

# Configurar telemetria
claude-agents config --set telemetry=true

🎛️ Interface de Monitoramento

Dashboard WebSocket em Tempo Real

# Iniciar monitoramento
claude-agents run realtime-monitor "ativar dashboard completo"

# 📊 Acesso às interfaces:
# WebSocket Server: ws://localhost:8080
# Dashboard Visual: http://localhost:8081

🎯 Features da Interface:

Pipeline Progress View

┌─ Pipeline: fullstack_complete ─────────────┐
│ ✅ GitHub Flow      │ ✅ Tech Roundtable   │
│ 🟡 React Components │ ⏳ Tailwind         │
│ ⏸️  Performance     │ ⏸️  Security        │
│                                            │
│ ETA: 3 min remaining │ 67% complete       │
└────────────────────────────────────────────┘

Agent Execution Timeline

• Real-time status de cada agente
• Performance metrics (CPU, memória, tempo)
• Error detection com sugestões automáticas
• Resource optimization alerts
• Success/failure tracking por pipeline

Interactive Controls

• Pause/Resume pipelines em execução
• Quick retry para falhas com auto-fix
• Rollback buttons para checkpoints
• Performance tuning sliders
• Log streaming em tempo real

📱 Responsive Design

A interface funciona perfeitamente em:

• Desktop: Dashboard completo com múltiplas visualizações
• Tablet: Interface adaptada com painéis colapsáveis
• Mobile: View essencial com métricas principais

🤝 Contribuindo

Contribuições são bem-vindas!

# Fork do repositório
git clone https://github.com/saturnino-fabrica-de-software/claude-agents-global

# Desenvolvimento local
cd claude-agents-global
npm install
npm run dev

# Testes
npm run test
npm run validate

📄 Licença

MIT License - veja LICENSE para detalhes.

🔗 Links Úteis

• NPM: https://www.npmjs.com/package/@emerson-saturnino/claude-agents-global
• Repositório: https://github.com/saturnino-fabrica-de-software/agentes
• Issues: https://github.com/saturnino-fabrica-de-software/agentes/issues
• Changelog: https://github.com/saturnino-fabrica-de-software/agentes/releases

🎯 Sistema Enterprise-Grade com 31 agentes especializados 🧠 Mesa técnica obrigatória para decisões técnicas fundamentadas 🎭 Validação Playwright MCP automática em todos os frontends 🔄 Híbrido global-local com auto-detecção inteligente

Desenvolvido com ❤️ pela Saturnino Fábrica de Software