aiox-core 5.0.0

package/.aiox-core/development/tasks/squad-creator-sync-ide-command.md

@@ -0,0 +1,402 @@
+---
+task: Sync Command to IDE Configurations
+responsavel: '@squad-creator'
+responsavel_type: agent
+atomic_layer: task
+status: active
+sprint: 9
+story: SQC-12
+version: 1.0.0
+Entrada: |
+  - type: agent | task | workflow | squad (obrigatório)
+  - name: Nome do componente para sincronizar (obrigatório)
+  - ides: Lista de IDEs alvo (opcional, default: todas ativas)
+  - dry_run: Preview sem sincronizar (--dry-run)
+  - force: Sobrescrever existentes (--force)
+Saida: |
+  - sync_results: Mapa de resultados por IDE
+  - files_created: Lista de arquivos criados
+  - files_updated: Lista de arquivos atualizados
+  - files_skipped: Lista de arquivos pulados
+Checklist:
+  - '[x] Carregar .aiox-sync.yaml'
+  - '[x] Localizar arquivo fonte em squads/'
+  - '[x] Verificar arquivos existentes nos destinos'
+  - '[x] Sincronizar para cada IDE ativa'
+  - '[x] Validar arquivos criados'
+---
+
+# \*command
+
+Sincroniza agents, tasks, workflows ou squads inteiros para todas as configurações de IDE configuradas no projeto.
+
+## Uso
+
+```bash
+# Sincronizar um agent específico
+*command agent legal-chief
+
+# Sincronizar uma task
+*command task revisar-contrato
+
+# Sincronizar um workflow
+*command workflow legal-workflow
+
+# Sincronizar squad inteiro (todos os componentes)
+*command squad legal
+
+# Preview sem executar
+*command agent legal-chief --dry-run
+
+# Forçar sobrescrita
+*command squad legal --force
+```
+
+## Output Exemplo
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *command squad legal
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Loading sync configuration...
+   Active IDEs: claude, cursor
+   Pack alias: legal → Legal
+
+📦 Syncing squad: legal
+
+Step 1: Locating source files
+   ✓ squads/legal/config.yaml
+   ✓ Found 8 agents
+   ✓ Found 4 tasks
+   ✓ Found 6 checklists
+   ✓ Found 1 data file
+
+Step 2: Syncing to Claude Code
+   ✓ .claude/commands/Legal/agents/legal-chief.md
+   ✓ .claude/commands/Legal/agents/brad-feld.md
+   ✓ .claude/commands/Legal/agents/ken-adams.md
+   ✓ .claude/commands/Legal/agents/pierpaolo-bottini.md
+   ✓ .claude/commands/Legal/agents/tributarista.md
+   ✓ .claude/commands/Legal/agents/trabalhista.md
+   ✓ .claude/commands/Legal/agents/societarista.md
+   ✓ .claude/commands/Legal/agents/lgpd-specialist.md
+   ✓ .claude/commands/Legal/tasks/revisar-contrato.md
+   ... (4 tasks, 6 checklists, 1 data)
+
+Step 3: Syncing to Cursor
+   ✓ .cursor/rules/legal-chief.mdc
+   ✓ .cursor/rules/brad-feld.mdc
+   ... (8 agents converted to MDC)
+
+Step 4: Validation
+   ✓ All files validated
+
+═══════════════════════════════════════════════
+✅ SYNC COMPLETE
+═══════════════════════════════════════════════
+
+Summary:
+  Files created:  19
+  Files updated:  0
+  Files skipped:  0
+  IDEs synced:    2
+
+🚀 Commands available:
+   /Legal:agents:legal-chief (Claude Code)
+   @legal-chief (Cursor rule)
+```
+
+## Configuração
+
+### .aiox-sync.yaml
+
+O sistema usa `.aiox-sync.yaml` na raiz do projeto para configuração:
+
+```yaml
+# IDEs ativas para sincronização
+active_ides:
+  - claude # .claude/commands/
+  - cursor # .cursor/rules/
+  # - gemini    # .gemini/
+
+# Mapeamento de diretório → prefixo de comando
+squad_aliases:
+  legal: Legal
+  copy: Copy
+  hr: HR
+  data: Data
+
+# Mapeamentos de sincronização
+sync_mappings:
+  squad_agents:
+    source: 'squads/*/agents/'
+    destinations:
+      claude:
+        - path: '.claude/commands/{squad_alias}/agents/'
+          format: 'md'
+      cursor:
+        - path: '.cursor/rules/'
+          format: 'mdc'
+          wrapper: 'cursor-rule'
+```
+
+### Squad Aliases
+
+O `squad_aliases` mapeia o nome do diretório do squad para o prefixo usado nos comandos:
+
+| Diretório       | Alias   | Comando Claude              |
+| --------------- | ------- | --------------------------- |
+| `squads/legal/` | `Legal` | `/Legal:agents:legal-chief` |
+| `squads/copy/`  | `Copy`  | `/Copy:agents:copy-chief`   |
+| `squads/hr/`    | `HR`    | `/HR:agents:hr-chief`       |
+
+## Workflow Interno
+
+```
+┌──────────────────────────────────────────────────┐
+│                  *command                         │
+├──────────────────────────────────────────────────┤
+│                                                   │
+│  1. Parse type + name                             │
+│     ↓                                             │
+│  2. Load .aiox-sync.yaml                          │
+│     ↓ (not found → create default)                │
+│  3. Resolve squad alias                           │
+│     ↓                                             │
+│  4. Locate source files in squads/                │
+│     ↓ (not found → error)                         │
+│  5. Check existing files in destinations          │
+│     ↓ (exists + no --force → ask)                 │
+│  6. For each active IDE:                          │
+│     │                                             │
+│     ├── Claude: Copy MD → .claude/commands/       │
+│     ├── Cursor: Convert MD → MDC                  │
+│     ├── Gemini: Copy MD → .gemini/agents/         │
+│     ↓                                             │
+│  7. Validate created files                        │
+│     ↓                                             │
+│  8. Log to .aiox-sync.log                         │
+│     ↓                                             │
+│  9. Display summary                               │
+│                                                   │
+└──────────────────────────────────────────────────┘
+```
+
+## Conversão de Formatos
+
+### MD → MDC (Cursor)
+
+Cursor usa formato MDC com frontmatter YAML:
+
+**Entrada (MD):**
+
+```markdown
+# legal-chief
+
+ACTIVATION-NOTICE: This file contains...
+
+## COMPLETE AGENT DEFINITION
+
+...
+```
+
+**Saída (MDC):**
+
+```markdown
+---
+description: Diretor Jurídico & Orquestrador de Especialistas
+globs: []
+alwaysApply: false
+---
+
+# legal-chief
+
+ACTIVATION-NOTICE: This file contains...
+...
+```
+
+### Extração de Description
+
+A description é extraída de:
+
+1. Campo `whenToUse` no YAML do agent
+2. Primeiro parágrafo após o título
+3. Campo `title` se disponível
+
+## Flags
+
+| Flag            | Descrição                              | Default |
+| --------------- | -------------------------------------- | ------- |
+| `--dry-run`     | Preview sem criar arquivos             | false   |
+| `--force`       | Sobrescrever arquivos existentes       | false   |
+| `--verbose`     | Output detalhado                       | false   |
+| `--ide=X`       | Sincronizar apenas para IDE específica | todas   |
+| `--no-validate` | Pular validação pós-sync               | false   |
+
+## Tipos de Componentes
+
+### Agent (`*command agent {name}`)
+
+Sincroniza um arquivo de agent:
+
+- Source: `squads/{squad}/agents/{name}.md`
+- Claude: `.claude/commands/{SquadAlias}/agents/{name}.md`
+- Cursor: `.cursor/rules/{name}.mdc`
+
+### Task (`*command task {name}`)
+
+Sincroniza um arquivo de task:
+
+- Source: `squads/{squad}/tasks/{name}.md`
+- Claude: `.claude/commands/{SquadAlias}/tasks/{name}.md`
+
+### Workflow (`*command workflow {name}`)
+
+Sincroniza um arquivo de workflow:
+
+- Source: `squads/{squad}/workflows/{name}.yaml`
+- Claude: `.claude/commands/{SquadAlias}/workflows/{name}.yaml`
+
+### Squad (`*command squad {name}`)
+
+Sincroniza TODOS os componentes de um squad:
+
+- Agents (todos em `agents/`)
+- Tasks (todos em `tasks/`)
+- Workflows (todos em `workflows/`)
+- Checklists (todos em `checklists/`)
+- Data (todos em `data/`)
+- Templates (todos em `templates/`)
+
+## Error Handling
+
+| Error                  | Causa                           | Solução                     |
+| ---------------------- | ------------------------------- | --------------------------- |
+| `Source not found`     | Arquivo não existe em squads/   | Verifique o nome e tipo     |
+| `Squad alias not found` | Squad não está em squad_aliases | Adicione ao .aiox-sync.yaml |
+| `File exists`          | Destino já existe               | Use --force ou escolha ação |
+| `IDE not active`       | IDE não está em active_ides     | Ative no .aiox-sync.yaml    |
+| `Invalid YAML`         | Arquivo fonte com YAML inválido | Corrija o arquivo fonte     |
+
+## Implementation Guide
+
+### Para Execução pelo Agent
+
+```javascript
+// 1. Parse argumentos
+const [type, name] = args;
+const flags = parseFlags(args);
+
+// 2. Validar tipo
+const validTypes = ['agent', 'task', 'workflow', 'squad'];
+if (!validTypes.includes(type)) {
+  error(`Invalid type: ${type}. Use: ${validTypes.join(', ')}`);
+  return;
+}
+
+// 3. Carregar configuração
+const syncConfig = loadYaml('.aiox-sync.yaml');
+const activeIdes = syncConfig.active_ides || ['claude'];
+const squadAliases = syncConfig.squad_aliases || syncConfig.pack_aliases || {};
+
+// 4. Localizar source
+let sourceFiles = [];
+if (type === 'squad') {
+  // Listar todos os componentes do squad
+  sourceFiles = findAllSquadFiles(`squads/${name}/`);
+} else {
+  // Localizar arquivo específico
+  const sourceFile = findSourceFile(type, name);
+  if (!sourceFile) {
+    error(`Source not found: ${name}`);
+    return;
+  }
+  sourceFiles = [sourceFile];
+}
+
+// 5. Determinar squad alias
+const squadName = extractSquadName(sourceFiles[0]);
+const squadAlias = squadAliases[squadName] || capitalize(squadName);
+
+// 6. Verificar existentes
+for (const file of sourceFiles) {
+  for (const ide of activeIdes) {
+    const destPath = getDestPath(ide, squadAlias, file);
+    if (fs.existsSync(destPath) && !flags.force) {
+      const action = await askUser(`${destPath} exists. Overwrite?`);
+      if (action === 'skip') continue;
+    }
+  }
+}
+
+// 7. Dry run check
+if (flags.dryRun) {
+  output('DRY RUN - Would sync:');
+  for (const file of sourceFiles) {
+    for (const ide of activeIdes) {
+      output(`  ${file} → ${getDestPath(ide, squadAlias, file)}`);
+    }
+  }
+  return;
+}
+
+// 8. Executar sync
+const results = { created: 0, updated: 0, skipped: 0 };
+
+for (const file of sourceFiles) {
+  for (const ide of activeIdes) {
+    const destPath = getDestPath(ide, packAlias, file);
+    const content = fs.readFileSync(file, 'utf8');
+    const converted = convertForIde(ide, content);
+
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, converted);
+
+    results.created++;
+    output(`✓ ${destPath}`);
+  }
+}
+
+// 9. Validar
+if (!flags.noValidate) {
+  validateSyncedFiles(sourceFiles, activeIdes, packAlias);
+}
+
+// 10. Log
+if (syncConfig.behavior?.log_sync_operations) {
+  appendLog('.aiox-sync.log', {
+    timestamp: new Date().toISOString(),
+    type,
+    name,
+    results,
+  });
+}
+
+// 11. Summary
+output(`
+═══════════════════════════════════════════════
+✅ SYNC COMPLETE
+═══════════════════════════════════════════════
+
+Summary:
+  Files created:  ${results.created}
+  Files updated:  ${results.updated}
+  Files skipped:  ${results.skipped}
+  IDEs synced:    ${activeIdes.length}
+`);
+```
+
+## Related Tasks
+
+- `*create-squad` - Criar novo squad
+- `*validate-squad` - Validar estrutura do squad
+- `*install-expansion-commands` - Instalar commands (versão anterior)
+- `*sync-squad-synkra` - Sincronizar para Synkra marketplace
+
+## Changelog
+
+| Version | Date       | Description                                |
+| ------- | ---------- | ------------------------------------------ |
+| 1.0.0   | 2026-01-27 | Full implementation with multi-IDE support |
+| 0.1.0   | 2026-01-27 | Initial spec                               |

package/.aiox-core/development/tasks/squad-creator-sync-synkra.md

@@ -0,0 +1,315 @@
+---
+task: Sync Squad to Synkra
+responsavel: "@squad-creator"
+responsavel_type: agent
+atomic_layer: task
+status: active
+sprint: 8
+story: SQS-5
+version: 1.0.0
+Entrada: |
+  - squad_path: Caminho do squad para sincronizar (obrigatório)
+  - visibility: public | private (default: private)
+  - official: Flag para marcar como oficial (--official, apenas SynkraAI)
+  - dry_run: Preview sem sincronizar (--dry-run)
+Saida: |
+  - sync_result: Resultado do sync (created | updated | skipped)
+  - squad_url: URL do squad no marketplace (quando público)
+  - squad_id: ID único do squad
+  - checksum: Checksum do squad sincronizado
+Checklist:
+  - "[x] Validar squad localmente"
+  - "[x] Obter token de autenticação"
+  - "[x] Calcular checksum"
+  - "[x] Enviar para Synkra API"
+  - "[x] Exibir URL do marketplace"
+---
+
+# *sync-squad-synkra
+
+Sincroniza um squad local para o Synkra API marketplace.
+
+## Uso
+
+```bash
+@squad-creator
+
+# Sync privado (apenas workspace)
+*sync-squad-synkra ./squads/meu-squad
+
+# Sync público (visível para todos)
+*sync-squad-synkra ./squads/meu-squad --public
+
+# Preview sem sincronizar
+*sync-squad-synkra ./squads/meu-squad --dry-run
+
+# Sync com verbosidade
+*sync-squad-synkra ./squads/meu-squad --verbose
+```
+
+## Autenticação
+
+Requer autenticação com Synkra API:
+
+```bash
+export SYNKRA_API_TOKEN="seu-token"
+```
+
+Ou configure em `.env`:
+
+```env
+SYNKRA_API_URL=https://api.synkra.dev/api
+SYNKRA_API_TOKEN=seu-token
+```
+
+Para obter um token:
+1. Acesse https://synkra.dev/settings/api-keys
+2. Crie uma nova API key com permissões de sync
+3. Configure a variável de ambiente
+
+## Output Exemplo
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *sync-squad-synkra
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Squad: ./squads/meu-squad/
+
+Step 1: Local Validation
+  ✓ Found squad.yaml
+  ✓ Name: meu-squad
+  ✓ Version: 1.0.0
+  ✓ Schema validation: PASSED
+
+Step 2: Calculate Checksum
+  ✓ Checksum: a1b2c3d4e5f6...
+
+Step 3: Sync to Synkra API
+  ✓ Visibility: private
+  ✓ API URL: https://api.synkra.dev/api
+
+Syncing to Synkra API...
+
+✅ Squad synced successfully!
+
+  Status:   created
+  ID:       550e8400-e29b-41d4-a716-446655440000
+  Checksum: a1b2c3d4e5f6...
+
+Next steps:
+  - View squad: *describe-squad meu-squad
+  - Make public: *sync-squad-synkra ./squads/meu-squad --public
+```
+
+## Flags
+
+| Flag | Descrição | Default |
+|------|-----------|---------|
+| `--public` | Torna o squad visível no marketplace público | false |
+| `--private` | Mantém squad privado (apenas workspace) | true |
+| `--dry-run` | Preview sem enviar para API | false |
+| `--verbose` | Output detalhado | false |
+| `--official` | Marca como squad oficial (apenas SynkraAI team) | false |
+| `--force` | Ignora warnings e força sync | false |
+
+## Workflow
+
+```
+┌──────────────────────────────────────────────────┐
+│              *sync-squad-synkra                   │
+├──────────────────────────────────────────────────┤
+│                                                   │
+│  1. Parse Arguments                               │
+│     ↓                                             │
+│  2. Find squad.yaml                               │
+│     ↓                                             │
+│  3. Validate with squad-validator.js              │
+│     ↓ (fail → abort)                              │
+│  4. Calculate SHA-256 checksum                    │
+│     ↓                                             │
+│  5. Check SYNKRA_API_TOKEN                        │
+│     ↓ (missing → abort)                           │
+│  6. If --dry-run: show preview and exit           │
+│     ↓                                             │
+│  7. POST to /api/squads/sync                      │
+│     ↓                                             │
+│  8. Display result and marketplace URL            │
+│                                                   │
+└──────────────────────────────────────────────────┘
+```
+
+## API Integration
+
+### Request
+
+```javascript
+POST ${SYNKRA_API_URL}/squads/sync
+Authorization: Bearer ${SYNKRA_API_TOKEN}
+Content-Type: application/json
+
+{
+  "squadData": {
+    "name": "meu-squad",
+    "version": "1.0.0",
+    "description": "...",
+    "author": "...",
+    "license": "MIT",
+    "components": {...},
+    "tags": [...]
+  },
+  "isPublic": false,
+  "isOfficial": false
+}
+```
+
+### Response (Success)
+
+```json
+{
+  "success": true,
+  "data": {
+    "action": "created",
+    "squad_id": "meu-squad",
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "version": "1.0.0"
+  },
+  "duration_ms": 150
+}
+```
+
+### Response (Error)
+
+```json
+{
+  "success": false,
+  "error": "Validation failed: Missing required field: version"
+}
+```
+
+## Implementation Guide
+
+### For Agent Execution
+
+```javascript
+// 1. Parse squad path from arguments
+const squadPath = args[0] || '.';
+const flags = parseFlags(args);
+
+// 2. Find and read squad.yaml
+const squadYamlPath = path.join(squadPath, 'squad.yaml');
+if (!fs.existsSync(squadYamlPath)) {
+  error(`squad.yaml not found in ${squadPath}`);
+  return;
+}
+
+// 3. Validate with squad-validator.js
+const { validateSquad } = await import('.aiox-core/development/scripts/squad/squad-validator.js');
+const validation = await validateSquad(squadYamlPath);
+
+if (!validation.valid) {
+  error(`Validation failed: ${validation.errors.join(', ')}`);
+  return;
+}
+
+if (validation.warnings.length > 0 && !flags.force) {
+  warn(`Warnings: ${validation.warnings.join(', ')}`);
+  // Consider prompting user to continue
+}
+
+// 4. Read and parse squad data
+const squadContent = fs.readFileSync(squadYamlPath, 'utf8');
+const squadData = parseYaml(squadContent);
+
+// 5. Calculate checksum
+const checksum = crypto.createHash('sha256')
+  .update(squadContent)
+  .digest('hex');
+
+// 6. Check authentication
+const apiToken = process.env.SYNKRA_API_TOKEN;
+const apiUrl = process.env.SYNKRA_API_URL || 'https://api.synkra.dev/api';
+
+if (!apiToken) {
+  error('SYNKRA_API_TOKEN not set. See task docs for authentication.');
+  return;
+}
+
+// 7. Dry run check
+if (flags.dryRun) {
+  output(`
+DRY RUN - Would sync:
+  Squad: ${squadData.name}
+  Version: ${squadData.version}
+  Checksum: ${checksum}
+  Visibility: ${flags.public ? 'public' : 'private'}
+  `);
+  return;
+}
+
+// 8. Call Synkra API
+const response = await fetch(`${apiUrl}/squads/sync`, {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${apiToken}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    squadData: {
+      ...squadData,
+      checksum,
+      raw_content: squadContent
+    },
+    isPublic: flags.public,
+    isOfficial: flags.official
+  })
+});
+
+const result = await response.json();
+
+// 9. Display result
+if (result.success) {
+  output(`
+✅ Squad synced successfully!
+
+  Status:   ${result.data.action}
+  ID:       ${result.data.id}
+  Squad ID: ${result.data.squad_id}
+  `);
+
+  if (flags.public) {
+    output(`  URL: https://synkra.dev/squads/${result.data.squad_id}`);
+  }
+} else {
+  error(`Sync failed: ${result.error}`);
+}
+```
+
+## Error Handling
+
+| Error | Causa | Solução |
+|-------|-------|---------|
+| `squad.yaml not found` | Caminho inválido | Verifique o path do squad |
+| `Validation failed` | Squad não passa na validação | Execute `*validate-squad` primeiro |
+| `SYNKRA_API_TOKEN not set` | Token não configurado | Configure a variável de ambiente |
+| `401 Unauthorized` | Token inválido ou expirado | Gere novo token em synkra.dev |
+| `403 Forbidden` | Sem permissão para operação | Verifique permissões da API key |
+| `Squad not found or not owned` | Tentando atualizar squad de outro workspace | Verifique ownership |
+
+## Related Tasks
+
+- `*create-squad` - Criar novo squad local
+- `*validate-squad` - Validar squad antes de sync
+- `*describe-squad` - Ver detalhes do squad
+- `*list-squads` - Listar squads disponíveis
+
+## Related Story
+
+- **SQS-5:** SquadSyncService for Synkra API (Sprint 8)
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0.0 | 2025-12-23 | Full implementation (Story SQS-5) |
+| 0.1.0 | 2025-12-18 | Initial placeholder |