trackfw 2.15.0 → 2.16.0

package/README.md

@@ -367,6 +367,179 @@ The 10 roles installed for each tool: **architect · backend · frontend · qa
 
 ---
 
+## Agent identity — give your agents a name
+
+By default the agents are functional and impersonal: `trackfw-architect`,
+`trackfw-backend`, … Agent identity lets you name all ten, pick how they
+address you, and call them by name.
+
+```bash
+# Non-interactive: pick a themed preset
+trackfw init --identity-preset greek
+
+# Or answer the wizard, which also offers "name them one by one"
+trackfw init
+```
+
+`--identity-preset` accepts ten themed presets plus two opt-outs:
+
+`greek` · `norse` · `potter` · `thrones` · `chaves` · `pioneers` · `starwars` · `tolkien` · `turma` · `egyptian` · `neutral` · `none`
+
+`neutral` and `none` write nothing and keep the current behavior.
+
+Sample mapping (three of the ten presets):
+
+| Agent | `greek` | `pioneers` | `tolkien` |
+|---|---|---|---|
+| architect | Zeus | Turing | Gandalf |
+| backend | Apolo | Ritchie | Aragorn |
+| frontend | Afrodite | Berners-Lee | Arwen |
+| qa | Ártemis | Hamilton | Legolas |
+| infra | Ares | Torvalds | Gimli |
+| security | Hades | Diffie | Boromir |
+| dba | Poseidon | Codd | Elrond |
+| ux | Atena | Norman | Galadriel |
+| code-quality | Hefesto | Knuth | Faramir |
+| data | Métis | Hopper | Bilbo |
+
+The remaining presets are `norse` (Odin, Thor, Freya…), `potter` (Dumbledore,
+Snape, Luna…), `thrones` (Tyrion, Jon, Arya…), `chaves` (Girafales, Madruga,
+Chiquinha…), `starwars` (Yoda, Han, Leia…), `turma` (Franjinha, Cebolinha,
+Magali…), and `egyptian` (Thoth, Rá, Ísis…).
+
+### Custom mode and your nickname
+
+The interactive wizard also offers **name them one by one**: you type all ten
+display names yourself. Each entry is validated as you go — an invalid name is
+rejected with an inline error, never silently corrected, and two names that
+resolve to the same identifier are rejected too.
+
+The wizard then asks for an optional **nickname for you**, which is how the
+agents will address you.
+
+### `agents install` also runs the wizard
+
+`trackfw init` is not the only entry point: `trackfw agents install`, the
+natural path in a project that is already governed, offers the same wizard.
+The rule is identical across the three CLIs — it appears **only** when
+**all** of the following hold:
+
+- the command is `agents` (never `skills`: skills have no identity);
+- stdin is a TTY (a non-interactive run never blocks on a prompt);
+- and either no `~/.trackfw/identity.json` exists yet, or `--identity` was
+  passed to force reconfiguration.
+
+With an identity already configured and no `--identity`, the command asks
+nothing — it prints `identity: N custom agent(s)` and installs directly.
+
+```bash
+# First run on this machine: offers the wizard, then installs
+trackfw agents install --targets claude
+
+# Identity already configured: no prompt, installs directly
+trackfw agents install --targets claude
+
+# Force reconfiguration
+trackfw agents install --targets claude --identity
+
+# Non-interactive, same semantics as init --identity-preset
+trackfw agents install --targets claude --identity-preset chaves
+```
+
+Two new flags exist only on `agents install` (`skills install` never
+registers them): `--identity` (bool, forces reconfiguration even if a file
+already exists) and `--identity-preset <preset>` (same ten themed presets
+plus `neutral` and `none`; an invalid value errors out listing the valid
+ones).
+
+In **name them one by one** mode, each field is now labeled by the agent's
+specialty, taken from the catalog, never by its technical id:
+
+```
+Architect — Architecture, ADRs and governed coordination
+> _
+```
+
+Before anything is written to disk — for a themed preset **or** for custom
+names — a confirmation screen lists all ten `specialty → name` pairs plus
+your nickname:
+
+```
+── Confirmation ──────────────────────────────
+  Architecture, ADRs and governed coordination   →  Girafales
+  Backend APIs, domain logic and integrations    →  Madruga
+  ...
+  What we'll call you:                              chefe
+
+? Confirm?
+```
+
+Answering no returns to preset selection; nothing is written until you
+confirm.
+
+Everything is stored in a single global file, shared by the Go, npm, and PyPI
+distributions:
+
+```json
+// ~/.trackfw/identity.json
+{
+  "schema_version": 1,
+  "user_nickname": "Kleber",
+  "agents": {
+    "architect": { "display_name": "Zeus", "slug": "zeus" }
+  }
+}
+```
+
+The generated artifact — still installed at the unchanged path
+`~/.claude/agents/trackfw-architect.md`:
+
+```markdown
+---
+name: zeus-tf
+description: Zeus — Principal software architect for system design, ADRs and governed multi-agent coordination.
+model: opus
+---
+
+Você é Zeus. Trate o usuário como Kleber.
+
+# Architect
+...
+```
+
+### Why the `-tf` suffix
+
+The `name` always ends in `-tf`. Two agents sharing the same `name` in the same
+directory make Claude Code load *"only one of them, chosen by filesystem read
+order rather than a documented precedence"* — a silent, non-deterministic
+shadowing that the user cannot detect. If you already keep a personal `zeus.md`
+agent, `zeus-tf` guarantees both survive.
+
+The suffix belongs to the technical identifier only. It never appears in how
+the agent presents itself: the `description` and the body both say **Zeus**.
+
+### How to invoke it
+
+| You type | What happens |
+|---|---|
+| `@agent-zeus-tf` | Works — explicit mention resolves against `name` |
+| "chame o Zeus" / "ask Zeus to…" | Works — natural-language routing reads `description` |
+| "quem é você?" | Answers "Sou Zeus" — the body is loaded after selection |
+
+### Cost and non-regression
+
+The agent **never reads the configuration at runtime**. Identity is
+materialized into the artifact at install time, so the per-interaction cost is
+essentially zero: the `description` is substituted rather than extended, and
+the body grows by tens of tokens that are loaded only after the agent has
+already been selected. No tool call, no file read, no permanent instruction.
+
+Without `~/.trackfw/identity.json`, the generated artifacts are **byte for byte
+identical** to the current ones in all three CLIs. The feature is opt-in and
+regresses nothing.
+
+---
+
 ## `trackfw init` — stack-aware scaffolding
 
 ```
@@ -377,6 +550,7 @@ The 10 roles installed for each tool: **architect · backend · frontend · qa
 ? Git hooks?             husky / lefthook / none
 ? CI system?             GitHub Actions / GitLab CI / none
 ? Which AI assistants?   Claude / Codex / Gemini / Antigravity / Cursor / Copilot / Windsurf / Amazon Q / Kiro
+? Agent identity?        Greek / Norse / Potter / Thrones / Chaves / Pioneers / Star Wars / Tolkien / Turma / Egyptian / Name them one by one / Neutral
 ```
 
 The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",

package/src/commands/identity-wizard.js

@@ -0,0 +1,258 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const identityStore = require('../identity')
+const { t } = require('../i18n')
+
+// identityFileExists reporta se ~/.trackfw/identity.json já existe, sem
+// depender de identityStore.load (que retorna config vazia para "ausente").
+// Espelha internal/commands/init.go:identityFileExists.
+function identityFileExists(home) {
+  return fs.existsSync(path.join(home, '.trackfw', 'identity.json'))
+}
+
+// resolveIdentityPreset traduz o valor da flag --identity-preset para uma
+// Config a persistir. "none" e "neutral" significam "não gravar nada" — o
+// chamador não deve criar ~/.trackfw/identity.json para esses valores. Um
+// valor desconhecido é sempre um erro, listando os valores aceitos. Espelha
+// internal/commands/init.go:resolveIdentityPreset.
+function resolveIdentityPreset(value) {
+  if (value === 'none' || value === 'neutral') return { cfg: null, shouldSave: false }
+  let cfg
+  try {
+    cfg = identityStore.preset(value)
+  } catch {
+    const valid = ['none', 'neutral', ...identityStore.presetNames()]
+    throw new Error(`identity-preset invalido "${value}" (validos: ${valid.join(', ')})`)
+  }
+  return { cfg, shouldSave: true }
+}
+
+// applyIdentityPresetFlag resolve e persiste --identity-preset para
+// `agents install|update|uninstall`, reusando resolveIdentityPreset para que
+// ambos os comandos aceitem exatamente os mesmos nomes de preset e rejeitem
+// valores inválidos com o mesmo formato de erro. Espelha
+// internal/commands/integrations_flags.go:applyIdentityPresetFlag.
+function applyIdentityPresetFlag(home, presetValue, operation) {
+  const { cfg, shouldSave } = resolveIdentityPreset(presetValue)
+  if (!shouldSave) return
+  try {
+    identityStore.validate(cfg, identityStore.knownAgentIds())
+  } catch (err) {
+    throw new Error(`${operation}: identidade invalida: ${err.message}`)
+  }
+  try {
+    identityStore.save(home, cfg)
+  } catch (err) {
+    throw new Error(`${operation}: falha ao gravar identidade: ${err.message}`)
+  }
+}
+
+// shouldPromptIdentity decide se `trackfw agents install` (e as operações
+// update/uninstall, que compartilham o mesmo fluxo) deve mostrar o wizard
+// interativo de identidade. Todas as condições devem valer simultaneamente
+// (ADR D2):
+//
+//  1. kind é "agents" — skills não têm identidade e nunca devem perguntar.
+//  2. stdin é um TTY — nunca bloquear uma execução não-interativa.
+//  3. ou não há identidade configurada ainda, ou o usuário pediu
+//     explicitamente para reconfigurá-la via --identity.
+//
+// Com uma identidade já configurada e sem a flag --identity, o wizard NÃO
+// deve reaparecer — um wizard que aparece a cada install vira incentivo a
+// automatizar o "pular", o que esvazia a feature. Espelha
+// internal/commands/identity_wizard.go:shouldPromptIdentity.
+function shouldPromptIdentity(kind, isTTY, identityExists, forceFlag) {
+  if (kind !== 'agents') return false
+  if (!isTTY) return false
+  return !identityExists || Boolean(forceFlag)
+}
+
+// identityPresetOptions é a lista fixa de presets temáticos de identidade
+// oferecidos pelo wizard, compartilhada literalmente entre init e agents
+// install para que nenhum consumidor divirja do outro. Espelha
+// internal/commands/identity_wizard.go:identityPresetOptions.
+function identityPresetOptions() {
+  return [
+    { name: 'Panteão grego (Zeus, Apolo, Afrodite...)', value: 'greek' },
+    { name: 'Mitologia nórdica (Odin, Thor, Freya...)', value: 'norse' },
+    { name: 'Pioneiros da computação (Turing, Codd, Knuth...)', value: 'pioneers' },
+    { name: 'Harry Potter (Dumbledore, Snape, Luna...)', value: 'potter' },
+    { name: 'Game of Thrones (Tyrion, Jon, Arya...)', value: 'thrones' },
+    { name: 'Senhor dos Anéis (Gandalf, Aragorn, Arwen...)', value: 'tolkien' },
+    { name: 'Star Wars (Yoda, Leia, Vader...)', value: 'starwars' },
+    { name: 'Chaves (Girafales, Madruga, Chiquinha...)', value: 'chaves' },
+    { name: 'Turma da Mônica (Franjinha, Cebolinha, Mônica...)', value: 'turma' },
+    { name: 'Panteão egípcio (Thoth, Ísis, Anúbis...)', value: 'egyptian' },
+    { name: 'Personalizar um a um', value: 'custom' },
+    { name: 'Nomes neutros (padrão)', value: 'neutral' },
+  ]
+}
+
+// catalogAgentItem busca o item "agents" do catálogo pelo id. Todo id vindo
+// de identity.knownAgentIds() deve existir no catálogo embedado — se não
+// existir, é erro de programação: falha alto em vez de rotular
+// silenciosamente errado. Espelha o panic em
+// internal/commands/identity_wizard.go:buildCustomIdentityGroup.
+function catalogAgentItem(catalog, id) {
+  const found = (catalog.agents || []).find(entry => entry.id === id)
+  if (!found) {
+    throw new Error(`identity wizard: agent id "${id}" from identity.knownAgentIds() has no entry in the agents catalog`)
+  }
+  return found
+}
+
+// buildIdentityConfig constrói a Config em memória para o caminho escolhido
+// no wizard, sem tocar em disco. Espelha
+// internal/commands/identity_wizard.go:buildIdentityConfig.
+function buildIdentityConfig(identitySelect, knownAgentIds, customDisplayNames, userNickname) {
+  let cfg
+  if (identitySelect === 'custom') {
+    const agents = {}
+    knownAgentIds.forEach((id, index) => {
+      let slug
+      try {
+        slug = identityStore.slugify(customDisplayNames[index])
+      } catch (err) {
+        throw new Error(`identidade customizada invalida para "${id}": ${err.message}`)
+      }
+      agents[id] = { display_name: customDisplayNames[index], slug }
+    })
+    cfg = { agents }
+  } else {
+    cfg = identityStore.preset(identitySelect)
+  }
+  cfg.user_nickname = userNickname
+  return cfg
+}
+
+// promptCustomNames pede um nome de exibição para cada agente conhecido,
+// rotulado com a especialidade do catálogo (Item.name + Item.description) —
+// nunca com o id técnico cru (ADR D4). Espelha
+// internal/commands/identity_wizard.go:buildCustomIdentityGroup.
+async function promptCustomNames(catalog, knownAgentIds, prompts) {
+  const { input } = prompts
+  const helperText = t('init.prompt.identityCustomName')
+  const customDisplayNames = []
+  for (const id of knownAgentIds) {
+    const item = catalogAgentItem(catalog, id)
+    const label = `${item.name} — ${item.description}`
+    // eslint-disable-next-line no-await-in-loop
+    const value = await input({
+      message: `${label}\n  ${helperText}`,
+      validate: candidate => {
+        let slug
+        try {
+          slug = identityStore.slugify(candidate)
+        } catch (err) {
+          return err.message
+        }
+        for (let index = 0; index < customDisplayNames.length; index += 1) {
+          let otherSlug
+          try {
+            otherSlug = identityStore.slugify(customDisplayNames[index])
+          } catch {
+            continue
+          }
+          if (otherSlug === slug) return `slug "${slug}" duplicado com o agente "${knownAgentIds[index]}"`
+        }
+        return true
+      },
+    })
+    customDisplayNames.push(value)
+  }
+  return customDisplayNames
+}
+
+// confirmIdentitySelection exibe o mapeamento especialidade → nome de
+// exibição (ADR D3) e pede confirmação. O mapeamento é impresso com
+// console.log simples (não por um campo de prompt) para que o alinhamento
+// de colunas siga exatamente o exemplo do ADR. Espelha
+// internal/commands/identity_wizard.go:confirmIdentitySelection.
+async function confirmIdentitySelection(catalog, knownAgentIds, cfg, prompts) {
+  const { confirm } = prompts
+  const nicknameLabel = t('identity.wizard.nicknameRowLabel')
+  let labelWidth = nicknameLabel.length
+  const labels = knownAgentIds.map(id => {
+    const item = catalogAgentItem(catalog, id)
+    if (item.description.length > labelWidth) labelWidth = item.description.length
+    return item.description
+  })
+
+  console.log()
+  console.log(t('identity.wizard.confirmHeader'))
+  knownAgentIds.forEach((id, index) => {
+    const agent = cfg.agents[id]
+    console.log(`  ${labels[index].padEnd(labelWidth)}   →  ${agent.display_name}`)
+  })
+  if (cfg.user_nickname) {
+    console.log(`  ${nicknameLabel.padEnd(labelWidth)}   ${cfg.user_nickname}`)
+  }
+  console.log()
+
+  return confirm({ message: t('identity.wizard.confirmQuestion') })
+}
+
+// runIdentityWizard é o único wizard interativo de identidade, consumido
+// tanto por `trackfw init` quanto por `trackfw agents install`
+// (ADR-2026-07-25-wizard-unificado-de-identidade-no-agents-install, D1).
+//
+// Mostra, em ordem: seleção de preset/custom, nomes livres em texto (só no
+// modo custom), o apelido do usuário e uma tela de confirmação (D3, D6). Se
+// o usuário recusar a confirmação, o wizard volta à seleção de preset sem
+// persistir nada — nunca retorna tendo gravado uma config parcial ou
+// recusada em disco.
+//
+// Retorna [cfg, persisted]. "neutral" (ou deixar o select vazio) é o
+// caminho "não gravar nada" e retorna [{}, false].
+async function runIdentityWizard(catalog, home, prompts = require('@inquirer/prompts')) {
+  const { select, input } = prompts
+  const knownAgentIds = identityStore.knownAgentIds()
+
+  const titleIdentityPreset = t('init.prompt.identityPreset')
+  const titleIdentityNickname = t('init.prompt.identityNickname')
+
+  for (;;) {
+    const identitySelect = await select({
+      message: titleIdentityPreset,
+      choices: identityPresetOptions(),
+    })
+
+    if (identitySelect === '' || identitySelect === 'neutral') {
+      return [{}, false]
+    }
+
+    let customDisplayNames = []
+    if (identitySelect === 'custom') {
+      customDisplayNames = await promptCustomNames(catalog, knownAgentIds, prompts)
+    }
+
+    const userNickname = await input({ message: titleIdentityNickname, default: '' })
+
+    const cfg = buildIdentityConfig(identitySelect, knownAgentIds, customDisplayNames, userNickname)
+    identityStore.validate(cfg, knownAgentIds)
+
+    // eslint-disable-next-line no-await-in-loop
+    const confirmed = await confirmIdentitySelection(catalog, knownAgentIds, cfg, prompts)
+    if (!confirmed) {
+      // D3: recusar volta à seleção de preset sem persistir absolutamente nada.
+      continue
+    }
+
+    identityStore.save(home, cfg)
+    return [cfg, true]
+  }
+}
+
+module.exports = {
+  identityFileExists,
+  resolveIdentityPreset,
+  applyIdentityPresetFlag,
+  shouldPromptIdentity,
+  identityPresetOptions,
+  buildIdentityConfig,
+  confirmIdentitySelection,
+  runIdentityWizard,
+}

package/src/commands/init.js

@@ -1,14 +1,39 @@
 'use strict'
 const { Command } = require('commander')
 const { t } = require('../i18n')
+const identityStore = require('../identity')
+const identityWizard = require('./identity-wizard')
+const { resolveIdentityPreset, identityFileExists } = identityWizard
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
 cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,kiro)', '')
-cmd.action(async (options) => {
+cmd.option('--identity-preset <preset>', `Agent identity preset: none, neutral, ${identityStore.presetNames().join(', ')}`, 'none')
+cmd.action(async (options, command) => {
+  const os = require('os')
   const path = require('path')
   const generators = require('../generators/init')
 
+  const home = os.homedir()
+
+  // A validação e persistência da flag acontecem incondicionalmente, acima
+  // do early-return não-TTY abaixo — é isso que faz um --identity-preset
+  // inválido falhar alto em CI em vez de silenciosamente não fazer nada.
+  const presetChanged = command.getOptionValueSource('identityPreset') === 'cli'
+  if (presetChanged) {
+    const { cfg, shouldSave } = resolveIdentityPreset(options.identityPreset)
+    if (shouldSave) {
+      identityStore.validate(cfg, identityStore.knownAgentIds())
+      identityStore.save(home, cfg)
+    }
+  }
+
+  // Pula o wizard de identidade inteiramente quando a flag foi passada
+  // explicitamente (já tratado acima) ou quando um arquivo de identidade já
+  // existe — re-executar init nunca deve sobrescrever silenciosamente uma
+  // identidade já configurada.
+  const skipIdentityWizard = presetChanged || identityFileExists(home)
+
   // Modo não-TTY: usar defaults e chamar scaffold diretamente
   if (!process.stdin.isTTY) {
     const cfg = {
@@ -158,6 +183,7 @@ cmd.action(async (options) => {
         { name: 'Kiro', value: 'kiro' },
       ],
     })
+
   } catch (err) {
     // Fallback quando stdin fecha inesperadamente (ex: pipe em TTY simulado)
     const cfg = {
@@ -175,6 +201,33 @@ cmd.action(async (options) => {
     return
   }
 
+  // O wizard de identidade roda como seu próprio formulário, logo após o
+  // formulário principal — o mesmo componente compartilhado (ADR D1) usado
+  // por `agents install`. É pulado inteiramente (nenhuma pergunta) quando a
+  // flag já resolveu a identidade acima, ou quando um arquivo de identidade
+  // já existe.
+  if (!skipIdentityWizard) {
+    const { catalog } = require('../integrations')
+    try {
+      await identityWizard.runIdentityWizard(catalog, home)
+    } catch {
+      // Fallback quando stdin fecha inesperadamente durante o wizard de
+      // identidade (mesma tolerância aplicada ao formulário principal acima).
+      await generators.scaffold({
+        projectName: path.basename(process.cwd()),
+        projectType: 'governance',
+        frontend: '',
+        backend: '',
+        pkgManager: 'npm',
+        hooks: 'none',
+        ci: 'none',
+      })
+      console.log(`\n${t('init.success')}`)
+      require('../generators/init').printArchitectNextSteps(process.cwd())
+      return
+    }
+  }
+
   const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
   await generators.scaffold(cfg)
 

package/src/commands/integrations.js

@@ -1,7 +1,11 @@
 'use strict'
 
+const os = require('node:os')
 const { Command } = require('commander')
 const { catalog, execute, parseSurfaces } = require('../integrations')
+const identityStore = require('../identity')
+const identityWizard = require('./identity-wizard')
+const { t } = require('../i18n')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
@@ -39,6 +43,7 @@ async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquir
 function createLifecycleCommand(kind) {
   const root = new Command(kind).description(`Manage trackfw ${kind}`)
   for (const operation of ['list', 'install', 'uninstall', 'update']) {
+    const mutation = operation !== 'list'
     const command = new Command(operation)
       .option('--targets <targets>', 'Comma-separated target CLIs', csv)
       .option('--items <items>', `Comma-separated ${kind} IDs`, csv)
@@ -46,16 +51,67 @@ function createLifecycleCommand(kind) {
       .option('--surface <target=surface>', 'Surface selection (repeatable)', collect, [])
       .option('--json', 'Print deterministic JSON')
       .option('--force', 'Replace or remove modified artifacts')
-    command.action(async options => {
+
+    // Flags de identidade são exclusivas de agents (ADR D5): skills não têm
+    // identidade, e createLifecycleCommand é compartilhado entre `agents` e
+    // `skills` — sem este filtro por kind, `trackfw skills install
+    // --identity` aceitaria silenciosamente uma flag sem nenhum efeito.
+    // Espelha internal/commands/integrations_flags.go:addIntegrationFlags.
+    if (mutation && kind === 'agents') {
+      command
+        .option('--identity', 'Reconfigure agent identity even if ~/.trackfw/identity.json already exists')
+        .option('--identity-preset <preset>', `Agent identity preset (non-interactive): none, neutral, ${identityStore.presetNames().join(', ')}`)
+    }
+
+    command.action(async (options, cmd) => {
       options.surfaces = options.surface || []
       if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
-      const mutation = operation !== 'list'
+
+      // O booleano de --identity nunca deve chegar a execute()/buildPlans()
+      // sob a chave "identity" — essa chave ali é reservada para uma Config
+      // de identidade já resolvida (ver src/integrations/index.js:execute).
+      // Colidir os dois faria "agents install --identity" renderizar uma
+      // identidade booleana nos artefatos em vez da Config real.
+      const forceIdentity = options.identity === true
+      delete options.identity
+
+      // --identity-preset é validado e persistido incondicionalmente, acima
+      // de qualquer ramo dependente de TTY abaixo — isso é o que faz um
+      // --identity-preset inválido falhar alto em CI em vez de
+      // silenciosamente não fazer nada. Espelha init.js e
+      // internal/commands/integrations_flags.go:executeIntegrationMutation.
+      let presetChanged = false
+      if (mutation && kind === 'agents') {
+        presetChanged = cmd.getOptionValueSource('identityPreset') === 'cli'
+        if (presetChanged) identityWizard.applyIdentityPresetFlag(os.homedir(), options.identityPreset, operation)
+      }
+
       if (mutation && (!options.targets || !options.targets.length)) {
         if (!process.stdin.isTTY) throw new Error(`${operation} requires --targets in non-interactive mode`)
         await promptSelection(kind, options)
       }
       if (mutation && process.stdin.isTTY) await promptAmbiguousSurfaces(kind, options)
       options.allSurfaces = operation === 'list'
+
+      // Disparo do wizard de identidade (ADR D2): mostrado somente quando o
+      // caminho da flag acima ainda não resolveu a identidade desta
+      // execução, e somente para agents (nunca skills, D5). Roda depois da
+      // seleção de alvo/superfície e antes de execute() para que a
+      // identidade recém-gravada pelo wizard seja a que é renderizada nos
+      // planos abaixo. Espelha
+      // internal/commands/integrations_flags.go:executeIntegrationMutation.
+      if (mutation && kind === 'agents' && !presetChanged) {
+        const homeRoot = os.homedir()
+        const identityExists = identityWizard.identityFileExists(homeRoot)
+        const isTTY = Boolean(process.stdin.isTTY)
+        if (identityWizard.shouldPromptIdentity(kind, isTTY, identityExists, forceIdentity)) {
+          await identityWizard.runIdentityWizard(catalog, homeRoot)
+        } else if (identityExists && !options.json) {
+          const existing = identityStore.load(homeRoot)
+          console.log(t('identity.inUse', { count: String(Object.keys(existing.agents || {}).length) }))
+        }
+      }
+
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })

package/src/commands/update.js

@@ -2,7 +2,9 @@
 
 const { Command } = require('commander');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const identityStore = require('../identity');
 
 function readUpdateConfig(rootDir) {
   const yaml = path.join(rootDir, 'trackfw.yaml');
@@ -62,6 +64,11 @@ cmd.action(() => {
   const generators = require('../generators/init');
   const discover = require('./discover');
 
+  // A identidade é carregada uma única vez, fora de qualquer try/catch —
+  // um identity.json corrompido deve abortar o comando inteiro, nunca cair
+  // silenciosamente para os nomes neutros default.
+  const identityConfig = identityStore.load(os.homedir());
+
   console.log('trackfw update — re-aplicando templates atuais...\n');
 
   // 1. Agent rules (marker-delimited, idempotent)
@@ -77,7 +84,7 @@ cmd.action(() => {
       const roots = { projectRoot: cwd };
       const manager = new IntegrationManager(roots);
       for (const kind of ['agents', 'skills']) {
-        const plans = buildPlans(kind, { targets: ['codex'], scope: 'project' });
+        const plans = buildPlans(kind, { targets: ['codex'], scope: 'project', identity: identityConfig });
         const statuses = manager.inspect(plans);
         const existing = plans.filter((_, index) => statuses[index].state !== 'not-installed');
         manager.update(existing);

package/src/i18n/locales/en-US.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Frontend only",
       "projectType_backend": "Backend only",
-      "projectType_governance": "Governance only (no build stack)"
+      "projectType_governance": "Governance only (no build stack)",
+      "identityPreset": "How would you like to name your agents?",
+      "identityCustomName": "Display name for the agent",
+      "identityNickname": "What should we call you? (optional)"
     },
     "success": "✓ trackfw initialized — run 'trackfw status' to see your governance state."
   },
+  "identity": {
+    "inUse": "identity: {{count}} custom agent(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmation ──────────────────────────────",
+      "confirmQuestion": "Confirm?",
+      "nicknameRowLabel": "What we'll call you:"
+    }
+  },
   "adr": {
     "description": "Manage Architecture Decision Records",
     "new": {