Moving content from a site with a messy legacy architecture into a modern Drupal structure is a migration where automated rules hold up as long as the source is consistent; beyond that point, interpretation and judgment are required. Roberto Peruzzo, Drupal and PHP developer at SparkFabrik, brought this case study to the stage at DrupalCamp Italy 20261 and DrupalCon Rotterdam 20262, showing how to tackle it with AI in a structured way, without turning the entire job over to a single prompt.
Roberto has been contributing to Drupal since roughly 2014 and works on several modules as a contributor and maintainer3. His perspective is that of someone who writes Drupal code every day at SparkFabrik. In his talk, he does not present a turnkey tool, but rather offers food for thought on how to tackle complex challenges like migration using AI.
His insights center around an approach that a software engineer immediately recognizes: SOLID principles as a design standard, breaking down the work into independent atomic skills, and delegating orchestration to dedicated agents. Each of these elements addresses a specific flaw of the more intuitive approach: asking a model to read the old site and output the new one in a single pass.

All this structure is justified by looking at where traditional automation breaks down. It happens when source data stops being uniform and begins demanding interpretation, or when content emerges that the initial analysis had not accounted for. At that point, the Migrate API, a solid tool for everything that can be described with a rule, starts requiring exceptions that multiply with every new edge case uncovered in the archive.
Why is a Drupal content migration such a tough problem?
The difficulty lies in interpreting the data, far more than in moving it. As long as the source is consistent, Drupal’s Migrate API provides a clear model: a source plugin reads rows from the origin system, a chain of process plugins transforms values field by field, and a destination plugin writes entities, revisions, and translations. Mapping tables record the relationship between source and destination IDs, and that tracking supports rollbacks, incremental updates, and controlled reruns.
In this model, every transformation is an explicit, repeatable rule declared in the migration definition. The same input always produces the same output, and a change to a rule can be verified by rerunning the migration on a subset of rows. The entire migration lifecycle, from source analysis to verifying imported content, relies on this predictability.

A typical legacy source breaks this predictability in many places. The first is the body field, which often contains embedded markup and layout: grids, inline styles, and shortcodes mix content with presentation. Then comes the structure: a content type created for news ends up, over the years, hosting events, press releases, and landing pages, while taxonomies degenerate into freeform lists of tags written in inconsistent ways. Finally, dates, authors, and references to other content often remain buried in the text rather than stored in dedicated fields. In a real migration project, almost nothing carries over untouched: content architecture, the media layer, multilingual handling, URLs, and frequently the frontend all change.

A particularly delicate scenario involves sites with a decoupled frontend, where part of the meaning lives in HTML snippets saved in fields and interpreted by the client, meaning that reading the database alone is not enough to understand what they represent. The new content model must map those fragments back to fields and components, yet no general rule can succeed without knowing the often undocumented conventions used to write them.

Component mapping also takes multiple shapes. A source component can correspond to a destination one (1:1), multiple components can merge into one (N:1), one can split into several (1:N), some disappear without successors (1:0), and others emerge without a predecessor (0:1). Each pattern requires different process logic. Every exception uncovered along the way adds custom plugins, nested conditions, and special cases, eventually making the rules unmanageable. These are mapping pain points that every migration to Drupal must plan before writing code.

This is where AI becomes tempting. A language model can read unstructured content and propose a structure: for example, recognizing that a paragraph contains a date, that an HTML table describes team members, or that a link points to content that should become an entity reference. The destination is an explicit content model with declared types, fields, and relationships. The obvious move is feeding source and content model into a single prompt and asking it to output the result.
The limits of a single prompt: instability and costs
In his talk, Roberto states bluntly that a monolithic approach based on a single AI prompt fails quickly due to instability and high costs. Both symptoms stem from specific mechanisms, familiar to anyone who has worked with language models on real production volumes.
The first concerns the context window. A single prompt must simultaneously hold the instructions for every transformation, the destination schema, examples clarifying ambiguous cases, and the node content. Every rule added for an edge case takes up space and competes with others for the model’s attention: instructions buried in the middle of the prompt end up carrying less weight, and behavior on previously working cases shifts without anyone touching them.
The second is non-determinism. Given identical input, LLM output can vary across runs, even with conservative sampling parameters. On a single node, this is an annoyance; across an entire archive, it means the same source pattern gets transformed in different ways, and the inconsistency only surfaces downstream when an editor notices that two structurally identical articles have fields populated differently. On top of that come hallucinations: plausible values absent from the source, invented fields, and references to non-existent entities, all formally valid and therefore hard to catch without explicit checks.
The third mechanism combines token cost and error opacity. Instructions must be paid for on every call, so a prompt that grows to handle exceptions makes every transformation more expensive, even for the simplest nodes. If a single detail of the output is wrong, the entire call must be rerun, without any way to isolate which instruction caused the drift. Adjusting the prompt for one case can break another that was already working: the classic regression issue of an untested system, compounded by the fact that the behavior cannot be inspected in any source code.
An external factor amplifies all three problems: requirements change while the migration is underway. It is common for the rationalization of destination components, originally meant to trim down a bloated set of bundles into a manageable catalog, to reopen when edge cases overlooked during initial analysis surface, causing the catalog to expand once more. The scope grows, the content model updates, and every update invalidates part of the work already done.

An approach that packs all analysis into a single phase and all transformations into a single call assumes stable requirements. When the content model changes, the prompt must be rewritten and the archive reprocessed from scratch, in a loop that keeps resetting to the starting line without ever converging.
Lined up together, these symptoms describe a component with too many responsibilities concentrated in one place, changes that break other parts, and zero ability to test in isolation. Software engineers know this as a god class, and they also know the principles created to dismantle it.
Reading SOLID principles into a system of skills and agents
A monolithic prompt that migrates an entire archive is like a class that validates, transforms, persists, and logs everything on its own: it works while cases are few, then every modification becomes a risk. This is the starting point for Peruzzo’s proposal: an engineered migration framework based on SOLID principles, atomic breakdown into independent skills, and orchestration handled by dedicated agents.
When the design units are skills and AI agents, SOLID principles can be interpreted as follows:
- Single responsibility: a skill performs only one transformation, such as normalizing a date format or extracting a reference to other content from a text field, and changes for only one reason.
- Open/closed: a new case emerging in the source is handled by adding a skill, without rewriting existing ones or reconsidering previously validated transformations.
- Liskov substitution: this is the principle least directly applicable, as Roberto openly notes on stage. Skills are not interchangeable with one another, because each answers a different question. Substitution happens inside the individual skill, which queries a Drupal 7 or Drupal 8+ source while honoring the exact same contract. The agent calling it does not need to know which variant executed.
- Interface segregation: each agent receives only the skills and context it actually needs; an agent classifying content does not need instructions for rewriting markup, keeping the per-call context compact.
- Dependency inversion: orchestration depends on the skill’s contract rather than on the specific model, which remains replaceable whenever a more suitable or cost-effective one emerges.

This same insight is shared elsewhere as well. At DrupalCon Europe 2026, Len Swaneveld described clean code and architecture as a form of context engineering and a safeguard against LLMs going off track, since a model reasons only on what it sees and guesses the rest4. A system broken down according to SOLID minimizes what the model must guess, because every call gets a narrow task and an explicit contract.
SOLID also has a limitation worth stating clearly. Separating responsibilities does not make an LLM-based skill deterministic on its own: a skill extracting a date from freeform text can still fail, and in non-reproducible ways. However, it changes the error blast radius, narrowing it down to one transformation and one contract, making it verifiable via tests, repeatable across a sample, and fixable without touching the rest. What remains is defining the concrete unit to apply these criteria to, and how small it needs to be to stay useful.
Atomic skills: designing the minimal migration unit
An atomic skill is the smallest unit of capability that makes sense to execute on its own. It performs a single transformation, declares what it accepts and returns, and makes errors traceable where a single prompt leaves them opaque. Five properties distinguish it from a prompt snippet. It has declared inputs and outputs, with a schema validated by the orchestrator before and after execution, and it runs a single transformation. It is independent of other skills, because it does not assume an execution order or the state left behind by another skill. It is testable in isolation using real source samples selected to cover known patterns and edge cases. Finally, it can be selectively rerun: when it fails, only that specific skill is rerun on the affected elements, without incurring the cost of the rest.
Identifying the right skills requires a preliminary step before any automation: formalizing the manual process. Documenting the steps an expert takes to inspect source content, classify it, determine its destination, and verify the output yields the true inventory of transformations the project actually requires. Every step that can be expressed as a rule becomes code; every step requiring judgment over freeform text becomes a candidate for an LLM-based skill.
From this stems a design choice separating two distinct phases. AI handles source analysis: the agent decides which skill to invoke and interprets the results, while each skill executes SQL queries that, for a given database, always return identical data. Content migration itself remains deterministic code, following the tradition of Migrate API process plugins, which are already, by design, functions with predictable inputs, outputs, and behaviors.
HTML snippets follow this same rule. The code breaks them down by traversing the DOM and assigns each fragment a deterministic UUID, ensuring reruns do not duplicate content. Liskov substitution (one of the SOLID principles) comes into play in a more targeted spot: inside analysis skills. The exact same skill responds with the same contract on a Drupal 7 or Drupal 8+ source (and now also WordPress), without the rest of the system noticing.

The destination matters just as much as the source. As we discussed when analyzing what once seemed excessive in Drupal and now serves AI agents, three architectural choices that seemed over-engineered in 2015 now allow an AI agent to operate on a site with proper governance: structured content, API-first architecture, and strict configuration management.
All three make content and configuration explicitly readable. In a migration, the output of each skill is validated against a content model declared in Drupal configuration, not against an implicit expectation in a prompt. Content types, fields, cardinalities, and constraints are exported as version-controlled files. This guarantee derives from the Drupal structured content model and turns validation into schema comparison rather than subjective assessment.
From a qualitative perspective, the two approaches compare as follows:
| Dimension | Monolithic prompt | Orchestrated atomic skills |
|---|---|---|
| Context per call | Contains rules, schema, examples, and content all at once | Contains only the contract and context for the single transformation |
| Output reproducibility | Varies between runs and between nodes sharing the same pattern | Guaranteed for deterministic skills, bounded and testable for LLM-based ones |
| Error isolation | Cannot identify which instruction caused the discrepancy | Error is tied to a specific skill and its contract |
| Rerun cost | Must rerun the entire call across every affected node | Reruns only the failed skill on the affected elements |
| Evolution with new cases | Prompt is modified, introducing regression risks | A skill is added, leaving validated skills untouched |
A well-designed skill does one thing and does it verifiably. However, a component is needed to decide which skill to call, in what order, and what to do when one fails. That role belongs to dedicated agents.
Dedicated agents and orchestration: architecture and trade-offs
The orchestrator decides which skill to apply to which content, in what order, and with what error-handling policy: it represents the third pillar of Peruzzo’s framework. In multi-agent systems, the most natural breakdown follows responsibilities: one agent analyzes the source and classifies cases, one or more agents apply transformation skills, and a dedicated agent or validation step checks the result against the content model. The skills and agent used in the project are public in the drupal-migrate plugin in the sf-agents-harness repository by SparkFabrik.

Two patterns lend themselves well to this architecture. In the orchestrator-worker pattern, a central agent receives the content, activates the necessary workers, and collects their results: it handles heterogeneous content effectively and routes edge cases to specific skills, but concentrates logic and token consumption in the coordinator. The sequential pipeline passes each piece of content through fixed stages: from classification, to transformation, to validation. This makes it more predictable, easier to monitor, and straightforward to rerun stage by stage, but it adapts less easily when source records demand divergent flows. Both models can coexist, using a pipeline for known patterns and an orchestrator for edge cases that resist classification.
Regardless of pattern, orchestration must manage state and idempotency: rerunning a skill must not duplicate content or overwrite manual corrections. The Migrate API source-to-destination ID tracking provides the natural foundation, recording what has already been imported and with what outcome. As a general best practice, uncertain cases should be escalated to a human, complete with the proposed classification and rationale, rather than forced into a plausible structure.
The interface between agents and systems also warrants a deliberate choice. MCP (Model Context Protocol) is an open protocol standardizing how AI models and agents connect to external tools and data sources (Roberto is also a maintainer of the Drupal MCP Client module5). In an architecture like this, MCP is a concrete option for exposing source reading and Drupal writing to agents as tools with well-defined permissions: for example, read-only access to the legacy database and write access restricted strictly to import operations.
Costs must be accounted for from the start. More components need to be designed, versioned, and monitored, each with its own failure modes. The orchestrator also consumes model calls, shifting part of the token savings gained by slimming down individual skill contexts over to coordination. Skill contracts require upfront source analysis demanding expert time, and over-fragmentation merely moves complexity from the prompt into a dependency graph. Not every migration warrants this architecture; a clean, regular source remains a job for the traditional Migrate API, where AI would only add cost and uncertainty.
Roberto’s talk draws on a real project currently running in production, but does not aim to set a formal benchmark. An experiment like this should be evaluated against its own metrics: the percentage of outputs from each skill passing validation, rerun count per skill, token consumption distribution between skills and orchestrator, and the share of cases routed to human review. These are standard observability metrics in agentic workflows, as we discussed when talking about AgentOps, and they highlight where to intervene: a frequently failing skill should be broken down or made deterministic, while an overly costly orchestrator should be simplified.
Finally, it is worth remembering that available models and tooling evolve faster than the duration of an enterprise migration project. Separated responsibilities, explicit contracts, and isolated validation remain resilient when the underlying model is swapped out, a transition made smooth by dependency inversion.
Where to start when engineering a migration
An experiment like this is set up well before connecting to any model. The sequence mirrors the logical flow of the framework, from source analysis to output validation:
- Inventory the transformations required by the source, formalizing the manual process before drafting any prompts.
- Separate deterministic transformations, which remain migration rules and process plugins, from interpretive ones that justify using an LLM.
- Give each skill an input and output contract, alongside a set of real source samples to test against.
- Assign agents by responsibility and clearly define when a case must escalate to a human.
- Validate every output against the content model declared in Drupal configuration before executing any final import.
The first step delivers value even if the experiment ends there, because an inventory of transformations makes the migration estimable and reveals which components genuinely require AI. Roberto Peruzzo’s talk on Drupal migrations with AI should be taken as an invitation to handle prompts with the same rigor reserved for code: contracts, tests, separated responsibilities, and a human in the loop for ambiguous cases.
If you are planning a replatforming or migration to Drupal, our Drupal team starts with source analysis and an inventory of transformations. That is how we estimate scope and decide where Migrate API rules suffice and where AI is required.
If you want to apply this same methodology beyond migrations, using explicit skill contracts, agents divided by responsibility, and human review for uncertain edge cases, SparkFabrik’s AI Native Journey is our program for guiding teams through adopting AI across their engineering workflows.
Notes and sources
Recording of Roberto Peruzzo’s talk at DrupalCamp Italy 2026. (source: www.youtube.com/watch?v=JMwC9HRYcGo) ↩︎
Recording of Roberto Peruzzo’s talk at DrupalCon Rotterdam 2026. (source: www.youtube.com/watch?v=kPHC6m8FB2o) ↩︎
“Projects maintained Ai dev recipe Google Shopping Feed Imagecache Cron Flush Iubenda Integration Lara Translate Provider MCP Client Panther Search API Typesense Typesense RAG recipe” (source: www.drupal.org/u/robertoperuzzo) ↩︎
According to Len Swaneveld at DrupalCon Europe 2026, clean code and architecture are a form of context engineering and a safeguard against LLMs straying off course, since an LLM reasons only on what it sees and guesses the rest. Three feedback sources keep code clean: human review, static analysis with PHPStan and PHPCS, and testing with code coverage and CRAP score. (source: Guardrails, AI migrations, MCP: what we brought to Rotterdam) ↩︎
MCP Client module page on drupal.org, maintained by Roberto Peruzzo. (source: www.drupal.org/project/mcp_client) ↩︎
Video source
This article is based on the video “163 → 42: smantellare e riassemblare una migrazione Drupal con l’IA | Roberto Peruzzo”.














