Framework Multiagente Polimórfico (.agent) — Ecossistema Azteca

Repositório central de conhecimento para os agentes de IA do ecossistema Azteca. Usado como git submodule .agent nos repositórios e monorepos do ecossistema.

---

Premissas

1. Polimórfico & Agnóstico ao Projeto — o .agent é um submódulo genérico compartilhado entre múltiplos projetos do ecossistema, sem acoplamento fixo a nenhum módulo específico
2. Multiagente — 11 agentes especializados com escopo e responsabilidades bem definidos
3. Personalização e Identidade Desacopladas via memorias-ia/modulo.yml — toda informação referente ao módulo hospedeiro reside em ./memorias-ia/modulo.yml, ./memorias-ia/, <modulo-wiki>/<modulo-id>/ e <modulo-wiki>/dev/<modulo-id>/
4. Aprendizado contínuo — conhecimento evolui a cada sessão via workflow /aprimora-ia
5. Vendor-neutral — arquitetura em Markdown puro, compatível com qualquer LLM
6. Documentation-Driven (DDD) — documentação precede implementação nos 6 pilares

---

Arquitetura Polimórfica e Locais de Personalização

O repositório .agent fornece a estrutura genérica de inteligência (regras universais, personas, workflows e skills). A identidade e personalização de cada projeto é armazenada estritamente fora do submódulo .agent, tendo memorias-ia/modulo.yml como fonte única da verdade:

<projeto-pai>/
├── memorias-ia/                    ← Personalização & Identidade:
│   ├── modulo.yml                  ← OBRIGATÓRIO: modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki
│   ├── historico-acoes.md          ← Índice central cumulativo de ações da IA
│   └── sessao-*.md                 ← Histórico de ações e memórias de IA deste projeto
├── PLANOS/                         ← Fila de Planos Técnicos (Tester ➔ Dev):
│   ├── pendente/                   ← Planos criados por testers aguardando dev (/plano <instrução>)
│   └── executado/                  ← Planos implementados, testados e arquivados (/plano.executar <slug>)
├── .agent/                         ← Polimórfico: Submódulo genérico compartilhado
│   ├── DOCUMENTACAO/               ← Hub DDD: Manifesto e templates padronizados
│   ├── global/                     ← Rules, workflows e skills globais
│   └── agents/                     ← Personas e configurações dos 11 agentes
│
└── <modulo-wiki>/                  ← Aplicação VitePress com a documentação viva (padrão: ../wiki/)
    ├── <modulo-id>/                ← Personalização: Documentação com ACESSO DOS USUÁRIOS
    └── dev/<modulo-id>/            ← Personalização: Documentação técnica ACESSO INTERNO DEV

---

Estrutura do repositório

memorias-ia/                        ← armazenamento de memórias das ações da IA (na raiz do projeto pai)
├── modulo.yml                      ← identificador mandatório do projeto (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso, modulo-wiki)
├── historico-acoes.md              ← índice central de sessões e citações no código
PLANOS/                             ← fila de planos técnicos de implementação (Tester ➔ Dev)
├── pendente/                       ← gerados via /plano pelo tester em reviews
└── executado/                      ← arquivados após implementação pelo dev
.agent/                             ← raiz do repositório de agentes (submódulo)
├── DOCUMENTACAO/                   ← hub DDD — matriz canônica dos 6 pilares
│   ├── README                      ← manifesto DDD: princípios e workflow
│   ├── INDICE                      ← índice navegável de toda documentação
│   └── templates/                  ← templates padronizados dos 6 pilares
│       ├── modulo.yml.template     ← identidade do módulo (memorias-ia/modulo.yml)
│       ├── historico-acoes.md.template ← índice central de ações da IA (memorias-ia/historico-acoes.md)
│       ├── sessao-memoria.md.template  ← relato individual de sessão (memorias-ia/sessao-*.md)
│       ├── modulo-dominio.md.template ← domínio e glossário (Wiki Usuário/Dev)
│       ├── regra-negocio.md.template  ← regras de negócio (Wiki Dev)
│       ├── adr.md.template         ← decisões técnicas (ADRs na Wiki Dev)
│       ├── ajuda-tela.md.template  ← ajuda contextual na UI (Pilar 2)
│       ├── contrato-api.md.template ← contratos de endpoints e schemas
│       ├── fluxo-usuario.md.template ← fluxos e jornadas de usuário
│       └── plano.md.template       ← planos técnicos de implementação (PLANOS/)
├── README                          ← este arquivo
├── TOOLS                           ← ferramentas CLI recomendadas
├── manifesto.json                  ← inventário de todos os artefatos
├── manifesto-local.template.json   ← template para projetos filhos
├── verificar-linhas.sh             ← governance: limite de 250 linhas
├── validar-setup.sh                ← governance: auditoria automática de setup multi-projeto
├── scripts/                        ← utilitários de ciclo de vida, MinIO Paiol e Graphify
│
├── global/                         ← herdado por TODOS os agentes
│   ├── rules/                      ← regras universais (identidade-modulo, ddd, etc.)
│   ├── workflows/                  ← workflows globais
│   └── skills/                     ← skills globais
│
├── agents/                         ← definição dos 11 agentes
│   ├── arquiteto/
│   ├── back/
│   ├── front/
│   ├── testes/
│   ├── deploy/
│   ├── documentacao/
│   ├── ux/
│   ├── comercial/
│   ├── agente/
│   ├── refatorar/
│   └── land/

---

Agentes disponíveis

Handle	Agente	Especialidade
@arquiteto	Arquiteto	Arquitetura, especificações, ADRs
@back	Backend	APIs, banco de dados, filas, CRONs, rota /llm.md
@front	Frontend	Componentes, telas, composables, ajuda contextual {componente}.ajuda.md
@testes	Testes	Testes unitários, integração, roteiros de QA e E2E via agent-browser
@deploy	Deploy	Docker, CI/CD, infraestrutura, ambientes
@documentacao	Documentação	Guardião dos 6 pilares (código, .ajuda.md, wiki usuário, wiki dev, /llm.md, memorias-ia/)
@ux	UX	Fluxos de uso, usabilidade, mensagens de interface
@comercial	Comercial	Propostas, marketing, Reels, orçamentos
@agente	Arquiteto de Agentes	Arquitetura, governança e evolução do ecossistema multiagente
@refatorar	Refatoração	SOLID, Design Patterns GoF, code smells, refatoração segura
@land	Landing Pages & Sites	Criação de sites, landing pages de alta conversão, copywriting B2B/B2G e CTAs

---

Usar em um novo projeto (Onboarding em 4 passos)

# 1. Adicionar e sincronizar o submódulo na branch master
git submodule add -b master https://git2.idz.one/publico/.agent.git .agent
git submodule update --init --recursive --remote

# 2. Criar obrigatoriamente a identidade do módulo
mkdir -p memorias-ia
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
cp .agent/DOCUMENTACAO/templates/historico-acoes.md.template memorias-ia/historico-acoes.md
# Preencher em memorias-ia/modulo.yml: modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso e modulo-wiki

# 3. Auditar a conformidade do setup
bash .agent/validar-setup.sh

# 4. (Opcional) Criar camada de extensões exclusivas deste projeto
mkdir -p .agent-local/rules .agent-local/skills .agent-local/workflows

ℹ️ Hierarquia de Precedência: Artefatos em .agent-local/ sobrescrevem automaticamente os equivalentes do submódulo .agent/ (.agent-local/ > .agent/).

---

Compatibilidade com múltiplas LLMs

Camada	Formato	Portabilidade
global/ + agents/*/persona	Markdown puro	✅ 100% — qualquer LLM
agents/*/agent.json	JSON Antigravity	✅ Configuração nativa