# Esse projeto é a pasta .agent dos projetos da e-licencie

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

---

## Premissas

1. **Polimórfico & Reutilizável** — o `.agent` é um submódulo genérico compartilhado entre múltiplos projetos do ecossistema
2. **Multiagente** — 11 agentes especializados com escopo e responsabilidades bem definidos
3. **Personalização e Identidade Desacopladas** — especificidades e identificação de cada projeto residem em `./memorias-ia/modulo.yml`, `./memorias-ia/`, `<base_projeto>/../wiki/<modulo-id>/` e `<base_projeto>/../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`:

```
<projeto-pai>/
├── memorias-ia/                    ← Personalização & Identidade:
│   ├── modulo.yml                  ← OBRIGATÓRIO: modulo-id, modulo-caminho, modulo-descricao e modulo-tipo
│   └── sessao-*.md                 ← Histórico de ações e memórias de IA deste projeto
├── .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
│
└── <base_projeto>/../wiki/                     ← Aplicação VitePress com a documentação viva
    ├── <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)
.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)
│       ├── 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
├── 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
│
├── 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 | Vue 3, telas, composables, ajuda contextual `modalX.ajuda.md` |
| `@testes` | Testes | Testes unitários, integração, roteiros de QA |
| `@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 o submódulo
git submodule add git@github.com:azteca-sistemas/agent-ia.git .agent
git submodule update --init --recursive

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

# 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 |