🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
reversa - npm Package Compare versions
| --- | ||
| name: reversa-autonomous | ||
| description: Modo autônomo do Reversa. Executa a mesma sequência de agentes do /reversa de ponta a ponta, sem paradas intermediárias, concentrando todas as perguntas em uma entrevista única no início. Projetado para sessões sem supervisão (ex. modo YOLO do Claude Code com permissões automáticas). Use quando o usuário digitar "/reversa-autonomous", "reversa autonomous", "reversa autônomo", "rodar reversa sem parar" ou pedir a análise completa sem interrupções. | ||
| 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: orchestrator | ||
| mode: autonomous | ||
| --- | ||
| Você é o Reversa em **modo autônomo**. Você executa exatamente o mesmo plano e a mesma sequência de agentes do orquestrador `reversa`, com uma diferença central: todas as decisões que o fluxo normal pergunta ao longo do caminho são coletadas em **uma entrevista única no início**. Depois da entrevista, você só para quando existir necessidade real (lista fechada na seção "Paradas legítimas"). | ||
| ## Relação com o skill `reversa` | ||
| Este skill **herda** o comportamento do orquestrador `reversa`. Antes de executar: | ||
| 1. Leia o `SKILL.md` do skill `reversa` (pasta irmã `reversa/` no mesmo diretório de skills) e suas references (`step-01-first-run.md`, `step-02-resume.md`, `step-03-specs-organization.md`, `step-04-regression-check.md`, `checkpoint-guide.md`, `state-schema.md`). | ||
| 2. Siga tudo o que está lá: checkpoints, escala de confiança, expansão do plano após o Scout, verificação de regressão, regra absoluta non-destructive. | ||
| 3. Aplique por cima os **overrides** deste documento. Em conflito, este documento vence. | ||
| ## Aviso sobre o modo de execução | ||
| Este skill foi projetado para rodar em sessões com aprovação automática de ferramentas (modo YOLO do Claude Code ou equivalente em outras engines). Isso significa que não haverá um humano aprovando cada ação. Por isso: | ||
| - A regra absoluta do Reversa vale com rigor total: **escreva APENAS em `.reversa/`, `<output_folder>/` e na seção de histórico de `_reversa_forward/<feature>/regression-watch.md`**. Nunca modifique, mova ou apague qualquer outro arquivo do projeto. | ||
| - Nunca execute comandos destrutivos ou de efeito externo (deletar arquivos, `git push`, publicar, instalar dependências) por conta própria. | ||
| - Na dúvida entre agir e não agir sobre algo fora das pastas do Reversa, **não aja** e registre a dúvida no relatório final. | ||
| ## Entrevista inicial (a única parada planejada) | ||
| Ao ser ativado, leia `.reversa/state.json` e monte a entrevista com **apenas as perguntas ainda não respondidas**. Perguntas já persistidas em `state.json` ou `.reversa/config.toml` não são refeitas. | ||
| Use o mecanismo de menu interativo da engine (no Claude Code, `AskUserQuestion`). Em engines sem suporte, use menus numerados. Toda pergunta de escolha oferece opções com rótulo + descrição e uma opção final "Outro" aberta. | ||
| ### 0. Migração em andamento (condicional) | ||
| Execute a seção 0 de `step-02-resume.md` (verificação de `<output_folder>/migration/.state.json`). Se houver migração em andamento ou pausada, esta pergunta entra **primeiro** na entrevista, com as mesmas 4 opções do fluxo normal. Se o usuário escolher retomar a migração, encerre aqui indicando `/reversa-migrate`, como no fluxo normal. | ||
| ### 1. Dados de instalação (condicional) | ||
| Se `user_name` estiver vazio no `state.json`, colete **em um único bloco** (não uma por vez): nome do usuário, idioma do chat, idioma das especificações e nome do projeto. Salve nos campos `user_name`, `chat_language`, `doc_language` e `project`. | ||
| ### 2. Nível de documentação | ||
| A mesma pergunta que o fluxo normal faz após o Scout, antecipada. Se `doc_level` já estiver preenchido no `state.json`, pule. | ||
| > Qual nível de documentação você quer para este projeto? | ||
| > | ||
| > 1. **Essencial** (padrão): artefatos principais (code-analysis, domain, architecture, specs SDD). Ideal para projetos simples. | ||
| > 2. **Completo**: diagramas C4, ERD, ADRs, OpenAPI e matrizes de rastreabilidade. Recomendado para a maioria dos projetos. | ||
| > 3. **Detalhado**: máxima profundidade, flowcharts por função, ADRs expandidos, deployment, revisão cruzada obrigatória. | ||
| > 4. **Outro**: descreva o que precisa. | ||
| Resposta vazia assume `essencial`. Salve em `state.json` → `doc_level`. | ||
| ### 3. Organização das specs | ||
| A decisão do `step-03-specs-organization.md`, antecipada. Se a seção `[specs]` já estiver decidida (mescla de `config.toml` + `config.user.toml` com `granularity` válida), pule. | ||
| Como o Scout ainda não rodou, a sugestão dele não existe. Ofereça: | ||
| > Como organizar as specs deste projeto? | ||
| > | ||
| > 1. **Automática** (padrão): aceitar a sugestão que o Scout fizer após mapear o projeto. | ||
| > 2. **Por módulo de código** | ||
| > 3. **Por caso de uso** | ||
| > 4. **Por endpoint/contrato** | ||
| > 5. **Híbrida**: módulo na raiz, casos de uso aninhados. | ||
| > 6. **Por features** | ||
| > 7. **Customizada**: você informa as pastas de primeiro nível (colete os nomes ainda na entrevista). | ||
| > 8. **Outro**: descreva. | ||
| Resposta vazia assume `automática`. Guarde a escolha em `state.json` → campo novo `specs_choice` (valores: `auto`, `module`, `use-case`, `endpoint`, `hybrid`, `feature`, `custom` + `custom_folders`). A persistência definitiva em `config.toml` acontece após o Scout (ver adiante). | ||
| ### 4. Lacunas durante a análise | ||
| > Se surgirem dúvidas durante a análise (regras ambíguas, código sem contexto), o que prefiro fazer? | ||
| > | ||
| > 1. **Não parar** (padrão do modo autônomo): registro cada dúvida em `<output_folder>/questions.md`, marco 🔴 LACUNA na spec e sigo em frente. Você responde depois. | ||
| > 2. **Parar e perguntar**: pauso e pergunto no chat a cada dúvida. | ||
| > 3. **Outro**: descreva. | ||
| Salve em `state.json` → `answer_mode` (`file` para a opção 1, `chat` para a 2). | ||
| ### 5. Plano e confirmação única | ||
| Garanta que `.reversa/plan.md` existe (se não existir, crie como no passo 5 de `step-01-first-run.md`). Apresente o resumo do plano e encerre a entrevista com uma única confirmação: | ||
| > "[Nome], respostas registradas. Vou executar o plano completo de ponta a ponta: [lista resumida dos agentes]. A partir daqui não vou mais parar, exceto por necessidade real. Digite **INICIAR** para começar (ou ajuste o plano antes)." | ||
| Após o INICIAR, salve tudo em `state.json`, atualize `phase` para `"reconhecimento"` e comece. | ||
| ## Execução autônoma | ||
| Execute o plano sequencialmente, um agente por vez, exatamente como o `reversa` faz (informar o agente, ativar o skill, salvar checkpoint, marcar ✅ no `plan.md`, resumo breve). Com estes overrides: | ||
| 1. **Nenhuma confirmação intermediária.** Não pergunte "podemos começar com o Scout?", não ofereça o checkpoint preventivo de `/clear` + nova sessão, não peça CONTINUAR entre agentes. | ||
| 2. **Handoff automático.** Os skills dos agentes terminam sugerindo o próximo passo e pedindo "Digite CONTINUAR". Em modo autônomo, o orquestrador é quem responde: prossiga imediatamente para a próxima tarefa do plano, sem esperar o usuário. | ||
| 3. **Após o Scout:** expanda a Fase 2 do `plan.md` com uma tarefa por módulo (igual ao fluxo normal). **Não** apresente o menu de `doc_level` (já respondido). Em seguida, persista a organização das specs em `config.toml` seguindo as regras de escrita do `step-03` (atomic write, `scout_suggestion` imutável, non-destructive), usando a resposta da entrevista: | ||
| - `specs_choice = "auto"`: use `organization_suggestion.granularity` do `surface.json`. Se o Scout não tiver produzido sugestão, use `module` e registre aviso no relatório final. | ||
| - Qualquer outro valor: use o valor escolhido (e `custom_folders`, se houver). | ||
| 4. **Conflitos que o fluxo normal pergunta viram avisos.** Detecção de estrutura divergente em disco (RF-11) e override em `config.user.toml` (RF-18): aplique o comportamento seguro (criar estrutura nova em paralelo, preservar tudo, manter o override ativo) e acumule o aviso para o relatório final, sem parar. | ||
| 5. **Lacunas:** com `answer_mode = "file"`, nenhum agente pergunta no chat. Toda dúvida vai para `<output_folder>/questions.md` com contexto e marcador 🔴 LACUNA na spec correspondente. Com `answer_mode = "chat"`, as pausas de dúvida são permitidas (o usuário escolheu isso). | ||
| 6. **Checkpoints continuam obrigatórios.** Salve `state.json` após cada agente, seguindo `checkpoint-guide.md`. O modo autônomo não dispensa a retomabilidade. | ||
| 7. **Final do plano:** execute a verificação de regressão semântica (`step-04-regression-check.md`) normalmente. | ||
| ## Paradas legítimas (lista fechada) | ||
| Só interrompa a execução nestes casos: | ||
| 1. **Migração em andamento** detectada na entrevista (seção 0) e o usuário ainda não decidiu. | ||
| 2. **`answer_mode = "chat"`**: dúvidas dos agentes pausam, porque o usuário pediu. | ||
| 3. **Erro irrecuperável**: falha de IO, `state.json`/`config.toml` corrompido, pasta de saída sem permissão de escrita. Explique o erro e o que o usuário precisa corrigir. | ||
| 4. **Risco de violar a regra non-destructive**: qualquer situação em que prosseguir exigiria tocar arquivo fora das pastas do Reversa. | ||
| 5. **Estouro de contexto**: salve checkpoint imediatamente e diga: | ||
| > "[Nome], vou pausar para preservar o contexto. Tudo salvo. Digite `/reversa-autonomous` em uma nova sessão para continuar de onde paramos." | ||
| Qualquer outra vontade de perguntar não é parada legítima: escolha o padrão seguro, registre no relatório final e siga. | ||
| ## Retomada | ||
| Se `phase` já estiver definida no `state.json`, esta é uma retomada: | ||
| 1. Refaça apenas a seção 0 da entrevista (migração em andamento) e as perguntas cujas respostas ainda não estejam persistidas. | ||
| 2. Mostre o resumo de progresso (✅ concluídas, 🔄 atual, ⏳ pendentes) e retome a próxima tarefa pendente do `plan.md` **sem pedir CONTINUAR**. | ||
| 3. Não ofereça `/clear` + nova sessão na retomada. | ||
| ## Relatório final | ||
| Ao concluir o plano (e a verificação de regressão), apresente: | ||
| 1. Fases e agentes executados, com os artefatos gerados em `<output_folder>/`. | ||
| 2. Contagem por escala de confiança: 🟢 CONFIRMADO, 🟡 INFERIDO, 🔴 LACUNA. | ||
| 3. Perguntas pendentes em `<output_folder>/questions.md`, se houver, com pedido para o usuário respondê-las. | ||
| 4. Avisos acumulados durante a execução (RF-11, RF-18, Scout sem sugestão de organização, vereditos 🔴 da verificação de regressão). | ||
| 5. Sugestão de próximos passos (ex. `/reversa-forward` para evoluir o sistema, `/reversa-docs` para documentação viva). |
| // Fonte única da regra de não-destrutividade do Reversa: as únicas pastas em | ||
| // que o framework pode criar/escrever. Renderiza o texto da regra injetado em | ||
| // cada arquivo de entrada de engine no momento do install. | ||
| // | ||
| // `_reversa_sdd` e `_reversa_forward` são configuráveis pelo usuário | ||
| // (state.json: output_folder / forward_folder). `_reversa_docs` é fixo por | ||
| // enquanto; se um dia virar configurável (docs_folder), basta passá-lo aqui. | ||
| // Exportada também para uso futuro por updateGitignore/uninstall, que hoje | ||
| // só conhecem `.reversa/` + output_folder e divergem da regra global. | ||
| export function getWritableFolders({ | ||
| outputFolder = '_reversa_sdd', | ||
| forwardFolder = '_reversa_forward', | ||
| } = {}) { | ||
| return ['.reversa/', `${outputFolder}/`, '_reversa_docs/', `${forwardFolder}/`]; | ||
| } | ||
| export function renderPolicyBlock(opts = {}) { | ||
| const folders = getWritableFolders(opts).map((f) => `\`${f}\``); | ||
| const list = `${folders.slice(0, -1).join(', ')} e ${folders[folders.length - 1]}`; | ||
| return [ | ||
| 'Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto legado.', | ||
| `O Reversa escreve apenas em ${list}.`, | ||
| ].join('\n'); | ||
| } |
@@ -23,2 +23,26 @@ --- | ||
| ## Menu principal | ||
| | O que você quer fazer? | Comando | Time | | ||
| |---|---|---| | ||
| | Descobrir e documentar um sistema legado | `/reversa` | Reversa Agents Core | | ||
| | Criar um projeto novo a partir de uma ideia | `/reversa-new` | Code New Project Agents | | ||
| | Implementar ou evoluir código a partir das specs | `/reversa-forward` | Code Forward Agents | | ||
| | Planejar a migração de um legado | `/reversa-migrate` | Migration Agents | | ||
| | Gerar um mini-site visual da documentação | `/reversa-docs` | Documentation Agents | | ||
| | Entender qual agente usar | `/reversa-agents-help` | Guia de agentes | | ||
| Os times de Pricing e Translators têm comandos especializados. Use `/reversa-pricing-profile`, `/reversa-pricing-size`, `/reversa-pricing-estimate` ou `/reversa-n8n` conforme a necessidade. | ||
| --- | ||
| ## 🆕 Reversa New — o fundador de produto | ||
| **Comando:** `/reversa-new` | ||
| O fundador começa com uma ideia ainda bruta, investiga o problema, entende para quem o produto existe, consolida um PRD e transforma tudo em especificações prontas para implementação. | ||
| > Use o Reversa New para projetos greenfield. Ele conduz `Ideator → Researcher → Drafter → Spec SDD` e entrega o resultado ao `/reversa-forward`. | ||
| --- | ||
| ## 🎼 Reversa — orquestrador central | ||
@@ -126,9 +150,11 @@ **Comando:** `/reversa` | ||
| ``` | ||
| /reversa → orquestra tudo automaticamente | ||
| Projeto legado: /reversa → descoberta e especificações | ||
| Projeto novo: /reversa-new → PRD e specs → /reversa-forward | ||
| Migração: /reversa → /reversa-migrate → /reversa-forward | ||
| Ou manualmente: | ||
| Pipeline legado manual: | ||
| Scout → Archaeologist (N sessões) → Detective → Architect → Writer → Reviewer | ||
| Opcionais em qualquer fase: | ||
| Soul Extractor · Visor · Data Master · Design System | ||
| Soul Extractor · Visor · Data Master · Design System · Reversa Docs | ||
| ``` |
@@ -47,3 +47,3 @@ --- | ||
| - **JSON inline**: usuário fornece `modules.json` (lista de módulos) e/ou `deps.json` (grafo de dependências). | ||
| - **Caminho de arquivo**: usuário aponta para JSONs em `.reversa/documentation/assets/data/` (gerados pelo agente `/reversa-documentation`). | ||
| - **Caminho de arquivo**: usuário aponta para JSONs em `_reversa_docs/assets/data/` (gerados pelo agente `/reversa-documentation`). | ||
| - **Solicitado ao usuário**: se a skill é invocada sem dados, perguntar caminho ou pedir colagem inline. | ||
@@ -149,3 +149,3 @@ | ||
| O output é sempre HTML standalone. Salvar no caminho indicado pelo agente orquestrador (geralmente `.reversa/documentation/arquitetura.html`). | ||
| O output é sempre HTML standalone. Salvar no caminho indicado pelo agente orquestrador (geralmente `_reversa_docs/arquitetura.html`). | ||
@@ -152,0 +152,0 @@ Quando invocada fora do contexto do `/reversa-documentation`, perguntar caminho de destino ou usar `<modo>-<timestamp>.html` no diretório atual. |
@@ -23,6 +23,6 @@ --- | ||
| - `.reversa/documentation/assets/data/modules.json` (do Mapper, ou extrai sob demanda) | ||
| - `.reversa/documentation/assets/data/deps.json` | ||
| - `_reversa_docs/assets/data/modules.json` (do Mapper, ou extrai sob demanda) | ||
| - `_reversa_docs/assets/data/deps.json` | ||
| - `.reversa/chronicle.md` (histórico, se existir) | ||
| - `.reversa/documentation/.config.json` | ||
| - `_reversa_docs/.config.json` | ||
| - Skill: `reversa-highcharts-visualizer` | ||
@@ -32,6 +32,6 @@ | ||
| - `.reversa/documentation/metricas.html` (dashboard 4+ gráficos) | ||
| - `.reversa/documentation/timeline.html` (omitida se chronicle ausente) | ||
| - `.reversa/documentation/assets/data/metrics.json` | ||
| - `.reversa/documentation/assets/data/timeline.json` (apenas se chronicle existir) | ||
| - `_reversa_docs/metricas.html` (dashboard 4+ gráficos) | ||
| - `_reversa_docs/timeline.html` (omitida se chronicle ausente) | ||
| - `_reversa_docs/assets/data/metrics.json` | ||
| - `_reversa_docs/assets/data/timeline.json` (apenas se chronicle existir) | ||
@@ -41,5 +41,5 @@ ## Antes de começar | ||
| 1. Leia `.reversa/state.json` para `user_name`, `chat_language`. | ||
| 2. Leia `.reversa/documentation/.config.json`. Se ausente, conduza entrevista mínima. | ||
| 2. Leia `_reversa_docs/.config.json`. Se ausente, conduza entrevista mínima. | ||
| 3. Verifique presença de `modules.json` e `deps.json`. Se ausentes, invoque os scripts do Mapper para gerá-los (`extract_modules.py`, `extract_deps.py`). Política de cache em `agents/reversa-docs-mapper/references/extraction-policy.md`. | ||
| 4. Verifique se `.reversa/documentation/assets/vendor/highcharts.js` (e módulos associados) existe. Se ausente em modo isolado, execute o Passo 0 do Publisher (`agents/reversa-docs-publisher/SKILL.md`) lendo `vendor-pins.yaml` para baixar Highcharts + módulos com retry de CDN. No modo orquestrado, isso já foi feito na Fase 0. | ||
| 4. Verifique se `_reversa_docs/assets/vendor/highcharts.js` (e módulos associados) existe. Se ausente em modo isolado, execute o Passo 0 do Publisher (`agents/reversa-docs-publisher/SKILL.md`) lendo `vendor-pins.yaml` para baixar Highcharts + módulos com retry de CDN. No modo orquestrado, isso já foi feito na Fase 0. | ||
@@ -80,3 +80,3 @@ ## Entrevista mínima | ||
| Salve em `.reversa/documentation/assets/data/metrics.json`. | ||
| Salve em `_reversa_docs/assets/data/metrics.json`. | ||
@@ -97,3 +97,3 @@ ### 2. Gerar `metricas.html` (dashboard) | ||
| 4. Layout responsivo em grid 2x2. Adicione 5º/6º gráficos se houver dados ricos (ex: `language_distribution`). | ||
| 5. Salve em `.reversa/documentation/metricas.html`. | ||
| 5. Salve em `_reversa_docs/metricas.html`. | ||
@@ -108,3 +108,3 @@ ### 3. Derivar `timeline.json` (se chronicle existir) | ||
| --src .reversa/chronicle.md \ | ||
| --out .reversa/documentation/assets/data/timeline.json | ||
| --out _reversa_docs/assets/data/timeline.json | ||
| ``` | ||
@@ -121,3 +121,3 @@ 4. Se Python indisponível, faça parsing inline: cada item de bullet ou heading com data ISO-8601 vira um evento. | ||
| 6. Cada evento clicável abre painel lateral com detalhes (use `EVENT_DETAILS` marker). | ||
| 7. Salve em `.reversa/documentation/timeline.html`. | ||
| 7. Salve em `_reversa_docs/timeline.html`. | ||
@@ -131,7 +131,7 @@ ### 5. Atualizar `.state.json` | ||
| `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever. | ||
| `_reversa_docs/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever. | ||
| ## Diretiva non-destructive | ||
| Apenas escreve em `.reversa/documentation/`. `chronicle.md`, `modules.json`, `deps.json` são lidos sem modificação. | ||
| Apenas escreve em `_reversa_docs/`. `chronicle.md`, `modules.json`, `deps.json` são lidos sem modificação. | ||
@@ -166,3 +166,3 @@ ## Tratamento gracioso | ||
| - Nunca escreva fora de `.reversa/documentation/`. | ||
| - Nunca escreva fora de `_reversa_docs/`. | ||
| - Nunca modifique chronicle.md ou os JSONs do Mapper. | ||
@@ -169,0 +169,0 @@ - Nunca rode varredura de credenciais. |
| # Política de extração de dados (Mapper) | ||
| Define quando invocar scripts de extração vs reusar cache em `.reversa/documentation/assets/data/`. | ||
| Define quando invocar scripts de extração vs reusar cache em `_reversa_docs/assets/data/`. | ||
@@ -9,3 +9,3 @@ ## Cache hit (reutilizar) | ||
| 1. O arquivo existe em `.reversa/documentation/assets/data/<nome>.json`. | ||
| 1. O arquivo existe em `_reversa_docs/assets/data/<nome>.json`. | ||
| 2. `mtime` do JSON é maior que o `mtime` máximo entre todos os arquivos fonte relevantes: | ||
@@ -23,7 +23,7 @@ - Para `modules.json`: maior `mtime` dentro do código fonte (excluindo `.reversa/`, `_reversa_sdd/`, `node_modules/`, `.git/`). | ||
| --root . \ | ||
| --out .reversa/documentation/assets/data/modules.json | ||
| --out _reversa_docs/assets/data/modules.json | ||
| python templates/documentation/scripts/extract_deps.py \ | ||
| --modules .reversa/documentation/assets/data/modules.json \ | ||
| --out .reversa/documentation/assets/data/deps.json | ||
| --modules _reversa_docs/assets/data/modules.json \ | ||
| --out _reversa_docs/assets/data/deps.json | ||
| ``` | ||
@@ -30,0 +30,0 @@ |
@@ -23,3 +23,3 @@ --- | ||
| - `.reversa/documentation/.config.json` (entrevista, seed, estilo visual) | ||
| - `_reversa_docs/.config.json` (entrevista, seed, estilo visual) | ||
| - Código fonte do projeto legado (LOC, complexidade, dependências) | ||
@@ -31,7 +31,7 @@ - `_reversa_sdd/architecture.md` se houver (topologia detectada) | ||
| - `.reversa/documentation/arquitetura.html` | ||
| - `.reversa/documentation/modulos.html` | ||
| - `.reversa/documentation/topologia.html` (omitido se sem topologia detectada) | ||
| - `.reversa/documentation/assets/data/modules.json` | ||
| - `.reversa/documentation/assets/data/deps.json` | ||
| - `_reversa_docs/arquitetura.html` | ||
| - `_reversa_docs/modulos.html` | ||
| - `_reversa_docs/topologia.html` (omitido se sem topologia detectada) | ||
| - `_reversa_docs/assets/data/modules.json` | ||
| - `_reversa_docs/assets/data/deps.json` | ||
@@ -43,3 +43,3 @@ Schemas formais em `specs/reversa-docs/design.md`, seção "JSONs intermediários em assets/data/". | ||
| 1. Leia `.reversa/state.json` para `user_name`, `chat_language`. | ||
| 2. Leia `.reversa/documentation/.config.json`. Se não existir, conduza a entrevista mínima. | ||
| 2. Leia `_reversa_docs/.config.json`. Se não existir, conduza a entrevista mínima. | ||
| 3. Verifique `templates/documentation/scripts/extract_modules.py` e `extract_deps.py` acessíveis. | ||
@@ -74,3 +74,3 @@ | ||
| --root . \ | ||
| --out .reversa/documentation/assets/data/modules.json | ||
| --out _reversa_docs/assets/data/modules.json | ||
| ``` | ||
@@ -80,4 +80,4 @@ - Mesmo para `deps.json`: | ||
| python templates/documentation/scripts/extract_deps.py \ | ||
| --modules .reversa/documentation/assets/data/modules.json \ | ||
| --out .reversa/documentation/assets/data/deps.json | ||
| --modules _reversa_docs/assets/data/modules.json \ | ||
| --out _reversa_docs/assets/data/deps.json | ||
| ``` | ||
@@ -103,3 +103,3 @@ | ||
| 4. Adicione sidebar com `data-param` controlando: escala vertical, intensidade da luz, paleta. Use o helper `templates/documentation/assets/js/sidebar.js` (já incluso pelo viewer). | ||
| 5. Salve em `.reversa/documentation/arquitetura.html`. | ||
| 5. Salve em `_reversa_docs/arquitetura.html`. | ||
@@ -114,3 +114,3 @@ ### 3. Gerar `modulos.html` (force-directed 2D) | ||
| 6. Sidebar com filtros: linguagem, tipo, força de repulsão, distância mínima. | ||
| 7. Salve em `.reversa/documentation/modulos.html`. | ||
| 7. Salve em `_reversa_docs/modulos.html`. | ||
@@ -123,7 +123,7 @@ ### 4. Gerar `topologia.html` (apenas se topologia detectada) | ||
| 4. Renderize side-by-side usando `templates/documentation/pages/topologia.html.tpl`. HTML manual ou D3 hierárquico, depende da complexidade. | ||
| 5. Salve em `.reversa/documentation/topologia.html`. | ||
| 5. Salve em `_reversa_docs/topologia.html`. | ||
| ### 5. Atualizar `.state.json` | ||
| Após cada página gerada, atualize `.reversa/documentation/.state.json`: | ||
| Após cada página gerada, atualize `_reversa_docs/.state.json`: | ||
| - Adicione `cartographer` (mapper) ao array `completedAgents` ao final. | ||
@@ -134,7 +134,7 @@ - Para cada página gerada: adicione `{status: "created", agent: "reversa-docs-mapper", hash: sha256(conteudo)}` em `pages`. | ||
| Se qualquer página alvo já existe, mova para `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de escrever. Backup é por execução, não por arquivo. | ||
| Se qualquer página alvo já existe, mova para `_reversa_docs/.backup-<YYYYMMDD-HHMMSS>/` antes de escrever. Backup é por execução, não por arquivo. | ||
| ## Diretiva non-destructive | ||
| Apenas escreve em `.reversa/documentation/`. Código fonte do projeto legado é lido para análise estática, nunca modificado. | ||
| Apenas escreve em `_reversa_docs/`. Código fonte do projeto legado é lido para análise estática, nunca modificado. | ||
@@ -171,3 +171,3 @@ ## Tratamento gracioso de fontes ausentes | ||
| - Nunca escreva fora de `.reversa/documentation/`. | ||
| - Nunca escreva fora de `_reversa_docs/`. | ||
| - Nunca modifique código fonte do projeto legado. | ||
@@ -174,0 +174,0 @@ - Nunca rode varredura de credenciais. Use gitleaks/trufflehog externos se o usuário pedir. |
@@ -10,3 +10,3 @@ # Diretórios varridos pelo Publisher em auto-discovery de HTMLs auxiliares. | ||
| exclude: | ||
| - ".reversa/documentation/" | ||
| - "_reversa_docs/" | ||
| - ".reversa/_config/" | ||
@@ -13,0 +13,0 @@ - ".reversa/context/" |
@@ -19,3 +19,3 @@ # vendor-pins.yaml | ||
| # CDNs por arquivo: unpkg + jsdelivr cobrem 99% das falhas observadas. | ||
| # - "local" é o caminho relativo dentro de .reversa/documentation/. Os | ||
| # - "local" é o caminho relativo dentro de _reversa_docs/. Os | ||
| # templates HTML referenciam exatamente esse caminho via <script src>. | ||
@@ -22,0 +22,0 @@ |
@@ -23,6 +23,6 @@ --- | ||
| - Todas as páginas existentes em `.reversa/documentation/` (HTMLs gerados pelos 3 agentes anteriores) | ||
| - Todas as páginas existentes em `_reversa_docs/` (HTMLs gerados pelos 3 agentes anteriores) | ||
| - HTMLs auxiliares em `_reversa_sdd/` e `.reversa/` (descobertos via meta-tag `reversa-category`) | ||
| - `.reversa/documentation/.config.json` (seed, estilo visual, project name) | ||
| - `.reversa/documentation/.state.json` (cronograma, agentes concluídos) | ||
| - `_reversa_docs/.config.json` (seed, estilo visual, project name) | ||
| - `_reversa_docs/.state.json` (cronograma, agentes concluídos) | ||
| - Skill `reversa-selo-generativo` | ||
@@ -32,8 +32,8 @@ | ||
| - `.reversa/documentation/index.html` (porta de entrada) | ||
| - `.reversa/documentation/assets/img/seal.svg` (selo grande do hero) | ||
| - `.reversa/documentation/assets/img/seal-mini.svg` (mini-selo do header) | ||
| - `.reversa/documentation/assets/js/data.js` (todos os JSONs intermediários embedados em `window.RV_DATA`) | ||
| - `.reversa/documentation/assets/vendor/*` (Three.js, OrbitControls, D3, Highcharts e módulos, baixados localmente) | ||
| - `.reversa/documentation/.state.json` (atualizado com telemetria final, incluindo `smokeTestFailed`/`smokeTestErrors`) | ||
| - `_reversa_docs/index.html` (porta de entrada) | ||
| - `_reversa_docs/assets/img/seal.svg` (selo grande do hero) | ||
| - `_reversa_docs/assets/img/seal-mini.svg` (mini-selo do header) | ||
| - `_reversa_docs/assets/js/data.js` (todos os JSONs intermediários embedados em `window.RV_DATA`) | ||
| - `_reversa_docs/assets/vendor/*` (Three.js, OrbitControls, D3, Highcharts e módulos, baixados localmente) | ||
| - `_reversa_docs/.state.json` (atualizado com telemetria final, incluindo `smokeTestFailed`/`smokeTestErrors`) | ||
| - Todas as páginas existentes têm `<!-- MINI_SEAL_SVG -->` substituído pelo mini-selo e `<!-- NAV_LINKS -->` substituído pelo menu derivado de `pagesGenerated`. | ||
@@ -53,4 +53,4 @@ | ||
| 1. Leia `.reversa/state.json` para `user_name`, `chat_language`. | ||
| 2. Leia `.reversa/documentation/.config.json` para seed, visualStyle, projectName. | ||
| 3. Liste páginas existentes em `.reversa/documentation/` (excluindo `assets/`, `.config.json`, `.state.json`, `.logs/`, `.backup-*`). | ||
| 2. Leia `_reversa_docs/.config.json` para seed, visualStyle, projectName. | ||
| 3. Liste páginas existentes em `_reversa_docs/` (excluindo `assets/`, `.config.json`, `.state.json`, `.logs/`, `.backup-*`). | ||
| 4. Leia `agents/reversa-docs-publisher/references/auxiliary_sources.yaml` para configuração de varredura. | ||
@@ -86,3 +86,3 @@ | ||
| Salve em `.reversa/documentation/assets/img/seal.svg`. | ||
| Salve em `_reversa_docs/assets/img/seal.svg`. | ||
@@ -93,3 +93,3 @@ ### 2. Gerar mini-selo (`seal-mini.svg`) | ||
| Salve em `.reversa/documentation/assets/img/seal-mini.svg`. | ||
| Salve em `_reversa_docs/assets/img/seal-mini.svg`. | ||
@@ -127,3 +127,3 @@ ### 3. Gerar `assets/js/data.js` (única fonte de dados das páginas) | ||
| 1. Liste os JSONs em `.reversa/documentation/assets/data/` produzidos pelos agentes anteriores. Se algum esperado estiver ausente, registre a chave correspondente como `{}` (ou `null`) e siga. | ||
| 1. Liste os JSONs em `_reversa_docs/assets/data/` produzidos pelos agentes anteriores. Se algum esperado estiver ausente, registre a chave correspondente como `{}` (ou `null`) e siga. | ||
| 2. Leia cada JSON e embed o conteúdo direto no script (sem `JSON.parse(...)` em runtime, deixe o objeto já pronto). Quando o JSON for grande (acima de 200 KB), avalie minificar e ainda assim manter inline. Não comprima. | ||
@@ -142,3 +142,3 @@ 3. Embed também `seal.svg` e `seal-mini.svg` como strings (`sealSvg`, `sealMiniSvg`). | ||
| | deck | deck.html | Deck | | ||
| 5. Salve em `.reversa/documentation/assets/js/data.js`. | ||
| 5. Salve em `_reversa_docs/assets/js/data.js`. | ||
| 6. Garanta que `viewer.html` (e portanto todas as páginas que herdam dele) carrega `<script src="assets/js/data.js"></script>` **antes** de `nav.js`. Se uma página foi gerada por agente anterior sem essa referência, injete a tag logo no início de `<!-- SCRIPTS -->` (ou no `<head>` se necessário) ao reescrever a página no passo 5. | ||
@@ -150,3 +150,3 @@ | ||
| Para cada página HTML existente em `.reversa/documentation/` (exceto `index.html` que será gerado depois): | ||
| Para cada página HTML existente em `_reversa_docs/` (exceto `index.html` que será gerado depois): | ||
@@ -165,3 +165,3 @@ 1. Leia o conteúdo da página. | ||
| - **Raízes**: `_reversa_sdd/` e `.reversa/` (excluindo `.reversa/documentation/`, `.reversa/_config/`, `.reversa/context/`). | ||
| - **Raízes**: `_reversa_sdd/` e `.reversa/` (excluindo `.reversa/_config/`, `.reversa/context/`). | ||
| - **Profundidade máxima**: 6 níveis. | ||
@@ -185,3 +185,3 @@ - **Timeout**: 10 segundos no total. | ||
| 1. **Hero**: selo grande inline + nome do projeto + tagline (1 frase derivada de `soul.md` ou placeholder). | ||
| 2. **Sumário**: cards linkando para todas as páginas do time presentes em `.reversa/documentation/`. Cada card tem ícone, título e 1 linha descritiva. Ordem: arquitetura, modulos, topologia, metricas, timeline, glossario, deck, features (link agregado), depois index é a porta). | ||
| 2. **Sumário**: cards linkando para todas as páginas do time presentes em `_reversa_docs/`. Cada card tem ícone, título e 1 linha descritiva. Ordem: arquitetura, modulos, topologia, metricas, timeline, glossario, deck, features (link agregado), depois index é a porta). | ||
| 3. **Seções de auxiliares descobertos** (uma por categoria): | ||
@@ -198,3 +198,3 @@ - **Code Reviews**: links para HTMLs com `category=review` | ||
| - GENERATED_AT = ISO-8601 atual | ||
| 5. Salve em `.reversa/documentation/index.html`. | ||
| 5. Salve em `_reversa_docs/index.html`. | ||
@@ -204,3 +204,3 @@ ### 7. Validar links relativos e nav | ||
| Para cada link `<a href="...">` em `index.html` **e em cada `<nav>` das demais páginas**: | ||
| - Se o href é relativo, verifique se o destino existe em `.reversa/documentation/` (ou no caminho relativo correspondente). | ||
| - Se o href é relativo, verifique se o destino existe em `_reversa_docs/` (ou no caminho relativo correspondente). | ||
| - Registre links quebrados em `.state.json` campo `brokenLinks: [{from, href, expected_path}]`. | ||
@@ -225,3 +225,3 @@ | ||
| ```python | ||
| # 1. Subir http.server em porta efêmera apontando para .reversa/documentation/ | ||
| # 1. Subir http.server em porta efêmera apontando para _reversa_docs/ | ||
| # 2. Para cada página em pagesGenerated: | ||
@@ -290,7 +290,7 @@ # a. GET http://localhost:<porta>/<pagina> | ||
| `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever `index.html`, `seal.svg`, `seal-mini.svg`, ou qualquer página onde o mini-selo é injetado. | ||
| `_reversa_docs/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever `index.html`, `seal.svg`, `seal-mini.svg`, ou qualquer página onde o mini-selo é injetado. | ||
| ## Diretiva non-destructive | ||
| Apenas escreve em `.reversa/documentation/`. Auto-discovery só **lê** HTMLs em outros diretórios. Nunca modifica ou apaga HTMLs auxiliares dos outros agentes. | ||
| Apenas escreve em `_reversa_docs/`. Auto-discovery só **lê** HTMLs em outros diretórios. Nunca modifica ou apaga HTMLs auxiliares dos outros agentes. | ||
@@ -310,3 +310,3 @@ ## Tratamento gracioso | ||
| > | ||
| > Caminho: `.reversa/documentation/index.html` | ||
| > Caminho: `_reversa_docs/index.html` | ||
| > | ||
@@ -323,4 +323,4 @@ > Estatísticas: | ||
| > Como abrir: | ||
| > - **Duplo clique funciona** (Windows: `start .reversa/documentation/index.html`, macOS: `open ...`, Linux: `xdg-open ...`). Como o Publisher embedou dados em `assets/js/data.js` e baixou vendor offline, o mini-site abre via `file://` sem CORS. | ||
| > - **Para hot-reload** durante edição: `python -m http.server 8080` na pasta `.reversa/documentation/` e acesse `http://localhost:8080/`. | ||
| > - **Duplo clique funciona** (Windows: `start _reversa_docs/index.html`, macOS: `open ...`, Linux: `xdg-open ...`). Como o Publisher embedou dados em `assets/js/data.js` e baixou vendor offline, o mini-site abre via `file://` sem CORS. | ||
| > - **Para hot-reload** durante edição: `python -m http.server 8080` na pasta `_reversa_docs/` e acesse `http://localhost:8080/`. | ||
| > | ||
@@ -333,3 +333,3 @@ > Próximo agente sugerido: [contextual conforme tabela acima] | ||
| - Nunca escreva fora de `.reversa/documentation/`. | ||
| - Nunca escreva fora de `_reversa_docs/`. | ||
| - Nunca modifique HTMLs auxiliares descobertos em outros diretórios. | ||
@@ -336,0 +336,0 @@ - Nunca rode varredura de credenciais. |
@@ -25,4 +25,4 @@ --- | ||
| - `.reversa/soul.md` (alma do projeto) | ||
| - `.reversa/documentation/.config.json` | ||
| - `.reversa/documentation/assets/data/features-index.json` (gerado pelo próprio Storyteller) | ||
| - `_reversa_docs/.config.json` | ||
| - `_reversa_docs/assets/data/features-index.json` (gerado pelo próprio Storyteller) | ||
| - Skill `reversa-image-prompt-json` (opcional, capas em estilo premium) | ||
@@ -32,7 +32,7 @@ | ||
| - `.reversa/documentation/glossario.html` | ||
| - `.reversa/documentation/deck.html` | ||
| - `.reversa/documentation/features/<nome-kebab>.html` (uma por spec selecionada) | ||
| - `.reversa/documentation/assets/data/soul.json` | ||
| - `.reversa/documentation/assets/data/features-index.json` | ||
| - `_reversa_docs/glossario.html` | ||
| - `_reversa_docs/deck.html` | ||
| - `_reversa_docs/features/<nome-kebab>.html` (uma por spec selecionada) | ||
| - `_reversa_docs/assets/data/soul.json` | ||
| - `_reversa_docs/assets/data/features-index.json` | ||
@@ -42,3 +42,3 @@ ## Antes de começar | ||
| 1. Leia `.reversa/state.json` para `user_name`, `chat_language`. | ||
| 2. Leia `.reversa/documentation/.config.json`. Se ausente, conduza entrevista mínima. | ||
| 2. Leia `_reversa_docs/.config.json`. Se ausente, conduza entrevista mínima. | ||
| 3. Verifique fontes disponíveis: `soul.md`, `_reversa_sdd/*/requirements.md`. | ||
@@ -60,3 +60,3 @@ 4. Storyteller geralmente não usa libs externas pesadas (glossário é HTML puro + JS inline, deck é navegação por setas), mas se algum recurso premium (capa com canvas, slide com chart) for habilitado, garanta vendor disponível em `assets/vendor/` antes (em modo isolado, execute o Passo 0 do Publisher; em modo orquestrado já foi feito na Fase 0). | ||
| --src .reversa/soul.md \ | ||
| --out .reversa/documentation/assets/data/soul.json | ||
| --out _reversa_docs/assets/data/soul.json | ||
| ``` | ||
@@ -73,3 +73,3 @@ | ||
| --sdd-root _reversa_sdd \ | ||
| --out .reversa/documentation/assets/data/features-index.json | ||
| --out _reversa_docs/assets/data/features-index.json | ||
| ``` | ||
@@ -92,3 +92,3 @@ | ||
| - Deixe `<!-- NAV_LINKS -->` como está (Publisher backpatcha). | ||
| 6. Salve em `.reversa/documentation/glossario.html`. | ||
| 6. Salve em `_reversa_docs/glossario.html`. | ||
@@ -127,3 +127,3 @@ ### 4. Gerar `deck.html` | ||
| Salve em `.reversa/documentation/deck.html`. | ||
| Salve em `_reversa_docs/deck.html`. | ||
@@ -143,3 +143,3 @@ ### 5. Gerar `features/<slug>.html` (uma por spec) | ||
| - Aplique chassis com PAGE_ID = `feature-<slug>`, REVERSA_TEMPLATE = "feature". | ||
| - Salve em `.reversa/documentation/features/<slug>.html`. | ||
| - Salve em `_reversa_docs/features/<slug>.html`. | ||
@@ -156,7 +156,7 @@ Se nenhuma spec disponível, omita totalmente o diretório `features/` e registre em `pagesOmitted`. | ||
| `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever. Inclua diretório `features/` no backup. | ||
| `_reversa_docs/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever. Inclua diretório `features/` no backup. | ||
| ## Diretiva non-destructive | ||
| Apenas escreve em `.reversa/documentation/`. `soul.md` e `_reversa_sdd/` são lidos sem modificação. | ||
| Apenas escreve em `_reversa_docs/`. `soul.md` e `_reversa_sdd/` são lidos sem modificação. | ||
@@ -193,3 +193,3 @@ ## Tratamento gracioso | ||
| - Nunca escreva fora de `.reversa/documentation/`. | ||
| - Nunca escreva fora de `_reversa_docs/`. | ||
| - Nunca modifique `soul.md`, `chronicle.md` ou specs em `_reversa_sdd/`. | ||
@@ -196,0 +196,0 @@ - Nunca rode varredura de credenciais. |
| { | ||
| "$schema": "http://json-schema.org/draft-07/schema#", | ||
| "title": "Reversa Docs Config", | ||
| "description": "Configuração persistida em .reversa/documentation/.config.json após a entrevista do /reversa-docs. Reusada por execuções subsequentes e por agentes isolados.", | ||
| "description": "Configuração persistida em _reversa_docs/.config.json após a entrevista do /reversa-docs. Reusada por execuções subsequentes e por agentes isolados.", | ||
| "type": "object", | ||
@@ -6,0 +6,0 @@ "required": ["schemaVersion", "generatedAt", "projectName", "interview", "seed", "knowledgeSources"], |
| --- | ||
| name: reversa-docs | ||
| description: "Orquestrador do Time Reversa Docs. Gera um mini-site HTML autocontido em .reversa/documentation/ com arquitetura 3D, dashboards, glossário, deck e páginas por feature, a partir do conhecimento já extraído pelo core do Reversa. Ative com /reversa-docs, reversa-docs, gerar documentação visual, mini-site do projeto, documentação interativa." | ||
| description: "Orquestrador do Time Reversa Docs. Gera um mini-site HTML autocontido em _reversa_docs/ com arquitetura 3D, dashboards, glossário, deck e páginas por feature, a partir do conhecimento já extraído pelo core do Reversa. Ative com /reversa-docs, reversa-docs, gerar documentação visual, mini-site do projeto, documentação interativa." | ||
| license: MIT | ||
@@ -15,3 +15,3 @@ compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills. | ||
| Você é o Reversa Docs, orquestrador do Time Reversa Docs. Sua missão é transformar o conhecimento extraído pelos demais agentes do core (alma, crônica, módulos, dependências, specs SDD) em um mini-site HTML autocontido e navegável publicado em `.reversa/documentation/`. | ||
| Você é o Reversa Docs, orquestrador do Time Reversa Docs. Sua missão é transformar o conhecimento extraído pelos demais agentes do core (alma, crônica, módulos, dependências, specs SDD) em um mini-site HTML autocontido e navegável publicado em `_reversa_docs/`. | ||
@@ -27,3 +27,3 @@ O time tem 4 agentes especialistas, executados em sequência fixa: **Mapper** (estrutura espacial), **Analyst** (dados quantitativos), **Storyteller** (narrativa e onboarding) e **Publisher** (integração final, selo, auto-discovery). Cada agente também é invocável isoladamente via `/reversa-docs-<nome>` para regeneração focada. | ||
| 1. Leia `.reversa/state.json`, especialmente: `user_name`, `chat_language`, `output_folder` (padrão `_reversa_sdd`). | ||
| 2. Leia `.reversa/documentation/.config.json` se existir. | ||
| 2. Leia `_reversa_docs/.config.json` se existir. | ||
| 3. Detecte fontes disponíveis lendo `references/expected_sources.yaml` e verificando a presença de cada uma. Popule mentalmente o objeto `knowledgeSources`. | ||
@@ -33,5 +33,5 @@ | ||
| Nada fora de `.reversa/documentation/` é modificado. Os artefatos do core (`_reversa_sdd/`, `.reversa/soul.md`, `.reversa/chronicle.md`, código fonte do projeto legado) são apenas lidos. | ||
| Nada fora de `_reversa_docs/` é modificado. Os artefatos do core (`_reversa_sdd/`, `.reversa/soul.md`, `.reversa/chronicle.md`, código fonte do projeto legado) são apenas lidos. | ||
| Se `.reversa/documentation/` já existir com conteúdo, leia `.state.json` e ofereça ao usuário as opções de regeneração antes de sobrescrever (ver seção "Regeneração"). | ||
| Se `_reversa_docs/` já existir com conteúdo, leia `.state.json` e ofereça ao usuário as opções de regeneração antes de sobrescrever (ver seção "Regeneração"). | ||
@@ -101,3 +101,3 @@ ## Processo | ||
| Persista as respostas em `.reversa/documentation/.config.json` seguindo o schema definido em `references/config-schema.json`. | ||
| Persista as respostas em `_reversa_docs/.config.json` seguindo o schema definido em `references/config-schema.json`. | ||
@@ -139,3 +139,3 @@ ### 3. Seed determinístico | ||
| 2. Ative o skill `reversa-docs-<nome>` correspondente. Se a engine não suportar ativação direta, leia o `SKILL.md` do agente e execute no contexto atual passando o `.config.json` como entrada. | ||
| 3. Após conclusão, atualize `.reversa/documentation/.state.json`: adicione o agente ao array `completedAgents`, registre as páginas geradas em `pages`, calcule hash sha256 de cada página. | ||
| 3. Após conclusão, atualize `_reversa_docs/.state.json`: adicione o agente ao array `completedAgents`, registre as páginas geradas em `pages`, calcule hash sha256 de cada página. | ||
| 4. Apresente resumo: | ||
@@ -158,3 +158,3 @@ | ||
| > | ||
| > Caminho: `.reversa/documentation/index.html` | ||
| > Caminho: `_reversa_docs/index.html` | ||
| > Total de páginas: [N] | ||
@@ -168,6 +168,6 @@ > Páginas omitidas: [N] | ||
| > - **Duplo clique funciona**: o Publisher embedou dados em `assets/js/data.js` e baixou Three.js, D3 e Highcharts em `assets/vendor/`. Não precisa de servidor para abrir. | ||
| > - Windows: `start .reversa/documentation/index.html` | ||
| > - macOS: `open .reversa/documentation/index.html` | ||
| > - Linux: `xdg-open .reversa/documentation/index.html` | ||
| > - **Para hot-reload durante edição**: `python -m http.server 8080` na pasta `.reversa/documentation/` e acesse `http://localhost:8080/`. | ||
| > - Windows: `start _reversa_docs/index.html` | ||
| > - macOS: `open _reversa_docs/index.html` | ||
| > - Linux: `xdg-open _reversa_docs/index.html` | ||
| > - **Para hot-reload durante edição**: `python -m http.server 8080` na pasta `_reversa_docs/` e acesse `http://localhost:8080/`. | ||
| > | ||
@@ -187,5 +187,5 @@ > Próximo agente sugerido: [contextual: `/reversa-forward` se há specs, `/reversa-chronicler` se não há crônica recente, etc.] | ||
| Se `.reversa/documentation/.state.json` já existe (segunda execução), apresente: | ||
| Se `_reversa_docs/.state.json` já existe (segunda execução), apresente: | ||
| > "[Nome], já existe um mini-site em `.reversa/documentation/` gerado em [data do `lastCheckpoint`]. O que você quer fazer? | ||
| > "[Nome], já existe um mini-site em `_reversa_docs/` gerado em [data do `lastCheckpoint`]. O que você quer fazer? | ||
| > | ||
@@ -201,7 +201,7 @@ > 1. **Manter tudo** — Sair sem regenerar. | ||
| Backup automático em `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de qualquer escrita destrutiva. | ||
| Backup automático em `_reversa_docs/.backup-<YYYYMMDD-HHMMSS>/` antes de qualquer escrita destrutiva. | ||
| ## Telemetria local | ||
| Ao final do pipeline (sucesso ou falha parcial), grave em `.reversa/documentation/.state.json`: | ||
| Ao final do pipeline (sucesso ou falha parcial), grave em `_reversa_docs/.state.json`: | ||
| - `pipelineDurationMs` (int) | ||
@@ -223,3 +223,3 @@ - `pagesGenerated` (array) | ||
| - Nunca escreva fora de `.reversa/documentation/`. | ||
| - Nunca escreva fora de `_reversa_docs/`. | ||
| - Nunca modifique artefatos do core (`_reversa_sdd/`, `.reversa/soul.md`, `.reversa/chronicle.md`). | ||
@@ -226,0 +226,0 @@ - Nunca apague ou sobrescreva sem backup automático em `.backup-<timestamp>/`. |
+7
-0
@@ -43,2 +43,9 @@ #!/usr/bin/env node | ||
| Fluxos principais no chat (após a instalação): | ||
| /reversa Descobre e documenta um sistema existente | ||
| /reversa-new Cria PRD e specs para um projeto novo | ||
| /reversa-forward Implementa ou evolui código a partir das specs | ||
| /reversa-migrate Planeja a migração de um sistema legado | ||
| /reversa-docs Gera o mini-site visual da documentação | ||
| Documentação: https://github.com/sandeco/reversa | ||
@@ -45,0 +52,0 @@ `); |
@@ -17,2 +17,3 @@ import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs'; | ||
| const AGENT_LABELS = { | ||
| 'reversa-autonomous': 'Autonomous: runs the full /reversa pipeline without intermediate stops (/reversa-autonomous)', | ||
| 'reversa-scout': 'Scout: reconnaissance', | ||
@@ -19,0 +20,0 @@ 'reversa-archaeologist': 'Archaeologist: excavation', |
@@ -68,3 +68,6 @@ import { existsSync, readFileSync, writeFileSync } from 'fs'; | ||
| seenEntryFiles.add(engine.entryFile); | ||
| await writer.installEntryFile(engine); | ||
| await writer.installEntryFile(engine, { | ||
| outputFolder: state.output_folder, | ||
| forwardFolder: state.forward_folder, | ||
| }); | ||
| } | ||
@@ -71,0 +74,0 @@ for (const agent of installedAgents) { |
@@ -103,3 +103,6 @@ import { join, resolve } from 'path'; | ||
| seenEntryFiles.add(engine.entryFile); | ||
| await writer.installEntryFile(engine); | ||
| await writer.installEntryFile(engine, { | ||
| outputFolder: answers.output_folder, | ||
| forwardFolder: answers.forward_folder, | ||
| }); | ||
| } | ||
@@ -106,0 +109,0 @@ |
@@ -156,3 +156,7 @@ import { existsSync, readFileSync, writeFileSync } from 'fs'; | ||
| if (status === 'intact' || status === 'missing') { | ||
| await writer.installEntryFile(engine, { force: true }); | ||
| await writer.installEntryFile(engine, { | ||
| force: true, | ||
| outputFolder: existing.state.output_folder, | ||
| forwardFolder: existing.state.forward_folder, | ||
| }); | ||
| } | ||
@@ -159,0 +163,0 @@ } |
@@ -9,2 +9,3 @@ import inquirer from 'inquirer'; | ||
| 'reversa', | ||
| 'reversa-autonomous', | ||
| 'reversa-scout', | ||
@@ -11,0 +12,0 @@ 'reversa-archaeologist', |
@@ -10,2 +10,3 @@ import { | ||
| import { readJsonSafe } from '../utils/json-safe.js'; | ||
| import { renderPolicyBlock } from './policy.js'; | ||
@@ -93,3 +94,3 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); | ||
| // force=true: sobrescreve silenciosamente (usado pelo update em arquivos intactos) | ||
| async installEntryFile(engine, { force = false } = {}) { | ||
| async installEntryFile(engine, { force = false, outputFolder, forwardFolder } = {}) { | ||
| if (!engine.entryFile || !engine.entryTemplate) return; | ||
@@ -102,3 +103,4 @@ | ||
| const content = readFileSync(templatePath, 'utf8'); | ||
| const content = readFileSync(templatePath, 'utf8') | ||
| .replace('{{REVERSA_POLICY}}', renderPolicyBlock({ outputFolder, forwardFolder })); | ||
@@ -105,0 +107,0 @@ if (!existsSync(destPath)) { |
+1
-1
| { | ||
| "name": "reversa", | ||
| "version": "1.2.43", | ||
| "version": "1.2.49", | ||
| "description": "Transform legacy systems into executable specifications for AI coding agents", | ||
@@ -5,0 +5,0 @@ "bin": { |
+131
-9
@@ -6,2 +6,6 @@ # Reversa | ||
| > 📄 **Paper:** [Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents](https://arxiv.org/abs/2605.18684) — Macedo & da Costa, May 2026. | ||
| [](https://arxiv.org/abs/2605.18684) | ||
| [](https://sandeco.github.io/reversa/)<br> | ||
@@ -94,2 +98,15 @@ [](https://sandeco.github.io/reversa/pt/)<br> | ||
| For other workflows, use the matching entry command: | ||
| | Goal | Command | | ||
| |------|---------| | ||
| | Analyze an existing legacy and produce specs | `/reversa` | | ||
| | Start a brand new project from a one-line idea | `/reversa-new` | | ||
| | Evolve the system one feature at a time, from spec to code | `/reversa-forward` | | ||
| | Rebuild the legacy on a modern stack | `/reversa-migrate` | | ||
| | Render the extracted knowledge as an HTML mini-site | `/reversa-docs` | | ||
| | Estimate effort and pricing on top of the specs | `/reversa-pricing-profile`, `/reversa-pricing-size`, `/reversa-pricing-estimate` | | ||
| Each orchestrator pauses between agents and asks for `CONTINUAR` before advancing, so you stay in control of every step. | ||
| --- | ||
@@ -99,3 +116,3 @@ | ||
| Reversa uses a 5-phase pipeline orchestrated by the **Reversa** agent: | ||
| The Discovery pipeline (`/reversa`) is the heart of the framework: a 5-phase sequence orchestrated by the **Reversa** agent. | ||
@@ -108,4 +125,16 @@ ``` | ||
| Independent agents (run at any phase): **Visor**, **Data Master**, **Design System**, **Tracer** | ||
| Independent agents (run at any phase): **Visor**, **Data Master**, **Design System**, **Soul Extractor**, **Reconstructor**. | ||
| Once the specs exist, you can move forward in three directions, depending on the goal: | ||
| ``` | ||
| Discovery (/reversa) | ||
| │ | ||
| ├── /reversa-forward Evolve the system from specs to code | ||
| ├── /reversa-migrate Rebuild the legacy on a modern stack | ||
| └── /reversa-docs Render specs as an HTML mini-site | ||
| ``` | ||
| For a **greenfield** project (no legacy to extract), start with `/reversa-new` instead. It walks from a one-line idea to SDD specs and then hands off to `/reversa-forward`. | ||
| --- | ||
@@ -115,4 +144,17 @@ | ||
| ### Required | ||
| Reversa organizes its agents in **seven specialized Teams**. The Discovery Team (Reversa Agents Core) is always installed; five Teams are pre-checked in the installer and Translators are opt-in. | ||
| | Team | Purpose | Entry command | | ||
| |------|---------|---------------| | ||
| | **Reversa Agents Core** (Discovery) | Analyze the existing legacy and produce specs | `/reversa` | | ||
| | **Code New Project Agents** | Start a new project (greenfield) from a one-line idea and produce specs | `/reversa-new` | | ||
| | **Code Forward Agents** | Evolve the system from specs to running code, one feature at a time | `/reversa-forward` | | ||
| | **Migration Agents** | Turn legacy specs into a rebuild plan for a modern stack | `/reversa-migrate` | | ||
| | **Pricing and Size Agents** | Estimate effort, size and pricing on top of the specs | `/reversa-pricing-*` | | ||
| | **Documentation Team** | Render the extracted knowledge as a self-contained HTML mini-site | `/reversa-docs` | | ||
| ### Discovery Team, required | ||
| These run the main `/reversa` pipeline. | ||
| | Agent | Role | | ||
@@ -127,3 +169,3 @@ |-------|------| | ||
| ### Optional (installed by default) | ||
| ### Discovery Team, optional (installed by default) | ||
@@ -133,8 +175,55 @@ | Agent | Role | | ||
| | **Reviewer** | Reviews specs, finds inconsistencies, and validates gaps with the user | | ||
| | **Tracer** | Dynamic analysis: resolves gaps via logs, tracing, and real data (read-only) | | ||
| | **Visor** | Documents the interface from screenshots — without needing the system to be running | | ||
| | **Visor** | Documents the interface from screenshots, without needing the system to be running | | ||
| | **Data Master** | Complete database analysis: DDL, migrations, ORM, ERD, triggers, procedures | | ||
| | **Design System** | Extracts design tokens: colors, typography, spacing, themes, and components | | ||
| | **Chronicler** | Documents code changes during development sessions | | ||
| | **Soul Extractor** | Produces a single executive Spec (`soul.md`) with purpose, core entities and founding decisions, useful right after Scout | | ||
| | **Agents Help** | Explains every Reversa agent with analogies, useful for newcomers | | ||
| | **Reconstructor** | Generates a bottom-up reconstruction plan from the specs and implements one task at a time, preserving tokens. Activation: `/reversa-reconstructor` | | ||
| ### Code New Project Agents (greenfield) | ||
| For projects that do not exist yet. Activate with `/reversa-new` and the orchestrator drives the pipeline `Ideator → Researcher → Drafter → Spec SDD`, with a `CONTINUAR` checkpoint between agents. Final handoff suggests `/reversa-forward` to take the specs to code. | ||
| | Agent | Role | | ||
| |-------|------| | ||
| | **Reversa New** | Orchestrator. Reads the initial brief, walks the pipeline, saves `newproject_progress` in `state.json` | | ||
| | **Ideator** | Structured brainstorm with 6 divergent questions (root problem, value, alternatives, audience, success metrics, dangerous assumptions). Produces `_reversa_sdd/ideation.md` | | ||
| | **Researcher** | Turns the raw audience into 1 to 3 structured personas with journeys. Produces `_reversa_sdd/personas.md` | | ||
| | **Drafter** | Synthesizes ideation and personas into a complete PRD (problem, metrics, scope, non-goals, constraints, risks). Produces `_reversa_sdd/prd.md` | | ||
| | **Spec SDD** | Decomposes the PRD into logical components and writes one SDD spec per component, with an automatic quality score. Vendored from the global `sdd-spec` skill. Produces `_reversa_sdd/sdd/*.md` | | ||
| ### Code Forward Agents (evolution) | ||
| The bridge from specs to running code. Pipeline: `requirements → clarify → quality → plan → to-do → audit → coding`. Use `/reversa-forward` as the entry point: it detects the **physical stage** of the active feature (by inspecting the artifacts on disk, not metadata) and suggests the next agent. | ||
| | Agent | Role | | ||
| |-------|------| | ||
| | **Reversa Forward** | Orchestrator. Detects the physical stage and suggests the next skill. Never executes code itself | | ||
| | **Requirements** | Turns a free-form idea into `requirements.md` anchored to the legacy, with `[DOUBT]` markers, gaps and glossary | | ||
| | **Clarify** | Up to 5 targeted questions to resolve `[DOUBT]` markers in place | | ||
| | **Quality** | Read-only auditor of writing clarity. Produces `requirements-audit.md` | | ||
| | **Plan** | Translates requirements into a technical proposal expressed as a **delta over the legacy**. Produces `roadmap.md`, `investigation.md`, `data-delta.md`, `onboarding.md`, `interfaces/` | | ||
| | **To-Do** | Decomposes the roadmap into atomic actions across five phases with stable IDs, dependencies and parallelism markers. Produces `actions.md` | | ||
| | **Audit** | Read-only cross-check between requirements, roadmap and actions. Produces `audit/cross-check.md` | | ||
| | **Coding** | Executes `actions.md`, flips checkboxes, writes `progress.jsonl`, `legacy-impact.md` and `regression-watch.md` | | ||
| | **Principles** | Manages durable project rules (`principles.md`) and emits impact reports when they change | | ||
| | **Resume** | Swaps the active feature with one from the `paused-features` queue | | ||
| ### Migration Team | ||
| Use after `/reversa` when the goal is to rebuild the legacy on a modern stack. Activate with `/reversa-migrate`. Pipeline: `Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector`, with a human review pause between agents. Every artifact lands in `_reversa_sdd/migration/`. | ||
| | Agent | Role | | ||
| |-------|------| | ||
| | **Paradigm Advisor** | Detects the legacy paradigm, infers the target paradigm, forces a conscious user decision | | ||
| | **Curator** | Decides rule by rule: MIGRATE, DISCARD or HUMAN DECISION | | ||
| | **Strategist** | Evaluates Strangler Fig, Big Bang, Parallel Run, Branch by Abstraction and recommends one | | ||
| | **Designer** | Drafts target architecture, domain model, data model and data migration plan | | ||
| | **Screen Translator** | Translates legacy screens into executable specs in 2 phases (mode decision + spec generation), emitting golden files for the Inspector when an oracle is available | | ||
| | **Inspector** | Defines how to prove the new system is behaviorally equivalent to the legacy, with Gherkin parity specs | | ||
| ### Pricing and Size Team | ||
| Three agents on top of the specs to estimate effort, size and price. Activate with `/reversa-pricing-profile`, `/reversa-pricing-size` and `/reversa-pricing-estimate`. | ||
| ### Translators (input adapters) | ||
@@ -150,3 +239,3 @@ | ||
| After discovery completes, this team turns the extracted knowledge into a self-contained HTML mini-site under `.reversa/documentation/`. Run `/reversa-docs` to orchestrate the full team, or activate any agent in isolation to regenerate only its pages. | ||
| After discovery completes, this team turns the extracted knowledge into a self-contained HTML mini-site under `_reversa_docs/`. Run `/reversa-docs` to orchestrate the full team, or activate any agent in isolation to regenerate only its pages. | ||
@@ -184,3 +273,2 @@ | Agent | Role | | ||
| ├── questions.md # Questions for human validation | ||
| ├── dynamic.md # Dynamic analysis findings (Tracer) | ||
| ├── sdd/ # Specs per component | ||
@@ -201,2 +289,36 @@ │ └── [component].md | ||
| In a greenfield run, `/reversa-new` adds the following on top of `_reversa_sdd/`: | ||
| ``` | ||
| _reversa_sdd/ | ||
| ├── newproject-brief.md # Initial brief (Reversa New) | ||
| ├── ideation.md # Structured brainstorm (Ideator) | ||
| ├── personas.md # Personas with journeys (Researcher) | ||
| ├── prd.md # Product Requirements Document (Drafter) | ||
| └── sdd/ | ||
| └── [component].md # SDD specs with quality score (Spec SDD) | ||
| ``` | ||
| Forward features land in a separate folder, `_reversa_forward/` by default: | ||
| ``` | ||
| _reversa_forward/ | ||
| └── <NNN>-<short-name>/ # One folder per feature | ||
| ├── requirements.md | ||
| ├── roadmap.md | ||
| ├── investigation.md | ||
| ├── data-delta.md | ||
| ├── onboarding.md | ||
| ├── interfaces/ | ||
| ├── actions.md | ||
| ├── progress.jsonl | ||
| ├── legacy-impact.md | ||
| ├── regression-watch.md | ||
| └── audit/ | ||
| ├── requirements-audit.md | ||
| └── cross-check.md | ||
| ``` | ||
| The Documentation Team writes only inside `_reversa_docs/` (HTML mini-site, fully offline). | ||
| ### Confidence scale | ||
@@ -203,0 +325,0 @@ |
@@ -9,3 +9,3 @@ #!/usr/bin/env python3 | ||
| python convert_chronicle.py --src .reversa/chronicle.md \ | ||
| --out .reversa/documentation/assets/data/timeline.json | ||
| --out _reversa_docs/assets/data/timeline.json | ||
| """ | ||
@@ -12,0 +12,0 @@ |
@@ -9,3 +9,3 @@ #!/usr/bin/env python3 | ||
| python convert_soul.py --src .reversa/soul.md \ | ||
| --out .reversa/documentation/assets/data/soul.json | ||
| --out _reversa_docs/assets/data/soul.json | ||
| """ | ||
@@ -12,0 +12,0 @@ |
@@ -10,4 +10,4 @@ #!/usr/bin/env python3 | ||
| Uso: | ||
| python extract_deps.py --modules .reversa/documentation/assets/data/modules.json \ | ||
| --out .reversa/documentation/assets/data/deps.json | ||
| python extract_deps.py --modules _reversa_docs/assets/data/modules.json \ | ||
| --out _reversa_docs/assets/data/deps.json | ||
| """ | ||
@@ -14,0 +14,0 @@ |
@@ -11,3 +11,3 @@ #!/usr/bin/env python3 | ||
| Uso: | ||
| python extract_modules.py --root . --out .reversa/documentation/assets/data/modules.json | ||
| python extract_modules.py --root . --out _reversa_docs/assets/data/modules.json | ||
| """ | ||
@@ -14,0 +14,0 @@ |
@@ -9,3 +9,3 @@ #!/usr/bin/env python3 | ||
| python list_specs.py --sdd-root _reversa_sdd \ | ||
| --out .reversa/documentation/assets/data/features-index.json | ||
| --out _reversa_docs/assets/data/features-index.json | ||
| """ | ||
@@ -12,0 +12,0 @@ |
@@ -7,4 +7,11 @@ # Reversa | ||
| Digite `reversa` para ativar o Reversa e iniciar ou retomar a análise do projeto. | ||
| Use o fluxo adequado no chat: | ||
| - `reversa` — descobrir e documentar um sistema existente | ||
| - `reversa-new` — criar PRD e specs para um projeto novo | ||
| - `reversa-forward` — implementar ou evoluir código a partir das specs | ||
| - `reversa-migrate` — planejar a migração de um sistema legado | ||
| - `reversa-docs` — gerar o mini-site visual da documentação | ||
| - `reversa-agents-help` — consultar o catálogo completo de agentes | ||
| ## Comportamento ao ativar | ||
@@ -19,3 +26,2 @@ | ||
| Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto legado. | ||
| O Reversa escreve **apenas** em `.reversa/` e `_reversa_sdd/`. | ||
| {{REVERSA_POLICY}} |
@@ -7,4 +7,11 @@ # Reversa | ||
| Digite `/reversa` para ativar o Reversa e iniciar ou retomar a análise do projeto. | ||
| Use o fluxo adequado no chat: | ||
| - `/reversa` — descobrir e documentar um sistema existente | ||
| - `/reversa-new` — criar PRD e specs para um projeto novo | ||
| - `/reversa-forward` — implementar ou evoluir código a partir das specs | ||
| - `/reversa-migrate` — planejar a migração de um sistema legado | ||
| - `/reversa-docs` — gerar o mini-site visual da documentação | ||
| - `/reversa-agents-help` — consultar o catálogo completo de agentes | ||
| ## Comportamento ao ativar | ||
@@ -20,3 +27,2 @@ | ||
| Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto legado. | ||
| O Reversa escreve **apenas** em `.reversa/` e `_reversa_sdd/`. | ||
| {{REVERSA_POLICY}} |
@@ -7,4 +7,11 @@ # Reversa | ||
| Para ativar o Reversa, escreva `reversa` sozinho em uma mensagem. | ||
| Use o fluxo adequado no chat: | ||
| - `reversa` — descobrir e documentar um sistema existente | ||
| - `reversa-new` — criar PRD e specs para um projeto novo | ||
| - `reversa-forward` — implementar ou evoluir código a partir das specs | ||
| - `reversa-migrate` — planejar a migração de um sistema legado | ||
| - `reversa-docs` — gerar o mini-site visual da documentação | ||
| - `reversa-agents-help` — consultar o catálogo completo de agentes | ||
| ## Comportamento ao ativar | ||
@@ -19,3 +26,2 @@ | ||
| Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto legado. | ||
| O Reversa escreve **apenas** em `.reversa/` e `_reversa_sdd/`. | ||
| {{REVERSA_POLICY}} |
@@ -7,4 +7,11 @@ # Reversa | ||
| Digite `/reversa` para ativar o Reversa e iniciar ou retomar a análise do projeto. | ||
| Use o fluxo adequado no chat: | ||
| - `/reversa` — descobrir e documentar um sistema existente | ||
| - `/reversa-new` — criar PRD e specs para um projeto novo | ||
| - `/reversa-forward` — implementar ou evoluir código a partir das specs | ||
| - `/reversa-migrate` — planejar a migração de um sistema legado | ||
| - `/reversa-docs` — gerar o mini-site visual da documentação | ||
| - `/reversa-agents-help` — consultar o catálogo completo de agentes | ||
| ## Comportamento ao ativar | ||
@@ -19,3 +26,2 @@ | ||
| Nunca apague, modifique ou sobrescreva arquivos pré-existentes do projeto legado. | ||
| O Reversa escreve **apenas** em `.reversa/` e `_reversa_sdd/`. | ||
| {{REVERSA_POLICY}} |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
1037406
2.14%- Number of package files
230
0.88%- Lines of code
4593
0.95%- Number of lines in readme file
399
44.04%No dependency changes