Reversa Forward

---
name: reversa-forward
description: 'Orquestrador do ciclo forward do Reversa: detecta o estágio da feature ativa em `_reversa_forward/` e roteia para o próximo agente (requirements, clarify, plan, to-do, audit, quality, coding, add, sync). Só roteia, não escreve artefatos. Use com "/reversa-forward", "iniciar evolução", "iniciar pipeline forward".'
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)
7. Para o estágio `done`, verifique também se existe adendo da feature em `<output_folder>/addenda/` (arquivo cujo nome começa com o `feature-id`). Adendo presente e vigente (sem linha de superação na seção Vigência) significa que a entrega já foi convergida na extração

## 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` sem adendo em `addenda/` | Indiferente | `/reversa-sync` (converger a entrega na extração) |
| Estágio `done` com adendo vigente | 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, add)

`/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.

`/reversa-add` também é opcional, roda depois do coding e é repetível. Ele existe para ajustes de minuto na feature já entregue ("aumenta esse título", "põe um loading aqui"), registrando a emenda na spec antes de implementar. Sugira apenas quando o usuário descrever um ajuste curto sobre o que a feature entregou. Nunca sugira `/reversa-add` para ideia nova, feature nova, ou qualquer coisa que exija dependência nova, mudança de schema ou contrato, superfície pública nova, ou caminho de auth. Nesses casos o encaminhamento é `/reversa-requirements`.

## 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 → add? → sync?
> ```
>
> 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`, `reversa-add`, `reversa-sync`) 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` sem adendo:** diga "Todas as ações estão fechadas, falta converger a entrega na extração com `/reversa-sync` para `<output_folder>/` não ficar defasado."
- **Estágio `done` com adendo vigente:** diga "Todas as ações estão fechadas e a entrega já foi convergida em `<output_folder>/addenda/`. Se quiser, retome uma feature pausada com `/reversa-resume` ou comece outra com `/reversa-requirements <descrição>`. Para ajustes curtos sobre o que essa feature entregou, use `/reversa-add`."
- **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.