@lugom.io/hefesto 0.2.0 → 1.0.0

package/skills/hefesto-simplify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: hefesto-simplify
+description: >
+  Revisão de código para reuso, qualidade e eficiência. Corrige issues preservando funcionalidade.
+  ATIVAR quando: "simplificar", "refatorar", "code review", "código duplicado", "limpar código",
+  "otimizar", "extrair pra lib", "checar qualidade", "código repetido", "performance".
+  Também: revisar reuso de utilitários, code smells, leaky abstractions, memory leaks.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: '[arquivos ou escopo opcional]'
+---
+
+# Hefesto Simplify
+
+Revisão de código modificado focada em reuso, qualidade e eficiência. Corrige issues encontradas preservando funcionalidade.
+
+## Fase 1 — Identificar Escopo
+
+Rodar `git diff` (ou `git diff HEAD` se houver staged changes) para ver o que mudou. Determinar o escopo:
+
+1. Se argumentos foram fornecidos (paths de arquivos), usar esses arquivos como escopo
+2. Senão, identificar a feature ativa:
+   - Ler `.hefesto/STATE.md` → seção "Feature Ativa"
+   - Se houver feature ativa, ler o frontmatter do arquivo da feature em `.hefesto/features/`
+   - Usar `git diff --name-only` para listar arquivos modificados e não comitados
+3. Fallback: `git diff --name-only HEAD~1`
+4. Se nenhuma mudança no git, revisar os arquivos mais recentemente modificados que o usuário mencionou ou que foram editados anteriormente na conversa
+5. Filtrar: incluir apenas arquivos de código-fonte (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, etc.). Excluir: `node_modules/`, `.next/`, `dist/`, `build/`, arquivos de configuração, lockfiles, testes, arquivos gerados
+
+## Fase 2 — Lançar Três Agentes de Revisão em Paralelo
+
+Usar a ferramenta Agent para lançar os três agentes concorrentemente em uma única mensagem. Passar para cada agente o diff completo para que tenha o contexto completo.
+
+### Agent 1: Code Reuse Review
+
+Para cada mudança:
+
+1. **Buscar utilitários e helpers existentes** que possam substituir código recém-escrito. Procurar padrões similares em outros lugares do codebase — locais comuns são diretórios de utilitários, módulos compartilhados e arquivos adjacentes aos modificados
+2. **Flaggar qualquer função nova que duplica funcionalidade existente.** Sugerir a função existente para usar no lugar
+3. **Flaggar lógica inline que poderia usar utilitário existente** — manipulação de string manual, path handling customizado, checks de ambiente ad-hoc, type guards manuais e padrões similares são candidatos comuns
+4. **Duplicação cross-feature**: para funções exportadas nos arquivos do escopo, grep pelo nome em todo o projeto (excluindo o arquivo de origem). Se encontrar implementação idêntica ou muito similar em outro local, flaggar e sugerir extração para módulo compartilhado
+5. **Helpers não externalizados**: identificar funções helper definidas dentro de componentes/módulos que não dependem de state/props local e são genéricas o suficiente para compartilhar. Verificar se já existe algo similar nos diretórios compartilhados do projeto
+
+### Agent 2: Code Quality Review
+
+Revisar as mesmas mudanças para padrões problemáticos:
+
+1. **Redundant state**: state que duplica state existente, valores cacheados que poderiam ser derivados, observers/effects que poderiam ser chamadas diretas
+2. **Parameter sprawl**: adicionar novos parâmetros a uma função ao invés de generalizar ou reestruturar os existentes
+3. **Copy-paste com variação leve**: blocos de código near-duplicate que deveriam ser unificados com uma abstração compartilhada
+4. **Leaky abstractions**: expor detalhes internos que deveriam ser encapsulados, ou quebrar boundaries de abstração existentes
+5. **Stringly-typed code**: usar strings raw onde constants, enums (string unions) ou branded types já existem no codebase
+6. **Unnecessary JSX nesting**: wrapper Boxes/elements que não adicionam valor de layout — verificar se props do componente interno (flexShrink, alignItems, etc.) já fornecem o comportamento necessário
+7. **Unnecessary comments**: comentários explicando O QUE o código faz (identificadores bem nomeados já fazem isso), narrando a mudança, ou referenciando task/caller — deletar; manter apenas WHY não óbvio (constraints escondidas, invariantes sutis, workarounds)
+8. **Ternários aninhados**: substituir por `if/else` ou `switch`. Um nível de ternário é ok; dois ou mais precisa simplificar
+9. **Nesting excessivo**: funções com mais de 3 níveis de indentação. Aplicar early return ou extrair subfunção
+10. **Código morto**: imports não usados, variáveis declaradas mas não referenciadas, branches de condição inalcançáveis
+11. **Nomes pouco descritivos**: variáveis de 1-2 letras (exceto iteradores `i`, `j`), nomes genéricos como `data`, `temp`, `result` quando o contexto permite ser mais específico
+12. **Abstrações prematuras**: wrappers que apenas chamam outra função sem adicionar lógica, abstrações de uso único (classes, interfaces, factories usadas por apenas um consumidor), configurabilidade excessiva (parâmetros que só têm um valor possível)
+13. **Padrões do projeto**: ler `CLAUDE.md` e `.hefesto/PROJECT.md` (se existir). Comparar código do escopo contra convenções estabelecidas — imports, naming conventions, error handling, estrutura de features. Reportar desvios
+
+### Agent 3: Efficiency Review
+
+Revisar as mesmas mudanças para eficiência:
+
+1. **Trabalho desnecessário**: computações redundantes, leituras de arquivo repetidas, chamadas de rede/API duplicadas, padrões N+1
+2. **Concorrência perdida**: operações independentes executadas sequencialmente quando poderiam ser paralelas
+3. **Hot-path bloat**: novo trabalho bloqueante adicionado a startup ou hot paths per-request/per-render
+4. **Updates recorrentes no-op**: updates de state/store dentro de polling loops, intervals, ou event handlers que disparam incondicionalmente — adicionar guard de change-detection para que consumidores downstream não sejam notificados quando nada mudou. Também: se uma função wrapper recebe um callback updater/reducer, verificar que respeita retornos same-reference (ou qualquer que seja o sinal de "sem mudança") — senão, early-return no-ops dos callers são silenciosamente derrotados
+5. **Checks de existência desnecessários**: verificar existência de arquivo/recurso antes de operar (anti-pattern TOCTOU) — operar diretamente e tratar o erro
+6. **Memory**: data structures unbounded, cleanup faltando, event listener leaks
+7. **Operações broad demais**: ler arquivos inteiros quando apenas uma porção é necessária, carregar todos os items quando filtrando por um
+
+## Fase 3 — Aplicar Correções
+
+Aguardar os três agentes completarem. Agregar os findings e corrigir cada issue diretamente. Se um finding é false positive ou não vale a pena endereçar, anotar e seguir em frente — não argumentar com o finding, apenas pular.
+
+Restrições: não modificar configs/testes/gerados, respeitar boundaries de packages em monorepo, rodar `verification.commands` após fixes.
+
+Relatório via `TPL-SIMPLIFY.md`. Omitir dimensões sem issues. Código limpo → confirmar sem relatório.
+
+Funciona sem `.hefesto/` (usa `git diff` e `CLAUDE.md`). Se invocado pelo `/hefesto-execute`, relatório vai para o Argos.

package/templates/TPL-CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+Este arquivo orienta o Claude Code (claude.ai/code) ao trabalhar com o código deste repositório.
+
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Comandos
+
+{{COMMANDS}}
+
+## Arquitetura
+
+{{ARCHITECTURE}}
+
+## Convenções
+
+{{CONVENTIONS}}
+
+## Idioma
+
+- Comunicação com o usuário: Português BR
+- Identificadores de código: Inglês
+
+## Hefesto
+
+Este projeto usa o [Hefesto](https://www.npmjs.com/package/@lugom.io/hefesto) para gestão de features e desenvolvimento feature-driven.
+
+### Estrutura .hefesto/
+
+- `PROJECT.md` — Visão, restrições, features e decisões
+- `STATE.md` — Memória entre sessões (manter < 80 linhas)
+- `config.json` — Configuração e counters
+- `features/` — Documentos de feature (FEAT-NNN-slug.md)
+- `research/` — Documentos de pesquisa (RES-NNN-slug.md)
+- `DESIGN.md` — Contrato visual (cores, tipografia, componentes, tokens)
+
+### Skills disponíveis
+
+- `/hefesto-init` — Inicializar ou atualizar configuração do projeto
+- `/hefesto-new-feature` — Criar nova feature
+- `/hefesto-execute` — Executar implementação de feature (verificação + QA loop)
+- `/hefesto-debug` — Debugging sistemático (causa raiz → hipótese → fix)
+- `/hefesto-design` — Criar contrato visual do projeto
+- `/hefesto-security` — Auditoria de segurança (OWASP, secrets, boundaries)
+- `/hefesto-simplify` — Simplificação e reuso de código
+
+### Workflow
+
+1. Features seguem o ciclo: `draft` → `ready` → `active` → `done`
+2. Cada feature tem Fases de implementação (stories atômicas)
+3. `STATE.md` é atualizado a cada mudança de estado
+4. IDs são sequenciais e nunca reutilizados

package/templates/TPL-CONFIG.json

@@ -0,0 +1,19 @@
+{
+  "version": "{{HEFESTO_VERSION}}",
+  "project": {
+    "name": "",
+    "description": "",
+    "language": "pt-BR",
+    "platform": "",
+    "lang": "",
+    "monorepo": false
+  },
+  "runtime": "claude",
+  "feature": { "id_prefix": "FEAT", "counter": 0 },
+  "research": { "id_prefix": "RES", "counter": 0 },
+  "design": { "status": "none" },
+  "verification": {
+    "commands": [],
+    "auto_detect": true
+  }
+}

package/templates/TPL-DESIGN.md

@@ -0,0 +1,305 @@
+# {{DESIGN_NAME}}
+
+{{DESIGN_DESCRIPTION}}
+
+## Overview
+
+{{DESIGN_OVERVIEW}}
+
+## Colors
+
+### Brand Palette
+
+| Token     | Hex       | Role     |
+| --------- | --------- | -------- |
+| Primary   | `{{HEX}}` | {{ROLE}} |
+| Secondary | `{{HEX}}` | {{ROLE}} |
+| Tertiary  | `{{HEX}}` | {{ROLE}} |
+
+### Surface Palette
+
+| Token          | Hex       | Role     |
+| -------------- | --------- | -------- |
+| Background     | `{{HEX}}` | {{ROLE}} |
+| Surface        | `{{HEX}}` | {{ROLE}} |
+| Surface Raised | `{{HEX}}` | {{ROLE}} |
+
+### Content Palette
+
+| Token          | Hex       | Role     |
+| -------------- | --------- | -------- |
+| Text Primary   | `{{HEX}}` | {{ROLE}} |
+| Text Secondary | `{{HEX}}` | {{ROLE}} |
+| Text Tertiary  | `{{HEX}}` | {{ROLE}} |
+
+### Border Palette
+
+| Token         | Hex       |
+| ------------- | --------- |
+| Border Subtle | `{{HEX}}` |
+| Border Medium | `{{HEX}}` |
+| Border Strong | `{{HEX}}` |
+
+### Semantic Colors
+
+| Token   | Hex       |
+| ------- | --------- |
+| Success | `{{HEX}}` |
+| Warning | `{{HEX}}` |
+| Error   | `{{HEX}}` |
+| Info    | `{{HEX}}` |
+
+## Typography
+
+### Font Stack
+
+| Role             | Font             |
+| ---------------- | ---------------- |
+| Display/Headings | {{FONT_DISPLAY}} |
+| UI/Body          | {{FONT_BODY}}    |
+| Mono/Code        | {{FONT_MONO}}    |
+
+### Type Scale
+
+| Level      | Font     | Size     | Weight     | Line Height     | Letter Spacing     | Usage     |
+| ---------- | -------- | -------- | ---------- | --------------- | ------------------ | --------- |
+| Display    | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Headline   | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Subhead    | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Body Large | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Body       | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Body Small | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Caption    | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Overline   | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+| Code       | {{FONT}} | {{SIZE}} | {{WEIGHT}} | {{LINE_HEIGHT}} | {{LETTER_SPACING}} | {{USAGE}} |
+
+## Spacing
+
+| Property                   | Value           |
+| -------------------------- | --------------- |
+| Base unit                  | {{BASE_UNIT}}px |
+| Scale                      | {{SCALE}}       |
+| Component padding — small  | {{PAD_SM}}px    |
+| Component padding — medium | {{PAD_MD}}px    |
+| Component padding — large  | {{PAD_LG}}px    |
+| Section spacing — mobile   | {{SPACE_MOB}}px |
+| Section spacing — tablet   | {{SPACE_TAB}}px |
+| Section spacing — desktop  | {{SPACE_DSK}}px |
+
+## Border Radius
+
+{{BORDER_RADIUS_PHILOSOPHY}}
+
+| Token  | Value             | Usage     |
+| ------ | ----------------- | --------- |
+| None   | {{RADIUS_NONE}}px | {{USAGE}} |
+| Small  | {{RADIUS_SM}}px   | {{USAGE}} |
+| Medium | {{RADIUS_MD}}px   | {{USAGE}} |
+| Large  | {{RADIUS_LG}}px   | {{USAGE}} |
+| XL     | {{RADIUS_XL}}px   | {{USAGE}} |
+| Full   | 9999px            | {{USAGE}} |
+
+## Shadows
+
+{{SHADOW_PHILOSOPHY}}
+
+| Level   | CSS Value        | Usage     |
+| ------- | ---------------- | --------- |
+| Subtle  | {{SHADOW_VALUE}} | {{USAGE}} |
+| Medium  | {{SHADOW_VALUE}} | {{USAGE}} |
+| Large   | {{SHADOW_VALUE}} | {{USAGE}} |
+| Overlay | {{SHADOW_VALUE}} | {{USAGE}} |
+
+{{SPECIAL_TREATMENTS}}
+
+## Motion
+
+{{MOTION_PHILOSOPHY}}
+
+| Property        | Value                 | Usage     |
+| --------------- | --------------------- | --------- |
+| Duration Fast   | {{DURATION_FAST}}ms   | {{USAGE}} |
+| Duration Normal | {{DURATION_NORMAL}}ms | {{USAGE}} |
+| Duration Slow   | {{DURATION_SLOW}}ms   | {{USAGE}} |
+| Easing Default  | {{EASING_DEFAULT}}    | {{USAGE}} |
+| Easing Enter    | {{EASING_ENTER}}      | {{USAGE}} |
+| Easing Exit     | {{EASING_EXIT}}       | {{USAGE}} |
+
+## Components
+
+### Buttons
+
+**Primary**
+
+- Background: `{{HEX}}`
+- Text: `{{HEX}}`
+- Border: {{BORDER}}
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Radius: {{RADIUS}}
+- Hover: {{HOVER_STATE}}
+- Active: {{ACTIVE_STATE}}
+
+**Secondary**
+
+- Background: {{BACKGROUND}}
+- Text: `{{HEX}}`
+- Border: {{BORDER}}
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Radius: {{RADIUS}}
+- Hover: {{HOVER_STATE}}
+- Active: {{ACTIVE_STATE}}
+
+**Ghost**
+
+- Background: transparent
+- Text: `{{HEX}}`
+- Border: none
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Radius: {{RADIUS}}
+- Hover: {{HOVER_STATE}}
+- Active: {{ACTIVE_STATE}}
+
+**Destructive**
+
+- Background: `{{HEX}}`
+- Text: `{{HEX}}`
+- Border: {{BORDER}}
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Radius: {{RADIUS}}
+- Hover: {{HOVER_STATE}}
+- Active: {{ACTIVE_STATE}}
+
+**Sizes:** Small {{SIZE_SM}} / Medium {{SIZE_MD}} / Large {{SIZE_LG}}
+
+**Disabled:** {{DISABLED_STATE}}
+
+### Cards
+
+**Default**
+
+- Background: `{{HEX}}`
+- Border: {{BORDER}}
+- Radius: {{RADIUS}}
+- Padding: {{PADDING}}
+- Shadow: {{SHADOW}}
+- Hover: {{HOVER_STATE}}
+
+**Elevated**
+
+- Background: `{{HEX}}`
+- Border: {{BORDER}}
+- Radius: {{RADIUS}}
+- Padding: {{PADDING}}
+- Shadow: {{SHADOW}}
+
+### Inputs
+
+**Text Input**
+
+- Height: {{INPUT_HEIGHT}}px
+- Background: `{{HEX}}`
+- Border: {{BORDER}}
+- Radius: {{RADIUS}}
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Text color: `{{HEX}}`
+- Placeholder color: `{{HEX}}`
+- Focus: {{FOCUS_STATE}}
+- Error: {{ERROR_STATE}}
+- Disabled: {{DISABLED_STATE}}
+
+**Label:** {{LABEL_SPEC}}
+
+**Helper Text:** {{HELPER_SPEC}}
+
+### Chips
+
+**Filter Chip**
+
+- Background: {{BACKGROUND}}
+- Border: {{BORDER}}
+- Radius: {{RADIUS}}
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Text: `{{HEX}}`
+- Selected: {{SELECTED_STATE}}
+
+**Status Chip**
+
+- Padding: {{PADDING}}
+- Font: {{FONT_SPEC}}
+- Radius: {{RADIUS}}
+- Success: {{SUCCESS_STATE}}
+- Warning: {{WARNING_STATE}}
+- Error: {{ERROR_STATE}}
+
+### Lists
+
+**Default List Item**
+
+- Padding: {{PADDING}}
+- Border bottom: {{BORDER}}
+- Font: {{FONT_SPEC}}
+- Text: `{{HEX}}`
+- Secondary text: {{SECONDARY_SPEC}}
+- Hover: {{HOVER_STATE}}
+- Active: {{ACTIVE_STATE}}
+- Leading element: {{LEADING_SPEC}}
+
+### Checkboxes
+
+- Size: {{CHECKBOX_SIZE}}px
+- Border: {{BORDER}}
+- Radius: {{RADIUS}}
+- Background: `{{HEX}}`
+- Checked: {{CHECKED_STATE}}
+- Indeterminate: {{INDETERMINATE_STATE}}
+- Hover: {{HOVER_STATE}}
+- Focus: {{FOCUS_STATE}}
+- Disabled: {{DISABLED_STATE}}
+- Label: {{LABEL_SPEC}}
+
+### Radio Buttons
+
+- Size: {{RADIO_SIZE}}px
+- Border: {{BORDER}}
+- Radius: 9999px
+- Background: `{{HEX}}`
+- Selected: {{SELECTED_STATE}}
+- Hover: {{HOVER_STATE}}
+- Focus: {{FOCUS_STATE}}
+- Disabled: {{DISABLED_STATE}}
+- Label: {{LABEL_SPEC}}
+
+### Tooltips
+
+- Background: `{{HEX}}`
+- Text: `{{HEX}}`
+- Font: {{FONT_SPEC}}
+- Padding: {{PADDING}}
+- Radius: {{RADIUS}}
+- Max width: {{TOOLTIP_MAX_WIDTH}}px
+- Arrow: {{ARROW_SPEC}}
+- Delay: {{DELAY_ENTER}}ms enter, {{DELAY_LEAVE}}ms leave
+- Shadow: {{SHADOW}}
+
+## Do's and Don'ts
+
+1. **Do** {{SPECIFIC_DO_1}}
+2. **Don't** {{SPECIFIC_DONT_1}}
+3. **Do** {{SPECIFIC_DO_2}}
+4. **Don't** {{SPECIFIC_DONT_2}}
+5. **Do** {{SPECIFIC_DO_3}}
+6. **Don't** {{SPECIFIC_DONT_3}}
+7. **Do** {{SPECIFIC_DO_4}}
+8. **Do** {{SPECIFIC_DO_5}}
+9. **Don't** {{SPECIFIC_DONT_4}}
+10. **Do** {{SPECIFIC_DO_6}}
+
+---
+
+_Gerado por /hefesto-design em {{DATE}}_

package/templates/{FEATURE.md → TPL-FEATURE.md}

@@ -1,11 +1,14 @@
 ---
-id: { { FEATURE_ID } }
-title: "{{FEATURE_TITLE}}"
+id: '{{FEATURE_ID}}'
+title: '{{FEATURE_TITLE}}'
 status: draft
-created: { { DATE } }
-updated: { { DATE } }
+created: '{{DATE}}'
+updated: '{{DATE}}'
 phases_total: 0
 phases_done: 0
+qa_iterations: 0
+last_verdict: null
+verification_commands: []
 ---
 
 # {{FEATURE_ID}}: {{FEATURE_TITLE}}
@@ -33,14 +36,18 @@ phases_done: 0
 
 ### Fase 1: {{PHASE_1_NAME}}
 
+**Requisitos:** {{REQ_IDS}}
+
 **Arquivos:**
 
 - `{{FILE_PATH}}` — {{FILE_DESCRIPTION}}
 
 **Tarefas:**
 
-- [ ] {{TASK_1}}
-- [ ] {{TASK_2}}
+- [ ] **{{TASK_1}}**
+      Arquivo: `{{FILE_PATH}}`
+      Verificar: `{{VERIFY_COMMAND}}`
+- [ ] **{{TASK_2}}**
 
 **Critérios de Aceitação:**
 

package/templates/TPL-PROJECT.md

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}}
+
+## O Que É
+
+{{PROJECT_DESCRIPTION}}
+
+## Valor Central
+
+{{CORE_VALUE}}
+
+## Contexto
+
+{{CONTEXT}}
+
+## Restrições
+
+- **Stack**: {{STACK_CONSTRAINT}}
+- **Prazo**: {{DEADLINE_CONSTRAINT}}
+
+## Convenções
+
+{{CONVENTIONS}}
+
+## 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
+
+## Receitas Disponíveis
+
+{{RECIPES}}
+
+## Decisões
+
+| Decisão | Justificativa | Resultado |
+| ------- | ------------- | --------- |
+| —       | —             | —         |
+
+---
+
+_Última atualização: {{DATE}}_

package/templates/TPL-RECON.md

@@ -0,0 +1,60 @@
+## Reconhecimento: {{FEATURE_ID}} — {{FEATURE_TITLE}}
+
+profundidade: {{DEPTH}}
+
+### 1. Estrutura Relevante
+
+(árvore de diretórios mostrando APENAS o que importa para a feature)
+
+```
+{{RELEVANT_TREE}}
+```
+
+(descrição do que cada arquivo faz e por que é relevante)
+
+### 2. Padrões a Seguir
+
+Para cada tipo de artefato que a feature precisa criar:
+
+**{{ARTIFACT_TYPE}}** — baseado em `{{EXAMPLE_PATH}}:{{LINES}}`
+
+- Convenção: {{CONVENTION}}
+- Imports: {{IMPORTS}}
+- Exemplo real: (trecho de código copiado do codebase)
+
+### 3. Pontos de Integração
+
+| Arquivo         | Ação      | O que fazer | Linha     |
+| --------------- | --------- | ----------- | --------- |
+| `{{FILE_PATH}}` | modificar | {{ACTION}}  | :{{LINE}} |
+| `{{FILE_PATH}}` | criar     | {{ACTION}}  | —         |
+
+### 4. Dependências e Riscos
+
+**Consumers** (importam o que vai mudar):
+
+- `{{FILE_PATH}}:{{LINE}}` importa `{{MODULE}}`
+
+**Testes adjacentes**:
+
+- `{{TEST_PATH}}` — {{RELEVANCE}}
+
+**Configs**:
+
+- `{{CONFIG_FILE}}` precisa de `{{NEW_ENTRY}}`
+
+**Riscos**:
+
+- Risco: {{RISK}} → Mitigação: {{MITIGATION}}
+
+### 5. Ordem de Ataque
+
+1. **{{TASK_1}}** — {{REASON}} (desbloqueia {{WHAT}})
+2. **{{TASK_2}}** — {{REASON}}
+3. **{{TASK_3}}** — pode ser paralelo com {{N}}
+4. **{{TASK_4}}** — deixar por último ({{REASON}})
+
+### 6. Perguntas Abertas
+
+- {{OPEN_QUESTION_1}}
+- {{OPEN_QUESTION_2}}