forge-prefs

name	forge-prefs
description	Catálogo de preferências do forge-agent — todos os 87 knobs com estado/valor/camada/descrição, e um caminho de edição via forge-prefs-migrate.js --set.
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Bash

Input

$ARGUMENTS

---

O que este skill faz

Superfície completa do motor de preferências JSONC (M008): lista todos os 87 knobs do catálogo (forge-prefs.schema.json, 38 seções), cada um com:

• estado — ATIVO (usuário setou em alguma camada) ou desligado (default do schema)
• valor resolvido — o valor efetivo, ativo ou default
• camada de origem — global (~/.claude/), local (.gsd/), mixed, ou — (default)
• descrição — a linha do schema.description daquele knob (auto-didata, fonte única)

O motor real é scripts/forge-prefs-view.js (renderView(cwd) / buildCatalog(cwd) / CLI --view|--json). Este skill NUNCA reimplementa a leitura do schema, a resolução de camadas ou a escrita de catálogos — apenas invoca o helper e, na edição, delega a scripts/forge-prefs-migrate.js --set (primitivo block-preserving já testado em S05). Resolver o script: preferir scripts/forge-prefs-view.js do repo; se ausente, ~/.claude/scripts/forge-prefs-view.js.

---

Operações

Sem argumento, "show" ou "list"

Rode o helper e exiba a saída verbatim — não resuma, não reformate:

SCRIPT=$([ -f scripts/forge-prefs-view.js ] && echo scripts/forge-prefs-view.js || echo "$HOME/.claude/scripts/forge-prefs-view.js")
node "$SCRIPT" --cwd .

A saída já traz, nesta ordem: fonte de cada camada (jsonc / md-legacy — com aviso para migrar / absent), erros de parse (✗) e avisos de valor inválido (⚠) se houver, legenda ● ATIVO / ○ desligado, e o catálogo completo agrupado pelas 38 seções na ordem do schema.

Se layers.global.source == "md-legacy" ou layers.local.source == "md-legacy" na saída, mencione ao usuário que node scripts/forge-prefs-migrate.js --cwd . migra para JSONC sem risco de perda (gate resolvedDiff, round-trip provado).

---

"set <dotted.key> <value> [global|local]"

Exemplos válidos:

• /forge-prefs set review.rounds 2
• /forge-prefs set skip_research true local
• /forge-prefs set tier_models.heavy claude-opus-4-8[1m] global

Rota sempre pelo primitivo --set de forge-prefs-migrate.js — nunca edite um .jsonc/.md de preferências manualmente com Edit/Write:

MIGRATE=$([ -f scripts/forge-prefs-migrate.js ] && echo scripts/forge-prefs-migrate.js || echo "$HOME/.claude/scripts/forge-prefs-migrate.js")
node "$MIGRATE" --set "<dotted.key>=<value>" --cwd . [--layer global|local] [--create]

Regras:

• $schema é recusado. É metadata de tooling (o hook de referência do catálogo), não uma preferência. set $schema ... retorna erro ($schema é metadata de tooling, não pode ser setado como preferência) e não delega ao --set. No show, o $schema aparece com o marcador ◆ e a anotação "metadata de tooling — não é preferência" em vez de ATIVO/desligado.
• <value> é interpretado como JSON quando possível (true, 2, "texto", ["a","b"]); caso contrário cai para string literal. Passe o argumento do usuário sem aspas extras — o parser (parseSetExpression) já cobre isso.
• Camada: se o usuário não especificar, o primitivo escolhe local quando .gsd/ existe no projeto atual, senão global. Se o alvo for local e o catálogo ainda não existir, adicione --create (senão retorna local-create-required, sem escrever nada).
• --set falha com exit≠0 se a chave não existir no schema, se o valor violar type/enum, ou se a pós-verificação (getDottedValue no resolved final) não bater — nesses casos, mostre o stderr ao usuário e não afirme sucesso.

Após um --set bem-sucedido, re-rode o viewer para confirmar visualmente o novo estado (mesmo comando de "show" acima) e mostre apenas o knob alterado mais o header de camadas — não repita o catálogo inteiro na confirmação.

✓ review.rounds atualizado

  Antes: desligado (default: 1)
  Agora: ATIVO = 2   (camada: local)

---

"models" (compatibilidade retroativa — roteamento por fase legado)

Mantido do skill anterior a M008: alguns usuários ainda pensam em "modelo por fase" em vez de tier_models/routing. Trate como um atalho de leitura sobre o catálogo atual — não uma rota de escrita separada.

MODELOS DISPONÍVEIS NO CLAUDE CODE

  opus    claude-opus-4-8[1m] (fallback: claude-opus-4-7)
          Modelo mais capaz. Ideal para: discuss, research, plan, tier heavy/max.

  sonnet  claude-sonnet-5
          Modelo balanceado (padrão para execução). Ideal para: execute, complete, tier standard.

  haiku   claude-haiku-4-5-20251001
          Modelo mais rápido e barato. Ideal para: memory extraction, tier light.

Para mudar o modelo de um tier:
  /forge-prefs set tier_models.<tier> <alias ou model ID>

Exemplos:
  /forge-prefs set tier_models.heavy opus
  /forge-prefs set tier_models.standard claude-sonnet-5

"set <phase> <model>" (alias legado)

Fases válidas: discuss, research, plan, execute, complete, memory — mapeadas para o tier equivalente (ver shared/forge-tiers.md):

Fase legada	Tier equivalente
discuss, research, plan	heavy (ou max para plan-milestone)
execute	standard
complete	standard
memory	light

Converta o alias de modelo (opus/sonnet/haiku) para o model ID completo se necessário, e rode:

node "$MIGRATE" --set "tier_models.<tier>=<model-id>" --cwd . [--layer global|local] [--create]

Confirme:

✓ Fase 'execute' (tier standard) atualizada

  Antes: claude-sonnet-5
  Agora: claude-opus-4-8[1m]

Modelo não reconhecido (nem alias nem ID válido):

Modelo desconhecido: '{input}'

Modelos disponíveis:
  opus    → claude-opus-4-8[1m] (fallback claude-opus-4-7)
  sonnet  → claude-sonnet-5
  haiku   → claude-haiku-4-5-20251001

---

"reset"

Não existe um primitivo --reset no motor JSONC (M008): resetar significa remover as linhas ativas de um knob, voltando-o ao default do schema. Para o caso geral, oriente o usuário a editar o .jsonc da camada e recomentar a linha (prefixo // ) ou remover a entrada ativa duplicada. Não implemente um mutator de reset ad-hoc aqui — está fora do escopo deste skill (S06/T01); é um candidato de task futura em forge-prefs-migrate.js se houver demanda.

---

Referência completa

Para a lista longa (todos os 87 knobs, com tipo, enum, default e descrição completa, fora do contexto de uma sessão), aponte o usuário para shared/forge-prefs-reference.md (gerado por scripts/forge-prefs-reference.js, T03 deste slice) — é o documento de referência versionado, complementar ao /forge-prefs show interativo.

---

Notas de implementação (para quem editar este skill)

• Fonte única de verdade: forge-prefs.schema.json — nunca hardcode uma descrição, default ou lista de knobs aqui. O helper (forge-prefs-view.js) lê o schema em runtime; qualquer prosa fixa neste arquivo sobre "quais são os 87 knobs" ficaria desatualizada na primeira mudança de schema.
• Nunca escreva .jsonc/.md de preferências diretamente. Toda mutação passa por forge-prefs-migrate.js (setPreference/--set), que preserva blocos comentados existentes byte-a-byte e verifica o resultado antes de reportar sucesso.
• --resolved --explain (o CLI de forge-prefs.js) só retorna knobs ATIVOS — o viewer funde isso com loadSchema()/defaultsFromSchema() para mostrar o universo completo. Ver comentário no topo de scripts/forge-prefs-view.js.