Automated Search & Navigation to Graph Migration with Claude Code

A Claude Code plugin that scans your S&N codebase, applies Graph SDK transformations, and validates the result. Install once, run one command.

1. Why This Plugin Exists

The Graph SDK blog post on Optimizely World covers how to write queries with Optimizely.Graph.Cms.Query. If you have not read it yet, start there. It walks through Where(), SearchFor(), Facet(), and the rest of the API that replaces Search & Navigation.

What the blog post does not cover is the mechanical work of actually migrating a real codebase. A typical Optimizely solution has Search & Navigation calls spread across dozens of files. Some are straightforward Search<T>().Filter().GetResult() chains. Others are wrapped behind repository classes, injected through DI containers, or built up conditionally with .OrFilter() composition. Finding all of that, understanding the dependency graph, and rewriting it file by file takes time that could be spent on the parts of a CMS 13 migration that genuinely require human judgment.

The cg-migrate plugin handles the mechanical part. It is a set of Claude Code skills that scan your solution, apply the known API mappings from the Graph SDK blog post, flag the patterns that need human decisions, and validate the result against the compiler. You stay in control of architecture questions. The plugin handles the find-and-replace at scale.

2. Getting Started

Prerequisites

You need Claude Code installed and a .NET solution that currently uses the Search & Navigation (EPiServer Find) SDK.

Before running the migration, check out a dedicated branch with no pending changes. The solution should build cleanly and all tests should pass. This gives the plugin a clean baseline so it can distinguish migration-introduced errors from pre-existing issues.

Installation

Run these two commands in Claude Code:

/plugin marketplace add episerver/content-graph-sdk-migrations
/plugin install cg-migrate@content-graph-sdk-migrations

The plugin loads automatically on every subsequent Claude Code session. No configuration files to edit.

What Gets Installed

The plugin adds five slash commands to your Claude Code session:

Three Ways to Use the Plugin

You do not have to use all five commands. Pick the approach that fits where you are in your migration:

The rest of this post covers each approach in detail. If you just want to get started, skip to section 3 for the full pipeline or section 5 for one-off translations.

3. Running the Full Migration

The fastest way to migrate is /migrate-all. It orchestrates the entire pipeline in a single invocation:

/migrate-all --project path/to/YourSolution.sln

If you omit --project, the plugin searches for .sln files in the current directory.

What Happens

The command runs six phases sequentially:

Phase 1: Scan. Invokes /migrate-scan to discover all Find SDK usage, trace dependency graphs, and classify each pattern by complexity. If no migration targets are found, the command stops early.

Phase 2: Confirm. Presents a summary of what will be transformed automatically and what will require manual decisions, then pauses for your confirmation before making any changes.

Phase 3: Transform. Invokes /migrate-transform to apply all known API mappings, swap NuGet packages, and flag items for manual review.

Phase 4: Validate. Invokes /migrate-validate to build the project and attribute compiler errors to specific transformation rules. If errors are found, it automatically retries the transformation on the failed files for a second pass.

Phase 5: Build & Fix. Rebuilds the project and iteratively fixes remaining compiler errors that have clear automated solutions, such as CS0266 type mismatches, CS1061 missing members, CS0246 unknown types, and NuGet version conflicts. Errors that require business logic decisions are deferred for you to handle manually.

Phase 6: Report. Generates a comprehensive migration report at .cg-migrations/migrate-all/ that ties together the results from every phase: targets scanned, files transformed, errors fixed, and remaining manual items with prioritized next steps.

The final report classifies the migration status as Complete (all errors resolved), Partial (some errors remain), or Nothing to migrate (no targets found).

4. Scanning Your Codebase

If you want to inspect the migration scope before committing to a full run, or if you need to re-run just the scan phase, use /migrate-scan directly:

/migrate-scan --project path/to/YourSolution.sln

If you omit --project, the plugin searches for .sln files in the current directory.

The scan runs in four phases:

Phase 1: NuGet Detection. The scan parses .csproj files to find which projects reference EPiServer.Find packages and what versions they use.

Phase 2: Direct Reference Scan. Using regex patterns from a built-in registry of 50+ S&N API patterns, the scan locates every file that calls into the Find SDK. Each match is categorized by type (filtering, facets, sorting, search, DI registration, etc.).

Phase 3: Dependency Graph Tracing. This is where the scan goes beyond simple text search. It follows constructor injection, DI registrations, and wrapper class hierarchies up to 5 hops deep. If you have a SearchService that wraps IClient and a SearchController that injects SearchService, both get flagged as migration targets even though only SearchService contains direct Find API calls.

Phase 4: Complexity Classification. Every identified pattern gets one of three labels:

Scan Output

The scan produces a console summary with statistics and a detailed markdown report at .cg-migrations/migrate-scan/scan-report.md. The report includes every target file, the specific patterns found, the dependency tree, and the complexity breakdown.

5. Translating Individual Queries

For one-off translations or to understand how a specific pattern maps to the Graph SDK, use /migrate-map:

/migrate-map

Point it at a file or paste a code snippet. The skill applies 17 translation rules covering the full S&N API surface.

Before and After

var result = searchClient.Search<ArticlePage>()
    .For("chocolate cake")
    .InField(x => x.Title, 3.0)
    .InField(x => x.Summary, 2.0)
    .Filter(x => x.Category.Match("Dessert"))
    .Filter(x => x.IsPublished.Match(true))
    .TermsFacetFor(x => x.Category)
    .OrderByDescending(x => x.PublishDate)
    .Take(10)
    .Skip(20)
    .GetResult();

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate cake")
    .UsingField(x => x.Title, boost: 3)
    .UsingField(x => x.Summary, boost: 2)
    .Where(x => x.Category == "Dessert" && x.IsPublished)
    .Facet(x => x.Category)
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .Limit(10)
    .Skip(20)
    .IncludeTotal()
    .GetAsContentAsync();

The /migrate-map skill is useful for building intuition about the mapping rules before running a full transformation, and for handling files you want to review individually.

6. Transforming the Full Codebase

Once you have reviewed the scan report and understand the scope, run the full transformation:

/migrate-transform --project path/to/YourSolution.sln

You can optionally pass the scan report path if you have already run /migrate-scan:

/migrate-transform --project path/to/YourSolution.sln --scan-report .cg-migrations/migrate-scan/scan-report.md

How the Transform Works

The transform runs in six phases:

Phase 1: Decision Resolution. For every pattern classified as manual in the scan, the transform generates a decisions file at .cg-migrations/migrate-decisions.md. This file groups patterns and presents strategy options. The plugin pauses here and asks you to choose a strategy for each group before continuing.

Example decision groups and strategies:

Phase 2: NuGet Package Setup. Adds Optimizely.Graph.Cms.Query to the relevant projects and tracks the S&N packages for removal.

Phase 3: Code Transformation. Each file gets 13 transformation steps applied in sequence: namespace updates, DI registration changes, query entry points, full-text search, filtering, sorting, pagination, facets, projections, execution (all made async), result access patterns, manual pattern strategies, and cleanup of orphaned using statements.

Phase 4: Cleanup. Removes using EPiServer.Find statements that are no longer needed.

Phase 5: Build Validation. Runs dotnet build and auto-fixes common issues like NuGet conflicts and generic constraint mismatches (the Graph SDK requires where T : class, IContentData rather than just IContentData). Iterates up to 2 cycles.

Phase 6: Reporting. Generates a transform report at .cg-migrations/migrate-transform/transform-report.md with per-file results.

7. Validating the Result

After the transform completes, run validation:

/migrate-validate --project path/to/YourSolution.sln

The validation phase does more than just run dotnet build. It parses every compiler error, matches it against a built-in lookup table of known migration-related error signatures, and attributes each failure to the specific transformation rule that likely caused it.

Validation Output

The report separates errors into three buckets:

Each error includes the file path, line number, error code, message, and the likely cause with a suggested fix.

Example Error Attribution

CS1061 in SearchService.cs:42
  'IContentQuery<ArticlePage>' does not contain a definition for 'TotalMatching'
  Likely cause: Rule 11 (Result Access)
  Suggested fix: Add .IncludeTotal() to the query chain and access result.Total

After reporting, the validation skill offers to re-run /migrate-transform on just the failed files for a second pass (max 2 rounds). This catches cases where the first pass produced valid but incomplete transformations.

8. Full Workflow at a Glance

# 1. Check out a clean branch
git checkout -b feature/graph-migration

# 2. Run the full migration
/migrate-all --project src/MySolution.sln

# 3. Make decisions for manual patterns when prompted

# 4. Review the migration report
# (open .cg-migrations/migrate-all/*-migration-report.md)

# 5. Fix any remaining manual items and commit

That is the simplest path. If you need more control, the individual skills (/migrate-scan, /migrate-transform, /migrate-validate) can be run separately and repeated as needed. The decisions file and scan report persist between runs, so you can iterate without losing your choices.

9. What the Plugin Handles vs. What You Handle

Looking Ahead

The plugin's pattern registry will continue to grow as partners encounter additional S&N patterns during real-world migrations.

If you run into a Search & Navigation pattern that the plugin does not handle, the validation report will call it out. File an issue on the GitHub repository at episerver/content-graph-sdk-migrations so the pattern can be added to the registry.

Next Steps

1. Install the plugin with /plugin marketplace add episerver/content-graph-sdk-migrations
2. Run /migrate-all on your solution to migrate end-to-end, or start with /migrate-scan to preview the scope first
3. Review the migration report and fix any remaining manual items
4. Read the Graph SDK blog post to understand the API you are migrating to

Resources:

• Introducing the Optimizely CMS 13 Graph SDK (the companion blog post covering the Graph SDK API)
• Plugin Repository: episerver/content-graph-sdk-migrations

This guide is based on the cg-migrate Claude Code plugin for migrating Search & Navigation to the Optimizely Graph SDK. The plugin is actively maintained and the pattern registry grows with each release.