Migrate Plan

Migration Plan Creation

Produces two documents: a Migration Overview (concise, human-readable) and a Migration Detail (comprehensive, AI-consumable). Takes structured content model descriptions or free-text descriptions as input.

Workflow

Step 1: Read Reference Materials

• Read [migration-tool.md](../_shared/references/migration-tool.md) for migration tool capabilities, supported data, extension points, and configuration options.
• If you need documentation links, read [migration-docs.md](../_shared/references/migration-docs.md).
• If a Kentico documentation lookup tool is available, use it for additional context on XbyK content types, reusable field schemas, Content hub, or Page Builder.

Step 2: Understand the Source Content Model

If a file path was provided, read the source content model files. If a direct description was provided, analyze it to identify:

• Page types and their fields (note any inheritance, macros in defaults, or field categories — these are NOT supported by the migration tool). Document the class inheritance hierarchy (ClassInheritsFromClassID relationships) — this is critical for determining which classes can safely be excluded. Parent classes must not be excluded even if they have 0 instances, or all child classes will fail during --page-types. Collect ClassID (numeric) for every page type — ICmsTree.NodeClassID is an int, and ContentItemDirectorBase filters like LinkChildren use .Where(c => c.NodeClassID == ), not class code names. The numeric ClassID must be available in the plan for anyone writing director or extension code.
• Custom tables and module classes
• Page Builder widgets in use (distinguish built-in vs custom)
• Page relationships (linked pages, child pages) — see the "Linked Pages in KX13" section in [migration-tool.md](../_shared/references/migration-tool.md) for how to identify linked pages (NodeLinkedNodeID IS NOT NULL), their characteristics (shared content, separate tree node, no own data), and common KX13 patterns (taxonomy, reused-content folders)
• docrelationships field data (CMS_Relationship table) — when the source audit includes a "Page Relationships (CMS_Relationship)" section, use it to understand which docrelationships fields have actual relationship data, which pages they connect, and what the target page types are. Each ad-hoc relationship name contains the field GUID (ClassName_FieldGUID), making it possible to map relationship rows back to specific page type fields. This data is critical for planning ConvertFrom transforms that resolve docrelationships NodeIDs to target values (taxonomy tags, content item references, webpage references). Include the full relationship data in the detail document's Source Content Model section.
• Parent-child hierarchies where children could become content item references — identify page types that are direct children of another page type and are candidates for Content Hub conversion (e.g., Company children under a ContactPage, product children under a store section). These can be linked as references via LinkChildren in ContentItemDirectorBase.Direct(). Also identify intermediate non-content nodes (e.g., CMS.Folder) that may sit between the target parent and the child pages, as these affect the director implementation.
• Media handling (attachments, media libraries, text fields with Media selection form control — text fields can be converted to content item assets via OptInFeatures.CustomMigration.FieldMigrations configuration; file/attachment fields automatically migrate as Legacy.Attachment content items with working asset references)

Ask clarifying questions if critical information is missing (page types, page relationships, widgets).

Step 3: Resolve Migration Approach Decisions

Read [migration-approach-categories.md](references/migration-approach-categories.md) for the full list of migration approach categories (A through J).

If a target content model was provided, analyze it, then compare it against the source model to identify structural divergences — places where the target departs from a straightforward 1:1 migration. Use the "When to ask — target model provided" triggers in each category.

If no target content model was provided, walk through the source model and use the "When to ask — no target model" triggers to identify which categories apply. The default option in each category is a straightforward migration; only ask about categories where the source model has characteristics that make the non-default option worth considering.

For each applicable category, ask the user which option they prefer before generating the plan. Present the options concisely with clear trade-off summaries. If there are 3+ decisions, present all of them and collect all answers at once. After collecting answers, proceed to generate the plan using the chosen approaches and record which option was selected.

Step 4: Create the Migration Overview

Read [MIGRATIONOVERVIEWTEMPLATE.md](assets/MIGRATIONOVERVIEWTEMPLATE.md) and produce the overview document covering:

Manual Steps — Pre-migration setup (items to create before migration), post-migration tasks (creating wrapper pages, populating references, optionally curating Legacy.Attachment items into custom asset types), target-only entities (content types and taxonomies with no source equivalent that must be created manually), and unsupported features with recommended XbyK alternatives. Note: ToolApiController deployment for Source Instance API Discovery is NOT a manual step — the appsettings skill handles it automatically during configuration generation (see migrate-appsettings Step 1c). Do not list it as a pre-migration manual step. When a pre-migration step involves creating a taxonomy whose tag GUIDs are needed by field transforms, the step description must tell the user to fill in the tag GUIDs in the detail document's lookup table and include a markdown link to the relevant Custom Value Transforms subsection in the detail document (e.g., [fill in the tag GUIDs](migration-detail.md#doctoremergen‌cyshift--doctorprofiledoctorprofileemergencyshift)). Before listing any step as "manual", critically evaluate whether the migration tool can handle it via configuration or code extensions — only list it as manual if there is genuinely no migration tool mechanism. Do not list project setup (creating the XbyK project), source instance prerequisites, or other assumed setup steps. Reusable field schemas created by ReusableSchemaBuilder in IClassMapping are automatic — never list them as manual.

Content Model Mapping Overview — High-level tables showing Content Hub conversions, webpage mappings, merge/split scenarios, exclusions, taxonomy planning (migrated from KX13 categories vs. new), and reusable field schemas. No appsettings.json fragments or code — just class names and brief summaries. Content types that exist only in the target model (no source equivalent) must be listed in the "Target-Only Entities" section with pre/post-migration timing. Taxonomies not migrated from KX13 categories must be marked as "Manual (pre-migration)" if needed by field transforms during migration (i.e., a ConvertFrom or IFieldMigration references tag GUIDs at migration time), or "Manual (post-migration)" if only referenced by target-only content types that are created after migration or used solely for editorial classification.

Field Mapping Overview — Key transformations summarized by source class with complexity notes in the transformation summary text (no dedicated effort column). Attachment field migration paths. No ConvertFrom details or lookup dictionaries.

Widget Transformation Overview — Built-in widgets (auto-migrate), custom widget mappings, section mappings. Brief summaries with complexity notes in summary text (no dedicated effort column), no property-level detail.

Page Relationship Overview — Strategies (materialize, store_reference, etc.) described in plain language.

Execution Summary — A table of all migrate CLI parameters with a Status column. Set Status to Required for parameters actively needed by this migration run; leave as — for parameters that are available but not required. Default to including all applicable CLI steps (--sites, --custom-modules, --users, --page-types, --pages, --categories, --media-libraries, --forms) — it is safer to run a step that finds no data than to omit one that silently skips content. Each parameter is displayed as inline code (e.g., ` --sites ). An optional **Notes** column can add brief context (dependencies, what data the step covers). Do not use checkbox syntax (- [x] / - [ ]`) as it does not render in standard markdown previewers. Do NOT include a code extensions summary table here — code extensions are already listed in the dedicated "Code Extensions Summary" section earlier in the document.

Operational Notes — Iterative migration guidance (upsert behavior, --bypass-dependency-check for repeated runs), bulk deletion requirements (data types that require manual cleanup before re-runs: contacts/activities, consent agreements, form submissions, custom module class data), and logging/troubleshooting guidance (console output, log file location at logs/log.txt — relative to the CLI project directory and configured by Logging.pathFormat in appsettings.json).

Step 5: Create the Migration Detail

Read [MIGRATIONDETAILTEMPLATE.md](assets/MIGRATIONDETAILTEMPLATE.md) and produce the detail document covering:

Source Content Model — Full page type field tables with ClassID (numeric ID from CMS_Class) included in each page type's heading or summary row, class inheritance hierarchy (when any page type has ClassInheritsFromClassID), custom tables, module classes, Page Builder component inventories.

Target Content Model — Full content type definitions with Created By indicators (Migration tool vs Manual), reusable field schemas with field lists, taxonomy definitions with tag values and creation method. The migration tool only creates content types from source data (via IClassMapping during --page-types) and taxonomies from KX13 categories (via --categories). Types with no source equivalent must be marked "Manual" with pre/post-migration timing. Reusable field schemas created by ReusableSchemaBuilder in an IClassMapping are automatic and must not be listed as manual.

Content Model Mapping — ConvertClassesToContentHub lists with appsettings.json fragments, IClassMapping registrations, merge/split field mapping tables, exclusion configuration with EntityConfigurations JSON, and taxonomy planning (migrated KX13 categories vs. new taxonomies with creation method).

Field Mappings — Complete field change tables (source → target with rename, data type change, form component change). Use the Field Type and Form Control Mapping table in [migration-tool.md](../_shared/references/migration-tool.md) for default data type → form component mappings. For every field with a data type or form control change, explicitly assign a mechanism — see the "Field definition changes" gotcha below. Include a Custom Form Control Fields subsection listing any source form controls not covered by the built-in mapping table (e.g., countrySelector, emailinput, URLSelector). For each, state the source data type + form control, the target data type + form component, and the handling mechanism: built-in catch-all, appsettings.json FieldMigrations config, IFieldMigration code, or IClassMapping.WithFieldPatch. Include SEO metadata mapping, file/attachment migration paths (including OptInFeatures.CustomMigration.FieldMigrations configuration for text fields with Media selection form control), and custom value transforms with detailed transformation logic (ConvertFrom targets, lookup dictionaries, edge cases). In lookup dictionary tables where XbyK tag GUIDs are not yet known (assigned when the taxonomy is created pre-migration), use TODO as the placeholder value (e.g., TODO in the "XbyK Tag GUID" column) so these are easy to find and fill in later.

Page Relationship Handling — Linked page strategies with ContentItemDirectorBase configuration, linked page audit (every linked page with explicit strategy), child-as-reference mappings with ancestor level calculations, pages-as-widgets configuration.

Widget Transformations — Source Instance API Discovery config, section type mappings with property transforms, custom widget mappings with full property-level detail, IWidgetPropertyMigration transforms with examples.

Execution Plan — Complete appsettings.json configuration (including TargetWorkspaceName and AssetRootFolders when applicable) and full code extensions table (every IClassMapping, ContentItemDirectorBase, IWidgetMigration, IWidgetPropertyMigration, IFieldMigration with descriptions). For code extensions, reference ModelFacade for source data querying and IImporter with UMT models (ContentItemModel, DataClassModel, ContentItemLanguageMetadataModel, WebPageItemModel) for target writes where relevant. Do NOT include a "Migration Command" section — the migration command checklist belongs exclusively in the overview document.

Validate plan completeness before presenting:

• Every target content type has a creation path (migration tool via IClassMapping, manual pre-migration, or manual post-migration)
• Every source page type/class has a disposition (mapped, converted to Content Hub, merged, excluded, or default migration)
• No class in the Exclusions ExcludeCodeNames list is a parent class (ClassInheritsFromClassID) of any class being migrated — parent classes with 0 instances must NOT be excluded
• All linked pages in the KX13 page tree are audited with explicit strategies
• Error/utility pages (404, maintenance, redirects) are explicitly handled — either excluded or mapped

Validate plan internal consistency before presenting:

• Code extension counts: The count for each extension type in the overview's "Code Extensions Summary" table must exactly match the number of rows of that type in the detail's "Code Extensions to Implement" table. If a widget transformation section describes IWidgetMigration code for a widget, there must be a corresponding row in the code extensions table.
• Widget strategy consistency: Each custom widget must tell exactly one story across: (1) the widget transformation section (overview + detail), (2) the code extensions summary/table, (3) the "Unsupported features" section, and (4) manual steps. A widget cannot simultaneously be described as "automated via IWidgetMigration" in the widget section and "unsupported / post-migration only" in the unsupported features section. If a widget's structural migration is automated but its underlying KX13 feature has no XbyK equivalent (e.g., newsletter subscription engine), the unsupported features entry must clearly scope what is unsupported (the feature/engine) vs. what is automated (the widget structure/property migration).
• Child-as-reference vs. post-migration manual: Before marking any "populate content item references" as a post-migration manual step, verify whether LinkChildren (in ContentItemDirectorBase.Direct()) can handle it automatically during --pages. Direct parent-child relationships where both types are converted to Content Hub should use LinkChildren. Only mark as post-migration manual when: (a) the reference connects content types that are not in a parent-child tree relationship, (b) the reference field connects types where the child is not a direct child (grandchildren through folders may require LinkChildren on the intermediate node), or (c) the reference field was invented for the target model with no source hierarchy equivalent.
• Manual step scope: When

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Kentico
• Source: Kentico/xperience-by-kentico-kenticopilot
• License: MIT

Install and usage instructions live in the source repository linked above.