# Como usar o AGENT-IA como submodulo git

O AGENT-IA é adicionado como **git submodule** em cada projeto filho.
Isso garante controle de versão, rollback seguro e atualizações rastreáveis.

---

## Estrutura em um projeto filho

```
meu-modulo/
├── .agent/
│   ├── base/              ← git submodule (AGENT-IA repo — nunca editar)
│   │   └── .agent/
│   │       ├── global/
│   │       ├── agents/
│   │       ├── adaptadores/
│   │       └── ...
│   ├── local/             ← suas extensões (commitar no projeto)
│   │   ├── rules/
│   │   ├── workflows/
│   │   ├── skills/
│   │   └── agents/
│   ├── inherited/         ← cópia sincronizada do base (git-ignored)
│   ├── manifesto-local.json
│   └── atualizar-agente.sh
└── .gitmodules            ← gerado pelo git ao adicionar submodulo
```

---

## Configuração inicial (uma vez por projeto)

### 1. Adicionar o AGENT-IA como submodulo

```sh
# Na raiz do projeto
git submodule add https://git2.idz.one/publico/.agent.git .agent/base
git submodule update --init --recursive
```

### 2. Criar a estrutura local

```sh
mkdir -p .agent/local/rules
mkdir -p .agent/local/workflows
mkdir -p .agent/local/skills
mkdir -p .agent/local/agents
```

### 3. Criar o `manifesto-local.json`

```sh
cp .agent/base/.agent/manifesto-local.template.json .agent/manifesto-local.json
```

Editar o arquivo:

```json
{
  "submodulo": ".agent/base",
  "projeto": "sigma2026",
  "descricao": "Módulo de monitoramento ambiental",
  "versao": "1.0.0",
  "local": {
    "rules": [
      "local/rules/dominio-ambiental.md"
    ],
    "workflows": [],
    "skills": [
      "local/skills/criar-funcao-api/SKILL.md"
    ],
    "agents": {
      "ag-back": {
        "persona-local": "local/agents/ag-back/persona-local.md",
        "rules": [
          "local/agents/ag-back/rules/knex-padrao.md"
        ]
      }
    }
  }
}
```

### 4. Copiar e executar o script de sincronização

```sh
cp .agent/base/.agent/atualizar-agente.sh .agent/atualizar-agente.sh
chmod +x .agent/atualizar-agente.sh
sh .agent/atualizar-agente.sh
```

Isso popula `.agent/inherited/` com os artefatos do base, sem tocar em `local/`.

### 5. Configurar `.gitignore`

```gitignore
# Artefatos sincronizados do submodulo — regenerados automaticamente
.agent/inherited/
```

---

## Como atualizar o base no futuro

```sh
# Atualiza o submodulo para o commit mais recente e sincroniza
sh .agent/atualizar-agente.sh

# Só atualiza o git sem sincronizar (verificar antes)
sh .agent/atualizar-agente.sh --no-pull --dry-run

# Atualiza sem fazer pull (usar conteúdo atual do submodulo)
sh .agent/atualizar-agente.sh --no-pull
```

---

## Como fazer override de um agente

Crie `persona-local.md` em `local/agents/{agente}/`:

```markdown
---
name: ag-back
extends: inherited/agents/ag-back/persona.md
project: sigma2026
---

# Extensão: @ag-back para sigma2026

## Contexto adicional do projeto

- PostgreSQL com PostGIS (coordenadas geográficas)
- JSONB para características variáveis por tipo de monitoramento
- Padrão `zBaseTabelaPadrao` do sigma-comuns

## Regras adicionais

- Toda query de coordenadas usa funções PostGIS
- O campo `info` é cache descartável — não é fonte primária
```

---

## Como adicionar uma rule local

Crie em `local/rules/`:

```markdown
---
name: dominio-ambiental
description: Vocabulário e padrões do domínio ambiental para o sigma2026
scope: local
---

# Regra: Domínio Ambiental (sigma2026)

## Contexto
...

## Regra
...
```

Declare no `manifesto-local.json`:
```json
"local": {
  "rules": ["local/rules/dominio-ambiental.md"]
}
```

---

## Precedência de artefatos

```
local/ > inherited/ (base)
```

| Situação | Resultado |
|----------|-----------|
| Artefato só em `inherited/` | Usa o base |
| Artefato só em `local/` | Usa o local |
| Artefato em ambos | `local/` tem prioridade |

---

## Pinagem de versão (segurança)

O submodulo fica travado em um commit específico do AGENT-IA.
Para atualizar para uma versão específica:

```sh
cd .agent/base
git checkout v2.1.0           # travar em tag
# ou
git checkout main             # usar sempre o mais recente

cd ../..
git add .agent/base
git commit -m "chore: atualizar agent-ia para v2.1.0"
```

---

## O que commitar no projeto filho

```
✅ Commitar:
  .agent/manifesto-local.json
  .agent/atualizar-agente.sh
  .agent/local/           (todas as extensões locais)
  .gitmodules             (referência ao submodulo)

❌ Não commitar (adicionar ao .gitignore):
  .agent/inherited/       (sincronizado automaticamente)
```

---

## Compatibilidade com múltiplas LLMs

O modelo de herança funciona com qualquer LLM:
- `local/` e `inherited/` são **Markdown puro**
- `manifesto-local.json` é **JSON genérico**
- Para gerar config nativa de uma LLM: use `inherited/adaptadores/{llm}/`