---
name: orquestrar-agentes
description: >
  Protocolo de colaboração e handoff entre agentes especializados do ecossistema Azteca.
  Define como agentes passam contexto, comunicam resultados e resolvem dependências.
scope: global
---

# Skill: Orquestrar Agentes

Use esta skill sempre que uma tarefa exigir a colaboração de dois ou mais agentes especializados, ou quando precisar entender quem deve fazer o quê em uma implementação complexa.

---

## PASSO 1 — Identificar os agentes envolvidos

Antes de qualquer implementação, mapear quais agentes são necessários:

| Tarefa | Agente responsável |
|--------|-------------------|
| Definir arquitetura, contratos de API, schemas | `@arquiteto` |
| Implementar backend (rotas, serviços, banco) | `@back` |
| Implementar frontend (telas, componentes, fluxos) | `@front` |
| Garantir qualidade e criar testes | `@testes` |
| Configurar infraestrutura e deploy | `@deploy` |
| Criar/atualizar documentação | `@documentacao` |
| Revisar e melhorar UX | `@ux` |
| Criar materiais de venda e marketing | `@comercial` |

---

## PASSO 2 — Definir a sequência de handoff

Toda tarefa complexa segue uma ordem de precedência:

```
1. @arquiteto   → define e especifica
2. @back        → implementa backend + schemas *-comuns
3. @front       → implementa frontend (consome *-comuns)
4. @ux          → revisa experiência (paralelo com front)
5. @testes      → valida qualidade
6. @deploy      → empacota e publica
7. @documentacao → documenta (pode ser paralelo)
8. @comercial   → cria materiais (após documentação)
```

Agentes podem trabalhar em paralelo quando não há dependência direta:
- `@ux` e `@front` podem colaborar em paralelo
- `@documentacao` pode trabalhar em paralelo com `@testes`
- `@comercial` é sempre o último da cadeia

---

## PASSO 3 — Formato de mensagem entre agentes

Quando um agente precisa comunicar resultado ou delegar tarefa para outro, usar o formato:

```markdown
**De:** @arquiteto
**Para:** @back
**Tipo:** especificação | resultado | bloqueio | revisão

## Contexto
[O que foi decidido/implementado/identificado]

## Entrega
[O que o agente destinatário precisa fazer ou receber]

## Dependências
[Arquivos, schemas, endpoints ou decisões que o destinatário precisa conhecer]

## Critérios de aceite
[Como saber que a tarefa do destinatário está completa]
```

---

## PASSO 4 — Regras de escopo entre agentes

### Permitido ✅

```
@arquiteto → pode delegar para qualquer agente
@back      → pode enviar schemas e endpoints para @front (via *-comuns)
@front     → pode solicitar revisão de @ux
@ux        → pode propor melhorias para @front
@testes    → pode reportar bugs para @back e @front
@documentacao → pode documentar artefatos de qualquer agente
@deploy    → recebe builds de @back e @front
```

### Proibido ❌

```
@front     ✗ não importa código de @back diretamente
@back      ✗ não cria componentes Vue ou lógica de interface
@comercial ✗ não promete features que @arquiteto não aprovou
@testes    ✗ não modifica código de produção
@ux        ✗ não implementa código Vue — apenas orienta @front
```

---

## PASSO 5 — Resolução de conflitos

Quando dois agentes têm visões diferentes:

1. **Técnico vs. UX:** `@arquiteto` arbitra, priorizando viabilidade técnica com mínimo impacto na UX
2. **Back vs. Front (sobre contrato de API):** `@arquiteto` define o contrato no schema `*-comuns`
3. **Documentação vs. Implementação:** O código é a verdade — `@documentacao` atualiza para refletir o código
4. **Comercial vs. Produto:** `@arquiteto` define o que existe; `@comercial` comunica apenas o real

---

## PASSO 6 — Fluxos típicos de colaboração

### Fluxo: Nova feature completa

```
@arquiteto → especifica schema e contrato de API
     ↓
@back → implementa endpoint + atualiza *-comuns
     ↓
@front → implementa tela consumindo *-comuns
     ↓ (paralelo)
@ux → revisa UX da tela
     ↓
@testes → valida back + front
     ↓
@deploy → publica
     ↓ (paralelo)
@documentacao → documenta
     ↓
@comercial → cria material de divulgação
```

### Fluxo: Correção de bug crítico

```
@testes → identifica e documenta bug
     ↓
@back ou @front → corrige
     ↓
@testes → valida correção
     ↓
@deploy → hotfix
```

### Fluxo: Melhoria de UX

```
@ux → identifica problema e propõe melhoria
     ↓
@arquiteto → avalia impacto técnico
     ↓
@front → implementa
     ↓
@ux → valida
```

---

## Checklist de orquestração

- [ ] Agentes necessários identificados?
- [ ] Sequência de handoff definida?
- [ ] Dependências entre agentes mapeadas?
- [ ] Critérios de aceite definidos para cada entrega?
- [ ] Conflitos potenciais identificados e árbitro definido?

---

## Referências

- Rule: `global/rules/autonomia-agente`
- Rule: `global/rules/fronteiras-monorepo`
- Personas: `agents/*/persona`