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

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: . Pendente: .

      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.

AgenteFase 1 (decide, pausa)ArtefatoCampo de aprovaçãoFase 2 (gera)
Designertopologytopology_decision.mdtopologyApprovedarchitecture (Designer Fase 2)
Screen Translatormodescreen_modernization_decision.mdscreenModeApprovedgeneration (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 agentePausa para
Paradigm AdvisorConfirmar paradigma e gap
CuratorRevisar itens DECISÃO HUMANA
StrategistEscolher 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:
  • Itens em ambiguity_log.md: pendentes (esperado 0), resolvidos, referidos à codificação
  • Tempo total:

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