Skip to content

squad-migration.md

Latest commit

 

History

History
356 lines (252 loc) · 6.59 KB

squad-migration.md

File metadata and controls

356 lines (252 loc) · 6.59 KB
Raw

Guia de Migração de Squad

🌐 EN | PT | ES

Como migrar squads legados para o formato AIOX 2.1.

Visão Geral

AIOX 2.1 introduziu um novo formato de squad com:

  • Arquitetura task-first
  • Validação JSON Schema
  • Distribuição em três níveis
  • Manifesto padronizado (squad.yaml)

Squads legados usando config.yaml ou formatos mais antigos precisam de migração.

Detectando Squads Legados

Sinais de Formato Legado

Indicador Legado Atual (2.1+)
Arquivo de manifesto config.yaml squad.yaml
Campo AIOX type Ausente aiox.type: squad
Versão mínima Ausente aiox.minVersion: "2.1.0"
Estrutura Agent-first Task-first

Comando de Verificação

@squad-creator
*validate-squad ./squads/legacy-squad

A saída indicará se migração é necessária:

⚠️ Formato legado detectado (config.yaml)
   Execute: *migrate-squad ./squads/legacy-squad

Comando de Migração

Pré-visualizar Mudanças (Recomendado Primeiro)

@squad-creator
*migrate-squad ./squads/legacy-squad --dry-run

Mostra o que mudará sem modificar arquivos.

Executar Migração

*migrate-squad ./squads/legacy-squad

Saída Detalhada

*migrate-squad ./squads/legacy-squad --verbose

Mostra progresso detalhado passo a passo.

O Que É Migrado

1. Renomeação do Manifesto

config.yaml → squad.yaml

2. Campos Adicionados

# Estes campos são adicionados se ausentes
aiox:
  minVersion: '2.1.0'
  type: squad

3. Normalização de Estrutura

Componentes são reorganizados na estrutura padrão:

Antes:
├── config.yaml
├── my-agent.yaml
└── my-task.yaml

Depois:
├── squad.yaml
├── agents/
│   └── my-agent.md
└── tasks/
    └── my-task.md

4. Conversão de Formato de Arquivo

Arquivos YAML de agent são convertidos para formato Markdown:

# Antes: my-agent.yaml
name: my-agent
role: Helper
# Depois: agents/my-agent.md

# my-agent

ACTIVATION-NOTICE: ...

\`\`\`yaml
agent:
name: my-agent
...
\`\`\`

Cenários de Migração

Cenário 1: Squad Simples (apenas config.yaml)

Antes:

my-squad/
├── config.yaml
└── README.md

Comando:

*migrate-squad ./squads/my-squad

Depois:

my-squad/
├── squad.yaml         # Renomeado + atualizado
├── README.md
└── .backup/           # Backup criado
    └── pre-migration-2025-12-26/

Cenário 2: Squad com Agents YAML

Antes:

my-squad/
├── config.yaml
├── agent.yaml
└── task.yaml

Comando:

*migrate-squad ./squads/my-squad

Depois:

my-squad/
├── squad.yaml
├── agents/
│   └── agent.md       # Convertido para MD
├── tasks/
│   └── task.md        # Convertido para MD
└── .backup/

Cenário 3: Migração Parcial (Já Tem Alguns Recursos 2.1)

Antes:

my-squad/
├── squad.yaml         # Já renomeado
├── agent.yaml         # Ainda formato YAML
└── tasks/
    └── task.md        # Já formato MD

Comando:

*migrate-squad ./squads/my-squad

Resultado:

  • Adiciona campos aiox ausentes ao manifesto
  • Converte arquivos YAML restantes
  • Pula arquivos já migrados

Backup & Rollback

Backup Automático

Toda migração cria um backup:

.backup/
└── pre-migration-{timestamp}/
    ├── config.yaml    # Manifesto original
    ├── agent.yaml     # Arquivos originais
    └── ...

Rollback Manual

# Listar backups
ls ./squads/my-squad/.backup/

# Restaurar backup específico
cp -r ./squads/my-squad/.backup/pre-migration-2025-12-26/. ./squads/my-squad/

Rollback Programático

const { SquadMigrator } = require('./.aiox-core/development/scripts/squad');

const migrator = new SquadMigrator();
await migrator.rollback('./squads/my-squad');

Solução de Problemas

"Manifesto não encontrado"

Error: No manifest found (config.yaml or squad.yaml)

Solução: Crie um manifesto básico:

# squad.yaml
name: my-squad
version: 1.0.0
description: Meu squad

aiox:
  minVersion: '2.1.0'
  type: squad

components:
  agents: []
  tasks: []

"Sintaxe YAML inválida"

Error: YAML parse error at line 15

Solução:

  1. Verifique sintaxe YAML com um linter
  2. Problemas comuns: tabs (use espaços), aspas faltando
  3. Corrija erros, depois tente a migração novamente

"Falha no backup"

Error: Could not create backup directory

Solução:

  1. Verifique permissões de escrita: chmod 755 ./squads/my-squad
  2. Verifique espaço em disco
  3. Tente com sudo (se apropriado)

"Migração incompleta"

Warning: Some files could not be migrated

Solução:

  1. Execute com --verbose para ver quais arquivos falharam
  2. Corrija arquivos problemáticos manualmente
  3. Re-execute a migração

Checklist Pós-Migração

Após migração, verifique:

  • squad.yaml existe e é válido
  • aiox.type é "squad"
  • aiox.minVersion é "2.1.0" ou superior
  • Todos os agents estão na pasta agents/
  • Todas as tasks estão na pasta tasks/
  • Arquivos de agent estão em formato Markdown
  • Arquivos de task seguem TASK-FORMAT-SPEC-V1
  • Validação passa: *validate-squad --strict

Migração Programática

const { SquadMigrator } = require('./.aiox-core/development/scripts/squad');

const migrator = new SquadMigrator({
  verbose: true,
  dryRun: false,
  backupDir: '.backup',
});

// Verificar se migração é necessária
const needsMigration = await migrator.needsMigration('./squads/my-squad');

// Executar migração
const result = await migrator.migrate('./squads/my-squad');

console.log(result);
// {
//   success: true,
//   changes: ['config.yaml → squad.yaml', ...],
//   backupPath: '.backup/pre-migration-...'
// }

Recursos Relacionados

Versão: 1.0.0 | Atualizado: 2025-12-26 | Story: SQS-8