aiox-core 5.0.0

package/docs/pt/guides/development-setup.md

@@ -0,0 +1,1114 @@
+# Guia de Configuração de Desenvolvimento
+
+> [EN](../../guides/development-setup.md) | **PT** | [ES](../../es/guides/development-setup.md)
+
+---
+
+Guia completo para desenvolvedores que desejam contribuir com o projeto Synkra AIOX.
+
+**Versão:** 1.0.0
+**Última Atualização:** 2026-01-29
+
+---
+
+## Índice
+
+1. [Pré-requisitos](#pré-requisitos)
+2. [Fork e Clone](#fork-e-clone)
+3. [Configuração do Ambiente](#configuração-do-ambiente)
+4. [Estrutura do Projeto](#estrutura-do-projeto)
+5. [Executando Testes](#executando-testes)
+6. [Adicionando Novos Agentes](#adicionando-novos-agentes)
+7. [Criando Novas Tasks](#criando-novas-tasks)
+8. [Criando Novos Workflows](#criando-novos-workflows)
+9. [Padrões de Código](#padrões-de-código)
+10. [Processo de PR e Code Review](#processo-de-pr-e-code-review)
+11. [Debug e Solução de Problemas](#debug-e-solução-de-problemas)
+
+---
+
+## Pré-requisitos
+
+Antes de começar, certifique-se de ter os seguintes itens instalados:
+
+| Ferramenta     | Versão Mínima   | Comando de Verificação | Finalidade           |
+| -------------- | --------------- | ---------------------- | -------------------- |
+| **Node.js**    | 18.0.0          | `node --version`       | Runtime JavaScript   |
+| **npm**        | 9.0.0           | `npm --version`        | Gerenciador de pacotes |
+| **Git**        | 2.30+           | `git --version`        | Controle de versão   |
+| **GitHub CLI** | 2.0+            | `gh --version`         | Operações no GitHub  |
+
+### Ferramentas Recomendadas
+
+| Ferramenta           | Finalidade                                    |
+| -------------------- | --------------------------------------------- |
+| **Claude Code**      | Desenvolvimento com IA usando agentes AIOX    |
+| **VS Code / Cursor** | IDE com integração AIOX                       |
+| **Docker Desktop**   | Servidores MCP e ferramentas containerizadas  |
+
+### Instalando os Pré-requisitos
+
+**macOS (Homebrew):**
+
+```bash
+# Instalar Node.js
+brew install node@18
+
+# Instalar GitHub CLI
+brew install gh
+
+# Autenticar GitHub CLI
+gh auth login
+```
+
+**Windows (Chocolatey):**
+
+```bash
+# Instalar Node.js
+choco install nodejs-lts
+
+# Instalar GitHub CLI
+choco install gh
+
+# Autenticar GitHub CLI
+gh auth login
+```
+
+**Linux (Ubuntu/Debian):**
+
+```bash
+# Instalar Node.js via NodeSource
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Instalar GitHub CLI
+sudo apt install gh
+
+# Autenticar GitHub CLI
+gh auth login
+```
+
+---
+
+## Fork e Clone
+
+### Passo 1: Fazer Fork do Repositório
+
+1. Navegue até [github.com/SynkraAI/aiox-core](https://github.com/SynkraAI/aiox-core)
+2. Clique no botão **Fork** no canto superior direito
+3. Selecione sua conta do GitHub como destino
+
+### Passo 2: Clonar Seu Fork
+
+```bash
+# Clonar seu fork
+git clone https://github.com/YOUR_USERNAME/aiox-core.git
+cd aiox-core
+
+# Adicionar remote upstream
+git remote add upstream https://github.com/SynkraAI/aiox-core.git
+
+# Verificar remotes
+git remote -v
+# origin    https://github.com/YOUR_USERNAME/aiox-core.git (fetch)
+# origin    https://github.com/YOUR_USERNAME/aiox-core.git (push)
+# upstream  https://github.com/SynkraAI/aiox-core.git (fetch)
+# upstream  https://github.com/SynkraAI/aiox-core.git (push)
+```
+
+### Passo 3: Manter-se Atualizado
+
+```bash
+# Buscar últimas alterações do upstream
+git fetch upstream
+
+# Fazer merge do main upstream no seu main local
+git checkout main
+git merge upstream/main
+
+# Enviar para seu fork
+git push origin main
+```
+
+---
+
+## Configuração do Ambiente
+
+### Passo 1: Instalar Dependências
+
+```bash
+# Instalar todas as dependências
+npm install
+
+# Isso também irá:
+# - Configurar hooks do Husky (via script prepare)
+# - Instalar dependências do workspace
+```
+
+### Passo 2: Variáveis de Ambiente
+
+Crie um arquivo `.env` na raiz do projeto (este arquivo é ignorado pelo git):
+
+```bash
+# Configuração do Provedor de IA
+ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# Opcional: Fallback OpenAI
+OPENAI_API_KEY=your-openai-api-key
+
+# Configurações do Framework
+NODE_ENV=development
+AIOX_DEBUG=false
+
+# Opcional: Configuração MCP
+SYNKRA_API_TOKEN=your-synkra-token
+```
+
+### Passo 3: Verificar Instalação
+
+```bash
+# Executar a suite de testes
+npm test
+
+# Verificar linting
+npm run lint
+
+# Verificar TypeScript
+npm run typecheck
+
+# Validar estrutura do projeto
+npm run validate:structure
+```
+
+### Passo 4: Integração com IDE (Opcional)
+
+Sincronizar agentes AIOX com sua IDE:
+
+```bash
+# Sincronizar para todas as IDEs suportadas
+npm run sync:ide
+
+# Sincronizar para IDE específica
+npm run sync:ide:cursor
+
+# Validar sincronização
+npm run sync:ide:validate
+```
+
+---
+
+## Estrutura do Projeto
+
+Entendendo a estrutura de diretórios do `aiox-core`:
+
+```
+aiox-core/
+├── .aiox-core/                    # Fonte do framework (commitado)
+│   ├── core/                      # Utilitários e configurações principais
+│   │   ├── config/                # Arquivos de configuração do framework
+│   │   ├── docs/                  # Documentação interna
+│   │   └── registry/              # Registro de componentes
+│   │
+│   ├── development/               # Assets de desenvolvimento
+│   │   ├── agents/                # Definições de agentes (*.md)
+│   │   ├── checklists/            # Checklists de validação
+│   │   ├── scripts/               # Scripts utilitários (JS)
+│   │   ├── tasks/                 # Workflows de tasks (*.md)
+│   │   └── workflows/             # Workflows multi-etapas (*.yaml)
+│   │
+│   ├── infrastructure/            # Build e deployment
+│   │   ├── scripts/               # Sincronização de IDE, validação
+│   │   └── config/                # Configuração de infraestrutura
+│   │
+│   └── product/                   # Assets de produto
+│       ├── templates/             # Templates de documentos
+│       └── checklists/            # Checklists de produto
+│
+├── .claude/                       # Configuração do Claude Code
+│   ├── commands/AIOX/agents/      # Comandos de skill dos agentes
+│   ├── hooks/                     # Hooks de governança
+│   └── rules/                     # Regras de comportamento da IA
+│
+├── bin/                           # Pontos de entrada do CLI
+│   ├── aiox.js                    # CLI principal
+│   └── aiox-minimal.js            # CLI mínimo
+│
+├── docs/                          # Toda documentação
+│   ├── architecture/              # Arquitetura do sistema
+│   ├── guides/                    # Guias de usuário e desenvolvedor
+│   ├── migration/                 # Guias de migração
+│   ├── prd/                       # Requisitos de produto
+│   └── stories/                   # Stories de desenvolvimento
+│
+├── packages/                      # Pacotes do monorepo
+│   └── */                         # Pacotes individuais
+│
+├── scripts/                       # Scripts de build e utilitários
+│
+├── squads/                        # Definições locais de squads
+│
+├── src/                           # Código fonte
+│
+├── tests/                         # Suites de teste
+│   ├── health-check/              # Testes de health check
+│   └── unit/                      # Testes unitários
+│
+├── tools/                         # Ferramentas CLI e utilitários
+│
+├── package.json                   # Manifesto do projeto
+├── tsconfig.json                  # Configuração TypeScript
+├── eslint.config.mjs              # Configuração ESLint
+└── jest.config.js                 # Configuração Jest
+```
+
+### Diretórios Principais
+
+| Diretório                           | Finalidade                    | Quando Modificar          |
+| ----------------------------------- | ----------------------------- | ------------------------- |
+| `.aiox-core/development/agents/`    | Personas e comportamentos de agentes | Adicionar/modificar agentes |
+| `.aiox-core/development/tasks/`     | Workflows de tasks executáveis | Adicionar/modificar tasks |
+| `.aiox-core/development/workflows/` | Orquestrações multi-etapas    | Criar workflows           |
+| `.claude/rules/`                    | Regras de comportamento da IA | Adicionar restrições      |
+| `docs/stories/`                     | Stories de desenvolvimento    | Trabalhar em features     |
+| `src/`                              | Código fonte do framework     | Funcionalidade principal  |
+| `tests/`                            | Suites de teste               | Todas as alterações       |
+
+---
+
+## Executando Testes
+
+### Comandos de Teste
+
+```bash
+# Executar todos os testes
+npm test
+
+# Executar testes em modo watch (desenvolvimento)
+npm run test:watch
+
+# Executar testes com relatório de cobertura
+npm run test:coverage
+
+# Executar testes de health check
+npm run test:health-check
+```
+
+### Estrutura de Testes
+
+```
+tests/
+├── health-check/           # Testes de integração
+│   └── *.test.js           # Arquivos de teste de health check
+├── unit/                   # Testes unitários
+│   └── *.test.js           # Arquivos de teste unitário
+└── fixtures/               # Fixtures de teste e mocks
+```
+
+### Escrevendo Testes
+
+**Exemplo de Teste Unitário:**
+
+```javascript
+// tests/unit/example.test.js
+const { describe, it, expect } = require('@jest/globals');
+
+describe('ComponentName', () => {
+  describe('methodName', () => {
+    it('should handle expected input', () => {
+      const result = myFunction('input');
+      expect(result).toBe('expected');
+    });
+
+    it('should throw on invalid input', () => {
+      expect(() => myFunction(null)).toThrow('Invalid input');
+    });
+  });
+});
+```
+
+### Executando Testes Específicos
+
+```bash
+# Executar testes correspondendo ao padrão
+npm test -- --testPathPattern="agent"
+
+# Executar arquivo de teste único
+npm test -- tests/unit/agent.test.js
+
+# Executar com saída detalhada
+npm test -- --verbose
+```
+
+---
+
+## Adicionando Novos Agentes
+
+Agentes são personas de IA que fornecem capacidades especializadas. Cada agente é definido em um arquivo Markdown com frontmatter YAML.
+
+### Passo 1: Planejar Seu Agente
+
+| Aspecto           | Perguntas a Responder                        |
+| ----------------- | -------------------------------------------- |
+| **Propósito**     | Que problema específico este agente resolve? |
+| **Expertise**     | Que conhecimento de domínio o agente deve ter? |
+| **Comandos**      | Que ações o agente pode executar?            |
+| **Colaboração**   | Com quais outros agentes ele trabalha?       |
+
+### Passo 2: Criar Arquivo do Agente
+
+Crie um novo arquivo em `.aiox-core/development/agents/`:
+
+```bash
+# Arquivo: .aiox-core/development/agents/my-agent.md
+```
+
+### Passo 3: Template de Agente
+
+````markdown
+# my-agent
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines.
+
+## COMPLETE AGENT DEFINITION FOLLOWS
+
+```yaml
+agent:
+  name: AgentName
+  id: my-agent
+  title: Agent Role Title
+  icon: emoji
+  whenToUse: 'Short description of when to use this agent'
+
+persona_profile:
+  archetype: ArchetypeType # Builder, Guardian, Orchestrator, etc.
+
+  communication:
+    tone: professional # pragmatic, analytical, friendly, etc.
+    emoji_frequency: medium # low, medium, high
+
+    vocabulary:
+      - domain-specific
+      - terms
+      - here
+
+    greeting_levels:
+      minimal: 'icon Agent ready'
+      named: 'icon AgentName ready!'
+      archetypal: 'icon AgentName the Archetype ready!'
+
+    signature_closing: '-- AgentName, closing phrase'
+
+persona:
+  role: Expert description
+  style: Communication style description
+  identity: Core identity statement
+  focus: Primary focus area
+
+core_principles:
+  - Principle 1
+  - Principle 2
+  - Principle 3
+
+commands:
+  - name: help
+    visibility: [full, quick, key]
+    description: 'Show all available commands'
+  - name: my-command
+    visibility: [full, quick]
+    description: 'Description of what this command does'
+
+dependencies:
+  tasks:
+    - relevant-task.md
+  checklists:
+    - relevant-checklist.md
+  tools:
+    - tool-name
+```
+````
+
+---
+
+## Comandos Rápidos
+
+**Comandos Principais:**
+
+- `*help` - Mostrar todos os comandos
+- `*my-command` - Executar comando personalizado
+- `*exit` - Sair do modo agente
+
+**Colaboração:**
+
+- Trabalha com: @other-agent
+- Delega para: @specialist-agent
+
+---
+
+````
+
+### Passo 4: Adicionar Dependências
+
+Se seu agente usa tasks ou checklists, certifique-se de que existem:
+
+```yaml
+dependencies:
+  tasks:
+    - my-agent-task.md       # Criar em .aiox-core/development/tasks/
+  checklists:
+    - my-agent-checklist.md  # Criar em .aiox-core/development/checklists/
+  tools:
+    - git
+    - context7
+````
+
+### Passo 5: Sincronizar para IDEs
+
+```bash
+# Sincronizar novo agente para todas as IDEs
+npm run sync:ide
+
+# Verificar sincronização
+npm run sync:ide:validate
+```
+
+---
+
+## Criando Novas Tasks
+
+Tasks são workflows executáveis que agentes usam para realizar ações.
+
+### Passo 1: Planejar Sua Task
+
+| Aspecto        | Descrição                       |
+| -------------- | ------------------------------- |
+| **Propósito**  | O que esta task realiza?        |
+| **Entradas**   | Quais dados ela precisa?        |
+| **Saídas**     | O que ela produz?               |
+| **Etapas**     | Qual é o fluxo de execução?     |
+| **Validação**  | Como sabemos se teve sucesso?   |
+
+### Passo 2: Criar Arquivo de Task
+
+Crie um novo arquivo em `.aiox-core/development/tasks/`:
+
+```bash
+# Convenções de nomenclatura:
+# Específica de agente: {agent-id}-{task-name}.md
+# Compartilhada: {task-name}.md
+
+# Exemplos:
+# .aiox-core/development/tasks/dev-build-component.md  (agente dev)
+# .aiox-core/development/tasks/create-doc.md          (compartilhada)
+```
+
+### Passo 3: Template de Task
+
+````markdown
+---
+## Modos de Execução
+
+**Escolha seu modo de execução:**
+
+### 1. Modo YOLO - Rápido, Autônomo (0-1 prompts)
+- Tomada de decisão autônoma com logging
+- Interação mínima com usuário
+- **Ideal para:** Tasks simples e determinísticas
+
+### 2. Modo Interativo - Equilibrado, Educacional (5-10 prompts) **[PADRÃO]**
+- Checkpoints de decisão explícitos
+- Explicações educacionais
+- **Ideal para:** Aprendizado, decisões complexas
+
+### 3. Planejamento Pre-Flight - Planejamento Abrangente Inicial
+- Fase de análise da task (identificar todas as ambiguidades)
+- Execução sem ambiguidades
+- **Ideal para:** Requisitos ambíguos, trabalho crítico
+
+---
+
+## Definição da Task (AIOX Task Format V1.0)
+
+```yaml
+task: myTaskFunction()
+responsável: AgentName
+responsavel_type: Agente
+atomic_layer: Config
+
+**Entrada:**
+- campo: inputName
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be non-empty
+
+**Saída:**
+- campo: outputName
+  tipo: string
+  destino: File system
+  persistido: true
+```
+````
+
+---
+
+## Pré-Condições
+
+```yaml
+pre-conditions:
+  - [ ] Required inputs provided
+    blocker: true
+```
+
+---
+
+## Pós-Condições
+
+```yaml
+post-conditions:
+  - [ ] Task completed successfully
+    blocker: true
+```
+
+---
+
+# Título da Task
+
+## Propósito
+
+Descrição clara do que esta task realiza.
+
+## Pré-requisitos
+
+- Pré-requisito 1
+- Pré-requisito 2
+
+## Processo de Elicitação Interativa
+
+### Passo 1: Coletar Informações
+
+```
+ELICIT: Information Collection
+1. What is the input?
+2. What is the expected output?
+```
+
+### Passo 2: Validar
+
+```
+ELICIT: Validation
+1. Is the input valid?
+2. Are all dependencies available?
+```
+
+## Passos de Implementação
+
+1. **Título do Passo Um**
+   - Descrição da ação
+   - Exemplo de código se necessário
+
+2. **Título do Passo Dois**
+   - Descrição da ação
+
+3. **Título do Passo Três**
+   - Descrição da ação
+
+## Checklist de Validação
+
+- [ ] Critério 1
+- [ ] Critério 2
+- [ ] Critério 3
+
+## Tratamento de Erros
+
+- Se X falhar: Fazer Y
+- Se Z estiver faltando: Solicitar entrada
+
+## Saída de Sucesso
+
+```
+Task completed successfully!
+Output: {output}
+```
+
+````
+
+### Passo 4: Referenciar no Agente
+
+Adicione a task às dependências do seu agente:
+
+```yaml
+dependencies:
+  tasks:
+    - my-new-task.md
+````
+
+---
+
+## Criando Novos Workflows
+
+Workflows orquestram múltiplos agentes e tasks para operações complexas.
+
+### Passo 1: Planejar Seu Workflow
+
+| Aspecto         | Descrição                     |
+| --------------- | ----------------------------- |
+| **Objetivo**    | Qual é o resultado final?     |
+| **Etapas**      | Quais fases ele possui?       |
+| **Agentes**     | Quais agentes participam?     |
+| **Transições**  | Como as etapas se conectam?   |
+
+### Passo 2: Criar Arquivo de Workflow
+
+Crie um novo arquivo em `.aiox-core/development/workflows/`:
+
+```bash
+# Arquivo: .aiox-core/development/workflows/my-workflow.yaml
+```
+
+### Passo 3: Template de Workflow
+
+```yaml
+workflow:
+  id: my-workflow
+  name: My Workflow Name
+  description: |
+    Detailed description of what this workflow accomplishes
+    and when it should be used.
+  type: development # development, deployment, analysis
+  scope: fullstack # ui, service, fullstack
+
+stages:
+  - id: stage-1-planning
+    name: Planning Phase
+    description: Initial planning and requirements gathering
+    agent: pm
+    tasks:
+      - create-story
+    outputs:
+      - Story file created
+      - Requirements documented
+    next: stage-2-design
+
+  - id: stage-2-design
+    name: Design Phase
+    description: Architecture and technical design
+    agent: architect
+    tasks:
+      - analyze-impact
+    outputs:
+      - Architecture document
+      - Technical specifications
+    next: stage-3-implement
+
+  - id: stage-3-implement
+    name: Implementation Phase
+    description: Code implementation
+    agent: dev
+    tasks:
+      - develop-story
+    outputs:
+      - Source code
+      - Unit tests
+    next: stage-4-review
+
+  - id: stage-4-review
+    name: Review Phase
+    description: Quality assurance
+    agent: qa
+    tasks:
+      - code-review
+    outputs:
+      - Review feedback
+      - Test results
+    next: null # End of workflow
+
+transitions:
+  - from: stage-1-planning
+    to: stage-2-design
+    condition: "Story status is 'Ready for Design'"
+
+  - from: stage-2-design
+    to: stage-3-implement
+    condition: 'Architecture approved'
+
+  - from: stage-3-implement
+    to: stage-4-review
+    condition: 'All tests passing'
+
+resources:
+  templates:
+    - story-template.md
+    - architecture-template.md
+  data:
+    - project-config.yaml
+
+validation:
+  checkpoints:
+    - stage: stage-1-planning
+      criteria: 'Story file exists and is valid'
+    - stage: stage-3-implement
+      criteria: 'All acceptance criteria implemented'
+    - stage: stage-4-review
+      criteria: 'Code review approved'
+
+metadata:
+  version: 1.0.0
+  author: Your Name
+  created: 2026-01-29
+  tags:
+    - development
+    - feature
+```
+
+---
+
+## Padrões de Código
+
+### Configuração ESLint
+
+O projeto usa ESLint 9 com configuração flat:
+
+```bash
+# Executar linting
+npm run lint
+
+# Corrigir problemas auto-corrigíveis
+npm run lint -- --fix
+```
+
+**Regras Principais:**
+
+- Sem variáveis não utilizadas (error)
+- Espaçamento e formatação consistentes
+- Sem console.log em código de produção (warn)
+- Preferir const sobre let
+
+### Configuração TypeScript
+
+```bash
+# Executar verificação de tipos
+npm run typecheck
+```
+
+**Configurações Principais do tsconfig.json:**
+
+- `strict: true` - Segurança de tipos completa
+- `noEmit: true` - Apenas verificação de tipos (sem compilação)
+- `esModuleInterop: true` - Compatibilidade CommonJS/ES module
+
+### Formatação Prettier
+
+```bash
+# Formatar todos os arquivos Markdown
+npm run format
+```
+
+### Convenções de Nomenclatura
+
+| Tipo          | Convenção   | Exemplo                     |
+| ------------- | ----------- | --------------------------- |
+| **Arquivos**  | kebab-case  | `my-component.js`           |
+| **Classes**   | PascalCase  | `MyComponent`               |
+| **Funções**   | camelCase   | `myFunction`                |
+| **Constantes**| UPPER_SNAKE | `MAX_RETRIES`               |
+| **Agentes**   | kebab-case  | `dev`, `qa`, `architect`    |
+| **Tasks**     | kebab-case  | `create-story`, `dev-build` |
+
+### Convenções de Commit
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+# Feature
+git commit -m "feat: add new agent validation"
+
+# Correção de bug
+git commit -m "fix: resolve task execution error"
+
+# Documentação
+git commit -m "docs: update development guide"
+
+# Chore (manutenção)
+git commit -m "chore: update dependencies"
+
+# Com escopo
+git commit -m "feat(agents): add data-engineer agent"
+git commit -m "fix(tasks): handle missing input gracefully"
+```
+
+### Hooks Pre-commit
+
+Husky executa estas verificações antes de cada commit:
+
+1. **lint-staged**: Executa ESLint e Prettier nos arquivos staged
+2. **IDE sync**: Atualiza configurações da IDE se agentes mudaram
+
+---
+
+## Processo de PR e Code Review
+
+### Passo 1: Criar Branch de Feature
+
+```bash
+# Criar branch a partir do main
+git checkout main
+git pull upstream main
+git checkout -b feat/my-feature
+
+# Ou para correções
+git checkout -b fix/bug-description
+```
+
+### Passo 2: Fazer Alterações
+
+Siga a abordagem de desenvolvimento orientado a stories:
+
+1. Verificar se existe uma story ou criar uma
+2. Implementar alterações seguindo as tasks da story
+3. Atualizar checkboxes da story conforme progride
+4. Adicionar testes para novas funcionalidades
+5. Atualizar documentação se necessário
+
+### Passo 3: Executar Verificações de Qualidade
+
+```bash
+# Executar todas as verificações
+npm test
+npm run lint
+npm run typecheck
+
+# Validar estrutura
+npm run validate:structure
+```
+
+### Passo 4: Commit e Push
+
+```bash
+# Stage das alterações
+git add -A
+
+# Commit com mensagem convencional
+git commit -m "feat: implement my feature"
+
+# Push para seu fork
+git push origin feat/my-feature
+```
+
+### Passo 5: Criar Pull Request
+
+```bash
+# Usando GitHub CLI
+gh pr create --title "feat: implement my feature" --body "$(cat <<'EOF'
+## Summary
+- Added feature X
+- Updated component Y
+
+## Test plan
+- [ ] Unit tests pass
+- [ ] Manual testing completed
+- [ ] Documentation updated
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Diretrizes de Code Review
+
+**Como Autor:**
+
+- Mantenha PRs focados e pequenos (< 500 linhas quando possível)
+- Forneça descrição clara e contexto
+- Responda ao feedback prontamente
+- Solicite re-review após alterações
+
+**Como Revisor:**
+
+- Revise dentro de 24 horas
+- Seja construtivo e específico
+- Aprove quando satisfeito ou solicite alterações
+- Use sugestões do GitHub para pequenas correções
+
+### Requisitos para Merge
+
+| Requisito              | Descrição                       |
+| ---------------------- | ------------------------------- |
+| **Testes passando**    | Todos os testes de CI devem passar |
+| **Lint limpo**         | Sem erros de ESLint             |
+| **Tipos válidos**      | Compilação TypeScript bem-sucedida |
+| **Review aprovado**    | Pelo menos uma aprovação        |
+| **Conflitos resolvidos** | Sem conflitos de merge        |
+
+---
+
+## Debug e Solução de Problemas
+
+### Habilitar Modo Debug
+
+```bash
+# Definir variável de ambiente
+export AIOX_DEBUG=true
+
+# Executar com saída de debug
+npm test -- --verbose
+```
+
+### Visualizar Logs de Agentes
+
+```bash
+# Verificar logs de execução de agentes
+ls -la .aiox/logs/
+
+# Tail do log de agente
+tail -f .aiox/logs/agent.log
+```
+
+### Problemas Comuns
+
+#### Problema: Testes falhando localmente mas passando no CI
+
+**Causa:** Diferenças de ambiente ou cache desatualizado
+
+**Solução:**
+
+```bash
+# Limpar cache do Jest
+npx jest --clearCache
+
+# Limpar cache do npm
+npm cache clean --force
+
+# Reinstalar dependências
+rm -rf node_modules
+npm install
+```
+
+#### Problema: Erros de ESLint após fazer pull de alterações
+
+**Causa:** Cache do ESLint está desatualizado
+
+**Solução:**
+
+```bash
+# Limpar cache do ESLint
+rm .eslintcache
+
+# Executar lint novamente
+npm run lint
+```
+
+#### Problema: Erros de TypeScript na IDE mas não no CLI
+
+**Causa:** Versão do TypeScript diferente na IDE
+
+**Solução:**
+
+```bash
+# Forçar IDE a usar TypeScript do projeto
+# No VS Code: Ctrl+Shift+P -> "TypeScript: Select TypeScript Version" -> "Use Workspace Version"
+```
+
+#### Problema: Agente não ativando
+
+**Causa:** Erro de sintaxe no arquivo do agente ou dependências faltando
+
+**Solução:**
+
+```bash
+# Validar YAML do arquivo do agente
+npx js-yaml .aiox-core/development/agents/my-agent.md
+
+# Verificar se dependências existem
+ls .aiox-core/development/tasks/my-task.md
+```
+
+#### Problema: IDE não mostrando comandos do agente
+
+**Causa:** Sincronização de IDE não executada ou falhou
+
+**Solução:**
+
+```bash
+# Executar sincronização
+npm run sync:ide
+
+# Validar sincronização
+npm run sync:ide:validate
+
+# Verificar diretório específico da IDE
+ls .cursor/  # Para Cursor
+```
+
+#### Problema: Hooks pre-commit não executando
+
+**Causa:** Husky não instalado corretamente
+
+**Solução:**
+
+```bash
+# Reinstalar Husky
+npm run prepare
+
+# Verificar se hooks existem
+ls -la .husky/
+```
+
+### Debugando Execução de Workflow
+
+```bash
+# Rastrear execução de workflow
+AIOX_DEBUG=true npm run trace -- workflow-name
+
+# Verificar estado do workflow
+cat .aiox/state/workflow-state.json
+```
+
+### Profiling de Performance
+
+```bash
+# Fazer profiling da execução de testes
+npm test -- --detectOpenHandles
+
+# Verificar vazamentos de memória
+node --inspect node_modules/.bin/jest
+```
+
+---
+
+## Obtendo Ajuda
+
+### Recursos
+
+- **GitHub Discussions:** [github.com/SynkraAI/aiox-core/discussions](https://github.com/SynkraAI/aiox-core/discussions)
+- **Issue Tracker:** [github.com/SynkraAI/aiox-core/issues](https://github.com/SynkraAI/aiox-core/issues)
+- **Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+### Labels de Issues
+
+| Label              | Caso de Uso                  |
+| ------------------ | ---------------------------- |
+| `bug`              | Algo está quebrado           |
+| `feature`          | Solicitação de nova funcionalidade |
+| `documentation`    | Melhorias na documentação    |
+| `good-first-issue` | Bom para iniciantes          |
+| `help-wanted`      | Ajuda da comunidade apreciada |
+
+### Contatar Mantenedores
+
+- Veja o arquivo `CODEOWNERS` para propriedade de módulos
+- Marque `@SynkraAI/core-team` para issues urgentes
+
+---
+
+## Documentação Relacionada
+
+- [Guia do Usuário](./user-guide.md) - Documentação para usuários finais
+- [Visão Geral da Arquitetura](../architecture/ARCHITECTURE-INDEX.md) - Design do sistema
+- [Contribuindo com Squads](./contributing-squads.md) - Desenvolvimento de squads
+- [Guia de Quality Gates](./quality-gates.md) - Garantia de qualidade
+- [Configuração Global MCP](./mcp-global-setup.md) - Configuração MCP
+
+---
+
+_Synkra AIOX Development Setup Guide v1.0.0_
+_Última Atualização: 2026-01-29_