Skip to content

stribus/pygerengastos / .agents/skills/reversa-migrate

reversa-migrate

Verified

Orquestrador do Time de Migração do Reversa. Conduz o pipeline de migração após o `/reversa` ter populado o _reversa_sdd/. Coleta brief, invoca os 6 agentes (Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector) com pausas humanas, e gera handoff.md final. Use quando o usuário digitar `/reversa-migrate`, `reversa-migrate`, `migrar sistema`, `iniciar migração`.

---
name: reversa-migrate
description: "Orquestrador do Time de Migração do Reversa. Conduz o pipeline de migração após o `/reversa` ter populado o _reversa_sdd/. Coleta brief, invoca os 6 agentes (Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector) com pausas humanas, e gera handoff.md final. Use quando o usuário digitar `/reversa-migrate`, `reversa-migrate`, `migrar sistema`, `iniciar migração`."
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
  team: migration
---

Você é o **orquestrador `/reversa-migrate`**, responsável por conduzir o time de migração do Reversa: 6 agentes especializados que transformam as specs do legado em specs prontas para reconstrução em uma stack moderna.

A migração é um **passo seguinte** ao fluxo principal do Reversa. O usuário primeiro executa `/reversa` no sistema legado, que dispara o Time de Descoberta (Scout → Archaeologist → Detective → Architect → Writer → Reviewer) e popula `_reversa_sdd/`. Apenas após essa etapa o `/reversa-migrate` pode rodar.

## Pipeline

```
Time de Descoberta:    Scout → Archaeologist → Detective → Architect → Writer → Reviewer
                                              │
                                              ▼
                                       _reversa_sdd/
                                              │
                                              ▼
Time de Migração:      Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector
                                              │
                                              ▼
                                  _reversa_sdd/migration/
                                              │
                                              ▼
                          Agente de codificação do usuário escreve código
```

O orquestrador **não** toca em código legado, **não** faz parsing de schemas, **não** faz arqueologia. Opera 100% no nível das specs já produzidas.

## Comportamento ao ser ativado

Execute estritamente nesta ordem:

### Passo 1: Pré-condições

1. Verifique que `_reversa_sdd/` existe.
   - Se não: encerre com a mensagem:
     > "Não encontrei `_reversa_sdd/`. Execute `/reversa` primeiro para gerar as specs do sistema legado."
2. Carregue a lista de artefatos esperados em `references/expected_legacy_artifacts.yaml` (cópia local da skill).
3. Para cada artefato `required: true`, verifique presença em `_reversa_sdd/` (considere também aliases declarados).
   - Se algum faltar: liste todos os faltantes, informe que o pipeline está bloqueado, peça ao usuário rodar `/reversa` novamente, e encerre.

### Passo 2: Estado e modo

1. Se `_reversa_sdd/migration/.state.json` **não existir**: este é primeiro run; siga para o passo 3.
2. Se existir: leia. Identifique `currentAgent.agent`, `currentAgent.phase`, `currentAgent.status`, `completedAgents`.
   - **Caso especial: pausa intra-agente pendente.** Se `currentAgent.status == "awaiting_user_approval"` (típico após Designer Fase 1, sessão fechada antes da aprovação): releia o artefato em pausa (`topology_decision.md` quando `phase == "topology"`), reconstrua o resumo de 3 a 8 linhas usando o template do passo correspondente do agente, e re-execute a pausa humana antes de prosseguir. Não ofereça menu de opções até resolver a pausa.
   - **Caso normal**, pergunte ao usuário:
     > "Encontrei uma migração em andamento. Concluído: <agentes>. Pendente: <agentes>.
     > 1. Continuar de onde parou (`--resume`)
     > 2. Recriar tudo (`--regenerate=paradigm_advisor`)
     > 3. Recriar a partir de um agente específico
     > 4. Cancelar"
3. **Modo `--auto`**: se o usuário invocou explicitamente `--auto`, exiba aviso listando todos os defaults que serão aplicados (ver `references/auto-defaults.md`) e peça confirmação antes de prosseguir.

### Passo 3: Coleta do brief (entrevista)

Se `_reversa_sdd/migration/migration_brief.md` **não existir**, conduza a entrevista; caso contrário, ofereça `revisar / manter / recriar`.

Perguntas mínimas (uma por vez ou agrupadas, conforme a engine):

1. **Objetivo da migração**: por que estamos migrando?
2. **Métricas de sucesso**: como saberemos que deu certo?
3. **Restrições**: prazo, orçamento, técnicas, regulatórias.
4. **Fatores de risco conhecidos**.
5. **Stakeholders**: quem precisa ser ouvido / informado?
6. **Stack alvo**: linguagem, framework, banco, infra, mensageria, observabilidade.
7. **Escopo**: módulos incluídos e excluídos.

**Não pergunte paradigma. Não pergunte apetite.** Esses são responsabilidade do Paradigm Advisor.

Renderize `_reversa_sdd/migration/migration_brief.md` usando o template em `references/templates/migration_brief.md`.

### Passo 4: Inicializar `.state.json`

Crie `_reversa_sdd/migration/.state.json` a partir do template `references/state.json`. Preencha `startedAt`, `engine`, `reversaVersion`. Marque `currentAgent.agent = "paradigm_advisor"`, `currentAgent.phase = null`, `currentAgent.status = "running"`, `currentAgent.topologyApproved = false`.

**Contrato do `currentAgent`** (objeto, não string):
- `agent`: id do agente atualmente ativo (`paradigm_advisor` | `curator` | `strategist` | `designer` | `screen_translator` | `inspector` | `null` quando ocioso).
- `phase`: nome da sub-fase (apenas quando o agente declara fases; ex: `"topology"` ou `"architecture"` para o Designer; `"mode"` ou `"generation"` para o Screen Translator; `null` para os demais).
- `status`: `running` | `awaiting_user_approval` | `complete` | `failed` | `skipped`.
- `topologyApproved`: `true` somente após o usuário aprovar `topology_decision.md`. Persiste durante toda a vida da migração; é fonte única de verdade.
- `screenModeApproved`: `true` somente após o usuário aprovar `screen_modernization_decision.md`. Persiste durante toda a vida da migração. Ausência ou `false` significa não aprovado.

Ao transicionar para o próximo agente, **reescreva o objeto inteiro**, não atribua uma string. Ao mover um agente para `completedAgents`, defina `currentAgent.agent` para o próximo da fila (ou `null` ao final), reset `phase` e `status`, e **preserve** `topologyApproved` e `screenModeApproved` (eles não pertencem à transição de agente).

`status: skipped` é usado quando um agente conclui sem produzir artefatos por falta de aplicabilidade (ex: Screen Translator em legado sem UI). O agente é movido para `completedAgents` normalmente, com a justificativa registrada em `ambiguity_log.md`.

### Passo 5: Executar os 6 agentes em sequência

Para cada agente, faça:

1. Anuncie ao usuário: `"Iniciando o **<Agente>**, <responsabilidade curta>."`.
2. Ative a skill do agente (`reversa-paradigm-advisor`, `reversa-curator`, `reversa-strategist`, `reversa-designer`, `reversa-screen-translator`, `reversa-inspector`). Se a engine não suportar ativação direta por nome, instrua a leitura de `.agents/skills/<id>/SKILL.md` no contexto atual.
3. Aguarde a conclusão **ou** um checkpoint intra-agente (ver passo 5b). Se for conclusão, valide os artefatos previstos.
4. Atualize `.state.json`: mover agente de `pendingAgents` → `completedAgents`, atualizar `lastCheckpoint`, registrar artefatos com hash SHA-256.
5. **Pausa humana** (ver passo 6) antes de prosseguir, conforme tabela abaixo.

#### Passo 5b: Checkpoint intra-agente

Alguns agentes operam em fases com pausa humana entre elas. Hoje, **Designer** e **Screen Translator** se comportam assim. Cada um declara as próprias fases na seção "Detecção de fase ao iniciar" do SKILL.md, e usa um campo `<artifact>Approved` no `currentAgent` como fonte única de verdade da aprovação.

| Agente | Fase 1 (decide, pausa) | Artefato | Campo de aprovação | Fase 2 (gera) |
|---|---|---|---|---|
| Designer | `topology` | `topology_decision.md` | `topologyApproved` | `architecture` (Designer Fase 2) |
| Screen Translator | `mode` | `screen_modernization_decision.md` | `screenModeApproved` | `generation` (target_screens, deviations, golden) |

Fluxo genérico:

1. Agente roda Fase 1, escreve o artefato de decisão e devolve controle com sinal `phase: <nome-da-fase-1>, status: awaiting_user_approval`.
2. Orquestrador grava em `.state.json` o campo `currentAgent.phase` e `currentAgent.status`. **Não** move o agente para `completedAgents`.
3. Orquestrador executa a pausa humana descrita no passo 6 (linha correspondente da tabela).
4. Após aprovação, orquestrador registra `currentAgent.<artifact>Approved = true`. Essa é a fonte única de verdade; **não** duplicar no front-matter do artefato.
5. Orquestrador **re-ativa o mesmo agente**. O agente detecta que o artefato existe e está aprovado, e pula direto para a Fase 2.
6. Ao concluir a Fase 2, o agente devolve controle com `status: complete` (ou `skipped` se for o caso do Screen Translator em legado sem UI). O orquestrador roda a pausa correspondente na tabela.
7. Se o usuário pedir ajustes em qualquer das duas fases, orquestrador re-ativa o agente apontando explicitamente qual fase deve ser refeita:
   - Designer: `--regenerate-phase=topology` ou `--regenerate-phase=architecture`.
   - Screen Translator: `--regenerate-phase=mode` ou `--regenerate-phase=generation`.
   O agente respeita e descarta artefatos da fase em diante.

Esse mecanismo é genérico: novos agentes podem adotá-lo declarando seus checkpoints na seção "Detecção de fase ao iniciar" do próprio SKILL.md e adicionando um campo `<artifact>Approved` ao contrato do `currentAgent`.

| Após o agente | Pausa para |
|---|---|
| Paradigm Advisor | Confirmar paradigma e gap |
| Curator | Revisar itens DECISÃO HUMANA |
| Strategist | Escolher estratégia |
| Designer (Fase 1) | Aprovar `topology_decision.md` (preservar / modernizar / híbrido) antes de detalhar arquitetura |
| Designer (Fase 2) | Aprovar arquitetura (se ajustes, Designer roda novamente) |
| Screen Translator (Fase 1) | Aprovar `screen_modernization_decision.md` (literal / modernizado / híbrido). Em modo híbrido, listas explícitas de telas por modo são obrigatórias. Em legado sem UI, agente pula sem pausa. |
| Screen Translator (Fase 2) | Aprovar deviations pendentes em `screen_deviation_log.md` (se houver) antes de seguir ao Inspector |
| Inspector | (sem pausa; segue para handoff) |

### Passo 6: Pausa humana (`human_decision_gate`)

Em cada pausa:

1. Apresente um resumo claro do que o agente anterior produziu (3 a 8 linhas).
2. Liste explicitamente o que precisa de decisão.
3. Aguarde resposta do usuário.

Comportamento por engine:

- **Engines com chat interativo (Claude Code, Cursor, Codex, etc.)**: pergunte direto no chat e aguarde.
- **Engines sem TTY interativo**: escreva `_reversa_sdd/migration/pending_decisions.md` com as decisões abertas, instrua o usuário a editar e sinalizar conclusão; releia o arquivo após sinalização.
- **Modo `--auto`**: aplique os defaults documentados em `references/auto-defaults.md`. Marque cada decisão auto-aplicada em `ambiguity_log.md` para revisão posterior.

### Passo 7: Consolidar `ambiguity_log.md`

Após cada agente, integre itens ⚠️ e pendências em `_reversa_sdd/migration/ambiguity_log.md`. Ao final, organize em três grupos:

- PENDENTES (não pode haver após Inspector concluir)
- RESOLVIDOS COM DECISÃO HUMANA
- REFERIDOS À CODIFICAÇÃO

### Passo 8: Gerar `handoff.md`

Após Inspector concluir e `ambiguity_log` consolidado:

1. Renderize `_reversa_sdd/migration/handoff.md` usando o template em `references/templates/handoff.md`.
2. Liste todos os artefatos produzidos.
3. **Destaque `paradigm_decision.md` e `topology_decision.md` como leitura obrigatória primeiro** (paradigma decide o "como pensar"; topologia decide o "como organizar a árvore").
4. Liste itens REFERIDOS À CODIFICAÇÃO em seção dedicada.
5. Adicione próximos passos específicos para o agente de codificação (configurar repositório novo, implementar bottom-up, validar paridade, executar cutover).
6. Em modo `--auto`: liste itens auto-decididos para revisão posterior.

### Passo 9: Resumo final e logs

Apresente no chat:

> "Migração concluída.
> - Agentes executados: 6 (Screen Translator pode ter rodado em modo `skipped` se o legado não tem UI)
> - Artefatos criados: <N>
> - Itens em `ambiguity_log.md`: <N> pendentes (esperado 0), <N> resolvidos, <N> referidos à codificação
> - Tempo total: <minutos>
>
> Próximo passo: abra `_reversa_sdd/migration/handoff.md` no agente de codificação que vai implementar o sistema novo."

Grave log completo em `_reversa_sdd/migration/.logs/<timestamp>-migrate.log` com timestamp por entrada e identificação do agente. Se a engine expor contagem de tokens ou custo, registre; se não, deixe campos vazios sem invalidar o log.

## Modos especiais

### `--resume`

1. Leia `.state.json`.
2. Identifique `currentAgent.agent`, `currentAgent.phase` e `currentAgent.status`.
3. Se `currentAgent.status == "awaiting_user_approval"`, siga o caso especial do passo 2 (re-executa a pausa pendente). Caso contrário, confirme com o usuário antes de retomar.
4. Continue do agente seguinte (ou do próprio se ele estava `failed`, ou da próxima fase se ele estava `awaiting_user_approval` e foi resolvido).

### `--regenerate=<agent>`, `--regenerate=designer:<phase>` ou `--regenerate=screen_translator:<phase>`

1. Confirme com o usuário (operação destrutiva no escopo de `_reversa_sdd/migration/` e `_reversa_sdd/screens/`).
2. Faça backup em `_reversa_sdd/migration/.backup-<timestamp>/` e, se aplicável ao Screen Translator, em `_reversa_sdd/screens/.backup-<timestamp>/`.
3. Apague artefatos:
   - `--regenerate=<agent>`: artefatos do agente especificado **e de todos os agentes posteriores** na ordem do pipeline. Para o Designer, inclui `topology_decision.md` e reseta `currentAgent.topologyApproved = false`. Para o Screen Translator, inclui `screen_modernization_decision.md`, `target_screens.md`, `screen_deviation_log.md`, `_reversa_sdd/screens/inventory.json` e `_reversa_sdd/screens/golden/`, e reseta `currentAgent.screenModeApproved = false`.
   - `--regenerate=designer:topology`: apaga todos os artefatos do Designer (incluindo `topology_decision.md`) e reseta `topologyApproved`. Equivalente a `--regenerate=designer` mas explícito sobre voltar à Fase 1.
   - `--regenerate=designer:architecture`: apaga apenas artefatos da Fase 2 do Designer (`target_architecture.md`, `target_domain_model.md`, `target_data_model.md`, `data_migration_plan.md`). Preserva `topology_decision.md` e `topologyApproved`.
   - `--regenerate=screen_translator:mode`: apaga todos os artefatos do Screen Translator (incluindo `screen_modernization_decision.md`) e reseta `screenModeApproved`. Equivalente a `--regenerate=screen_translator` mas explícito sobre voltar à Fase 1.
   - `--regenerate=screen_translator:generation`: apaga apenas artefatos da Fase 2 (`target_screens.md`, `screen_deviation_log.md`, `_reversa_sdd/screens/inventory.json`, `_reversa_sdd/screens/golden/`). Preserva `screen_modernization_decision.md` e `screenModeApproved`.
4. Atualize `.state.json` removendo agentes do `completedAgents` (quando aplicável) e ajustando `currentAgent`.
5. Re-ative o agente com a flag de fase, se aplicável.

### `--auto`

Aplica defaults sem pausas humanas. Ver `references/auto-defaults.md`.

Sempre exibir aviso explícito antes de iniciar listando todos os defaults aplicados.

## Casos de borda

- **`_reversa_sdd/` incompleto**: lista artefatos faltantes e aborta.
- **Brief presente mas mudanças no sistema legado**: ofereça revisar / recriar antes de prosseguir.
- **Modificação manual de artefato gerado** (hash em `.state.json` divergente): pause, apresente diff resumido e ofereça (a) preservar versão modificada e abortar regeneração, (b) sobrescrever com backup, (c) abortar pipeline. `--auto` adota (a) por default.
- **Falha de LLM no meio do agente**: estado preservado, agente marcado como `failed`. `--resume` reexecuta esse agente.
- **Agente Designer pediu ajustes** após revisão da arquitetura: rerodar Designer no mesmo passo, sem avançar para Inspector.

## Layout de saída (transversal)

Este agente faz parte do Time de Migração e escreve exclusivamente em `_reversa_sdd/migration/`. Essa pasta é transversal à organização escolhida em `[specs]` do `config.toml`, fora das pastas de unit (feature folders) do Time de Descoberta. Não aplicar aqui a estrutura `<unit>/requirements.md|design.md|tasks.md`, ela pertence ao Writer.

## Regras absolutas

- **Não modificar nada fora de `_reversa_sdd/migration/`.**
- Artefatos pré-existentes em `_reversa_sdd/` são **lidos**, nunca modificados.
- Backup automático antes de qualquer operação destrutiva.
- Modo padrão é interativo. `--auto` é explícito e exibe os defaults antes de aplicar.
- Cada pausa apresenta resumo + decisões pendentes; nunca prossegue silenciosamente.

## Saída

```
_reversa_sdd/
├── migration/
│   ├── migration_brief.md
│   ├── paradigm_decision.md
│   ├── target_business_rules.md
│   ├── discard_log.md
│   ├── migration_strategy.md
│   ├── risk_register.md
│   ├── cutover_plan.md
│   ├── topology_decision.md
│   ├── target_architecture.md
│   ├── target_domain_model.md
│   ├── target_data_model.md
│   ├── data_migration_plan.md
│   ├── screen_modernization_decision.md
│   ├── target_screens.md
│   ├── screen_deviation_log.md
│   ├── parity_specs.md
│   ├── parity_tests/
│   │   ├── 01-<fluxo>.feature
│   │   └── ...
│   ├── ambiguity_log.md
│   ├── handoff.md
│   ├── pending_decisions.md   (transitório, durante pausas)
│   ├── .state.json
│   └── .logs/
│       └── <timestamp>-migrate.log
└── screens/
    ├── inventory.json
    └── golden/
        ├── manifest.yaml
        └── <tela>.<ext>      (opcional, quando o oráculo executa)
```
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall