@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/catalog.json

@@ -7,69 +7,43 @@
   },
   "master": {
     "id": "harness",
-    "file": "commands/harness.md",
-    "title": "/harness (comando-mestre)",
-    "description": "Conduz a sequência de setup em ordem: validar-ideia → gerar-spec → gerar-claude-md → nova-tarefa → scaffold → executar-plan.",
-    "requires": [
-      "validar-ideia",
-      "gerar-spec",
-      "gerar-claude-md",
-      "gerar-ignore",
-      "nova-tarefa",
-      "scaffold",
-      "configurar-comentarios",
-      "criar-skill",
-      "criar-agents",
-      "criar-code-reviewer",
-      "criar-rules",
-      "criar-hooks",
-      "configurar-orquestrador",
-      "executar-plan"
-    ]
+    "skill": "skills/harness",
+    "title": "/harness (setup guiado)",
+    "description": "Conduz o setup do harness em etapas (ideia, contexto, ignores, plano do start, scaffold, peças do harness, auto-tag e execução), validando entre elas; /harness <etapa> roda uma etapa isolada.",
+    "requires": ["sincronizar-claude-md", "nova-tarefa", "evoluir-harness", "executar-plan"],
+    "replaces": ["validar-ideia", "gerar-ignore", "scaffold", "configurar-auto-tag"]
   },
+  "agents": [
+    { "id": "auditor-plano", "file": "agents/auditor-plano.md", "title": "Agent auditor-plano", "description": "Audita o PLAN.md antes da execução: dependências, paralelismo, testes críticos e critérios binários." },
+    { "id": "investigador", "file": "agents/investigador.md", "title": "Agent investigador", "description": "Investiga a causa raiz de um bug antes da correção, com evidência." },
+    { "id": "qa", "file": "agents/qa.md", "title": "Agent qa", "description": "Valida critérios de aceite e roda a suíte completa antes do gate." },
+    { "id": "revisor-testes", "file": "agents/revisor-testes.md", "title": "Agent revisor-testes", "description": "Verifica se cada teste crítico falharia com a implementação errada." }
+  ],
   "skills": [
     { "id": "lgpd-checker", "dir": "skills/lgpd-checker", "title": "Skill lgpd-checker", "description": "Conformidade com a LGPD (Lei nº 13.709/2018) em 11 categorias, com checklist e template de relatório. Vendorizada de bittencourtthulio/lgpd-checker." }
   ],
   "groups": [
     {
       "id": "setup",
-      "title": "Setup inicial",
+      "title": "Setup e contexto",
       "commands": [
-        { "id": "validar-ideia", "file": "commands/validar-ideia.md", "title": "/validar-ideia", "description": "Valida se a ideia cabe em ~4h com multi-agents (entrevista + veredito).", "recommended": true },
-        { "id": "gerar-spec", "file": "commands/gerar-spec.md", "title": "/gerar-spec", "description": "Entrevista de requisitos e gera o SPEC.md principal na raiz.", "recommended": true },
-        { "id": "gerar-claude-md", "file": "commands/gerar-claude-md.md", "title": "/gerar-claude-md", "description": "Gera o CLAUDE.md (context file) a partir do SPEC.md.", "recommended": true },
-        { "id": "gerar-ignore", "file": "commands/gerar-ignore.md", "title": "/gerar-ignore", "description": "Gera .claudeignore e .gitignore conforme a stack.", "recommended": false },
-        { "id": "scaffold", "file": "commands/scaffold.md", "title": "/scaffold", "description": "Cria a estrutura inicial do projeto (pastas, configs, /health, testes de smoke).", "recommended": true }
+        { "id": "sincronizar-claude-md", "file": "commands/sincronizar-claude-md.md", "title": "/sincronizar-claude-md", "description": "Gera o SPEC.md e o CLAUDE.md que faltam e reconcilia os existentes com o código e os agents do projeto, inclusive a seção de orquestração.", "recommended": true, "replaces": ["gerar-spec", "gerar-claude-md", "configurar-orquestrador"] },
+        { "id": "evoluir-harness", "skill": "skills/evoluir-harness", "title": "/evoluir-harness", "description": "Audita a pasta .claude e cria agents, skills, rules, hooks, code-reviewer e design system do projeto.", "recommended": true, "replaces": ["criar-agents", "criar-skill", "criar-rules", "criar-hooks", "criar-code-reviewer", "design-system", "validar-commands"] }
       ]
     },
     {
       "id": "orquestracao",
       "title": "Orquestração & implementação",
       "commands": [
-        { "id": "executar-plan", "file": "commands/executar-plan.md", "title": "/executar-plan", "description": "Orquestra a execução do plano com sub-agents em paralelo, fase a fase.", "recommended": true },
-        { "id": "configurar-orquestrador", "file": "commands/configurar-orquestrador.md", "title": "/configurar-orquestrador", "description": "Configura o agente orquestrador de sub-agents no CLAUDE.md.", "recommended": false },
-        { "id": "corrigir-review", "file": "commands/corrigir-review.md", "title": "/corrigir-review", "description": "Organiza correções do review em sprints/fases/tasks com TDD e delega.", "recommended": false },
-        { "id": "review-por-task", "file": "commands/review-por-task.md", "title": "/review-por-task", "description": "Enforça implementação → review isolado → correção em cada task.", "recommended": false }
-      ]
-    },
-    {
-      "id": "harness",
-      "title": "Harness (agents/skills/hooks/rules)",
-      "commands": [
-        { "id": "criar-skill", "file": "commands/criar-skill.md", "title": "/criar-skill", "description": "Sugere e cria skills do projeto em .claude/skills/.", "recommended": false },
-        { "id": "criar-agents", "file": "commands/criar-agents.md", "title": "/criar-agents", "description": "Cria agents especializados em .claude/agents/ a partir do plano.", "recommended": false },
-        { "id": "criar-hooks", "file": "commands/criar-hooks.md", "title": "/criar-hooks", "description": "Cria hooks por agent em .claude/hooks/ conforme o escopo.", "recommended": false },
-        { "id": "criar-rules", "file": "commands/criar-rules.md", "title": "/criar-rules", "description": "Cria rules incondicionais e por path em .claude/rules/.", "recommended": false },
-        { "id": "configurar-comentarios", "file": "commands/configurar-comentarios.md", "title": "/configurar-comentarios", "description": "Instala o padrão de comentários (rule com orçamento, bloco no CLAUDE.md e hook bloqueante com catraca sobre o legado), inclusive Delphi/Pascal.", "recommended": true },
-        { "id": "criar-code-reviewer", "file": "commands/criar-code-reviewer.md", "title": "/criar-code-reviewer", "description": "Cria o agent code-reviewer (somente leitura) em .claude/agents/.", "recommended": true }
+        { "id": "executar-plan", "skill": "skills/executar-plan", "title": "/executar-plan", "description": "Executa o plano aprovado com sub-agents em paralelo, fase a fase, com gates de revisor-testes e qa, portões extras do projeto, bloqueios registrados e retomada.", "recommended": true, "replaces": ["review-por-task"] }
       ]
     },
     {
       "id": "dia-a-dia",
       "title": "Slash commands & dia a dia",
       "commands": [
-        { "id": "resolver-bug", "file": "commands/resolver-bug.md", "title": "/resolver-bug", "description": "Investiga, planeja em docs/bugs e corrige um bug passo a passo.", "recommended": true },
-        { "id": "nova-tarefa", "file": "commands/nova-tarefa.md", "title": "/nova-tarefa", "description": "Gera spec+plano em docs/ (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador.", "recommended": true }
+        { "id": "resolver-bug", "skill": "skills/resolver-bug", "title": "/resolver-bug", "description": "Investiga a causa raiz, corrige com teste de regressão e entrega relatório técnico e para o cliente.", "recommended": true },
+        { "id": "nova-tarefa", "skill": "skills/nova-tarefa", "title": "/nova-tarefa", "description": "Verifica se já existe, gera SPEC e PLAN do trabalho, audita o plano e, se confirmado, dispara a execução.", "recommended": true }
       ]
     },
     {
@@ -77,8 +51,7 @@
       "title": "Qualidade & manutenção de código",
       "commands": [
         { "id": "gerar-testes", "file": "commands/gerar-testes.md", "title": "/gerar-testes", "description": "Detecta cobertura faltante e escreve testes seguindo TDD (RED→GREEN).", "recommended": false },
-        { "id": "refatorar", "file": "commands/refatorar.md", "title": "/refatorar", "description": "Refatora um alvo usando os testes como rede de segurança, sem mudar comportamento.", "recommended": false },
-        { "id": "codigo-morto", "file": "commands/codigo-morto.md", "title": "/codigo-morto", "description": "Varre o projeto em busca de código morto e propõe remoção segura.", "recommended": false },
+        { "id": "refatorar", "file": "commands/refatorar.md", "title": "/refatorar", "description": "Refatora um alvo usando os testes como rede de segurança, sem mudar comportamento, inclusive a remoção de código morto.", "recommended": false, "replaces": ["codigo-morto"] },
         { "id": "atualizar-deps", "file": "commands/atualizar-deps.md", "title": "/atualizar-deps", "description": "Atualiza dependências em lotes, testando a cada passo e isolando o que quebra.", "recommended": false }
       ]
     },
@@ -86,7 +59,6 @@
       "id": "documentacao",
       "title": "Documentação & onboarding",
       "commands": [
-        { "id": "sincronizar-claude-md", "file": "commands/sincronizar-claude-md.md", "title": "/sincronizar-claude-md", "description": "Aponta onde o CLAUDE.md/SPEC.md divergiu do código, sem reescrever sozinho.", "recommended": false },
         { "id": "diagrama", "file": "commands/diagrama.md", "title": "/diagrama", "description": "Gera diagramas Mermaid de arquitetura/fluxo a partir do código.", "recommended": false },
         { "id": "onboarding", "file": "commands/onboarding.md", "title": "/onboarding", "description": "Gera um guia de onboarding (rodar, entender e contribuir) em docs/.", "recommended": false },
         { "id": "gerar-env", "file": "commands/gerar-env.md", "title": "/gerar-env", "description": "Monta o .env.example a partir das variáveis de ambiente lidas no código.", "recommended": false }
@@ -94,20 +66,12 @@
     },
     {
       "id": "avancado",
-      "title": "Avançado (RAG, UX, Design, Auditorias)",
-      "commands": [
-        { "id": "criar-rag", "file": "commands/criar-rag.md", "title": "/criar-rag", "description": "Cria um sistema de RAG (SQLite + sqlite-vec) para capturar aprendizados.", "recommended": false },
-        { "id": "auditar-ui", "file": "commands/auditar-ui.md", "title": "/auditar-ui", "description": "Navega a app via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y), por tela e severidade.", "recommended": false },
-        { "id": "design-system", "file": "commands/design-system.md", "title": "/design-system", "description": "Cria o agent de design system com skills e rules de identidade visual.", "recommended": false },
-        { "id": "auditar-performance", "file": "commands/auditar-performance.md", "title": "/auditar-performance", "description": "Audita gargalos de performance (queries, bundle, renders, algoritmos).", "recommended": false },
-        { "id": "auditar-seguranca", "file": "commands/auditar-seguranca.md", "title": "/auditar-seguranca", "description": "Auditoria defensiva: segredos, deps vulneráveis, inputs sem validação, configs e conformidade LGPD.", "recommended": false, "requiresSkills": ["lgpd-checker"] }
-      ]
-    },
-    {
-      "id": "manutencao",
-      "title": "Manutenção & validação",
+      "title": "Avançado (memória e auditorias)",
       "commands": [
-        { "id": "validar-commands", "file": "commands/validar-commands.md", "title": "/validar-commands", "description": "Audita .claude: valida modelos dos agents, aponta commands redundantes e sugere novos.", "recommended": false }
+        { "id": "memoria", "skill": "skills/memoria", "title": "/memoria", "description": "Mostra quem já mexeu num arquivo e por quê e aponta regressões candidatas de um bug.", "recommended": false },
+        { "id": "auditar-ui", "skill": "skills/auditar-ui", "title": "/auditar-ui", "description": "Navega a app via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y), por tela e severidade.", "recommended": false },
+        { "id": "auditar-performance", "skill": "skills/auditar-performance", "title": "/auditar-performance", "description": "Audita gargalos de performance (queries, bundle, renders, algoritmos).", "recommended": false },
+        { "id": "auditar-seguranca", "skill": "skills/auditar-seguranca", "title": "/auditar-seguranca", "description": "Auditoria defensiva: segredos, deps vulneráveis, inputs sem validação, configs e conformidade LGPD.", "recommended": false, "requiresSkills": ["lgpd-checker"] }
       ]
     },
     {
@@ -116,8 +80,7 @@
       "commands": [
         { "id": "git-commit-push", "file": "commands/git-commit-push.md", "title": "/git-commit-push", "description": "Gera mensagem e executa git add/commit/push em PT-BR.", "recommended": true },
         { "id": "versao", "file": "commands/versao.md", "title": "/versao", "description": "Detecta o versionamento do projeto (qualquer stack) e aplica o bump de versão + changelog (autossuficiente), com gate de aprovação e sem push.", "recommended": true },
-        { "id": "configurar-auto-tag", "file": "commands/configurar-auto-tag.md", "title": "/configurar-auto-tag", "description": "Detecta o padrão de versionamento (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na main.", "recommended": true },
-        { "id": "revisar-pr", "file": "commands/revisar-pr.md", "title": "/revisar-pr", "description": "Revisa um PR ou o diff atual, classificando em BLOQUEANTE/IMPORTANTE/SUGESTÃO.", "recommended": false }
+        { "id": "revisar-pr", "file": "commands/revisar-pr.md", "title": "/revisar-pr", "description": "Revisa um PR ou o diff atual em BLOQUEANTE/IMPORTANTE/SUGESTÃO e, se pedido, organiza as correções num trabalho com teste de regressão.", "recommended": false, "replaces": ["corrigir-review"] }
       ]
     }
   ]

package/templates/commands/atualizar-deps.md

@@ -1,15 +1,49 @@
 ---
-description: Atualiza dependências em lotes, rodando testes a cada passo e isolando o que quebra.
+description: Atualiza dependências em lotes (patch, minor e major), rodando build e testes a cada passo e isolando o pacote que quebra.
+argument-hint: "[pacote específico ou 'tudo']"
 ---
 
-# Atualização segura de dependências
+# /atualizar-deps — Atualização segura de dependências
 
-Alvo (opcional — pacote específico ou "tudo"): $ARGUMENTS
+Alvo: $ARGUMENTS
 
-Passos:
+> **🚦 Há um GATE de aprovação** antes de alterar qualquer arquivo de dependências. Este comando **não faz commit
+> nem push**.
 
-1. Detecte o gerenciador de pacotes do projeto (npm/pnpm/yarn, pip/poetry, go, cargo, maven, etc.) e liste as dependências **desatualizadas**, separando **patch**, **minor** e **major**.
-2. Garanta um baseline verde: rode build e testes **antes** de qualquer mudança. Se já estiver vermelho, **pare e me avise**.
-3. Atualize em lotes, do mais seguro ao mais arriscado: primeiro **patch**, depois **minor**, por último **major** (um de cada vez). Após cada lote, rode build + testes.
-4. Se um lote quebrar, **isole o pacote culpado**, reverta-o e siga com o resto. Para cada **major**, consulte o changelog/breaking changes antes (use o Context7 quando útil).
-5. **Não faça commit nem push** sem minha confirmação. Ao final, reporte: o que foi atualizado, o que foi segurado e por quê, e o estado da suíte.
+## Passo 0 — Pré-checagem (somente leitura)
+
+1. Detecte o gerenciador de pacotes (npm/pnpm/yarn, pip/poetry, dotnet, go, cargo, maven...) e o arquivo de lock.
+2. Liste as dependências **desatualizadas**, separando **patch**, **minor** e **major**
+   (`npm outdated`, `pip list --outdated`, `dotnet list package --outdated`...).
+3. Garanta um **baseline verde**: rode build e testes antes de qualquer mudança. Se já estiver vermelho, **pare e
+   avise** — atualizar sobre uma suíte quebrada esconde a causa das próximas falhas.
+
+## Passo 1 — Planejar os lotes
+
+- Ordem do mais seguro ao mais arriscado: **patch**, depois **minor**, por último cada **major** separadamente.
+- Para cada major, leia o changelog e as breaking changes (use o Context7 quando útil) e anote o que muda no
+  projeto.
+- Separe as dependências que também aparecem como vulneráveis: elas sobem de prioridade.
+
+## Passo 2 — 🚦 GATE de aprovação
+
+Mostre os lotes, o resumo das breaking changes de cada major e o que você propõe **segurar** (e por quê).
+**Peça aprovação explícita.**
+
+## Passo 3 — Aplicar lote a lote
+
+1. Aplique um lote e rode build e testes.
+2. Se quebrar, **isole o pacote culpado**, reverta-o e siga com o restante.
+3. Uma major que exige mudança de código só é migrada se a migração estiver no escopo aprovado no GATE.
+
+## Passo 4 — Relatório
+
+Informe o que foi atualizado, o que foi segurado e o motivo, e o estado final da suíte. Vulnerabilidades que
+continuaram abertas viram recomendação de `/auditar-seguranca`.
+
+## Guardrails
+
+- **Nunca** atualizar com o baseline vermelho nem aplicar várias majors de uma vez.
+- **Nunca** trocar o gerenciador de pacotes nem apagar o arquivo de lock.
+- **Nunca** fazer commit ou push por conta própria.
+- Conteúdo em **pt-BR**.

package/templates/commands/diagrama.md

@@ -1,17 +1,42 @@
 ---
-description: Gera diagramas Mermaid de arquitetura/fluxo a partir do código do projeto.
+description: Gera diagramas Mermaid fiéis ao código (arquitetura, fluxo, sequência, dados e estados) e salva em docs/diagramas/.
+argument-hint: "[visão: 'arquitetura geral', 'fluxo de login', 'modelo de dados']"
 ---
 
-# Geração de diagrama (Mermaid)
+# /diagrama — Diagrama Mermaid a partir do código
 
-O que diagramar (opcional — ex.: "arquitetura geral", "fluxo de login", "modelo de dados"): $ARGUMENTS
+Visão: $ARGUMENTS
 
-Se eu não especifiquei, me pergunte qual visão eu quero antes de gerar.
+> **🚦 Há um GATE de aprovação** antes de gravar o arquivo.
 
-Passos:
+## Passo 0 — Definir a visão
 
-1. Explore o código para entender a estrutura relevante (módulos, camadas, serviços, entidades, rotas, eventos) ao tema pedido.
-2. Gere um diagrama em **Mermaid**, escolhendo o tipo adequado: `flowchart` (arquitetura/fluxo), `sequenceDiagram` (interações), `erDiagram` (dados), `classDiagram` (modelo OO), `stateDiagram` (estados).
-3. Mantenha o diagrama **fiel ao código real**, não a uma versão idealizada. Use nomes reais de módulos/arquivos.
-4. Salve em `docs/diagramas/<slug>.md` (crie a pasta se necessário) com um título e um parágrafo curto explicando o que o diagrama mostra.
-5. Mostre o bloco Mermaid no chat e o caminho do arquivo salvo.
+Se a visão não veio nos argumentos, pergunte qual é antes de explorar o código.
+
+## Passo 1 — Explorar o código (somente leitura)
+
+Entenda a estrutura relevante para a visão pedida: módulos, camadas, serviços, entidades, rotas e eventos.
+
+## Passo 2 — Rascunhar o diagrama
+
+1. Escolha o tipo: `flowchart` (arquitetura ou fluxo), `sequenceDiagram` (interações), `erDiagram` (dados),
+   `classDiagram` (modelo orientado a objetos) ou `stateDiagram` (estados).
+2. Use os **nomes reais** de módulos, arquivos e tabelas — o diagrama retrata o código como ele é, não uma versão
+   idealizada.
+3. Mostre o bloco Mermaid no chat.
+
+## Passo 3 — 🚦 GATE de aprovação
+
+Confirme o diagrama e o caminho `docs/diagramas/<slug>.md`. Se já existir um diagrama da mesma visão, proponha
+atualizá-lo em vez de criar outro.
+
+## Passo 4 — Gravar
+
+Grave o arquivo com um título, um parágrafo curto explicando o que o diagrama mostra e o bloco Mermaid, e mostre o
+caminho salvo.
+
+## Guardrails
+
+- **Nunca** desenhar o que o código não faz; lacunas ficam explícitas no parágrafo.
+- **Nunca** alterar código neste comando.
+- Conteúdo em **pt-BR**.

package/templates/commands/gerar-env.md

@@ -1,16 +1,45 @@
 ---
-description: Monta o .env.example a partir das variáveis de ambiente realmente lidas no código.
+description: Monta o .env.example a partir das variáveis de ambiente realmente lidas no código, com placeholders seguros e as divergências da configuração atual.
+argument-hint: "[escopo opcional]"
 ---
 
-# Geração de .env.example
+# /gerar-env — .env.example fiel ao código
 
-Escopo (opcional): $ARGUMENTS
+Escopo: $ARGUMENTS
 
-Passos:
+> **🚦 Há um GATE de aprovação** antes de gravar o `.env.example`.
 
-1. Varra o código procurando todo acesso a variáveis de ambiente (`process.env.X`, `os.environ`, `os.getenv`, `Deno.env`, `System.getenv`, libs de config, etc.).
-2. Consolide a lista única de variáveis usadas, inferindo para cada uma: finalidade, se é obrigatória ou opcional e um valor de exemplo **seguro** (placeholder).
-3. **Nunca** copie segredos reais para o `.env.example` — use placeholders como `troque-me`, `sua-chave-aqui`. Se encontrar segredos hardcoded no código, **avise** como achado de segurança.
-4. Gere/atualize `.env.example` agrupando por contexto (banco, auth, integrações, etc.) com um comentário curto por variável.
-5. Compare com o `.env` atual (se existir e não estiver no git) e aponte variáveis usadas no código mas ausentes da config, e vice-versa.
-6. Garanta que `.env` está no `.gitignore`. Mostre o resultado e as divergências encontradas.
+## Passo 0 — Pré-checagem (somente leitura)
+
+Identifique a stack e as bibliotecas de configuração usadas (dotenv, configuração do framework, arquivos de
+settings).
+
+## Passo 1 — Varrer o código
+
+Encontre todo acesso a variáveis de ambiente: `process.env.X`, `os.environ`, `os.getenv`, `Deno.env`,
+`System.getenv`, `Environment.GetEnvironmentVariable` e as bibliotecas de configuração.
+
+## Passo 2 — Consolidar
+
+Para cada variável: finalidade, obrigatória ou opcional e um **placeholder seguro** (`troque-me`, `sua-chave-aqui`).
+Segredo escrito direto no código é **achado de segurança**: aponte a localização e sugira `/auditar-seguranca`.
+
+## Passo 3 — Comparar com a configuração atual
+
+Compare com o `.env.example` existente e com os **nomes** das variáveis do `.env` local, se houver: aponte o que o
+código usa e falta na configuração, e o que está configurado e ninguém usa.
+
+## Passo 4 — 🚦 GATE de aprovação
+
+Mostre o `.env.example` proposto, agrupado por contexto (banco, autenticação, integrações...), e as divergências.
+**Peça aprovação.**
+
+## Passo 5 — Gravar
+
+Grave o `.env.example` e garanta que `.env` está no `.gitignore`.
+
+## Guardrails
+
+- **Nunca** copiar valores reais para o `.env.example`, para o chat ou para relatórios — só nomes de variáveis.
+- O hook `segredo-no-commit` bloqueia o commit de `.env` com valores; não tente contorná-lo.
+- Conteúdo em **pt-BR**.

package/templates/commands/gerar-testes.md

@@ -1,17 +1,49 @@
 ---
-description: Detecta cobertura de testes faltante e escreve os testes seguindo TDD (RED→GREEN).
+description: Detecta cobertura de testes faltante e escreve testes com asserções fortes (pelo menos 2 por comportamento crítico), sem alterar o código de produção.
+argument-hint: "[arquivo, módulo ou pasta]"
 ---
 
-# Geração de testes
+# /gerar-testes — Testes para o que não está coberto
 
-Alvo (arquivo, módulo ou pasta): $ARGUMENTS
+Alvo: $ARGUMENTS
 
-Se eu não informei um alvo, primeiro liste os módulos com **menor cobertura ou sem testes** e me pergunte por onde começar.
+> **🚦 Há um GATE de aprovação** antes de gravar os testes.
 
-Passos:
+## Passo 0 — Pré-checagem (somente leitura)
 
-1. Leia o `CLAUDE.md` e o framework de testes já usado no projeto. **Não introduza um framework novo** sem me perguntar.
-2. Para o alvo, mapeie os comportamentos críticos, casos de borda e caminhos de erro que **não** estão cobertos hoje.
-3. Escreva os testes seguindo **TDD**: primeiro confirme que eles falham (**RED**) contra o estado atual quando fizer sentido; depois garanta que passam (**GREEN**). Mínimo de **2 testes críticos** por comportamento.
-4. **Não altere o código de produção** para fazer um teste passar, a menos que exista um bug evidente — nesse caso, **pare e me avise** antes.
-5. Ao final, rode a suíte e reporte: quantos testes foram criados, o que passou/falhou e qual a cobertura aproximada antes/depois.
+1. Leia o `CLAUDE.md` e identifique o framework de testes já usado. **Não introduza framework novo** sem perguntar.
+2. Sem alvo informado, liste os módulos com **menor cobertura ou sem testes** e pergunte por onde começar.
+3. Rode a suíte atual e anote o resultado (baseline).
+
+## Passo 1 — Mapear o que falta
+
+Para o alvo, liste os comportamentos críticos, os casos de borda e os caminhos de erro que **não** estão cobertos,
+com `arquivo:linha`.
+
+## Passo 2 — 🚦 GATE de aprovação
+
+Mostre os testes propostos (**pelo menos 2 por comportamento crítico**), onde cada um será criado e o que ele
+verifica. **Peça aprovação.**
+
+## Passo 3 — Escrever os testes
+
+1. Cada teste precisa **falhar se o comportamento mudar**: evite asserções fracas (só "não lança", só status 200) e
+   mocks que substituem justamente o que está sendo testado.
+2. Rode os testes novos e a suíte completa.
+3. Quando útil, peça ao agent `revisor-testes` (no plugin, `fontdata:revisor-testes`) que confira se os testes
+   passariam com uma implementação errada.
+
+## Passo 4 — Bug encontrado
+
+Se um teste revelar um defeito real, **pare**: não altere o código de produção. Mostre o teste que falha e sugira
+`/resolver-bug`.
+
+## Passo 5 — Relatório
+
+Quantos testes foram criados, o resultado da suíte e a cobertura aproximada antes e depois.
+
+## Guardrails
+
+- **Nunca** alterar o código de produção para fazer um teste passar.
+- **Nunca** introduzir framework ou dependência de teste sem aprovação.
+- Conteúdo em **pt-BR**.

package/templates/commands/onboarding.md

@@ -1,21 +1,50 @@
 ---
-description: Gera um guia de onboarding (como rodar, entender e contribuir) para um dev novo no projeto.
+description: Gera um guia de onboarding verificado (como rodar, entender e contribuir) em docs/ONBOARDING.md para quem chega no projeto.
+argument-hint: "[público: 'dev backend júnior', 'pessoa de QA'...]"
 ---
 
-# Guia de onboarding
+# /onboarding — Guia para quem chega
 
-Público-alvo (opcional — ex.: "dev backend júnior", "pessoa de QA"): $ARGUMENTS
+Público: $ARGUMENTS
 
-Passos:
+> **🚦 Há um GATE de aprovação** antes de gravar o guia.
 
-1. Leia o `CLAUDE.md`, o `SPEC.md` (se houver), os scripts do projeto e a estrutura de pastas.
-2. Monte um guia prático em `docs/ONBOARDING.md` cobrindo:
-   - **Visão geral** do que o projeto faz (1–2 parágrafos).
-   - **Pré-requisitos** e versões (linguagem, runtime, ferramentas).
-   - **Setup passo a passo** até rodar localmente (instalar, variáveis de ambiente, subir o app).
-   - **Como rodar testes** e o que o harness espera (TDD, gates).
-   - **Mapa do código**: principais pastas/módulos e o que cada um faz.
-   - **Fluxo de trabalho**: branches, commits semânticos, slash commands do dia a dia.
-   - **Onde pedir ajuda / armadilhas comuns**.
-3. Baseie tudo no estado **real** do projeto — confira que os comandos descritos realmente existem e funcionam. Não invente passos.
-4. Ao final, mostre o caminho do arquivo e um resumo do que foi documentado.
+## Passo 0 — Público
+
+Sem público nos argumentos, pergunte para quem é o guia: o nível de detalhe muda.
+
+## Passo 1 — Ler o projeto (somente leitura)
+
+`CLAUDE.md`, `SPEC.md`, scripts de build e teste, estrutura de pastas e os trabalhos recentes em `docs/trabalhos/`.
+
+## Passo 2 — Verificar os comandos
+
+Confira que os comandos que o guia vai citar **existem e funcionam** (build, testes, subir a aplicação). Não instale
+nada sem perguntar; comando que não funciona entra no guia como armadilha conhecida, não como passo.
+
+## Passo 3 — Rascunhar o guia
+
+Seções de `docs/ONBOARDING.md`:
+
+- **Visão geral** do que o projeto faz.
+- **Pré-requisitos** e versões.
+- **Setup passo a passo** até rodar localmente.
+- **Como rodar os testes** e o que o harness espera (TDD, gates).
+- **Mapa do código**: principais pastas e módulos.
+- **Como trabalhamos**: `/nova-tarefa`, `/executar-plan`, `/resolver-bug`, a pasta de cada trabalho em
+  `docs/trabalhos/`, commits semânticos e `npx @fontdata/ai-harness doctor`.
+- **Armadilhas comuns** e onde pedir ajuda.
+
+## Passo 4 — 🚦 GATE de aprovação
+
+Mostre o guia completo. **Peça aprovação.**
+
+## Passo 5 — Gravar
+
+Grave `docs/ONBOARDING.md` e resuma o que foi documentado.
+
+## Guardrails
+
+- **Nunca** inventar passos que não foram verificados.
+- **Nunca** incluir valores de variáveis de ambiente ou credenciais.
+- Conteúdo em **pt-BR**.

package/templates/commands/refatorar.md

@@ -1,17 +1,57 @@
 ---
-description: Refatora um alvo usando os testes existentes como rede de segurança, sem mudar comportamento.
+description: Refatora um alvo em passos pequenos usando os testes existentes como rede de segurança, sem mudar comportamento. Também caça e remove código morto (imports, exports, funções e arquivos não usados).
+argument-hint: "[arquivo ou módulo | codigo-morto] [objetivo: legibilidade, duplicação, acoplamento...]"
 ---
 
-# Refatoração guiada por testes
+# /refatorar — Refatoração guiada por testes
 
-Alvo da refatoração: $ARGUMENTS
+Alvo e objetivo: $ARGUMENTS
 
-Se eu não informei um alvo, me pergunte qual arquivo/módulo refatorar e qual o objetivo (legibilidade, duplicação, performance, acoplamento).
+> **🚦 Há um GATE de aprovação** antes de alterar o código.
 
-Regras:
+## Passo 0 — Alvo e objetivo
 
-1. **Refatoração não muda comportamento.** A interface pública e os resultados observáveis devem permanecer idênticos.
-2. Antes de tocar no código, verifique se há **testes cobrindo o alvo**. Se a cobertura for insuficiente, **pare e me avise** — ofereça rodar `/gerar-testes` primeiro para criar a rede de segurança.
-3. Rode os testes **antes** (baseline verde), faça a refatoração em passos pequenos e rode os testes **depois** de cada passo. Se algo ficar vermelho, reverta o passo.
-4. Não misture refatoração com novas funcionalidades nem com correção de bugs na mesma passada.
-5. Ao final, reporte: o que mudou, por quê, e a confirmação de que toda a suíte continua verde.
+Sem alvo ou objetivo nos argumentos, pergunte qual arquivo ou módulo refatorar e o que se quer melhorar
+(legibilidade, duplicação, acoplamento, performance).
+
+**Alvo código morto** (`/refatorar codigo-morto [pasta ou módulo]` ou pedido equivalente):
+
+1. Varra imports, exports sem consumidor, funções, variáveis e classes nunca referenciadas, arquivos órfãos e
+   dependências não usadas com a ferramenta da stack (ex.: `knip`, `ts-prune`, `depcheck`, `vulture`, `deadcode`,
+   linter). **Não instale nada novo** sem perguntar.
+2. Confirme cada item **por busca** no projeto e classifique a confiança: **ALTA**, **MÉDIA** (reflexão, rota,
+   acesso por string, teste) ou **BAIXA**. Cuidado com API pública, entrypoints e plugins.
+3. Crie um trabalho do tipo `investigacao` (id `AAAA-MM-DD-codigo-morto`) e grave o relatório em
+   `docs/trabalhos/<id>/relatorios/TECNICO.md`, com o frontmatter do contrato (`tipo: relatorio_tecnico`,
+   `trabalho_tipo: investigacao`) e os arquivos analisados em `arquivos`.
+4. Os itens a remover passam pelo GATE do Passo 3; cada remoção é um passo do Passo 4.
+
+## Passo 1 — Rede de segurança (somente leitura)
+
+1. Verifique se há **testes cobrindo o comportamento do alvo**. Com cobertura insuficiente, **pare** e ofereça rodar
+   `/gerar-testes` primeiro.
+2. Rode a suíte e confirme o **baseline verde**.
+
+## Passo 2 — Planejar os passos
+
+Liste passos pequenos e independentes, cada um verificável pela suíte. Em **código legado**, preserve o **padrão
+local** do arquivo: a refatoração melhora a estrutura sem impor as convenções de arquivo novo.
+
+## Passo 3 — 🚦 GATE de aprovação
+
+Mostre os passos, o que muda em cada um e a garantia de que a interface pública permanece igual. **Peça aprovação.**
+
+## Passo 4 — Executar passo a passo
+
+Aplique um passo, rode a suíte e siga. Se algo ficar vermelho, **reverta o passo** e reavalie.
+
+## Passo 5 — Relatório
+
+O que mudou, por quê e a confirmação de que toda a suíte continua verde.
+
+## Guardrails
+
+- **Refatoração não muda comportamento**: interface pública e resultados observáveis idênticos.
+- **Nunca** misturar refatoração com funcionalidade nova ou correção de defeito na mesma passada.
+- **Nunca** remover código morto que não foi aprovado no GATE, principalmente os de confiança MÉDIA ou BAIXA.
+- Conteúdo em **pt-BR**.

package/templates/commands/revisar-pr.md

@@ -1,18 +1,62 @@
 ---
-description: Faz o review de um PR ou do diff atual, classificando achados em BLOQUEANTE, IMPORTANTE e SUGESTÃO.
+description: Faz o review de um PR, de uma branch ou do diff atual, classificando os achados em BLOQUEANTE, IMPORTANTE e SUGESTÃO, sem alterar código. Se pedido, organiza as correções num trabalho com plano.
+argument-hint: "[número do PR, branch ou nada para o diff atual]"
 ---
 
-# Review de PR / diff
+# /revisar-pr — Review de PR ou diff
 
-Alvo (opcional — número do PR, branch ou nada para o diff atual): $ARGUMENTS
+Alvo: $ARGUMENTS
 
-Passos:
+Este comando só lê e reporta. O Passo 5, opcional, só cria arquivos se o usuário pedir e depois do GATE.
 
-1. Determine o que revisar:
-   - Se eu informei um **número de PR**, use o `gh` para buscar o diff (`gh pr diff <n>`) e a descrição.
-   - Se informei uma **branch**, compare-a com a branch principal.
-   - Se **nada** foi informado, revise o diff local atual (`git diff` do que está em andamento vs. a base).
-2. Se existir o agent `@code-reviewer` em `.claude/agents/`, **delegue a ele** a análise, passando `SPEC.md`/plano como referência. Caso contrário, faça o review diretamente.
-3. Avalie: correção (bugs, casos de borda), segurança, performance, testes (existem? cobrem o crítico?), aderência ao `CLAUDE.md` e às convenções, legibilidade e simplicidade, e **comentários** (orçamento da rule `.claude/rules/comentarios.md`: bloco <= 3 linhas, docstring pública <= 5, sem cabeçalho de arquivo, sem banner/separador, sem task/plano/data/hash de commit no código) — comentário fora do padrão é **IMPORTANTE**, não SUGESTÃO.
-4. Classifique cada achado em **BLOQUEANTE** (não pode entrar assim), **IMPORTANTE** (deveria ser ajustado) e **SUGESTÃO** (melhoria opcional), com `arquivo:linha` e a correção proposta.
-5. Termine com um veredito: **aprovar**, **aprovar com ressalvas** ou **solicitar mudanças**. Não altere o código — apenas revise.
+## Passo 0 — Determinar o que revisar
+
+- **Número de PR:** busque o diff e a descrição com `gh pr diff <n>` e `gh pr view <n>`.
+- **Branch:** compare com a branch principal.
+- **Nada informado:** revise o diff local em andamento contra a base.
+
+## Passo 1 — Contexto
+
+Leia o `SPEC.md`, as rules de `.claude/rules/` e, se o diff pertence a um trabalho, o `SPEC.md` e o `PLAN.md` dele
+em `docs/trabalhos/<id>/`.
+
+## Passo 2 — Delegar ou revisar
+
+Se existir o agent `code-reviewer` em `.claude/agents/`, delegue a análise a ele, passando o diff e o contexto.
+Caso contrário, revise diretamente.
+
+## Passo 3 — Avaliar
+
+1. **Correção:** bugs, casos de borda, erros silenciados.
+2. **Aderência** à SPEC e ao plano do trabalho.
+3. **Testes:** existem e cobrem o crítico? Falhariam com a implementação errada?
+4. **Segurança e dados:** autorização, isolamento, segredos.
+5. **Performance** nos trechos quentes.
+6. **Convenções** do `CLAUDE.md` e das rules; em código legado, respeito ao padrão local.
+7. **Comentários** fora do orçamento de `.claude/rules/comentarios.md` são **IMPORTANTE**, não sugestão.
+
+## Passo 4 — Classificar e concluir
+
+Cada achado em **BLOQUEANTE**, **IMPORTANTE** ou **SUGESTÃO**, com `arquivo:linha` e a correção proposta. Termine
+com o veredito: **aprovar**, **aprovar com ressalvas** ou **solicitar mudanças**. Com achados a corrigir, ofereça
+o Passo 5.
+
+## Passo 5 — Organizar as correções (opcional, só se o usuário pedir)
+
+1. Entram sempre os achados **BLOQUEANTE** e **IMPORTANTE**; pergunte quais **SUGESTÕES** entram.
+2. Rascunhe o trabalho de correção seguindo `/nova-tarefa` (id `AAAA-MM-DD-correcoes-<slug>`, tipo `feature`) ou,
+   quando o achado for defeito de comportamento, `/resolver-bug`. Os documentos ficam em `docs/trabalhos/<id>/`.
+3. Cada achado vira uma task com **pelo menos 2 testes críticos**, sendo o primeiro um **teste de regressão** que
+   falha hoje pelo problema apontado. O achado de origem fica na prosa da task, nunca no código.
+4. Para cada **classe** de problema que as rules de `.claude/rules/` não cobrem, sugira uma rule curta que teria
+   evitado o achado.
+5. **🚦 GATE de aprovação:** mostre as tasks por achado, as rules sugeridas e o que ficou de fora. **Não crie nenhum
+   arquivo antes da aprovação explícita.** Aprovado, siga o fluxo de `/nova-tarefa` ou `/resolver-bug` (auditoria
+   do plano e execução com `/executar-plan`).
+
+## Guardrails
+
+- **Nunca** alterar código neste comando; até o GATE do Passo 5, nem criar arquivos.
+- **Nunca** escrever no código a referência ao achado ou ao review — ela mora na prosa do `PLAN.md`.
+- **Nunca** publicar comentários no PR sem pedido explícito.
+- Conteúdo em **pt-BR**.