aios-core 3.4.0 → 3.6.0

package/.aios-core/development/tasks/squad-creator-download.md

@@ -3,63 +3,165 @@ task: Download Squad
 responsavel: "@squad-creator"
 responsavel_type: agent
 atomic_layer: task
-status: placeholder
+status: active
 sprint: 8
+story: SQS-6
 Entrada: |
-  - name: Nome do squad para baixar
-  - source: Fonte (aios-squads | synkra-api)
+  - squad_name: Nome do squad para baixar (obrigatório)
+  - version: Versão específica (opcional, default: latest)
+  - list: Flag para listar squads disponíveis (--list)
+  - overwrite: Flag para sobrescrever squad existente (--overwrite)
 Saida: |
   - squad_path: Caminho do squad baixado
-  - status: Sucesso ou erro
+  - manifest: Manifest do squad
+  - validation_result: Resultado da validação
 Checklist:
-  - "[ ] Implementar em Sprint 8 (SQS-5)"
+  - "[ ] Verificar se já existe localmente"
+  - "[ ] Buscar no registry.json"
+  - "[ ] Baixar arquivos do GitHub"
+  - "[ ] Extrair para ./squads/{name}/"
+  - "[ ] Validar squad baixado"
+  - "[ ] Exibir próximos passos"
 ---
 
 # *download-squad
 
-> **PLACEHOLDER** - Implementation scheduled for Sprint 8 (Story SQS-5)
+Downloads public squads from the aios-squads GitHub repository to use in your project.
 
-## Planned Functionality
+## Usage
 
-Downloads a public squad from the aios-squads repository or Synkra API marketplace.
+```bash
+@squad-creator
+
+# List available squads
+*download-squad --list
+
+# Download a squad
+*download-squad etl-squad
 
-## Planned Usage
+# Download specific version
+*download-squad etl-squad@2.0.0
 
+# Overwrite existing
+*download-squad etl-squad --overwrite
 ```
-@squad-creator
 
+## Examples
+
+### List Available Squads
+
+```
+*download-squad --list
+
+Available Squads (from aios-squads):
+
+Official:
+  ├── etl-squad@1.0.0 - ETL pipeline automation
+  ├── api-squad@1.2.0 - REST API development
+  └── devops-squad@1.0.0 - CI/CD automation
+
+Community:
+  ├── data-viz-squad@0.5.0 - Data visualization
+  └── ml-squad@0.3.0 - Machine learning pipelines
+```
+
+### Download Squad
+
+```
 *download-squad etl-squad
-# → Downloads from github.com/SynkraAI/aios-squads
 
-*download-squad premium-pack --source synkra-api
-# → Downloads from api.synkra.dev/squads (requires auth)
+Downloading: etl-squad@1.0.0
+  Source: github.com/SynkraAI/aios-squads/packages/etl-squad
+  Target: ./squads/etl-squad/
+
+✓ Downloaded 12 files
+✓ Validated successfully
+
+Squad installed! Next steps:
+  1. Review: cat squads/etl-squad/squad.yaml
+  2. Activate: @squad-creator *activate etl-squad
 ```
 
-## Planned Features
+## Options
 
-1. **Repository Source (Default)**
-   - Clone from github.com/SynkraAI/aios-squads
-   - Support specific versions via tags
-   - Validate squad before installation
+| Option | Description |
+|--------|-------------|
+| `--list` | List all available squads from registry |
+| `--version` | Download specific version (e.g., @2.0.0) |
+| `--overwrite` | Overwrite if squad already exists locally |
+| `--verbose` | Show detailed download progress |
 
-2. **Synkra API Source**
-   - Download from api.synkra.dev/squads
-   - Support premium/paid squads
-   - Require authentication
+## How It Works
 
-3. **Installation**
-   - Install to ./squads/{name}/
-   - Run validation after download
-   - Show usage instructions
+```
+1. Fetch registry.json from aios-squads
+   ├── Contains official and community squads
+   └── Includes version and metadata
 
-## Related Story
+2. Find requested squad
+   ├── Search official squads first
+   └── Then community squads
 
-- **SQS-5:** SquadSyncService (Sprint 8)
-- **SQS-6:** Registry Integration (Sprint 8)
+3. Download via GitHub API
+   ├── Get directory listing
+   └── Download each file recursively
 
-## Current Status
+4. Validate downloaded squad
+   ├── Run SquadValidator
+   └── Report warnings/errors
+
+5. Load manifest
+   └── Confirm installation
+```
+
+## Registry Structure
+
+The registry.json in aios-squads contains:
+
+```json
+{
+  "version": "1.0.0",
+  "squads": {
+    "official": [
+      {
+        "name": "etl-squad",
+        "version": "1.0.0",
+        "description": "ETL pipeline automation",
+        "author": "SynkraAI"
+      }
+    ],
+    "community": [
+      {
+        "name": "data-viz-squad",
+        "version": "0.5.0",
+        "description": "Data visualization",
+        "author": "community-member"
+      }
+    ]
+  }
+}
+```
 
-This task is a placeholder. The full implementation will be done in Sprint 8.
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `SQUAD_NOT_FOUND` | Squad not in registry | Check available squads with --list |
+| `SQUAD_EXISTS` | Already downloaded | Use --overwrite flag |
+| `REGISTRY_FETCH_ERROR` | Network issue | Check connection |
+| `RATE_LIMIT` | GitHub API limit | Set GITHUB_TOKEN env var |
+
+## Implementation
+
+Uses `SquadDownloader` class from:
+- `.aios-core/development/scripts/squad/squad-downloader.js`
+
+## Related Tasks
+
+- `*validate-squad` - Validate downloaded squad
+- `*publish-squad` - Publish your squad to registry
+- `*create-squad` - Create new local squad
+
+## Related Story
 
-For now, manually clone squads from:
-- https://github.com/SynkraAI/aios-squads
+- **SQS-6:** Download & Publish Tasks (Sprint 8)

package/.aios-core/development/tasks/squad-creator-migrate.md

@@ -0,0 +1,243 @@
+---
+task: Migrate Squad
+responsável: @squad-creator
+responsável_type: agent
+atomic_layer: task
+Entrada: |
+  - squad_path: Path to the squad directory to migrate (required)
+  - dry_run: If true, preview changes without modifying files (--dry-run)
+  - verbose: If true, show detailed output (--verbose)
+Saída: |
+  - migration_result: Object with { success, actions, validation, backupPath }
+  - report: Formatted migration report
+  - exit_code: 0 if successful, 1 if failed
+Checklist:
+  - "[ ] Analyze squad for migration needs"
+  - "[ ] Create backup in .backup/"
+  - "[ ] Execute migration actions"
+  - "[ ] Validate migrated squad"
+  - "[ ] Generate migration report"
+---
+
+# *migrate-squad
+
+Migrates legacy squad formats to AIOS 2.1 standard.
+
+## Usage
+
+```
+@squad-creator
+
+# Preview changes without modifying files
+*migrate-squad ./squads/my-squad --dry-run
+
+# Migrate with automatic backup
+*migrate-squad ./squads/my-squad
+
+# Migrate with detailed output
+*migrate-squad ./squads/my-squad --verbose
+
+# Migrate expansion pack
+*migrate-squad ./expansion-packs/my-pack --verbose
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `squad_path` | string | - | Full path to squad directory (required) |
+| `--dry-run` | flag | false | Preview changes without modifying files |
+| `--verbose` | flag | false | Show detailed migration output |
+
+## Migration Detection
+
+The migrator detects the following legacy patterns:
+
+| Pattern | Detection | Migration Action |
+|---------|-----------|------------------|
+| `config.yaml` | Legacy manifest name | Rename to `squad.yaml` |
+| Flat structure | No `tasks/`, `agents/` dirs | Create directory structure |
+| Missing `aios.type` | Field not present | Add `aios.type: squad` |
+| Missing `aios.minVersion` | Field not present | Add `aios.minVersion: 2.1.0` |
+| Missing `name` | Field not present | Infer from directory name |
+| Missing `version` | Field not present | Add `version: 1.0.0` |
+
+## Flow
+
+```
+1. Analyze Squad
+   ├── Check for config.yaml vs squad.yaml
+   ├── Check directory structure
+   ├── Validate manifest schema
+   └── Generate action list
+
+2. Confirm Migration (if not --dry-run)
+   ├── Display issues found
+   ├── Display planned actions
+   └── Request user confirmation
+
+3. Create Backup
+   └── Copy all files to .backup/pre-migration-{timestamp}/
+
+4. Execute Actions
+   ├── RENAME_MANIFEST: config.yaml → squad.yaml
+   ├── CREATE_DIRECTORIES: tasks/, agents/, config/
+   ├── ADD_FIELD: Add missing required fields
+   └── MOVE_FILE: Reorganize files if needed
+
+5. Validate Result
+   ├── Run squad-validator on migrated squad
+   └── Report any remaining issues
+
+6. Generate Report
+   ├── Summary of changes made
+   ├── Backup location
+   └── Validation result
+```
+
+## Output Example
+
+### Analysis Phase
+
+```
+═══════════════════════════════════════════════════════════
+              SQUAD MIGRATION REPORT
+═══════════════════════════════════════════════════════════
+
+Squad Path: ./squads/my-legacy-squad/
+Needs Migration: Yes
+
+───────────────────────────────────────────────────────────
+ISSUES FOUND:
+───────────────────────────────────────────────────────────
+  ⚠️ [WARNING] Uses deprecated config.yaml manifest
+  ⚠️ [WARNING] Missing task-first directories: tasks, agents
+  ❌ [ERROR] Missing required field: aios.type
+  ❌ [ERROR] Missing required field: aios.minVersion
+
+───────────────────────────────────────────────────────────
+PLANNED ACTIONS:
+───────────────────────────────────────────────────────────
+  1. Rename config.yaml → squad.yaml
+  2. Create directories: tasks, agents
+  3. Add field: aios.type = "squad"
+  4. Add field: aios.minVersion = "2.1.0"
+
+═══════════════════════════════════════════════════════════
+```
+
+### Migration Result
+
+```
+───────────────────────────────────────────────────────────
+MIGRATION RESULT:
+───────────────────────────────────────────────────────────
+  Status: ✅ SUCCESS
+  Message: Migration completed successfully
+  Backup: ./squads/my-legacy-squad/.backup/pre-migration-1703318400000/
+
+  Executed Actions:
+    ✅ Rename config.yaml → squad.yaml [success]
+    ✅ Create directories: tasks, agents [success]
+    ✅ Add field: aios.type = "squad" [success]
+    ✅ Add field: aios.minVersion = "2.1.0" [success]
+
+  Post-Migration Validation:
+    Valid: Yes
+
+═══════════════════════════════════════════════════════════
+```
+
+### Dry-Run Mode
+
+```
+───────────────────────────────────────────────────────────
+MIGRATION RESULT:
+───────────────────────────────────────────────────────────
+  Status: ✅ SUCCESS
+  Message: Dry-run completed successfully
+
+  Executed Actions:
+    🔍 Rename config.yaml → squad.yaml [dry-run]
+    🔍 Create directories: tasks, agents [dry-run]
+    🔍 Add field: aios.type = "squad" [dry-run]
+    🔍 Add field: aios.minVersion = "2.1.0" [dry-run]
+
+═══════════════════════════════════════════════════════════
+```
+
+## Rollback Procedure
+
+If migration fails or produces unexpected results, restore from backup:
+
+```bash
+# List available backups
+ls ./squads/my-squad/.backup/
+
+# View backup contents
+ls ./squads/my-squad/.backup/pre-migration-1703318400000/
+
+# Restore from backup (removes current, restores backup)
+rm -rf ./squads/my-squad/squad.yaml ./squads/my-squad/tasks ./squads/my-squad/agents
+cp -r ./squads/my-squad/.backup/pre-migration-1703318400000/. ./squads/my-squad/
+
+# Verify restoration
+ls ./squads/my-squad/
+```
+
+## Error Codes
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| `SQUAD_NOT_FOUND` | Error | Squad directory doesn't exist |
+| `NO_MANIFEST` | Error | No config.yaml or squad.yaml found |
+| `BACKUP_FAILED` | Error | Failed to create backup |
+| `MIGRATION_FAILED` | Error | Action execution failed |
+| `VALIDATION_FAILED` | Warning | Post-migration validation found issues |
+| `INVALID_PATH` | Error | Invalid squad path provided |
+
+## Implementation
+
+```javascript
+const { SquadMigrator } = require('./.aios-core/development/scripts/squad');
+const { SquadValidator } = require('./.aios-core/development/scripts/squad');
+
+async function migrateSquad(options) {
+  const { squadPath, dryRun, verbose } = options;
+
+  // Create migrator with optional validator
+  const validator = new SquadValidator();
+  const migrator = new SquadMigrator({
+    dryRun,
+    verbose,
+    validator
+  });
+
+  // Analyze first
+  const analysis = await migrator.analyze(squadPath);
+
+  // Display analysis report
+  console.log(migrator.generateReport(analysis));
+
+  if (!analysis.needsMigration) {
+    console.log('Squad is already up to date. No migration needed.');
+    return 0;
+  }
+
+  // Execute migration
+  const result = await migrator.migrate(squadPath);
+
+  // Display final report
+  console.log(migrator.generateReport(analysis, result));
+
+  return result.success ? 0 : 1;
+}
+```
+
+## Related
+
+- **Story:** SQS-7 (Squad Migration Tool)
+- **Dependencies:** squad-migrator.js, squad-validator.js
+- **Schema:** .aios-core/schemas/squad-schema.json
+- **Agent:** @squad-creator (Craft)
+- **Similar Tasks:** *validate-squad, *create-squad