@lugom.io/hefesto 0.2.0 → 1.0.0

package/hooks/hefesto-statusline.cjs

@@ -9,36 +9,25 @@ 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('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 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);
@@ -68,7 +57,9 @@ process.stdin.on('end', () => {
     }
 
     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}`);
+    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/hooks/hefesto-workflow.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Hefesto Workflow Enforcement
+// PreToolUse hook: avisa quando Write/Edit é usado sem feature ativa
+// Comportamento: WARN only, nunca BLOCK — Hefesto guia, não bloqueia
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+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 toolName = data.tool_name;
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Só verificar Write e Edit
+    if (toolName !== 'Write' && toolName !== 'Edit') return;
+
+    // Se não tem file_path, não tem como verificar
+    if (!filePath) return;
+
+    const basename = path.basename(filePath);
+    const normalized = filePath.replace(/\\/g, '/');
+
+    // Escape hatches — sempre permitir:
+    // .hefesto/ (state files do próprio Hefesto)
+    if (normalized.includes('.hefesto/')) return;
+    // Configs de runtime (.claude/, .gemini/, .codex/)
+    if (
+      normalized.includes('.claude/') ||
+      normalized.includes('.gemini/') ||
+      normalized.includes('.codex/')
+    )
+      return;
+    // Testes (test, spec, __tests__)
+    if (/test|spec|__tests__/i.test(normalized)) return;
+    // Dotfiles e package.json
+    if (basename.startsWith('.') || basename === 'package.json' || basename === 'package-lock.json')
+      return;
+    // Markdown docs
+    if (basename.endsWith('.md')) return;
+
+    // Verificar se .hefesto/STATE.md existe
+    const statePath = path.join(process.cwd(), '.hefesto', 'STATE.md');
+    if (!fs.existsSync(statePath)) return;
+
+    // Ler STATE.md e checar se tem feature ativa
+    const state = fs.readFileSync(statePath, 'utf8');
+    const featureSection = state.match(/## Feature Ativa\s*\n([\s\S]*?)(?=\n## |\n---|$)/);
+
+    if (!featureSection) return;
+
+    const content = featureSection[1].trim();
+    if (content && content !== 'Nenhuma.' && content !== 'Nenhuma') return;
+
+    // Sem feature ativa — emitir warning via stderr
+    process.stderr.write(
+      '\n⚒ HEFESTO: Nenhuma feature ativa. Considere usar /hefesto-new-feature antes de implementar.\n'
+    );
+  } catch (_) {
+    // Silent failure — nunca quebrar o runtime
+  }
+});

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@lugom.io/hefesto",
-  "version": "0.2.0",
+  "version": "1.0.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"
+    "test": "node --test tests/**/*.test.js",
+    "lint": "eslint bin/ hooks/ tests/",
+    "lint:fix": "eslint bin/ hooks/ tests/ --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "sandbox": "HEFESTO=$PWD && mkdir -p $HEFESTO/tmp/hefesto-sandbox/src && cd $HEFESTO/tmp/hefesto-sandbox && test -f package.json || echo '{\"name\":\"sandbox\",\"type\":\"module\"}' > package.json && node $HEFESTO/bin/install.js && claude"
   },
   "engines": {
     "node": ">=18"
@@ -15,7 +20,6 @@
   "files": [
     "bin/",
     "templates/",
-    "commands/",
     "skills/",
     "hooks/",
     "agents/"
@@ -33,5 +37,11 @@
     "codex-cli"
   ],
   "author": "lugom.io",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1"
+  }
 }

package/skills/hefesto-context/SKILL.md

@@ -1,6 +1,12 @@
 ---
 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.
+description: >
+  Conhecimento sobre estrutura e convenções do Hefesto (.hefesto/).
+  ATIVAR quando: projeto tem .hefesto/, usuário menciona feature/spec/story/roadmap/STATE.md/
+  PROJECT.md/config.json, qualquer skill hefesto-* precisa de contexto do sistema, ou tarefa
+  envolve IDs (FEAT-NNN, RES-NNN), status de features ou ciclo de desenvolvimento Hefesto.
+user-invocable: false
+disable-model-invocation: false
 ---
 
 # Hefesto Context
@@ -11,10 +17,10 @@ O Hefesto é um toolkit spec-driven + story-driven que organiza o desenvolviment
 
 ```
 .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)
+├── PROJECT.md              # Visão, valor central, restrições, convenções e features
+├── STATE.md                # Memória entre sessões — posição, decisões, bloqueios (~80 linhas)
+├── config.json             # Configuração (projeto, plataforma, counters de ID)
+├── DESIGN.md               # Contrato visual (opcional, /hefesto-design)
 ├── features/               # Documentos narrativos unificados
 │   └── FEAT-NNN-slug.md    # Uma feature por arquivo
 └── research/               # Pesquisas estruturadas
@@ -48,31 +54,78 @@ Cada feature é um documento narrativo que combina **spec** (O QUÊ) e **stories
 - `done` — completa e verificada
 - `blocked` — bloqueada por dependência
 
+## UX: Interação com o Usuário
+
+- **Opções predefinidas** → sempre usar seletor interativo (não texto livre). Aplica-se a qualquer pergunta com respostas fixas: escolha de plataforma, confirmações sim/não, seleção entre alternativas, etc.
+- **Inputs abertos** → texto livre. Aplica-se a: nome do projeto, descrição, valor central, prazo, perguntas-chave, etc.
+
+## Ciclo de Vida Completo
+
+```
+init → (design) → new-feature → (research) → execute → validate → done
+  │       │            │              │          │          │
+  ▼       ▼            ▼              ▼          ▼          ▼
+/hefesto /hefesto   /hefesto     athena    /hefesto    argos
+ -init    -design   -new-feature  (agent)  -execute    (agent)
+                                             │
+                                             ├→ hermes (recon)
+                                             ├→ self-review inline
+                                             ├→ verification gate
+                                             │    └→ falha após retries → /hefesto-debug
+                                             ├→ /hefesto-simplify (pós)
+                                             ├→ /hefesto-security (pós)
+                                             └→ argos (QA loop, max 3x)
+```
+
 ## STATE.md
 
-Memória viva do projeto. Máximo ~80 linhas. Contém:
-- Posição atual (features feitas vs total)
+Memória entre sessões. Máximo ~80 linhas. Contém:
+
+- Posição atual (features feitas vs total, progresso)
 - Feature e fase ativa
 - Decisões recentes
 - Bloqueios
-- Informação de continuidade (última sessão, onde parou, como retomar)
+- Continuidade (última sessão, onde parou, como retomar)
 
 ## Pesquisas
 
-Pesquisas estruturadas ficam em `.hefesto/research/` com IDs `RES-NNN`. São executadas pelo agente `hefesto-researcher` em contexto isolado.
+Pesquisas estruturadas ficam em `.hefesto/research/` com IDs `RES-NNN`. São executadas pelo agente `hefesto-athena` em contexto isolado. O output é otimizado para consumo por agentes planners — inclui file paths, build order e verificação.
 
 - **ID**: `RES-NNN` (zero-padded, counter em `config.json` → `research.counter`)
 - **Status**: `draft` → `in-progress` → `done`
+- **Profundidade**: `quick` (15-20 linhas), `standard` (completo), `deep` (exaustivo)
 - **Vinculação**: podem ser linked a features via campo `feature` no frontmatter
 - Antes de pesquisar algo novo, verificar se já existe pesquisa relevante em `.hefesto/research/`
 
+## Validação
+
+Após implementar features ou fases, delegue ao agente `hefesto-argos` para avaliação independente. O tester lê a spec, lê o código com olhar fresco (isolamento epistêmico), cria testes e retorna um veredicto estruturado (`approved` / `approved-with-notes` / `needs-work`). Delegue passando: Feature ID, fase(s) implementada(s) e paths dos arquivos alterados.
+
+## config.json
+
+Metadados e contadores do projeto. Sempre leia `.hefesto/config.json` para valores atuais. Estrutura canônica em `.hefesto/templates/TPL-CONFIG.json`. Seções: `project`, `feature`, `research`, `design`, `verification`. O campo `project.language` define o idioma dos artefatos (default: `pt-BR`); `project.lang` define a linguagem de programação.
+
 ## 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
+## Hooks
+
+- **hefesto-statusline.cjs** (StatusLine) — Exibe `⚒ HEFESTO | modelo | dir | contexto%` na statusline
+- **hefesto-check-update.cjs** (SessionStart) — Verifica versão nova no npm ao iniciar sessão
+- **hefesto-workflow.cjs** (PreToolUse) — Avisa quando Write/Edit é usado sem feature ativa
+
+## Skills disponíveis
+
+- `/hefesto-init` — Inicializa .hefesto/ no projeto
+- `/hefesto-new-feature` — Cria nova feature (com gate de validação)
+- `/hefesto-execute` — Executa implementação de feature (decomposição, verificação, QA loop)
+- `/hefesto-debug` — Debugging sistemático em 4 fases (causa raiz → padrão → hipótese → fix)
+- `/hefesto-design` — Cria contrato visual do projeto (cores, tipografia, componentes, tokens CSS)
+- `/hefesto-security` — Auditoria de segurança (OWASP, secrets, boundaries)
+- `/hefesto-simplify` — Simplificação e reuso de código (pós-implementação)
+- `hefesto-athena` — Agente de pesquisa estruturada (delegação automática)
+- `hefesto-argos` — Agente de teste e validação (delegação após implementação, suporta QA loop)
+- `hefesto-hermes` — Agente batedor de codebase (reconhecimento antes de implementar)
 
-- `/hefesto:init` — Inicializa .hefesto/ no projeto
-- `/hefesto:new-feature` — Cria nova feature
-- `/hefesto:status` — Mostra estado do projeto
-- `hefesto-researcher` — Agente de pesquisa estruturada (delegação automática)
+> **Nota:** Skills com `/` são invocadas diretamente pelo usuário. Agents sem `/` (athena, argos, hermes) são delegados automaticamente via subagent dispatch durante a execução — não são slash commands.

package/skills/hefesto-debug/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: hefesto-debug
+description: >
+  Debugging sistemático: investigar causa raiz antes de corrigir. 4 fases, máximo 3 tentativas.
+  ATIVAR quando: "bug", "erro", "quebrou", "não funciona", "debugar", "regressão",
+  "parou de funcionar", "tá dando erro", ou quando um comando/teste falha repetidamente
+  durante execução de outra tarefa.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: '[descrição do problema]'
+---
+
+# Hefesto Debug
+
+Debugging sistemático que impõe disciplina: investigar antes de corrigir. Sem investigação, cada "tentativa" empilha patches frágeis que mascaram a causa real. Este workflow força o caminho correto: entender primeiro, corrigir depois.
+
+## Fase 1 — Causa Raiz (OBRIGATÓRIA)
+
+1. **Reproduzir**: rodar o comando/teste que falha, ler output COMPLETO (não só última linha)
+2. **Contexto**: `git diff`, `git log -5`, arquivos no fluxo do erro, spec da feature ativa (se houver)
+3. **Cadeia de erro**: sintoma → função → input → origem do input (rastrear para trás)
+4. **Output**: "A causa provável é [X] porque [evidência Y]. Manifesta em [Z], origina em [W]."
+
+Sinais de que está pulando investigação:
+
+- Propor solução antes de traçar o fluxo de dados
+- "Não entendo completamente mas..." — se não entende, não pode corrigir
+- Cada fix revela problema novo em lugar diferente → sinal arquitetural, pare e reavalie
+
+## Fase 2 — Análise de Padrões
+
+1. **Recorrência**: git log por fixes similares. Bug recorrente = problema estrutural
+2. **Profundidade**: módulo isolado ou atravessa camadas? Fix cria problemas em outro lugar?
+3. **Impacto**: módulos/features afetados, testes existentes, consumidores
+
+## Fase 3 — Teste de Hipóteses
+
+1. Formular 1-3 hipóteses específicas e refutáveis: "Se [causa], quando [teste], deveria [resultado]"
+2. Testar com mínima intervenção: logging, teste focado, UMA variável por vez
+3. Confirmada → Fase 4. Refutada → reformular. Todas refutadas → voltar à Fase 1
+
+## Fase 4 — Fix
+
+1. **Implementar fix mínimo**: causa raiz, não sintoma. Uma mudança por vez
+2. **Verificar**: comando original, `verification_commands` do config.json, regressões
+3. **Se falhar**: voltar à Fase 3 com hipótese refinada. Reverter, não empilhar
+4. **Após 3 tentativas**: PARAR. Listar premissas e tentativas. Sugerir revisão da abordagem
+5. **Se funcionar**: atualizar STATE.md, considerar teste de regressão
+
+## Integração com Hefesto
+
+- **Feature ativa**: ler spec para comportamento esperado, fix consistente com requisitos
+- **Verification commands**: usar de config.json na Fase 4
+- **Argos**: se bug durante `/hefesto-execute`, o debug é pausa no workflow — retomar após resolver

package/skills/hefesto-design/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: hefesto-design
+description: >
+  Contrato visual do projeto (.hefesto/DESIGN.md) — criação e enforcement do design system.
+  ATIVAR quando: .hefesto/DESIGN.md existe E tarefa envolve CSS, cores, fontes, componentes UI,
+  layout, Tailwind, styled-components, tema, dark mode, shadcn components ou qualquer decisão visual.
+  Também: /hefesto-design, "criar design", "paleta de cores", "design system", "identidade visual",
+  "look and feel", prototipar UI, fazer landing page.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Hefesto Design
+
+Cria o contrato visual do projeto (`.hefesto/DESIGN.md`) ou aplica durante implementação.
+
+## Princípio
+
+O contrato visual deve ter **ponto de vista**. Cada decisão — fonte, cor, radius, shadow — deve ser uma escolha intencional que reflete o projeto, não um default seguro. Se o resultado parece que qualquer AI geraria, está errado. O teste: alguém olhando o design consegue adivinhar que tipo de projeto é?
+
+## Detecção de Modo
+
+1. Se invocado como `/hefesto-design` → **Modo Criação**
+2. Se `/hefesto-design update` → **Modo Atualização**
+3. Se ativado automaticamente durante tarefa visual → **Modo Enforcement**
+
+---
+
+## Modo Criação
+
+### Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não, sugerir `/hefesto-init`.
+
+### Fase 1 — Discovery
+
+Coletar informações com o usuário:
+
+1. **"Descreve teu projeto em uma frase"** — input aberto
+2. **"Quem é o público-alvo?"** — input aberto
+3. **"Em 3 palavras, que sentimento quer provocar?"** — input aberto (ex: confiança, energia, sofisticação)
+4. **Referência visual?** — seletor: URL de site / Imagem local (print/screenshot) / Descrição textual / Múltiplas fontes / Nenhuma
+   - Se URL: ler com WebFetch ou browser para extrair padrões visuais (cores, tipografia, layout)
+   - Se imagem: ler com Read tool para analisar padrões visuais (cores, tipografia, layout, componentes)
+   - Se descrição: usar como guia estético
+   - Se múltiplas fontes: aceitar combinação de URLs, imagens e descrições. Consolidar padrões visuais de todas as fontes numa síntese coerente, resolvendo conflitos pelo que melhor reflete o discovery
+
+**Antes de gerar**: com base nas respostas, comprometer-se com uma direção estética clara. Não buscar equilíbrio — buscar personalidade. Uma cor dominante com acentos afiados supera paletas distribuídas uniformemente. Uma fonte com caráter supera uma fonte "segura". Documentar a direção escolhida e o porquê em 1-2 frases antes de iniciar a geração.
+
+### Fase 2 — Geração
+
+1. Ler `.hefesto/templates/TPL-DESIGN.md` como guia de estrutura
+2. Gerar contrato **completo** — todas seções, todos componentes
+3. Cada valor é **exato**: HEX, px, font-family, CSS value. Zero ambiguidade
+4. Validar contrastes WCAG AA (ver seção Validação WCAG AA)
+5. Do's/Don'ts específicos deste projeto — se servem para qualquer projeto, são genéricos demais
+6. Validar contra Checklist de Qualidade (ver seção abaixo)
+7. Apresentar resumo para aprovação:
+   - Nome e descrição do design
+   - Paleta (brand + semantic)
+   - Tipografia (fonts + scale resumido)
+   - Filosofia (radius, shadows, spacing)
+   - 3 Do's e 3 Don'ts mais importantes
+8. Seletor: **Aprovar** / **Ajustar** (especificar o quê) / **Refazer** (novo discovery)
+
+### Fase 3 — Gravação
+
+1. Salvar `.hefesto/DESIGN.md`
+2. Atualizar `.hefesto/config.json` → `design.status: "active"`
+3. Atualizar `.hefesto/STATE.md` com decisão
+
+---
+
+## Modo Enforcement
+
+Ativado automaticamente quando o modelo detecta tarefa visual (criar componente, CSS, Tailwind, estilizar, layout, tema, cores, fontes).
+
+### Protocolo
+
+1. Ler `.hefesto/config.json` → `design.status`
+   - Se `"none"` → sair silenciosamente, sem output
+   - Se `"active"` → prosseguir
+2. Ler `.hefesto/DESIGN.md`
+3. **Todas** decisões visuais usam valores do contrato:
+   - Cores → paleta declarada
+   - Fontes → font stack declarado
+   - Tamanhos → type scale declarado
+   - Espaçamento → scale declarado
+   - Componentes → specs declaradas (estados, variantes, dimensões)
+   - Radius, shadows → filosofia declarada
+   - Animações → motion tokens declarados (durations, easings)
+4. Se o contrato **não cobre** algo necessário → **propor extensão** ao usuário, não inventar
+5. Se o contrato é ambíguo em algum ponto → perguntar ao usuário
+
+---
+
+## Modo Atualização
+
+Invocado com `/hefesto-design update`.
+
+1. Ler `.hefesto/DESIGN.md` existente
+2. Perguntar o que quer ajustar (seletor: Cores / Tipografia / Componentes / Do's-Don'ts / Outro)
+3. Propor mudanças mantendo coerência com o restante do contrato
+4. Validar WCAG AA e checklist de qualidade
+5. Salvar com diff claro do que mudou
+
+---
+
+## Validação WCAG AA
+
+Fórmula para verificar contraste de cores inline, sem dependências externas:
+
+```
+Converter HEX para sRGB (0-1):
+  R = parseInt(hex.slice(1,3), 16) / 255
+  G = parseInt(hex.slice(3,5), 16) / 255
+  B = parseInt(hex.slice(5,7), 16) / 255
+
+Linearizar cada canal:
+  Se C <= 0.03928 → C / 12.92
+  Senão → ((C + 0.055) / 1.055) ^ 2.4
+
+Luminância relativa:
+  L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+
+Contrast ratio:
+  (L_lighter + 0.05) / (L_darker + 0.05)
+
+Thresholds WCAG AA:
+  >= 4.5:1 — texto normal (< 18px regular, < 14px bold)
+  >= 3.0:1 — texto grande (>= 18px regular, >= 14px bold)
+```
+
+Verificar obrigatoriamente:
+
+- Text Primary sobre Background
+- Text Primary sobre Surface
+- Text Secondary sobre Background
+- Text Secondary sobre Surface
+- Semantic colors (Success, Warning, Error) sobre Background
+
+---
+
+## Anti-patterns
+
+Erros comuns que o modelo comete ao gerar design systems. Detectar e corrigir antes de apresentar o contrato:
+
+- **Contrato genérico** — Inter + blue primary + rounded 8px + subtle shadows = output padrão de qualquer modelo. Se o contrato parece genérico, refazer com mais personalidade baseada no discovery
+- **Inconsistência interna** — cores declaradas na paleta mas não usadas nos componentes, ou cores nos componentes que não existem na paleta
+- **Valores órfãos** — tokens mencionados em uma seção que não aparecem em outra
+- **Filosofia ausente** — listar valores sem explicar o "porquê". O Overview existe para dar contexto narrativo a cada decisão
+- **Componentes incompletos** — definir apenas default state, esquecendo hover, focus, active, disabled, error
+- **Do's/Don'ts genéricos** — "Use cores consistentes" ou "Mantenha espaçamento uniforme" servem para qualquer projeto. Cada regra deve ser consequência direta da filosofia deste design específico
+- **Spacing desalinhado** — base unit 8px mas usando valores como 10px, 15px, 22px que quebram o grid
+- **Contrastes não verificados** — declarar paleta sem rodar WCAG AA nas combinações text-on-surface
+- **Dark mode esquecido** — se o projeto suporta dark mode, todas surfaces e content colors precisam de variantes declaradas
+- **Default seguro** — escolher a fonte, cor ou layout "que funciona para tudo" é escolher nada. Cada valor deve ser consequência da direção estética, não uma aposta conservadora
+- **Convergência** — se o contrato resultante é indistinguível de outro projeto, falta personalidade. O discovery existe para diferenciar
+
+---
+
+## Checklist de Qualidade
+
+Validar antes de apresentar o contrato ao usuário:
+
+- [ ] **Completude** — todas seções do TPL-DESIGN.md preenchidas com valores reais?
+- [ ] **Coerência narrativa** — Overview reflete as decisões visuais? Do's/Don'ts derivam da filosofia?
+- [ ] **Especificidade** — todos valores são copy-paste ready (HEX, px, font-family, CSS value)? Nenhum "algo como" ou "variação de"?
+- [ ] **Consistência interna** — tokens usados nos componentes batem com a paleta? Font specs batem com o type scale?
+- [ ] **WCAG AA** — todas combinações text-on-surface verificadas com a fórmula?
+- [ ] **Componentes completos** — todos estados definidos (default, hover, active, focus, disabled)?
+- [ ] **Anti-patterns** — nenhum item da lista acima presente no contrato?
+- [ ] **Personalidade** — o contrato reflete o projeto, não um template genérico?
+- [ ] **Memorabilidade** — alguém vendo apenas a paleta + tipografia consegue intuir o tipo de projeto?
+
+---
+
+## Regras
+
+- **DESIGN.md em Inglês** — o contrato é consumido por agentes e código
+- **Zero dependências** — validação WCAG AA inline, sem scripts
+- **Valores exatos** — nunca gerar "algo entre X e Y" ou "variação de"
+- **Font stack com fallbacks** — sempre incluir fallback CSS completo (system fonts)
+- **Filosofia explícita** — border radius, shadows e spacing devem ter justificativa, não apenas valores

package/skills/hefesto-execute/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: hefesto-execute
+description: >
+  Executa a implementação de uma feature Hefesto. Decompõe em fases atômicas, roda verificação
+  após cada fase, e invoca Argos para QA final (max 3 iterações).
+  Usar com: /hefesto-execute [FEAT-NNN]. Requer feature com status "ready" ou "active".
+  Para criar o spec da feature, usar /hefesto-new-feature primeiro.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: '[FEAT-NNN]'
+---
+
+# Hefesto Execute
+
+Executa a implementação de uma feature, do reconhecimento à validação final.
+
+Ciclo: identificar feature → reconhecer codebase → detectar verificação → executar fases → validar com Argos → QA loop → concluir.
+
+## Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não, sugerir `/hefesto-init`.
+
+## Workflow
+
+### Fase 1 — Identificar Feature
+
+1. Se argumento `FEAT-NNN` fornecido, buscar em `.hefesto/features/FEAT-NNN-*.md`
+2. Senão, ler `.hefesto/STATE.md` → feature ativa
+3. Se nenhuma feature ativa: listar features `ready`, apresentar via seletor interativo. Se não houver, sugerir `/hefesto-new-feature`
+4. Validar status:
+   - `ready` ou `active` → prosseguir
+   - `draft` → "Promova para ready antes de executar"
+   - `done` → informar e sair
+   - `blocked` → informar, seletor: desbloquear (status → `ready`) / cancelar (mantém `blocked`)
+
+### Fase 2 — Reconhecimento
+
+Sempre delegar para `hefesto-hermes` com: ID, título, requisitos, fases. O Hermes calibra a profundidade automaticamente — features simples recebem relatório curto, complexas recebem mapeamento completo. Usar output para informar execução: padrões, pontos de integração, ordem de ataque.
+
+**Dispatch paralelo**: se a feature também precisa de pesquisa, Athena e Hermes podem rodar simultaneamente — exceto quando a pesquisa pode mudar a abordagem (executar Athena primeiro).
+
+### Fase 3 — Detectar Verificação
+
+1. Ler `.hefesto/config.json` → `verification`
+2. Se `commands` vazio e `auto_detect` true:
+   - Ler `package.json`, buscar scripts: `test`, `lint`, `typecheck`, `tsc`, `check`, `format:check`
+   - Seletor: "Detectei estes comandos: [lista]. Confirmar?" (Sim / Editar / Pular)
+3. Se nada detectado, perguntar ao usuário
+4. Salvar em `config.json → verification.commands` e frontmatter da feature
+
+### Fase 4 — Executar Fases
+
+Para **cada Fase** da seção "Implementação" da feature:
+
+#### Fases em paralelo (quando aplicável)
+
+Critérios (TODOS devem ser verdadeiros): sem arquivos compartilhados, sem dependência de dados, verificação independente. Na dúvida, sequencial.
+
+#### 4.1 Preparar
+
+- Ler tarefas, avaliar granularidade (2-5 min cada)
+- Se primeira fase: status → `active`, atualizar STATE.md
+
+#### 4.2 Executar tarefas
+
+Executar no contexto principal (sem subagents para implementação). Para cada tarefa:
+
+1. **Implementar**: ler arquivos antes de modificar, seguir padrões do Hermes
+2. **Self-review inline** (~30s):
+   - [ ] Requisito(s) atendido(s)?
+   - [ ] Nenhum placeholder/TODO no código?
+   - [ ] Segue padrões do codebase?
+   - [ ] Escopo respeitado?
+   - [ ] Nenhuma lógica duplicada? (Grep antes de criar helpers)
+   - [ ] Se tarefa visual e `.hefesto/DESIGN.md` existe: valores seguem o contrato?
+3. Se falhar, corrigir antes de prosseguir
+4. Marcar tarefa concluída no checklist
+
+#### 4.3 Verification Gate
+
+Após todas as tarefas da fase:
+
+1. Rodar cada `verification_command` via Bash
+2. Se falhar: analisar erro, auto-fix, re-rodar. **Max 3 tentativas**
+3. Se falhar após retries: marcar blocker em STATE.md, informar usuário, sugerir `/hefesto-debug`. Não prosseguir
+4. **Stuck detection**: mesmo erro 3x = PARAR e pedir orientação
+
+#### 4.4 Atualizar Tracking
+
+1. Incrementar `phases_done` no frontmatter
+2. Atualizar STATE.md (barra de progresso, fase atual)
+
+### Fase 4.5 — Revisão de Qualidade e Segurança
+
+Após todas as fases de implementação, antes do Argos:
+
+1. `/hefesto-simplify` nos arquivos modificados
+2. `/hefesto-security` nos mesmos arquivos
+3. Re-rodar verificação se fixes aplicados
+4. Pular se o usuário pedir para acelerar
+
+### Fase 5 — Validação (Argos)
+
+Após TODAS as fases executadas: delegar para `hefesto-argos` com feature ID, fases, paths. Aguardar veredicto.
+
+### Fase 6 — QA Loop
+
+O protocolo detalhado do QA loop (foco em itens falhos, detecção de regressão, campos do veredicto) está em `hefesto-argos`. Aqui, o fluxo de decisão:
+
+**Se `needs-work`:**
+
+1. Incrementar `qa_iterations` no frontmatter
+2. Se `qa_iterations >= 3`: **PARAR** — problema arquitetural. Sugerir `/hefesto-debug`. Atualizar STATE.md
+3. Se < 3: aplicar fixes, re-rodar verificação, re-delegar para Argos com veredicto anterior
+
+**Se `approved` ou `approved-with-notes`:**
+
+1. Status → `done`, limpar feature ativa em STATE.md
+2. Se `approved-with-notes`: exibir notas ao usuário
+
+### Fase 7 — Wrap Up
+
+1. Atualizar STATE.md (posição, última atividade, continuidade)
+2. Exibir resumo: feature, fases executadas, iterações QA, veredicto
+3. Sugerir `/hefesto-new-feature` para a próxima
+
+## Regras
+
+- **Implementação no contexto principal** — subagents só para Hermes (recon) e Argos (validação)
+- **Self-review após cada tarefa**, verification gate após cada fase
+- **QA loop max 3 iterações** — regressão = `needs-work` obrigatório
+- **STATE.md atualizado** a cada mudança significativa
+- **Campos ausentes**: inicializar com defaults (qa_iterations: 0, last_verdict: null)