# AGENTS — Ponto de entrada dos agentes Azteca

Este arquivo descreve como ativar e colaborar com os agentes especializados do ecossistema Azteca.

---

## Agentes disponíveis

| Agente | Handle | Especialidade |
|--------|--------|--------------|
| Arquiteto | `@ag-arquiteto` | Arquitetura, especificações, ADRs |
| Backend | `@ag-back` | APIs, banco de dados, filas, CRONs |
| Frontend | `@ag-front` | Vue 3, telas, composables, integração API |
| Testes | `@ag-testes` | Testes unitários, integração, roteiros de QA |
| Deploy | `@ag-deploy` | Docker, CI/CD, infraestrutura, ambientes |
| Documentação | `@ag-documentacao` | JSDoc, regras de negócio, guias de usuário |
| UX | `@ag-ux` | Fluxos de uso, usabilidade, mensagens de interface |
| Comercial | `@ag-comercial` | Propostas, marketing, Reels, orçamentos |
| Arquiteto de Agentes | `@ag-agente` | Arquitetura, governança e evolução do ecossistema multiagente |
| Refatoração | `@ag-refatorar` | SOLID, Design Patterns GoF, code smells, refatoração segura |

---

## Como ativar um agente

Mencione o agente pelo handle:

```
@ag-back implementa o endpoint POST /usuarios conforme schema zUsuarioCriar
```

```
@ag-ux revisa o fluxo de cadastro de empreendimento
```

---

## Estrutura do `.agent/`

Este repositório é usado como **git submodule** `.agent` nos monorepos.

```
.agent/                          ← este repositório (submodule)
├── AGENTS                       ← este arquivo
├── EXTEND                       ← como projetos filhos herdam e estendem
├── README                       ← documentação do repositório
├── TOOLS                        ← ferramentas CLI recomendadas
├── manifesto.json               ← inventário de todos os artefatos
├── gerar-manifesto.sh           ← gera manifesto.json automaticamente
├── atualizar-agente.sh          ← distribui artefatos para os módulos
├── verificar-linhas.sh          ← governance: limite de linhas
│
├── global/                      ← artefatos herdados por TODOS os agentes
│   ├── rules/                   ← 11 rules globais
│   ├── workflows/               ← 4 workflows globais
│   └── skills/                  ← 7 skills globais (incluindo orquestrar-agentes)
│
├── agents/                      ← definições dos 10 agentes
│   ├── ag-arquiteto/
│   │   └── persona              ← identidade, escopo, responsabilidades
│   ├── ag-back/
│   │   └── persona
│   ├── ag-front/
│   │   ├── persona
│   │   ├── rules/
│   │   └── workflows/
│   ├── ag-refatorar/
│   │   ├── persona
│   │   ├── rules/               ← refatoracao-segura, solid-compliance, design-patterns-pragmatico
│   │   ├── skills/              ← diagnosticar-code-smells
│   │   └── workflows/           ← refatorar-modulo
│   ├── ag-testes/
│   ├── ag-deploy/
│   ├── ag-documentacao/
│   ├── ag-ux/
│   ├── ag-comercial/
│   └── ag-agente/
│
└── adaptadores/                 ← conversores por plataforma LLM
    ├── antigravity/
    │   └── gerar-agent-json.sh  ← gera agent.json para o Antigravity
    ├── claude/
    │   └── README               ← instruções para migração futura
    └── openai/
        └── README               ← instruções para migração futura
```

> **Convenção:** artefatos de conhecimento (personas, rules, workflows, skills) não possuem extensão. Scripts (`.sh`) e dados (`.json`) mantêm suas extensões nativas.

---

## Compatibilidade com outras LLMs

A estrutura foi projetada para ser **vendor-neutral**:

- `persona` + `global/rules/` + `agents/*/rules/` = **Markdown puro**, funciona com qualquer LLM
- `agent.json` = configuração específica do Antigravity, **gerada automaticamente** pelo script adaptador
- Para migrar para outra LLM: criar adaptador em `adaptadores/{nome}/` sem alterar o conhecimento

---

## Orquestração entre agentes

Consulte a skill `global/skills/orquestrar-agentes/SKILL` para o protocolo completo de colaboração.

Sequência padrão para uma nova feature:

```
                    @ag-agente (governa o ecossistema)
                         │
@ag-arquiteto → @ag-back → @ag-front → @ag-testes → @ag-deploy
                   ↕            ↕
              @ag-refatorar  @ag-ux
                                ↓
                     @ag-documentacao → @ag-comercial
```

> `@ag-agente` governa todos os agentes — projeta, audita e evolui o ecossistema.
> `@ag-refatorar` pode ser acionado em qualquer ponto do fluxo quando código existente precisa ser melhorado.

---

## Distribuição para módulos

Para copiar os artefatos do `.agent/` para um módulo:

```sh
sh .agent/atualizar-agente.sh
```

Para gerar/atualizar o `manifesto.json` após adicionar novos artefatos:

```sh
sh .agent/gerar-manifesto.sh
```