maister-migration

name	maister:migration
description	Orchestrates the complete migration workflow from current state analysis through implementation to compatibility verification. Handles technology migrations, platform changes, and architecture pattern transitions with adaptive risk assessment, incremental execution, and rollback planning. Use when migrating technologies, platforms, or architecture patterns.
user-invocable	true

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** — 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). / → 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. Create Task Items: Use TaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy
3. Create Task Directory: .maister/tasks/migrations/YYYY-MM-DD-task-name/
4. Initialize State: Create orchestrator-state.yml with migration context
5. 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).
6. 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). 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.

---

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

Type	Keywords	Strategy	Risk Focus
Code	framework, library, upgrade	Incremental or phased	Breaking changes, API differences
Data	database, schema, data migration	Dual-run (zero downtime)	Data integrity, checksums
Architecture	REST→GraphQL, monolith→microservices	Dual-run or phased	Compatibility, rollback

---

Phase Configuration

Phase	content	activeForm	Agent/Skill
1	"Analyze current state"	"Analyzing current state"	codebase-analyzer
2	"Plan target state and gaps"	"Planning target state and gaps"	gap-analyzer
3	"Gather requirements & create migration strategy"	"Gathering requirements & creating migration strategy"	Direct + specification-creator (subagent)
4	"Plan implementation"	"Planning implementation"	implementation-planner (subagent)
5	"Execute migration"	"Executing migration"	implementation-plan-executor
6	"Verify and test compatibility"	"Verifying and testing compatibility"	implementation-verifier
7	"Resolve verification issues"	"Resolving verification issues"	Direct (conditional)
8	"Generate documentation"	"Generating documentation"	user-docs-generator (optional)

---

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 task_context with current system info, task_context.clarifications_resolved

→ 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, risk_level, breaking_changes

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)
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?"
2. Save gathered requirements to analysis/requirements.md

Part B — Specification Creation (subagent): 3. Task tool - maister:specification-creator subagent

Context to pass to subagent: task_path, task_type (migration), task_description, requirements_path (analysis/requirements.md), project_context_paths (INDEX.md + project_doc_paths from state — all discovered project docs), migration_type, current_system, target_system, risk_level, breaking_changes, phase_summaries (current_state_analysis, gap_analysis), html_style_guide_path (for the spec.html companion)

Output: analysis/requirements.md, implementation/spec.md, analysis/rollback-plan.md, optionally analysis/dual-run-plan.md State: Update rollback_plan_created, dual_run_configured

→ 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. Read implementation/spec.md and extract: migration strategy chosen, scope boundaries, rollback approach, breaking changes identified, key constraints. Format as brief overview then "Continue to implementation planning?"

---

Phase 4: Implementation Planning

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 3 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: Break migration into task groups with rollback steps Execute: Task tool - maister:implementation-planner subagent Output: implementation/implementation-plan.md with rollback procedures State: Update task groups and dependencies

Context to pass to subagent: task_path, task_type (migration), migration_type, task_description, phase_summaries (current_state_analysis, gap_analysis, specification), html_style_guide_path (for the implementation-plan.html companion)

→ 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. Read implementation/implementation-plan.md and extract: number of task groups, total steps, rollback steps included, key dependencies, execution sequence. Format as brief overview then "Continue to execute migration?"

---

Phase 5: Migration Execution

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 4 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: Execute migration steps with incremental verification

ANTI-PATTERN — DO NOT DO THIS:

• ❌ "Let me implement this directly..." — STOP. Delegate to implementation-plan-executor.
• ❌ "This migration is simple enough to code inline..." — STOP. Simplicity is NOT a reason to skip delegation.

INVOKE NOW — Skill tool call:

Execute: Skill tool - maister:implementation-plan-executor Output: Implemented migration changes, implementation/work-log.md State: Update implementation progress, extract phase_summaries.implementation

📋 Standards Reminder: Review .maister/docs/INDEX.md before implementing.

SELF-CHECK: Did you just invoke the Skill tool with maister:implementation-plan-executor? Or did you start writing migration code yourself? If the latter, STOP immediately and invoke the Skill tool instead.

⚠️ POST-IMPLEMENTATION CONTINUATION — After the skill completes and returns control:

1. HTML plan reconciliation (backstop for syncs missed during waves): if implementation/implementation-plan.html exists, for every group whose md checkboxes are all [x], run the executor's idempotent marker-flip command (sed flipping data-step="N\.[0-9]*" class="step todo" and data-group="N" class="group todo" to done). VERIFY: when all md steps are checked, grep -c 'class="step todo"' implementation/implementation-plan.html must return 0.
2. Read orchestrator-state.yml to confirm you are the orchestrator
3. Update state: add Phase 5 to completed_phases
4. Proceed to Phase 6

→ 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 phase_summaries.implementation and implementation/work-log.md: migration steps completed, files changed, test results, rollback readiness status. Format as brief overview then "Continue to verification?"

---

Phase 6: Verification + Compatibility Testing

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 5 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: Verify migration success with compatibility and rollback testing Execute: Skill tool - maister:implementation-verifier Output: verification/implementation-verification.md, verification/compatibility-test-results.md State: Update verification results

Migration-Specific Checks:

• Verify old system still works (if dual-run)
• Test rollback procedures (non-destructive)
• Validate data integrity (for data migrations)
• Check performance benchmarks (before/after)

⚠️ POST-VERIFICATION CONTINUATION — After the skill completes and returns control:

1. Read orchestrator-state.yml to confirm you are the orchestrator
2. Update state: add Phase 6 to completed_phases
3. Evaluate verdict: if PASS → Phase 8, if fixable issues → Phase 7, otherwise stop workflow

→ 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 verification results: overall verdict, issue counts by severity, compatibility test results, data integrity status, rollback test results. Format as detailed overview then "Continue to Phase [7 or 8]?"

---

Phase 7: Migration Issue Resolution (Conditional)

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from Phase 6 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: Fix verification issues through direct editing and re-verification Execute: Direct - apply fixes, re-verify Output: Updated code, verification_context.fixes_applied State: Update reverify_count, decisions_made

Skip if: verdict = PASS

Process:

1. Display detailed issue breakdown grouped by category and severity, listing location, description, and fixability
2. Present all critical + warning issues as a numbered list
3. AskUserQuestion — "Which issues should I fix?" with options: "Fix all fixable issues" / "Let me choose specific issues" / "Skip fixes, proceed as-is"
4. Fix selected issues
5. AskUserQuestion — "Re-run verification to check fixes?" with options: "Yes, re-run verification" / "No, proceed to next phase"
6. If re-run → re-invoke maister:implementation-verifier → return to Step 1
7. Max 3 iterations

Data Safety Critical: HALT on any data integrity issue - never auto-fix data problems. Always present data issues to user with rollback option.

Exit Conditions:

• ✅ No critical issues remain → Proceed to Phase 8
• ⚠️ Max iterations (3) reached → Ask user: proceed with warnings or rollback
• ❌ Data integrity issues → HALT immediately, recommend rollback

→ 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: total issues found, issues fixed, issues remaining by severity. Then "Continue to documentation?"

---

Phase 8: Documentation (Optional)

Phase entry self-check: Before executing this phase, locate the AskUserQuestion tool call from the preceding phase 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: Create migration guide for end users Execute: Task tool - maister:user-docs-generator subagent Output: documentation/migration-guide.md State: Set documentation complete

Skip if: options.docs_enabled = false

Documentation Covers:

• Migration overview and goals
• Prerequisites and preparation steps
• Step-by-step migration procedure
• Rollback procedures
• Troubleshooting common issues

→ End of workflow

---

Domain Context (State Extensions)

Migration-specific fields in orchestrator-state.yml:

migration_context:
  migration_type: "code" | "data" | "architecture" | "general"
  current_system:
    description: null
    technologies: []
  target_system:
    description: null
    technologies: []
  migration_strategy:
    approach: "incremental" | "big-bang" | "dual-run" | "phased"
    phases: []
  risk_level: null
  breaking_changes: []
  rollback_plan_created: false
  dual_run_configured: false

external_research:
  performed: false
  category: null
  breaking_changes: []
  migration_guide_url: null

verification_context:
  last_status: null
  issues_found: null
  fixes_applied: []
  decisions_made: []
  reverify_count: 0

options:
  html_output: true  # Seeded from .maister/config.yml at init (default true). Gates dashboard + HTML companions.
  docs_enabled: false

---

Task Structure

.maister/tasks/migrations/YYYY-MM-DD-migration-name/
├── orchestrator-state.yml
├── dashboard.html                    # Operator dashboard (copied plugin asset — never model-generated)
├── dashboard-data.js                 # Dashboard data projection (rewritten per phase/gate)
├── analysis/
│   ├── current-state-analysis.md     # Phase 1
│   ├── target-state-plan.md          # Phase 2
│   ├── requirements.md               # Phase 3
│   ├── rollback-plan.md              # Phase 3
│   └── dual-run-plan.md              # Phase 3 (if dual-run)
├── implementation/
│   ├── spec.md                       # Phase 3
│   ├── spec.html                     # Phase 3 (HTML companion)
│   ├── implementation-plan.md        # Phase 4
│   ├── implementation-plan.html      # Phase 4 (HTML companion)
│   └── work-log.md                   # Phase 5
├── verification/
│   ├── implementation-verification.md    # Phase 6
│   ├── implementation-verification.html  # Phase 6 (HTML companion)
│   └── compatibility-test-results.md     # Phase 6
└── documentation/
    └── migration-guide.md            # Phase 8 (optional)

---

Auto-Recovery

Phase	Max Attempts	Strategy
1	2	Expand search patterns, prompt user for file paths
2	2	Re-prompt for target details
3	2	Re-gather requirements, re-invoke spec-creator subagent, regenerate rollback plan
4	2	Regenerate with migration constraints
5	5	Fix syntax errors, prompt user on repeated failure
6	3	Fix-then-reverify. HALT on data integrity issues
8	1	Generate text-only without screenshots

---

Command Integration

Invoked via:

• /maister:migration [description] [--type=TYPE] [--sequential] (new)
• /maister:migration [task-path] [--from=PHASE] [--sequential] (resume)

Flags:

• --type=TYPE: Migration category (e.g. database, api, framework)
• --from=PHASE: Resume from specific phase
• --sequential: Disable parallel wave dispatch in implementation-plan-executor; run one task group at a time. Persisted as orchestrator.options.sequential: true in orchestrator-state.yml. Defaults to off (parallel waves).

Task directory: .maister/tasks/migrations/YYYY-MM-DD-task-name/