AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

🌐 README por idioma: EN | PT | ES | ZH

Devolvendo às pessoas o poder de criar — Framework open source de orquestração de IA que devolve o controle a quem tem coragem de construir. Agentes especializados, workflows e experiência CLI First para qualquer domínio.

Novo namespace npm: @aiox-squads/core é o sucessor de aiox-core sem scope. O conteúdo é o mesmo framework AIOX; o novo namespace reflete a consolidação dos squads sob @aiox-squads/*. Os comandos de CLI, incluindo aiox-core, permanecem preservados durante a transição.

Comece Aqui (10 Min)

Se é sua primeira vez no AIOX, siga este caminho linear:

1. Instale em um projeto novo ou existente:

# novo projeto
npx aiox-core init meu-projeto

# projeto existente
cd seu-projeto
npx aiox-core install

1. Escolha sua IDE/CLI e o caminho de ativação:

2. Claude Code: /agent-name

3. Gemini CLI: /aiox-menu → /aiox-<agent>
4. Codex CLI: /skills → aiox-<agent-id>

5. Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md

6. Ative 1 agente e confirme o greeting.

7. Rode 1 comando inicial (*help ou equivalente) para validar first-value.

Definição de first-value (binária): ativação de agente + greeting válido + comando inicial com output útil em <= 10 minutos.

Compatibilidade de Hooks por IDE (Realidade AIOX 4.2)

Muitos recursos avançados do AIOX dependem de eventos de ciclo de vida (hooks). A tabela abaixo mostra a paridade real entre IDEs/plataformas:

IDE/CLI	Paridade de Hooks vs Claude	Impacto Prático
Claude Code	Completa (referência)	Automação máxima de contexto, guardrails e auditoria
Gemini CLI	Alta (eventos nativos)	Cobertura forte de automações pre/post tool e sessão
Codex CLI	Parcial/limitada	Parte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
Cursor	Sem lifecycle hooks equivalentes	Menor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub Copilot	Sem lifecycle hooks equivalentes	Menor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravity	Workflow-based (não hook-based)	Integração por workflows, não por eventos de hook equivalentes ao Claude

Impactos e mitigação detalhados: docs/ide-integration.md.

Visão Geral

Premissa Arquitetural: CLI First

O AIOX segue uma hierarquia clara de prioridades:

CLI First → Observability Second → UI Third

Camada	Prioridade	Foco	Exemplos
CLI	Máxima	Onde a inteligência vive. Toda execução, decisões e automação acontecem aqui.	Agentes (@dev, @qa), workflows, comandos
Observability	Secundária	Observar e monitorar o que acontece no CLI em tempo real.	Dashboard SSE, logs, métricas, timeline
UI	Terciária	Gestão pontual e visualizações quando necessário.	Kanban, settings, story management

Princípios derivados:

• A CLI é a fonte da verdade - dashboards apenas observam
• Funcionalidades novas devem funcionar 100% via CLI antes de ter UI
• A UI nunca deve ser requisito para operação do sistema
• Observabilidade serve para entender o que o CLI está fazendo, não para controlá-lo

---

As Duas Inovações Chave do AIOX:

1. Planejamento Agêntico: Agentes dedicados (analyst, pm, architect) colaboram com você para criar documentos de PRD e Arquitetura detalhados e consistentes. Através de engenharia avançada de prompts e refinamento com human-in-the-loop, estes agentes de planejamento produzem especificações abrangentes que vão muito além da geração genérica de tarefas de IA.

2. Desenvolvimento Contextualizado por Engenharia: O agente sm (Scrum Master) então transforma estes planos detalhados em histórias de desenvolvimento hiperdetalhadas que contêm tudo que o agente dev precisa - contexto completo, detalhes de implementação e orientação arquitetural incorporada diretamente nos arquivos de histórias.

Esta abordagem de duas fases elimina tanto a inconsistência de planejamento quanto a perda de contexto - os maiores problemas no desenvolvimento assistido por IA. Seu agente dev abre um arquivo de história com compreensão completa do que construir, como construir e por quê.

📖 Veja o fluxo de trabalho completo no Guia do Usuário - Fase de planejamento, ciclo de desenvolvimento e todos os papéis dos agentes

Pré-requisitos

• Node.js >=18.0.0 (v20+ recomendado)
• npm >=9.0.0
• GitHub CLI (opcional, necessário para colaboração em equipe)

Problemas de instalação? Consulte o Guia de Troubleshooting

Guias específicos por plataforma:

• 📖 Guia de Instalação para macOS
• 📖 Guia de Instalação para Windows
• 📖 Guia de Instalação para Linux

Documentação multilíngue disponível: English | Português | Español | 中文

Navegação Rápida

Entendendo o Fluxo de Trabalho AIOX

Antes de mergulhar, revise estes diagramas críticos de fluxo de trabalho que explicam como o AIOX funciona:

1. Fluxo de Planejamento (Interface Web) - Como criar documentos de PRD e Arquitetura
2. Ciclo Principal de Desenvolvimento (IDE) - Como os agentes sm, dev e qa colaboram através de arquivos de histórias

⚠️ Estes diagramas explicam 90% da confusão sobre o fluxo AIOX Agentic Agile - Entender a criação de PRD+Arquitetura e o fluxo de trabalho sm/dev/qa e como os agentes passam notas através de arquivos de histórias é essencial - e também explica por que isto NÃO é taskmaster ou apenas um simples executor de tarefas!

O que você gostaria de fazer?

• Instalar e Construir software com Equipe Ágil Full Stack de IA → Instruções de Início Rápido
• Aprender como usar o AIOX → Guia completo do usuário e passo a passo
• Ver agentes IA disponíveis → Papéis especializados para sua equipe
• Explorar usos não técnicos → Escrita criativa, negócios, bem-estar, educação
• Criar meus próprios agentes IA → Construir agentes para seu domínio
• Navegar Squads prontos → Veja como criar e usar equipes de agentes IA
• Entender a arquitetura → Mergulho técnico profundo
• Reportar problemas → Bug reports e feature requests

Importante: Mantenha Sua Instalação AIOX Atualizada

Mantenha-se atualizado sem esforço! Para atualizar sua instalação AIOX existente:

npx aiox-core@latest install

Isto vai:

• ✅ Detectar automaticamente sua instalação existente
• ✅ Atualizar apenas os arquivos que mudaram
• ✅ Criar arquivos de backup .bak para quaisquer modificações customizadas
• ✅ Preservar suas configurações específicas do projeto

Isto facilita beneficiar-se das últimas melhorias, correções de bugs e novos agentes sem perder suas customizações!

Início Rápido

🚀 Instalação via NPX (Recomendado)

Instale o AIOX com um único comando:

# Criar um novo projeto com assistente interativo moderno
npx aiox-core init meu-projeto

# Ou instalar em projeto existente
cd seu-projeto
npx aiox-core install

# Ou usar uma versão específica
npx aiox-core@latest init meu-projeto

✨ Assistente de Instalação Moderno

O AIOX agora inclui uma experiência de instalação interativa de última geração, inspirada em ferramentas modernas como Vite e Next.js:

Recursos do Instalador Interativo:

• 🎨 Interface Moderna: Prompts coloridos e visuais com @clack/prompts
• ✅ Validação em Tempo Real: Feedback instantâneo sobre entradas inválidas
• 🔄 Indicadores de Progresso: Spinners para operações longas (cópia de arquivos, instalação de deps)
• 📦 Seleção Multi-Componente: Escolha quais componentes instalar com interface intuitiva
• ⚙️ Escolha de Gerenciador de Pacotes: Selecione entre npm, yarn ou pnpm
• ⌨️ Suporte a Cancelamento: Ctrl+C ou ESC para sair graciosamente a qualquer momento
• 📊 Resumo de Instalação: Visualize todas as configurações antes de prosseguir
• ⏱️ Rastreamento de Duração: Veja quanto tempo levou a instalação

O instalador oferece:

• ✅ Download da versão mais recente do NPM
• ✅ Assistente de instalação interativo moderno
• ✅ Configuração automática do IDE (Codex CLI, Cursor ou Claude Code)
• ✅ Configuração de todos os agentes e fluxos de trabalho AIOX
• ✅ Criação dos arquivos de configuração necessários
• ✅ Inicialização do sistema de meta-agentes
• ✅ Verificações de saúde do sistema
• ✅ Suporte Cross-Platform: Testado em Windows, macOS e Linux

É isso! Sem clonar, sem configuração manual - apenas um comando e você está pronto para começar com uma experiência de instalação moderna e profissional.

Pré-requisitos: Node.js v18+ necessário (v20+ recomendado) | Troubleshooting

Atualizando uma Instalação Existente

Se você já tem o AIOX instalado:

npx aiox-core@latest install
# O instalador detectará sua instalação existente e a atualizará

Configure Seu IDE para Desenvolvimento AIOX

O AIOX inclui regras pré-configuradas para IDE para melhorar sua experiência de desenvolvimento:

Para Cursor:

1. Abra as configurações do Cursor
2. Navegue até User Rules
3. Copie o conteúdo de .cursor/global-rules.md
4. Cole na seção de regras e salve

Para Claude Code:

• ✅ Já configurado! O arquivo .claude/CLAUDE.md é carregado automaticamente
• Sync dedicado de agentes: npm run sync:ide:claude
• Validacao dedicada: npm run validate:claude-sync && npm run validate:claude-integration

Para Codex CLI:

• ✅ Integração de primeira classe no AIOX 4.2 (pipeline de ativação e greeting compartilhado)
• ✅ Já configurado! O arquivo AGENTS.md na raiz é carregado automaticamente
• Opcional: sincronize agentes auxiliares com npm run sync:ide:codex
• Recomendado neste repositório: gerar e versionar skills locais com npm run sync:skills:codex
• Use npm run sync:skills:codex:global apenas fora deste projeto (para evitar duplicidade no /skills)
• Validacao dedicada: npm run validate:codex-sync && npm run validate:codex-integration
• Guardrails de skills/paths: npm run validate:codex-skills && npm run validate:paths

Para Gemini CLI:

• ✅ Regras e agentes sincronizaveis com npm run sync:ide:gemini
• Arquivos gerados em .gemini/rules.md, .gemini/rules/AIOX/agents/ e .gemini/commands/*.toml
• ✅ Hooks e settings locais no fluxo de instalacao (.gemini/hooks/ + .gemini/settings.json)
• ✅ Ativacao rapida por slash commands (/aiox-menu, /aiox-dev, /aiox-architect, etc.)
• Validacao dedicada: npm run validate:gemini-sync && npm run validate:gemini-integration
• Paridade multi-IDE em um comando: npm run validate:parity

Estas regras fornecem:

• 🤖 Reconhecimento e integração de comandos de agentes
• 📋 Fluxo de trabalho de desenvolvimento dirigido por histórias
• ✅ Rastreamento automático de checkboxes
• 🧪 Padrões de teste e validação
• 📝 Padrões de código específicos do AIOX

Início Mais Rápido com Interface Web (2 minutos)

1. Instale o AIOX: Execute npx aiox-core init meu-projeto
2. Configure seu IDE: Siga as instruções de configuração para Codex CLI, Cursor ou Claude Code
3. Comece a Planejar: Ative um agente como @analyst para começar a criar seu briefing
4. Use comandos AIOX: Digite *help para ver comandos disponíveis
5. Siga o fluxo: Veja o Guia do usuário para mais detalhes

Referência de Comandos CLI

O AIOX oferece uma CLI