aios-core 3.4.0 → 3.6.0

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

@@ -3,84 +3,227 @@ task: Publish 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 publicar
-  - target: Destino (aios-squads | synkra-api)
+  - 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 PR criado (para aios-squads)
-  - api_url: URL na API (para synkra-api)
-  - status: Sucesso ou erro
+  - pr_url: URL do Pull Request criado
+  - branch: Nome do branch criado
+  - validation_result: Resultado da validação pré-publish
 Checklist:
-  - "[ ] Implementar em Sprint 8 (SQS-6)"
+  - "[ ] 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
 
-> **PLACEHOLDER** - Implementation scheduled for Sprint 8 (Story SQS-6)
+Publishes a local squad to the aios-squads GitHub repository via Pull Request.
 
-## Planned Functionality
+## Prerequisites
 
-Publishes a local squad to the aios-squads repository (via PR) or Synkra API marketplace.
+- GitHub CLI installed and authenticated: `gh auth login`
+- Squad must pass validation with no errors
+- Squad must have required manifest fields (name, version)
 
-## Planned Usage
+## Usage
 
-```
+```bash
 @squad-creator
 
-*publish-squad meu-squad
-# → Creates PR to github.com/SynkraAI/aios-squads
+# 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 meu-squad --target synkra-api
-# → Publishes to api.synkra.dev/squads (requires auth)
 ```
+*publish-squad ./squads/my-squad --dry-run
 
-## Planned Features
+[SquadPublisher] Dry run mode
 
-1. **Pre-publish Validation**
-   - Run *validate-squad before publishing
-   - Check required fields in squad.yaml
-   - Verify license and author info
+Squad: my-squad
+Version: 1.0.0
+Author: developer-name
 
-2. **GitHub Repository (Default)**
-   - Fork aios-squads if needed
-   - Copy squad to squads/{name}/
-   - Create PR with description
-   - Add appropriate labels
+PR Preview:
+  Title: Add squad: my-squad
+  Branch: squad/my-squad
+  Target: SynkraAI/aios-squads
 
-3. **Synkra API**
-   - Upload to api.synkra.dev/squads
-   - Support pricing configuration
-   - Manage versions and updates
+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/aios-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/aios-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 *validate-squad
-   └── Ensure no errors
+   ├── 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/aios-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}/
 
-2. Prepare for publishing
-   ├── Check license
-   ├── Check author
-   └── Generate changelog
+8. Update registry.json
+   ├── Add to community section
+   └── Sort alphabetically
 
-3. Publish
-   ├── If aios-squads → Create PR
-   └── If synkra-api → Upload via API
+9. Commit and push
+   └── Include metadata in commit message
 
-4. Display result
-   └── Show URL and next steps
+10. Create PR
+    ├── Generate PR body from manifest
+    └── Target main branch
+
+11. Cleanup
+    └── Remove temp directory
 ```
 
-## Related Story
+## 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 AIOS task-first architecture
+- [x] Documentation is complete
+- [x] Squad validated locally
+- [ ] No sensitive data included
+```
+
+## Error Handling
 
-- **SQS-6:** Registry Integration (Sprint 8)
+| 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 |
 
-## Current Status
+## Requirements
 
-This task is a placeholder. The full implementation will be done in Sprint 8.
+### 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:
+- `.aios-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
 
-For now, manually create PRs at:
-- https://github.com/SynkraAI/aios-squads
+- **SQS-6:** Download & Publish Tasks (Sprint 8)

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

@@ -3,81 +3,313 @@ task: Sync Squad to Synkra
 responsavel: "@squad-creator"
 responsavel_type: agent
 atomic_layer: task
-status: placeholder
+status: active
 sprint: 8
+story: SQS-5
+version: 1.0.0
 Entrada: |
-  - name: Nome do squad para sincronizar
-  - pricing: Modelo de preco (free | premium | subscription)
+  - 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: |
-  - api_url: URL na Synkra API
-  - dashboard_url: URL do dashboard de gestao
-  - status: Sucesso ou erro
+  - 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:
-  - "[ ] Implementar em Sprint 8 (SQS-5)"
+  - "[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
 
-> **PLACEHOLDER** - Implementation scheduled for Sprint 8 (Story SQS-5)
+Sincroniza um squad local para o Synkra API marketplace.
 
-## Planned Functionality
+## Uso
 
-Syncs a local squad to the Synkra API marketplace for distribution and monetization.
+```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
+```
 
-## Planned Usage
+## Autenticação
+
+Requer autenticação com Synkra API:
 
 ```bash
-@squad-creator
+export SYNKRA_API_TOKEN="seu-token"
+```
 
-*sync-squad-synkra meu-squad
-# → Syncs to api.synkra.dev/squads (free tier)
+Ou configure em `.env`:
 
-*sync-squad-synkra meu-squad --pricing premium --price 9.99
-# → Syncs as premium squad with pricing
+```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 meu-squad --update
-# → Updates existing squad in marketplace
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *sync-squad-synkra
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Squad: ./squads/meu-squad/
 
-## Planned Features
+Step 1: Local Validation
+  ✓ Found squad.yaml
+  ✓ Name: meu-squad
+  ✓ Version: 1.0.0
+  ✓ Schema validation: PASSED
 
-1. **Authentication**
-   - Require Synkra API key
-   - Validate account permissions
-   - Support team accounts
+Step 2: Calculate Checksum
+  ✓ Checksum: a1b2c3d4e5f6...
 
-2. **Pricing Models**
-   - Free: Available to all users
-   - Premium: One-time purchase
-   - Subscription: Monthly/yearly
+Step 3: Sync to Synkra API
+  ✓ Visibility: private
+  ✓ API URL: https://api.synkra.dev/api
 
-3. **Version Management**
-   - Semantic versioning
-   - Changelog generation
-   - Update existing squads
+Syncing to Synkra API...
 
-4. **Analytics Dashboard**
-   - Download statistics
-   - Revenue tracking (for paid)
-   - User feedback
+✅ Squad synced successfully!
 
-## Synkra API Endpoints
+  Status:   created
+  ID:       550e8400-e29b-41d4-a716-446655440000
+  Checksum: a1b2c3d4e5f6...
 
-```http
-POST   /api/v1/squads           # Create new squad
-PUT    /api/v1/squads/{id}      # Update existing
-GET    /api/v1/squads/{id}      # Get squad info
-DELETE /api/v1/squads/{id}      # Remove squad
-GET    /api/v1/squads/me        # List my squads
+Next steps:
+  - View squad: *describe-squad meu-squad
+  - Make public: *sync-squad-synkra ./squads/meu-squad --public
 ```
 
-## Related Story
+## 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('.aios-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';
 
-- **SQS-5:** SquadSyncService (Sprint 8)
+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
 
-## Current Status
+- **SQS-5:** SquadSyncService for Synkra API (Sprint 8)
 
-This task is a placeholder. The full implementation will be done in Sprint 8.
+## Changelog
 
-The Synkra API is under development at:
-- https://api.synkra.dev (planned)
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0.0 | 2025-12-23 | Full implementation (Story SQS-5) |
+| 0.1.0 | 2025-12-18 | Initial placeholder |