Skip to content

Commit 07cc3d9

Browse files
xminar1Jakub SkurekJakubS-Kentico
authored
Feature/kx13 migration (#5)
* Add GH Copilot prompts * Add Cursor prompts * Add claude code prompts * Rename instruction files in widget part * Adjust CC MCP tools * Improve parametrization * documentation * revert accidental legacy->source rename in prompt files * review changes * restructure readme * rename folder * typos fix * review changes --------- Co-authored-by: Jakub Skurek <jakubs@NN-32-NTB.localdomain> Co-authored-by: Jakub Skurek <jakubs@kentico.com>
1 parent 5a4ef64 commit 07cc3d9

38 files changed

+1334
-39
lines changed

‎src/kx13-codebase-migration/README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# KX13 Project codebase migration
2+
3+
AI-assistant prompts for migrating the **codebase** of Kentico Xperience 13 projects to [Xperience by Kentico](https://docs.kentico.com/x/migrate_from_kx13_guides).
4+
5+
## Scope
6+
7+
These prompts are designed to help migrate the live site and page presentation logic as described in the following guides:
8+
9+
- [Adjust global code](https://docs.kentico.com/guides/architecture/upgrade-from-kx13/upgrade-walkthrough/adjust-global-code) – Generating code files for content types, copying localization resources, shared views, styles/scripts, and enabling content tree-based routing and Page Builder.
10+
- [Display an upgraded page](https://docs.kentico.com/guides/architecture/upgrade-from-kx13/upgrade-walkthrough/display-an-upgraded-page) – Content retrieval services, repositories, view models, views, controllers, and Page Builder sections/widgets.
11+
12+
The following areas are not covered and must be handled manually:
13+
14+
- Custom modules
15+
- Custom tables
16+
- Authentication and user management
17+
- Search functionality
18+
- E-commerce
19+
- Marketing features
20+
21+
See the [Adjust and adapt your code](https://docs.kentico.com/x/migrate_your_code_guides) migration guide for details.
22+
23+
## Prerequisites
24+
25+
- Kentico Xperience 13 project (source).
26+
- Xperience by Kentico project (target) connected to a database migrated using the [Kentico Migration Tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool). The prompts were tested on a fresh Xperience by Kentico project created using the `kentico-xperience-mvc` [project template](https://docs.kentico.com/x/DQKQC).
27+
- AI coding assistant installed (for example: GitHub Copilot, Cursor, Claude Code).
28+
29+
## Usage
30+
31+
### 1. Set up project structure
32+
33+
Place your KX13 and XbyK projects in the same workspace with the following structure:
34+
35+
```
36+
KX13/ # Kentico Xperience 13 project files
37+
XbyK/ # Xperience by Kentico project files
38+
```
39+
40+
Start both projects locally. During the migration, the agent actively visits URLs in both projects to evaluate progress.
41+
42+
### 2. Copy the prompts to the workspace
43+
44+
Copy the appropriate files for your AI assistant. Note that the files also add the Xperience by Kentico [Documentation MCP server](https://docs.kentico.com/x/mcp_server_xp) and [Playwright MCP server](https://github.com/microsoft/playwright-mcp) to your workspace.
45+
46+
> **Important:** For Claude Code, you need to add the MCP servers manually via the command line. Follow the [setup instructions](claude-code/MCP_Setup.md).
47+
48+
### 3. Run the migration prompts
49+
50+
The prompts are divided into three main groups:
51+
52+
#### Global
53+
- [**migrate-global-code**](#migrate-global-code) – Sets up the target XbyK project structure, generates code files, and migrates shared code (localization, styles, business logic, etc.).
54+
55+
#### Component
56+
- [**migrate-shared-component**](#migrate-shared-component) – Migrates reusable components (layouts, headers, breadcrumbs, etc.).
57+
58+
#### Page
59+
- [**migrate-page-widgets**](#migrate-page-widgets) – Migrates Page Builder widgets and sections used by the specified page.
60+
- [**migrate-page**](#migrate-page-logic) – Migrates the specified page and related business and presentation logic, including controllers, views, and dependencies.
61+
- [**migrate-page-visual**](#ensure-page-visual-match) – Ensures migrated pages visually match the original KX13 pages. Used in case the page migration prompts result in visual discrepancies.
62+
63+
In a general workflow, you migrate in waves:
64+
65+
1. Global code to seed the target project with initial logic (using the [*migrate-global-code*](#migrate-global-code) prompt).
66+
2. A single page to establish working URLs in the target project.
67+
1. First, migrate the page's Page Builder dependencies using [*migrate-page-widgets*](#migrate-page-widgets). Skip this step for pages that don't use Page Builder.
68+
2. Then, migrate the business and presentation logic using [*migrate-page*](#migrate-page-logic).
69+
3. Shared components to ensure consistent visuals across pages (using the [*migrate-shared-component*](#migrate-shared-component) prompt). Use the URL of the page migrated in step 2 to verify visual accuracy.
70+
4. Remaining pages, repeating step 2 for each.
71+
- If any migration results in visual issues, use [*migrate-page-visual*](#ensure-page-visual-match).
72+
73+
## Best practices
74+
75+
- Run prompts in sequence. Each prompt builds on the work done in the previous step. For example, the full sequence to migrate a page is: *migrate-page-widgets* → *migrate-page* → *migrate-page-visual*, repeating as necessary until all pages are converted. You can also omit prompts based on the requirements of the page being converted. If a page doesn't use Page Builder features, you can skip the *migrate-page-widgets* prompt.
76+
- Have both the source KX13 and target XbyK applications running -- the agent visits both applications to compare migration progress.
77+
- After running a prompt, review all generated code before proceeding to the next step.
78+
- Use the visual matching prompt to fix styling discrepancies.
79+
- Thoroughly test all migrated functionality.
80+
81+
## Prompt reference
82+
83+
### Migrate global code
84+
85+
Prompt name: **migrate-global-code**
86+
87+
Migrates global code, generates code files, and sets up the project foundation. The prompt makes the following changes:
88+
89+
- Creates a new .NET project in the target folder and marks it as [discoverable](https://docs.kentico.com/x/QoXWCQ) by Xperience.
90+
- Uses the code generator utility to [generate classes](https://docs.kentico.com/x/5IbWCQ) for migrated database entities (content types, etc.).
91+
- Copies global project files, such as assets and resources, and global code, such as service registration and project startup logic, to the target.
92+
- Enables [content tree-based routing](https://docs.kentico.com/x/GoXWCQ) and [Page Builder](https://docs.kentico.com/x/6QWiCQ) on the target.
93+
94+
**VS Code GitHub Copilot example:**
95+
96+
```
97+
/migrate-global-code
98+
```
99+
100+
### Migrate shared component
101+
102+
Prompt name: **migrate-shared-component**
103+
Parameters:
104+
- *componentName*: The name of the shared element to migrate. For example: header, footer, navigation menu, sidebar.
105+
- *legacyPageUrl*: The URL of the page in the source project
106+
107+
Migrates reusable components like headers, footers, and navigation elements. The prompt locates the specified element in the source project and migrates it together with all dependencies (views, layouts, logic, etc.).
108+
109+
**VS Code GitHub Copilot example:**
110+
111+
```
112+
/migrate-shared-component
113+
114+
componentName: breadcrumbs
115+
legacyPageUrl: https://localhost:5001/en-us/home
116+
```
117+
118+
### Migrate page widgets
119+
120+
Prompt name: **migrate-page-widgets**
121+
Parameters:
122+
- *pageName*: The name in the content tree of the source project
123+
- *legacyPageUrl*: The URL of the page in the source project
124+
125+
Migrates Page Builder [widgets](https://docs.kentico.com/x/7gWiCQ) and [sections](https://docs.kentico.com/x/9AWiCQ) used by the specified page.
126+
127+
This prompt can be omitted if the specific page doesn't use Page Builder features.
128+
129+
**VS Code GitHub Copilot example:**
130+
131+
```
132+
/migrate-page-widgets
133+
134+
pageName: home
135+
legacyPageUrl: https://localhost:5001/en-us/home
136+
```
137+
138+
### Migrate page logic
139+
140+
Prompt name: **migrate-page**
141+
Parameters:
142+
- *pageName*: The name in the content tree of the source project
143+
- *legacyPageUrl*: The URL of the page in the source project
144+
145+
Migrates the code of individual pages: controllers, views, layouts, and dependencies.
146+
147+
**VS Code GitHub Copilot example:**
148+
149+
```
150+
/migrate-page
151+
152+
pageName: home
153+
legacyPageUrl: https://localhost:5001/en-us/home
154+
```
155+
156+
### Ensure page visual match
157+
158+
Prompt name: **migrate-page-visual**
159+
Parameters:
160+
- *pageName*: The name in the content tree of the source project
161+
- *legacyPageUrl*: The URL of the page in the source project
162+
- *newPageUrl*: The URL of the page in the target project
163+
164+
Ensures the migrated page visually matches the original KX13 page. Use if the migrate-page prompt doesn't successfully replicate the look and feel. The prompt uses Playwright to identify differences in both pages and aligns the migrated page to match the source.
165+
166+
**VS Code GitHub Copilot example:**
167+
168+
```
169+
/migrate-page-visual
170+
171+
pageName: home
172+
legacyPageUrl: https://localhost:5001/en-us/home
173+
newPageUrl: http://localhost:60444/en-us/home
174+
```
175+
176+
## Prompt customization
177+
178+
These prompt files serve as a baseline for migrating the codebase of KX13 projects to Xperience by Kentico. Modify and enhance the files as required by your implementation, workflow, and requirements. For example, you can update the `instructions/projects-structure.md` file with additional information about the project being migrated.

‎src/kx13-codebase-migration/claude-code/.claude/commands/migrate-global-code.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
description: "Migrate global code from KX13 to XbyK project."
3+
allowed-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, AskUserQuestion, Skill, SlashCommand, mcp__kentico.docs.mcp__*
4+
---
5+
6+
You are tasked with the process of migrating global code from a Kentico Xperience 13 project to an Xperience by Kentico project.
7+
8+
## Structure of the projects
9+
10+
Look at the file `../instructions/projects-structure.md` to understand the structure of both the legacy and new project.
11+
12+
## Migration Steps
13+
14+
1. Check out the structure of both the legacy and new project.
15+
2. Use Kentico Docs MCP to read the following page: https://docs.kentico.com/guides/architecture/upgrade-from-kx13/upgrade-walkthrough/adjust-global-code (note that this guide is written for a sample project and that there will be some differences between the sample project and the project you are migrating)
16+
3. Create a new project for generated code files (named {ProjectName}.Entities).
17+
1. Configure given project as described in the documentation.
18+
2. **CRITICAL:** Ensure the .csproj file contains the following (without this, content item reference fields will fail to populate):
19+
```xml
20+
<ItemGroup>
21+
<AssemblyAttribute Include="CMS.AssemblyDiscoverableAttribute" />
22+
</ItemGroup>
23+
```
24+
4. Generate code files by running the `--kxp-codegen` command as described in the documentation. Always use `--skip-confirmation` flag to avoid interactive prompts
25+
5. Copy relevant global code from source project to the new project.
26+
1. Localization
27+
2. Shared views
28+
3. Styles and scripts
29+
4. Identifiers
30+
5. Services registration
31+
6. Configure the project to display content.
32+
1. Enable Content tree-based routing and Page Builder.
33+
2. Add future custom service registrations and localization.
34+
7. In the end, ensure that the new project builds successfully without errors and warnings, if not, some part of documentation was not followed correctly, so fix the issues based on the docs page.
35+
36+
Notes relevant to the migration process:
37+
38+
- Do not change any other files or settings outside of the global code migration process (that are not mentioned in the docs page).
39+
- When commenting out code, always add "TODO:" note to make it easier to find later.
40+
41+
## Output format
42+
43+
When done, provide user with this exact output (without any additional text):
44+
45+
```
46+
# Migration Complete
47+
Global code migration from the legacy project to the new one has been successfully completed.
48+
49+
**Next steps:**
50+
- Update your channel configuration to include the port of the local XbyK instance (the one the project launches with).
51+
Follow these steps: https://docs.kentico.com/guides/architecture/upgrade-from-kx13/upgrade-walkthrough/adjust-global-code#adjust-system-url
52+
- Review the changes to ensure everything looks as expected.
53+
- Continue with the /migrate-page-widgets prompt to migrate Page Builder widgets used by the specified page.
54+
```

‎src/kx13-codebase-migration/claude-code/.claude/commands/migrate-page-visual.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
description: "Ensure migrated page visually matches the original KX13 page"
3+
argument-hint: [pageName] [legacyPageUrl] [newPageUrl]
4+
allowed-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, AskUserQuestion, Skill, SlashCommand, mcp__kentico.docs.mcp__*, mcp__playwright-mcp__*
5+
---
6+
7+
You are tasked with ensuring that the migrated page visually matches the original legacy page.
8+
9+
## Input Parameters
10+
11+
- **Page Name:** `$pageName` - The name/path of the page being matched (e.g., 'home', 'doctors').
12+
- **Legacy Page URL:** `$legacyPageUrl` - The URL of the page in the KX13 project (e.g., 'https://localhost:5001/en-us/home').
13+
- **New Page URL:** `$newPageUrl` - The URL of the page in the XbyK project (e.g., 'http://localhost:60444/en-us/home').
14+
15+
## Structure of the projects
16+
17+
Look at the file `../instructions/projects-structure.md` to understand the structure of both the legacy and new project.
18+
19+
## Context
20+
21+
The page migration from KX13 to XbyK has been completed in the previous step. The result is a functional page, but it does not visually match the original. Your task is to make the new page look completely identical to the old one.
22+
23+
## Important Principles
24+
25+
1. **Dynamic content** - When migrating a page, ensure that everything that was fetched dynamically from the database will still be dynamically fetched from the database. Nothing can be statically hardcoded in the new project if it was dynamic in the legacy project.
26+
2. **Pixel-perfect matching** - The goal is to make the pages visually identical, including layout, spacing, colors, fonts, and responsive behavior.
27+
3. **Preserve functionality** - While fixing visual issues, ensure all functionality remains intact.
28+
29+
## Visual Matching Steps
30+
31+
1. **Ensure XbyK is running** - Start the application if not already running.
32+
33+
2. **Capture both pages** - Use Playwright MCP to navigate to both pages:
34+
35+
- Navigate to the legacy page URL
36+
- Take a snapshot/screenshot for reference
37+
- Navigate to the new page URL
38+
- Take a snapshot/screenshot for comparison
39+
40+
3. **Identify visual differences** - Compare the two pages and note all differences:
41+
42+
- Layout and structure
43+
- Colors and backgrounds
44+
- Typography (fonts, sizes, weights)
45+
- Spacing and margins
46+
- Images and media
47+
- Interactive elements (buttons, links, forms)
48+
49+
4. **Fix each difference** - For each visual discrepancy:
50+
51+
- Identify the source of the difference (CSS, HTML structure, missing content)
52+
- Make the necessary changes in the XbyK project
53+
- Prefer fixing via CSS/styling over changing HTML structure
54+
- Implement retrieval of missing content dynamically from the database
55+
- Nothing can be hardcoded if it was dynamic in the legacy project
56+
57+
5. **Rebuild and restart** - After making changes:
58+
59+
- Verify the project builds without errors
60+
- Restart the XbyK application
61+
62+
6. **Verify the fix** - Use Playwright MCP to check if the difference is resolved
63+
64+
7. **Iterate** - Repeat steps 3-6 until both pages are visually identical
65+
66+
## Output format
67+
68+
When done, provide user with this exact output (without any additional text, but with replaced placeholder for limitations):
69+
70+
```
71+
# Migration Complete
72+
Page visual match adjustment has been successfully completed.
73+
74+
**Next steps:**
75+
- Review the changes to ensure everything looks as expected.
76+
- Continue migrating other pages by repeatedly running /migrate-page-widgets and /migrate-page.
77+
```

‎src/kx13-codebase-migration/claude-code/.claude/commands/migrate-page-widgets.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
description: "Migrate page widgets from KX13 to XbyK project"
3+
argument-hint: [pageName] [legacyPageUrl]
4+
allowed-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, AskUserQuestion, Skill, SlashCommand, mcp__kentico.docs.mcp__*, mcp__playwright-mcp__*
5+
---
6+
7+
You are tasked with the process of migrating the widgets and sections of Page Builder from the legacy project to the new one.
8+
9+
## Input Parameters
10+
11+
- **Page Name:** `$pageName` - The name of the page, which widgets need to be migrated (e.g., 'home', 'doctors').
12+
- **Legacy Page URL:** `$legacyPageUrl` - The URL of the page in the KX13 project (e.g., 'https://localhost:5001/en-us/home').
13+
14+
## Structure of the projects
15+
16+
Look at the file `../instructions/projects-structure.md` to understand the structure of both the legacy and new project.
17+
18+
## Important
19+
20+
When migrating a page, ensure that everything that was fetched dynamically from the database will still be dynamically fetched from the database. Nothing can be statically hardcoded in the new project if it was dynamic in the legacy project.
21+
22+
## Useful Documentation
23+
24+
- Use Kentico Docs MCP to read the following pages:
25+
- [Adjust your code and adapt](https://docs.kentico.com/guides/architecture/upgrade-from-kx13/adjust-your-code-and-adapt)
26+
- [Upgrade content retrieval code](https://docs.kentico.com/guides/development/upgrade-deep-dives/upgrade-content-retrieval)
27+
- [Content Retrieval](https://docs.kentico.com/documentation/developers-and-admins/development/content-retrieval)
28+
- [Content Retriever API](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api/content-retriever-api)
29+
- [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder)
30+
- [Widgets for Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder)
31+
- [Widget Properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties)
32+
- [Sections for Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/sections-for-page-builder)
33+
- [Section Properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/sections-for-page-builder/section-properties)
34+
- [Upgrade Widgets Introduction](https://docs.kentico.com/guides/development/upgrade-deep-dives/upgrade-widgets-introduction)
35+
- Use web fetch to read the following pages:
36+
- [Migration Tool README - Pages](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md)
37+
38+
## Migration Steps
39+
40+
1. Read all documentation links mentioned above.
41+
2. Check out how the legacy page looks like using the provided URL `${input:legacyPageUrl}` and identify all parts it consists of.
42+
3. Go through pages in the legacy project and identify the provided page `${input:pageName}`.
43+
4. When you know the page, research from which sections and widgets this page consists of or which it uses.
44+
5. If present, check how other widgets and sections are implemented in the new project.
45+
6. Migrate all the page builder widgets and sections identified in previous steps together with all their dependencies.
46+
7. When done with implementation, ensure that the new project builds successfully without errors and warnings. If not, fix the issues until none are present.
47+
48+
Whenever unsure about anything, use Kentico Docs MCP to search for relevant information.
49+
50+
## Output format
51+
52+
When done, provide user with this exact output (without any additional text):
53+
54+
```
55+
# Migration Complete
56+
Page builder widget migration from the legacy project to the new one has been successfully completed.
57+
58+
**Next steps:**
59+
- Review the changes to ensure everything looks as expected.
60+
- Continue with the /migrate-page prompt to migrate individual pages.
61+
```

0 commit comments

Comments
 (0)