Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Force GitHub README to respect dark mode (function() { var style = document.createElement('style'); style.textContent = ' .markdown-body { color-scheme: dark light; } .markdown-body pre { background: #161b22 !important; } .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; } .markdown-body table th, .markdown-body table td { border-color: #30363d !important; } .markdown-body img { background: #0d1117; } .markdown-body blockquote { border-left-color: #8b949e; } .markdown-body hr { border-color: #30363d; } '; document.head.appendChild(style); })(); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Highlight search terms from Google/DuckDuckGo/Bing referrer (function() { var ref = document.referrer; var terms = []; if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) { var url = new URL(ref); var q = url.searchParams.get('q') || url.searchParams.get('p'); if (q) { terms = q.split(/\s+/).filter(function(t) { return t.length > 2; }); } } if (terms.length === 0) return; var style = document.createElement('style'); style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }'; document.head.appendChild(style); function highlight(node) { if (node.nodeType === 3) { // text node var text = node.textContent; var found = false; terms.forEach(function(term) { var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ' GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ' GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Universal Dark Mode - works on any site (function() { var enabled = true; function applyDarkMode() { if (!enabled) return; // Create style element if it doesn't exist var style = document.getElementById('universal-dark-mode-style'); if (!style) { style = document.createElement('style'); style.id = 'universal-dark-mode-style'; document.head.appendChild(style); } // Dark mode CSS - inverts colors but preserves images/video style.textContent = ' /* Invert everything except media */ html { filter: invert(1) hue-rotate(180deg) !important; background: #1a1a2e !important; } /* Restore images, videos, iframes, canvas */ img, video, iframe, canvas, svg, picture, [style*="background-image"] { filter: invert(1) hue-rotate(180deg) !important; } /* Preserve specific elements that should not be inverted */ .no-dark-mode, .no-dark-mode *, [data-theme="light"], [data-theme="light"], .ace_editor, .ace_editor *, .CodeMirror, .CodeMirror *, .monaco-editor, .monaco-editor *, .markdown-body pre, .markdown-body pre *, .highlight, .highlight *, pre code, pre code * { filter: none !important; } /* Fix common UI elements */ .modal, .popup, .dropdown-menu, .tooltip, .popover { filter: invert(1) hue-rotate(180deg) !important; background: #2d2d44 !important; border-color: #444 !important; } /* Scrollbars */ ::-webkit-scrollbar { background: #1a1a2e !important; } ::-webkit-scrollbar-thumb { background: #444 !important; } ::-webkit-scrollbar-thumb:hover { background: #555 !important; } /* Selection */ ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; } ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; } '; } function removeDarkMode() { var style = document.getElementById('universal-dark-mode-style'); if (style) style.remove(); } // Toggle with Alt+Shift+D document.addEventListener('keydown', function(e) { if (e.altKey && e.shiftKey && e.key === 'D') { e.preventDefault(); enabled = !enabled; if (enabled) { applyDarkMode(); console.log('[Universal Dark Mode] Enabled'); } else { removeDarkMode(); console.log('[Universal Dark Mode] Disabled'); } } }); // Apply on load applyDarkMode(); // Re-apply on dynamic content var observer = new MutationObserver(function(mutations) { if (enabled && !document.getElementById('universal-dark-mode-style')) { applyDarkMode(); } }); observer.observe(document.head, { childList: true }); console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle'); })(); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })(); GitHub - SynkraAI/aiox-core: Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0 · GitHub
Skip to content

Latest commit

History

964 Commits

Folders and files

NameName
Last commit message
Last commit date

Repository files navigation

AIOX Squad: Artificial Intelligence Orchestration eXperience

🌍 English | Português

Versão NPMLicença: MITVersão Node.jsCIcodecovDocumentaçãoOpen SourceContributions WelcomeCode of Conduct

🌐 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 existentecd seu-projeto
npx aiox-core install
  1. Escolha sua IDE/CLI e o caminho de ativação:
  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu/aiox-<agent>
  • Codex CLI: /skillsaiox-<agent-id>
  • Cursor/Copilot/AntiGravity: siga os limites e workarounds em docs/ide-integration.md
  1. Ative 1 agente e confirme o greeting.
  2. 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/CLIParidade de Hooks vs ClaudeImpacto Prático
Claude CodeCompleta (referência)Automação máxima de contexto, guardrails e auditoria
Gemini CLIAlta (eventos nativos)Cobertura forte de automações pre/post tool e sessão
Codex CLIParcial/limitadaParte das automações depende de AGENTS.md, /skills, MCP e fluxo operacional
CursorSem lifecycle hooks equivalentesMenor automação de pre/post tool; foco em regras, MCP e fluxo do agente
GitHub CopilotSem lifecycle hooks equivalentesMenor automação de sessão/tooling; foco em instruções de repositório + MCP no VS Code
AntiGravityWorkflow-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
CamadaPrioridadeFocoExemplos
CLIMáximaOnde a inteligência vive. Toda execução, decisões e automação acontecem aqui.Agentes (@dev, @qa), workflows, comandos
ObservabilitySecundáriaObservar e monitorar o que acontece no CLI em tempo real.Dashboard SSE, logs, métricas, timeline
UITerciáriaGestã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:

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?

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 existentecd 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 moderna e cross-platform com comandos intuitivos:

# Gerenciamento de Projeto (com assistente interativo)
npx aiox-core init <nome-projeto> [opções]
--force Forçar criação em diretório não vazio
--skip-install Pular instalação de dependências npm
--template <nome> Usar template específico (default, minimal, enterprise)
# Instalação e Configuração (com prompts modernos)
npx aiox-core install [opções]
--force Sobrescrever configuração existente
--quiet Saída mínima durante instalação
--dry-run Simular instalação sem modificar arquivos
# Comandos do Sistema
npx aiox-core --version Exibir versão instalada
npx aiox-core --help Exibir ajuda detalhada
npx aiox-core info Exibir informações do sistema
npx aiox-core doctor Executar diagnósticos do sistema
npx aiox-core doctor --fix Corrigir problemas detectados automaticamente
# Manutenção
npx aiox-core update Atualizar para versão mais recente
npx aiox-core uninstall Remover AIOX

Recursos da CLI:

  • Help System Abrangente: --help em qualquer comando mostra documentação detalhada
  • Validação de Entrada: Feedback imediato sobre parâmetros inválidos
  • Mensagens Coloridas: Erros em vermelho, sucessos em verde, avisos em amarelo
  • Cross-Platform: Funciona perfeitamente em Windows, macOS e Linux
  • Suporte a Dry-Run: Teste instalações sem modificar arquivos

💡 Exemplos de Uso

Instalação Interativa Completa

$ npx aiox-core install
🚀 AIOX Installation
◆ What is your project name?
│ my-awesome-project
│
◇ Which directory should we use?
│ ./my-awesome-project
│
◆ Choose components to install:
│ ● Core Framework (Required)
│ ● Agent System (Required)
│ ● Squads (optional)
│ ○ Example Projects (optional)
│
◇ Select package manager:
│ ● npm
│ ○ yarn
│ ○ pnpm
│
◆ Initialize Git repository?
│ Yes
│
◆ Install dependencies?
│ Yes
│
▸ Creating project directory...
▸ Copying framework files...
▸ Initializing Git repository...
▸ Installing dependencies (this may take a minute)...
▸ Configuring environment...
▸ Running post-installation setup...
✔ Installation completed successfully! (34.2s)
Next steps:
cd my-awesome-project
aiox-core doctor # Verify installation
aiox-core --help # See available commands

Instalação Silenciosa (CI/CD)

# Instalação automatizada sem prompts
$ npx aiox-core install --quiet --force
✔ AIOX installed successfully

Simulação de Instalação (Dry-Run)

# Testar instalação sem modificar arquivos
$ npx aiox-core install --dry-run
[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aiox-core/ (45 files)
[DRY RUN] Would initialize: Git repository
[DRY RUN] Would install: npm dependencies
✔ Dry run completed - no files were modified

Diagnóstico do Sistema

$ npx aiox-core doctor
🏥 AIOX System Diagnostics
✔ Node.js version: v20.10.0 (meets requirement: >=18.0.0)
✔ npm version: 10.2.3
✔ Git installed: version 2.43.0
✔ GitHub CLI: gh 2.40.1
✔ AIOX: v4.2.11
Configuration:
✔ .aiox-core/ directory exists
✔ Agent files: 11 found
✔ Workflow files: 8 found
✔ Templates: 15 found
Dependencies:
✔ @clack/prompts: ^0.7.0
✔ commander: ^12.0.0
✔ execa: ^9.0.0
✔ fs-extra: ^11.0.0
✔ picocolors: ^1.0.0
✅ All checks passed! Your installation is healthy.

Obter Ajuda

$ npx aiox-core --help
Usage: aiox-core [options] [command]
AIOX: AI-Orchestrated System for Full Stack Development
Options:
-V, --version output the version number
-h, --help display helpforcommand
Commands:
init <project-name> Create new AIOX project with interactive wizard
install [options] Install AIOX in current directory
info Display system information
doctor [options] Run system diagnostics and health checks
help [command] display helpforcommand
Run 'aiox-core <command> --help'for detailed information about each command.

Alternativa: Clonar e Construir

Para contribuidores ou usuários avançados que queiram modificar o código fonte:

# Clonar o repositório
git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
# Instalar dependências
npm install
# Executar o instalador
npm run install:aiox

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

# Instalar AIOX no projeto
npx aiox-core@latest install
# Isto vai:# 1. Detectar instalação existente (se houver)# 2. Instalar/atualizar framework AIOX# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOX funciona em QUALQUER domínio. Os Squads fornecem agentes IA especializados para escrita criativa, estratégia de negócios, saúde e bem-estar, educação e muito mais. Além disso, os Squads podem expandir o núcleo do AIOX com funcionalidade específica que não é genérica para todos os casos. Veja o Guia de Squads e aprenda a criar os seus próprios!

Agentes Disponíveis

O AIOX vem com 12 agentes especializados:

Agentes Meta

  • aiox-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
  • aiox-orchestrator - Orquestrador de fluxo de trabalho e coordenação de equipe

Agentes de Planejamento (Interface Web)

  • analyst - Especialista em análise de negócios e criação de PRD
  • pm (Product Manager) - Gerente de produto e priorização
  • architect - Arquiteto de sistema e design técnico
  • ux-expert - Design de experiência do usuário e usabilidade

Agentes de Desenvolvimento (IDE)

  • sm (Scrum Master) - Gerenciamento de sprint e criação de histórias
  • dev - Desenvolvedor e implementação
  • qa - Garantia de qualidade e testes
  • po (Product Owner) - Gerenciamento de backlog e histórias
  • data-engineer - Design de banco de dados e modelagem de dados
  • devops - CI/CD, infraestrutura e operações git (autoridade exclusiva de push)

Documentação e Recursos

Guias Essenciais

  • 📖 Guia do Usuário - Passo a passo completo desde a concepção até a conclusão do projeto
  • 🏗️ Arquitetura Principal - Mergulho técnico profundo e design do sistema
  • 🚀 Guia de Squads - Estenda o AIOX para qualquer domínio além do desenvolvimento de software

Documentação Adicional

🤖 AIOX Autonomous Development Engine (ADE)

O AIOX introduz o Autonomous Development Engine (ADE) - um sistema completo para desenvolvimento autônomo que transforma requisitos em código funcional.

🎯 O Que é o ADE?

O ADE é um conjunto de 7 Epics que habilitam execução autônoma de desenvolvimento:

EpicNomeDescrição
1Worktree ManagerIsolamento de branches via Git worktrees
2Migration V2→V3Migração para formato autoClaude V3
3Spec PipelineTransforma requisitos em specs executáveis
4Execution EngineExecuta specs com 13 steps + self-critique
5Recovery SystemRecuperação automática de falhas
6QA EvolutionReview estruturado em 10 fases
7Memory LayerMemória persistente de padrões e insights

🔄 Fluxo Principal

User Request → Spec Pipeline → Execution Engine → QA Review → Working Code
↓
Recovery System
↓
Memory Layer

⚡ Quick Start ADE

# 1. Criar spec a partir de requisito
@pm *gather-requirements
@architect *assess-complexity
@analyst *research-deps
@pm *write-spec
@qa *critique-spec
# 2. Executar spec aprovada
@architect *create-plan
@architect *create-context
@dev *execute-subtask 1.1
# 3. QA Review
@qa *review-build STORY-42

📖 Documentação ADE

🆕 Novos Comandos por Agente

@devops:

  • *create-worktree, *list-worktrees, *merge-worktree, *cleanup-worktrees
  • *inventory-assets, *analyze-paths, *migrate-agent, *migrate-batch

@pm:

  • *gather-requirements, *write-spec

@architect:

  • *assess-complexity, *create-plan, *create-context, *map-codebase

@analyst:

  • *research-deps, *extract-patterns

@qa:

  • *critique-spec, *review-build, *request-fix, *verify-fix

@dev:

  • *execute-subtask, *track-attempt, *rollback, *capture-insights, *list-gotchas, *apply-qa-fix

Criando Seu Próprio Squad

Squads permitem estender o AIOX para qualquer domínio. Estrutura básica:

squads/seu-squad/
├── config.yaml # Configuração do squad
├── agents/ # Agentes especializados
├── tasks/ # Fluxos de trabalho de tarefas
├── templates/ # Templates de documentos
├── checklists/ # Checklists de validação
├── data/ # Base de conhecimento
├── README.md # Documentação do squad
└── user-guide.md # Guia do usuário

Veja o Guia de Squads para instruções detalhadas.

Squads Disponíveis

Squads são equipes modulares de agentes IA. Veja a Visão Geral de Squads para mais informações.

Squads Externos

  • hybrid-ops - Operações híbridas humano-agente (repositório separado)

AIOX Pro

O AIOX Pro é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

Disponibilidade restrita: O AIOX Pro está disponível exclusivamente para membros do AIOX Cohort Advanced. Saiba mais sobre o programa.

Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consulte o Guia de Acesso ao AIOX Pro.

Instalação

npx -y -p @aiox-squads/core@latest aiox pro setup

Identificação Estável de Máquina (>= 5.0.8)

O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar machineId, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.

Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.

Features Premium

  • Squads Avançados - Squads especializados com capacidades expandidas
  • Memory Layer - Memória persistente de padrões e insights entre sessões
  • Métricas & Analytics - Dashboard de produtividade e métricas de desenvolvimento
  • Integrações Enterprise - Conectores para Jira, Linear, Notion e mais
  • Configuração em Camadas - Sistema de configuração L1-L4 com herança
  • Licenciamento - Gerenciamento de licença via aiox pro activate --key <KEY>

Para mais informações, execute npx aiox-core pro --help após a instalação.

Suporte

Git Workflow e Validação

O AIOX implementa um sistema de validação de múltiplas camadas para garantir qualidade do código e consistência:

🛡️ Defense in Depth - 3 Camadas de Validação

Camada 1: Pre-commit (Local - Rápida)

  • ✅ ESLint - Qualidade de código
  • ✅ TypeScript - Verificação de tipos
  • ⚡ Performance: <5s
  • 💾 Cache habilitado

Camada 2: Pre-push (Local - Validação de Stories)

  • ✅ Validação de checkboxes de histórias
  • ✅ Consistência de status
  • ✅ Seções obrigatórias

Camada 3: CI/CD (Cloud - Obrigatório para merge)

  • ✅ Todos os testes
  • ✅ Cobertura de testes (80% mínimo)
  • ✅ Validações completas
  • ✅ GitHub Actions

📖 Documentação Detalhada

Comandos Disponíveis

# Validações locais
npm run lint # ESLint
npm run typecheck # TypeScript
npm test# Testes
npm run test:coverage # Testes com cobertura# Validador AIOX
node .aiox-core/utils/aiox-validator.js pre-commit # Validação pre-commit
node .aiox-core/utils/aiox-validator.js pre-push # Validação pre-push
node .aiox-core/utils/aiox-validator.js stories # Validar todas stories

Branch Protection

Configure proteção da branch master com:

node scripts/setup-branch-protection.js

Requer:

  • GitHub CLI (gh) instalado e autenticado
  • Acesso de admin ao repositório

Contribuindo

Estamos empolgados com contribuições e acolhemos suas ideias, melhorias e Squads! 🎉

Para contribuir:

  1. Fork o repositório
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaNovaFeature)
  3. Commit suas mudanças (git commit -m 'feat: Adicionar nova feature')
  4. Push para a branch (git push origin feature/MinhaNovaFeature)
  5. Abra um Pull Request

Veja também:

📄 Legal

DocumentoEnglishPortuguês
LicençaMIT License-
Modelo de LicençaCore vs Pro-
PrivacidadePrivacy Policy-
Termos de UsoTerms of Use-
Código de CondutaCode of ConductPT-BR
ContribuiçãoContributingPT-BR
SegurançaSecurityPT-BR
ComunidadeCommunityPT-BR
RoadmapRoadmapPT-BR
ChangelogVersion History-

Contribuidores

Contributors

🌟 Contribuidores da Comunidade

Nikolas de Hor
Nikolas de Hor

💻🐛⚠️👀

Construído com ❤️ para a comunidade de desenvolvimento assistido por IA


⬆ Voltar ao topo

About

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3.1k stars

Watchers

67 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages