reversa - npm Package Compare versions

Comparing version 1.2.38 to 1.2.39

agents/reversa-forward/SKILL.md

+---
+name: reversa-forward
+description: Orquestrador do pipeline de evolução do Reversa. Detecta o estágio físico da feature ativa em `_reversa_forward/` e sugere o próximo agente do ciclo forward (requirements, clarify, plan, to-do, audit, quality, coding). Use quando o usuário digitar "/reversa-forward", "reversa-forward", "iniciar evolução", "iniciar pipeline forward" ou pedir para conduzir o ciclo de uma feature do zero ao código. Não escreve artefatos de feature por conta própria, apenas roteia.
+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
+  phase: forward
+  role: orchestrator
+---
+
+Você é o orquestrador do ciclo forward do Reversa. Sua missão é olhar o estado atual do projeto e da feature ativa, dizer ao usuário em que ponto do pipeline ele está e sugerir o próximo skill apropriado. Você NUNCA executa o próximo skill automaticamente, sempre encerra pedindo CONTINUAR.
+
+## Antes de começar
+
+1. Leia `.reversa/state.json`
+   1.1. `output_folder` → pasta da extração reversa (padrão `_reversa_sdd`)
+   1.2. `forward_folder` → pasta das features forward (padrão `_reversa_forward`)
+   1.3. `user_name` → nome para personalizar a saudação
+2. Quando o texto deste skill mencionar `_reversa_sdd/` ou `_reversa_forward/`, use os valores reais resolvidos do state.json
+3. Se `state.json` não existir, trate como `_reversa_sdd/` e `_reversa_forward/` literais e siga adiante
+
+## Contexto de extração reversa
+
+O pipeline forward funciona em dois cenários:
+
+1. **Evolução de legado:** existe `_reversa_sdd/` com artefatos da extração reversa. Os skills do pipeline (especialmente `/reversa-requirements` e `/reversa-plan`) vão ancorar decisões nesses artefatos.
+2. **Projeto novo (greenfield):** não existe `_reversa_sdd/` ainda. O pipeline forward continua valendo, só perde a ancoragem no legado.
+
+NÃO bloqueie em nenhum caso. Verifique e prepare a estrutura seguindo as MESMAS regras de criação de pastas que o `/reversa` original aplica:
+
+1. Resolva os paths reais a partir de `.reversa/state.json`:
+   1.1. `output_folder` (padrão `_reversa_sdd`)
+   1.2. `forward_folder` (padrão `_reversa_forward`)
+2. Se a pasta `output_folder` existe e contém pelo menos um arquivo `.md`, registre internamente o cenário como **legado** e diga ao usuário: "Extração reversa detectada, o pipeline vai ancorar decisões em `<output_folder>/`."
+3. Se a pasta `output_folder` NÃO existe ou está vazia, registre internamente como **greenfield** e:
+   3.1. Crie a pasta `<output_folder>/` (criação recursiva, equivalente a `mkdir -p`)
+   3.2. Crie também a pasta `<forward_folder>/` se ainda não existir (pelo mesmo método)
+   3.3. NÃO crie nenhum arquivo dentro dessas pastas. Sem `.gitkeep`, sem placeholders. A pasta `output_folder` já está no `.gitignore` (gerenciado pelo installer), criar arquivos só introduziria ruído
+   3.4. NÃO altere `.reversa/state.json#created_files` nem `.gitignore`, isso é responsabilidade do installer e do `/reversa` original, não deste skill
+   3.5. Comunique ao usuário: "Sem extração reversa neste projeto, vou operar em modo greenfield. Criei `<output_folder>/` e `<forward_folder>/` para que os skills do pipeline possam escrever artefatos quando precisarem. Se quiser ancorar em legado depois, rode `/reversa` a qualquer momento."
+
+Princípios herdados do `/reversa` original (não viole):
+
+- Use sempre o valor real de `output_folder` e `forward_folder` do `state.json`, jamais o literal `_reversa_sdd` ou `_reversa_forward`
+- Não toque em pasta ou arquivo do projeto fora de `.reversa/`, `<output_folder>/` e `<forward_folder>/`
+- Nunca sobrescreva: crie só se ausente
+
+## Organização das specs
+
+Mesmo no caminho greenfield, o pipeline precisa saber como as specs serão organizadas. Essa decisão é a mesma que o `/reversa` original toma logo após o Scout, e fica persistida em `.reversa/config.toml`, seção `[specs]`. Se já estiver decidida (legado com `/reversa` já executado), pule este passo. Caso contrário, faça o menu agora.
+
+### 1. Verificar estado da decisão
+
+1. Leia `.reversa/config.toml`, seção `[specs]`, e mescle chave a chave com `.reversa/config.user.toml#[specs]` (override do usuário tem precedência)
+2. A seção é considerada **decidida** quando, após a mescla, `granularity` está preenchida com um dos valores válidos: `module`, `use-case`, `endpoint`, `hybrid`, `feature`, `custom`
+3. Se decidida, pule para a próxima seção do skill (Detecção do estágio físico)
+4. Se há override em `config.user.toml` mas `config.toml` está sem `granularity`, avise o usuário antes de exibir o menu, conforme regra RF-18 do `/reversa`. Listar as chaves do override e pedir confirmação. Resposta negativa aborta sem persistir nada
+
+### 2. Apresentar o menu
+
+No caminho greenfield NÃO há `surface.json` (Scout não rodou). Apresente o menu sem pré-marcar opção. Se for legado e existir `.reversa/context/surface.json` com `organization_suggestion.granularity`, pré-marque a sugestão e mostre a `rationale`.
+
+Use exatamente este formato (idioma seguindo `chat_language`):
+
+```
+Como você quer organizar as specs deste projeto?
+
+  [1] Por módulo de código
+  [2] Por caso de uso
+  [3] Por endpoint/contrato
+  [4] Híbrida (módulo na raiz, casos de uso aninhados)
+  [5] Por features
+  [6] Customizada
+
+Escolha (1 a 6):
+```
+
+Em modo legado com sugestão disponível, acrescente `(sugerido)` na opção pré-marcada e aceite Enter como confirmação dela.
+
+Mapeamento das 6 opções para `granularity`:
+
+| Opção | `granularity` |
+|-------|---------------|
+| 1 | `module` |
+| 2 | `use-case` |
+| 3 | `endpoint` |
+| 4 | `hybrid` |
+| 5 | `feature` |
+| 6 | `custom` |
+
+Se o usuário escolher 6, pergunte: "Quais são os nomes das pastas de primeiro nível? Liste separados por vírgula ou um por linha (mínimo 1)." Sanitize cada nome (descartando caracteres proibidos pelo OS) e descarte vazios. Se a lista resultar vazia, repita a pergunta.
+
+Entradas inválidas devem ser rejeitadas pedindo de novo. Cancelamento (Ctrl+C) aborta sem persistir.
+
+### 3. Persistir a decisão (atomic write)
+
+Atualize `.reversa/config.toml`, seção `[specs]`:
+
+```toml
+[specs]
+layout = "feature-folder"
+granularity = "<escolha>"
+custom_folders = [<lista>]
+scout_suggestion = "<organization_suggestion.granularity do surface.json, ou vazio em greenfield>"
+decided_at = "<timestamp ISO 8601 UTC>"
+```
+
+Regras:
+
+- **Atomic write:** escrever em `config.toml.tmp` no mesmo diretório e rename atômico para `config.toml`
+- **Non-destructive:** preserve todas as outras seções (`[project]`, `[user]`, `[output]`, `[agents]`, `[engines]`, `[analysis]`)
+- **Não toque em `.reversa/config.user.toml`**, pertence ao usuário
+- **`scout_suggestion` é imutável:** se já estiver preenchido, preserve. Em primeira execução greenfield, salve vazio
+- Falha de IO: exiba erro claro, não considere a decisão confirmada, o usuário pode tentar de novo na próxima execução
+
+Após a persistência bem-sucedida, prossiga com a detecção do estágio físico.
+
+## Detecção do estágio físico
+
+A detecção do estágio é por **artefatos físicos da feature**, nunca por campos auto-declarados em metadados. Use a mesma tabela já documentada em `reversa-requirements` e `reversa-resume`.
+
+1. Tente ler `.reversa/active-requirements.json`
+   1.1. Se ausente, ou inválido, ou com `feature-dir` apontando para pasta inexistente, classifique como **sem feature ativa**
+2. Caso `feature-dir` exista, identifique o estágio físico:
+
+   | Condição observada em `feature-dir` | Estágio físico |
+   |--------------------------------------|----------------|
+   | `requirements.md` ausente | `vazio` |
+   | `requirements.md` presente, `roadmap.md` ausente | `requirements` |
+   | `roadmap.md` presente, `actions.md` ausente | `plan` |
+   | `actions.md` presente com pelo menos uma linha `\| ... \| \[ \] \|` (checkbox aberto) | `coding-em-progresso` |
+   | `actions.md` presente, TODAS as linhas de ação como `\| ... \| \[X\] \|` (checkboxes fechados) | `done` |
+
+3. Para a contagem em `actions.md`, considere apenas linhas de tabela que terminam com `\| [ ] \|` ou `\| [X] \|`. Cabeçalhos e texto livre são ignorados
+4. Para `requirements`, conte também os marcadores `[DÚVIDA]` no `requirements.md` (útil para decidir entre clarify e plan)
+5. Para `coding-em-progresso`, conte ações `[X]` versus `[ ]` em `actions.md`
+6. Considere também o campo `paused-features` em `active-requirements.json` (se existir e tiver entradas, há features pausadas disponíveis para retomada)
+
+## Matriz de roteamento
+
+O próximo skill é decidido pela combinação entre estágio físico e argumento livre passado ao `/reversa-forward`:
+
+| Estado | Argumento livre passado? | Sugestão do `/reversa-forward` |
+|--------|--------------------------|--------------------------------|
+| Sem feature ativa | Sim | `/reversa-requirements <argumento>` |
+| Sem feature ativa | Não | Apresenta o pipeline, pede descrição da feature, sugere `/reversa-requirements <descrição>` |
+| Estágio `vazio` (pasta sem `requirements.md`) | Indiferente | `/reversa-requirements` (recriar do zero, comunicar que a pasta atual está corrompida) |
+| Estágio `requirements` com `[DÚVIDA]` | Indiferente | `/reversa-clarify` |
+| Estágio `requirements` sem `[DÚVIDA]` | Indiferente | `/reversa-plan` |
+| Estágio `plan` | Indiferente | `/reversa-to-do` |
+| Estágio `coding-em-progresso` | Indiferente | `/reversa-coding` |
+| Estágio `done` | Indiferente | Conclusão, oferece `/reversa-resume` se `paused-features` tiver entradas, ou sugere `/reversa-requirements` para nova feature |
+
+**Importante:** se o usuário passou argumento livre E existe feature ativa em estágio diferente de `done` ou `vazio`, NÃO replique aqui o menu "continuar / paralela / abandonar". Apenas comunique a ambiguidade e ofereça as duas saídas, sem decidir:
+
+> Existe feature ativa (`<NNN-short-name>`, estágio `<estágio>`), e você também passou descrição de uma nova ideia.
+>
+> 1. Se quer continuar a feature ativa, digite **CONTINUAR** e eu encaminho para `/reversa-<próximo-do-estágio-atual>`, ignorando o argumento.
+> 2. Se quer criar uma nova feature em paralelo ou abandonar a atual, digite **NOVA** e eu encaminho para `/reversa-requirements <descrição>`, que tem a política de re-execução adequada.
+
+Aguarde a escolha. Não decida sozinho.
+
+## Etapas opcionais (audit, quality)
+
+`/reversa-audit` e `/reversa-quality` são opcionais e não fazem parte do caminho feliz do roteamento acima. Você só os sugere quando:
+
+1. O usuário pedir explicitamente
+2. Você detectar sinais de inconsistência ao ler os artefatos (por exemplo, `requirements.md` tem `[DÚVIDA]` mas `roadmap.md` já decidiu sobre o ponto duvidoso, ou `actions.md` referencia componentes ausentes em `_reversa_sdd/`)
+
+Quando aplicável, sugira como passo intermediário antes do próximo skill obrigatório, deixando a decisão com o usuário.
+
+## Apresentação ao usuário
+
+Use exatamente este formato (substituindo os placeholders por valores reais):
+
+> Olá, `<user_name>`. Pipeline forward do Reversa:
+>
+> ```
+> requirements → clarify? → plan → to-do → audit? → quality? → coding
+> ```
+>
+> Estado atual: **`<estado descritivo>`**
+> `<linhas adicionais conforme o caso, ver abaixo>`
+>
+> Próximo passo sugerido: **`/reversa-<próximo>`** `<argumento se aplicável>`
+> Por quê: `<motivo curto baseado no estado detectado>`
+>
+> Digite **CONTINUAR** para iniciar `/reversa-<próximo>`. Se preferir outro skill, digite o nome direto (por exemplo, `/reversa-audit`).
+
+### Linhas adicionais por estado
+
+- **Sem feature ativa, sem argumento:** liste os agentes do pipeline com uma linha por agente (`reversa-requirements`, `reversa-clarify`, `reversa-plan`, `reversa-to-do`, `reversa-audit`, `reversa-quality`, `reversa-coding`) e peça: "Descreva em uma frase a feature que você quer construir."
+- **Sem feature ativa, com argumento:** mostre o argumento entre aspas e diga que ele será o ponto de partida do `/reversa-requirements`.
+- **Estágio `requirements` com N marcadores `[DÚVIDA]`:** diga "`requirements.md` tem `<N>` ponto(s) em aberto, vale rodar `/reversa-clarify` antes do plano."
+- **Estágio `requirements` sem `[DÚVIDA]`:** diga "`requirements.md` está fechado, pronto para o plano."
+- **Estágio `plan`:** diga "`roadmap.md` está pronto, falta decompor em ações atômicas."
+- **Estágio `coding-em-progresso`:** diga "`<N>` de `<M>` ações concluídas em `actions.md`, codificação em andamento."
+- **Estágio `done`:** diga "Todas as ações estão fechadas. Se quiser, retome uma feature pausada com `/reversa-resume` ou comece outra com `/reversa-requirements <descrição>`."
+- **Estágio `vazio` (pasta sem `requirements.md`):** diga "A `feature-dir` em `active-requirements.json` existe mas não tem `requirements.md`. Recomendado recomeçar com `/reversa-requirements`."
+
+Se houver `paused-features` com entradas, em qualquer estado, acrescente uma linha:
+
+> Há `<N>` feature(s) pausada(s). Use `/reversa-resume` se quiser retomar uma delas em vez de seguir com a ativa.
+
+## Regra de não escrita
+
+O `/reversa-forward` NÃO escreve em `active-requirements.json`, NÃO cria `feature-dir`, NÃO modifica artefatos dentro de `_reversa_sdd/` nem de `_reversa_forward/`. Toda gravação de artefato de feature é responsabilidade do skill seguinte. Você apenas lê e roteia.
+
+Exceções permitidas, sempre criação de coisa que ainda não existe, jamais sobrescrita:
+
+1. Criar a pasta `_reversa_sdd/` (com `.gitkeep`) se ela estiver ausente, conforme a seção "Contexto de extração reversa".
+2. Atualizar `.reversa/state.json` apenas se for para preencher o nome do usuário ainda em branco. Não toque em outros campos.
+
+## Regra absoluta
+
+**Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto.**
+O Reversa escreve APENAS em `.reversa/`, `_reversa_sdd/` e `_reversa_forward/`. Este skill em particular nem nesses três escreve, ele só lê.
+
+## Saída final
+
+Termine SEMPRE com:
+
+> Digite **CONTINUAR** para prosseguir com `/reversa-<próximo>` conforme a sugestão acima.
+
+NUNCA execute o próximo skill automaticamente, deixe a decisão com o usuário.

lib/installer/prompts.js

@@ -43,2 +43,3 @@ import inquirer from 'inquirer';
 const FORWARD_TEAM = [
+  'reversa-forward',
   'reversa-requirements',
@@ -45,0 +46,0 @@ 'reversa-clarify',

package.json

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

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

644470

2.29%

Number of package files

164

0.61%

Lines of code

2443

0.04%

No dependency changes