146 lines
No EOL
8.6 KiB
Text
146 lines
No EOL
8.6 KiB
Text
# 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>)
|
||
├── .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
|
||
│
|
||
└── <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
|
||
.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 | |