Guia de Desenvolvimento de Squads

🌐 EN | PT | ES

Guia completo para criar, validar, publicar e gerenciar Squads no AIOX.

AIOX Squads: Equipes de AI agents trabalhando com você

Índice

O que é um Squad?
Início Rápido
Arquitetura de Squad
Criando Squads
Squad Designer
Analisando e Estendendo Squads (NOVO)
Validando Squads
Publicação e Distribuição
Migração do Formato Legado
Squad Loader e Resolução
Solução de Problemas
FAQ

O que é um Squad?

Squads são equipes modulares de agentes de IA que estendem a funcionalidade do AIOX. Cada squad é um pacote autocontido contendo:

Componente	Propósito
Agents	Personas de IA específicas do domínio
Tasks	Fluxos de trabalho executáveis (TASK-FORMAT-SPEC-V1)
Workflows	Orquestrações de múltiplas etapas
Config	Padrões de código, stack tecnológico, árvore de código
Templates	Templates de geração de documentos
Tools	Integrações de ferramentas personalizadas

Níveis de Distribuição

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

Squads Oficiais

Squad	Versão	Descrição
etl-squad	2.0.0	Coleta e transformação de dados
creator-squad	1.0.0	Utilitários de geração de conteúdo

Início Rápido

Pré-requisitos

Node.js 18+
Projeto AIOX inicializado (.aiox-core/ existe)
Git para controle de versão

Opção 1: Design Guiado (Recomendado)

# 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

Opção 2: Criação Direta

@squad-creator

# Criar com prompts interativos
*create-squad my-domain-squad

# Ou especificar template
*create-squad my-squad --template etl

Arquitetura de Squad

Estrutura de Diretórios

./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

Manifesto do Squad (squad.yaml)

# 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 AIOX
aiox:
  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

Arquitetura Task-First

Squads seguem arquitetura task-first onde tarefas são o ponto de entrada principal:

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

Tasks devem seguir TASK-FORMAT-SPECIFICATION-V1.

Criando Squads

Usando o Agente @squad-creator

# Ativar o agente
@squad-creator

# Ver todos os comandos
*help

Comandos Disponíveis

Comando	Descrição
`*create-squad {name}`	Criar novo squad com prompts
`*create-squad {name} --template {type}`	Criar a partir de template (basic, etl, agent-only)
`*create-squad {name} --from-design`	Criar a partir de blueprint de design
`*validate-squad {name}`	Validar estrutura do squad
`*list-squads`	Listar todos os squads locais
`*design-squad`	Projetar squad a partir de documentação

Templates

Template	Caso de Uso
`basic`	Squad simples com um agent e task
`etl`	Extração, transformação, carregamento de dados
`agent-only`	Squad com agents, sem tasks

Modos de Herança de Configuração

Modo	Comportamento
`extend`	Adiciona regras do squad às regras core do AIOX
`override`	Substitui regras core pelas regras do squad
`none`	Configuração standalone

Squad Designer

O Squad Designer analisa sua documentação e recomenda agents e tasks.

Uso

@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/

Fluxo de Trabalho

Coletar Documentação - Fornecer PRDs, specs, requisitos
Análise de Domínio - Sistema extrai conceitos, workflows, papéis
Recomendações de Agent - Revisar agents sugeridos
Recomendações de Task - Revisar tasks sugeridas
Gerar Blueprint - Salvar em .squad-design.yaml
Criar a partir do Blueprint - *create-squad my-squad --from-design

Formato do Blueprint

# .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

Analisando & Estendendo Squads

Após criar um squad, você pode analisar sua estrutura e estendê-lo com novos componentes usando os comandos *analyze-squad e *extend-squad.

Analisando Squads

@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

Saída da Análise

=== 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

Estendendo Squads

Adicione novos componentes a squads existentes com atualizações automáticas do manifesto:

@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

Fluxo Interativo de Extensão

@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

Tipos de Componente

Tipo	Diretório	Extensão	Descrição
agent	agents/	.md	Definição de persona de agent
task	tasks/	.md	Fluxo de trabalho executável
workflow	workflows/	.yaml	Orquestração de múltiplas etapas
checklist	checklists/	.md	Checklist de validação
template	templates/	.md	Template de geração de documento
tool	tools/	.js	Integração de ferramenta personalizada
script	scripts/	.js	Script de automação utilitário
data	data/	.yaml	Configuração de dados estáticos

Fluxo de Trabalho de Melhoria Contínua

# 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

Uso Programático

const { SquadAnalyzer } = require('./.aiox-core/development/scripts/squad/squad-analyzer');
const { SquadExtender } = require('./.aiox-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);

Validando Squads

Validação Básica

@squad-creator
*validate-squad my-squad

Modo Strict (para CI/CD)

*validate-squad my-squad --strict

Trata avisos como erros.

Verificações de Validação

Verificação	Descrição
Manifest Schema	squad.yaml contra JSON Schema
Estrutura de Diretório	Pastas obrigatórias existem
Formato de Task	Tasks seguem TASK-FORMAT-SPEC-V1
Definições de Agent	Agents têm campos obrigatórios
Dependências	Arquivos referenciados existem

Saída da Validação

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)

Validação Programática

const { SquadValidator } = require('./.aiox-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: [...] }

Publicação & Distribuição

Nível 1: Local (Privado)

Squads em ./squads/ estão automaticamente disponíveis para seu projeto.

# Listar squads locais
*list-squads

Nível 2: Repositório aiox-squads (Público)

@squad-creator

# Validar primeiro
*validate-squad my-squad --strict

# Publicar no GitHub
*publish-squad ./squads/my-squad

Isso cria um PR para SynkraAI/aiox-squads.

Nível 3: Synkra Marketplace

# Configurar autenticação
export SYNKRA_API_TOKEN="your-token"

# Sincronizar com marketplace
*sync-squad-synkra ./squads/my-squad --public

Baixando Squads

@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

Migração do Formato Legado

Detectando Squads Legados

Squads legados usam config.yaml em vez de squad.yaml e podem estar faltando:

Campo aiox.type
Campo aiox.minVersion
Estrutura task-first

Comando de Migração

@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

Etapas da Migração

Backup - Cria .backup/pre-migration-{timestamp}/
Renomear - config.yaml → squad.yaml
Adicionar Campos - aiox.type, aiox.minVersion
Reestruturar - Organizar em layout task-first
Validar - Executar validação no squad migrado

Rollback

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

Veja o Guia de Migração de Squad para cenários detalhados.

Squad Loader & Resolução

Cadeia de Resolução

O Squad Loader resolve squads nesta ordem:

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

Uso Programático

const { SquadLoader } = require('./.aiox-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: '...' }]

Tratamento de Erros

const { SquadLoader, SquadLoaderError } = require('./.aiox-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}`);
  }
}

Códigos de Erro

Código	Descrição	Solução
`SQUAD_NOT_FOUND`	Diretório do squad não encontrado	Criar com `*create-squad`
`MANIFEST_NOT_FOUND`	Nenhum arquivo de manifesto	Criar `squad.yaml`
`YAML_PARSE_ERROR`	Sintaxe YAML inválida	Use um linter YAML
`PERMISSION_DENIED`	Erro de permissão de arquivo	Verifique `chmod 644`

Solução de Problemas

"Squad não encontrado"

# Verifique se o diretório squads existe
ls ./squads/

# Verificar manifesto
cat ./squads/my-squad/squad.yaml

# Verificar resolução
@squad-creator
*list-squads

Erros de Validação

# Obter erros detalhados
*validate-squad my-squad --verbose

# Correções comuns:
# - name: deve ser kebab-case
# - version: deve ser semver (x.y.z)
# - aiox.type: deve ser "squad"
# - aiox.minVersion: deve ser semver válido

Erros de Parse YAML

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

Problemas comuns:

Indentação incorreta (use 2 espaços)
Aspas faltando ao redor de caracteres especiais
Tabs em vez de espaços

Falhas de Migração

# 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

Erros de Publicação

# 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

FAQ

Qual a diferença entre um Squad e formatos legados de squad no AIOX?

Squads são o padrão no AIOX 2.1+ com:

Arquitetura task-first
Validação JSON Schema
Distribuição em três níveis
Melhor ferramental (@squad-creator)

Posso usar Squads de diferentes fontes juntos?

Sim. O Squad Loader resolve de múltiplas fontes. Squads locais têm precedência.

Como atualizo um Squad publicado?

Atualizar versão no squad.yaml (semver)
Executar *validate-squad --strict
Re-publicar: *publish-squad ou *sync-squad-synkra

Squads podem depender de outros Squads?

Sim, declare em dependencies.squads:

dependencies:
  squads:
    - etl-squad@^2.0.0

Como torno um Squad privado?

Nível 1: Mantenha em ./squads/ (não comitado) - adicione ao .gitignore
Nível 3: Sincronize com flag --private: *sync-squad-synkra my-squad --private

Qual a versão mínima do AIOX para Squads?

Squads requerem AIOX 2.1.0+. Defina no manifesto:

aiox:
  minVersion: '2.1.0'

Como testo meu Squad antes de publicar?

# 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/

Recursos Relacionados

Obtendo Ajuda

AIOX Squads: Equipes de AI agents trabalhando com você

Versão: 2.1.0 | Atualizado: 2025-12-26 | Stories: SQS-8, SQS-11

FilesExpand file tree

squads-guide.md

Latest commit

History

squads-guide.md

File metadata and controls

Guia de Desenvolvimento de Squads

Índice

O que é um Squad?

Níveis de Distribuição

Squads Oficiais

Início Rápido

Pré-requisitos

Opção 1: Design Guiado (Recomendado)

Opção 2: Criação Direta

Arquitetura de Squad

Estrutura de Diretórios

Manifesto do Squad (squad.yaml)

Arquitetura Task-First

Criando Squads

Usando o Agente @squad-creator

Comandos Disponíveis

Templates

Modos de Herança de Configuração

Squad Designer

Uso

Fluxo de Trabalho

Formato do Blueprint

Analisando & Estendendo Squads

Analisando Squads

Saída da Análise

Estendendo Squads

Fluxo Interativo de Extensão

Tipos de Componente

Fluxo de Trabalho de Melhoria Contínua

Uso Programático

Validando Squads

Validação Básica

Modo Strict (para CI/CD)

Verificações de Validação

Saída da Validação

Validação Programática

Publicação & Distribuição

Nível 1: Local (Privado)

Nível 2: Repositório aiox-squads (Público)

Nível 3: Synkra Marketplace

Baixando Squads

Migração do Formato Legado

Detectando Squads Legados

Comando de Migração

Etapas da Migração

Rollback

Squad Loader & Resolução

Cadeia de Resolução

Uso Programático

Tratamento de Erros

Códigos de Erro

Solução de Problemas

"Squad não encontrado"

Erros de Validação

Erros de Parse YAML

Falhas de Migração

Erros de Publicação

FAQ

Qual a diferença entre um Squad e formatos legados de squad no AIOX?

Posso usar Squads de diferentes fontes juntos?

Como atualizo um Squad publicado?

Squads podem depender de outros Squads?

Como torno um Squad privado?

Qual a versão mínima do AIOX para Squads?

Como testo meu Squad antes de publicar?

Recursos Relacionados

Obtendo Ajuda