create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-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 AIOX 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 squad
+*migrate-squad ./squads/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 `aiox.type` | Field not present | Add `aiox.type: squad` |
+| Missing `aiox.minVersion` | Field not present | Add `aiox.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: aiox.type
+  ❌ [ERROR] Missing required field: aiox.minVersion
+
+───────────────────────────────────────────────────────────
+PLANNED ACTIONS:
+───────────────────────────────────────────────────────────
+  1. Rename config.yaml → squad.yaml
+  2. Create directories: tasks, agents
+  3. Add field: aiox.type = "squad"
+  4. Add field: aiox.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: aiox.type = "squad" [success]
+    ✅ Add field: aiox.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: aiox.type = "squad" [dry-run]
+    🔍 Add field: aiox.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('./.aiox-core/development/scripts/squad');
+const { SquadValidator } = require('./.aiox-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:** .aiox-core/schemas/squad-schema.json
+- **Agent:** @squad-creator (Craft)
+- **Similar Tasks:** *validate-squad, *create-squad

package/template/.aiox-core/development/tasks/squad-creator-publish.md

@@ -0,0 +1,229 @@
+---
+task: Publish Squad
+responsavel: "@squad-creator"
+responsavel_type: agent
+atomic_layer: task
+status: active
+sprint: 8
+story: SQS-6
+Entrada: |
+  - squad_path: Caminho do squad para publicar (obrigatório)
+  - dry_run: Flag para simular sem criar PR (--dry-run)
+  - category: Categoria do squad (community | official)
+Saida: |
+  - pr_url: URL do Pull Request criado
+  - branch: Nome do branch criado
+  - validation_result: Resultado da validação pré-publish
+Checklist:
+  - "[ ] Validar squad (deve passar sem errors)"
+  - "[ ] Verificar autenticação GitHub"
+  - "[ ] Verificar se squad já existe no registry"
+  - "[ ] Criar branch no fork/clone"
+  - "[ ] Copiar arquivos do squad"
+  - "[ ] Atualizar registry.json"
+  - "[ ] Criar Pull Request"
+  - "[ ] Exibir URL do PR"
+---
+
+# *publish-squad
+
+Publishes a local squad to the aiox-squads GitHub repository via Pull Request.
+
+## Prerequisites
+
+- GitHub CLI installed and authenticated: `gh auth login`
+- Squad must pass validation with no errors
+- Squad must have required manifest fields (name, version)
+
+## Usage
+
+```bash
+@squad-creator
+
+# Publish squad (creates PR)
+*publish-squad ./squads/my-squad
+
+# Preview without creating PR
+*publish-squad ./squads/my-squad --dry-run
+
+# Verbose output
+*publish-squad ./squads/my-squad --verbose
+```
+
+## Examples
+
+### Dry Run (Preview)
+
+```
+*publish-squad ./squads/my-squad --dry-run
+
+[SquadPublisher] Dry run mode
+
+Squad: my-squad
+Version: 1.0.0
+Author: developer-name
+
+PR Preview:
+  Title: Add squad: my-squad
+  Branch: squad/my-squad
+  Target: SynkraAI/aiox-squads
+
+Components:
+  - Tasks: 5
+  - Agents: 2
+  - Workflows: 1
+
+✓ Validation passed
+✓ Ready to publish
+
+Run without --dry-run to create the actual PR.
+```
+
+### Publish (Create PR)
+
+```
+*publish-squad ./squads/my-squad
+
+Publishing: my-squad@1.0.0
+  Source: ./squads/my-squad/
+  Target: github.com/SynkraAI/aiox-squads
+
+✓ Validated successfully
+✓ GitHub auth verified (user: your-username)
+✓ Fork ready
+✓ Files copied to packages/my-squad/
+✓ registry.json updated
+✓ Committed changes
+✓ Pushed to fork
+
+Pull Request Created!
+  URL: https://github.com/SynkraAI/aiox-squads/pull/42
+  Branch: squad/my-squad
+
+Next steps:
+  1. Review the PR: gh pr view 42
+  2. Wait for maintainer review
+  3. Address any feedback
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview publish without creating PR |
+| `--verbose` | Show detailed progress |
+| `--category` | Squad category (default: community) |
+
+## Workflow
+
+```
+1. Validate squad
+   ├── Run SquadValidator
+   └── Must pass with 0 errors
+
+2. Load manifest
+   ├── Extract name, version, author
+   └── Extract components list
+
+3. Check GitHub auth
+   └── Verify gh auth status
+
+4. Create/check fork
+   └── Fork SynkraAI/aiox-squads if needed
+
+5. Clone fork to temp directory
+   └── Shallow clone for speed
+
+6. Create branch
+   └── squad/{squad-name}
+
+7. Copy squad files
+   └── To packages/{squad-name}/
+
+8. Update registry.json
+   ├── Add to community section
+   └── Sort alphabetically
+
+9. Commit and push
+   └── Include metadata in commit message
+
+10. Create PR
+    ├── Generate PR body from manifest
+    └── Target main branch
+
+11. Cleanup
+    └── Remove temp directory
+```
+
+## PR Body Template
+
+The generated PR body includes:
+
+```markdown
+## New Squad: {name}
+
+**Version:** {version}
+**Author:** {author}
+**Category:** community
+**Description:** {description}
+
+### Components
+
+| Type | Count |
+|------|-------|
+| Tasks | {n} |
+| Agents | {n} |
+| Workflows | {n} |
+
+### Pre-submission Checklist
+
+- [x] Squad follows AIOX task-first architecture
+- [x] Documentation is complete
+- [x] Squad validated locally
+- [ ] No sensitive data included
+```
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `AUTH_REQUIRED` | Not authenticated | Run `gh auth login` |
+| `VALIDATION_FAILED` | Squad has errors | Fix errors with `*validate-squad` |
+| `SQUAD_NOT_FOUND` | Invalid path | Check squad path exists |
+| `MANIFEST_ERROR` | Missing name/version | Update squad.yaml |
+| `PR_ERROR` | GitHub CLI error | Check `gh` is working |
+
+## Requirements
+
+### Manifest Fields
+
+Required for publishing:
+```yaml
+# squad.yaml
+name: my-squad          # Required
+version: 1.0.0          # Required
+description: "..."      # Recommended
+author: your-name       # Recommended
+```
+
+### Validation Rules
+
+Squad must pass validation:
+- Valid squad.yaml with required fields
+- Task files in tasks/ directory
+- No critical errors
+
+## Implementation
+
+Uses `SquadPublisher` class from:
+- `.aiox-core/development/scripts/squad/squad-publisher.js`
+
+## Related Tasks
+
+- `*validate-squad` - Validate before publishing
+- `*download-squad` - Download published squads
+- `*create-squad` - Create new local squad
+
+## Related Story
+
+- **SQS-6:** Download & Publish Tasks (Sprint 8)