# Plano de Trabalho — Reestruturação Multiagente do `.agent`

> **Projeto:** AGENT-IA (repositório de conhecimento centralizado da Azteca)
> **Data:** 2026-06-18
> **Premissa 1:** Estrutura atualizada com multiagente
> **Premissa 2:** Capacidade de aprendizado ao longo da execução de cada módulo
> **Premissa 3:** Compatibilidade com múltiplas LLMs para futuras migrações (vendor-neutral)

---

## Diagnóstico da Estrutura Atual

### Estado atual (flat/monolítico)

```
.agent/
├── atualizar-agente.global.sh     ← script de distribuição (hardcoded)
├── tools.md                       ← ferramentas CLI recomendadas
├── verificar-linhas.sh            ← governance: limite de linhas
├── rules/                         ← 11 rules globais (flat)
│   ├── autonomia-agente.global.md
│   ├── carta-principios-agente-azteca.global.md
│   ├── escrita-natural.global.md
│   ├── estrutura-vue.global.md
│   ├── fronteiras-monorepo.global.md
│   ├── jsdoc-padrao.global.md
│   ├── limite-linhas.global.md
│   ├── mensagens-usuario.global.md
│   ├── regras-negocio-md.global.md
│   ├── typescript-sem-any.global.md
│   └── zod-validacao-padrao.global.md
├── workflows/                     ← 11 workflows globais (flat)
│   └── (...)
└── skills/                        ← 6 skills globais (flat)
    └── (...)
```

### Problemas identificados

| # | Problema | Impacto |
|---|----------|---------|
| 1 | **Estrutura flat** — todos os artefatos são globais, sem separação por agente | Agentes recebem instruções irrelevantes (ex: ag-comercial recebe rules de TypeScript) |
| 2 | **Sem definição formal de agentes** — os 8 agentes do readme.md não existem como configuração | Impossível acionar agentes especializados |
| 3 | **Acoplamento ao Antigravity** — estrutura segue convenções de um único vendor | Migração para outra LLM exige reescrita total |
| 4 | **Script de distribuição hardcoded** — `atualizar-agente.global.sh` lista cada arquivo manualmente | Cada novo artefato exige edição manual do script |
| 5 | **Sem sistema de herança** — não há mecanismo global → plugin → agente | Rules duplicadas quando um agente precisa de variação |
| 6 | **Sem orquestração** — falta um mecanismo para agentes colaborarem em tarefas complexas | Trabalho em silos, sem passagem de contexto |

---

## Arquitetura Proposta

### Princípio Central: Separação de Camadas

```
┌─────────────────────────────────────────────────┐
│           Camada Universal (Markdown)            │ ← vendor-neutral
│  Rules, Skills, Workflows, Personas, Prompts     │   compatível com qualquer LLM
├─────────────────────────────────────────────────┤
│         Camada de Adaptador (JSON/YAML)          │ ← vendor-specific
│  agent.json (Antigravity), claude.json, etc.     │   gerado a partir da camada universal
├─────────────────────────────────────────────────┤
│            Camada de Distribuição                │ ← scripts + manifesto
│  manifesto.json + atualizar-agente.sh            │   auto-discovery, sem hardcode
└─────────────────────────────────────────────────┘
```

> **IMPORTANTE:** A **camada universal** (Markdown puro) é a fonte de verdade.
> Os adaptadores JSON são **derivados** e podem ser regenerados para qualquer plataforma.

### Nova estrutura de diretórios

```
.agent/
├── manifesto.json                         ← inventário auto-gerado de todos os artefatos
├── atualizar-agente.sh                    ← script baseado em manifesto (não hardcoded)
├── tools.md                               ← ferramentas CLI (mantido)
├── verificar-linhas.sh                    ← governance (mantido)
│
├── global/                                ← artefatos herdados por TODOS os agentes
│   ├── rules/
│   │   ├── autonomia-agente.md
│   │   ├── carta-principios-agente-azteca.md
│   │   ├── typescript-sem-any.md
│   │   ├── zod-validacao-padrao.md
│   │   ├── fronteiras-monorepo.md
│   │   ├── regras-negocio-md.md
│   │   └── limite-linhas.md
│   ├── workflows/
│   │   ├── aprimorar-IA.md
│   │   ├── documentar-regras-negocio.md
│   │   └── otimizar-codigos.md
│   └── skills/
│       ├── mapear-codigo-fonte/SKILL.md
│       ├── diagnosticar-erros-build/SKILL.md
│       ├── documentar-decisao-tecnica/SKILL.md
│       ├── documentar-regras-negocio/SKILL.md
│       ├── criar-schema-zod/SKILL.md
│       └── documentar-dominio-modulo/SKILL.md
│
├── agents/                                ← definições dos 8 agentes especializados
│   ├── ag-arquiteto/
│   │   ├── persona.md                    ← identidade, tom, escopo (vendor-neutral)
│   │   ├── agent.json                    ← config Antigravity (vendor-specific)
│   │   ├── rules/                        ← rules exclusivas deste agente
│   │   ├── workflows/                    ← workflows exclusivos
│   │   └── skills/                       ← skills exclusivas
│   │
│   ├── ag-back/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── jsdoc-padrao.md           ← movida de global (só back precisa)
│   │   │   └── estrutura-api.md
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-front/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── estrutura-vue.md          ← movida de global (só front precisa)
│   │   │   ├── escrita-natural.md        ← movida (foco em UI text)
│   │   │   └── mensagens-usuario.md      ← movida (foco em UX)
│   │   ├── workflows/
│   │   │   ├── adicionar-ajuda.md
│   │   │   ├── criar-fluxograma.md
│   │   │   └── ux.md
│   │   └── skills/
│   │
│   ├── ag-testes/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-deploy/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   ├── workflows/
│   │   │   └── atualizar-agente.md       ← movido de global
│   │   └── skills/
│   │
│   ├── ag-documentacao/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── jsdoc-padrao.md           ← compartilhada com back (herança)
│   │   │   └── escrita-natural.md
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-ux/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── mensagens-usuario.md
│   │   │   └── escrita-natural.md
│   │   ├── workflows/
│   │   │   └── ux.md
│   │   └── skills/
│   │
│   └── ag-comercial/
│       ├── persona.md
│       ├── agent.json
│       ├── rules/
│       │   └── escrita-natural.md
│       ├── workflows/
│       │   ├── comercial.md
│       │   ├── marketing.md
│       │   ├── orcamento.md
│       │   └── reels.md
│       └── skills/
│
└── adaptadores/                           ← templates de conversão por plataforma
    ├── antigravity/
    │   └── gerar-agent-json.sh           ← gera agent.json a partir de persona.md
    ├── claude/
    │   └── README.md                     ← futuro: instruções para Claude
    └── openai/
        └── README.md                     ← futuro: instruções para OpenAI/GPT
```

---

## Fases do Trabalho

### Fase 1 — Fundação: Camada Universal (vendor-neutral)

**Objetivo:** Criar os arquivos `persona.md` de cada agente — a fonte de verdade que funciona com qualquer LLM.

#### Estrutura padrão do `persona.md`

```markdown
---
name: ag-back
display_name: "Agente Backend"
description: >
  Responsável pelo desenvolvimento do backend...
scope: [back, comuns, migracao]
inherits: [global]
tools: [view_file, replace_file_content, run_command, grep_search]
---

# Agente Backend (@ag-back)

## Identidade
Você é o agente especialista em backend...

## Escopo de Atuação
- Pacotes: *-back, *-comuns, *-migracao
- Linguagem: TypeScript (Node.js)
- Frameworks: Express/Fastify, Knex, BullMQ

## Responsabilidades
1. Implementação da lógica de negócio
2. Rotas e APIs REST
3. Integrações com banco de dados
4. Processamento de filas
5. CRONs e workers

## Restrições
- NUNCA alterar pacotes *-front
- NUNCA criar componentes Vue
- Respeitar todas as rules globais herdadas

## Colaborações
- Recebe especificações de: @ag-arquiteto
- Schemas compartilhados com: @ag-front (via *-comuns)
- Valida integridade com: @ag-testes
```

> O `persona.md` é **Markdown puro** — funciona como instrução para Antigravity, Claude, GPT, Gemini, LLaMA ou qualquer LLM futura.
> O frontmatter YAML contém metadados estruturados que os adaptadores leem programaticamente.

#### Tarefas

| # | Tarefa | Arquivos |
|---|--------|----------|
| 1.1 | Criar `persona.md` para `ag-arquiteto` | `agents/ag-arquiteto/persona.md` |
| 1.2 | Criar `persona.md` para `ag-back` | `agents/ag-back/persona.md` |
| 1.3 | Criar `persona.md` para `ag-front` | `agents/ag-front/persona.md` |
| 1.4 | Criar `persona.md` para `ag-testes` | `agents/ag-testes/persona.md` |
| 1.5 | Criar `persona.md` para `ag-deploy` | `agents/ag-deploy/persona.md` |
| 1.6 | Criar `persona.md` para `ag-documentacao` | `agents/ag-documentacao/persona.md` |
| 1.7 | Criar `persona.md` para `ag-ux` | `agents/ag-ux/persona.md` |
| 1.8 | Criar `persona.md` para `ag-comercial` | `agents/ag-comercial/persona.md` |

**Estimativa:** 1-2 sessões de trabalho

---

### Fase 2 — Redistribuição de Artefatos Existentes

**Objetivo:** Mover rules, workflows e skills para seus donos corretos (global vs agente específico).

#### Mapa de redistribuição de Rules

| Rule atual | Destino | Justificativa |
|-----------|---------|---------------|
| `autonomia-agente` | **global** | Todos os agentes devem respeitar |
| `carta-principios-agente-azteca` | **global** | Constituição comportamental universal |
| `typescript-sem-any` | **global** | Todo código TS, independente do agente |
| `zod-validacao-padrao` | **global** | Validação é transversal |
| `fronteiras-monorepo` | **global** | Todos devem respeitar fronteiras |
| `regras-negocio-md` | **global** | Qualquer agente que toque lógica de negócio |
| `limite-linhas` | **global** | Governance universal |
| `estrutura-vue` | **ag-front** | Só o front usa Vue |
| `escrita-natural` | **ag-front, ag-ux, ag-documentacao, ag-comercial** | Agentes que produzem texto para humanos |
| `jsdoc-padrao` | **ag-back, ag-documentacao** | Agentes que documentam código |
| `mensagens-usuario` | **ag-front, ag-ux** | Agentes que criam UI/UX |

#### Mapa de redistribuição de Workflows

| Workflow atual | Destino | Justificativa |
|---------------|---------|---------------|
| `aprimorar-IA` | **global** | Meta-workflow de evolução contínua |
| `otimizar-codigos` | **global** | Refatoração transversal |
| `documentar-regras-negocio` | **global** | Qualquer agente pode documentar |
| `atualizar-agente` | **ag-deploy** | Infraestrutura |
| `adicionar-ajuda` | **ag-front** | Interface |
| `criar-fluxograma` | **ag-front** | Interface |
| `ux` | **ag-front, ag-ux** | UX |
| `comercial` | **ag-comercial** | Comercial |
| `marketing` | **ag-comercial** | Marketing |
| `orcamento` | **ag-comercial** | Orçamento |
| `reels` | **ag-comercial** | Marketing digital |

#### Tarefas

| # | Tarefa | Impacto |
|---|--------|---------|
| 2.1 | Criar diretório `global/` e mover artefatos globais | 7 rules, 3 workflows, 6 skills |
| 2.2 | Criar diretórios por agente e distribuir artefatos específicos | 4 rules, 8 workflows |
| 2.3 | Remover sufixo `.global` dos nomes de arquivo | Todos os artefatos |
| 2.4 | Atualizar referências cruzadas nos artefatos | Seções `Referências` |
| 2.5 | Criar mecanismo de herança via `inherits` no frontmatter | `persona.md` → resolve rules efetivas |

> **ATENÇÃO:** A redistribuição altera mais de 5 arquivos. Requer confirmação conforme rule `autonomia-agente`.

**Estimativa:** 1-2 sessões de trabalho

---

### Fase 3 — Camada de Adaptador (Antigravity-first)

**Objetivo:** Gerar os `agent.json` compatíveis com Antigravity a partir dos `persona.md`.

#### Formato `agent.json` (Antigravity)

```json
{
  "name": "ag-back",
  "description": "Responsável pelo desenvolvimento do backend...",
  "hidden": false,
  "config": {
    "customAgent": {
      "systemPromptSections": [
        {
          "title": "Identidade e Escopo",
          "content": "<!-- conteúdo extraído de persona.md -->"
        },
        {
          "title": "Rules Efetivas",
          "content": "<!-- rules globais + rules do agente, concatenadas -->"
        }
      ],
      "toolNames": [
        "view_file", "replace_file_content", "multi_replace_file_content",
        "write_to_file", "run_command", "grep_search", "list_dir",
        "send_message"
      ],
      "systemPromptConfig": {
        "includeSections": [
          "user_information", "user_rules", "skills",
          "subagent_reminder", "messaging", "artifacts"
        ]
      }
    }
  }
}
```

#### Script adaptador `gerar-agent-json.sh`

Lê o `persona.md` + rules efetivas (globais + do agente) e gera o `agent.json` automaticamente. Passos:

1. Parsear frontmatter YAML do `persona.md`
2. Resolver herança: `inherits: [global]` → incluir todas as rules de `global/rules/`
3. Concatenar rules do agente (`agents/{nome}/rules/`)
4. Gerar `systemPromptSections` a partir do corpo do `persona.md`
5. Mapear `tools` do frontmatter para `toolNames`
6. Escrever `agent.json`

#### Tarefas

| # | Tarefa |
|---|--------|
| 3.1 | Criar script `adaptadores/antigravity/gerar-agent-json.sh` |
| 3.2 | Gerar `agent.json` para cada um dos 8 agentes |
| 3.3 | Criar stub `adaptadores/claude/README.md` (placeholder para futuro) |
| 3.4 | Criar stub `adaptadores/openai/README.md` (placeholder para futuro) |
| 3.5 | Validar que os `agent.json` são reconhecidos pelo Antigravity |

**Estimativa:** 1 sessão de trabalho

---

### Fase 4 — Manifesto e Distribuição Inteligente

**Objetivo:** Substituir o script hardcoded por um sistema baseado em manifesto com auto-discovery.

#### `manifesto.json`

```json
{
  "versao": "2.0.0",
  "base_url": "https://paiol.idz.one/desenvolvimento/agent-ia",
  "gerado_em": "2026-06-18T10:00:00-03:00",
  "artefatos": {
    "global": {
      "rules": [
        "global/rules/autonomia-agente.md",
        "global/rules/carta-principios-agente-azteca.md",
        "global/rules/typescript-sem-any.md"
      ],
      "workflows": [
        "global/workflows/aprimorar-IA.md"
      ],
      "skills": [
        "global/skills/mapear-codigo-fonte/SKILL.md"
      ]
    },
    "agents": {
      "ag-back": {
        "persona": "agents/ag-back/persona.md",
        "config": "agents/ag-back/agent.json",
        "rules": ["agents/ag-back/rules/jsdoc-padrao.md"],
        "workflows": [],
        "skills": []
      }
    }
  }
}
```

#### Novo `atualizar-agente.sh`

```bash
# Em vez de listar cada arquivo:
# 1. Baixa manifesto.json
# 2. Itera sobre todos os caminhos listados
# 3. Baixa cada artefato automaticamente
# Resultado: novos artefatos são incluídos sem editar o script
```

#### Tarefas

| # | Tarefa |
|---|--------|
| 4.1 | Criar `manifesto.json` com inventário completo |
| 4.2 | Criar script `gerar-manifesto.sh` (auto-discovery via `fd`) |
| 4.3 | Reescrever `atualizar-agente.sh` baseado em manifesto |
| 4.4 | Testar distribuição end-to-end em um módulo de teste |

**Estimativa:** 1 sessão de trabalho

---

### Fase 5 — Orquestração entre Agentes

**Objetivo:** Definir como agentes colaboram em tarefas que cruzam fronteiras.

#### Modelo de colaboração

```
@ag-arquiteto ──especificação──► @ag-back ──schemas *-comuns──► @ag-front
       │                              │                              │
       │                              ▼                              ▼
       │                        @ag-testes ◄──────────────── @ag-testes
       │                              │
       ├──wireframes──► @ag-front ──fluxos──► @ag-ux ──melhorias──► @ag-front
       │
       ├──features──► @ag-comercial
       │
       └──────────────► @ag-documentacao ──docs──► @ag-comercial
                              ▲
                    @ag-back ──código──┘
                    @ag-front ─código──┘

@ag-back ──build──► @ag-deploy
@ag-front ─build──► @ag-deploy
```

#### Skill de orquestração

Criar uma skill global `orquestrar-agentes/SKILL.md` que define:

- **Protocolo de handoff** — como um agente passa contexto para outro
- **Formato de mensagem** — estrutura padrão para `send_message` entre agentes
- **Regras de escopo** — qual agente pode chamar qual
- **Resolução de conflito** — quando dois agentes discordam

#### Tarefas

| # | Tarefa |
|---|--------|
| 5.1 | Criar `global/skills/orquestrar-agentes/SKILL.md` |
| 5.2 | Definir protocolo de mensagens inter-agentes |
| 5.3 | Adicionar seção `Colaborações` em cada `persona.md` |
| 5.4 | Testar fluxo: arquiteto → back → front (end-to-end) |

**Estimativa:** 1-2 sessões de trabalho

---

### Fase 6 — Validação e Documentação

**Objetivo:** Garantir integridade da nova estrutura e documentar para o time.

#### Tarefas

| # | Tarefa |
|---|--------|
| 6.1 | Atualizar `readme.md` com a nova arquitetura |
| 6.2 | Criar `AGENTS.md` na raiz (ponto de entrada para ativação de agentes) |
| 6.3 | Executar validação: todo `persona.md` tem `agent.json` correspondente |
| 6.4 | Executar validação: toda rule referenciada existe no caminho correto |
| 6.5 | Executar validação: manifesto cobre 100% dos artefatos |
| 6.6 | Testar distribuição em módulo real do e-licencie |

**Estimativa:** 1 sessão de trabalho

---

## Resumo de Esforço

| Fase | Descrição | Sessões |
|------|-----------|---------|
| **1** | Camada Universal (personas) | 1-2 |
| **2** | Redistribuição de artefatos | 1-2 |
| **3** | Adaptador Antigravity | 1 |
| **4** | Manifesto e distribuição | 1 |
| **5** | Orquestração | 1-2 |
| **6** | Validação e documentação | 1 |
| **Total** | | **6-9 sessões** |

---

## Compatibilidade Multi-LLM

> A arquitetura foi desenhada para que **trocar de LLM não exija reescrever o conhecimento dos agentes**.

| Camada | O que contém | Formato | Portabilidade |
|--------|-------------|---------|---------------|
| **Universal** | Personas, Rules, Skills, Workflows | Markdown puro + frontmatter YAML | ✅ 100% portável — qualquer LLM entende Markdown |
| **Adaptador** | `agent.json`, configs de plataforma | JSON específico do vendor | 🔄 Regenerável via script para cada plataforma |
| **Distribuição** | Manifesto, scripts de deploy | Shell + JSON | ✅ Independente de LLM |

### Para migrar para outra LLM:

1. Criar novo adaptador em `adaptadores/{nova-llm}/`
2. Implementar script que lê `persona.md` + rules e gera config nativa
3. **Zero alteração** na camada universal

### Plataformas previstas:

| Plataforma | Status | Adaptador |
|-----------|--------|-----------|
| **Antigravity (Google)** | 🟢 Ativo | `adaptadores/antigravity/` |
| **Claude (Anthropic)** | 🟡 Preparado | `adaptadores/claude/` (stub) |
| **GPT (OpenAI)** | 🟡 Preparado | `adaptadores/openai/` (stub) |
| **Gemini (Google AI)** | ⚪ Futuro | — |
| **LLaMA (Meta)** | ⚪ Futuro | — |

---

## Riscos e Mitigações

| Risco | Probabilidade | Mitigação |
|-------|--------------|-----------|
| Rules globais muito genéricas perdem eficácia | Média | Revisão por agente na Fase 2 |
| Overhead de manutenção com 8 agentes | Média | Manifesto auto-gerado + herança automática |
| Antigravity muda API de plugins | Baixa | Camada universal não é afetada |
| Agentes concorrentes editam mesmo arquivo | Alta | Protocolo de handoff (Fase 5) |

---

## Próximo Passo

> Aguardando aprovação do plano para iniciar a **Fase 1** — criação dos `persona.md` dos 8 agentes.