.agent/workflows/aprimorar-IA.global.md

type	name	description	scope	updatedAt
workflow	aprimorar-IA	Dois comandos para extrair conhecimento das conversas e aplicá-lo nas estruturas do ecossistema de agentes	global	2026-07-02

Workflow: Aprimorar IA Global

🎯 Visão Geral

Este workflow opera em duas fases independentes, cada uma com um comando próprio:

Comando	Fase	O que faz
aprimorar-ia-global	Captura	Lê a conversa, extrai conhecimento e registra na Memória Corporativa
aplicar-aprimorar-ia-global	Aplicação	Lê a Memória Corporativa e atualiza as estruturas do ecossistema (rules, workflows, skills, agent.json)

As fases são intencionalmente desacopladas: a captura pode ocorrer em qualquer conversa; a aplicação pode ser executada depois, inclusive em sessão separada.

---

FASE 1 — aprimorar-ia-global

Objetivo

Varrer a conversa atual, identificar conhecimento útil e registrá-lo na Memória Azteca (https://memoria-ia.idz.one) sem modificar nenhum arquivo do ecossistema.

Quando executar

• Ao final de qualquer conversa em que houve:
  • Decisões arquiteturais ou técnicas novas
  • Padrões definidos ou alterados
  • Bugs encontrados e resolvidos
  • Regras de negócio descobertas
  • Qualquer conhecimento que beneficiaria sessões futuras

Passo 1 — Analisar a conversa

Ler integralmente o histórico da conversa atual e identificar cada item de conhecimento extraível:

Para cada item descoberto, classificar:
  - É uma DECISÃO arquitetural? → categoria: decisoes, tipo: adr
  - É um PADRÃO técnico?        → categoria: tecnologias, tipo: referencia
  - É uma SOLUÇÃO de problema?  → categoria: solucao-problemas, tipo: solucao-problemas
  - É uma REGRA DE NEGÓCIO?     → categoria: regras-negocio, tipo: referencia
  - É info de MÓDULO/CONTEXTO?  → categoria: modulos, tipo: referencia

Passo 2 — Buscar duplicatas antes de registrar

Para cada item identificado, verificar se já existe na memória:

curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"termo": "PALAVRAS_CHAVE_DO_ITEM"}' | jq '.items[].titulo'

• Se existir: editar (/api/memorias/editar) em vez de criar novo
• Se não existir: criar novo registro

Passo 3 — Registrar na Memória Corporativa

curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "titulo": "Título claro e pesquisável",
    "conteudo": "Descrição detalhada com contexto, decisão e motivo",
    "resumo": "Síntese de 10-500 chars — alimenta a busca vetorial",
    "categoria": "CATEGORIA_ADEQUADA",
    "tipo": "TIPO_ADEQUADO",
    "tags": ["aprimorar-ia", "tag-adicional"],
    "contexto": "Nome do módulo ou projeto",
    "criado_por": "@ag-agente"
  }' | jq '{codigo: .codigo, titulo: .titulo}'

resumo é obrigatório — sem ele a API retorna erro 400.

aprimorar-ia é a tag padrão — toda memória registrada por este workflow DEVE incluí-la. Ela é o identificador que permite à Fase 2 recuperar exatamente esses registros.

Passo 4 — Criar vínculos (quando aplicável)

Se o item registrado está relacionado a memórias já existentes:

curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo_memoria_a": NOVO_ID,
    "codigo_memoria_b": EXISTENTE_ID,
    "relacao": "{mem:NOVO_ID} expande o padrão de {mem:EXISTENTE_ID}",
    "criado_por": "@ag-agente"
  }'

Checklist da Fase 1

• Conversa lida integralmente
• Todos os itens de conhecimento identificados e classificados
• Duplicatas verificadas antes de criar
• resumo preenchido em todos os registros
• Vínculos criados entre memórias relacionadas
• Nenhum código-fonte, log ou dado sensível foi registrado

---

FASE 2 — aplicar-aprimorar-ia-global

Objetivo

Ler os registros recentes da Memória Corporativa e traduzir o conhecimento acumulado em mudanças concretas nas estruturas do ecossistema: global/rules/, global/workflows/, global/skills/, agents/*/persona, agents/*/agent.json.

Quando executar

• Quando houver registros na memória que ainda não foram aplicados ao ecossistema
• Após um conjunto de conversas de aprendizado (aprimorar-ia-global) acumular massa crítica
• Antes de atualizar projetos que usam o ecossistema como submodulo

Passo 1 — Consultar registros relevantes da memória

A tag aprimorar-ia é o filtro primário — recupera exatamente os registros capturados pela Fase 1:

# Buscar todos os registros pendentes de aplicação (tag aprimorar-ia, sem tag aplicado-no-ecossistema)
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"tags": ["aprimorar-ia"], "limite": 50}' | jq '.items[] | {codigo, titulo, resumo, tags}'

Se precisar filtrar por categoria específica:

# Apenas decisões arquiteturais ainda não aplicadas
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"tags": ["aprimorar-ia"], "categoria": "decisoes", "limite": 20}' | jq '.items[] | {codigo, titulo, resumo}'

Registros com a tag aplicado-no-ecossistema já foram processados e podem ser ignorados.

Passo 2 — Classificar cada item pelo tipo de mudança

Para cada registro da memória, determinar o impacto:

ITEM DA MEMÓRIA → AÇÃO NO ECOSSISTEMA
─────────────────────────────────────────────────────────────────
Convenção que agentes DEVEM respeitar sempre  → CRIAR/ATUALIZAR rule em global/rules/
Processo repetível com etapas definidas       → CRIAR/ATUALIZAR workflow em global/workflows/
Guia operacional complexo e reutilizável      → CRIAR/ATUALIZAR skill em global/skills/
Escopo ou comportamento de um agente          → ATUALIZAR persona do agente em agents/*/persona
Padrão novo sem impacto em artefatos          → Nenhuma ação (permanece só na memória)

Passo 3 — Aplicar mudanças nos artefatos

Criar ou atualizar uma rule global

Arquivo em global/rules/<nome-em-kebab-case>:

---
type: rule
name: nome-da-rule
description: O que a rule faz em uma linha
scope: global
trigger: always_on | context_match | file_match
priority: alta | normal
updatedAt: "AAAA-MM-DD"
---

# Regra: Nome

## Contexto
Quando se aplica.

## Regra
Definição objetiva e obrigatória.

## Exemplos
✅ Correto
❌ Incorreto

## Impacto
Problema que evita.

## Referências
- Memória: https://memoria-ia.idz.one (código: MEM_ID)

Criar ou atualizar um workflow global

Arquivo em global/workflows/<nome>.global.md.

Criar ou atualizar uma skill global

Arquivo em global/skills/<nome>/SKILL (sem extensão).

Passo 4 — Regenerar os agent.json

Após qualquer mudança em global/rules/ ou personas:

# No repositório raiz do ecossistema
sh adaptadores/antigravity/gerar-agent-json.sh

# Para um agente específico
sh adaptadores/antigravity/gerar-agent-json.sh ag-back

Passo 5 — Verificar consistência

# Nenhum arquivo acima de 250 linhas
sh verificar-linhas.sh

# Regenerar manifesto
sh gerar-manifesto.sh

Passo 6 — Atualizar memórias após aplicação

Após aplicar cada item ao ecossistema, avaliar a relevância contínua da memória e agir conforme o caso:

Caso A — Memória ainda relevante (manter)

Se o conhecimento ainda é útil para consultas futuras (contexto histórico, referência de padrão, ADR):

1. Remover a tag aprimorar-ia — ela não precisa mais ser reprocessada
2. Atualizar o conteúdo se houver informação complementar gerada durante a aplicação
3. Adicionar aplicado-no-ecossistema para rastreabilidade

curl -s -X POST "https://memoria-ia.idz.one/api/memorias/editar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo": "CODIGO_DA_MEMORIA",
    "tags": ["aplicado-no-ecossistema"],
    "atualizado_por": "@ag-agente"
  }'

Atenção: ao editar tags, envie apenas as tags que devem permanecer — a tag aprimorar-ia é removida simplesmente por não ser incluída na lista.

Caso B — Memória sem mais relevância (remover ou ocultar)

Se o conhecimento foi totalmente absorvido pelo ecossistema e não agrega valor como referência futura (itens pontuais, contexto temporário, bugs já superados):

Opção 1 — Exclusão lógica (preferida: mantém histórico, oculta das buscas)

curl -s -X POST "https://memoria-ia.idz.one/api/memorias/excluir" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"codigo": "CODIGO_DA_MEMORIA"}'

Opção 2 — Sinalizar como obsoleta (quando há valor histórico, mas não operacional)

curl -s -X POST "https://memoria-ia.idz.one/api/memorias/sinalizar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo": "CODIGO_DA_MEMORIA",
    "obsoleto": true,
    "motivo": "Conhecimento integrado ao ecossistema em AAAA-MM-DD",
    "sinalizado_por": "@ag-agente"
  }'

Critérios de decisão

Situação	Ação
Decisão arquitetural (ADR), padrão ou regra de negócio duradoura	Manter — remove aprimorar-ia, adiciona aplicado-no-ecossistema
Solução de problema genérica (workaround reutilizável)	Manter — idem acima
Contexto pontual de uma conversa, já registrado em artefato	Excluir logicamente
Bug específico já resolvido e sem valor futuro	Excluir logicamente
Item com valor histórico mas sem uso operacional	Sinalizar como obsoleta

Checklist da Fase 2

• Memória consultada e registros relevantes identificados
• Cada item classificado pelo tipo de mudança (rule/workflow/skill/persona)
• Artefatos criados ou atualizados com frontmatter correto
• Nenhuma duplicação entre global/ e agents/*/
• Referências cruzadas apontam para caminhos válidos (sem extensão)
• agent.json regenerados após mudanças em rules ou personas
• manifesto.json regerado via sh gerar-manifesto.sh
• Cada memória tratada após aplicação (Caso A ou Caso B do Passo 6)
• Alterações informadas ao usuário para commit

---

Tipos de Artefatos — Referência Rápida

Artefato	Local	Responsabilidade
Rule	global/rules/<nome>	Restrições que agentes devem respeitar sempre
Workflow	global/workflows/<nome>.global.md	Processos sequenciais acionados por comando
Skill	global/skills/<nome>/SKILL	Guias operacionais completos e reutilizáveis
Persona	agents/<nome>/persona	Identidade, escopo e comportamento do agente
agent.json	agents/<nome>/agent.json	Compilado: persona + rules globais + rules locais

Regra de escolha

• Se é uma restrição que vale sempre → Rule
• Se é um processo com etapas que o usuário aciona → Workflow
• Se é um guia operacional com templates e checklist → Skill
• Se é comportamento ou escopo de um agente → Persona

---

Referências

• Skill: global/skills/memoria-persistente/SKILL (API completa da Memória Azteca)
• Rule: global/rules/usar-memoria-persistente
• Rule: global/rules/autonomia-agente
• Script: adaptadores/antigravity/gerar-agent-json.sh
• Script: gerar-manifesto.sh