Antigravity Agents v1.0.0 🚀

Framework AI para código production-ready com validação OWASP, RLS, MFA e best practices automáticas

📦 Instalação

Pré-requisitos

• Node.js >= 18.0.0
• npm >= 9.0.0

Instalar o Pacote

npm install agents-gho-core

Instalar Dependências de Desenvolvimento (se necessário)

npm install --save-dev typescript @types/node ts-node

Estrutura de Diretórios

O framework criará automaticamente os seguintes diretórios:

seu-projeto/
├── data/              # Memórias dos agentes (auto-criado)
├── checkpoints/       # Checkpoints do sistema (auto-criado)
├── reports/           # Relatórios gerados (auto-criado)
└── .agent/
    └── skills/        # Skills dinâmicas (opcional)

🎯 O Que É?

Agents-GHO é um framework TypeScript de agentes autônomos especializados que trabalham em orquestração para gerar código de produção com OWASP security, RLS validation, MFA authentication e expertise em PHP, Python e React.

🎯 10 Agentes Especialistas

🏗️ Arquitetura Principal

❌ Sem Antigravity:

• IA gera código vulnerável (SQL injection, XSS)
• Ignora mobile-first e acessibilidade
• Não segue padrões do projeto
• Repete erros passados

✅ Com Antigravity:

• 10 agentes especialistas (Planning → Architecture → Security → Coding → Quality → Verification → Supabase → Auth → Python/PHP/React → Data → Infrastructure)
• **Memória individual Agora suportamos um Skills System dinâmico que permite aos agentes carregarem conhecimento especializado de arquivos .agent/skills/.

📚 Skills System

Cada agente pode carregar skills dinâmicas organizadas em 7 categorias:

• architecture/ - Design patterns, C4, System Design
• security/ - OWASP, Auth, API Security
• development/ - TypeScript, React, Python, PHP
• testing/ - TDD, Unit/Integration/E2E Tests
• data-ai/ - RAG, ML, ETL, Vector DBs
• infrastructure/ - Docker, K8s, CI/CD
• quality/ - Code quality, Metrics

Consulte: SKILLS_GUIDE.md para detalhes completos.

⚡ Quick Start

1. Criar Projeto TypeScript (novo projeto)

mkdir meu-projeto-agents
cd meu-projeto-agents
npm init -y
npm install agents-gho-core
npm install --save-dev typescript @types/node ts-node

# Criar tsconfig.json
npx tsc --init

2. Criar Script de Teste

Crie index.ts:

import { PlanningAgent } from 'agents-gho-core';
import { MemoryManager } from 'agents-gho-core';

async function main() {
  // Inicializar Memory Manager
  const memoryManager = new MemoryManager('./data');
  
  // Criar agente de planejamento
  const planningAgent = new PlanningAgent(memoryManager);
  
  // Criar uma task
  const task = {
    id: 'task-001',
    type: 'planning' as const,
    context: {
      description: 'Planejar arquitetura de API REST com autenticação JWT',
      metadata: {},
      priority: 'high' as const
    },
    status: 'pending' as const,
    createdAt: new Date(),
    updatedAt: new Date()
  };
  
  // Executar
  const result = await planningAgent.execute(task);
  
  console.log('Resultado:', result);
}

main().catch(console.error);

3. Executar

npx ts-node index.ts

4. Usar com Projeto Existente

cd seu-projeto-existente
npm install agents-gho-core

# Importar agentes conforme necessário

Exemplo de Uso em Projeto Existente:

import { SecurityAgent, CodingAgent, QualityAgent } from 'agents-gho-core';
import { MemoryManager } from 'agents-gho-core';

const memoryManager = new MemoryManager('./data');

// Usar agentes específicos
const securityAgent = new SecurityAgent(memoryManager);
const codingAgent = new CodingAgent(memoryManager);

// Executar validações
const securityResult = await securityAgent.execute(myTask);

3. IA Lê Documentação Automaticamente

A IA consulta:

• ARCHITECTURE.md - Ciclo mandatório
• AI_GUIDE.md - Regras críticas
• FRONTEND_DESIGN.md - Mobile-first, A11y
• SUPABASE_GUIDE.md - RLS policies
• AUTH_SECURITY_GUIDE.md - MFA, JWT, Argon2id
• data/memory-*.json - Experiências passadas

🤖 Agentes Disponíveis

| Agente | Responsabilidade | Output | |--------|------------------|--------| | PlanningAgent | Arquitetura, dependências | PlanOutput | | VerificationAgent | Validação de planos | passed, issues[] | | CodingAgent | Geração de código | files[] | | QualityAgent | Code smells, complexity | metrics | | SecurityAgent | OWASP Top 10 | issues[], riskScore | | SupabaseAgent | RLS, migrations | checks[], score | | AuthAgent | MFA, JWT, CSP, PCI DSS | issues[], paymentScore |

• Multi-Factor Authentication (TOTP, WebAuthn)
• JWT best practices
• Content Security Policy (CSP)
• PCI DSS Level 1 compliance

💻 Especialistas em Linguagens

8. PHPAgent - Laravel, Symfony, PSR, Modern PHP 8+
   • ✅ Best for: Web APIs, CRUD, Backoffice, Auth Web
   • Laravel/Symfony frameworks
   • PSR standards (PSR-1, PSR-2, PSR-4, PSR-12)
   • Security: SQL injection, XSS, CSRF
9. PythonAgent - Django, FastAPI, PEP 8, Type Hints
   • ✅ Best for: IA/ML, ETL, Workers, Heavy Processing
   • Django/FastAPI/Flask frameworks
   • PEP 8 compliance
   • Security: pickle, eval, yaml.load
10. ReactAgent - Next.js, Hooks, Performance, A11y
    • React 18+ (hooks, concurrent, suspense)
    • Next.js 14+ (app router)
    • Performance (memo, lazy loading)
    • Accessibility (ARIA, semantic HTML)

🆕 Novos Agentes Especializados (v1.1.0)

ArchitectureAgent - Design de arquitetura e sistemas

• Clean Architecture, DDD, Hexagonal
• Diagramas C4 (Context, Container, Component)
• ADRs (Architecture Decision Records)
• Skills: architecture/*

DataAgent - AI/ML e Data Engineering

• RAG (Retrieval Augmented Generation)
• ETL pipelines e data processing
• Vector databases (Pinecone, Weaviate)
• Query optimization
• Skills: data-ai/*

InfrastructureAgent - DevOps e Cloud

• Docker/Kubernetes deployment
• CI/CD pipelines (GitHub Actions, GitLab CI)
• Cloud deployment (AWS, Vercel)
• Monitoring e observability
• Skills: infrastructure/*

📊 Regra de Ouro: PHP vs Python

| Função | PHP | Python | |------------------------|------------|------------| | API REST simples | ✅ Excelente | ✅ Excelente | | CRUD / Backoffice | ✅ Excelente | ⚠️ Ok | | Auth web | ✅ Excelente | ⚠️ Ok | | Jobs / cron | ⚠️ Limitado | ✅ Excelente | | IA / ML | ❌ Ruim | ✅ Excelente | | ETL / CSV / Relatórios | ⚠️ Médio | ✅ Excelente | | Deploy simples | ✅ Muito fácil | ⚠️ Médio | | Escalar workers | ⚠️ Médio | ✅ Excelente |

Memorize: PHP = servir a web | Python = processar coisas

📚 Documentação para IAs

Regras Absolutas

1. Ler memória ANTES de executar

const experiences = await this.getRelevantExperiences(task);

2. Limite de 500 linhas por arquivo

// Se exceder → dividir em múltiplos arquivos

3. Ciclo mandatório

Planning → Verification → Coding → Quality → Security

4. Nunca alucinar

// ❌ NÃO inventar APIs/tabelas/configs
// ✅ Consultar: código + memórias + docs

🛡️ SecurityAgent - OWASP Expert

Detecta

• A01: Broken Access Control
• A02: Cryptographic Failures (hardcoded secrets)
• A03: Injection (SQL, XSS, Command)
• A07: Auth Failures
• A10: SSRF

Exemplo

// Código vulnerável
const query = `SELECT * FROM users WHERE id = ${req.params.id}`; // ❌ SQL Injection

// SecurityAgent detecta:
{
  type: 'sql_injection',
  severity: 'critical',
  description: 'SQL injection vulnerability detected',
  mitigation: 'Use parameterized queries or ORM',
  owaspCategory: 'A03:2021'
}

🗄️ SupabaseAgent - RLS Validator

Valida

• ✅ RLS habilitado em todas as tables
• ✅ Policies criadas (SELECT/INSERT/UPDATE/DELETE)
• ✅ Migrations versionadas (CLI)
• ✅ Nenhum hardcoded secret
• ✅ Índices em colunas de busca

Exemplo

-- ❌ Table sem RLS
CREATE TABLE public.users (...);

-- SupabaseAgent detecta:
{
  type: 'missing_rls',
  severity: 'critical',
  description: 'Table public.users does not have RLS enabled',
  mitigation: 'ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;'
}

🔐 AuthAgent - MFA/JWT/PCI DSS

Valida

• ✅ Senhas hashadas com Argon2id
• ✅ JWT com expiração ≤15min
• ✅ MFA implementado (TOTP)
• ✅ HTTP-only cookies (previne XSS)
• ✅ CSP configurado
• ✅ Rate limiting (5 tentativas/15min)
• ✅ Nenhum card data armazenado

Exemplo

// ❌ Código inseguro
const token = jwt.sign({ email }, 'secret', { expiresIn: '7d' });
localStorage.setItem('token', token);

// AuthAgent detecta:
{
  issues: [
    {
      type: 'jwt_insecure',
      severity: 'critical',
      description: 'JWT with long expiry (7d)',
      mitigation: 'Use expiresIn: 15m'
    },
    {
      type: 'token_in_localstorage',
      severity: 'high',
      description: 'Token in localStorage (XSS vulnerable)',
      mitigation: 'Use HTTP-only cookies'
    }
  ]
}

🎨 Frontend Design - Mobile-First

Best Practices Automáticas

/* ✅ Mobile-first (regra obrigatória) */
.container {
  width: 100%;
}

@media (min-width: 768px) {
  .container { width: 768px; }
}

/* ✅ Botões touch-friendly */
.btn {
  min-width: 44px;
  min-height: 44px;
}

/* ✅ Tipografia legível */
body {
  font-size: 16px; /* Mínimo em mobile */
}

Repositórios GitHub integrados:

• Bootstrap (167k⭐)
• React (209k⭐)
• Flutter (160k⭐)

📊 Exemplo de Fluxo

Comando: "Quero que melhore o home da página"

graph TD
    A[Comando] --> B[PlanningAgent]
    B --> C[VerificationAgent]
    C --> D[CodingAgent]
    D --> E[QualityAgent]
    E --> F[SecurityAgent]
    F --> G{Vulnerabilities?}
    G -->|Não| H[GitManager]
    G -->|Sim| I[Bloqueia]
    H --> J[Homepage melhorada ✅]

Output:

• components/Hero.tsx (180 linhas)
• styles/hero.css (120 linhas)
• Git commit automático
• Memórias salvas

Regras aplicadas:

• ✅ Mobile-first (FRONTEND_DESIGN.md)
• ✅ Botões ≥44x44px
• ✅ Fonte ≥16px
• ✅ A11y (contraste 4.5:1)
• ✅ OWASP scan (0 issues)

🧠 Memória Individual

Cada agente tem seu próprio JSON:

// data/memory-agent-security-001.json
{
  "agentId": "agent-security-001",
  "entries": [
    {
      "taskId": "scan-homepage",
      "success": true,
      "output": {
        "issues": [],
        "riskScore": 0
      },
      "keywords": ["security", "owasp", "clean"]
    }
  ]
}

Próxima execução: Agent consulta memória e aprende!

🔧 Configuração

.env

# Git (opcional)
GIT_AUTO_COMMIT=true
GIT_COMMIT_PREFIX="feat: "

# AI Adapter (opcional)
AI_ADAPTER_ENABLED=false

# Supabase (se usar SupabaseAgent)
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=your-key

📖 Documentação Completa

• ARCHITECTURE.md - Sistema completo
• AI_GUIDE.md - Guia rápido
• FRONTEND_DESIGN.md - Best practices web/mobile
• SUPABASE_GUIDE.md - RLS + migrations
• AUTH_SECURITY_GUIDE.md - MFA + JWT + PCI DSS
• EXEMPLO_FLUXO.md - Demonstração prática

🧪 Testes

# Build e testes completos
npm test

# Teste rápido
npm run test:quick

# Testar memória individual
npm run test:memory

# Testar SecurityAgent
npm run test:security

📝 Changelog

v1.0.0 (2026-02-04)

Agents:

• ✅ PlanningAgent - Arquitetura
• ✅ SecurityAgent - OWASP Top 10 (600+ patterns)
• ✅ CodingAgent - Geração de código
• ✅ QualityAgent - Code quality
• ✅ VerificationAgent - Validação
• ✅ SupabaseAgent - RLS validator
• ✅ AuthAgent - MFA/JWT/CSP/PCI DSS

Features:

• ✅ Memória individual por agente
• ✅ Leitura de memória ANTES de executar
• ✅ 9 arquivos MD de documentação
• ✅ Build aprovado (0 erros)
• ✅ Testado com troca de IA (Claude → Gemini)

Documentação:

• 500+ linhas AUTH_SECURITY_GUIDE.md
• EXEMPLO_FLUXO.md demonstrando ciclo completo
• AGENT.md individual para cada agente

🤝 Contribuindo

# Fork o repositório
git clone https://github.com/seu-usuario/agents
cd agents

# Instalar dependências
npm install

# Desenvolver
npm run dev

# Testar
npm test

# Build
npm run build

📄 Licença

MIT © Antigravity Team

🌟 Destaques

• 7 agentes validadores trabalhando em ciclo
• Memória individual: cada agente aprende
• OWASP compliant: 0 vulnerabilidades
• PCI DSS: pagamentos seguros
• Mobile-first: A11y by design
• RLS validator: Supabase seguro
• Testado: funciona com qualquer IA

Instale agora e deixe a IA codificar com padrão de produção! 🚀