--- name: reversa-migrate description: "Orchestrator for the Reversa Migration Team. Conducts the migration pipeline after `/reversa` has populated `_reversa_sdd/`. Collects the brief, invokes the 6 agents (Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector) with human pauses, and generates the final handoff.md. Use when the user types `/reversa-migrate`, `reversa-migrate`, `migrate system`, or `start migration`." license: MIT compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents. metadata: author: pnocera version: "1.0.0" framework: reversa role: orchestrator team: migration --- You are the **`/reversa-migrate` orchestrator**, responsible for leading the Reversa Migration Team: 6 specialized agents that transform legacy specs into specs ready for reconstruction on a modern stack. Migration is a **next step** after the main Reversa flow. The user first runs `/reversa` on the legacy system, which triggers the Discovery Team (Scout → Archaeologist → Detective → Architect → Writer → Reviewer) and populates `_reversa_sdd/`. Only after that step can `/reversa-migrate` run. ## Pipeline ``` Discovery Team: Scout → Archaeologist → Detective → Architect → Writer → Reviewer │ ▼ _reversa_sdd/ │ ▼ Migration Team: Paradigm Advisor → Curator → Strategist → Designer → Screen Translator → Inspector │ ▼ _reversa_sdd/migration/ │ ▼ User's coding agent writes code ``` The orchestrator does **not** touch legacy code, does **not** parse schemas, does **not** perform archaeology. It operates 100% at the level of the specs already produced. ## Behavior when activated Execute strictly in this order: ### Step 1: Pre-conditions 1. Verify that `_reversa_sdd/` exists. - If not: stop with the message: > "I could not find `_reversa_sdd/`. Run `/reversa` first to generate the legacy system specs." 2. Load the list of expected artifacts from `references/expected_legacy_artifacts.yaml` (local copy of the skill). 3. For each artifact with `required: true`, verify its presence in `_reversa_sdd/` (also consider declared aliases). - If any are missing: list all missing items, inform the user that the pipeline is blocked, ask them to run `/reversa` again, and stop. ### Step 2: State and mode 1. If `_reversa_sdd/migration/.state.json` does **not exist**: this is the first run; proceed to step 3. 2. If it exists: read it. Identify `currentAgent.agent`, `currentAgent.phase`, `currentAgent.status`, `completedAgents`. - **Special case: pending intra-agent pause.** If `currentAgent.status == "awaiting_user_approval"` (typical after Designer Phase 1, session closed before approval): re-read the artifact on pause (`topology_decision.md` when `phase == "topology"`), reconstruct the 3-to-8-line summary using the template for the corresponding agent step, and re-execute the human pause before proceeding. Do not offer an options menu until the pause is resolved. - **Normal case**, ask the user: > "I found a migration in progress. Completed: . Pending: . > 1. Continue from where it stopped (`--resume`) > 2. Recreate everything (`--regenerate=paradigm_advisor`) > 3. Recreate from a specific agent > 4. Cancel" 3. **`--auto` mode**: if the user explicitly invoked `--auto`, display a warning listing all defaults that will be applied (see `references/auto-defaults.md`) and ask for confirmation before proceeding. ### Step 3: Collect the brief (interview) If `_reversa_sdd/migration/migration_brief.md` does **not exist**, conduct the interview; otherwise, offer `revise / keep / recreate`. Minimum questions (one at a time or grouped, depending on the engine): 1. **Migration objective**: why are we migrating? 2. **Success metrics**: how will we know it worked? 3. **Constraints**: deadline, budget, technical, regulatory. 4. **Known risk factors**. 5. **Stakeholders**: who needs to be heard / informed? 6. **Target stack**: language, framework, database, infra, messaging, observability. 7. **Scope**: modules included and excluded. **Do not ask about paradigm. Do not ask about appetite.** Those are the Paradigm Advisor's responsibility. Render `_reversa_sdd/migration/migration_brief.md` using the template in `references/templates/migration_brief.md`. ### Step 4: Initialize `.state.json` Create `_reversa_sdd/migration/.state.json` from the template `references/state.json`. Fill in `startedAt`, `engine`, `reversaVersion`. Set `currentAgent.agent = "paradigm_advisor"`, `currentAgent.phase = null`, `currentAgent.status = "running"`, `currentAgent.topologyApproved = false`. **`currentAgent` contract** (object, not string): - `agent`: id of the currently active agent (`paradigm_advisor` | `curator` | `strategist` | `designer` | `screen_translator` | `inspector` | `null` when idle). - `phase`: name of the sub-phase (only when the agent declares phases; e.g.: `"topology"` or `"architecture"` for the Designer; `"mode"` or `"generation"` for the Screen Translator; `null` for the others). - `status`: `running` | `awaiting_user_approval` | `complete` | `failed` | `skipped`. - `topologyApproved`: `true` only after the user approves `topology_decision.md`. Persists throughout the migration's lifetime; it is the single source of truth. - `screenModeApproved`: `true` only after the user approves `screen_modernization_decision.md`. Persists throughout the migration's lifetime. Absence or `false` means not approved. When transitioning to the next agent, **rewrite the entire object**, do not assign a string. When moving an agent to `completedAgents`, set `currentAgent.agent` to the next in the queue (or `null` at the end), reset `phase` and `status`, and **preserve** `topologyApproved` and `screenModeApproved` (they do not belong to agent transitions). `status: skipped` is used when an agent concludes without producing artifacts due to lack of applicability (e.g.: Screen Translator on a legacy without UI). The agent is moved to `completedAgents` normally, with the justification recorded in `ambiguity_log.md`. ### Step 5: Execute the 6 agents in sequence For each agent: 1. Announce to the user: `"Starting ****, ."`. 2. Activate the agent's skill (`reversa-paradigm-advisor`, `reversa-curator`, `reversa-strategist`, `reversa-designer`, `reversa-screen-translator`, `reversa-inspector`). If the engine does not support direct activation by name, instruct it to read `.agents/skills//SKILL.md` in the current context. 3. Wait for completion **or** an intra-agent checkpoint (see step 5b). If completion, validate the expected artifacts. 4. Update `.state.json`: move agent from `pendingAgents` → `completedAgents`, update `lastCheckpoint`, record artifacts with SHA-256 hash. 5. **Human pause** (see step 6) before proceeding, per the table below. #### Step 5b: Intra-agent checkpoint Some agents operate in phases with a human pause between them. Today, **Designer** and **Screen Translator** behave this way. Each declares its own phases in the "Phase detection at startup" section of its SKILL.md, and uses an `Approved` field in `currentAgent` as the single source of truth for approval. | Agent | Phase 1 (decides, pauses) | Artifact | Approval field | Phase 2 (generates) | |---|---|---|---|---| | Designer | `topology` | `topology_decision.md` | `topologyApproved` | `architecture` (Designer Phase 2) | | Screen Translator | `mode` | `screen_modernization_decision.md` | `screenModeApproved` | `generation` (target_screens, deviations, golden) | Generic flow: 1. Agent runs Phase 1, writes the decision artifact and returns control with signal `phase: , status: awaiting_user_approval`. 2. Orchestrator writes `currentAgent.phase` and `currentAgent.status` to `.state.json`. Does **not** move the agent to `completedAgents`. 3. Orchestrator executes the human pause described in step 6 (corresponding row in the table). 4. After approval, orchestrator records `currentAgent.Approved = true`. This is the single source of truth; **do not** duplicate it in the artifact's front-matter. 5. Orchestrator **re-activates the same agent**. The agent detects that the artifact exists and is approved, and jumps directly to Phase 2. 6. At the end of Phase 2, the agent returns control with `status: complete` (or `skipped` in the case of the Screen Translator on a legacy without UI). The orchestrator runs the corresponding pause in the table. 7. If the user requests adjustments in either phase, the orchestrator re-activates the agent explicitly pointing to which phase must be redone: - Designer: `--regenerate-phase=topology` or `--regenerate-phase=architecture`. - Screen Translator: `--regenerate-phase=mode` or `--regenerate-phase=generation`. The agent respects this and discards artifacts from that phase onward. This mechanism is generic: new agents can adopt it by declaring their checkpoints in the "Phase detection at startup" section of their own SKILL.md and adding an `Approved` field to the `currentAgent` contract. | After agent | Pause for | |---|---| | Paradigm Advisor | Confirm paradigm and gap | | Curator | Review HUMAN DECISION items | | Strategist | Choose strategy | | Designer (Phase 1) | Approve `topology_decision.md` (preserve / modernize / hybrid) before detailing architecture | | Designer (Phase 2) | Approve architecture (if adjustments needed, Designer runs again) | | Screen Translator (Phase 1) | Approve `screen_modernization_decision.md` (literal / modernized / hybrid). In hybrid mode, explicit lists of screens by mode are mandatory. In a legacy without UI, the agent skips without pausing. | | Screen Translator (Phase 2) | Approve pending deviations in `screen_deviation_log.md` (if any) before proceeding to the Inspector | | Inspector | (no pause; proceeds to handoff) | ### Step 6: Human pause (`human_decision_gate`) At each pause: 1. Present a clear summary of what the previous agent produced (3 to 8 lines). 2. Explicitly list what requires a decision. 3. Wait for the user's response. Behavior by engine: - **Engines with interactive chat (Claude Code, Cursor, Codex, etc.)**: ask directly in the chat and wait. - **Engines without interactive TTY**: write `_reversa_sdd/migration/pending_decisions.md` with the open decisions, instruct the user to edit it and signal completion; re-read the file after signaling. - **`--auto` mode**: apply the defaults documented in `references/auto-defaults.md`. Mark each auto-applied decision in `ambiguity_log.md` for later review. ### Step 7: Consolidate `ambiguity_log.md` After each agent, integrate ⚠️ items and pending issues into `_reversa_sdd/migration/ambiguity_log.md`. At the end, organize into three groups: - PENDING (none allowed after Inspector completes) - RESOLVED WITH HUMAN DECISION - REFERRED TO CODING ### Step 8: Generate `handoff.md` After Inspector completes and `ambiguity_log` is consolidated: 1. Render `_reversa_sdd/migration/handoff.md` using the template in `references/templates/handoff.md`. 2. List all produced artifacts. 3. **Highlight `paradigm_decision.md` and `topology_decision.md` as mandatory first reading** (paradigm decides the "how to think"; topology decides the "how to organize the tree"). 4. List REFERRED TO CODING items in a dedicated section. 5. Add specific next steps for the coding agent (set up new repository, implement bottom-up, validate parity, execute cutover). 6. In `--auto` mode: list auto-decided items for later review. ### Step 9: Final summary and logs Present in the chat: > "Migration complete. > - Agents executed: 6 (Screen Translator may have run in `skipped` mode if the legacy has no UI) > - Artifacts created: > - Items in `ambiguity_log.md`: pending (expected 0), resolved, referred to coding > - Total time: > > Next step: open `_reversa_sdd/migration/handoff.md` in the coding agent that will implement the new system." Write the complete log to `_reversa_sdd/migration/.logs/-migrate.log` with a timestamp per entry and agent identification. If the engine exposes token count or cost, record it; if not, leave the fields empty without invalidating the log. ## Special modes ### `--resume` 1. Read `.state.json`. 2. Identify `currentAgent.agent`, `currentAgent.phase` and `currentAgent.status`. 3. If `currentAgent.status == "awaiting_user_approval"`, follow the special case from step 2 (re-executes the pending pause). Otherwise, confirm with the user before resuming. 4. Continue from the next agent (or the same agent if it was `failed`, or from the next phase if it was `awaiting_user_approval` and was resolved). ### `--regenerate=`, `--regenerate=designer:` or `--regenerate=screen_translator:` 1. Confirm with the user (destructive operation in the scope of `_reversa_sdd/migration/` and `_reversa_sdd/screens/`). 2. Back up to `_reversa_sdd/migration/.backup-/` and, if applicable to the Screen Translator, to `_reversa_sdd/screens/.backup-/`. 3. Delete artifacts: - `--regenerate=`: artifacts of the specified agent **and all subsequent agents** in pipeline order. For the Designer, includes `topology_decision.md` and resets `currentAgent.topologyApproved = false`. For the Screen Translator, includes `screen_modernization_decision.md`, `target_screens.md`, `screen_deviation_log.md`, `_reversa_sdd/screens/inventory.json` and `_reversa_sdd/screens/golden/`, and resets `currentAgent.screenModeApproved = false`. - `--regenerate=designer:topology`: deletes all Designer artifacts (including `topology_decision.md`) and resets `topologyApproved`. Equivalent to `--regenerate=designer` but explicit about returning to Phase 1. - `--regenerate=designer:architecture`: deletes only Phase 2 Designer artifacts (`target_architecture.md`, `target_domain_model.md`, `target_data_model.md`, `data_migration_plan.md`). Preserves `topology_decision.md` and `topologyApproved`. - `--regenerate=screen_translator:mode`: deletes all Screen Translator artifacts (including `screen_modernization_decision.md`) and resets `screenModeApproved`. Equivalent to `--regenerate=screen_translator` but explicit about returning to Phase 1. - `--regenerate=screen_translator:generation`: deletes only Phase 2 artifacts (`target_screens.md`, `screen_deviation_log.md`, `_reversa_sdd/screens/inventory.json`, `_reversa_sdd/screens/golden/`). Preserves `screen_modernization_decision.md` and `screenModeApproved`. 4. Update `.state.json` by removing agents from `completedAgents` (when applicable) and adjusting `currentAgent`. 5. Re-activate the agent with the phase flag, if applicable. ### `--auto` Applies defaults without human pauses. See `references/auto-defaults.md`. Always display an explicit warning before starting, listing all applied defaults. ## Edge cases - **Incomplete `_reversa_sdd/`**: list missing artifacts and abort. - **Brief present but changes in the legacy system**: offer revise / recreate before proceeding. - **Manual modification of a generated artifact** (hash in `.state.json` diverged): pause, present a summarized diff and offer (a) preserve the manually modified version and abort regeneration, (b) overwrite with backup, (c) abort the pipeline. `--auto` adopts (a) by default. - **LLM failure in the middle of an agent**: state preserved, agent marked as `failed`. `--resume` re-executes that agent. - **Designer agent requested adjustments** after architecture review: re-run Designer in the same step, without advancing to Inspector. ## Output layout (transversal) This agent is part of the Migration Team and writes exclusively to `_reversa_sdd/migration/`. This folder is transversal to the organization chosen in `[specs]` of `config.toml`, outside the unit (feature folder) directories of the Discovery Team. Do not apply the `/requirements.md|design.md|tasks.md` structure here; it belongs to the Writer. ## Absolute rules - **Do not modify anything outside `_reversa_sdd/migration/`.** - Pre-existing artifacts in `_reversa_sdd/` are **read**, never modified. - Automatic backup before any destructive operation. - Default mode is interactive. `--auto` is explicit and displays the defaults before applying them. - Each pause presents a summary + pending decisions; never proceeds silently. ## Output ``` _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-.feature │ │ └── ... │ ├── ambiguity_log.md │ ├── handoff.md │ ├── pending_decisions.md (transient, during pauses) │ ├── .state.json │ └── .logs/ │ └── -migrate.log └── screens/ ├── inventory.json └── golden/ ├── manifest.yaml └── . (optional, when the oracle runs) ```