skillpanel/maister/migration

Migration Orchestrator

Systematic migration workflow from current state analysis to verified migration with rollback capabilities.

Initialization

BEFORE executing any phase, you MUST complete these steps:

Step 0: Session-reminder conflict resolution (decide ONCE)

Before doing anything else, settle this policy now and do not re-litigate it at any gate:

`→ MANDATORY GATE` markers fire regardless of session-reminders, permission mode, or prior approval patterns. Auto / acceptEdits / bypassPermissions modes, reminders saying "work without stopping" / "continue without asking" / "minimize clarifying questions," and compaction summaries showing the user approving every prior gate do NOT exempt you from invoking AskUserQuestion at a gate. They apply only to your discretionary clarifications.

If you find yourself reasoning "the user has been approving everything, so I can skip this gate" or "auto-mode is on, so I should minimize questions" — that reasoning IS the failure mode. STOP and fire the gate.

Full framework rule: ../orchestrator-framework/references/orchestrator-patterns.md § 2 and § 2.1.

Step 1: Load Framework Patterns

Read the framework reference file NOW using the Read tool:

1. ../orchestrator-framework/references/orchestrator-patterns.md - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution

Step 2: Initialize Workflow

1. Capture the clock: run date -u +"%Y-%m-%dT%H:%M:%SZ" via Bash NOW — you do NOT know the time from context. Every timestamp written this turn (created, updated, generated, phases[].started) uses this value. Date-only or T00:00:00Z values are the documented failure mode (orchestrator-patterns.md § 4 Timestamp Rule). Re-run date in later turns before writing timestamps.
2. Validate the flags: --type, when passed, must be one of code, data, architecture, general. On any other value, print those four and STOP — do not create the task directory, do not write state. A technology name belongs in the description, not the flag; Phase 2 classifies when the flag is absent. A valid value is recorded as migration_context.migration_type. --user-docs, when passed, is recorded as orchestrator.options.docs_enabled: true.
3. Create Task Items: Use TaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy
4. Create Task Directory: .maister/tasks/migrations/YYYY-MM-DD-task-name/
5. Initialize State: Create orchestrator-state.yml with migration context
6. Set up Operator Dashboard (orchestrator-patterns.md § 8) — first read .maister/config.yml and set orchestrator.options.html_output (default true if the file/key is absent). When `html_output` is false, SKIP this entire step — no dashboard.html, no dashboard-data.js, no browser auto-open — and proceed. Otherwise: copy ../orchestrator-framework/assets/dashboard.html to the task root as dashboard.html, write the initial dashboard-data.js (all phases pending, task.type: "migration"), then auto-open it in the user's browser (open / xdg-open / start per platform, passing the plain absolute filesystem path — NEVER a hand-built file:// URL; on failure just print the path — never block). On resume: re-copy dashboard.html only if missing; regenerate dashboard-data.js from state; then auto-open it in the browser again (same opener as a new task — the OS focuses an already-open tab rather than duplicating).
7. Discover project documentation: Read .maister/docs/INDEX.md (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as project_context.project_doc_paths in state.

Output:

🚀 Migration Orchestrator Started
 
Task: [migration description]
Directory: [task-path]
Dashboard: open [task-path]/dashboard.html in a browser to monitor progress
 
Starting Phase 1: Analyze current state...

Operator Visibility (applies to every phase)

Config gate: these rules assume options.html_output is true (read from .maister/config.yml at init, default true). When false: skip the Dashboard-upkeep rule entirely (no dashboard files, no browser open, no rewrites) and the HTML-companions rule (do NOT pass html_style_guide_path; subagents write md only). The Artifact Summary Contract (§ 7 TL;DR blocks) and phase_summaries in state stay active either way.

Cross-cutting rules from orchestrator-patterns.md (same as the development orchestrator):

1. Artifact Summary Contract (§ 7): every artifact-writing subagent prompt MUST include the contract instruction (artifacts open with TL;DR / Key Decisions / Open Questions / Risks (the writer heading is ## Open Questions / Risks)). At context extraction, lift decisions, risks, and artifacts into phase_summaries.[phase] — verbatim, never re-summarized.
2. Dashboard upkeep (§ 8): rewrite dashboard-data.js at every phase START (mark in_progress before delegating), BEFORE firing every exit gate (register the finished phase's artifacts/summary/decisions/risks — the operator reviews them on the dashboard while answering; status stays in_progress until the gate passes), after every phase completion (including skipped phases, with reason), every gate decision, every verification cycle, and at finalization. Every rewrite starts with date -u (one call per turn). It is a terse projection of state — never duplicate artifact content into it.
3. HTML companions (§ 9): pass html_style_guide_path (absolute path to ../orchestrator-framework/references/html-report-style.md) to specification-creator, implementation-planner, and implementation-verifier. Register returned html_path values in phase_summaries.[phase].artifacts[].html so the dashboard hero cards link HTML first.
4. icon_hint values per phase: 1 analysis, 2 analysis, 3 spec, 4 plan, 5 code, 6 verify, 7 verify, 8 docs.
5. State writes (§ 4 Write Rule): update orchestrator-state.yml key by key in place, validate it with a re-read after every write, and stop with AskUserQuestion on a malformed file — never continue on a state file the operator tooling cannot read.

When to Use

Use for:

• Migrating from one framework/library to another (e.g., Vue 2 → Vue 3, Express → Fastify)
• Changing database platforms (e.g., MySQL → PostgreSQL, MongoDB → DynamoDB)
• Refactoring architecture patterns (e.g., REST → GraphQL, Monolith → Microservices)
• Upgrading major versions with breaking changes

DO NOT use for: New features, bug fixes, pure refactoring without technology change.

Core Principles

1. Analyze Before Migrating: Understand current system before planning target state
2. Risk Assessment: Classify migration type (code/data/architecture) and assess complexity
3. Incremental Execution: Support phased migration with rollback points
4. Rollback Planning: Document undo procedures for each migration phase
5. Dual-Run Support: Enable running old and new systems in parallel during transition

Migration Types

Phase Configuration

Workflow Phases

Phase 1: Current State Analysis & Clarifications

Purpose: Comprehensive analysis of current system before migration, followed by scope/requirements clarification Execute:

1. Skill tool - maister:codebase-analyzer
2. Update state with analysis results
3. Direct - use AskUserQuestion for max 5 critical clarifying questions about migration scope, target system, and constraints
4. Save clarifications to analysis/clarifications.md

Output: analysis/current-state-analysis.md, analysis/clarifications.md State: Update migration_context.current_system, migration_context.clarifications_resolved, migration_context.phase_summaries.current_state_analysis

→ AUTO-CONTINUE — Do NOT end turn, do NOT prompt user. Proceed immediately to Phase 2.

Phase 2: Target State Planning & Gap Analysis

Purpose: Define target system and identify migration gaps Execute: Task tool - maister:gap-analyzer subagent Output: analysis/target-state-plan.md State: Update migration_context.migration_type, target_system, migration_strategy, risk_level, breaking_changes, migration_context.phase_summaries.gap_analysis

Gap Analyzer Tasks:

1. Define target system from migration description
2. Identify gaps (features to migrate, APIs to adapt, data to transform)
3. Classify migration type (code/data/architecture/general), keeping a type supplied by --type
4. Recommend migration strategy (incremental/big-bang/dual-run/phased)
5. External research via WebSearch for version upgrades

→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke AskUserQuestion now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md § 2 / § 2.1).

AskUserQuestion - Display executive summary before asking. Extract from gap analysis: current system overview, target system, migration type classified, number of gaps identified, recommended strategy, risk level. Format as brief overview then "Continue to migration strategy?"

Phase 3: Migration Requirements & Strategy Specification

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 2 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding AskUserQuestion call are protocol violations — never paper over a missed gate by updating state.

Purpose: Gather migration requirements, then create detailed migration specification with rollback procedures Execute:

Part A — Migration Requirements Gathering (inline):

1. Direct - use AskUserQuestion for migration-specific requirements (3-5 questions):

• Migration scope and boundaries (what's in/out of migration)
• Rollback expectations and downtime tolerance
• Data migration specifics (if data migration type)
• Dual-run requirements (if applicable)
• Existing code/config to preserve
• Frame as confirmable assumptions: "I assume X, is that correct?"

1. Save gathered requirements to analysis/requirements.md

Part B — Specification Creation (subagent):

1. Task tool - maister:specification-creator subagent