Guia de Desenvolvimento de Squads

┌─────────────────────────────────────────────────────────────┐
│                    DISTRIBUIÇÃO DE SQUAD                     │
├─────────────────────────────────────────────────────────────┤
│  Nível 1: LOCAL        → ./squads/           (Privado)      │
│  Nível 2: AIOS-SQUADS  → github.com/SynkraAI (Público/Free) │
│  Nível 3: SYNKRA API   → api.synkra.dev      (Marketplace)  │
└─────────────────────────────────────────────────────────────┘

# Ativar agente squad-creator
@squad-creator
 
# Projetar squad a partir da sua documentação
*design-squad --docs ./docs/prd/my-project.md
 
# Revisar recomendações, depois criar
*create-squad my-squad --from-design
 
# Validar antes de usar
*validate-squad my-squad

@squad-creator
 
# Criar com prompts interativos
*create-squad my-domain-squad
 
# Ou especificar template
*create-squad my-squad --template etl

./squads/my-squad/
├── squad.yaml              # Manifesto (obrigatório)
├── README.md               # Documentação
├── LICENSE                 # Arquivo de licença
├── config/
│   ├── coding-standards.md # Regras de estilo de código
│   ├── tech-stack.md       # Tecnologias utilizadas
│   └── source-tree.md      # Estrutura de diretórios
├── agents/
│   └── my-agent.md         # Definições de agentes
├── tasks/
│   └── my-task.md          # Definições de tarefas (task-first!)
├── workflows/
│   └── my-workflow.yaml    # Workflows de múltiplas etapas
├── checklists/
│   └── review-checklist.md # Checklists de validação
├── templates/
│   └── report-template.md  # Templates de documentos
├── tools/
│   └── custom-tool.js      # Integrações de ferramentas personalizadas
├── scripts/
│   └── setup.js            # Scripts utilitários
└── data/
    └── reference-data.json # Arquivos de dados estáticos

# Campos obrigatórios
name: my-squad # kebab-case, identificador único
version: 1.0.0 # Versionamento semântico
description: O que este squad faz
 
# Metadados
author: Seu Nome <email@example.com>
license: MIT
slashPrefix: my # Prefixo de comando para IDE
 
# Compatibilidade AIOS
aios:
  minVersion: '2.1.0'
  type: squad
 
# Declaração de componentes
components:
  agents:
    - my-agent.md
  tasks:
    - my-task.md
  workflows: []
  checklists: []
  templates: []
  tools: []
  scripts: []
 
# Herança de configuração
config:
  extends: extend # extend | override | none
  coding-standards: config/coding-standards.md
  tech-stack: config/tech-stack.md
  source-tree: config/source-tree.md
 
# Dependências
dependencies:
  node: [] # pacotes npm
  python: [] # pacotes pip
  squads: [] # Outros squads
 
# Tags de descoberta
tags:
  - domain-specific
  - automation

Requisição do Usuário → Task → Execução do Agent → Saída
                         ↓
                    Workflow (se múltiplas etapas)

# Ativar o agente
@squad-creator
 
# Ver todos os comandos
*help

@squad-creator
 
# Design interativo
*design-squad
 
# Design a partir de arquivos específicos
*design-squad --docs ./docs/prd/requirements.md ./docs/specs/api.md
 
# Especificar contexto de domínio
*design-squad --domain casting --docs ./docs/

# .squad-design.yaml
metadata:
  domain: casting
  created: 2025-12-26T10:00:00Z
  source_docs:
    - ./docs/prd/casting-system.md
 
recommended_agents:
  - name: casting-coordinator
    role: Coordena workflows de casting
    confidence: 0.92
 
recommended_tasks:
  - name: process-submission
    description: Processar submissão de ator
    agent: casting-coordinator
    confidence: 0.88

@squad-creator
 
# Análise básica
*analyze-squad my-squad
 
# Incluir detalhes de arquivo
*analyze-squad my-squad --verbose
 
# Salvar em arquivo markdown
*analyze-squad my-squad --format markdown
 
# Saída como JSON
*analyze-squad my-squad --format json

=== Análise do Squad: my-squad ===

Visão Geral
  Nome: my-squad
  Versão: 1.0.0
  Autor: Seu Nome

Componentes
  agents/ (2)
    - lead-agent.md
    - helper-agent.md
  tasks/ (3)
    - lead-agent-task1.md
    - lead-agent-task2.md
    - helper-agent-task1.md
  workflows/ (0) <- Vazio
  checklists/ (0) <- Vazio

Cobertura
  Agents: [#####-----] 50% (1/2 com tasks)
  Tasks: [########--] 80% (3 tasks)
  Diretórios: [##--------] 25% (2/8 populados)

Sugestões
  1. [!] Adicionar tasks para helper-agent (atualmente tem apenas 1)
  2. [*] Criar workflows para sequências comuns
  3. [-] Adicionar checklists para validação

Próximo: *extend-squad my-squad

@squad-creator
 
# Modo interativo (guiado)
*extend-squad my-squad
 
# Modo direto - Adicionar agent
*extend-squad my-squad --add agent --name analytics-agent
 
# Adicionar task com vinculação de agent
*extend-squad my-squad --add task --name process-data --agent lead-agent
 
# Adicionar workflow com referência de story
*extend-squad my-squad --add workflow --name daily-processing --story SQS-11
 
# Adicionar todos os tipos de componente
*extend-squad my-squad --add template --name report-template
*extend-squad my-squad --add tool --name data-validator
*extend-squad my-squad --add checklist --name quality-checklist
*extend-squad my-squad --add script --name migration-helper
*extend-squad my-squad --add data --name config-data

@squad-creator
*extend-squad my-squad

? O que você gostaria de adicionar?
  1. Agent - Nova persona de agent
  2. Task - Nova task para um agent
  3. Workflow - Workflow de múltiplas etapas
  4. Checklist - Checklist de validação
  5. Template - Template de documento
  6. Tool - Ferramenta personalizada (JavaScript)
  7. Script - Script de automação
  8. Data - Arquivo de dados estático (YAML)

> 2

? Nome da task: process-data
? Qual agent é dono desta task?
  1. lead-agent
  2. helper-agent
> 1
? Descrição da task (opcional): Processar dados de entrada e gerar saída
? Vincular a story? (deixe em branco para pular): SQS-11

Criando task...
  Criado: tasks/lead-agent-process-data.md
  Atualizado: squad.yaml (adicionado a components.tasks)
  Validação: PASSOU

Próximos passos:
  1. Editar tasks/lead-agent-process-data.md
  2. Adicionar entrada/saída/checklist
  3. Executar: *validate-squad my-squad

# 1. Analisar estado atual
*analyze-squad my-squad
 
# 2. Revisar sugestões e métricas de cobertura
 
# 3. Adicionar componentes faltantes
*extend-squad my-squad --add task --name new-task --agent lead-agent
*extend-squad my-squad --add checklist --name quality-checklist
 
# 4. Re-analisar para verificar melhoria
*analyze-squad my-squad
 
# 5. Validar antes de usar
*validate-squad my-squad

const { SquadAnalyzer } = require('./.aios-core/development/scripts/squad/squad-analyzer');
const { SquadExtender } = require('./.aios-core/development/scripts/squad/squad-extender');
 
// Analisar squad
const analyzer = new SquadAnalyzer({ squadsPath: './squads' });
const analysis = await analyzer.analyze('my-squad');
 
console.log('Cobertura:', analysis.coverage);
console.log('Sugestões:', analysis.suggestions);
 
// Estender squad
const extender = new SquadExtender({ squadsPath: './squads' });
const result = await extender.addComponent('my-squad', {
  type: 'task',
  name: 'new-task',
  agentId: 'lead-agent',
  description: 'Uma nova task',
  storyId: 'SQS-11',
});
 
console.log('Criado:', result.filePath);
console.log('Manifesto atualizado:', result.manifestUpdated);

@squad-creator
*validate-squad my-squad

*validate-squad my-squad --strict

Validando squad: my-squad
═══════════════════════════

✅ Manifesto: Válido
✅ Estrutura: Completa
✅ Tasks: 3/3 válidas
✅ Agents: 2/2 válidos
⚠️ Avisos:
   - README.md está mínimo (considere expandir)

Resumo: VÁLIDO (3 avisos)

const { SquadValidator } = require('./.aios-core/development/scripts/squad');
 
const validator = new SquadValidator({ strict: false });
const result = await validator.validate('./squads/my-squad');
 
console.log(result);
// { valid: true, errors: [], warnings: [...], suggestions: [...] }

# Listar squads locais
*list-squads

@squad-creator
 
# Validar primeiro
*validate-squad my-squad --strict
 
# Publicar no GitHub
*publish-squad ./squads/my-squad

# Configurar autenticação
export SYNKRA_API_TOKEN="your-token"
 
# Sincronizar com marketplace
*sync-squad-synkra ./squads/my-squad --public

@squad-creator
 
# Listar squads disponíveis
*download-squad --list
 
# Baixar squad específico
*download-squad etl-squad
 
# Baixar versão específica
*download-squad etl-squad@2.0.0

@squad-creator
 
# Pré-visualizar mudanças
*migrate-squad ./squads/legacy-squad --dry-run
 
# Executar migração
*migrate-squad ./squads/legacy-squad
 
# Saída detalhada
*migrate-squad ./squads/legacy-squad --verbose

# Restaurar do backup
cp -r ./squads/my-squad/.backup/pre-migration-*/. ./squads/my-squad/

1. Local     → ./squads/{name}/
2. npm       → node_modules/@aios-squads/{name}/
3. Workspace → ../{name}/ (monorepo)
4. Registry  → api.synkra.dev/squads/{name}

const { SquadLoader } = require('./.aios-core/development/scripts/squad');
 
const loader = new SquadLoader({
  squadsPath: './squads',
  verbose: false,
});
 
// Resolver caminho do squad
const { path, manifestPath } = await loader.resolve('my-squad');
 
// Carregar manifesto
const manifest = await loader.loadManifest('./squads/my-squad');
 
// Listar todos os squads locais
const squads = await loader.listLocal();
// [{ name: 'my-squad', path: './squads/my-squad', manifestPath: '...' }]

const { SquadLoader, SquadLoaderError } = require('./.aios-core/development/scripts/squad');
 
try {
  await loader.resolve('non-existent');
} catch (error) {
  if (error instanceof SquadLoaderError) {
    console.error(`[${error.code}] ${error.message}`);
    console.log(`Sugestão: ${error.suggestion}`);
  }
}

# Verifique se o diretório squads existe
ls ./squads/
 
# Verificar manifesto
cat ./squads/my-squad/squad.yaml
 
# Verificar resolução
@squad-creator
*list-squads

# Obter erros detalhados
*validate-squad my-squad --verbose
 
# Correções comuns:
# - name: deve ser kebab-case
# - version: deve ser semver (x.y.z)
# - aios.type: deve ser "squad"
# - aios.minVersion: deve ser semver válido

# Validar sintaxe YAML online ou com:
npx js-yaml ./squads/my-squad/squad.yaml

# Verificar se backup existe
ls ./squads/my-squad/.backup/
 
# Restaurar e tentar novamente
cp -r ./squads/my-squad/.backup/pre-migration-*/. ./squads/my-squad/
*migrate-squad ./squads/my-squad --verbose

# Verificar autenticação GitHub
gh auth status
 
# Verificar validação do squad
*validate-squad my-squad --strict
 
# Verificar conflitos de nome
*download-squad --list | grep my-squad

dependencies:
  squads:
    - etl-squad@^2.0.0

aios:
  minVersion: '2.1.0'

# 1. Validar estrutura
*validate-squad my-squad --strict
 
# 2. Testar localmente
@my-agent  # Ativar agent do squad
*my-task   # Executar task do squad
 
# 3. Executar testes do squad (se definidos)
npm test -- tests/squads/my-squad/