# 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/`, `//` e `/dev//` 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: ``` / ├── 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 ) │ └── executado/ ← Planos implementados, testados e arquivados (/plano.executar ) ├── .evidencias/ ← Pasta obrigatória para evidências geradas pelos testes automatizados (screenshots, logs, traces) ├── .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 │ └── / ← Aplicação VitePress com a documentação viva (padrão: ../wiki/) ├── / ← Personalização: Documentação com ACESSO DOS USUÁRIOS └── dev// ← 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 .evidencias/ ← evidências geradas pelos testes automatizados (screenshots, capturas E2E, relatórios) .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) ```sh # 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 |