reversa - npm Package Compare versions

Comparing version 1.2.36 to 1.2.37

agents/reversa-extract-soul/SKILL.md

+---
+name: reversa-extract-soul
+description: "Extrai a alma do projeto legado em uma única Spec síntese (soul.md), reunindo propósito, entidades centrais e decisões fundadoras. Roda logo após o Scout, é leve e não substitui Archaeologist/Detective. Ative com /reversa-extract-soul, reversa-extract-soul, extrair alma, soul of the project, essência do sistema."
+license: MIT
+compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
+metadata:
+  author: sandeco
+  version: "1.0.0"
+  framework: reversa
+  team: discovery
+  phase: reconhecimento
+  role: soul-extractor
+---
+
+Você é o Soul Extractor. Sua missão é destilar a alma do sistema legado em um documento curto e denso: o que é, qual é o esqueleto de dados, e quais foram as decisões fundadoras que moldaram tudo.
+
+Esse agente é deliberadamente leve. Não faz escavação módulo a módulo (isso é do Archaeologist), não reconstrói regras de negócio (isso é do Detective), não desenha C4 completo (isso é do Architect). A entrega é UMA Spec única, executiva, que dá ao leitor o entendimento essencial do projeto em uma leitura.
+
+## Posicionamento
+
+Esse skill faz parte do Time de Descoberta (Reversa Core), mas **não entra no plano sequencial automático do orquestrador**. É invocado manualmente pelo usuário com `/reversa-extract-soul`, geralmente logo após o Scout, quando ainda não há tempo para rodar o pipeline completo, ou pontualmente em qualquer momento para ter uma visão executiva do sistema.
+
+## Antes de começar
+
+1. Leia `.reversa/state.json`, especialmente: `output_folder` (padrão `_reversa_sdd`), `doc_level` (padrão `completo`), `doc_language`, `user_name`.
+2. Use `output_folder` em todas as operações de escrita.
+
+## Pré-requisito obrigatório
+
+`.reversa/context/surface.json` deve existir. Esse é o sinal de que o Scout já mapeou a superfície.
+
+Se o arquivo não existir, pare imediatamente e diga ao usuário:
+
+> "[Nome], pra extrair a alma preciso primeiro do mapeamento do Scout. Rode `/reversa-scout` antes (ou `/reversa` para o pipeline completo). Volte aqui depois."
+
+Não tente extrair alma sem o Scout. Sem `surface.json` o agente não tem como amostrar o domínio nem confirmar a stack.
+
+## Diretiva non-destructive
+
+Se `<output_folder>/soul.md` já existir, **não sobrescreva**. Apresente o caminho ao usuário e pergunte:
+
+> "[Nome], encontrei `<output_folder>/soul.md` já existente. Você quer:
+> 1. Manter o atual e abortar
+> 2. Gerar uma nova versão em `<output_folder>/soul.<YYYYMMDD-HHMM>.md` (preserva o original)
+>
+> Pressione 1 ou 2."
+
+Nunca apague nem reescreva o `soul.md` original sem confirmação explícita do usuário.
+
+## Nível de documentação
+
+`doc_level` controla a profundidade da Spec. Sempre 1 arquivo (`soul.md`), nunca múltiplos.
+
+| Aspecto | essencial | completo | detalhado |
+|---------|-----------|----------|-----------|
+| Entidades centrais | 5 | 7 a 8 | até 10 |
+| Decisões fundadoras | 3 | 4 a 5 | 5 a 7 |
+| Diagrama de relações | em texto, formato lista | Mermaid simplificado | Mermaid expandido com cardinalidades |
+| Justificativa por decisão | 1 frase | 2 a 3 frases | parágrafo + evidência citada |
+
+## Idioma da Spec
+
+Os nomes de arquivo são fixos em inglês (`soul.md`), seguindo a convenção dos demais artefatos transversais (`architecture.md`, `domain.md`, `inventory.md`). O **conteúdo** do `soul.md` segue `doc_language` do state.json.
+
+## Processo
+
+### 1. Propósito e problema resolvido (1 parágrafo, máximo 8 linhas)
+
+Combine sinais de:
+
+- README do projeto (raiz e subprojetos)
+- Nomes de domínio detectados pelo Scout (`surface.json.modules`, `organization_suggestion.features`)
+- Endpoints públicos ou comandos CLI principais (do `surface.json.signals`)
+- Stack identificada (revela tipo de produto: API, SaaS B2B, ferramenta CLI, processador batch, app mobile, etc.)
+
+Responda 3 perguntas em texto corrido:
+
+1. O que esse software faz? (verbo + objeto)
+2. Para quem? (persona ou sistema consumidor)
+3. Que dor resolve ou que valor entrega?
+
+Se um dos três pontos não tiver evidência clara, marque-o como 🟡 INFERIDO ou 🔴 LACUNA. Não invente.
+
+### 2. Entidades centrais e relações
+
+#### Identificação
+
+Localize entidades de domínio amostrando os arquivos certos a partir do `surface.json`:
+
+- ORM models, schemas Prisma/SQLAlchemy/TypeORM/Hibernate
+- DDLs e migrations
+- Pastas `domain/`, `entities/`, `models/`, `schemas/`
+- Tipos/interfaces principais em linguagens com tipagem estática
+
+Limite a amostragem a 3 a 5 arquivos representativos. Não faça varredura completa, isso é trabalho do Archaeologist.
+
+#### Critério para "central"
+
+Uma entidade é central quando atende pelo menos 2 destes:
+
+- Aparece referenciada em múltiplos módulos
+- Tem chaves estrangeiras de várias outras entidades
+- É o sujeito de fluxos principais (carrinho, pedido, conta, post, projeto, etc.)
+- É mencionada no nome de endpoints ou comandos
+
+Liste de 5 a 10 entidades (conforme `doc_level`), cada uma com:
+
+- Nome
+- Frase curta sobre o que ela representa no domínio
+- Relacionamentos diretos (com cardinalidade quando óbvia: 1:1, 1:N, N:M)
+- Confiança 🟢 / 🟡 / 🔴
+
+#### Diagrama
+
+Em `essencial`: lista textual no formato `EntidadeA --1:N--> EntidadeB`.
+
+Em `completo` e `detalhado`: bloco Mermaid `erDiagram` ou `classDiagram` enxuto, só com as entidades centrais identificadas. Sem atributos detalhados (isso é do Architect).
+
+### 3. Decisões fundadoras
+
+Decisões fundadoras são as 3 a 7 escolhas estruturantes que moldam o sistema inteiro. Mexer em qualquer uma delas reescreveria boa parte do código. **Diferentes dos ADRs pontuais do Detective**, que cobrem decisões locais; aqui buscamos só as que sustentam o esqueleto.
+
+Fontes para inferir:
+
+- **Stack escolhida** (linguagem, framework, runtime), do `surface.json`. A escolha em si é uma decisão fundadora.
+- **Padrão arquitetural aparente** pela topologia de pastas: monolito MVC, microsserviços, hexagonal, layered, event-driven, modular monolith.
+- **Banco de dados** (relacional vs documento vs híbrido), também do `surface.json`.
+- **`git log` dos primeiros commits** (1 a 50 primeiros), eles costumam revelar a intenção original. Use `git log --reverse --max-count=50 --pretty=format:'%h %s'`.
+- **Grandes refactors no histórico** (commits com mais de 1000 linhas alteradas). Use `git log --shortstat` filtrando por delta grande. Eles revelam decisões que foram corrigidas.
+- **Comentários de cabeçalho** em arquivos centrais (`main.*`, `app.*`, `index.*`, `bootstrap.*`).
+- **Configurações estruturantes** (Dockerfile, docker-compose, k8s manifests, lambda configs).
+
+Para cada decisão fundadora, registre:
+
+- **Decisão** (frase imperativa: "usar PostgreSQL", "monolito modular", "REST sobre GraphQL", "JWT stateless")
+- **Evidência** (caminho ou commit que comprova)
+- **Implicação** (o que essa decisão obriga ou impede no resto do sistema)
+- **Confiança** 🟢 / 🟡 / 🔴
+
+Se a evidência for git log, cite o hash curto. Se for arquivo, cite o caminho relativo.
+
+### 4. Lacunas identificadas
+
+Se houver pontos onde nada do material disponível dá sinal claro, registre como 🔴 LACUNA com pergunta sugerida ao humano. Não force conclusão.
+
+## Saída
+
+Único arquivo: `<output_folder>/soul.md`.
+
+Estrutura sugerida (adapte ao `doc_language`):
+
+```markdown
+# Alma do Sistema
+
+> Síntese executiva do projeto, gerada por reversa-extract-soul em <data>.
+> Base: surface.json + amostragem leve de domínio + git log.
+
+## 1. Propósito
+
+[Parágrafo único, máximo 8 linhas, com confiança por afirmação]
+
+## 2. Entidades centrais
+
+[Lista de 5 a 10 entidades + diagrama conforme doc_level]
+
+## 3. Decisões fundadoras
+
+### D1. <decisão>
+- **Evidência:** <caminho ou commit>
+- **Implicação:** <o que isso obriga no resto do sistema>
+- **Confiança:** 🟢 / 🟡 / 🔴
+
+[repetir para cada decisão]
+
+## 4. Lacunas
+
+[Se houver, listar 🔴 com pergunta sugerida]
+
+## 5. Como ler esse documento
+
+Esse `soul.md` é uma síntese, não substitui:
+- `inventory.md` (Scout) para mapeamento de superfície
+- `code-analysis.md` (Archaeologist) para detalhes módulo a módulo
+- `domain.md` (Detective) para regras de negócio implícitas
+- `architecture.md` (Architect) para diagramas C4 e ERD completo
+```
+
+## Layout de saída (transversal)
+
+`soul.md` fica na raiz de `<output_folder>/`, fora das pastas de unit (feature folders). Não aplicar aqui a estrutura `<unit>/requirements.md|design.md|tasks.md`, ela pertence ao Writer.
+
+Mesmo com `doc_language` em português ou espanhol, o nome do arquivo permanece `soul.md`. Tradução de nome só vale para pastas de unit, não para artefatos transversais.
+
+## Escala de confiança
+
+Marque toda afirmação com 🟢 (CONFIRMADO no código ou git), 🟡 (INFERIDO de padrões) ou 🔴 (LACUNA). Sem exceções. A maior parte do conteúdo do `soul.md` tende a ficar 🟡, isso é esperado, dada a natureza sintética e amostral do agente.
+
+## Encerramento
+
+Após salvar `soul.md`, apresente ao usuário um resumo curto:
+
+> "[Nome], a alma está em `<output_folder>/soul.md`.
+>
+> Resumo:
+> - Propósito: [1 frase]
+> - Entidades centrais identificadas: [N]
+> - Decisões fundadoras: [N]
+> - Lacunas a validar: [N]
+>
+> Próximo passo natural: rodar `/reversa-archaeologist` para escavar módulo a módulo, ou `/reversa` para o pipeline completo.
+>
+> Digite **CONTINUAR** para prosseguir com a próxima ação que desejar."
+
+## Regras absolutas
+
+- Nunca apague, mova ou modifique arquivos pré-existentes do projeto legado.
+- Nunca sobrescreva `soul.md` existente sem confirmação do usuário.
+- Nunca duplique trabalho do Archaeologist (escavação módulo a módulo) ou do Detective (regras de negócio detalhadas, ADRs pontuais).
+- Não inclua "Pilares" como subseção, esse conceito ficou fora do escopo dessa Spec por escolha do projeto.
+- Não inclua varredura de credenciais nem listagem de segredos. Se identificar pista de credencial em texto, ignore e não cite.

agents/reversa-agents-help/SKILL.md

@@ -41,2 +41,11 @@ ---
 
+## 🧬 Soul Extractor: o biógrafo expresso
+**Comando:** `/reversa-extract-soul`
+
+O biógrafo expresso visita o personagem, lê as anotações do corretor (Scout), folheia rapidamente alguns álbuns de família e o histórico de cartas (git log), e produz uma biografia de uma página: quem é, o que faz, e as decisões fundadoras que moldaram a vida toda. Não é a história completa, é a alma destilada.
+
+> Use o Soul Extractor logo após o Scout, quando quiser uma síntese executiva do sistema (propósito, entidades centrais e decisões fundadoras) numa única Spec, sem esperar todo o pipeline. Não substitui Archaeologist nem Detective.
+
+---
+
 ## ⛏️ Archaeologist — o escavador
@@ -123,3 +132,3 @@ **Comando:** `/reversa-archaeologist`
 Opcionais em qualquer fase:
-Visor · Data Master · Design System
+Soul Extractor · Visor · Data Master · Design System
 ```

package.json

 {
   "name": "reversa",
-  "version": "1.2.36",
+  "version": "1.2.37",
   "description": "Transform legacy systems into executable specifications for AI coding agents",
@@ -5,0 +5,0 @@ "bin": {

templates/config.toml

@@ -26,3 +26,4 @@ # Reversa — Configuração do Projeto
   "reversa-data-master",
-  "reversa-design-system"
+  "reversa-design-system",
+  "reversa-extract-soul"
 ]
@@ -29,0 +30,0 @@

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

628280

1.74%

Number of package files

163

0.62%

No dependency changes