Skip to content

contributing-squads.md

Latest commit

 

History

History
256 lines (173 loc) · 5.43 KB

contributing-squads.md

File metadata and controls

256 lines (173 loc) · 5.43 KB
Raw

Guia de Contribuição de Squads

🌐 EN | PT | ES

Como contribuir squads para o ecossistema AIOX.

Visão Geral

Existem duas formas de compartilhar seu squad com a comunidade:

  1. Repositório aiox-squads - Squads gratuitos e open-source no GitHub
  2. Synkra Marketplace - Squads premium via API Synkra

Padrões de Qualidade

Todos os squads contribuídos devem atender a estes padrões:

Obrigatório

Requisito Descrição
Manifesto válido squad.yaml passa validação JSON Schema
Documentação README.md com instruções de uso
Licença Licença open source (MIT, Apache 2.0, etc.)
Compatibilidade AIOX aiox.minVersion: "2.1.0" ou superior
Arquitetura task-first Tasks como pontos de entrada principais

Recomendado

Recomendação Descrição
Exemplos Exemplos de uso no README
Testes Testes unitários para funcionalidade crítica
Changelog Documentação de histórico de versão
Solução de problemas Problemas comuns e soluções

Convenções de Nomenclatura

Nomes de Squad

  • Use kebab-case: my-awesome-squad
  • Seja descritivo: etl-data-pipeline não data1
  • Evite nomes genéricos: helper-squad é muito vago
  • Sem números de versão no nome: my-squad não my-squad-v2

Prefixo (slashPrefix)

O slashPrefix no squad.yaml determina prefixos de comando:

slashPrefix: etl  # Comandos tornam-se *etl-extract, *etl-transform

Escolha um prefixo único e curto (2-5 caracteres).

Requisitos do Manifesto

Campos Obrigatórios

# Estes campos são OBRIGATÓRIOS
name: my-squad
version: 1.0.0              # Versionamento semântico
description: Descrição clara do que este squad faz

aiox:
  minVersion: "2.1.0"
  type: squad

components:
  agents: []                # Pelo menos um agent OU task
  tasks: []

Campos Recomendados

# Estes campos são RECOMENDADOS
author: Seu Nome <email@example.com>
license: MIT
slashPrefix: my

tags:
  - relevant
  - keywords

dependencies:
  node: []
  python: []
  squads: []

Requisitos de Documentação

Estrutura do README.md

# Nome do Squad

Breve descrição (1-2 frases).

## Instalação

Como instalar/adicionar este squad.

## Uso

Exemplos básicos de uso.

## Comandos

| Comando | Descrição |
|---------|-----------|
| *cmd1 | O que faz |
| *cmd2 | O que faz |

## Configuração

Quaisquer opções de configuração.

## Exemplos

Exemplos detalhados de uso.

## Solução de Problemas

Problemas comuns e soluções.

## Licença

Informações da licença.

Publicando no aiox-squads

Pré-requisitos

  1. Conta GitHub
  2. Squad validado: *validate-squad --strict
  3. Nome de squad único (verifique squads existentes)

Passos

# 1. Validar seu squad
@squad-creator
*validate-squad my-squad --strict

# 2. Publicar (cria PR)
*publish-squad ./squads/my-squad

Isso irá:

  1. Fazer fork de SynkraAI/aiox-squads (se necessário)
  2. Criar branch com seu squad
  3. Abrir PR para revisão

Processo de Revisão

  1. Verificações automatizadas - Validação de schema, verificação de estrutura
  2. Revisão do mantenedor - Revisão de código, verificação de qualidade
  3. Merge - Squad adicionado ao registro

Prazo: Geralmente 2-5 dias úteis.

Publicando no Synkra Marketplace

Pré-requisitos

  1. Conta Synkra
  2. Token API configurado
  3. Squad validado

Passos

# 1. Configurar token
export SYNKRA_API_TOKEN="your-token"

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

Opções de Visibilidade

Flag Efeito
--private Visível apenas para seu workspace
--public Visível para todos

Atualizando Squads Publicados

Incremento de Versão

Siga versionamento semântico:

  • MAJOR (1.0.0 → 2.0.0): Mudanças que quebram compatibilidade
  • MINOR (1.0.0 → 1.1.0): Novos recursos, compatível com versões anteriores
  • PATCH (1.0.0 → 1.0.1): Correções de bugs

Processo de Atualização

# 1. Atualizar versão no squad.yaml
# 2. Atualizar CHANGELOG.md
# 3. Validar
*validate-squad my-squad --strict

# 4. Re-publicar
*publish-squad ./squads/my-squad
# ou
*sync-squad-synkra ./squads/my-squad

Código de Conduta

Faça

  • Forneça documentação clara e precisa
  • Teste seu squad antes de publicar
  • Responda a issues e feedback
  • Mantenha dependências mínimas
  • Siga convenções do AIOX

Não Faça

  • Incluir código malicioso
  • Armazenar credenciais no código
  • Copiar trabalho de outros sem atribuição
  • Usar nomes ou conteúdo ofensivo
  • Fazer spam no registro com squads de teste

Obtendo Ajuda

Recursos Relacionados

Versão: 1.0.0 | Atualizado: 2025-12-26 | Story: SQS-8