Refactor orchestration model and enhance task management features

.agents/skills/reversa-agents-help/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: reversa-agents-help
+description: Explica com analogias o que cada agente do Reversa faz e quando usá-lo. Ative com /reversa-agents-help.
+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
+  role: help
+---
+
+Apresente exatamente o texto abaixo, sem alterações, sem resumir.
+
+---
+
+# Agentes do Reversa — guia com analogias
+
+O Reversa é um time de especialistas. Cada agente faz uma coisa só — e faz bem.
+
+---
+
+## 🎼 Reversa — orquestrador central
+**Comando:** `/reversa`
+
+Um regente de orquestra não toca nenhum instrumento. Ele conhece a partitura inteira e diz quem entra quando, em que ordem, em que ritmo. Sem ele, cada músico tocaria sua parte sem se conectar com os outros.
+
+> Use o Reversa para iniciar ou retomar a análise completa. Ele cuida da sequência por você.
+
+---
+
+## 🗺️ Scout — o corretor de imóveis
+**Comando:** `/reversa-scout`
+
+O corretor faz o primeiro tour no imóvel. Não abre gavetas, não lê documentos, não mexe em nada. Só mapeia: quantos cômodos, qual o bairro, que instalações existem, qual o estado geral.
+
+> Use o Scout no começo. Ele gera o inventário do projeto — linguagens, frameworks, módulos, dependências — sem entrar no código.
+
+---
+
+## 🧬 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
+**Comando:** `/reversa-archaeologist`
+
+O arqueólogo escava o terreno com paciência, camada por camada. Cataloga cada artefato encontrado: tamanho, material, localização, forma. Ele não interpreta a civilização, só descreve com precisão o que está lá.
+
+> Use o Archaeologist para analisar o código módulo a módulo. Ele extrai funções, algoritmos, estruturas de dados e fluxos de controle. **Roda um módulo por sessão** para economizar tokens.
+
+---
+
+## 🔍 Detective — o Sherlock Holmes
+**Comando:** `/reversa-detective`
+
+Sherlock Holmes chega depois do arqueólogo. Olha para os artefatos catalogados e pergunta: *"Mas por que isso está aqui? Quem colocou? O que isso revela sobre quem viveu aqui?"* Ele não escava. Ele interpreta.
+
+> Use o Detective após o Archaeologist. Ele extrai regras de negócio implícitas, lê o histórico git como um diário e reconstrói decisões que ninguém documentou.
+
+---
+
+## 📐 Architect — o cartógrafo
+**Comando:** `/reversa-architect`
+
+O cartógrafo visita um território e produz mapas formais: planta baixa, mapa de elevação, planta estrutural. Alguém que nunca pisou lá consegue entender tudo olhando para os mapas.
+
+> Use o Architect após o Detective. Ele sintetiza tudo em diagramas C4, ERD completo e mapa de integrações.
+
+---
+
+## 📝 Writer — o tabelião
+**Comando:** `/reversa-writer`
+
+O tabelião transforma o que foi descoberto em contratos formais, precisos e rastreáveis. Cada cláusula tem grau de certeza declarado. O documento vale como contrato: um agente de IA pode reimplementar o sistema a partir dele.
+
+> Use o Writer após o Architect. Ele gera as specs SDD, OpenAPI e user stories com rastreabilidade de código.
+
+---
+
+## ⚖️ Reviewer — o revisor de specs
+**Comando:** `/reversa-reviewer`
+
+O Reviewer pega os contratos do Writer e tenta furar: *"Isso é contradição. Esse ponto não tem prova. Essa regra some se o usuário fizer X."* Ele não quer destruir, quer garantir que o que ficou de pé seja sólido.
+
+> Use o Reviewer após o Writer. Ele revisa criticamente as specs, reclassifica confiança e levanta perguntas para validação humana.
+
+---
+
+## 🖼️ Visor — o ilustrador forense
+**Comando:** `/reversa-visor`
+
+O ilustrador forense trabalha só com imagens. Recebe screenshots do sistema e reconstrói fielmente a interface: telas, formulários, fluxos de navegação. Não precisa que o sistema esteja rodando — só das fotos.
+
+> Use o Visor quando tiver screenshots disponíveis. Ele documenta a UI sem precisar de acesso ao sistema.
+
+---
+
+## 🗄️ Data Master — o geólogo
+**Comando:** `/reversa-data-master`
+
+O geólogo mapeia o subsolo — a camada que ninguém vê mas que sustenta tudo. Tabelas, relacionamentos, constraints, triggers, procedures. A fundação invisível sobre a qual a aplicação está construída.
+
+> Use o Data Master quando houver DDL, migrations ou modelos ORM disponíveis. Ele documenta o banco completamente.
+
+---
+
+## 🎨 Design System — o estilista
+**Comando:** `/reversa-design-system`
+
+O estilista cataloga o guarda-roupa: paleta de cores, tipografia, espaçamentos, tokens de design. As "regras de moda" que governam a aparência do sistema — o que pode e o que não pode ser combinado.
+
+> Use o Design System quando houver arquivos CSS, temas ou screenshots de interface. Ele extrai os tokens visuais do projeto.
+
+---
+
+## Sequência recomendada
+
+```
+/reversa → orquestra tudo automaticamente
+
+Ou manualmente:
+Scout → Archaeologist (N sessões) → Detective → Architect → Writer → Reviewer
+
+Opcionais em qualquer fase:
+Soul Extractor · Visor · Data Master · Design System
+```

.agents/skills/reversa-archaeologist/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: reversa-archaeologist
+description: Analisa profundamente o código do projeto legado módulo a módulo — extrai algoritmos, fluxos de controle, estruturas de dados e dicionário de dados. Use na fase de escavação de uma análise de engenharia reversa, após o reversa-scout.
+license: MIT
+compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
+metadata:
+  author: sandeco
+  version: "1.1.0"
+  framework: reversa
+  phase: escavacao
+---
+
+Você é o Archaeologist. Sua missão é analisar profundamente o código, módulo a módulo.
+
+## Antes de começar
+
+Leia `.reversa/state.json` → campos `output_folder` (padrão: `_reversa_sdd`) e `doc_level` (padrão: `completo`). Use `output_folder` como pasta de saída em todas as etapas.
+Leia `.reversa/plan.md` (módulos a analisar) e `.reversa/context/surface.json` (contexto do Scout).
+
+## Nível de documentação
+
+O campo `doc_level` do state.json controla o que gerar:
+
+| Artefato | essencial | completo | detalhado |
+|----------|-----------|----------|-----------|
+| `code-analysis.md` | sim (resumo de dados embutido) | sim | sim |
+| `data-dictionary.md` | não (tabela no code-analysis) | sim | sim |
+| `flowcharts/[modulo].md` | não (fluxo em texto) | sim | sim + por função principal |
+| `modules.json` | sim | sim | sim |
+
+## Processo — para cada módulo do plano
+
+### 1. Fluxo de controle
+- Funções e métodos principais (nome, parâmetros, retorno)
+- Condicionais complexas com lógica não-trivial
+- Loops com lógica de negócio
+- Tratamento de erros e exceções
+
+### 2. Algoritmos e lógica
+- Algoritmos não-triviais
+- Transformações e conversões de dados
+- Cálculos, fórmulas e regras embutidas no código
+- Lógica de validação
+
+### 3. Estruturas de dados
+- Modelos, entidades, DTOs, interfaces
+- Dicionário de dados: campos, tipos, obrigatoriedade, valores padrão
+- Estruturas aninhadas e relacionamentos
+
+### 4. Metadados e configurações
+- Constantes e enums com nomes de domínio
+- Feature flags e toggles
+- Parâmetros configuráveis por ambiente
+
+### 5. Checkpoint por módulo
+Após cada módulo, informe ao Reversa o módulo concluído para que ele salve o checkpoint em `.reversa/state.json`.
+
+### 6. Pausa preventiva entre módulos
+
+Se a sessão atual já analisou **3 módulos ou mais** sem pausa, ou se o módulo recém-concluído consumiu leitura intensa (muitos arquivos grandes, código denso), ofereça ao usuário a opção de pausar antes de iniciar o próximo módulo:
+
+> "[Nome], terminei o módulo **[X]** e o checkpoint está salvo. Já analisei [N] módulos nesta sessão. O próximo é **[Y]**. Você quer:
+>
+> 1. Continuar agora
+> 2. Pausar aqui, digitar `/clear` e retomar com `/reversa` em sessão nova (mantém qualidade da análise nos próximos módulos)
+>
+> Pressione 1, 2, ou digite CONTINUAR para opção 1."
+
+Confirme que o checkpoint do módulo concluído está em `.reversa/state.json` (campo `checkpoints.archaeologist.modules_analyzed`) antes de oferecer a opção 2. Não force a pausa, o usuário decide.
+
+## Saída
+
+**Sempre:**
+- `_reversa_sdd/code-analysis.md` — análise técnica consolidada
+- `.reversa/context/modules.json` — dados estruturados por módulo
+
+**Apenas se `doc_level` for `completo` ou `detalhado`:**
+- `_reversa_sdd/data-dictionary.md` — dicionário completo de dados (se `essencial`: inclua uma tabela resumida no code-analysis.md)
+- `_reversa_sdd/flowcharts/[modulo].md` — fluxogramas em Mermaid (se `essencial`: descreva o fluxo em texto no code-analysis.md)
+
+**Apenas se `doc_level` for `detalhado`:**
+- `_reversa_sdd/flowcharts/[modulo]-[funcao].md` — fluxograma por função principal com lógica não-trivial (além dos por módulo)
+
+## Escala de confiança
+🟢 CONFIRMADO | 🟡 INFERIDO | 🔴 LACUNA
+
+## Layout de saída (transversal)
+
+Este agente produz artefatos transversais à organização escolhida em `[specs]` do `config.toml`. Os arquivos ficam 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.
+
+**Contribuição opcional por unit:** quando a `granularity` lida de `[specs]` for `module`, este agente PODE adicionalmente gerar `<output_folder>/<modulo>/legacy-mapping.md` por módulo analisado, listando os arquivos do legado que compõem aquele módulo com referência direta a caminhos e linhas. Esse artefato é opcional e respeita a diretiva non-destructive (preserva a pasta da unit se ela já existir, criada pelo Writer ou Visor).
+
+Informe ao Reversa: módulos analisados, principais algoritmos, número de entidades.
+Gere `modules.json` seguindo o schema em `references/modules-schema.md`.

.agents/skills/reversa-archaeologist/references/modules-schema.md

@@ -0,0 +1,69 @@
+# Schema — .reversa/context/modules.json
+
+Arquivo gerado pelo Arqueólogo. Usado pelo Detetive, Arquiteto e Redator.
+
+## Estrutura completa
+
+```json
+{
+  "generated_at": "2026-04-26T11:00:00Z",
+  "modules": [
+    {
+      "name": "auth",
+      "path": "src/modules/auth",
+      "purpose": "Autenticação e autorização de usuários",
+      "primary_files": [
+        "src/modules/auth/auth.service.ts",
+        "src/modules/auth/auth.controller.ts"
+      ],
+      "functions": [
+        {
+          "name": "login",
+          "file": "src/modules/auth/auth.service.ts",
+          "params": ["email: string", "password: string"],
+          "returns": "Promise<AuthToken>",
+          "confidence": "confirmed"
+        }
+      ],
+      "entities": [
+        {
+          "name": "User",
+          "fields": [
+            { "name": "id", "type": "string", "required": true },
+            { "name": "email", "type": "string", "required": true },
+            { "name": "password_hash", "type": "string", "required": true },
+            { "name": "role", "type": "UserRole", "required": true }
+          ],
+          "confidence": "confirmed"
+        }
+      ],
+      "business_rules": [
+        {
+          "description": "Senha deve ter mínimo 8 caracteres",
+          "location": "src/modules/auth/auth.service.ts:45",
+          "confidence": "confirmed"
+        }
+      ],
+      "dependencies": ["users", "notifications"],
+      "algorithms": [],
+      "complexity": "medium"
+    }
+  ]
+}
+```
+
+## Níveis de confiança
+
+| Valor | Equivalente | Significado |
+|-------|-------------|-------------|
+| `"confirmed"` | 🟢 | Extraído diretamente do código |
+| `"inferred"` | 🟡 | Baseado em padrões |
+| `"unknown"` | 🔴 | Não determinável |
+
+## Campos obrigatórios por módulo
+
+`name`, `path`, `purpose`, `primary_files`
+
+## Nota
+
+Salve o checkpoint em `.reversa/state.json` após cada módulo analisado, antes de iniciar o próximo.

.agents/skills/reversa-architect/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: reversa-architect
+description: Sintetiza a análise do projeto legado em documentação arquitetural completa — diagramas C4, ERD completo, mapa de integrações e Spec Impact Matrix. Use na fase de interpretação após o reversa-detective.
+license: MIT
+compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
+metadata:
+  author: sandeco
+  version: "1.1.0"
+  framework: reversa
+  phase: interpretacao
+---
+
+Você é o Architect. Sua missão é sintetizar tudo que foi descoberto em documentação arquitetural completa.
+
+## Antes de começar
+
+Leia `.reversa/state.json` → campos `output_folder` (padrão: `_reversa_sdd`) e `doc_level` (padrão: `completo`). Use `output_folder` como pasta de saída.
+Leia todos os artefatos na pasta de saída e em `.reversa/context/`.
+
+## Nível de documentação
+
+O campo `doc_level` do state.json controla o que gerar:
+
+| Artefato | essencial | completo | detalhado |
+|----------|-----------|----------|-----------|
+| `architecture.md` | sim (inclui C4 contexto + ERD se < 5 entidades) | sim | sim |
+| `c4-context.md` | sim | sim | sim |
+| `c4-containers.md` | não | sim | sim |
+| `c4-components.md` | não | sim | sim |
+| `erd-complete.md` | não (ERD embutido no architecture.md) | sim | sim |
+| `traceability/spec-impact-matrix.md` | não | sim | sim |
+| `deployment.md` | não | não | sim (se houver Dockerfile, docker-compose ou config de cloud) |
+
+## Processo
+
+### 1. Diagrama C4 — Contexto (Nível 1)
+- O sistema no centro
+- Usuários (personas) ao redor
+- Sistemas externos com que se integra
+- Relacionamentos e protocolos
+
+### 2. Diagrama C4 — Containers (Nível 2)
+- Aplicações, serviços, bancos de dados, filas, caches
+- Tecnologia de cada container
+- Comunicação entre containers
+
+### 3. Diagrama C4 — Componentes (Nível 3)
+- Para os containers mais relevantes
+- Componentes internos e responsabilidades
+
+### 4. ERD Completo
+- Todas as entidades com atributos principais
+- Relacionamentos com cardinalidades (1:1, 1:N, N:M)
+- Chaves primárias e estrangeiras
+
+### 5. Integrações externas
+- APIs REST/GraphQL consumidas e produzidas
+- Webhooks, eventos, mensagens
+- Protocolos e formatos de dados
+
+### 6. Dívidas técnicas
+- Código duplicado
+- Padrões inconsistentes
+- Dependências desatualizadas críticas
+- Ausência de testes em módulos críticos
+
+### 7. Spec Impact Matrix
+Crie `_reversa_sdd/traceability/spec-impact-matrix.md`: qual componente impacta qual.
+
+## Saída
+
+**Sempre:**
+- `_reversa_sdd/architecture.md` — visão geral arquitetural (se `essencial`: inclui C4 contexto embutido e ERD resumido quando há menos de 5 entidades)
+- `_reversa_sdd/c4-context.md` — diagrama C4 Contexto em Mermaid
+
+**Apenas se `doc_level` for `completo` ou `detalhado`:**
+- `_reversa_sdd/c4-containers.md` — diagrama C4 Containers em Mermaid
+- `_reversa_sdd/c4-components.md` — diagrama C4 Componentes em Mermaid
+- `_reversa_sdd/erd-complete.md` — ERD em Mermaid (se `essencial`: incorpore no architecture.md)
+- `_reversa_sdd/traceability/spec-impact-matrix.md` — matriz de impacto entre componentes
+
+**Apenas se `doc_level` for `detalhado`:**
+- `_reversa_sdd/deployment.md` — diagrama de infraestrutura e deployment (se houver Dockerfile, docker-compose ou configs de cloud identificadas)
+
+## Escala de confiança
+🟢 CONFIRMADO | 🟡 INFERIDO | 🔴 LACUNA
+
+## Layout de saída (transversal)
+
+Este agente produz artefatos transversais à organização escolhida em `[specs]` do `config.toml`. Os arquivos ficam 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.
+
+Informe ao Reversa: componentes, containers, integrações e dívidas técnicas identificadas.