Versão: 2.0 Última Atualização: 2025-12-15 Status: Padrão Oficial do Framework Repositório: SynkraAI/aiox-core
- Visão Geral
- Arquitetura Modular
- Framework Core (.aiox-core/)
- Detalhes dos Módulos
- Documentação (docs/)
- Sistema de Squads
- Convenções de Nomenclatura de Arquivos
- Onde Colocar Novos Arquivos
O AIOX usa uma arquitetura modular com clara separação de responsabilidades:
- Framework Core (
.aiox-core/) - Componentes portáveis do framework organizados por domínio - Project Workspace (root) - Implementação específica do projeto
Filosofia:
- Organização orientada a domínio - Componentes agrupados por função
- Portabilidade - Componentes do framework funcionam entre projetos
- Separação de responsabilidades - Limites claros entre módulos
aiox-core/ # Root project
├── .aiox-core/ # Framework core (modular)
│ ├── cli/ # CLI commands and utilities
│ ├── core/ # Framework essentials
│ ├── data/ # Shared data files
│ ├── development/ # Development assets (agents, tasks, workflows)
│ ├── docs/ # Internal framework docs
│ ├── elicitation/ # Elicitation engines
│ ├── infrastructure/ # Infrastructure tools and scripts
│ ├── manifests/ # Installation manifests
│ ├── product/ # PM/PO assets (templates, checklists)
│ ├── quality/ # Quality gate schemas
│ ├── scripts/ # Utility scripts
│ └── core-config.yaml # Framework configuration
│
├── docs/ # Public documentation
│ ├── architecture/ # Architecture docs
│ ├── framework/ # Official framework standards
│ ├── guides/ # How-to guides
│ ├── installation/ # Installation guides
│ └── community/ # Community docs
│
├── templates/ # Project templates
│ └── squad/ # Squad template (see docs/guides/squads-guide.md)
│
├── bin/ # CLI executables
│ └── aiox.js # Main CLI entry point
│
├── tools/ # Build and utility tools
│ ├── cli.js # CLI builder
│ └── installer/ # Installation scripts
│
├── tests/ # Test suites
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
│
├── .claude/ # Claude Code configuration
│ ├── CLAUDE.md # Project instructions
│ ├── commands/ # Agent slash commands
│ └── rules/ # IDE rules
│
├── index.js # Main entry point
├── package.json # Package manifest
└── README.md # Project README
Propósito: Componentes portáveis do framework organizados por domínio para clara separação de responsabilidades.
.aiox-core/
├── cli/ # Sistema CLI
│ ├── commands/ # Implementações de comandos CLI
│ │ ├── generate/ # Comandos de geração de código
│ │ ├── manifest/ # Gerenciamento de manifests
│ │ ├── mcp/ # Comandos de ferramentas MCP
│ │ ├── metrics/ # Métricas de qualidade
│ │ ├── migrate/ # Ferramentas de migração
│ │ ├── qa/ # Comandos QA
│ │ └── workers/ # Workers em background
│ └── utils/ # Utilitários CLI
│
├── core/ # Essenciais do Framework
│ ├── config/ # Sistema de configuração
│ ├── data/ # Base de conhecimento core
│ ├── docs/ # Documentação core
│ ├── elicitation/ # Engine de prompting interativo
│ ├── manifest/ # Processamento de manifests
│ ├── mcp/ # Orquestração MCP
│ ├── migration/ # Utilitários de migração
│ ├── quality-gates/ # Validadores de quality gate
│ ├── registry/ # Registro de serviços
│ ├── session/ # Gerenciamento de estado de runtime
│ └── utils/ # Utilitários core
│
├── data/ # Dados Compartilhados
│ └── aiox-kb.md # Base de conhecimento AIOX
│
├── development/ # Assets de Desenvolvimento
│ ├── agents/ # Definições de agentes (11 agentes core)
│ │ ├── aiox-master.md # Orquestrador master
│ │ ├── dev.md # Agente desenvolvedor
│ │ ├── qa.md # Agente engenheiro QA
│ │ ├── architect.md # Agente arquiteto de sistemas
│ │ ├── po.md # Agente Product Owner
│ │ ├── pm.md # Agente Product Manager
│ │ ├── sm.md # Agente Scrum Master
│ │ ├── analyst.md # Agente Business Analyst
│ │ ├── ux-design-expert.md # Agente UX Designer
│ │ ├── data-engineer.md # Agente Data Engineer
│ │ └── devops.md # Agente DevOps
│ ├── agent-teams/ # Configurações de times de agentes
│ ├── tasks/ # Workflows de tarefas (60+ tasks)
│ ├── workflows/ # Workflows multi-etapas
│ └── scripts/ # Scripts de desenvolvimento
│
├── docs/ # Documentação Interna
│ └── standards/ # Padrões do framework
│
├── elicitation/ # Engines de Elicitação
│ ├── agent-elicitation.js # Elicitação de criação de agentes
│ ├── task-elicitation.js # Elicitação de criação de tasks
│ └── workflow-elicitation.js # Elicitação de criação de workflows
│
├── infrastructure/ # Infraestrutura
│ ├── integrations/ # Integrações externas
│ │ └── pm-adapters/ # Adapters de ferramentas PM (ClickUp, GitHub, Jira)
│ ├── scripts/ # Scripts de infraestrutura
│ │ ├── documentation-integrity/ # Sistema de integridade de docs
│ │ └── llm-routing/ # Utilitários de roteamento LLM
│ ├── templates/ # Templates de infraestrutura
│ │ ├── core-config/ # Templates de config
│ │ ├── github-workflows/ # Templates CI/CD
│ │ ├── gitignore/ # Templates de gitignore
│ │ └── project-docs/ # Templates de documentação de projeto
│ ├── tests/ # Testes de infraestrutura
│ └── tools/ # Integrações de ferramentas
│ ├── cli/ # Wrappers de ferramentas CLI
│ ├── local/ # Ferramentas locais
│ └── mcp/ # Configs de servidor MCP
│
├── manifests/ # Manifests de Instalação
│ └── schema/ # Schemas de manifests
│
├── product/ # Assets PM/PO
│ ├── checklists/ # Checklists de validação
│ │ ├── po-master-checklist.md # Validação PO
│ │ ├── story-draft-checklist.md # Validação de draft de story
│ │ ├── architect-checklist.md # Revisão de arquitetura
│ │ └── change-checklist.md # Gerenciamento de mudanças
│ ├── data/ # Dados específicos de PM
│ └── templates/ # Templates de documentos
│ ├── engine/ # Engine de templates
│ ├── ide-rules/ # Templates de regras IDE
│ ├── story-tmpl.yaml # Template de story
│ ├── prd-tmpl.yaml # Template de PRD
│ └── epic-tmpl.md # Template de epic
│
├── quality/ # Sistema de Qualidade
│ └── schemas/ # Schemas de quality gate
│
├── scripts/ # Scripts Root
│ └── ... # Scripts utilitários
│
├── core-config.yaml # Configuração do framework
├── install-manifest.yaml # Manifest de instalação
├── user-guide.md # Guia do usuário
└── working-in-the-brownfield.md # Guia brownfield
Agents:
Location: .aiox-core/development/agents/
Format: Markdown with YAML frontmatter
Naming: {agent-name}.md (kebab-case)
Example: dev.md, qa.md, architect.md
Tasks:
Location: .aiox-core/development/tasks/
Format: Markdown workflow
Naming: {task-name}.md (kebab-case)
Example: create-next-story.md, develop-story.md
Templates:
Location: .aiox-core/product/templates/
Format: YAML or Markdown
Naming: {template-name}-tmpl.{yaml|md}
Example: story-tmpl.yaml, prd-tmpl.md
Workflows:
Location: .aiox-core/development/workflows/
Format: YAML
Naming: {workflow-type}-{scope}.yaml
Example: greenfield-fullstack.yaml, brownfield-service.yaml
Checklists:
Location: .aiox-core/product/checklists/
Format: Markdown
Naming: {checklist-name}-checklist.md
Example: story-draft-checklist.md, architect-checklist.md
Core Utilities:
Location: .aiox-core/core/utils/
Format: JavaScript (CommonJS)
Naming: {utility-name}.js (kebab-case)
Example: component-generator.js, story-manager.js
CLI Commands:
Location: .aiox-core/cli/commands/{category}/
Format: JavaScript (CommonJS)
Naming: {command-name}.js (kebab-case)
Example: generate/agent.js, manifest/install.js
Infrastructure Scripts:
Location: .aiox-core/infrastructure/scripts/{category}/
Format: JavaScript
Naming: {script-name}.js (kebab-case)
Example: documentation-integrity/link-verifier.jsdocs/
├── architecture/ # ⚠️ Misto: oficial + específico do projeto
│ ├── coding-standards.md # ✅ Oficial (migra para REPO 1)
│ ├── tech-stack.md # ✅ Oficial (migra para REPO 1)
│ ├── source-tree.md # ✅ Oficial (migra para REPO 1)
│ ├── decision-analysis-*.md # Decisões específicas do projeto
│ ├── architectural-review-*.md # Revisões específicas do projeto
│ └── mcp-*.md # Docs do framework (migra para REPO 1)
│
├── framework/ # ⭐ NOVO: Docs oficiais do framework (Q2 2026)
│ ├── coding-standards.md # Padrões de código do framework
│ ├── tech-stack.md # Tech stack do framework
│ ├── source-tree.md # Source tree do framework
│ └── README.md # Aviso de migração
│
├── stories/ # Stories de desenvolvimento
│ ├── aiox migration/ # Stories de migração AIOX
│ │ ├── story-6.1.2.1.md
│ │ ├── story-6.1.2.2.md
│ │ ├── story-6.1.2.3.md
│ │ ├── story-6.1.2.4.md
│ │ └── story-6.1.2.5.md
│ └── ... # Outras stories
│
├── epics/ # Planejamento de epics
│ ├── epic-6.1-agent-identity-system.md
│ └── ... # Outros epics
│
├── decisions/ # Architecture Decision Records
│ ├── decision-005-repository-restructuring-FINAL.md
│ └── ... # Outros ADRs
│
├── guides/ # Guias how-to
│ ├── git-workflow-guide.md
│ ├── migration-guide.md
│ └── ... # Outros guias
│
├── qa/ # Artefatos QA
│ └── backlog-archive/ # Itens QA arquivados
│
├── prd/ # Product Requirements Documents
│ └── ... # Arquivos PRD
│
├── planning/ # Documentos de planejamento
│ └── ... # Planos de sprint, roadmaps
│
├── standards/ # Padrões do framework
│ └── AGENT-PERSONALIZATION-STANDARD-V1.md
│
└── STORY-BACKLOG.md # ⭐ Índice de backlog de stories
docs/
├── framework/ # ✅ Docs oficiais do framework
│ ├── coding-standards.md
│ ├── tech-stack.md
│ ├── source-tree.md
│ ├── agent-spec.md
│ ├── task-spec.md
│ └── workflow-spec.md
│
├── architecture/ # Arquitetura específica do projeto
│ ├── project-decisions/ # ✅ ADRs para este projeto
│ │ ├── decision-005-repository-restructuring-FINAL.md
│ │ ├── architectural-review-contextual-agent-load.md
│ │ └── ...
│ └── diagrams/ # Diagramas de arquitetura
│
├── stories/ # Stories de desenvolvimento
│ ├── index.md # ⭐ Índice de stories (auto-gerado)
│ ├── backlog.md # ⭐ Backlog de stories (oficial)
│ └── ... # Arquivos de stories
│
├── epics/
├── guides/
├── qa/
├── prd/
└── standards/
Nota: Squads substituíram o sistema legado "Squads" no OSR-8. Veja Guia de Squads para documentação completa.
Squads são extensões modulares que adicionam capacidades especializadas ao AIOX. Diferente dos Squads deprecados, Squads seguem uma estrutura de template padronizada.
templates/squad/ # Template de squad para criar extensões
├── squad.yaml # Template de manifest de squad
├── package.json # Template de pacote NPM
├── README.md # Template de documentação
├── LICENSE # Template de licença
├── .gitignore # Template de git ignore
├── agents/ # Agentes específicos do squad
│ └── example-agent.yaml
├── tasks/ # Tasks específicas do squad
│ └── example-task.yaml
├── workflows/ # Workflows específicos do squad
│ └── example-workflow.yaml
├── templates/ # Templates específicos do squad
│ └── example-template.md
└── tests/ # Testes do squad
└── example-agent.test.js
# Future CLI (planejado):
npx create-aiox-squad my-squad-name
# Método atual:
cp -r templates/squad/ squads/my-squad-name/
# Então customize squad.yaml e componentes# squad.yaml
name: my-custom-squad
version: 1.0.0
description: Description of what this squad does
author: Your Name
license: MIT
# Components provided by this squad
agents:
- custom-agent-1
- custom-agent-2
tasks:
- custom-task-1
workflows:
- custom-workflow-1
# Dependencies
dependencies:
aiox-core: '>=2.1.0'| Legado (Deprecado) | Atual (Squads) |
|---|---|
Squads/ directory |
templates/squad/ template |
legacyPacksLocation config |
squadsTemplateLocation config |
pack.yaml manifest |
squad.yaml manifest |
| Direct loading | Template-based creation |
Decision 005 define 5 repositórios separados:
aiox-core/
├── .aiox-core/ # Framework assets (modular v2.0)
│ ├── cli/ # CLI commands and utilities
│ ├── core/ # Framework essentials
│ │ ├── config/ # Configuration system
│ │ ├── quality-gates/ # Quality validators
│ │ └── utils/ # Core utilities
│ ├── development/ # Development assets
│ │ ├── agents/ # Agent definitions (11 core)
│ │ ├── tasks/ # Task workflows (60+)
│ │ └── workflows/ # Multi-step workflows
│ ├── infrastructure/ # Infrastructure tools
│ │ ├── integrations/ # PM adapters, tools
│ │ ├── scripts/ # Automation scripts
│ │ └── templates/ # Infrastructure templates
│ ├── product/ # PM/PO assets
│ │ ├── checklists/ # Validation checklists
│ │ └── templates/ # Document templates
│ └── ...
│
├── bin/ # CLI entry points
│ └── aiox.js # Main CLI
│
├── tools/ # Build and utility tools
│ ├── cli.js # CLI builder
│ └── installer/ # Installation scripts
│
├── docs/ # Framework documentation
│ ├── framework/ # Official standards
│ ├── guides/ # How-to guides
│ ├── installation/ # Setup guides
│ └── architecture/ # Architecture docs
│
├── templates/ # Project templates
│ └── squad/ # Squad template
│
├── tests/ # Test suites
│ ├── unit/
│ ├── integration/
│ └── e2e/
│
└── examples/ # Example projects
├── basic-agent/
├── vibecoder-demo/
└── multi-agent-workflow/
squads/
├── verified/ # Squads curados pelo AIOX
│ ├── github-devops/
│ ├── db-sage/
│ └── coderabbit-workflow/
│
├── community/ # Submissões da comunidade
│ ├── marketing-agency/
│ ├── sales-automation/
│ └── ...
│
├── templates/ # Templates de squad
│ ├── minimal-squad/
│ └── agent-squad/
│
└── tools/ # Ferramentas de desenvolvimento de squad
└── create-aiox-squad/
mcp-ecosystem/
├── presets/ # MCP presets (Docker MCP Toolkit)
│ ├── aiox-dev/
│ ├── aiox-research/
│ └── aiox-docker/
│
├── mcps/ # Base MCP configs
│ ├── exa/
│ ├── context7/
│ └── desktop-commander/
│
└── ide-configs/ # Integrações de IDE
├── claude-code/
├── gemini-cli/
└── cursor/
certified-partners/
├── premium-packs/ # Premium Squads
│ ├── enterprise-deployment/
│ └── advanced-devops/
│
├── partner-portal/ # Partner Success Platform
│ ├── dashboard/
│ └── analytics/
│
└── marketplace/ # Marketplace platform
├── api/
└── web/
mmos/
├── minds/ # 34 cognitive clones
│ ├── pedro-valerio/
│ ├── paul-graham/
│ └── ...
│
├── emulator/ # MMOS emulation engine
│ ├── mirror-agent/
│ └── dna-mental/
│
└── research/ # Research artifacts
└── transcripts/
Directories: kebab-case (minúsculas, separado por hífen)
✅ .aiox-core/
✅ Squads/
❌ .AIOX-Core/
❌ legacy-packs/
Files (Code): kebab-case com extensão
✅ agent-executor.js
✅ task-runner.js
❌ AgentExecutor.js
❌ taskRunner.js
Files (Docs): kebab-case com extensão .md
✅ coding-standards.md
✅ story-6.1.2.5.md
❌ CodingStandards.md
❌ Story_6_1_2_5.md
Files (Config): minúsculas ou kebab-case
✅ package.json
✅ tsconfig.json
✅ core-config.yaml
❌ PackageConfig.jsonStories:
Format: story-{epic}.{story}.{substory}.md
Example: story-6.1.2.5.md
Epics:
Format: epic-{number}-{name}.md
Example: epic-6.1-agent-identity-system.md
Decisions:
Format: decision-{number}-{name}.md
Example: decision-005-repository-restructuring-FINAL.md
Templates:
Format: {name}-tmpl.{yaml|md}
Example: story-tmpl.yaml, prd-tmpl.md
Checklists:
Format: {name}-checklist.md
Example: architect-checklist.md# Estou criando um novo agente:
Location: .aiox-core/development/agents/{agent-name}.md
Example: .aiox-core/development/agents/security-expert.md
# Estou criando uma nova task:
Location: .aiox-core/development/tasks/{task-name}.md
Example: .aiox-core/development/tasks/deploy-to-production.md
# Estou criando um novo workflow:
Location: .aiox-core/development/workflows/{workflow-name}.yaml
Example: .aiox-core/development/workflows/continuous-deployment.yaml
# Estou criando um novo template:
Location: .aiox-core/product/templates/{template-name}-tmpl.{yaml|md}
Example: .aiox-core/product/templates/deployment-plan-tmpl.yaml
# Estou criando um novo checklist:
Location: .aiox-core/product/checklists/{checklist-name}-checklist.md
Example: .aiox-core/product/checklists/security-review-checklist.md
# Estou criando um comando CLI:
Location: .aiox-core/cli/commands/{category}/{command-name}.js
Example: .aiox-core/cli/commands/generate/workflow.js
# Estou criando um utilitário core:
Location: .aiox-core/core/utils/{utility-name}.js
Example: .aiox-core/core/utils/performance-monitor.js
# Estou criando um script de infraestrutura:
Location: .aiox-core/infrastructure/scripts/{category}/{script-name}.js
Example: .aiox-core/infrastructure/scripts/llm-routing/router.js
# Estou adicionando um adapter de ferramenta PM:
Location: .aiox-core/infrastructure/integrations/pm-adapters/{adapter-name}.js
Example: .aiox-core/infrastructure/integrations/pm-adapters/monday-adapter.js
# Estou escrevendo uma story (docs internos de dev - gitignored):
Location: docs/stories/{sprint-context}/{story-file}.md
Example: docs/stories/v4.0.4/sprint-6/story-6.14-new-feature.md
# Estou criando documentação oficial do framework:
Location: docs/framework/{doc-name}.md
Example: docs/framework/agent-development-guide.md
# Estou criando um teste:
Location: tests/{type}/{test-name}.test.js
Example: tests/unit/agent-executor.test.js
# Estou criando um squad:
Location: Copy templates/squad/ to your squads directory
Example: squads/devops-automation/ (customize from template).ai/ # AI session artifacts
├── decision-log-6.1.2.5.md # Yolo mode decision log
├── decision-log-6.1.2.6.md # Another decision log
└── session-{date}-{agent}.md # Session transcripts (optional)
Propósito: Rastrear decisões orientadas por IA durante sessões de desenvolvimento (especialmente yolo mode)
Auto-gerado: Sim (quando yolo mode habilitado)
outputs/ # Runtime outputs (gitignored)
├── minds/ # MMOS cognitive clones
│ └── pedro_valerio/
│ ├── system-prompt.md
│ ├── kb/
│ └── artifacts/
│
└── architecture-map/ # Architecture analysis
├── MASTER-RELATIONSHIP-MAP.json
└── schemas/
Propósito: Artefatos de runtime não commitados no git
| Versão | Data | Alterações | Autor |
|---|---|---|---|
| 1.0 | 2025-01-15 | Documentação inicial de source tree | Aria (architect) |
| 1.1 | 2025-12-14 | Atualizado org para SynkraAI, substituído Squads pelo sistema Squads [Story 6.10] | Dex (dev) |
| 2.0 | 2025-12-15 | Atualização maior para refletir arquitetura modular (cli/, core/, development/, infrastructure/, product/) [Story 6.13] | Pax (PO) |
Este é um padrão oficial do framework AIOX. Todo posicionamento de arquivos deve seguir esta estrutura.