versão 1

EXTEND.md

@@ -0,0 +1,227 @@
+# 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 git@paiol.idz.one:desenvolvimento/agent-ia.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}/`