Guia de Validação

Garanta que seu squad atenda aos padrões de qualidade antes de publicar no marketplace.

Por que validar?

Squads executam código no ambiente do usuário. A validação garante qualidade, segurança e integridade estrutural antes que seu squad chegue a outros desenvolvedores.

O que é verificado

O validador analisa seu squad em 6 categorias ponderadas:

Categoria	Peso	O que valida
Manifesto (squad.yaml)	25%	name, version, description, aiox.minVersion, components
Estrutura	15%	Diretórios, arquivos esperados, extensões
Agentes	20%	Campos obrigatórios, archetype, persona_profile, whenToUse
Tarefas	15%	Contratos Entrada/Saída, responsavel, atomic_layer
Workflows	10%	agent_sequence, transitions, success_indicators
Referências Cruzadas	15%	Agentes referenciados existem, sem dependências circulares

Sistema de Pontuação

Cada squad recebe uma pontuação de 0 a 100 baseada nas categorias ponderadas acima.

SAFEPontuação >= 80, sem erros — pronto para publicar

WARNINGPossui alertas mas sem erros bloqueantes

CRITICALPossui erros ou pontuação abaixo do limite — corrija antes de publicar

Como Validar

a) CLI (recomendado)

A forma mais rápida de validar seu squad localmente antes de publicar:

squads validate ./my-squad           # Validação completa

squads validate ./my-squad --json    # Saída JSON

squads publish ./my-squad --dry-run  # Simular publicação

validationDocs.aiosMethodTitle

validationDocs.aiosMethodDescription

/SQUADS:nsc:squad-validator

*validate-squad my-squad

*extend-squad my-squad --add task --name missing-task

c) Claude Code (sem Squad)

Instrua o Claude Code a validar seu squad usando o CLI:

npx squads validate ./squads/my-squad

d) Web (página de submit)

A página de submit executa a validação automaticamente ao colar a URL do GitHub. Corrija os problemas antes de submeter.

Erros Comuns e Correções

Erro	Causa	Correção
description interpretado como objeto	YAML multi-line (\| ou >)	Usar string inline entre aspas
Agente sem campos obrigatórios	Falta whenToUse, archetype, etc.	Adicionar campos no frontmatter
Task responsavel não encontrado	Nome do agente não corresponde	Usar exatamente o valor de agent.name
Agente do workflow ausente na sequência	ID inválido em agent_sequence	Usar agent.id (kebab-case)
Incompatibilidade de componentes	Arquivos listados no squad.yaml não existem	Sincronizar components com arquivos reais

Checklist de Pré-Publicação

squad.yaml válido com name, version, description

Sem arquivos .env ou credenciais hardcoded

Sem diretórios node_modules/ ou .git/

README.md existe com seção de instalação

Todos os agentes têm campos obrigatórios (archetype, whenToUse, persona_profile)

Todas as tasks têm contratos Entrada/Saída

Referências cruzadas válidas (agentes existem, sem deps circulares)

Quality Gates Squad

Para usuários do Squad Core, o framework fornece quality gates integrados durante a geração de squads:

▸Fase 6: Quality Gate de Geração — 22 verificações bloqueantes em estrutura, campos e referências cruzadas.
▸Fase 9: Checklist de Pré-Publicação — 16 verificações bloqueantes de prontidão para o marketplace.

Use os comandos *validate-squad e *extend-squad para validação e correção iterativa:

*validate-squad my-squad
*extend-squad my-squad --add agent --name new-agent

Para mais detalhes, veja a Referência CLI