@lugom.io/hefesto 0.3.0 → 1.0.0

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)

package/skills/hefesto-init/SKILL.md

@@ -1,70 +1,105 @@
 ---
 name: hefesto-init
-description: "Inicializa o Hefesto no projeto atual. Use /hefesto-init para criar a estrutura .hefesto/ e começar a organizar o desenvolvimento."
+description: >
+  Inicializa um projeto com Hefesto. Dois modos: (1) projeto novo — scaffold com stack
+  pré-definida (web/cli/api/mobile); (2) projeto existente — analisa codebase, cria .hefesto/
+  e gera CLAUDE.md.
+  Usar com: /hefesto-init.
 user-invocable: true
 disable-model-invocation: true
 ---
 
 # 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/
-   └── research/
-   ```
-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 },
-     "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.
+Inicializa um projeto com a estrutura `.hefesto/`, gera `CLAUDE.md` e, opcionalmente, faz scaffold do código base. Para projetos existentes, faz uma varredura automática do codebase para detectar stack, plataforma, convenções e comandos.
+
+## Fluxo
+
+### Fase 1 — Verificar estado
+
+1. Verificar se `.hefesto/` já existe (`Bash: ls .hefesto/ 2>/dev/null`)
+2. Se existir:
+   - Ler `.hefesto/PROJECT.md` — se contém `{{PROJECT_NAME}}` → install fresco, prosseguir
+   - Senão → já configurado. Seletor: **Reinicializar** (apaga e recria, avisa sobre features existentes) / **Atualizar** (re-varredura, preserva features/) / **Cancelar**
+3. Se não existir → Fase 2
+
+### Fase 2 — Tipo de projeto
+
+Seletor: **Novo** → Fase 3A | **Existente** → Fase 3B.1
+
+### Fase 3A — Scaffold de projeto novo
+
+1. Seletor de **plataforma**:
+   - `web` — Next.js + TypeScript + TailwindCSS + shadcn/ui
+   - `cli` — Node.js + TypeScript + ES Modules
+   - `api` — Node.js + TypeScript + Fastify
+   - `mobile` — React Native + Expo + NativeWind
+
+2. Ler `references/{plataforma}.md` (relativo a esta skill)
+3. Executar scaffold conforme a referência
+4. Coletar do usuário: **Nome** (sugerir dir atual), **Descrição** (2-3 frases), **Valor central**, **Prazo/restrições**
+
+### Fase 3B.1 — Varredura do codebase
+
+Análise rápida (~10 reads) para detectar informações do projeto:
+
+**Passo 1 — Manifesto**: Glob por `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, `pubspec.yaml`. Se nenhum → modo manual (Fase 3B.2).
+
+**Passo 2 — Identidade**: Nome, descrição, dependências, scripts do manifesto. Fallback: README.md (primeiras 30 linhas).
+
+**Passo 3 — Linguagem** (por prioridade): tsconfig.json → TypeScript | jsconfig.json/package.json → JavaScript | pyproject.toml/requirements.txt → Python | go.mod → Go | Cargo.toml → Rust | Gemfile → Ruby | pubspec.yaml → Dart. Se ambíguo, contar arquivos por extensão.
+
+**Passo 4 — Plataforma**: Inferir das dependências — frameworks web → `web`, react-native/expo → `mobile`, express/fastify/flask/etc sem frontend → `api`, campo bin → `cli`, exports sem bin/web → `library`, frontend + backend → `fullstack`, nenhum → `other`.
+
+**Passo 5 — Monorepo**: workspaces em package.json, lerna.json, nx.json, turbo.json, pnpm-workspace.yaml.
+
+**Passo 6 — Comandos**: Extrair de package.json scripts (dev, build, test, lint, format) ou Makefile.
+
+**Passo 7 — Arquitetura**: Listar dirs em `src/` — features/modules/domains → feature-based | controllers/services/models → layered | app/pages → file-based routing. Detectar formatação: Prettier, ESLint, Biome, EditorConfig.
+
+### Fase 3B.2 — Confirmação
+
+Apresentar resultado da varredura em tabela (Campo | Detectado | Fonte). O usuário confirma ou ajusta.
+
+Perguntar apenas o não-detectável: **Valor central** (sempre), **Prazo** (sempre), **Descrição** (se não detectada). Se varredura pulada, coletar tudo manualmente.
+
+### Fase 4 — Criar estrutura .hefesto/
+
+Criar os artefatos listados em `/hefesto-context` (seção "Estrutura `.hefesto/`"): `PROJECT.md`, `STATE.md`, `config.json`, `features/`, `research/`.
+
+### Fase 5 — Preencher arquivos
+
+Ler os templates em `.hefesto/templates/TPL-*.md` (já copiados pelo instalador) e substituir os placeholders `{{...}}` com os dados coletados.
+
+**PROJECT.md**: Dados do projeto, valor central, stack, convenções. Para projetos novos, copiar convenções do reference file. Para existentes, gerar da varredura. Preencher `{{RECIPES}}` com a seção "Receitas" do reference file do preset — lista curta com nome e quando usar cada receita.
+
+**STATE.md**: Data e foco inicial.
+
+**config.json**: Atualizar seção `project` (name, description, platform, lang, monorepo). Valores vêm do preset (novos) ou da varredura (existentes). Não alterar demais seções.
+
+**verification.commands**: Preencher com comandos detectados (test, lint, typecheck). Para projetos novos, usar padrão do preset. Se nada detectado, deixar vazio com `auto_detect: true`.
+
+### Fase 5B — Gerar CLAUDE.md
+
+Ler template `TPL-CLAUDE.md` e substituir placeholders com dados coletados.
+
+Se CLAUDE.md existir: seletor **Substituir** / **Mesclar** (adicionar seção Hefesto) / **Pular**.
+
+Para projetos novos: usar dados do reference file. Para existentes: usar resultado da varredura.
+
+Princípios: conciso, sem repetição do PROJECT.md, sem obviedades, comandos acionáveis.
+
+### Fase 6 — MCP Context7
+
+Se o projeto usa dependências externas (frameworks, bibliotecas, SDKs): verificar `.mcp.json` para `context7`. Se não existir, sugerir configuração para o usuário. Se o projeto não tem dependências externas, pular.
+
+### Fase 7 — Resultado
+
+Informar o que foi criado. Sugerir `/hefesto-new-feature`. Se plataforma `web` ou `mobile`, sugerir também `/hefesto-design` para definir o contrato visual.
 
 ## 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.
+- Se usuário disser "decide você", fazer escolha razoável e justificar
+- **Atualizar**: não executar scaffold, apenas re-varredura + update dos arquivos .hefesto/
+- Varredura deve ser rápida (~10 reads)
+- CLAUDE.md gerado deve ser conciso — apenas o não derivável do código

package/skills/hefesto-init/references/api.md

@@ -0,0 +1,116 @@
+# Preset: API
+
+## Stack
+
+- Node.js + TypeScript
+- Fastify
+- ES Modules
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Inicializar projeto
+
+```bash
+pnpm init
+```
+
+### 2. Configurar package.json
+
+Editar o `package.json` gerado:
+
+- Adicionar `"type": "module"`
+- Adicionar scripts:
+  ```json
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  }
+  ```
+
+### 3. Instalar dependências
+
+```bash
+pnpm add fastify
+pnpm add -D typescript @types/node tsx
+```
+
+### 4. Criar tsconfig.json
+
+Criar `tsconfig.json` com:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 5. Criar estrutura de diretórios e arquivos
+
+```
+src/
+├── server.ts
+└── routes/
+    └── health.ts
+```
+
+### 6. Criar src/server.ts
+
+```typescript
+import Fastify from 'fastify';
+import { healthRoutes } from './routes/health.js';
+
+const app = Fastify({ logger: true });
+
+app.register(healthRoutes);
+
+app.listen({ port: 3000, host: '0.0.0.0' }, (err) => {
+  if (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+});
+```
+
+### 7. Criar src/routes/health.ts
+
+```typescript
+import { FastifyInstance } from 'fastify';
+
+export async function healthRoutes(app: FastifyInstance) {
+  app.get('/health', async () => {
+    return { status: 'ok' };
+  });
+}
+```
+
+### 8. Estrutura resultante esperada
+
+```
+src/
+├── server.ts
+└── routes/
+    └── health.ts
+tsconfig.json
+package.json
+```
+
+## config.json
+
+- platform: "api"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-init/references/cli.md

@@ -0,0 +1,91 @@
+# Preset: CLI
+
+## Stack
+
+- Node.js + TypeScript
+- ES Modules
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Inicializar projeto
+
+```bash
+pnpm init
+```
+
+### 2. Configurar package.json
+
+Editar o `package.json` gerado:
+
+- Adicionar `"type": "module"`
+- Adicionar campo `"bin"`: `{ "<nome-do-projeto>": "./dist/cli.js" }`
+- Adicionar scripts:
+  ```json
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js"
+  }
+  ```
+
+### 3. Instalar TypeScript
+
+```bash
+pnpm add -D typescript @types/node
+```
+
+### 4. Criar tsconfig.json
+
+Criar `tsconfig.json` com:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 5. Criar estrutura de diretórios e arquivos
+
+```
+src/
+└── cli.ts              ← entry point
+```
+
+### 6. Criar src/cli.ts
+
+```typescript
+#!/usr/bin/env node
+
+console.log('<nome-do-projeto> v0.1.0');
+```
+
+Substituir `<nome-do-projeto>` pelo nome real do projeto.
+
+### 7. Estrutura resultante esperada
+
+```
+src/
+└── cli.ts
+tsconfig.json
+package.json
+```
+
+## config.json
+
+- platform: "cli"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-init/references/mobile.md

@@ -0,0 +1,69 @@
+# Preset: Mobile
+
+## Stack
+
+- React Native + Expo + TypeScript
+- Expo Router (navegação file-based)
+- NativeWind (TailwindCSS para React Native)
+
+## Scaffold
+
+### 1. Criar projeto Expo
+
+```bash
+npx create-expo-app@latest . --template tabs
+```
+
+Se o diretório não estiver vazio, apresentar ao usuário via seletor interativo: **Criar num subdiretório** / **Limpar primeiro**.
+
+### 2. Instalar NativeWind
+
+```bash
+npx expo install nativewind tailwindcss
+```
+
+### 3. Configurar TailwindCSS
+
+Criar `tailwind.config.js`:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
+  presets: [require('nativewind/preset')],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+Adicionar o plugin do NativeWind no `babel.config.js` (se existir) ou em `metro.config.js` conforme a documentação do NativeWind para a versão instalada.
+
+### 4. Limpar boilerplate
+
+- Simplificar as tabs de exemplo — manter a estrutura mas substituir o conteúdo.
+- Substituir o conteúdo da tab Home por uma tela limpa com o nome do projeto centralizado.
+- Remover assets de exemplo desnecessários.
+
+### 5. Estrutura resultante esperada
+
+```
+app/
+├── (tabs)/
+│   ├── index.tsx         ← Home limpa com nome do projeto
+│   ├── _layout.tsx       ← Tab layout
+│   └── explore.tsx       ← Tab secundária
+├── _layout.tsx           ← Root layout
+└── +not-found.tsx
+assets/
+components/
+constants/
+hooks/
+```
+
+## config.json
+
+- platform: "mobile"
+- lang: "typescript"
+- monorepo: false