# Instalar Node.js
brew install node@18
 
# Instalar GitHub CLI
brew install gh
 
# Autenticar GitHub CLI
gh auth login

# Instalar Node.js
choco install nodejs-lts
 
# Instalar GitHub CLI
choco install gh
 
# Autenticar GitHub CLI
gh auth login

# 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

# Clonar seu fork
git clone https://github.com/YOUR_USERNAME/aios-core.git
cd aios-core
 
# Adicionar remote upstream
git remote add upstream https://github.com/SynkraAI/aios-core.git
 
# Verificar remotes
git remote -v
# origin    https://github.com/YOUR_USERNAME/aios-core.git (fetch)
# origin    https://github.com/YOUR_USERNAME/aios-core.git (push)
# upstream  https://github.com/SynkraAI/aios-core.git (fetch)
# upstream  https://github.com/SynkraAI/aios-core.git (push)

# 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

# Instalar todas as dependências
npm install
 
# Isso também irá:
# - Configurar hooks do Husky (via script prepare)
# - Instalar dependências do workspace

# 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
AIOS_DEBUG=false
 
# Opcional: Configuração MCP
SYNKRA_API_TOKEN=your-synkra-token

# 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

# 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

aios-core/
├── .aios-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/AIOS/agents/      # Comandos de skill dos agentes
│   ├── hooks/                     # Hooks de governança
│   └── rules/                     # Regras de comportamento da IA
│
├── bin/                           # Pontos de entrada do CLI
│   ├── aios.js                    # CLI principal
│   └── aios-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

# 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

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

// 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');
    });
  });
});

# 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

# Arquivo: .aios-core/development/agents/my-agent.md

# 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
```

### 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 .aios-core/development/tasks/
  checklists:
    - my-agent-checklist.md  # Criar em .aios-core/development/checklists/
  tools:
    - git
    - context7

# Sincronizar novo agente para todas as IDEs
npm run sync:ide
 
# Verificar sincronização
npm run sync:ide:validate

# Convenções de nomenclatura:
# Específica de agente: [agent-id]-[task-name].md
# Compartilhada: [task-name].md
 
# Exemplos:
# .aios-core/development/tasks/dev-build-component.md  (agente dev)
# .aios-core/development/tasks/create-doc.md          (compartilhada)

---
## 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 (AIOS 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
```

pre-conditions:
  - [ ] Required inputs provided
    blocker: true

post-conditions:
  - [ ] Task completed successfully
    blocker: true

ELICIT: Information Collection
1. What is the input?
2. What is the expected output?

ELICIT: Validation
1. Is the input valid?
2. Are all dependencies available?

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

# Arquivo: .aios-core/development/workflows/my-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

# Executar linting
npm run lint
 
# Corrigir problemas auto-corrigíveis
npm run lint -- --fix

# Executar verificação de tipos
npm run typecheck

# Formatar todos os arquivos Markdown
npm run format

# 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"

# 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

# Executar todas as verificações
npm test
npm run lint
npm run typecheck
 
# Validar estrutura
npm run validate:structure

# 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

# 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
)"

# Definir variável de ambiente
export AIOS_DEBUG=true
 
# Executar com saída de debug
npm test -- --verbose

# Verificar logs de execução de agentes
ls -la .aios/logs/
 
# Tail do log de agente
tail -f .aios/logs/agent.log

# Limpar cache do Jest
npx jest --clearCache
 
# Limpar cache do npm
npm cache clean --force
 
# Reinstalar dependências
rm -rf node_modules
npm install

# Limpar cache do ESLint
rm .eslintcache
 
# Executar lint novamente
npm run lint

# Forçar IDE a usar TypeScript do projeto
# No VS Code: Ctrl+Shift+P -> "TypeScript: Select TypeScript Version" -> "Use Workspace Version"

# Validar YAML do arquivo do agente
npx js-yaml .aios-core/development/agents/my-agent.md
 
# Verificar se dependências existem
ls .aios-core/development/tasks/my-task.md

# 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

# Reinstalar Husky
npm run prepare
 
# Verificar se hooks existem
ls -la .husky/

# Rastrear execução de workflow
AIOS_DEBUG=true npm run trace -- workflow-name
 
# Verificar estado do workflow
cat .aios/state/workflow-state.json

# Fazer profiling da execução de testes
npm test -- --detectOpenHandles
 
# Verificar vazamentos de memória
node --inspect node_modules/.bin/jest