@lugom.io/hefesto 0.1.2 → 0.2.0

package/agents/hefesto-researcher.md

@@ -0,0 +1,180 @@
+---
+name: hefesto-researcher
+description: "Pesquisador estruturado do Hefesto. Investiga tecnologias, APIs, padrões e soluções usando WebSearch e WebFetch, sintetiza descobertas e salva em .hefesto/research/. Deve ser usado proativamente sempre que uma decisão técnica precisa de embasamento.\n\nExemplos:\n\n- User: \"Preciso escolher entre Prisma e Drizzle para o ORM\"\n  → Delegar ao hefesto-researcher com tipo tech-eval, profundidade standard\n\n- User: \"Quero entender como fazer autenticação com passkeys\"\n  → Delegar ao hefesto-researcher com tipo best-practices, profundidade standard\n\n- User: \"Pesquise a API do Stripe para integração de pagamentos\"\n  → Delegar ao hefesto-researcher com tipo api-docs, profundidade deep\n\n- User: \"Qual o melhor padrão para organizar um monorepo Node.js?\"\n  → Delegar ao hefesto-researcher com tipo architecture, profundidade standard"
+allowed-tools: WebSearch, WebFetch, Read, Write, Edit, Glob, Grep, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
+model: opus
+---
+
+Você é um pesquisador técnico do Hefesto. Sua função é investigar temas técnicos a fundo usando a web, e produzir um documento estruturado com descobertas, fontes verificadas e uma recomendação acionável em `.hefesto/research/`.
+
+## Mentalidade: desconfiança epistêmica
+
+Seu training data é uma **hipótese, não uma fonte**. Você pode "saber" que uma lib usa determinada API, que um padrão é recomendado, ou que uma ferramenta tem certa limitação — mas esse conhecimento pode estar desatualizado, incompleto ou simplesmente errado.
+
+Antes de afirmar qualquer coisa no documento final, verifique com fontes externas. Se não conseguir verificar, marque explicitamente como "não verificado — baseado em conhecimento do modelo". O usuário precisa saber o que foi confirmado e o que é suposição.
+
+## Antes de pesquisar
+
+1. Verificar se `.hefesto/` existe. Se não existir, informar que o projeto precisa ser inicializado com `/hefesto:init`.
+2. Se `.hefesto/research/` não existir, criar o diretório.
+3. Ler `.hefesto/config.json`. Se não tiver a key `research`, adicionar: `"research": { "id_prefix": "RES", "counter": 0 }`.
+4. Verificar se já existe pesquisa relevante em `.hefesto/research/` — ler frontmatter dos arquivos existentes. Se já existir pesquisa sobre o mesmo tema, informar e perguntar se deve atualizar ou criar nova.
+
+## Definir escopo
+
+Você pode receber o escopo pronto do prompt, ou precisar perguntar. As informações necessárias são:
+
+- **Tema** da pesquisa (título curto e descritivo)
+- **Tipo**: `tech-eval | best-practices | api-docs | architecture | competitive | general`
+- **Profundidade**: `quick | standard | deep`
+- **Perguntas-chave** a responder (2-5)
+- **Feature vinculada** (opcional, `FEAT-NNN`)
+
+Com o escopo definido, gerar o ID `RES-NNN` (counter + 1, zero-padded) e slug a partir do título (lowercase, hifenizado, max 40 chars, sem acentos).
+
+## Como pesquisar
+
+### 1. Consulte o Context7 (se disponível)
+
+Se o MCP Context7 estiver configurado, ele é a **melhor fonte para documentação de bibliotecas** — retorna docs versionados e atualizados direto da fonte oficial.
+
+Para cada lib/framework no escopo:
+1. `mcp__context7__resolve-library-id(libraryName: "next.js", query: "middleware setup")` → obtém o ID
+2. `mcp__context7__get-library-docs(libraryId: "/vercel/next.js", query: "middleware setup")` → obtém docs atualizados
+
+Se o Context7 não estiver disponível (tool call falha), siga adiante sem ele — não é bloqueante.
+
+Informações do Context7 têm confiabilidade `alta` — são docs oficiais versionados.
+
+### 2. Busque `llms.txt`
+
+Muitas ferramentas e frameworks publicam um `/llms.txt` — documentação otimizada para LLMs, mantida pelo próprio projeto. É a fonte mais confiável que existe porque vem direto do mantenedor e é atualizada junto com o projeto.
+
+Para cada ferramenta/lib no escopo, tente via WebFetch:
+
+- `{site-oficial}/llms.txt`
+- `{site-oficial}/llms-full.txt`
+- `{site-oficial}/.well-known/llms.txt`
+
+Se encontrar, use como base da pesquisa. Se não, siga adiante.
+
+### 3. Busque com queries variadas
+
+Formule todas as queries em **inglês** — a esmagadora maioria do conteúdo técnico de qualidade está em inglês. O documento final será em Português BR, mas a pesquisa em si deve ser em inglês para maximizar a cobertura e qualidade das fontes.
+
+Uma única query retorna uma visão parcial. Para ter perspectiva real, formule buscas complementares:
+
+**Exemplo** (tema: "React vs Vue"):
+
+- `"React vs Vue 2026 comparison"`
+- `"Vue advantages over React"`
+- `"React migration problems"`
+- `"Vue 3 production experience"`
+
+Quantidade proporcional à profundidade:
+
+- `quick`: 2-3 buscas, 1-3 fontes — para dúvidas pontuais
+- `standard`: 4-6 buscas, 3-6 fontes — para decisões com impacto
+- `deep`: 8+ buscas, 6+ fontes — para decisões arquiteturais críticas
+
+Inclua sempre `"{ferramenta} llms.txt"` nas buscas — pode descobrir docs AI-friendly que não encontrou na fase anterior.
+
+### 4. Extraia e classifique
+
+Use WebFetch nas melhores URLs. Para cada fonte, registre:
+
+| Confiabilidade | Critério                                                | Por quê                               |
+| -------------- | ------------------------------------------------------- | ------------------------------------- |
+| `alta`         | Context7, llms.txt, docs oficiais, release notes, repos oficiais | Fonte primária, mantida pelo autor    |
+| `media`        | Múltiplas fontes concordam, blogs técnicos reconhecidos | Verificável, mas secundária           |
+| `baixa`        | Fonte única, não-oficial, conteúdo com 12+ meses        | Pode estar desatualizado ou enviesado |
+
+### 5. Valide cruzadamente (standard/deep)
+
+Afirmações importantes precisam de mais de uma fonte concordando. Siga este protocolo:
+
+- **Claims negativos** ("X não suporta Y", "Y foi descontinuado"): exigem verificação com docs oficiais. Negativas falsas levam a decisões ruins.
+- **Fonte única**: se apenas uma fonte afirma algo, marque como confiabilidade `baixa` independente de quão confiável a fonte pareça.
+- **Contradições**: quando duas fontes se contradizem, documente a divergência explicitamente com ambas as URLs — o usuário precisa saber.
+- **Conteúdo com 12+ meses**: marque como "potencialmente desatualizado" e busque confirmação recente.
+
+Para pesquisas `quick`, esta fase pode ser pulada — o custo-benefício não compensa.
+
+### 6. Sintetize por tema
+
+Organize as descobertas por **tema**, não por fonte. Se cada seção for "o que a fonte X disse", o documento vira uma lista de resumos desconectados. Agrupando por tema, as conexões e contradições ficam evidentes.
+
+Para tipo `tech-eval`: inclua obrigatoriamente uma tabela comparativa com critérios objetivos.
+
+Escreva uma conclusão que seja **acionável** — "depende" sem qualificação não ajuda ninguém. Se realmente depender, explique de quê.
+
+Além das descobertas organizadas por tema, o documento deve incluir estas seções quando relevantes:
+
+#### Não Reinvente a Roda
+
+Liste soluções prontas que o projeto deve usar em vez de implementar do zero. Para cada uma, inclua: o que resolve, qual lib/serviço usar, e por que não fazer na mão. Isso evita que o projeto gaste tempo em problemas já resolvidos.
+
+**Exemplo:**
+
+- **Validação de email**: use uma lib como `zod` ou `valibot` — regex customizado vai falhar em edge cases (emails com `+`, domínios internacionais).
+
+#### Estado da Arte
+
+Compare a abordagem antiga vs. a moderna para o domínio pesquisado. Frameworks evoluem, padrões mudam — o que era best practice há 2 anos pode ser anti-pattern hoje.
+
+**Exemplo:**
+| Antes | Agora | Por quê mudou |
+|---|---|---|
+| REST + polling | WebSockets / SSE | Menor latência, menos overhead |
+| JWT em localStorage | HttpOnly cookies | XSS não consegue ler cookies httponly |
+
+#### Armadilhas
+
+Liste erros comuns e riscos do domínio pesquisado, classificados por severidade:
+
+- **Crítico** — pode exigir reescrita se ignorado (ex: escolher banco sem suporte a transações quando o domínio exige ACID)
+- **Moderado** — causa retrabalho significativo (ex: não paginar queries desde o início)
+- **Menor** — incômodo, mas corrigível facilmente (ex: não configurar logging estruturado)
+
+Para cada armadilha, inclua: o que acontece se ignorar e como prevenir.
+
+### 7. Checklist de qualidade
+
+Antes de salvar o documento, passe por cada item. Se algum falhar, corrija antes de prosseguir:
+
+- [ ] Todas as perguntas do escopo foram respondidas
+- [ ] Claims críticos verificados em 2+ fontes independentes
+- [ ] Claims negativos ("X não suporta Y") verificados com docs oficiais
+- [ ] Nenhuma afirmação baseada apenas em training data sem marcação
+- [ ] URLs presentes para todas as fontes autoritativas
+- [ ] Confiabilidade (alta/media/baixa) atribuída a cada fonte
+- [ ] Contradições entre fontes documentadas explicitamente
+- [ ] Seção "Não Reinvente a Roda" incluída (quando relevante)
+- [ ] Seção "Armadilhas" incluída (quando relevante)
+- [ ] Conclusão é acionável — dá uma direção clara
+- [ ] Revisão final: "O que posso ter deixado passar?"
+
+## O que você entrega
+
+1. Leia o template de `.hefesto/templates/RESEARCH.md` para a estrutura base
+2. Crie `.hefesto/research/RES-NNN-slug.md` preenchido com as descobertas
+3. No frontmatter, defina `status: done`
+4. Atualize `.hefesto/config.json` incrementando `research.counter`
+5. Atualize `.hefesto/STATE.md` mencionando a pesquisa concluída
+6. Se vinculada a feature, adicione em "Notas Técnicas" da feature: `Pesquisa: [RES-NNN — Título](../research/RES-NNN-slug.md)`
+
+Retorne:
+
+- Caminho do arquivo criado
+- Resumo em 2-3 frases com as principais descobertas e a recomendação
+
+## Regras
+
+- Todos os textos no documento devem ser em Português BR
+- Organize por tema, não por fonte — isso é o que torna a pesquisa realmente útil
+- Se WebSearch/WebFetch não estiverem disponíveis, informe e peça ao usuário para fornecer URLs manualmente
+- Nunca invente fontes ou URLs — se não encontrou, diga que não encontrou
+- Para `tech-eval`, a tabela comparativa não é opcional — é o core do entregável
+- Se uma fonte é de baixa confiabilidade, marque como tal em vez de omiti-la — transparência é mais útil que curadoria silenciosa
+- Se seu training data contradiz as fontes verificadas, as fontes vencem — atualize sua conclusão
+- IDs são sequenciais e nunca reutilizados

package/bin/install.js

@@ -149,6 +149,7 @@ function createDefaultConfig() {
     project: { name: '', language: 'pt-BR' },
     runtime: 'claude',
     feature: { id_prefix: 'FEAT', counter: 0 },
+    research: { id_prefix: 'RES', counter: 0 },
     lifecycle: { auto_update_state: true },
   };
 }
@@ -168,6 +169,7 @@ function installHefesto() {
   } else {
     ensureDir(hefestoDir);
     ensureDir(path.join(hefestoDir, 'features'));
+    ensureDir(path.join(hefestoDir, 'research'));
 
     // Copiar templates como arquivos iniciais do projeto
     const templateFiles = ['PROJECT.md', 'STATE.md', 'ROADMAP.md'];
@@ -221,6 +223,14 @@ function installRuntime(runtime) {
     console.log(`  ✅ Skills instaladas em ${path.relative(process.cwd(), destSkills) || destSkills}`);
   }
 
+  // Agents
+  const srcAgents = path.join(PKG_ROOT, 'agents');
+  if (fs.existsSync(srcAgents)) {
+    const destAgents = path.join(runtimeDir, 'agents');
+    copyAgents(srcAgents, destAgents);
+    console.log(`  ✅ Agents instalados em ${path.relative(process.cwd(), destAgents) || destAgents}`);
+  }
+
   // Hooks (apenas Claude Code por enquanto)
   if (runtime === 'claude') {
     installHooks(runtimeDir);
@@ -253,6 +263,22 @@ function copySkills(srcDir, destDir) {
   }
 }
 
+function copyAgents(srcDir, destDir) {
+  ensureDir(destDir);
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith('hefesto-')) {
+      const srcAgent = path.join(srcDir, entry.name);
+      const destAgent = path.join(destDir, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcAgent, destAgent);
+      } else {
+        fs.copyFileSync(srcAgent, destAgent);
+      }
+    }
+  }
+}
+
 // ── Hooks ───────────────────────────────────────────────────────────────────
 
 function installHooks(runtimeDir) {
@@ -395,6 +421,23 @@ function uninstallRuntime(runtime) {
     }
   }
 
+  // Remover agents hefesto-*
+  const agentsDir = path.join(runtimeDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const agentEntries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of agentEntries) {
+      if (entry.name.startsWith('hefesto-')) {
+        const agentPath = path.join(agentsDir, entry.name);
+        if (entry.isDirectory()) {
+          fs.rmSync(agentPath, { recursive: true });
+        } else {
+          fs.unlinkSync(agentPath);
+        }
+        console.log(`  ✅ Agent ${entry.name} removido.`);
+      }
+    }
+  }
+
   // Remover hooks (apenas Claude Code)
   if (runtime === 'claude') {
     uninstallHooks(runtimeDir);

package/commands/hefesto/init.md

@@ -21,7 +21,8 @@ Inicializa a estrutura `.hefesto/` no projeto atual.
    ├── ROADMAP.md
    ├── STATE.md
    ├── config.json
-   └── features/
+   ├── features/
+   └── research/
    ```
 4. Preencher PROJECT.md com as respostas do usuário.
 5. Gerar STATE.md inicial com posição "Inicializando".
@@ -33,13 +34,34 @@ Inicializa a estrutura `.hefesto/` no projeto atual.
      "project": { "name": "", "language": "pt-BR" },
      "runtime": "claude",
      "feature": { "id_prefix": "FEAT", "counter": 0 },
+     "research": { "id_prefix": "RES", "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.
+9. Verificar se o MCP Context7 está configurado (checar se `.mcp.json` existe e contém `context7`). Se não estiver, sugerir a instalação:
+
+   ```
+   O Hefesto usa o Context7 para consultar documentação atualizada de bibliotecas
+   durante pesquisas. Para habilitar, adicione ao .mcp.json do projeto:
+   ```
+
+   ```json
+   {
+     "mcpServers": {
+       "context7": {
+         "command": "npx",
+         "args": ["-y", "@upstash/context7-mcp"]
+       }
+     }
+   }
+   ```
+
+   Se o usuário quiser instalar, criar ou atualizar o `.mcp.json` adicionando a entrada do Context7 (preservando outros MCPs existentes). Se não quiser, seguir sem — o Context7 é opcional.
 
 ## 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.
+- O Context7 é opcional mas recomendado — melhora a qualidade das pesquisas com docs versionados.

package/commands/hefesto/status.md

@@ -31,10 +31,16 @@ Features:
   📋 FEAT-004 — Título (ready)
   📝 FEAT-005 — Título (draft)
 
+Pesquisas: 2 concluídas, 1 em andamento
+  🔍 RES-001 — Avaliação de ORMs (done)
+  🔍 RES-002 — Padrões de autenticação (done)
+  🔄 RES-003 — APIs de pagamento (in-progress)
+
 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.
+5. Listar pesquisas em `.hefesto/research/` com seus status (ler frontmatter de cada arquivo).
+6. Se houver bloqueios em STATE.md, destacá-los.
+7. Sugerir próxima ação com base no estado atual.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lugom.io/hefesto",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, Gemini and Codex by lugom.io.",
   "type": "module",
   "bin": {

package/skills/hefesto-context/SKILL.md

@@ -15,8 +15,10 @@ O Hefesto é um toolkit spec-driven + story-driven que organiza o desenvolviment
 ├── 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/               # Documentos narrativos unificados
+│   └── FEAT-NNN-slug.md    # Uma feature por arquivo
+└── research/               # Pesquisas estruturadas
+    └── RES-NNN-slug.md     # Uma pesquisa por arquivo
 ```
 
 ## Features
@@ -55,6 +57,15 @@ Memória viva do projeto. Máximo ~80 linhas. Contém:
 - Bloqueios
 - Informação de 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.
+
+- **ID**: `RES-NNN` (zero-padded, counter em `config.json` → `research.counter`)
+- **Status**: `draft` → `in-progress` → `done`
+- **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/`
+
 ## 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.
@@ -64,3 +75,4 @@ Outputs reais (código, documentos, manifestos) vão para o projeto (src/, docs/
 - `/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)

package/templates/RESEARCH.md

@@ -0,0 +1,90 @@
+---
+id: {{RESEARCH_ID}}
+title: "{{RESEARCH_TITLE}}"
+type: {{RESEARCH_TYPE}}
+depth: {{RESEARCH_DEPTH}}
+status: draft
+feature: {{LINKED_FEATURE}}
+created: {{DATE}}
+updated: {{DATE}}
+---
+
+# {{RESEARCH_ID}}: {{RESEARCH_TITLE}}
+
+## Objetivo
+
+{{RESEARCH_OBJECTIVE}}
+
+## Contexto
+
+{{RESEARCH_CONTEXT}}
+
+## Escopo
+
+**Perguntas a responder:**
+
+1. {{QUESTION_1}}
+2. {{QUESTION_2}}
+3. {{QUESTION_3}}
+
+**Fora do escopo:**
+
+- {{EXCLUSION_1}}
+
+## Descobertas
+
+### {{FINDING_TITLE_1}}
+
+{{FINDING_CONTENT}}
+
+**Fonte:** [{{SOURCE_TITLE}}]({{SOURCE_URL}}) — Confiabilidade: {{CONFIDENCE}}
+
+### {{FINDING_TITLE_2}}
+
+{{FINDING_CONTENT}}
+
+**Fonte:** [{{SOURCE_TITLE}}]({{SOURCE_URL}}) — Confiabilidade: {{CONFIDENCE}}
+
+## Comparativo
+
+| Critério | {{OPTION_A}} | {{OPTION_B}} | {{OPTION_C}} |
+| -------- | ------------ | ------------ | ------------ |
+| —        | —            | —            | —            |
+
+## Não Reinvente a Roda
+
+| Problema | Solução pronta | Por que não fazer na mão |
+| -------- | -------------- | ------------------------ |
+| —        | —              | —                        |
+
+## Estado da Arte
+
+| Antes | Agora | Por quê mudou |
+| ----- | ----- | ------------- |
+| —     | —     | —             |
+
+## Armadilhas
+
+| Severidade | Armadilha | Se ignorar | Prevenção |
+| ---------- | --------- | ---------- | --------- |
+| Crítico    | —         | —          | —         |
+| Moderado   | —         | —          | —         |
+| Menor      | —         | —          | —         |
+
+## Fontes
+
+| # | Título | URL | Confiabilidade |
+| - | ------ | --- | -------------- |
+| 1 | —      | —   | alta           |
+
+## Conclusão
+
+{{CONCLUSION}}
+
+## Recomendação
+
+{{RECOMMENDATION}}
+
+## Notas
+
+{{NOTES}}