You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Versão: 1.0.0
Criado: 2026-02-04
Owner: @squad-creator (Craft)
Status: Documentação Oficial
Visão Geral
O Squad Creator (Craft) e o agente especializado do AIOX para criação, validação, publicacao e gerenciamento de squads. Squads sao pacotes modulares de agentes, tasks, workflows e recursos que podem ser reutilizados entre projetos.
Este sistema implementa a arquitetura task-first do AIOX, onde tasks sao o ponto de entrada principal para execucao, e agentes orquestram essas tasks.
Propósitos do Sistema
Criar squads seguindo padroes e estrutura do AIOX
Validar squads contra JSON Schema e especificacoes de task
Listar squads locais do projeto
Distribuir squads em 3 niveis (Local, aiox-squads, Synkra API)
Migrar squads para formato v2 com orquestracao e skills
Analisar e estender squads existentes
Principios Fundamentais
Task-First Architecture: Tasks sao o ponto de entrada, agentes orquestram
Validacao Obrigatoria: Sempre validar antes de distribuir
JSON Schema: Manifests validados contra schema
3 Niveis de Distribuicao: Local, Publico (aiox-squads), Marketplace (Synkra API)
Integracao com aiox-core: Squads trabalham em sinergia com o framework
short-title: string # max 100 charsdescription: string # max 500 charsauthor: stringlicense: MIT | Apache-2.0 | ISC | GPL-3.0 | UNLICENSEDslashPrefix: string # prefixo para comandostags: string[] # keywords para descobertaaiox:
minVersion: string # versao minima do AIOXtype: squadcomponents:
tasks: string[] # arquivos de tasksagents: string[] # arquivos de agentsworkflows: string[]checklists: string[]templates: string[]tools: string[]scripts: string[]config:
extends: extend | override | nonecoding-standards: stringtech-stack: stringsource-tree: stringdependencies:
node: string[]python: string[]squads: string[]
Codigos de Erro de Validacao
Codigo
Severidade
Descrição
MANIFEST_NOT_FOUND
Error
squad.yaml ou config.yaml não encontrado
YAML_PARSE_ERROR
Error
Sintaxe YAML invalida
SCHEMA_ERROR
Error
Manifest não corresponde ao JSON Schema
FILE_NOT_FOUND
Error
Arquivo referenciado não existe
DEPRECATED_MANIFEST
Warning
Usando config.yaml ao inves de squad.yaml
MISSING_DIRECTORY
Warning
Diretorio esperado não encontrado
NO_TASKS
Warning
Nenhum arquivo de task em tasks/
TASK_MISSING_FIELD
Warning
Task sem campo recomendado
AGENT_INVALID_FORMAT
Warning
Arquivo de agente pode não seguir formato
INVALID_NAMING
Warning
Nome do arquivo não e kebab-case
Niveis de Distribuicao
flowchart LR
subgraph LOCAL["📂 Nivel 1: Local"]
L_PATH["./squads/"]
L_DESC["Privado, projeto-especifico"]
L_CMD["*create-squad"]
end
subgraph PUBLIC["🌐 Nivel 2: Publico"]
P_REPO["github.com/SynkraAI/aiox-squads"]
P_DESC["Squads da comunidade (gratuitos)"]
P_CMD["*publish-squad"]
end
subgraph MARKET["💰 Nivel 3: Marketplace"]
M_API["api.synkra.dev/squads"]
M_DESC["Squads premium via Synkra API"]
M_CMD["*sync-squad-synkra"]
end
LOCAL --> PUBLIC
PUBLIC --> MARKET
style LOCAL fill:#e8f5e9
style PUBLIC fill:#e3f2fd
style MARKET fill:#fff3e0
Loading
Best Practices
Criacao de Squads
Sempre comece com design - Use *design-squad para projetos complexos
Siga task-first - Tasks sao o ponto de entrada principal
Use v2 por padrao - Suporte a orquestracao e skills
Valide antes de distribuir - *validate-squad obrigatorio
Documente bem - README.md e comentarios em YAML
Organizacao de Componentes
Naming: Sempre use kebab-case
Tasks: Inclua todos campos obrigatorios do TASK-FORMAT-V1
Agents: Use YAML frontmatter com agent: block
Config: Especifique modo de heranca (extend/override/none)
Validacao
Pre-commit: Execute *validate-squad antes de commits
CI/CD: Integre validação no pipeline
Strict mode: Use --strict para tratar warnings como erros
Correcao: Enderece warnings para melhor qualidade
Distribuicao
Teste localmente - Valide e use antes de publicar
Documentação - README completo e descricao clara
Versionamento - Use semver corretamente
Licenca - Especifique licenca apropriada
Troubleshooting
Squad não aparece em *list-squads
Verificar se diretorio existe em ./squads/
Checar se squad.yaml ou config.yaml existe
Validar YAML syntax do manifest
Validacao falha com SCHEMA_ERROR
Checar campo name (deve ser kebab-case)
Checar campo version (deve ser semver: 1.0.0)
Usar YAML linter para verificar sintaxe
Validacao falha com FILE_NOT_FOUND
Verificar arquivos listados em components
Checar paths relativos (relativo ao diretorio do squad)
Criar arquivos faltantes ou remover da lista
Task reporta TASK_MISSING_FIELD
Adicionar campos obrigatorios:
task:, responsavel:, responsavel_type:
atomic_layer:, Entrada:, Saida:, Checklist:
Seguir formato TASK-FORMAT-SPECIFICATION-V1
Blueprint falha em gerar
Fornecer documentacao mais detalhada
Usar --verbose para ver analise
Usar --domain para dar contexto
*create-squad --from-design falha
Verificar se blueprint existe no path especificado