Migração de Squads

Como migrar squads entre versões

4 min de leitura
squadsmigração

Squad Migration Guide

EN | PT | ES

How to migrate legacy squads to AIOX 2.1 format.

Overview

AIOX 2.1 introduced a new squad format with:

  • Task-first architecture
  • JSON Schema validation
  • Three-level distribution
  • Standardized manifest (squad.yaml)

Legacy squads using config.yaml or older formats need migration.

Detecting Legacy Squads

Signs of Legacy Format

| Indicator | Legacy | Current (2.1+) | |-----------|--------|----------------| | Manifest file | config.yaml | squad.yaml | | AIOX type field | Missing | aiox.type: squad | | Min version | Missing | aiox.minVersion: "2.1.0" | | Structure | Agent-first | Task-first |

Check Command

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

Output will indicate if migration is needed:

⚠️ Legacy format detected (config.yaml)
   Run: *migrate-squad ./squads/legacy-squad

Migration Command

Preview Changes (Recommended First)

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

Shows what will change without modifying files.

Execute Migration

*migrate-squad ./squads/legacy-squad

Verbose Output

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

Shows detailed step-by-step progress.

What Gets Migrated

1. Manifest Rename

config.yaml → squad.yaml

2. Added Fields

# These fields are added if missing
aiox:
  minVersion: "2.1.0"
  type: squad

3. Structure Normalization

Components are reorganized into the standard structure:

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

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

4. File Format Conversion

Agent YAML files are converted to Markdown format:

# Before: my-agent.yaml
name: my-agent
role: Helper

# After: agents/my-agent.md
# my-agent

ACTIVATION-NOTICE: ...

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

Migration Scenarios

Scenario 1: Simple Squad (config.yaml only)

Before:

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

Command:

*migrate-squad ./squads/my-squad

After:

my-squad/
├── squad.yaml         # Renamed + updated
├── README.md
└── .backup/           # Backup created
    └── pre-migration-2025-12-26/

Scenario 2: Squad with YAML Agents

Before:

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

Command:

*migrate-squad ./squads/my-squad

After:

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

Scenario 3: Partial Migration (Already Has Some 2.1 Features)

Before:

my-squad/
├── squad.yaml         # Already renamed
├── agent.yaml         # Still YAML format
└── tasks/
    └── task.md        # Already MD format

Command:

*migrate-squad ./squads/my-squad

Result:

  • Adds missing aiox fields to manifest
  • Converts remaining YAML files
  • Skips already-migrated files

Backup & Rollback

Automatic Backup

Every migration creates a backup:

.backup/
└── pre-migration-{timestamp}/
    ├── config.yaml    # Original manifest
    ├── agent.yaml     # Original files
    └── ...

Manual Rollback

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

# Restore specific backup
cp -r ./squads/my-squad/.backup/pre-migration-2025-12-26/. ./squads/my-squad/

Programmatic Rollback

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

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

Troubleshooting

"Manifest not found"

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

Solution: Create a basic manifest:

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

aiox:
  minVersion: "2.1.0"
  type: squad

components:
  agents: []
  tasks: []

"Invalid YAML syntax"

Error: YAML parse error at line 15

Solution:

  1. Check YAML syntax with a linter
  2. Common issues: tabs (use spaces), missing quotes
  3. Fix errors, then retry migration

"Backup failed"

Error: Could not create backup directory

Solution:

  1. Check write permissions: chmod 755 ./squads/my-squad
  2. Check disk space
  3. Try with sudo (if appropriate)

"Migration incomplete"

Warning: Some files could not be migrated

Solution:

  1. Run with --verbose to see which files failed
  2. Manually fix problematic files
  3. Re-run migration

Post-Migration Checklist

After migration, verify:

  • [ ] squad.yaml exists and is valid
  • [ ] aiox.type is "squad"
  • [ ] aiox.minVersion is "2.1.0" or higher
  • [ ] All agents are in agents/ folder
  • [ ] All tasks are in tasks/ folder
  • [ ] Agent files are in Markdown format
  • [ ] Task files follow TASK-FORMAT-SPEC-V1
  • [ ] Validation passes: *validate-squad --strict

Programmatic Migration

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

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

// Check if migration needed
const needsMigration = await migrator.needsMigration('./squads/my-squad');

// Run migration
const result = await migrator.migrate('./squads/my-squad');

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

Related Resources

Version: 1.0.0 | Updated: 2025-12-26 | Story: SQS-8

Falar com o Time