SynkraAI/aios-core

Synkra AIOS: Framework Universal de Agentes IA 🚀

Framework de Desenvolvimento Auto-Modificável Alimentado por IA. Fundado em Desenvolvimento Ágil Dirigido por Agentes, oferecendo capacidades revolucionárias para desenvolvimento dirigido por IA e muito mais. Transforme qualquer domínio com expertise especializada de IA: desenvolvimento de software, entretenimento, escrita criativa, estratégia de negócios, bem-estar pessoal e muito mais.

Visão Geral

Premissa Arquitetural: CLI First

O Synkra AIOS segue uma hierarquia clara de prioridades:

1

CLI First → Observability Second → UI Third

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 Synkra AIOS:

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

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

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

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

Pré-requisitos

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

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

Guias específicos por plataforma:

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

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

Navegação Rápida

Entendendo o Fluxo de Trabalho AIOS

Antes de mergulhar, revise estes diagramas críticos de fluxo de trabalho que explicam como o AIOS 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 Synkra AIOS Agentic Agile - Entender a criação de PRD+Arquitetura e o fluxo de trabalho sm/dev/qa e como os agentes passam notas através de arquivos de histórias é essencial - e também explica por que isto NÃO é taskmaster ou apenas um simples executor de tarefas!

O que você gostaria de fazer?

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

Importante: Mantenha Sua Instalação AIOS Atualizada

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

1

npx aios-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 Synkra AIOS com um único comando:

1
2
3
4
5
6
7
8
9

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

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

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

✨ Assistente de Instalação Moderno

O Synkra AIOS 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 (Windsurf, Cursor ou Claude Code)
• ✅ Configuração de todos os agentes e fluxos de trabalho AIOS
• ✅ 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 AIOS instalado:

1
2

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

Configure Seu IDE para Desenvolvimento AIOS

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

Para Windsurf ou Cursor:

1. Abra as configurações do seu IDE
2. Navegue até Global Rules (Windsurf) ou User Rules (Cursor)
3. Copie o conteúdo de .windsurf/global-rules.md ou .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

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 AIOS

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

1. Instale o AIOS: Execute npx aios-core init meu-projeto
2. Configure seu IDE: Siga as instruções de configuração para Windsurf, Cursor ou Claude Code
3. Comece a Planejar: Ative um agente como @analyst para começar a criar seu briefing
4. Use comandos AIOS: 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 Synkra AIOS oferece uma CLI moderna e cross-platform com comandos intuitivos:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Gerenciamento de Projeto (com assistente interativo)
npx aios-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 aios-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 aios-core --version   Exibir versão instalada
npx aios-core --help      Exibir ajuda detalhada
npx aios-core info        Exibir informações do sistema
npx aios-core doctor      Executar diagnósticos do sistema
npx aios-core doctor --fix Corrigir problemas detectados automaticamente

# Manutenção
npx aios-core update      Atualizar para versão mais recente
npx aios-core uninstall   Remover Synkra AIOS

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

$ npx aios-core install

🚀 Synkra AIOS 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
  aios-core doctor     # Verify installation
  aios-core --help     # See available commands

Instalação Silenciosa (CI/CD)

1
2
3

# Instalação automatizada sem prompts
$ npx aios-core install --quiet --force
✔ Synkra AIOS installed successfully

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

1
2
3
4
5
6
7
8

# Testar instalação sem modificar arquivos
$ npx aios-core install --dry-run

[DRY RUN] Would create: ./my-project/
[DRY RUN] Would copy: .aios-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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

$ npx aios-core doctor

🏥 AIOS 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
✔ Synkra AIOS: v1.0.0

Configuration:
✔ .aios-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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

$ npx aios-core --help

Usage: aios-core [options] [command]

Synkra AIOS: AI-Orchestrated System for Full Stack Development

Options:
  -V, --version                output the version number
  -h, --help                   display help for command

Commands:
  init <project-name>          Create new AIOS project with interactive wizard
  install [options]            Install AIOS in current directory
  info                         Display system information
  doctor [options]             Run system diagnostics and health checks
  help [command]               display help for command

Run 'aios-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:

1
2
3
4
5
6
7
8
9

# Clonar o repositório
git clone https://github.com/SynkraAI/aios-core.git
cd aios-core

# Instalar dependências
npm install

# Executar o instalador
npm run install:aios

Configuração Rápida para Equipe

Para membros da equipe ingressando no projeto:

1
2
3
4
5
6
7

# Instalar AIOS no projeto
npx aios-core@latest install

# Isto vai:
# 1. Detectar instalação existente (se houver)
# 2. Instalar/atualizar framework AIOS
# 3. Configurar agentes e workflows

🌟 Além do Desenvolvimento de Software - Squads

O framework de linguagem natural do AIOS 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 Synkra AIOS 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 Synkra AIOS vem com 11 agentes especializados:

Agentes Meta

• aios-master - Agente mestre de orquestração (inclui capacidades de desenvolvimento de framework)
• aios-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

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 AIOS para qualquer domínio além do desenvolvimento de software

Documentação Adicional

• 🤖 Guia de Squads - Crie e publique equipes de agentes IA
• 📋 Primeiros Passos - Tutorial passo a passo para iniciantes
• 🔧 Solução de Problemas - Soluções para problemas comuns
• 🎯 Princípios Orientadores - Filosofia e melhores práticas do AIOS
• 🏛️ Visão Geral da Arquitetura - Visão detalhada da arquitetura do sistema
• ⚙️ Guia de Ajuste de Performance - Otimize seu fluxo de trabalho AIOS
• 🔒 Melhores Práticas de Segurança - Segurança e proteção de dados
• 🔄 Guia de Migração - Migração de versões anteriores
• 📦 Versionamento e Releases - Política de versões

🤖 AIOS Autonomous Development Engine (ADE)

O Synkra AIOS v1.0.0 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:

🔄 Fluxo Principal

1
2
3
4
5

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

⚡ Quick Start ADE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 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

• Guia Completo do ADE - Tutorial passo a passo
• Alterações nos Agentes - Comandos e capabilities por agente
• Epic 1 - Worktree Manager
• Epic 2 - Migration V2→V3
• Epic 3 - Spec Pipeline
• Epic 4 - Execution Engine
• Epic 5 - Recovery System
• Epic 6 - QA Evolution
• Epic 7 - Memory Layer

🆕 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

Expansion packs permitem estender o AIOS para qualquer domínio. Estrutura básica:

1
2
3
4
5
6
7
8
9

squads/seu-pack/
├── config.yaml           # Configuração do pack
├── 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 pack
└── 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)

AIOS Pro

O AIOS Pro (@aios-fullstack/pro) é o módulo premium do Synkra AIOS, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.

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

Instalação

1

npm install @aios-fullstack/pro

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 aios pro activate --key <KEY>

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

Suporte & Comunidade

• 📖 Guia da Comunidade - Como participar e contribuir
• 💬 Discussões GitHub - Hub central da comunidade
• 💡 Processo de Features - Como propor novas funcionalidades
• 🐛 Rastreador de Issues
• 📋 Como Contribuir
• 🗺️ Roadmap - Veja o que estamos construindo
• 🤖 Guia de Squads - Crie equipes de agentes IA

Git Workflow e Validação

O Synkra AIOS 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

• 📋 Guia Completo de Git Workflow - Guia detalhado do fluxo de trabalho
• 📋 CONTRIBUTING.md - Guia de contribuição

Comandos Disponíveis

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Validações locais
npm run lint           # ESLint
npm run typecheck      # TypeScript
npm test              # Testes
npm run test:coverage # Testes com cobertura

# Validador AIOS
node .aios-core/utils/aios-validator.js pre-commit   # Validação pre-commit
node .aios-core/utils/aios-validator.js pre-push     # Validação pre-push
node .aios-core/utils/aios-validator.js stories      # Validar todas stories

Branch Protection

Configure proteção da branch master com:

1

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:

• 📋 Como Contribuir com Pull Requests
• 📋 Guia de Git Workflow

📄 Legal

Reconhecimentos

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

⬆ Voltar ao topo