Trilha Squad Creator

Construa squads de agentes do zero

6 min de leitura
trilhasquads

Trilha @squad-creator: Do Problema ao Output Validado

Story: AIOX-DIFF-4.3.1 Agente: @squad-creator (Craft) Tempo estimado: 30-45 minutos

Mapa da Trilha

PROBLEMA: "Preciso criar um squad para automação de marketing"
    ↓
WORKFLOW: Design → Create → Validate → Use
    ↓
TASKS: *design-squad → *create-squad → *validate-squad → *list-squads
    ↓
OUTPUT: Squad criado + Validação verde + Pronto para uso

Exemplo Reproduzível Passo a Passo

Cenário

Você precisa criar um squad para automação de marketing com:

  1. Agente de criação de conteúdo
  2. Agente de análise de métricas
  3. Tasks para geração de posts e relatórios
  4. Workflow de orquestração

Pré-requisitos

# Projeto AIOX inicializado
npx aiox-core doctor  # deve retornar healthy

# Diretório squads existe
ls squads/  # ou será criado automaticamente

Passo 1: Ativar @squad-creator

@squad-creator

Output esperado:

-- Craft aqui! Squad Creation & Management Specialist.
Pronto para criar, validar e gerenciar squads.

Quick commands:
  *design-squad      - Analisar docs e gerar blueprint
  *create-squad      - Criar novo squad
  *validate-squad    - Validar squad contra schema
  *list-squads       - Listar squads locais

Passo 2: Design do Squad

*design-squad

Interação:

Craft: Qual domínio do squad?
Você: Marketing automation

Craft: Descreva o propósito principal:
Você: Automação de criação de conteúdo para redes sociais e análise de performance

Craft: Quais processos precisa automatizar?
Você:
1. Gerar posts para diferentes plataformas
2. Analisar métricas de engajamento
3. Sugerir melhorias baseadas em dados
4. Criar calendário editorial

Craft: Integrações externas?
Você: APIs de redes sociais (Twitter, LinkedIn, Instagram)

Output esperado:

📐 Generating Blueprint...

🔍 Domain Analysis:
  - Primary domain: Marketing Automation
  - Sub-domains: Content Creation, Analytics, Scheduling
  - Detected entities: Posts, Metrics, Campaigns, Platforms

💡 Recommended Agents:
  1. content-creator (confidence: 0.92)
     - Role: Generate social media content
     - Commands: *generate-post, *adapt-content, *suggest-hashtags

  2. analytics-analyst (confidence: 0.88)
     - Role: Analyze engagement metrics
     - Commands: *analyze-metrics, *generate-report, *compare-campaigns

💡 Recommended Tasks:
  1. generate-social-post.md
  2. analyze-engagement.md
  3. create-content-calendar.md
  4. platform-adaptation.md

💡 Recommended Workflow:
  - content-workflow.yaml (3 phases)

📋 Blueprint saved: squads/.designs/marketing-automation-design.yaml

Ready to create? Run:
  *create-squad marketing-automation --from-design

Passo 3: Criar Squad a partir do Blueprint

*create-squad marketing-automation --from-design

Output esperado:

🏗️ Creating Squad: marketing-automation

📁 Structure:
  squads/marketing-automation/
  ├── squad.yaml                    ✅
  ├── README.md                     ✅
  ├── config/
  │   ├── coding-standards.md       ✅
  │   ├── tech-stack.md             ✅
  │   └── source-tree.md            ✅
  ├── agents/
  │   ├── content-creator.md        ✅
  │   └── analytics-analyst.md      ✅
  ├── tasks/
  │   ├── generate-social-post.md   ✅
  │   ├── analyze-engagement.md     ✅
  │   ├── create-content-calendar.md✅
  │   └── platform-adaptation.md    ✅
  ├── workflows/
  │   └── content-workflow.yaml     ✅
  ├── checklists/                   ✅
  ├── templates/                    ✅
  ├── tools/                        ✅
  ├── scripts/                      ✅
  └── data/                         ✅

✅ Squad created successfully!

📋 Next step: Validate
  *validate-squad marketing-automation

Passo 4: Validar Squad

*validate-squad marketing-automation

Output esperado:

✅ Validating Squad: marketing-automation

📜 MANIFEST VALIDATION
  ✅ squad.yaml found
  ✅ YAML syntax valid
  ✅ Schema validation passed
    - name: marketing-automation ✓
    - version: 1.0.0 ✓
    - components listed ✓

📁 STRUCTURE VALIDATION
  ✅ tasks/ directory exists
  ✅ agents/ directory exists
  ✅ workflows/ directory exists
  ✅ All referenced files exist

📋 TASK FORMAT VALIDATION
  ✅ generate-social-post.md
    - task: ✓
    - responsavel: ✓
    - responsavel_type: ✓
    - atomic_layer: ✓
    - Entrada: ✓
    - Saida: ✓
    - Checklist: ✓

  ✅ analyze-engagement.md (all fields present)
  ✅ create-content-calendar.md (all fields present)
  ✅ platform-adaptation.md (all fields present)

🤖 AGENT FORMAT VALIDATION
  ✅ content-creator.md (valid YAML frontmatter)
  ✅ analytics-analyst.md (valid YAML frontmatter)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 VALIDATION SUMMARY
  Errors: 0
  Warnings: 0
  Status: ✅ VALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Passo 5: Listar Squads

*list-squads

Output esperado:

📦 Local Squads (./squads/)

┌─────────────────────────┬─────────┬───────────────────────────┐
│ Squad                   │ Version │ Status                    │
├─────────────────────────┼─────────┼───────────────────────────┤
│ marketing-automation    │ 1.0.0   │ ✅ Valid                  │
│ (outros squads...)      │ ...     │ ...                       │
└─────────────────────────┴─────────┴───────────────────────────┘

Total: 1 squad(s)

Passo 6: Usar o Squad

Agora você pode ativar os agentes do squad:

# Em Claude Code
/marketing-automation:content-creator

# Ou via comando AIOX
@marketing-automation/content-creator
*generate-post "Lançamento do produto X"

Checklist de Validação

| Step | Comando | Output Esperado | ✓ | |------|---------|-----------------|---| | 1 | @squad-creator | Greeting de Craft | [ ] | | 2 | *design-squad | Blueprint criado | [ ] | | 3 | *create-squad --from-design | "Squad created" | [ ] | | 4 | *validate-squad | "VALID" | [ ] | | 5 | *list-squads | Squad listado | [ ] | | 6 | Ativar agente | Agente responde | [ ] |

Arquivos Gerados

squad.yaml (manifest)

name: marketing-automation
version: 1.0.0
short-title: Marketing Automation Squad
description: Automação de criação de conteúdo e análise de métricas

aiox:
  minVersion: "4.0.0"
  type: squad

components:
  tasks:
    - tasks/generate-social-post.md
    - tasks/analyze-engagement.md
    - tasks/create-content-calendar.md
    - tasks/platform-adaptation.md
  agents:
    - agents/content-creator.md
    - agents/analytics-analyst.md
  workflows:
    - workflows/content-workflow.yaml

config:
  extends: extend

agents/content-creator.md

---
agent:
  name: content-creator
  role: Content Generation Specialist
  persona: Creative
  commands:
    - name: generate-post
      task: generate-social-post.md
    - name: adapt-content
      task: platform-adaptation.md
---

# Content Creator

Especialista em criação de conteúdo para redes sociais...

tasks/generate-social-post.md

---
task: generate-social-post
responsavel: content-creator
responsavel_type: agent
atomic_layer: execution
---

# Generate Social Post

## Entrada
- Tema/tópico do post
- Plataforma alvo (Twitter, LinkedIn, Instagram)
- Tom desejado (formal, casual, técnico)

## Saida
- Post formatado para a plataforma
- Sugestões de hashtags
- Horário sugerido de publicação

## Checklist
- [ ] Post dentro do limite de caracteres
- [ ] Hashtags relevantes incluídas
- [ ] CTA claro
- [ ] Tom consistente com a marca

Variações da Trilha

Variação A: Criar sem Design

*create-squad my-squad --template basic
# Cria estrutura mínima para customizar manualmente

Variação B: ETL Squad

*create-squad data-pipeline --template etl
# Cria squad com extractor, transformer, loader

Variação C: Migrar Squad v1 para v2

*migrate-to-v2 old-squad
# Adiciona orquestração e skills

Variação D: Gerar Skills de Conhecimento

*generate-skills marketing-automation
# Extrai skills de conhecimento do squad

Comandos Relacionados

| Comando | Uso | |---------|-----| | *design-squad | Analisar docs e gerar blueprint | | *create-squad | Criar novo squad | | *validate-squad | Validar contra schema | | *list-squads | Listar squads locais | | *analyze-squad | Sugerir melhorias | | *extend-squad | Adicionar componentes | | *migrate-to-v2 | Migrar para formato v2 | | *generate-skills | Gerar skills de conhecimento | | *generate-workflow | Gerar workflow de orquestração |

Troubleshooting

Validação falha com SCHEMA_ERROR

# Verificar squad.yaml
cat squads/my-squad/squad.yaml
# name deve ser kebab-case
# version deve ser semver (1.0.0)

Task falha validação

# Verificar campos obrigatórios
# task, responsavel, responsavel_type, atomic_layer, Entrada, Saida, Checklist

Blueprint não gerou agentes

# Fornecer descrição mais detalhada
*design-squad --domain marketing --verbose

Trilha criada para Story AIOX-DIFF-4.3.1 -- Craft, sempre estruturando

Falar com o Time