trackfw 2.15.1 → 3.0.0

package/src/identity/preset.js

@@ -0,0 +1,197 @@
+'use strict'
+
+// knownAgentIds retorna a lista canônica de ids de agentes conhecidos pelo
+// trackfw, em ordem estável e determinística. Espelha
+// internal/identity/preset.go:KnownAgentIDs.
+function knownAgentIds() {
+  return [
+    'architect',
+    'backend',
+    'frontend',
+    'qa',
+    'infra',
+    'security',
+    'dba',
+    'ux',
+    'code-quality',
+    'data',
+  ]
+}
+
+// presets contém o catálogo de presets temáticos de identidade. display_name
+// e slug são HARDCODED aqui — não derivados chamando slugify em tempo de
+// execução — porque essa é uma decisão explícita do ADR: hardcoding evita
+// depender do comportamento de normalização Unicode sendo idêntico entre os
+// CLIs Go, Node.js e Python. Espelha internal/identity/preset.go:presets.
+const PRESETS = {
+  greek: {
+    architect: { display_name: 'Zeus', slug: 'zeus' },
+    backend: { display_name: 'Apolo', slug: 'apolo' },
+    frontend: { display_name: 'Afrodite', slug: 'afrodite' },
+    qa: { display_name: 'Ártemis', slug: 'artemis' },
+    infra: { display_name: 'Ares', slug: 'ares' },
+    security: { display_name: 'Hades', slug: 'hades' },
+    dba: { display_name: 'Poseidon', slug: 'poseidon' },
+    ux: { display_name: 'Atena', slug: 'atena' },
+    'code-quality': { display_name: 'Hefesto', slug: 'hefesto' },
+    data: { display_name: 'Métis', slug: 'metis' },
+  },
+  norse: {
+    architect: { display_name: 'Odin', slug: 'odin' },
+    backend: { display_name: 'Thor', slug: 'thor' },
+    frontend: { display_name: 'Freya', slug: 'freya' },
+    qa: { display_name: 'Heimdall', slug: 'heimdall' },
+    infra: { display_name: 'Tyr', slug: 'tyr' },
+    security: { display_name: 'Vidar', slug: 'vidar' },
+    dba: { display_name: 'Njord', slug: 'njord' },
+    ux: { display_name: 'Idun', slug: 'idun' },
+    'code-quality': { display_name: 'Bragi', slug: 'bragi' },
+    data: { display_name: 'Mimir', slug: 'mimir' },
+  },
+  potter: {
+    architect: { display_name: 'Dumbledore', slug: 'dumbledore' },
+    backend: { display_name: 'Snape', slug: 'snape' },
+    frontend: { display_name: 'Luna', slug: 'luna' },
+    qa: { display_name: 'Moody', slug: 'moody' },
+    infra: { display_name: 'Hagrid', slug: 'hagrid' },
+    security: { display_name: 'Kingsley', slug: 'kingsley' },
+    dba: { display_name: 'Flitwick', slug: 'flitwick' },
+    ux: { display_name: 'Tonks', slug: 'tonks' },
+    'code-quality': { display_name: 'Hermione', slug: 'hermione' },
+    data: { display_name: 'Trelawney', slug: 'trelawney' },
+  },
+  thrones: {
+    architect: { display_name: 'Tyrion', slug: 'tyrion' },
+    backend: { display_name: 'Jon', slug: 'jon' },
+    frontend: { display_name: 'Sansa', slug: 'sansa' },
+    qa: { display_name: 'Arya', slug: 'arya' },
+    infra: { display_name: 'Brienne', slug: 'brienne' },
+    security: { display_name: 'Varys', slug: 'varys' },
+    dba: { display_name: 'Samwell', slug: 'samwell' },
+    ux: { display_name: 'Margaery', slug: 'margaery' },
+    'code-quality': { display_name: 'Stannis', slug: 'stannis' },
+    data: { display_name: 'Bran', slug: 'bran' },
+  },
+  chaves: {
+    architect: { display_name: 'Girafales', slug: 'girafales' },
+    backend: { display_name: 'Madruga', slug: 'madruga' },
+    frontend: { display_name: 'Chiquinha', slug: 'chiquinha' },
+    qa: { display_name: 'Florinda', slug: 'florinda' },
+    infra: { display_name: 'Barriga', slug: 'barriga' },
+    security: { display_name: 'Quico', slug: 'quico' },
+    dba: { display_name: 'Clotilde', slug: 'clotilde' },
+    ux: { display_name: 'Popis', slug: 'popis' },
+    'code-quality': { display_name: 'Nhonho', slug: 'nhonho' },
+    data: { display_name: 'Godinez', slug: 'godinez' },
+  },
+  pioneers: {
+    architect: { display_name: 'Turing', slug: 'turing' },
+    backend: { display_name: 'Ritchie', slug: 'ritchie' },
+    frontend: { display_name: 'Berners-Lee', slug: 'berners-lee' },
+    qa: { display_name: 'Hamilton', slug: 'hamilton' },
+    infra: { display_name: 'Torvalds', slug: 'torvalds' },
+    security: { display_name: 'Diffie', slug: 'diffie' },
+    dba: { display_name: 'Codd', slug: 'codd' },
+    ux: { display_name: 'Norman', slug: 'norman' },
+    'code-quality': { display_name: 'Knuth', slug: 'knuth' },
+    data: { display_name: 'Hopper', slug: 'hopper' },
+  },
+  starwars: {
+    architect: { display_name: 'Yoda', slug: 'yoda' },
+    backend: { display_name: 'Han', slug: 'han' },
+    frontend: { display_name: 'Leia', slug: 'leia' },
+    qa: { display_name: 'Ahsoka', slug: 'ahsoka' },
+    infra: { display_name: 'Chewbacca', slug: 'chewbacca' },
+    security: { display_name: 'Vader', slug: 'vader' },
+    dba: { display_name: 'R2-D2', slug: 'r2-d2' },
+    ux: { display_name: 'Padmé', slug: 'padme' },
+    'code-quality': { display_name: 'Obi-Wan', slug: 'obi-wan' },
+    data: { display_name: 'C-3PO', slug: 'c-3po' },
+  },
+  tolkien: {
+    architect: { display_name: 'Gandalf', slug: 'gandalf' },
+    backend: { display_name: 'Aragorn', slug: 'aragorn' },
+    frontend: { display_name: 'Arwen', slug: 'arwen' },
+    qa: { display_name: 'Legolas', slug: 'legolas' },
+    infra: { display_name: 'Gimli', slug: 'gimli' },
+    security: { display_name: 'Boromir', slug: 'boromir' },
+    dba: { display_name: 'Elrond', slug: 'elrond' },
+    ux: { display_name: 'Galadriel', slug: 'galadriel' },
+    'code-quality': { display_name: 'Faramir', slug: 'faramir' },
+    data: { display_name: 'Bilbo', slug: 'bilbo' },
+  },
+  turma: {
+    architect: { display_name: 'Franjinha', slug: 'franjinha' },
+    backend: { display_name: 'Cebolinha', slug: 'cebolinha' },
+    frontend: { display_name: 'Magali', slug: 'magali' },
+    qa: { display_name: 'Mônica', slug: 'monica' },
+    infra: { display_name: 'Cascão', slug: 'cascao' },
+    security: { display_name: 'Bidu', slug: 'bidu' },
+    dba: { display_name: 'Marocas', slug: 'marocas' },
+    ux: { display_name: 'Anjinho', slug: 'anjinho' },
+    'code-quality': { display_name: 'Titi', slug: 'titi' },
+    data: { display_name: 'Chico', slug: 'chico' },
+  },
+  egyptian: {
+    architect: { display_name: 'Thoth', slug: 'thoth' },
+    backend: { display_name: 'Rá', slug: 'ra' },
+    frontend: { display_name: 'Ísis', slug: 'isis' },
+    qa: { display_name: 'Hórus', slug: 'horus' },
+    infra: { display_name: 'Ptah', slug: 'ptah' },
+    security: { display_name: 'Anúbis', slug: 'anubis' },
+    dba: { display_name: 'Seshat', slug: 'seshat' },
+    ux: { display_name: 'Bastet', slug: 'bastet' },
+    'code-quality': { display_name: 'Maat', slug: 'maat' },
+    data: { display_name: 'Osíris', slug: 'osiris' },
+  },
+}
+
+// presetOrder é a ordem canônica e estável em que os nomes de presets são
+// listados (ex.: por presetNames e em mensagens de erro).
+const PRESET_ORDER = ['greek', 'norse', 'potter', 'thrones', 'chaves', 'pioneers', 'starwars', 'tolkien', 'turma', 'egyptian']
+
+// preset retorna a Config de identidade para o nome de preset temático dado.
+// Se name não for um preset conhecido, lança erro listando os nomes válidos.
+//
+// A Config retornada é sempre uma cópia: mutá-la não afeta a tabela de
+// presets no nível do módulo nem qualquer outra Config retornada por uma
+// chamada anterior a preset().
+function preset(name) {
+  const agents = PRESETS[name]
+  if (!agents) {
+    throw new Error(`identity: preset desconhecido "${name}" (validos: ${presetNames().join(', ')})`)
+  }
+  const copied = {}
+  for (const [id, agent] of Object.entries(agents)) {
+    copied[id] = { display_name: agent.display_name, slug: agent.slug }
+  }
+  return { schema_version: 1, agents: copied }
+}
+
+// presetNames retorna os nomes de todos os presets conhecidos, na ordem
+// estável: greek, norse, potter, thrones, chaves, pioneers, starwars,
+// tolkien, turma, egyptian.
+function presetNames() {
+  return [...PRESET_ORDER]
+}
+
+// Verificação em tempo de carga do módulo: presetOrder e PRESETS devem estar
+// em sincronia — guarda defensiva contra drift silencioso entre o mapa e a
+// ordem documentada (espelha o init() de internal/identity/preset.go).
+;(function assertPresetOrderInSync() {
+  if (PRESET_ORDER.length !== Object.keys(PRESETS).length) {
+    throw new Error('identity: presetOrder e PRESETS fora de sincronia')
+  }
+  const seen = new Set()
+  for (const name of PRESET_ORDER) {
+    if (!PRESETS[name]) {
+      throw new Error(`identity: preset "${name}" listado em presetOrder mas ausente de PRESETS`)
+    }
+    seen.add(name)
+  }
+  if (seen.size !== PRESET_ORDER.length) {
+    throw new Error('identity: presetOrder contem nomes duplicados')
+  }
+})()
+
+module.exports = { knownAgentIds, preset, presetNames }

package/src/identity/slug.js

@@ -0,0 +1,62 @@
+'use strict'
+
+// maxSlugLength é o tamanho máximo aceito para um slug gerado.
+const MAX_SLUG_LENGTH = 40
+
+// collapseDashes colapsa sequências de '-' em um único '-'.
+function collapseDashes(value) {
+  let out = ''
+  let previousDash = false
+  for (const char of value) {
+    if (char === '-') {
+      if (previousDash) continue
+      previousDash = true
+    } else {
+      previousDash = false
+    }
+    out += char
+  }
+  return out
+}
+
+// slugify converte input em um slug normalizado que casa com
+// ^[a-z0-9]+(-[a-z0-9]+)*$.
+//
+// Passos, na ordem exata (espelham internal/identity/slug.go):
+//   1. Normalização Unicode NFD + remoção de marcas diacríticas (\p{Mn}).
+//   2. Lowercase.
+//   3. Espaços (incluindo sequências) e underscores viram '-'.
+//   4. Qualquer caractere fora de [a-z0-9-] é descartado.
+//   5. Sequências de '-' colapsam em um único '-'.
+//   6. '-' nas bordas (início/fim) são removidos.
+//   7. Resultado vazio é erro.
+//   8. Resultado com mais de 40 caracteres é erro.
+//
+// slugify nunca "corrige" silenciosamente uma entrada degenerada — sempre
+// lança erro em vez de adivinhar.
+function slugify(input) {
+  const folded = String(input).normalize('NFD').replace(/\p{Mn}/gu, '')
+  const lowered = folded.toLowerCase()
+  const replaced = lowered.replace(/[ _]/g, '-')
+
+  let filtered = ''
+  for (const char of replaced) {
+    if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char === '-') {
+      filtered += char
+    }
+  }
+
+  const collapsed = collapseDashes(filtered)
+  const trimmed = collapsed.replace(/^-+/, '').replace(/-+$/, '')
+
+  if (trimmed === '') {
+    throw new Error(`identity: slug vazio para "${input}"`)
+  }
+  if (trimmed.length > MAX_SLUG_LENGTH) {
+    throw new Error(`identity: slug "${trimmed}" excede o tamanho maximo de ${MAX_SLUG_LENGTH} caracteres (tem ${trimmed.length})`)
+  }
+
+  return trimmed
+}
+
+module.exports = { slugify, MAX_SLUG_LENGTH }

package/src/integrations/index.js

@@ -1,9 +1,12 @@
 'use strict'
 
+const os = require('node:os')
+
 const { catalog, items, target, surfaceFor, readAsset } = require('./catalog')
 const { render } = require('./render')
 const { IntegrationManager } = require('./manager')
 const { legacyHashes } = require('./legacy')
+const identityStore = require('../identity')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -40,6 +43,7 @@ function selections(kind, options = {}) {
 
 function buildPlans(kind, options = {}) {
   const selected = selections(kind, options)
+  const identityConfig = options.identity || { agents: {} }
   const plans = []
   for (const { target: targetEntry, surface } of selected.targets) {
     const capability = surface.capabilities[kind]
@@ -50,7 +54,7 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination })
+          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
           const claim = { target: targetEntry.id, surface: surface.id, scope, kind, item: item.id }
           plans.push({
             claim,
@@ -89,7 +93,13 @@ function result(kind, plans, statuses) {
 }
 
 function execute(kind, operation, options = {}, roots = {}) {
-  const plans = buildPlans(kind, options)
+  // A identidade é resolvida do disco antes de buildPlans — pular esta etapa
+  // reverteria silenciosamente os nomes customizados dos agentes para os
+  // defaults neutros (espelha internal/commands/integrations_flags.go:
+  // executeIntegrationMutation/executeIntegrationList).
+  const homeRoot = roots.homeRoot || os.homedir()
+  const identityConfig = options.identity !== undefined ? options.identity : identityStore.load(homeRoot)
+  const plans = buildPlans(kind, { ...options, identity: identityConfig })
   const manager = new IntegrationManager(roots)
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)

package/src/integrations/manager.js

@@ -5,6 +5,8 @@ const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
 
+const { frontmatterName } = require('./render')
+
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
 const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item].join('\u0000')
@@ -145,6 +147,7 @@ class IntegrationManager {
   }
 
   preflight(operation, { plan, file }, manifest, force) {
+    if (operation !== 'uninstall') this.detectNameCollision(plan, file, force)
     const status = this.inspectResolved(plan, file, manifest)
     const record = manifest.artifacts[file]
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
@@ -159,6 +162,53 @@ class IntegrationManager {
     }
   }
 
+  // detectNameCollision protege contra dois artefatos de agente gerenciados
+  // distintos declarando o mesmo "name" de frontmatter dentro do mesmo
+  // diretório de destino (ADR ADR-2026-07-25-identidade-personalizavel-de-
+  // agentes, seção D4). Isso importa porque, com identidades customizáveis,
+  // dois item.id diferentes poderiam resolver para o mesmo nome renderizado
+  // (ex.: dois agentes ambos apontados para o slug "zeus"), e algumas
+  // surfaces usam esse campo name para descoberta de agentes.
+  //
+  // Limitação: a varredura só inspeciona irmãos ".md", porque é o único
+  // formato onde temos uma forma barata e sem dependências (frontmatterName)
+  // de ler de volta o name declarado a partir de bytes já renderizados.
+  // Artefatos JSON (cli-agent-json/agent-json) e TOML (custom-agent-toml)
+  // não são varridos para colisões. Espelha
+  // internal/integrations/manager.go:detectNameCollision.
+  detectNameCollision(plan, file, force) {
+    if (plan.claim.kind !== 'agents') return
+    if (path.extname(file) !== '.md') return
+    const desiredName = frontmatterName(plan.content)
+    if (!desiredName) return
+    const directory = path.dirname(file)
+    let entries
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true })
+    } catch (err) {
+      if (err.code === 'ENOENT') return
+      throw new Error(`scan ${directory} for name collisions: ${err.message}`)
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() || path.extname(entry.name) !== '.md') continue
+      const candidate = path.join(directory, entry.name)
+      if (candidate === file) continue
+      let data
+      try {
+        data = fs.readFileSync(candidate)
+      } catch {
+        continue
+      }
+      const candidateName = frontmatterName(data)
+      if (!candidateName || candidateName !== desiredName) continue
+      if (force) {
+        process.stderr.write(`aviso: ${candidate} declara o mesmo name ${desiredName} que ${file}; prosseguindo por --force\n`)
+        continue
+      }
+      throw new Error(`artifact ${file} declares name ${desiredName} which collides with existing file ${candidate}`)
+    }
+  }
+
   inspectResolved(plan, file, manifest) {
     const record = manifest.artifacts[file]
     const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))

package/src/integrations/render.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { lookup: lookupIdentity, agentName } = require('../identity')
+
 // Mapa de model: nomes canônicos do catálogo → tier aceito pelo Antigravity CLI (agy)
 const MODEL_MAP = { opus: 'pro', sonnet: 'flash' }
 // Valores que já são tiers válidos do agy e devem passar sem transformação
@@ -65,38 +67,171 @@ function resolveModel(model) {
   return MODEL_MAP[model] || ''
 }
 
-// toolsFor retorna SET_ARCH para agentes cujo nome termina em "architect", SET_IMPL para os demais.
-// IDs proibidos (edit_file, read_file, find, view_code_item, view_file_outline, call_mcp_tool)
-// nunca fazem parte de nenhum dos conjuntos.
-function toolsFor(name) {
-  return name.endsWith('architect') ? SET_ARCH : SET_IMPL
+// toolsFor retorna SET_ARCH para o agente canônico "architect" (item.id do
+// catálogo, não o nome renderizado — que pode ser customizado pela
+// identidade), SET_IMPL para os demais. IDs proibidos (edit_file, read_file,
+// find, view_code_item, view_file_outline, call_mcp_tool) nunca fazem parte
+// de nenhum dos conjuntos.
+function toolsFor(itemId) {
+  return itemId === 'architect' ? SET_ARCH : SET_IMPL
+}
+
+// greetingLine monta a primeira linha injetada no corpo do agente quando há
+// identidade configurada. Sem apelido configurado, apenas o display name do
+// agente é mencionado. Espelha internal/integrations/render.go:greetingLine.
+function greetingLine(displayName, nickname) {
+  if (!nickname) return `Você é ${displayName}.`
+  return `Você é ${displayName}. Trate o usuário como ${nickname}.`
+}
+
+// insertBodyPrefix insere prefix como a nova primeira linha da seção de
+// corpo de um markdown cru (frontmatter + corpo), seguida de linha em
+// branco. Se source não tiver frontmatter reconhecível, prefix é inserido no
+// topo. Reusa a mesma detecção de fronteira do frontmatter usada por
+// markdownParts, para que Rota A e Rota B concordem sobre onde o corpo
+// começa. Espelha internal/integrations/render.go:insertBodyPrefix.
+function insertBodyPrefix(source, prefix) {
+  const trimmed = String(source).trim()
+  if (!prefix) return trimmed
+  if (!trimmed.startsWith('---\n')) return `${prefix}\n\n${trimmed}`
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return `${prefix}\n\n${trimmed}`
+  const insertAt = end + 4
+  const head = trimmed.slice(0, insertAt)
+  const rest = trimmed.slice(insertAt).replace(/^\n+/, '')
+  if (rest === '') return `${head}\n\n${prefix}`
+  return `${head}\n\n${prefix}\n\n${rest}`
+}
+
+// rewriteFrontmatterFields substitui as linhas "name:" e "description:" do
+// frontmatter de um markdown cru por name e description, preservando toda
+// outra linha do frontmatter byte a byte (ordem, espaçamento, estilo de
+// aspas) e deixando o corpo intocado. Usado pela Rota B (o branch default de
+// render) para que representações que consomem o frontmatter cru —
+// principalmente "subagent" (claude, gemini, cursor, copilot, kiro-ide,
+// windsurf) — recebam a identidade customizada. Se o frontmatter não tiver
+// "name:" ou "description:", a chave é simplesmente deixada ausente — esta
+// função nunca inventa uma chave que não existia. Se source não tiver
+// frontmatter reconhecível, source é retornado sem alteração (trimado).
+// Espelha internal/integrations/render.go:rewriteFrontmatterFields.
+function rewriteFrontmatterFields(source, name, description) {
+  const trimmed = String(source).trim()
+  if (!trimmed.startsWith('---\n')) return trimmed
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return trimmed
+  const frontmatter = trimmed.slice(4, end)
+  const rest = trimmed.slice(end) // começa com "\n---", seguido do corpo
+
+  const lines = frontmatter.split('\n').map(line => {
+    const separator = line.indexOf(':')
+    if (separator < 0) return line
+    const key = line.slice(0, separator).trim()
+    let replacement
+    if (key === 'name') replacement = name
+    else if (key === 'description') replacement = description
+    else return line
+    const value = line.slice(separator + 1).trim()
+    const quoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"')
+    return quoted ? `${key}: "${replacement}"` : `${key}: ${replacement}`
+  })
+
+  return `---\n${lines.join('\n')}${rest}`
+}
+
+// frontmatterName extrai apenas o campo "name" de um frontmatter YAML
+// delimitado por ---, sem os valores default aplicados por markdownParts.
+// Retorna undefined quando o arquivo não tem frontmatter reconhecível ou não
+// declara "name". Usado pela detecção de colisão em manager.js. Espelha
+// internal/integrations/render.go:frontmatterName.
+function frontmatterName(content) {
+  const text = String(content).trim()
+  if (!text.startsWith('---\n')) return undefined
+  const end = text.indexOf('\n---', 4)
+  if (end < 0) return undefined
+  const frontmatter = text.slice(4, end)
+  for (const line of frontmatter.split('\n')) {
+    const separator = line.indexOf(':')
+    if (separator < 0) continue
+    const key = line.slice(0, separator).trim()
+    if (key !== 'name') continue
+    let value = line.slice(separator + 1).trim()
+    value = value.replace(/^"+/, '').replace(/"+$/, '')
+    if (value === '') return undefined
+    return value
+  }
+  return undefined
 }
 
-function render({ kind, content, capability }) {
+// render converte um item canônico do catálogo para a representação nativa
+// declarada por uma surface alvo. Quando identity carrega uma identidade
+// customizada para item.id, o name/description/body renderizados são
+// personalizados (ADR ADR-2026-07-25-identidade-personalizavel-de-agentes,
+// seções D1/D2/D6).
+//
+// render tem duas rotas de saída:
+//   - Rota A: "custom-agent-toml", "cli-agent-json", "agent-json" e
+//     "agent-directory" trabalham a partir de name/description/body já
+//     separados do frontmatter por markdownParts.
+//   - Rota B: o branch default, usado pela representação "subagent" (claude,
+//     gemini, cursor, copilot, kiro-ide, windsurf), retorna o source cru
+//     normalizado com o frontmatter ainda anexado. Quando há identidade
+//     configurada, suas linhas "name:"/"description:" são reescritas no
+//     lugar (ver rewriteFrontmatterFields) — necessário porque a seleção de
+//     subagent do Claude Code lê apenas o frontmatter, nunca o corpo.
+//
+// Ambas as rotas devem receber a injeção de identidade. Quando não há
+// identidade configurada para item.id, name/description/body ficam
+// exatamente como markdownParts produziu e o branch default retorna
+// normalize(content) — a mesma expressão usada antes de existir suporte a
+// identidade — então a saída sem identidade é garantida byte a byte
+// inalterada por construção, não por coincidência.
+function render({ kind, content, capability, item, identity: cfg }) {
   if (kind === 'skills') return normalize(content)
+
+  const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
   const parts = markdownParts(content)
+  let { name, description, body } = parts
+  let greeting = ''
+  if (id) {
+    greeting = greetingLine(id.display_name, (cfg && cfg.user_nickname) || '')
+    name = agentName(id.slug)
+    description = `${id.display_name} — ${description}`
+    body = `${greeting}\n\n${body}`
+  }
+
   if (capability.representation === 'custom-agent-toml') {
-    return `name = ${JSON.stringify(parts.name.replaceAll('-', '_'))}\ndescription = ${JSON.stringify(parts.description)}\ndeveloper_instructions = ${JSON.stringify(parts.body)}\n`
+    return `name = ${JSON.stringify(name.replaceAll('-', '_'))}\ndescription = ${JSON.stringify(description)}\ndeveloper_instructions = ${JSON.stringify(body)}\n`
   }
   if (capability.representation === 'cli-agent-json' || capability.representation === 'agent-json') {
-    return `${JSON.stringify({ name: parts.name, description: parts.description, prompt: parts.body }, null, 2)}\n`
+    // Ordem alfabética das chaves (description, name, prompt) é obrigatória:
+    // Go serializa via json.MarshalIndent(map[string]string{...}), cujo encoder
+    // ordena as chaves alfabeticamente, e Python usa sort_keys. JSON.stringify
+    // preserva a ordem de inserção, então a ordem é fixada aqui à mão. Sem
+    // isso, instalar por um CLI e listar por outro reporta falso `modified`
+    // (o manifest indexa artefatos por sha256 do conteúdo).
+    return `${JSON.stringify({ description, name, prompt: body }, null, 2)}\n`
   }
   if (capability.representation === 'agent-directory') {
     // Reconstrói o frontmatter para o Antigravity CLI (agy):
     // - mapeia model canônico para o tier aceito (opus→pro, sonnet→flash)
-    // - injeta tools: SET_IMPL ou SET_ARCH dependendo do nome do agente
+    // - injeta tools: SET_IMPL ou SET_ARCH dependendo do item.id (não do
+    //   nome renderizado, que pode ser customizado pela identidade)
     // - omite campos não suportados pelo agy
     const mappedModel = resolveModel(parts.model)
-    const tools = toolsFor(parts.name)
-    let out = `---\nname: ${parts.name}\ndescription: ${parts.description}\n`
+    const tools = toolsFor(item && item.id)
+    let out = `---\nname: ${name}\ndescription: ${description}\n`
     if (mappedModel) out += `model: ${mappedModel}\n`
     out += 'tools:\n'
     for (const tool of tools) out += `  - ${tool}\n`
     out += '---\n'
-    if (parts.body) out += `${parts.body}\n`
+    if (body) out += `${body}\n`
     return out
   }
-  return normalize(content)
+
+  if (!id) return normalize(content)
+  const withBody = insertBodyPrefix(content, greeting)
+  const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)
+  return normalize(withFrontmatter)
 }
 
-module.exports = { render, markdownParts }
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields }