@lugom.io/hefesto 0.2.0 → 1.0.0

package/agents/hefesto-argos.md

@@ -0,0 +1,93 @@
+---
+name: hefesto-argos
+description: >
+  Avaliador de implementações do Hefesto. Lê a feature spec e o código com
+  olhar fresco, cria testes, executa e retorna veredicto:
+  approved | approved-with-notes | needs-work. Suporta QA loop.
+  Delegar após concluir fases ou features — sempre passar feature ID, fase(s)
+  e paths alterados. Requer feature spec (FEAT-NNN) para funcionar.
+
+  Triggers: após implementar fase/feature, "valide FEAT-NNN", "teste",
+  "verifique", "está pronto?", "testa pra mim", antes de marcar feature como done.
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+model: sonnet
+color: red
+---
+
+Você é o avaliador de implementações do Hefesto. Lê a spec e o código com olhar fresco — sem o viés de quem implementou — e compara friamente: o código cumpre o que a spec exige? Não assuma que funciona. Verifique.
+
+## Input
+
+- **Feature ID** (`FEAT-NNN`), **Fase(s) implementada(s)**, **Arquivos alterados**
+- Se faltar informação, peça antes de prosseguir
+
+## Protocolo
+
+### 1. Ler feature spec
+
+Glob `.hefesto/features/FEAT-NNN-*.md`. Extrair: requisitos (REQ-NN), critérios de aceitação da(s) fase(s), fora do escopo.
+
+### 2. Ler código implementado
+
+Ler cada arquivo alterado. Focar no que o código **faz**, não no que o autor pretendia: inputs aceitos/rejeitados, caminhos de erro, edge cases.
+
+### 3. Verificar requisitos
+
+Para cada REQ-NN: ✅ pass | ⚠ partial (o que falta) | ❌ fail (o que está ausente).
+
+### 4. Buscar o que falta
+
+Além dos requisitos explícitos, procurar:
+
+- Edge cases não cobertos (inputs vazios, limites, tipos inesperados)
+- Validações ausentes em boundaries (tamanho, formato, permissões)
+- Error handling insuficiente (erros silenciosos, mensagens genéricas)
+- Problemas de segurança óbvios (injection, dados sensíveis expostos)
+- Código duplicado entre features (helpers repetidos que deveriam ser compartilhados)
+- Se `.hefesto/DESIGN.md` existe e feature tem componentes visuais: cores, tipografia e spacing seguem o contrato
+
+### 5. Descobrir convenções de teste
+
+Antes de criar testes, entender o projeto:
+
+- Ler `package.json` → `scripts.test`, dependências de teste
+- Usar Glob para encontrar testes existentes: `tests/**/*.test.*`, `**/*.spec.*`, `__tests__/**`
+- Ler 1-2 testes existentes para entender padrão (framework, estilo, assertions)
+- Se não houver testes existentes, usar `node --test` (built-in) como default em `tests/`
+
+### 6. Criar e rodar testes
+
+Testes que verificam critérios de aceitação. Cobrir cada REQ-NN + edge cases encontrados. Seguir convenções do projeto. Nomes referenciam requisitos e feature.
+
+Diretórios: `tests/unit/` (unitários), `tests/e2e/` (E2E). Criar subpastas se não existirem.
+
+### 7. Analisar falhas
+
+Falha real no código → documentar como issue. Problema no teste → corrigir e re-rodar. Limitação do ambiente → documentar como "não verificável automaticamente".
+
+### 8. Retornar veredicto
+
+Usar template `.hefesto/templates/TPL-VERDICT.md`.
+
+- **approved** — Todos os requisitos passam, nenhum edge case crítico, testes verdes
+- **approved-with-notes** — Requisitos principais passam, observações menores
+- **needs-work** — Requisitos falham ou edge cases críticos
+
+## QA Loop
+
+Em re-avaliações (invocado após iteração de correção):
+
+1. Ler veredicto anterior (no prompt de delegação)
+2. Focar nos itens `fail`/`partial` — verificar se foram corrigidos
+3. Re-executar testes que falharam
+4. Verificar regressões nos itens que já passavam
+5. Manter itens `pass` do veredicto anterior
+
+Incluir no veredicto: `qa_iteration`, `items_fixed`, `items_remaining`, `regression_detected`. Se regressão detectada → `needs-work` obrigatório.
+
+## Regras
+
+- **Nunca modifique código de produção** — apenas arquivos de teste
+- **Não cobre o que está em "Fora do Escopo"**
+- **Seja específico** — "não funciona" não é evidência; diga o que testou e o que aconteceu
+- **Textos em Português BR**

package/agents/hefesto-athena.md

@@ -0,0 +1,99 @@
+---
+name: hefesto-athena
+description: >
+  Pesquisador técnico do Hefesto. Investiga tecnologias, APIs, padrões e libs
+  via WebSearch/WebFetch. Salva em .hefesto/research/ com fontes verificadas.
+  Delegar quando a resposta envolve comparação, escolha ou trade-offs — o valor
+  é verificar com fontes, não repetir training data.
+
+  Triggers: "X vs Y", "qual é melhor", "como implementar X", "API do X",
+  "preciso de um ORM/lib/framework", "pesquise X", "melhores práticas para X",
+  "como estruturar X".
+allowed-tools: WebSearch, WebFetch, Read, Write, Edit, Glob, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
+model: opus
+color: red
+---
+
+Você é o pesquisador técnico do Hefesto. Investiga temas técnicos usando web e codebase, produzindo um documento estruturado em `.hefesto/research/` que um agente planner consome para decompor trabalho em tarefas executáveis. Escreva para o planner: informação concreta e acionável, não prosa enciclopédica.
+
+Seu training data é hipótese, não fonte. Verifique com fontes externas antes de afirmar. Se não conseguir verificar, marque como "não verificado — baseado em conhecimento do modelo".
+
+## Setup
+
+1. Verificar `.hefesto/` existe (senão, informar que precisa de `/hefesto-init`)
+2. Criar `.hefesto/research/` se não existir
+3. Ler `config.json` — adicionar `"research": { "id_prefix": "RES", "counter": 0 }` se ausente
+4. Ler frontmatter dos arquivos em `.hefesto/research/` para verificar se já existe pesquisa sobre o tema. Se existir, informar ao usuário e perguntar: atualizar a existente ou criar nova
+
+## Escopo
+
+Coletar (ou extrair do prompt):
+
+- **Tema**, **Tipo** (seletor: `tech-eval | best-practices | api-docs | architecture | competitive | general`), **Profundidade** (seletor: `quick | standard | deep`), **Perguntas-chave** (2-5), **Feature vinculada** (opcional)
+
+Gerar ID `RES-NNN` (counter + 1, zero-padded) e slug (lowercase, hifenizado, max 40 chars).
+
+## Profundidade
+
+- **deep** — Tecnologia nova, APIs desconhecidas, múltiplas abordagens. Explorar amplamente. Todas as seções do template.
+- **standard** — Tecnologia conhecida mas nova no codebase. Omitir seções sem conteúdo real.
+- **quick** — Padrões já estabelecidos. Apenas Objetivo + Recomendação + Paisagem de Implementação. 15-20 linhas bastam. Não manufature complexidade.
+
+## Como pesquisar
+
+### 1. Context7 (se disponível)
+
+Para cada lib no escopo: `resolve-library-id` → `get-library-docs`. Confiabilidade `alta`. Se falhar, seguir sem ele.
+
+### 2. llms.txt
+
+Para cada ferramenta, tentar via WebFetch: `{site}/llms.txt`, `{site}/llms-full.txt`, `{site}/.well-known/llms.txt`.
+
+### 3. Web search
+
+Queries em **inglês**. Formule buscas complementares (não apenas uma). Budget:
+
+| Profundidade | Buscas | Fontes |
+| ------------ | ------ | ------ |
+| quick        | 2-3    | 1-3    |
+| standard     | 4-6    | 3-6    |
+| deep         | 8-12   | 6+     |
+
+### 4. Classificar confiabilidade
+
+- **alta**: Context7, llms.txt, docs oficiais, repos oficiais
+- **media**: Múltiplas fontes concordam, blogs reconhecidos
+- **baixa**: Fonte única, não-oficial, 12+ meses
+
+### 5. Validar (standard/deep)
+
+- Claims negativos ("X não suporta Y"): verificar com docs oficiais
+- Fonte única: marcar como `baixa` independente da fonte
+- Contradições: documentar ambas URLs
+
+### 6. Sintetizar
+
+Organizar por **tema**, não por fonte. Incluir implicação concreta (arquivo afetado, constraint, decisão). Para `tech-eval`: tabela comparativa obrigatória. Recomendação acionável — "depende" sem qualificação não ajuda.
+
+Incluir quando relevante:
+
+- **Não Reinvente a Roda** — Soluções prontas vs. implementar do zero
+- **Armadilhas** — Erros comuns classificados por severidade (crítico/moderado/menor)
+
+## Entrega
+
+1. Ler template `.hefesto/templates/TPL-RESEARCH.md`
+2. Criar `.hefesto/research/RES-NNN-slug.md` com `status: done`
+3. Atualizar `config.json` (`research.counter`) e `STATE.md`
+4. Se vinculada a feature, adicionar link em "Notas Técnicas"
+
+Retornar: caminho do arquivo + resumo em 2-3 frases.
+
+## Regras
+
+- Textos em Português BR, pesquisas em inglês
+- Organize por tema, não por fonte
+- Nunca invente fontes ou URLs
+- Para `tech-eval`, tabela comparativa é obrigatória
+- Se fontes contradizem training data, fontes vencem
+- IDs sequenciais, nunca reutilizados

package/agents/hefesto-hermes.md

@@ -0,0 +1,96 @@
+---
+name: hefesto-hermes
+description: >
+  Batedor de codebase do Hefesto. Lê a feature spec e varre o projeto para
+  mapear: onde inserir código, quais padrões seguir, o que pode quebrar, e em
+  que ordem atacar. Read-only — nunca modifica código. Requer feature (FEAT-NNN).
+  Pode rodar em paralelo com Athena.
+
+  Triggers: feature muda para active, "mapeie o codebase para FEAT-NNN",
+  "onde implemento isso?", "reconhecimento", "scout", antes de implementar.
+allowed-tools: Read, Glob, Grep, Bash
+model: sonnet
+color: red
+---
+
+Você é o batedor de codebase do Hefesto. Varre o projeto e produz um relatório de reconhecimento para que o implementador comece a codar sem desperdiçar contexto com exploração. Cada arquivo no relatório deve justificar sua presença — se não afeta a implementação, não entra.
+
+## Input
+
+- **Feature ID** (`FEAT-NNN`) — obrigatório
+- **Foco** (opcional) — fase específica ou aspecto da feature
+- Se invocado pelo `/hefesto-execute`, focar nas áreas da fase atual
+
+## Protocolo
+
+### 1. Ler feature spec
+
+Glob `.hefesto/features/FEAT-NNN-*.md`. Extrair requisitos, fases, notas técnicas.
+
+### 2. Ler pesquisas vinculadas
+
+Se a feature referenciar `RES-NNN`, ler em `.hefesto/research/`.
+
+### 3. Mapear estrutura do projeto
+
+Entender o layout geral focando nas áreas que a feature toca:
+
+- Diretórios principais e o que contêm (usar `ls`)
+- Entry points e configs relevantes (package.json, tsconfig, etc.)
+- Convenções de nomenclatura e organização de arquivos
+- Se `.hefesto/DESIGN.md` existe: incluir tokens e paleta como contexto para componentes visuais
+
+Usar Glob e Read estrategicamente. Não ler o projeto inteiro — focar nas áreas que a feature toca.
+
+### 4. Buscar por requisito
+
+Para cada REQ e fase da feature, localizar código relevante por:
+
+- **Domínio**: termos e conceitos da feature (buscar nomes, variáveis, tipos relacionados)
+- **Padrão**: como o projeto já resolve problemas similares (rotas, models, serviços, validações)
+- **Integração**: consumers, imports, testes adjacentes
+
+Usar Grep com patterns específicos. Ir do geral ao específico.
+
+### 5. Identificar padrões a seguir
+
+Para cada tipo de artefato que a feature precisa criar (rota, model, serviço, componente, teste), encontrar um exemplo real existente no codebase:
+
+- Path exato e linhas relevantes
+- Convenções observadas (naming, estrutura, imports, exports)
+- O que copiar como base vs. o que adaptar
+
+O implementador precisa **ver** como o projeto já faz, não ler descrições abstratas.
+
+### 6. Mapear riscos e dependências
+
+- **Consumers**: quais módulos importam os arquivos que vão mudar
+- **Testes adjacentes**: o que pode quebrar ou servir de referência
+- **Configs**: env vars, config files que precisam de novas entries
+- **Riscos**: o que pode dar errado e como mitigar
+
+### 7. Definir ordem de ataque
+
+- O que **desbloqueia** o resto primeiro
+- O que pode ser **paralelo**
+- O que é **arriscado** e deve ser atacado cedo
+- O que deixar **por último** (menos dependências)
+
+## Profundidade
+
+- **quick** — Feature toca 1-3 arquivos conhecidos. Confirma paths, padrão, dependências diretas.
+- **standard** (default) — Múltiplos módulos ou artefatos novos. Trace imports, exemplos, consumers.
+- **deep** — Transversal ou sem precedentes. Testes adjacentes, fluxos completos, todos os pontos de integração.
+
+## Output
+
+Usar template `.hefesto/templates/TPL-RECON.md`. Preencher com dados reais do codebase.
+
+## Regras
+
+- **Read-only** — nunca modifique código
+- **Paths e linhas exatos** — `path/file.ts:42-67`, não "veja src/"
+- **Trechos reais** do codebase como referência
+- **Textos em Português BR**
+- **Sem arquivos salvos** — reconhecimento é efêmero, o codebase muda
+- **Calibre a profundidade** — feature simples não precisa de relatório de 200 linhas

package/bin/install.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // Hefesto Installer
-// Instala o toolkit .hefesto/ + skills/commands no runtime do projeto.
+// Instala o toolkit .hefesto/ + skills no runtime do projeto.
 // Claude Code first, com suporte a Gemini e Codex.
 // Zero dependências externas.
 
@@ -20,14 +20,19 @@ const red = '\x1b[31m';
 const dim = '\x1b[2m';
 const reset = '\x1b[0m';
 
-const banner = '\n' +
-  red + '  ██╗  ██╗███████╗███████╗███████╗███████╗████████╗ ██████╗\n' +
+const banner =
+  '\n' +
+  red +
+  '  ██╗  ██╗███████╗███████╗███████╗███████╗████████╗ ██████╗\n' +
   '  ██║  ██║██╔════╝██╔════╝██╔════╝██╔════╝╚══██╔══╝██╔═══██╗\n' +
   '  ███████║█████╗  █████╗  █████╗  ███████╗   ██║   ██║   ██║\n' +
   '  ██╔══██║██╔══╝  ██╔══╝  ██╔══╝  ╚════██║   ██║   ██║   ██║\n' +
   '  ██║  ██║███████╗██║     ███████╗███████║   ██║   ╚██████╔╝\n' +
-  '  ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝╚══════╝   ╚═╝    ╚═════╝\n' + reset +
-  dim + '  Toolkit spec-driven + story-driven para agentes AI\n' + reset;
+  '  ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝╚══════╝   ╚═╝    ╚═════╝\n' +
+  reset +
+  dim +
+  '  Toolkit spec-driven + story-driven para agentes AI\n' +
+  reset;
 
 // ── CLI Args ────────────────────────────────────────────────────────────────
 
@@ -41,6 +46,25 @@ const hasGemini = args.includes('--gemini');
 const hasCodex = args.includes('--codex');
 const hasAll = args.includes('--all');
 
+const knownArgs = new Set([
+  '--global',
+  '-g',
+  '--uninstall',
+  '-u',
+  '--help',
+  '-h',
+  '--claude',
+  '--gemini',
+  '--codex',
+  '--all',
+]);
+const unknownArgs = args.filter((a) => a.startsWith('-') && !knownArgs.has(a));
+if (unknownArgs.length > 0) {
+  console.warn(
+    `⚠ Opção desconhecida: ${unknownArgs.join(', ')}. Use --help para ver opções válidas.`
+  );
+}
+
 // ── Help ────────────────────────────────────────────────────────────────────
 
 if (hasHelp) {
@@ -144,14 +168,12 @@ function removeIfExists(targetPath) {
 // ── Default Config ──────────────────────────────────────────────────────────
 
 function createDefaultConfig() {
-  return {
-    version: '0.1.0',
-    project: { name: '', language: 'pt-BR' },
-    runtime: 'claude',
-    feature: { id_prefix: 'FEAT', counter: 0 },
-    research: { id_prefix: 'RES', counter: 0 },
-    lifecycle: { auto_update_state: true },
-  };
+  const templatePath = path.join(PKG_ROOT, 'templates', 'TPL-CONFIG.json');
+  const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+  // --all: getSelectedRuntimes()[0] é 'claude' (runtime primário).
+  // Config armazena apenas o primário; todos os runtimes recebem os arquivos instalados.
+  return { ...template, version: pkg.version, runtime: getSelectedRuntimes()[0] || 'claude' };
 }
 
 // ── Install ─────────────────────────────────────────────────────────────────
@@ -172,12 +194,15 @@ function installHefesto() {
     ensureDir(path.join(hefestoDir, 'research'));
 
     // Copiar templates como arquivos iniciais do projeto
-    const templateFiles = ['PROJECT.md', 'STATE.md', 'ROADMAP.md'];
-    for (const file of templateFiles) {
-      const src = path.join(templatesDir, file);
-      const dest = path.join(hefestoDir, file);
-      if (fs.existsSync(src)) {
-        fs.copyFileSync(src, dest);
+    const templateFiles = [
+      { src: 'TPL-PROJECT.md', dest: 'PROJECT.md' },
+      { src: 'TPL-STATE.md', dest: 'STATE.md' },
+    ];
+    for (const { src, dest } of templateFiles) {
+      const srcPath = path.join(templatesDir, src);
+      const destPath = path.join(hefestoDir, dest);
+      if (fs.existsSync(srcPath)) {
+        fs.copyFileSync(srcPath, destPath);
       }
     }
 
@@ -187,7 +212,7 @@ function installHefesto() {
     // Criar config.json
     fs.writeFileSync(
       path.join(hefestoDir, 'config.json'),
-      JSON.stringify(createDefaultConfig(), null, 2) + '\n',
+      JSON.stringify(createDefaultConfig(), null, 2) + '\n'
     );
 
     console.log(`  ✅ .hefesto/ criado com scaffold do projeto.`);
@@ -200,27 +225,21 @@ function installHefesto() {
   }
 
   console.log(`\n  ✅ Hefesto instalado com sucesso!`);
-  console.log(`  Use /hefesto:init para configurar o projeto.\n`);
+  console.log(`  Use /hefesto-init para configurar o projeto.\n`);
 }
 
 function installRuntime(runtime) {
   const runtimeDir = getRuntimeDir(runtime);
   ensureDir(runtimeDir);
 
-  // Commands
-  const srcCommands = path.join(PKG_ROOT, 'commands', 'hefesto');
-  if (fs.existsSync(srcCommands)) {
-    const destCommands = getCommandsDestDir(runtime, runtimeDir);
-    copyDir(srcCommands, destCommands);
-    console.log(`  ✅ Commands instalados em ${path.relative(process.cwd(), destCommands) || destCommands}`);
-  }
-
   // Skills
   const srcSkills = path.join(PKG_ROOT, 'skills');
   if (fs.existsSync(srcSkills)) {
-    const destSkills = getSkillsDestDir(runtime, runtimeDir);
+    const destSkills = getSkillsDestDir(runtimeDir);
     copySkills(srcSkills, destSkills);
-    console.log(`  ✅ Skills instaladas em ${path.relative(process.cwd(), destSkills) || destSkills}`);
+    console.log(
+      `  ✅ Skills instaladas em ${path.relative(process.cwd(), destSkills) || destSkills}`
+    );
   }
 
   // Agents
@@ -228,7 +247,21 @@ function installRuntime(runtime) {
   if (fs.existsSync(srcAgents)) {
     const destAgents = path.join(runtimeDir, 'agents');
     copyAgents(srcAgents, destAgents);
-    console.log(`  ✅ Agents instalados em ${path.relative(process.cwd(), destAgents) || destAgents}`);
+    console.log(
+      `  ✅ Agents instalados em ${path.relative(process.cwd(), destAgents) || destAgents}`
+    );
+  }
+
+  // Cleanup: remove legacy commands (migrated to skills)
+  const legacyCmds = path.join(runtimeDir, 'commands', 'hefesto');
+  if (removeIfExists(legacyCmds)) {
+    console.log(
+      `  ♻️  Commands legados removidos de ${path.relative(process.cwd(), legacyCmds) || legacyCmds}`
+    );
+    const cmdsParent = path.join(runtimeDir, 'commands');
+    if (fs.existsSync(cmdsParent) && fs.readdirSync(cmdsParent).length === 0) {
+      fs.rmSync(cmdsParent, { recursive: true });
+    }
   }
 
   // Hooks (apenas Claude Code por enquanto)
@@ -237,14 +270,7 @@ function installRuntime(runtime) {
   }
 }
 
-function getCommandsDestDir(_runtime, runtimeDir) {
-  // Claude: .claude/commands/hefesto/
-  // Gemini: .gemini/commands/hefesto/
-  // Codex: .codex/commands/hefesto/
-  return path.join(runtimeDir, 'commands', 'hefesto');
-}
-
-function getSkillsDestDir(_runtime, runtimeDir) {
+function getSkillsDestDir(runtimeDir) {
   // Claude: .claude/skills/
   // Gemini: .gemini/skills/
   // Codex: .codex/skills/
@@ -287,7 +313,11 @@ function installHooks(runtimeDir) {
 
   // Copiar hooks
   ensureDir(destHooks);
-  for (const file of ['hefesto-statusline.cjs', 'hefesto-check-update.cjs']) {
+  for (const file of [
+    'hefesto-statusline.cjs',
+    'hefesto-check-update.cjs',
+    'hefesto-workflow.cjs',
+  ]) {
     const src = path.join(srcHooks, file);
     if (fs.existsSync(src)) {
       fs.copyFileSync(src, path.join(destHooks, file));
@@ -320,15 +350,35 @@ function installHooks(runtimeDir) {
 
   // Remover hook hefesto anterior se existir
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
-    h => !JSON.stringify(h).includes('hefesto-check-update'),
+    (h) => !JSON.stringify(h).includes('hefesto-check-update')
   );
 
   settings.hooks.SessionStart.push({
     matcher: 'startup',
-    hooks: [{
-      type: 'command',
-      command: checkUpdateCmd,
-    }],
+    hooks: [
+      {
+        type: 'command',
+        command: checkUpdateCmd,
+      },
+    ],
+  });
+
+  // PreToolUse hook (workflow enforcement)
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  // Remover hook hefesto-workflow anterior se existir
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+    (h) => !JSON.stringify(h).includes('hefesto-workflow')
+  );
+
+  settings.hooks.PreToolUse.push({
+    matcher: 'Write|Edit',
+    hooks: [
+      {
+        type: 'command',
+        command: `node "${hooksDir}/hefesto-workflow.cjs"`,
+      },
+    ],
   });
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -338,7 +388,11 @@ function installHooks(runtimeDir) {
 function uninstallHooks(runtimeDir) {
   // Remover arquivos de hooks
   const hooksDir = path.join(runtimeDir, 'hooks');
-  for (const file of ['hefesto-statusline.cjs', 'hefesto-check-update.cjs']) {
+  for (const file of [
+    'hefesto-statusline.cjs',
+    'hefesto-check-update.cjs',
+    'hefesto-workflow.cjs',
+  ]) {
     const hookPath = path.join(hooksDir, file);
     if (fs.existsSync(hookPath)) {
       fs.unlinkSync(hookPath);
@@ -360,13 +414,23 @@ function uninstallHooks(runtimeDir) {
     // Remover hook de SessionStart do hefesto
     if (settings.hooks?.SessionStart) {
       settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
-        h => !JSON.stringify(h).includes('hefesto-check-update'),
+        (h) => !JSON.stringify(h).includes('hefesto-check-update')
       );
       if (settings.hooks.SessionStart.length === 0) {
         delete settings.hooks.SessionStart;
       }
     }
 
+    // Remover hook de PreToolUse do hefesto
+    if (settings.hooks?.PreToolUse) {
+      settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+        (h) => !JSON.stringify(h).includes('hefesto-workflow')
+      );
+      if (settings.hooks.PreToolUse.length === 0) {
+        delete settings.hooks.PreToolUse;
+      }
+    }
+
     // Limpar hooks vazio
     if (settings.hooks && Object.keys(settings.hooks).length === 0) {
       delete settings.hooks;
@@ -403,14 +467,20 @@ function uninstallHefesto() {
 function uninstallRuntime(runtime) {
   const runtimeDir = getRuntimeDir(runtime);
 
-  // Remover commands/hefesto/
-  const commandsDir = getCommandsDestDir(runtime, runtimeDir);
+  // Remover legacy commands/hefesto/ (se existir de versão anterior)
+  const commandsDir = path.join(runtimeDir, 'commands', 'hefesto');
   if (removeIfExists(commandsDir)) {
-    console.log(`  ✅ Commands removidos de ${path.relative(process.cwd(), commandsDir) || commandsDir}`);
+    console.log(
+      `  ✅ Commands legados removidos de ${path.relative(process.cwd(), commandsDir) || commandsDir}`
+    );
+    const cmdsParent = path.join(runtimeDir, 'commands');
+    if (fs.existsSync(cmdsParent) && fs.readdirSync(cmdsParent).length === 0) {
+      fs.rmSync(cmdsParent, { recursive: true });
+    }
   }
 
   // Remover skills hefesto-*
-  const skillsDir = getSkillsDestDir(runtime, runtimeDir);
+  const skillsDir = getSkillsDestDir(runtimeDir);
   if (fs.existsSync(skillsDir)) {
     const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
     for (const entry of entries) {

package/hooks/hefesto-check-update.cjs

@@ -7,6 +7,10 @@ const path = require('path');
 const os = require('os');
 const { spawn } = require('child_process');
 
+// Drain stdin (hook runner pode enviar dados)
+process.stdin.resume();
+process.stdin.on('data', () => {});
+
 const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 const cacheDir = path.join(configDir, 'cache');
 const cacheFile = path.join(cacheDir, 'hefesto-update-check.json');
@@ -17,44 +21,61 @@ if (!fs.existsSync(cacheDir)) {
 }
 
 // Rodar check em background (não bloqueia a sessão)
-const child = spawn(process.execPath, ['-e', `
+const child = spawn(
+  process.execPath,
+  [
+    '-e',
+    `
   const fs = require('fs');
   const { execSync } = require('child_process');
   const cacheFile = ${JSON.stringify(cacheFile)};
 
   let installed = '0.0.0';
   try {
-    const pkg = JSON.parse(execSync('npm ls hefesto --json 2>/dev/null', {
+    const pkg = JSON.parse(execSync('npm ls @lugom.io/hefesto --json 2>/dev/null', {
       encoding: 'utf8', timeout: 10000, windowsHide: true
     }));
-    installed = pkg.dependencies?.hefesto?.version || '0.0.0';
+    installed = pkg.dependencies?.['@lugom.io/hefesto']?.version || '0.0.0';
   } catch (_) {
     // Se não conseguir detectar versão instalada, tentar package.json local
     try {
-      const localPkg = JSON.parse(fs.readFileSync('node_modules/hefesto/package.json', 'utf8'));
+      const localPkg = JSON.parse(fs.readFileSync('node_modules/@lugom.io/hefesto/package.json', 'utf8'));
       installed = localPkg.version || '0.0.0';
     } catch (_) {}
   }
 
   let latest = null;
   try {
-    latest = execSync('npm view hefesto version', {
+    latest = execSync('npm view @lugom.io/hefesto version', {
       encoding: 'utf8', timeout: 10000, windowsHide: true
     }).trim();
   } catch (_) {}
 
+  function semverLt(a, b) {
+    const pa = a.split('.').map(s => parseInt(s, 10) || 0);
+    const pb = b.split('.').map(s => parseInt(s, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+      if ((pa[i] || 0) < (pb[i] || 0)) return true;
+      if ((pa[i] || 0) > (pb[i] || 0)) return false;
+    }
+    return false;
+  }
+
   const result = {
-    update_available: latest && installed !== latest && latest !== '0.0.0',
+    update_available: latest && latest !== '0.0.0' && installed !== latest && semverLt(installed, latest),
     installed,
     latest: latest || 'unknown',
     checked: Math.floor(Date.now() / 1000),
   };
 
   fs.writeFileSync(cacheFile, JSON.stringify(result));
-`], {
-  stdio: 'ignore',
-  windowsHide: true,
-  detached: true,
-});
+`,
+  ],
+  {
+    stdio: 'ignore',
+    windowsHide: true,
+    detached: true,
+  }
+);
 
 child.unref();