@lugom.io/hefesto 0.1.0

package/bin/install.js

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+
+// Hefesto Installer
+// Instala o toolkit .hefesto/ + skills/commands no runtime do projeto.
+// Claude Code first, com suporte a Gemini e Codex.
+// Zero dependências externas.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+// ── ANSI Colors ─────────────────────────────────────────────────────────────
+
+const red = '\x1b[31m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+const banner = '\n' +
+  red + '  ██╗  ██╗███████╗███████╗███████╗███████╗████████╗ ██████╗\n' +
+  '  ██║  ██║██╔════╝██╔════╝██╔════╝██╔════╝╚══██╔══╝██╔═══██╗\n' +
+  '  ███████║█████╗  █████╗  █████╗  ███████╗   ██║   ██║   ██║\n' +
+  '  ██╔══██║██╔══╝  ██╔══╝  ██╔══╝  ╚════██║   ██║   ██║   ██║\n' +
+  '  ██║  ██║███████╗██║     ███████╗███████║   ██║   ╚██████╔╝\n' +
+  '  ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝╚══════╝   ╚═╝    ╚═════╝\n' + reset +
+  dim + '  Toolkit spec-driven + story-driven para agentes AI\n' + reset;
+
+// ── CLI Args ────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+const hasClaude = args.includes('--claude');
+const hasGemini = args.includes('--gemini');
+const hasCodex = args.includes('--codex');
+const hasAll = args.includes('--all');
+
+// ── Help ────────────────────────────────────────────────────────────────────
+
+if (hasHelp) {
+  console.log(banner);
+  console.log(`  Uso:
+    npx @lugom.io/hefesto [opções]
+
+  Opções:
+    --claude          Instala para Claude Code (padrão)
+    --gemini          Instala para Gemini CLI
+    --codex           Instala para Codex
+    --all             Instala para todos os runtimes
+    --global, -g      Instalação global (~/.claude/, etc.)
+    --uninstall, -u   Remove o Hefesto
+    --help, -h        Mostra esta ajuda
+
+  Exemplos:
+    npx @lugom.io/hefesto                  # Instala para Claude Code (local)
+    npx @lugom.io/hefesto --global         # Instala para Claude Code (global)
+    npx @lugom.io/hefesto --all            # Instala para todos os runtimes
+    npx @lugom.io/hefesto --uninstall      # Remove o Hefesto
+  `);
+  process.exit(0);
+}
+
+// ── Runtime Detection ───────────────────────────────────────────────────────
+
+function getSelectedRuntimes() {
+  if (hasAll) return ['claude', 'gemini', 'codex'];
+  const runtimes = [];
+  if (hasClaude) runtimes.push('claude');
+  if (hasGemini) runtimes.push('gemini');
+  if (hasCodex) runtimes.push('codex');
+  // Default: Claude Code
+  if (runtimes.length === 0) runtimes.push('claude');
+  return runtimes;
+}
+
+// ── Path Resolution ─────────────────────────────────────────────────────────
+
+function getRuntimeDirName(runtime) {
+  if (runtime === 'gemini') return '.gemini';
+  if (runtime === 'codex') return '.codex';
+  return '.claude';
+}
+
+function getGlobalDir(runtime) {
+  if (runtime === 'gemini') {
+    if (process.env.GEMINI_CONFIG_DIR) return path.resolve(process.env.GEMINI_CONFIG_DIR);
+    return path.join(os.homedir(), '.gemini');
+  }
+  if (runtime === 'codex') {
+    if (process.env.CODEX_HOME) return path.resolve(process.env.CODEX_HOME);
+    return path.join(os.homedir(), '.codex');
+  }
+  // Claude Code
+  if (process.env.CLAUDE_CONFIG_DIR) return path.resolve(process.env.CLAUDE_CONFIG_DIR);
+  return path.join(os.homedir(), '.claude');
+}
+
+function getRuntimeDir(runtime) {
+  if (hasGlobal) return getGlobalDir(runtime);
+  return path.join(process.cwd(), getRuntimeDirName(runtime));
+}
+
+function getHefestoDir() {
+  if (hasGlobal) return path.join(os.homedir(), '.hefesto');
+  return path.join(process.cwd(), '.hefesto');
+}
+
+// ── File Operations ─────────────────────────────────────────────────────────
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function copyDir(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function removeIfExists(targetPath) {
+  if (fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+// ── Default Config ──────────────────────────────────────────────────────────
+
+function createDefaultConfig() {
+  return {
+    version: '0.1.0',
+    project: { name: '', language: 'pt-BR' },
+    runtime: 'claude',
+    feature: { id_prefix: 'FEAT', counter: 0 },
+    lifecycle: { auto_update_state: true },
+  };
+}
+
+// ── Install ─────────────────────────────────────────────────────────────────
+
+function installHefesto() {
+  const hefestoDir = getHefestoDir();
+  const templatesDir = path.join(PKG_ROOT, 'templates');
+
+  console.log(banner);
+  console.log(`  Instalando...\n`);
+
+  // 1. Criar .hefesto/ com scaffold
+  if (fs.existsSync(hefestoDir)) {
+    console.log(`  ℹ️  .hefesto/ já existe, mantendo estado do projeto.`);
+  } else {
+    ensureDir(hefestoDir);
+    ensureDir(path.join(hefestoDir, 'features'));
+
+    // 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);
+      }
+    }
+
+    // Copiar pasta templates/ inteira para .hefesto/templates/
+    copyDir(templatesDir, path.join(hefestoDir, 'templates'));
+
+    // Criar config.json
+    fs.writeFileSync(
+      path.join(hefestoDir, 'config.json'),
+      JSON.stringify(createDefaultConfig(), null, 2) + '\n',
+    );
+
+    console.log(`  ✅ .hefesto/ criado com scaffold do projeto.`);
+  }
+
+  // 2. Instalar em cada runtime
+  const runtimes = getSelectedRuntimes();
+  for (const runtime of runtimes) {
+    installRuntime(runtime);
+  }
+
+  console.log(`\n  ✅ Hefesto instalado com sucesso!`);
+  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);
+    copySkills(srcSkills, destSkills);
+    console.log(`  ✅ Skills instaladas em ${path.relative(process.cwd(), destSkills) || destSkills}`);
+  }
+
+  // Hooks (apenas Claude Code por enquanto)
+  if (runtime === 'claude') {
+    installHooks(runtimeDir);
+  }
+}
+
+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) {
+  // Claude: .claude/skills/
+  // Gemini: .gemini/skills/
+  // Codex: .codex/skills/
+  return path.join(runtimeDir, 'skills');
+}
+
+function copySkills(srcDir, destDir) {
+  ensureDir(destDir);
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith('hefesto-')) {
+      const srcSkill = path.join(srcDir, entry.name);
+      const destSkill = path.join(destDir, entry.name);
+      copyDir(srcSkill, destSkill);
+    }
+  }
+}
+
+// ── Hooks ───────────────────────────────────────────────────────────────────
+
+function installHooks(runtimeDir) {
+  const srcHooks = path.join(PKG_ROOT, 'hooks');
+  const destHooks = path.join(runtimeDir, 'hooks');
+
+  // Copiar hooks
+  ensureDir(destHooks);
+  for (const file of ['hefesto-statusline.cjs', 'hefesto-check-update.cjs']) {
+    const src = path.join(srcHooks, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(destHooks, file));
+    }
+  }
+  console.log(`  ✅ Hooks instalados em ${path.relative(process.cwd(), destHooks) || destHooks}`);
+
+  // Registrar hooks em settings.json
+  const settingsPath = path.join(runtimeDir, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (_) {}
+  }
+
+  const hooksDir = destHooks.replace(/\\/g, '/');
+  const statuslineCmd = `node "${hooksDir}/hefesto-statusline.cjs"`;
+  const checkUpdateCmd = `node "${hooksDir}/hefesto-check-update.cjs"`;
+
+  // Statusline
+  settings.statusLine = {
+    type: 'command',
+    command: statuslineCmd,
+  };
+
+  // SessionStart hook (check-update)
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+  // Remover hook hefesto anterior se existir
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+    h => !JSON.stringify(h).includes('hefesto-check-update'),
+  );
+
+  settings.hooks.SessionStart.push({
+    matcher: 'startup',
+    hooks: [{
+      type: 'command',
+      command: checkUpdateCmd,
+    }],
+  });
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`  ✅ Hooks registrados em settings.json`);
+}
+
+function uninstallHooks(runtimeDir) {
+  // Remover arquivos de hooks
+  const hooksDir = path.join(runtimeDir, 'hooks');
+  for (const file of ['hefesto-statusline.cjs', 'hefesto-check-update.cjs']) {
+    const hookPath = path.join(hooksDir, file);
+    if (fs.existsSync(hookPath)) {
+      fs.unlinkSync(hookPath);
+    }
+  }
+
+  // Limpar settings.json
+  const settingsPath = path.join(runtimeDir, 'settings.json');
+  if (!fs.existsSync(settingsPath)) return;
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+    // Remover statusline se é do hefesto
+    if (settings.statusLine?.command?.includes('hefesto-statusline')) {
+      delete settings.statusLine;
+    }
+
+    // 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'),
+      );
+      if (settings.hooks.SessionStart.length === 0) {
+        delete settings.hooks.SessionStart;
+      }
+    }
+
+    // Limpar hooks vazio
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`  ✅ Hooks removidos de settings.json`);
+  } catch (_) {}
+}
+
+// ── Uninstall ───────────────────────────────────────────────────────────────
+
+function uninstallHefesto() {
+  console.log(banner);
+  console.log(`  Desinstalando...\n`);
+
+  // 1. Remover .hefesto/
+  const hefestoDir = getHefestoDir();
+  if (removeIfExists(hefestoDir)) {
+    console.log(`  ✅ .hefesto/ removido.`);
+  } else {
+    console.log(`  ℹ️  .hefesto/ não encontrado.`);
+  }
+
+  // 2. Remover de cada runtime
+  const runtimes = getSelectedRuntimes();
+  for (const runtime of runtimes) {
+    uninstallRuntime(runtime);
+  }
+
+  console.log(`\n  ✅ Hefesto desinstalado.\n`);
+}
+
+function uninstallRuntime(runtime) {
+  const runtimeDir = getRuntimeDir(runtime);
+
+  // Remover commands/hefesto/
+  const commandsDir = getCommandsDestDir(runtime, runtimeDir);
+  if (removeIfExists(commandsDir)) {
+    console.log(`  ✅ Commands removidos de ${path.relative(process.cwd(), commandsDir) || commandsDir}`);
+  }
+
+  // Remover skills hefesto-*
+  const skillsDir = getSkillsDestDir(runtime, runtimeDir);
+  if (fs.existsSync(skillsDir)) {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith('hefesto-')) {
+        fs.rmSync(path.join(skillsDir, entry.name), { recursive: true });
+        console.log(`  ✅ Skill ${entry.name} removida.`);
+      }
+    }
+  }
+
+  // Remover hooks (apenas Claude Code)
+  if (runtime === 'claude') {
+    uninstallHooks(runtimeDir);
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+if (hasUninstall) {
+  uninstallHefesto();
+} else {
+  installHefesto();
+}

package/commands/hefesto/init.md

@@ -0,0 +1,45 @@
+---
+description: "Inicializa o Hefesto no projeto atual. Use /hefesto:init para criar a estrutura .hefesto/ e começar a organizar o desenvolvimento."
+---
+
+# Hefesto Init
+
+Inicializa a estrutura `.hefesto/` no projeto atual.
+
+## O que fazer
+
+1. Verificar se `.hefesto/` já existe. Se existir, avisar o usuário e perguntar se quer reinicializar.
+2. Perguntar ao usuário:
+   - Nome do projeto
+   - Descrição curta (2-3 frases)
+   - Valor central (a única coisa que DEVE funcionar)
+   - Restrições principais (stack, prazo, plataforma, etc.)
+3. Criar a estrutura de diretórios:
+   ```
+   .hefesto/
+   ├── PROJECT.md
+   ├── ROADMAP.md
+   ├── STATE.md
+   ├── config.json
+   └── features/
+   ```
+4. Preencher PROJECT.md com as respostas do usuário.
+5. Gerar STATE.md inicial com posição "Inicializando".
+6. Gerar ROADMAP.md vazio.
+7. Gerar config.json com valores padrão:
+   ```json
+   {
+     "version": "0.1.0",
+     "project": { "name": "", "language": "pt-BR" },
+     "runtime": "claude",
+     "feature": { "id_prefix": "FEAT", "counter": 0 },
+     "lifecycle": { "auto_update_state": true }
+   }
+   ```
+8. Informar o usuário que o projeto foi inicializado e sugerir `/hefesto:new-feature` para criar a primeira feature.
+
+## Notas
+
+- Todos os textos gerados devem ser em Português BR.
+- O config.json deve ser atualizado com o nome do projeto informado pelo usuário.
+- Se `.hefesto/` já existir e o usuário não quiser reinicializar, abortar sem modificar nada.

package/commands/hefesto/new-feature.md

@@ -0,0 +1,50 @@
+---
+description: "Cria uma nova feature no Hefesto. Use /hefesto:new-feature para definir uma nova feature com visão, fluxo do usuário, requisitos e fases de implementação."
+---
+
+# Hefesto New Feature
+
+Cria um novo documento de feature em `.hefesto/features/`.
+
+## Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não existir, sugerir `/hefesto:init` primeiro.
+
+## O que fazer
+
+1. Ler `.hefesto/templates/FEATURE.md` como base para o novo arquivo de feature.
+2. Ler `.hefesto/config.json` para obter o próximo ID disponível.
+3. Perguntar ao usuário:
+   - Título da feature (curto, descritivo)
+   - Visão (o que entrega e por que existe)
+   - Fluxo do usuário (passos que o usuário percorre)
+   - Requisitos principais (testáveis, centrados no usuário)
+   - O que está fora do escopo
+4. Com base nas respostas, propor fases de implementação:
+   - Cada fase deve ser atômica (executável em uma sessão)
+   - Listar arquivos que serão criados/modificados
+   - Definir tarefas concretas e critérios de aceitação
+5. Gerar o ID: `FEAT-NNN` onde NNN é o counter + 1, zero-padded.
+6. Gerar o slug a partir do título (lowercase, hifenizado, max 40 chars).
+7. Criar o arquivo `.hefesto/features/FEAT-NNN-slug.md` com o conteúdo.
+8. Atualizar `.hefesto/config.json` incrementando o counter.
+9. Atualizar `.hefesto/ROADMAP.md` adicionando a nova feature na tabela.
+10. Atualizar `.hefesto/STATE.md` se for a primeira feature ou se nenhuma estiver ativa.
+
+## Formato do arquivo
+
+O arquivo segue o template narrativo unificado com frontmatter YAML:
+
+```yaml
+---
+id: FEAT-NNN
+title: "Título"
+status: draft
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+phases_total: N
+phases_done: 0
+---
+```
+
+Seguido pelas seções: Visão, Fluxo do Usuário, Requisitos, Fora do Escopo, Implementação (com Fases), Notas Técnicas.

package/commands/hefesto/status.md

@@ -0,0 +1,40 @@
+---
+description: "Mostra o estado atual do projeto Hefesto. Use /hefesto:status para ver progresso, features ativas, bloqueios e próximos passos."
+---
+
+# Hefesto Status
+
+Exibe o estado atual do projeto gerenciado pelo Hefesto.
+
+## Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não existir, informar que o projeto não foi inicializado e sugerir `/hefesto:init`.
+
+## O que fazer
+
+1. Ler `.hefesto/STATE.md` e exibir o conteúdo formatado.
+2. Ler `.hefesto/ROADMAP.md` e calcular progresso geral.
+3. Listar todas as features em `.hefesto/features/` com seus status (ler frontmatter de cada arquivo).
+4. Apresentar um resumo ao usuário:
+
+```
+📊 Estado do Projeto: [nome]
+
+Progresso: [██████░░░░] 60% (3 de 5 features)
+
+Feature ativa: FEAT-003 — Título (Fase 2 de 4)
+
+Features:
+  ✅ FEAT-001 — Título (done)
+  ✅ FEAT-002 — Título (done)
+  🔄 FEAT-003 — Título (active — fase 2/4)
+  📋 FEAT-004 — Título (ready)
+  📝 FEAT-005 — Título (draft)
+
+Bloqueios: Nenhum
+
+Próximo passo: Continuar execução da Fase 2 de FEAT-003
+```
+
+5. Se houver bloqueios em STATE.md, destacá-los.
+6. Sugerir próxima ação com base no estado atual.

package/commands/hefesto/update.md

@@ -0,0 +1,31 @@
+---
+description: "Atualiza o Hefesto para a versão mais recente. Use /hefesto:update para atualizar commands, skills, hooks e templates sem perder o estado do projeto."
+---
+
+# Hefesto Update
+
+Atualiza o toolkit Hefesto para a versão mais recente do npm.
+
+## Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não existir, informar que o projeto não foi inicializado e sugerir `/hefesto:init`.
+
+## O que fazer
+
+1. Ler `.hefesto/config.json` e anotar a versão atual (`version`).
+2. Executar o comando de atualização:
+   ```bash
+   npx @lugom.io/hefesto@latest
+   ```
+3. Verificar o output do comando. Se houver erro, informar o usuário e sugerir ação corretiva.
+4. Ler `.hefesto/config.json` novamente e comparar a versão com a anterior.
+5. Informar o resultado ao usuário:
+   - Se atualizou: mostrar versão anterior → nova versão
+   - Se já estava na última versão: informar que está atualizado
+
+## Notas
+
+- O installer preserva `.hefesto/` existente (PROJECT.md, STATE.md, ROADMAP.md, features/, config.json).
+- O que é atualizado: commands, skills, hooks, templates.
+- Não usar `--global` a menos que o usuário peça explicitamente.
+- Se o usuário pedir para atualizar um runtime específico (ex: `--gemini`), passar a flag correspondente.

package/hooks/hefesto-check-update.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Hefesto Update Checker
+// Verifica novas versões em background no SessionStart
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+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');
+
+// Garantir que cache dir existe
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Rodar check em background (não bloqueia a sessão)
+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', {
+      encoding: 'utf8', timeout: 10000, windowsHide: true
+    }));
+    installed = pkg.dependencies?.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'));
+      installed = localPkg.version || '0.0.0';
+    } catch (_) {}
+  }
+
+  let latest = null;
+  try {
+    latest = execSync('npm view hefesto version', {
+      encoding: 'utf8', timeout: 10000, windowsHide: true
+    }).trim();
+  } catch (_) {}
+
+  const result = {
+    update_available: latest && installed !== latest && latest !== '0.0.0',
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000),
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true,
+});
+
+child.unref();

package/hooks/hefesto-statusline.cjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Hefesto Statusline
+// Mostra: ⚒ HEFESTO | model | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window (normalizado para contexto utilizável)
+    const AUTO_COMPACT_BUFFER_PCT = 16.5;
+    let ctx = '';
+    if (remaining != null) {
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+
+      // Bridge file para o context-monitor
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `hefesto-ctx-${session}.json`);
+          fs.writeFileSync(bridgePath, JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000),
+          }));
+        } catch (_) {}
+      }
+
+      // Barra de progresso (10 segmentos)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Update disponível?
+    let updateMsg = '';
+    const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+    const cacheFile = path.join(configDir, 'cache', 'hefesto-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          updateMsg = '\x1b[33m⬆ npx @lugom.io/hefesto\x1b[0m │ ';
+        }
+      } catch (_) {}
+    }
+
+    const dirname = path.basename(dir);
+    process.stdout.write(`${updateMsg}\x1b[1;31m⚒ HEFESTO\x1b[0m │ \x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+  } catch (_) {
+    // Falha silenciosa
+  }
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lugom.io/hefesto",
+  "version": "0.1.0",
+  "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, Gemini and Codex by lugom.io.",
+  "type": "module",
+  "bin": {
+    "hefesto": "./bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "commands/",
+    "skills/",
+    "hooks/",
+    "agents/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "meta-prompting",
+    "context-engineering",
+    "spec-driven-development",
+    "gemini",
+    "gemini-cli",
+    "codex",
+    "codex-cli"
+  ],
+  "author": "lugom.io",
+  "license": "MIT"
+}

package/skills/hefesto-context/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: hefesto-context
+description: Conhecimento sobre a estrutura e convenções do Hefesto. Use sempre que o projeto tiver um diretório .hefesto/, quando o usuário mencionar features, specs, stories, roadmap ou estado do projeto no contexto do Hefesto, ou quando precisar entender como o .hefesto/ organiza o desenvolvimento.
+---
+
+# Hefesto Context
+
+O Hefesto é um toolkit spec-driven + story-driven que organiza o desenvolvimento através de documentos narrativos unificados chamados **features**.
+
+## Estrutura `.hefesto/`
+
+```
+.hefesto/
+├── PROJECT.md              # Visão, valor central, restrições do projeto
+├── ROADMAP.md              # Lista de features com status e progresso
+├── STATE.md                # Memória viva — posição atual, decisões, bloqueios (~80 linhas)
+├── config.json             # Configuração (counters de ID, runtime, preferências)
+└── features/               # Documentos narrativos unificados
+    └── FEAT-NNN-slug.md    # Uma feature por arquivo
+```
+
+## Features
+
+Cada feature é um documento narrativo que combina **spec** (O QUÊ) e **stories** (COMO) em um único arquivo:
+
+- **Visão** — o que entrega e por que existe
+- **Fluxo do Usuário** — passos que o usuário percorre
+- **Requisitos** — checklist testável (REQ-01, REQ-02, ...)
+- **Fora do Escopo** — exclusões explícitas
+- **Implementação** — dividida em **Fases** (cada fase = uma story atômica)
+  - Arquivos a criar/modificar
+  - Tarefas concretas
+  - Critérios de aceitação
+
+## IDs e Naming
+
+- **Feature ID**: `FEAT-NNN` (zero-padded, sequencial)
+- **Arquivo**: `FEAT-NNN-slug.md` (slug = título lowercase hifenizado, max 40 chars)
+- **Counter**: mantido em `config.json` → `feature.counter`
+
+## Status
+
+- `draft` — em definição
+- `ready` — pronta para execução
+- `active` — em andamento
+- `done` — completa e verificada
+- `blocked` — bloqueada por dependência
+
+## STATE.md
+
+Memória viva do projeto. Máximo ~80 linhas. Contém:
+- Posição atual (features feitas vs total)
+- Feature e fase ativa
+- Decisões recentes
+- Bloqueios
+- Informação de continuidade (última sessão, onde parou, como retomar)
+
+## Outputs
+
+Outputs reais (código, documentos, manifestos) vão para o projeto (src/, docs/, etc.). O `.hefesto/` apenas rastreia o que foi produzido e onde foi colocado.
+
+## Commands disponíveis
+
+- `/hefesto:init` — Inicializa .hefesto/ no projeto
+- `/hefesto:new-feature` — Cria nova feature
+- `/hefesto:status` — Mostra estado do projeto

package/templates/FEATURE.md

@@ -0,0 +1,52 @@
+---
+id: { { FEATURE_ID } }
+title: "{{FEATURE_TITLE}}"
+status: draft
+created: { { DATE } }
+updated: { { DATE } }
+phases_total: 0
+phases_done: 0
+---
+
+# {{FEATURE_ID}}: {{FEATURE_TITLE}}
+
+## Visão
+
+{{FEATURE_VISION}}
+
+## Fluxo do Usuário
+
+1. {{USER_FLOW_STEP_1}}
+2. {{USER_FLOW_STEP_2}}
+3. {{USER_FLOW_STEP_3}}
+
+## Requisitos
+
+- [ ] **REQ-01**: {{REQUIREMENT_1}}
+- [ ] **REQ-02**: {{REQUIREMENT_2}}
+
+## Fora do Escopo
+
+- {{EXCLUSION_1}}
+
+## Implementação
+
+### Fase 1: {{PHASE_1_NAME}}
+
+**Arquivos:**
+
+- `{{FILE_PATH}}` — {{FILE_DESCRIPTION}}
+
+**Tarefas:**
+
+- [ ] {{TASK_1}}
+- [ ] {{TASK_2}}
+
+**Critérios de Aceitação:**
+
+- [ ] {{ACCEPTANCE_CRITERIA_1}}
+- [ ] {{ACCEPTANCE_CRITERIA_2}}
+
+## Notas Técnicas
+
+{{TECHNICAL_NOTES}}

package/templates/PROJECT.md

@@ -0,0 +1,28 @@
+# {{PROJECT_NAME}}
+
+## O Que É
+
+{{PROJECT_DESCRIPTION}}
+
+## Valor Central
+
+{{CORE_VALUE}}
+
+## Contexto
+
+{{CONTEXT}}
+
+## Restrições
+
+- **Stack**: {{STACK_CONSTRAINT}}
+- **Prazo**: {{DEADLINE_CONSTRAINT}}
+
+## Decisões
+
+| Decisão | Justificativa | Resultado |
+| ------- | ------------- | --------- |
+| —       | —             | —         |
+
+---
+
+_Última atualização: {{DATE}}_

package/templates/ROADMAP.md

@@ -0,0 +1,23 @@
+# Roadmap
+
+## Visão Geral
+
+{{PROJECT_NAME}} — {{PROJECT_DESCRIPTION}}
+
+## Features
+
+| ID  | Título | Status | Fases | Progresso |
+| --- | ------ | ------ | ----- | --------- |
+| —   | —      | —      | —     | —         |
+
+## Legenda
+
+- `draft` — Em definição
+- `ready` — Pronta para execução
+- `active` — Em andamento
+- `done` — Completa e verificada
+- `blocked` — Bloqueada
+
+---
+
+_Atualizado automaticamente ao concluir features._

package/templates/STATE.md

@@ -0,0 +1,37 @@
+# Estado do Projeto
+
+## Referência
+
+**Projeto:** {{PROJECT_NAME}}
+**Valor central:** {{CORE_VALUE}}
+**Foco atual:** {{CURRENT_FOCUS}}
+
+## Posição Atual
+
+- Features: 0 de 0 completas
+- Status: Inicializando
+- Última atividade: {{DATE}} — Projeto inicializado
+
+Progresso: [░░░░░░░░░░] 0%
+
+## Feature Ativa
+
+Nenhuma.
+
+## Decisões Recentes
+
+Nenhuma.
+
+## Bloqueios
+
+Nenhum.
+
+## Continuidade
+
+- Última sessão: {{DATE}}
+- Parou em: Inicialização do projeto
+- Retomar: Criar primeira feature com /hefesto:new-feature
+
+---
+
+_Manter abaixo de 80 linhas. É um resumo, não um arquivo._