versão 1

global/skills/orquestrar-agentes/SKILL.md

@@ -0,0 +1,177 @@
+---
+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 | `@ag-arquiteto` |
+| Implementar backend (rotas, serviços, banco) | `@ag-back` |
+| Implementar frontend (telas, componentes, fluxos) | `@ag-front` |
+| Garantir qualidade e criar testes | `@ag-testes` |
+| Configurar infraestrutura e deploy | `@ag-deploy` |
+| Criar/atualizar documentação | `@ag-documentacao` |
+| Revisar e melhorar UX | `@ag-ux` |
+| Criar materiais de venda e marketing | `@ag-comercial` |
+
+---
+
+## PASSO 2 — Definir a sequência de handoff
+
+Toda tarefa complexa segue uma ordem de precedência:
+
+```
+1. @ag-arquiteto   → define e especifica
+2. @ag-back        → implementa backend + schemas *-comuns
+3. @ag-front       → implementa frontend (consome *-comuns)
+4. @ag-ux          → revisa experiência (paralelo com front)
+5. @ag-testes      → valida qualidade
+6. @ag-deploy      → empacota e publica
+7. @ag-documentacao → documenta (pode ser paralelo)
+8. @ag-comercial   → cria materiais (após documentação)
+```
+
+Agentes podem trabalhar em paralelo quando não há dependência direta:
+- `@ag-ux` e `@ag-front` podem colaborar em paralelo
+- `@ag-documentacao` pode trabalhar em paralelo com `@ag-testes`
+- `@ag-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:** @ag-arquiteto
+**Para:** @ag-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 ✅
+
+```
+@ag-arquiteto → pode delegar para qualquer agente
+@ag-back      → pode enviar schemas e endpoints para @ag-front (via *-comuns)
+@ag-front     → pode solicitar revisão de @ag-ux
+@ag-ux        → pode propor melhorias para @ag-front
+@ag-testes    → pode reportar bugs para @ag-back e @ag-front
+@ag-documentacao → pode documentar artefatos de qualquer agente
+@ag-deploy    → recebe builds de @ag-back e @ag-front
+```
+
+### Proibido ❌
+
+```
+@ag-front     ✗ não importa código de @ag-back diretamente
+@ag-back      ✗ não cria componentes Vue ou lógica de interface
+@ag-comercial ✗ não promete features que @ag-arquiteto não aprovou
+@ag-testes    ✗ não modifica código de produção
+@ag-ux        ✗ não implementa código Vue — apenas orienta @ag-front
+```
+
+---
+
+## PASSO 5 — Resolução de conflitos
+
+Quando dois agentes têm visões diferentes:
+
+1. **Técnico vs. UX:** `@ag-arquiteto` arbitra, priorizando viabilidade técnica com mínimo impacto na UX
+2. **Back vs. Front (sobre contrato de API):** `@ag-arquiteto` define o contrato no schema `*-comuns`
+3. **Documentação vs. Implementação:** O código é a verdade — `@ag-documentacao` atualiza para refletir o código
+4. **Comercial vs. Produto:** `@ag-arquiteto` define o que existe; `@ag-comercial` comunica apenas o real
+
+---
+
+## PASSO 6 — Fluxos típicos de colaboração
+
+### Fluxo: Nova feature completa
+
+```
+@ag-arquiteto → especifica schema e contrato de API
+     ↓
+@ag-back → implementa endpoint + atualiza *-comuns
+     ↓
+@ag-front → implementa tela consumindo *-comuns
+     ↓ (paralelo)
+@ag-ux → revisa UX da tela
+     ↓
+@ag-testes → valida back + front
+     ↓
+@ag-deploy → publica
+     ↓ (paralelo)
+@ag-documentacao → documenta
+     ↓
+@ag-comercial → cria material de divulgação
+```
+
+### Fluxo: Correção de bug crítico
+
+```
+@ag-testes → identifica e documenta bug
+     ↓
+@ag-back ou @ag-front → corrige
+     ↓
+@ag-testes → valida correção
+     ↓
+@ag-deploy → hotfix
+```
+
+### Fluxo: Melhoria de UX
+
+```
+@ag-ux → identifica problema e propõe melhoria
+     ↓
+@ag-arquiteto → avalia impacto técnico
+     ↓
+@ag-front → implementa
+     ↓
+@ag-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
+
+- Rules: `.agent/global/rules/autonomia-agente.md`
+- Rules: `.agent/global/rules/fronteiras-monorepo.md`
+- Personas: `.agent/agents/*/persona.md`