# AIOX Framework - Livro de Ouro v4.2 (Complete) ## O Sistema Operacional Definitivo para Orquestração de Agentes IA **Versão:** 2.1.0 **Status:** Living Document **Última Atualização:** 2025-12-09 **Mantido Por:** AIOX Framework Team + Community **Repositório Principal:** `SynkraAI/aiox-core` --- > **"Structure is Sacred. Tone is Flexible."** > _— Fundamento filosófico do AIOX_ --- ## 📣 IMPORTANTE: Sobre Este Documento Este documento é a **versão consolidada v4.2** que incorpora todas as mudanças dos Sprints 2-5: - ✅ **Modular Architecture** (4 módulos: core, development, product, infrastructure) - ✅ **Squad System** (nova terminologia, substituindo "Squad") - ✅ **Multi-Repo Strategy** (3 repositórios públicos + 2 privados) - ✅ **Quality Gates 3 Layers** (Pre-commit, PR Automation, Human Review) - ✅ **Story Template v2.0** (Cross-Story Decisions, CodeRabbit Integration) - ✅ **npm Package Scoping** (@aiox/core, @aiox/squad-\*, @aiox/mcp-presets) **Referências Legadas:** - `AIOX-LIVRO-DE-OURO.md` - Base v2.0.0 (Jan 2025) - `AIOX-LIVRO-DE-OURO-V2.1.md` - Delta parcial - `AIOX-LIVRO-DE-OURO-V2.1-SUMMARY.md` - Resumo de mudanças --- ## 📜 Open Source vs. Serviço - Business Model v4.2 ### O Que Mudou de v2.0 para v4.0.4 **IMPORTANTE: v4.0.4 alterou fundamentalmente o business model!** | Componente | v2.0 | v4.0.4 | Rationale | | ------------------------ | ----------- | --------------- | -------------------------- | | **11 Agents** | ✅ Open | ✅ Open | Core functionality | | **Workers (97+)** | ❌ Closed | ✅ **OPEN** | Commodity, network effects | | **Service Discovery** | ❌ None | ✅ **BUILT-IN** | Community needs it | | **Task-First Arch** | ⚠️ Implicit | ✅ **EXPLICIT** | Architecture clarity | | **Clones (DNA Mental™)** | 🔒 Closed | 🔒 **CLOSED** | True moat (IP) | | **Squads** | 🔒 Closed | 🔒 **CLOSED** | Domain expertise | ### Repositório Multi-Repo Structure ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ SYNKRA ORGANIZATION │ │ │ │ PUBLIC REPOSITORIES (3) │ │ ═══════════════════════ │ │ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ SynkraAI/aiox-core (Commons Clause) │ │ │ │ ───────────────────────────────────── │ │ │ │ • Core Framework & Orchestration Engine │ │ │ │ • 11 Base Agents (Dex, Luna, Aria, Quinn, etc.) │ │ │ │ • Task Runner & Workflow Engine │ │ │ │ • Quality Gates System │ │ │ │ • Service Discovery │ │ │ │ • DISCUSSIONS HUB (Central community) │ │ │ │ npm: @aiox/core │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ peerDependency │ │ ┌──────────────────────────┼──────────────────────────┐ │ │ │ │ │ │ │ ▼ │ ▼ │ │ ┌─────────────────────┐ │ ┌─────────────────────────────┐ │ │ │ SynkraAI/ │ │ │ SynkraAI/mcp-ecosystem │ │ │ │ aiox-squads (MIT) │ │ │ (Apache 2.0) │ │ │ │ ───────────────── │ │ │ ────────────────────────── │ │ │ │ • ETL Squad │ │ │ • Docker MCP Toolkit │ │ │ │ • Creator Squad │ │ │ • IDE Configurations │ │ │ │ • MMOS Squad │ │ │ • MCP Presets │ │ │ │ npm: @aiox/squad-* │ │ │ npm: @aiox/mcp-presets │ │ │ └─────────────────────┘ │ └─────────────────────────────┘ │ │ │ │ │ PRIVATE REPOSITORIES (2) │ │ │ ════════════════════════ │ │ │ │ │ │ ┌─────────────────────┐ │ ┌─────────────────────────────┐ │ │ │ SynkraAI/mmos │ │ │ SynkraAI/certified- │ │ │ │ (Proprietary + NDA) │ │ │ partners (Proprietary) │ │ │ │ ───────────────── │ │ │ ────────────────────────── │ │ │ │ • MMOS Minds │ │ │ • Premium Squads │ │ │ │ • Cognitive Clones │ │ │ • Partner Portal │ │ │ │ • DNA Mental™ │ │ │ • Marketplace │ │ │ └─────────────────────┘ │ └─────────────────────────────┘ │ │ │ │ └──────────────────────────────┴─────────────────────────────────────────┘ ``` ### Competitive Positioning | Framework | Open-Source Completeness | Unique Differentiator | | ------------- | ------------------------ | ------------------------------ | | LangChain | ✅ Complete | ❌ None (commodity) | | CrewAI | ✅ Complete | ❌ None (commodity) | | AutoGen | ✅ Complete | ❌ None (commodity) | | **AIOX v4.2** | ✅ **Complete** | ✅ **Clones (DNA Mental™)** ⭐ | **Analogia:** Linux é open source, mas Red Hat Enterprise Linux adiciona suporte e otimizações. Ambos são Linux, mas o valor agregado varia. AIOX funciona igual. --- ## 📖 Como Usar Este Livro Este não é um documento para ser lido do início ao fim. É um **sistema de aprendizado em camadas**: - 🚀 **Layer 0: DISCOVERY** - Descubra seu caminho (5 min) - 🎯 **Layer 1: UNDERSTANDING** - 5 essays que ensinam o modelo mental (75 min) - 🎨 **Layer 2: COMPONENT LIBRARY** - Catálogo completo de componentes - 📋 **Layer 3: USAGE GUIDE** - Como usar AIOX v4.2 no seu contexto - 📚 **Layer 4: COMPLETE REFERENCE** - Especificação técnica completa - 🔄 **META: EVOLUTION** - Como contribuir e evoluir o framework **A maioria das pessoas precisa apenas do Layer 1.** O resto existe para quando você precisar. --- # 🚀 LAYER 0: DISCOVERY ROUTER ## Bem-vindo ao AIOX v4.2 - Vamos Encontrar Seu Caminho ### Learning Tracks Disponíveis | Track | Tempo | Melhor Para | | --------------------------- | --------- | ---------------------------------------- | | **Track 1: Quick Start** | 15-30 min | Exploradores curiosos, decisores rápidos | | **Track 2: Deep Dive** | 1.5-2h | Builders ativos com dores reais | | **Track 3: Mastery Path** | Semanas | Framework developers, power users | | **Track 4: Decision Maker** | 30-45 min | Líderes avaliando adoção | | **Track 5: Targeted** | Variável | Precisa de algo específico | | **Track 6: v2.0 Upgrade** | 45-60 min | Usuários v2.0 migrando | --- # 🎯 LAYER 1: UNDERSTANDING ## Essay 1: Por Que AIOX Existe ### O Problema Desenvolvimento com AI agents hoje é **caótico**: - Agents sem coordenação - Resultados inconsistentes - Sem quality gates - Contexto perdido entre sessões - Cada projeto reinventa a roda ### A Solução AIOX fornece **orquestração estruturada**: - 11 agents especializados com personalidades - Workflows multi-agent coordenados - Quality Gates em 3 camadas - Task-First Architecture para portabilidade - Service Discovery para reutilização --- ## Essay 2: Estrutura é Sagrada > "Quando as informações estão sempre nas mesmas posições, nosso cérebro sabe onde buscar rápido." **FIXO (Structure):** - Posições de template - Ordem de seções - Formatos de métricas - Estrutura de arquivos - Workflows de task **FLEXÍVEL (Tone):** - Mensagens de status - Escolhas de vocabulário - Uso de emoji - Personalidade do agent - Tom de comunicação --- ## Essay 3: Business Model v4.2 ### Por Que Workers São Open-Source Agora? 1. **Workers são Commodity** - Any developer can write deterministic scripts 2. **Clones são Singularidade** - DNA Mental™ takes years to develop 3. **Maximum Adoption Strategy** - Zero friction to start 4. **Network Effects** - More users → More contributors → Better Workers ### O Que Permanece Proprietário? - **Clones** - Cognitive emulation via DNA Mental™ - **Squads Premium** - Industry expertise (Finance, Healthcare, etc.) - **Team Features** - Collaboration, shared memory - **Enterprise** - Scale, support, SLAs --- ## Essay 4: Agent System ### Os 11 Agents v4.2 | Agent | ID | Archetype | Responsabilidade | | --------- | --------------- | ------------ | ----------------------- | | **Dex** | `dev` | Builder | Code implementation | | **Quinn** | `qa` | Guardian | Quality assurance | | **Aria** | `architect` | Architect | Technical architecture | | **Nova** | `po` | Visionary | Product backlog | | **Kai** | `pm` | Balancer | Product strategy | | **River** | `sm` | Facilitator | Process facilitation | | **Zara** | `analyst` | Explorer | Business analysis | | **Dara** | `data-engineer` | Architect | Data engineering | | **Felix** | `devops` | Optimizer | CI/CD and operations | | **Uma** | `ux-expert` | Creator | User experience | | **Pax** | `aiox-master` | Orchestrator | Framework orchestration | ### Agent Activation ```bash # Ativar agent @dev # Ativa Dex (Developer) @qa # Ativa Quinn (QA) @architect # Ativa Aria (Architect) @aiox-master # Ativa Pax (Orchestrator) # Comandos de agent (prefix *) *help # Mostra comandos disponíveis *task # Executa task específica *exit # Desativa agent ``` --- ## Essay 5: Task-First Architecture ### A Filosofia > **"Everything is a Task. Executors are attributes."** ### O Que Isso Significa **Tradicional (Task-per-Executor):** ```yaml # 2 implementações separadas para a mesma task agent_task.md: executor: Agent (Sage) worker_task.js: executor: Worker (market-analyzer.js) ``` **Task-First (Universal Task):** ```yaml # UMA definição de task task: analyzeMarket() inputs: { market_data: object } outputs: { insights: array } # Executor é apenas um campo responsavel_type: Humano # Day 1 responsavel_type: Worker # Week 10 responsavel_type: Agente # Month 6 responsavel_type: Clone # Year 2 ``` ### Migração Instantânea - **Antes:** 2-4 dias (rewrite required) - **Depois:** 2 segundos (change 1 field) --- # 🎨 LAYER 2: COMPONENT LIBRARY ## Arquitetura Modular v4.2 ### Os 4 Módulos ``` .aiox-core/ ├── core/ # Framework foundations │ ├── config/ # Configuration management │ ├── registry/ # Service Discovery │ ├── quality-gates/ # 3-layer QG system │ ├── mcp/ # MCP global configuration │ └── session/ # Session management │ ├── development/ # Development artifacts │ ├── agents/ # 11 agent definitions │ ├── tasks/ # 115+ task definitions │ ├── workflows/ # 7 workflow definitions │ └── scripts/ # Dev support utilities │ ├── product/ # User-facing templates │ ├── templates/ # 52+ templates │ ├── checklists/ # 11 checklists │ └── data/ # PM knowledge base │ └── infrastructure/ # System configuration ├── scripts/ # 55+ infrastructure scripts ├── tools/ # CLI, MCP, local configs └── integrations/ # PM adapters (ClickUp, Jira) ``` ### Module Dependencies ``` ┌─────────────────────────────────────────────────────┐ │ CLI / Tools │ │ │ │ │ ┌──────────────┼──────────────┐ │ │ ▼ ▼ ▼ │ │ development product infrastructure │ │ │ │ │ │ │ └──────────────┼──────────────┘ │ │ ▼ │ │ core │ │ (no dependencies) │ └─────────────────────────────────────────────────────┘ Regras: • core/ não tem dependências internas • development/, product/, infrastructure/ dependem APENAS de core/ • Dependências circulares são PROIBIDAS ``` --- ## Squad System (Novo em v4.2) ### Terminologia | Termo Antigo | Termo Novo | Descrição | | -------------- | ------------------ | ---------------------- | | Squad | **Squad** | Modular AI agent teams | | Squads/ | **squads/** | Diretório de Squads | | pack.yaml | **squad.yaml** | Manifesto do Squad | | @expansion/\* | **@aiox/squad-\*** | npm scope | ### Estrutura de Squad ``` squads/ ├── etl-squad/ │ ├── squad.yaml # Manifesto │ ├── agents/ # Squad-specific agents │ ├── tasks/ # Squad tasks │ └── templates/ # Squad templates │ ├── creator-squad/ │ └── ... │ └── mmos-squad/ └── ... ``` ### Squad Manifest (squad.yaml) ```yaml name: etl-squad version: 1.0.0 description: Data pipeline and ETL automation squad license: MIT peerDependencies: '@aiox/core': '^2.1.0' agents: - id: etl-orchestrator extends: data-engineer - id: data-validator extends: qa tasks: - collect-sources - transform-data - validate-pipeline exports: - agents - tasks - templates ``` --- ## Quality Gates 3 Layers ### Visão Geral ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ QUALITY GATES 3 LAYERS │ │ │ │ LAYER 1: LOCAL (Pre-commit) │ │ ═════════════════════════════ │ │ • ESLint, Prettier, TypeScript │ │ • Unit tests (fast) │ │ • Executor: Worker (deterministic) │ │ • Tool: Husky + lint-staged │ │ • Blocking: Can't commit if fails │ │ • Catches: 30% of issues instantly │ │ │ │ LAYER 2: PR AUTOMATION (CI/CD) │ │ ══════════════════════════════ │ │ • CodeRabbit AI review │ │ • Integration tests, coverage │ │ • Security scan, performance │ │ • Executor: Agent (QA) + CodeRabbit │ │ • Tool: GitHub Actions + CodeRabbit App │ │ • Blocking: Required checks for merge │ │ • Catches: Additional 50% (80% total) │ │ │ │ LAYER 3: HUMAN REVIEW (Strategic) │ │ ════════════════════════════════ │ │ • Architecture alignment │ │ • Business logic correctness │ │ • Edge cases, documentation │ │ • Executor: Human (Senior Dev / Tech Lead) │ │ • Tool: Human expertise + context │ │ • Blocking: Final approval required │ │ • Catches: Final 20% (100% total) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### Configuração **Layer 1 - Pre-commit (.husky/pre-commit):** ```bash #!/bin/sh npx lint-staged npm run typecheck npm test -- --onlyChanged ``` **Layer 2 - GitHub Actions (.github/workflows/quality-gates-pr.yml):** ```yaml name: Quality Gates PR on: [pull_request] jobs: layer2: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci - run: npm run lint - run: npm run typecheck - run: npm test -- --coverage - run: npm audit --audit-level=high ``` **Layer 3 - CODEOWNERS:** ``` # Layer 3: Human review requirements *.md @architecture-team /src/core/ @senior-devs /docs/architecture/ @architect ``` --- ## Story Template v2.0 ### Estrutura Completa ````markdown # Story X.X: [Title] **Epic:** [Parent Epic] **Story ID:** X.X **Sprint:** [Number] **Priority:** 🔴 Critical | 🟠 High | 🟡 Medium | 🟢 Low **Points:** [Number] **Status:** ⚪ Ready | 🔄 In Progress | ✅ Done **Type:** 🔧 Infrastructure | 💻 Feature | 📖 Documentation | ✅ Validation --- ## 🔀 Cross-Story Decisions | Decision | Source | Impact on This Story | | --------------- | ---------- | --------------------------- | | [Decision Name] | [Story ID] | [How it affects this story] | --- ## 📋 User Story **Como** [persona], **Quero** [ação], **Para** [benefício]. --- ## ✅ Tasks ### Phase 1: [Name] - [ ] **1.1** [Task description] - [ ] **1.2** [Task description] --- ## 🎯 Acceptance Criteria ```gherkin GIVEN [context] WHEN [action] THEN [expected result] ``` ```` --- ## 🤖 CodeRabbit Integration ### Story Type Analysis | Attribute | Value | Rationale | | ----------------- | ----------------- | --------- | | Type | [Type] | [Why] | | Complexity | [Low/Medium/High] | [Why] | | Test Requirements | [Type] | [Why] | ### Agent Assignment | Role | Agent | Responsibility | | --------- | ----- | -------------- | | Primary | @dev | [Task] | | Secondary | @qa | [Task] | --- ## 🧑‍💻 Dev Agent Record ### Execution Log | Timestamp | Phase | Action | Result | | --------- | ----- | ------ | ------ | --- ## 🧪 QA Results ### Test Execution Summary | Check | Status | Notes | | ----- | ------ | ----- | ```` --- ## npm Package Scoping ### Package Structure | Package | Registry | Depends On | License | |---------|----------|------------|---------| | `@aiox/core` | npm public | - | Commons Clause | | `@aiox/squad-etl` | npm public | @aiox/core | MIT | | `@aiox/squad-creator` | npm public | @aiox/core | MIT | | `@aiox/squad-mmos` | npm public | @aiox/core | MIT | | `@aiox/mcp-presets` | npm public | - | Apache 2.0 | ### Installation ```bash # Core framework npm install @aiox/core # Squads (require core as peer) npm install @aiox/squad-etl # MCP presets (independent) npm install @aiox/mcp-presets ```` --- # 📋 LAYER 3: USAGE GUIDE ## Quick Start v4.2 ### Installation (5 minutes) ```bash # New project (Greenfield) $ npx @SynkraAI/aiox@latest init # Existing project (Brownfield) $ npx @SynkraAI/aiox migrate v2.0-to-v4.0.4 ``` ### First Steps ```bash # List available agents $ aiox agents list # List available Squads $ aiox squads list # Create your first story $ aiox stories create # Execute a task $ aiox task develop-story --story=1.1 ``` ### Local Development (Multi-Repo) ```bash # Clone all repos mkdir -p ~/Workspaces/AIOX && cd ~/Workspaces/AIOX gh repo clone SynkraAI/aiox-core gh repo clone SynkraAI/aiox-squads gh repo clone SynkraAI/mcp-ecosystem # Link for local development cd aiox-core && npm install && npm link cd ../aiox-squads && npm install && npm link @aiox/core # VS Code workspace code aiox-workspace.code-workspace ``` --- ## Service Discovery ### Finding Workers ```bash # Search for workers $ aiox workers search "json parse" Results (3 Workers): 📦 json-parser.js ⭐⭐⭐⭐⭐ (47 projects) 📦 json-validator.js ⭐⭐⭐⭐ (23 projects) 📦 json-transformer.js ⭐⭐⭐ (15 projects) # Get worker details $ aiox workers info json-parser # Use worker in task $ aiox workers use json-parser --task my-task ``` ### Time Saved - **Before:** 2 hours (search, install, wrap) - **After:** 30 seconds (search, use) --- ## Workflows ### Available Workflows | Workflow | Use Case | Agents Involved | | ------------------------ | ----------------------- | ----------------- | | `greenfield-fullstack` | New full-stack project | All agents | | `brownfield-integration` | Add AIOX to existing | dev, architect | | `fork-join` | Parallel task execution | Multiple | | `organizer-worker` | Delegated execution | po, dev | | `data-pipeline` | ETL workflows | data-engineer, qa | ### Executing Workflows ```bash # Start workflow $ aiox workflow greenfield-fullstack # With parameters $ aiox workflow brownfield-integration --target=./existing-project ``` --- # 📚 LAYER 4: COMPLETE REFERENCE ## Source Tree v4.2 (Current) ``` aiox-core/ # Root project ├── .aiox-core/ # Framework layer │ ├── core/ # Core module │ │ ├── config/ # Configuration │ │ ├── registry/ # Service Discovery │ │ ├── quality-gates/ # 3-layer QG │ │ ├── mcp/ # MCP system │ │ └── session/ # Session mgmt │ │ │ ├── development/ # Development module │ │ ├── agents/ # 11 agents │ │ ├── tasks/ # 115+ tasks │ │ ├── workflows/ # 7 workflows │ │ └── scripts/ # Dev scripts │ │ │ ├── product/ # Product module │ │ ├── templates/ # 52+ templates │ │ ├── checklists/ # 11 checklists │ │ └── data/ # PM data │ │ │ ├── infrastructure/ # Infrastructure module │ │ ├── scripts/ # 55+ scripts │ │ ├── tools/ # CLI, MCP configs │ │ └── integrations/ # PM adapters │ │ │ └── docs/ # Framework docs │ └── standards/ # This document lives here │ ├── docs/ # Project docs │ ├── stories/ # Development stories │ │ └── v4.0.4/ # v4.0.4 stories │ │ ├── sprint-1/ │ │ ├── sprint-2/ │ │ ├── sprint-3/ │ │ ├── sprint-4/ │ │ ├── sprint-5/ │ │ └── sprint-6/ │ │ │ ├── architecture/ # Architecture docs │ │ ├── multi-repo-strategy.md # Multi-repo guide │ │ ├── module-system.md # Module architecture │ │ └── ... │ │ │ └── epics/ # Epic planning │ ├── squads/ # Squad implementations │ ├── etl/ # ETL Squad │ ├── creator/ # Creator Squad │ └── mmos-mapper/ # MMOS Squad │ ├── .github/ # GitHub automation │ ├── workflows/ # CI/CD │ │ ├── quality-gates-pr.yml # Layer 2 QG │ │ └── tests.yml # Test automation │ │ │ ├── ISSUE_TEMPLATE/ # Issue templates │ ├── PULL_REQUEST_TEMPLATE.md # PR template │ └── CODEOWNERS # Code ownership │ ├── .husky/ # Git hooks (Layer 1) │ ├── pre-commit │ └── pre-push │ ├── package.json ├── tsconfig.json ├── .eslintrc.json ├── .prettierrc ├── README.md ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── COMMUNITY.md ├── SECURITY.md ├── LICENSE └── CHANGELOG.md ``` --- ## Key Metrics Comparison ### Installation | Metric | v2.0 | v4.2 | Improvement | | --------------- | ---------- | --------- | --------------- | | Time to install | 2-4 hours | 5 minutes | **96% faster** | | Steps required | 15+ manual | 1 command | **93% simpler** | | Success rate | 60% | 98% | **+38%** | ### Development Speed | Metric | v2.0 | v4.2 | Improvement | | --------------------- | -------- | ---------- | ----------------- | | Find reusable Worker | N/A | 30 seconds | **∞** | | Quality issues caught | 20% | 80% | **4x** | | Executor migration | 2-4 days | 2 seconds | **99.99% faster** | ### Quality | Metric | v2.0 | v4.2 | | ------------------- | ---------- | ------------- | | Quality Gate Layers | 1 (manual) | 3 (automated) | | Auto-caught issues | 0% | 80% | | Human review time | 2-4h/PR | 30min/PR | --- ## Version History | Version | Date | Changes | | ------- | ---------- | ------------------------------------------------- | | 2.0.0 | 2025-01-19 | Initial v2.0 release | | 2.1.0 | 2025-12-09 | Modular arch, Squads, Multi-repo, QG3, Story v2.0 | --- ## Related Documents - [Multi-Repo Strategy](../../architecture/multi-repo-strategy.md) - [Module System](../../architecture/module-system.md) - [QUALITY-GATES-SPECIFICATION.md](./QUALITY-GATES-SPECIFICATION.md) - [STORY-TEMPLATE-V2-SPECIFICATION.md](./STORY-TEMPLATE-V2-SPECIFICATION.md) - [STANDARDS-INDEX.md](./STANDARDS-INDEX.md) --- **Última Atualização:** 2025-12-09 **Versão:** 2.1.0-complete **Mantido Por:** AIOX Framework Team --- _Este documento consolida AIOX-LIVRO-DE-OURO.md (v2.0) + deltas v4.0.4 em um único documento completo._