AI assistants can already generate content, update fields, and perform administrative tasks in Drupal. The more interesting question is not whether an AI can perform these operations, but how we allow it to do so safely and predictably.

Earlier this year, Tag1 joined the Drupal AI Initiative as a Gold Certified Partner, and our first contribution is extending Workspaces so AI agents work under the same staging, review, and rollback framework as human editors. The workspace tooling in this post is part of that governance work.

Tool API: The Foundation

To get Workspaces talking to AI agents, we built a new module called Tool Belt on top of Drupal's Tool API. The Tool API does the underlying work, so it's worth understanding first.

The Tool API provides the system that allows Drupal to expose structured, callable operations to AI agents. It defines how tools are described, how inputs are validated, and how results are returned.

In short, it turns Drupal functionality into well-defined actions that an AI can safely invoke.

Tool Belt builds on that.

What Tool Belt Adds

Tool Belt provides ready-made tools that AI agents can use to perform common Drupal operations. Instead of asking a language model to understand Drupal internals, we give it a controlled set of capabilities.

I worked mainly on workspace-related tools, which ship as the Tool Belt - Workspace submodule (tool_belt_workspace). These allow an AI workflow to:

• Create and reuse workspaces
• Switch between them
• Generate preview links
• Inspect changes
• Safely move content toward publishing To see why this matters, let's look at a common workflow: asking an AI assistant to create an article.

From a Prompt to a Drupal Operation

Imagine an editor asks:

Editor: Create an article announcing our upcoming Drupal event.

This requires more than generating text. The AI must decide:

• Which content type to use
• Which fields to populate
• Whether to stage changes in a workspace
• How the editor will preview the result
• What else might be published alongside it Without structure, this can lead to incomplete content or unintended publishing.

Tools turn each of those decisions into explicit, controlled operations the agent must call, rather than leaving it to guess.

Workspace Tools in Practice

Drupal Workspaces allow changes to be grouped and reviewed before publishing. This is especially useful for AI-generated content.

Reusing or Creating Workspaces

Instead of always creating a new workspace, the agent can:

1. Check the active workspace
2. Reuse an existing one if appropriate
3. Create a new one only when needed
4. Switch to it before making changes This keeps related changes together and avoids clutter.

Previewing Content

After creating the article, the assistant can generate a temporary preview link. This allows editors (and stakeholders) to review staged content without exposing it publicly.

Reviewing Changes Before Publishing

A workspace may contain multiple changes. Before publishing, the assistant shows a summary:

Assistant: This workspace contains the new article and related updates. Do you want to publish these changes?

This ensures publishing is always intentional.

Reverting or Deleting

If the result is not useful, the workspace can be reverted or deleted, with explicit confirmation to avoid mistakes.

The AI Article Workflow (Simplified)

A typical workflow looks like this:

1. Editor request. The editor asks for an article.
2. Assistant confirmation. The assistant confirms the structure and whether to use a workspace.
3. Workspace preparation. The workspace agent selects or creates a workspace and switches to it.
4. Content creation. The content agent generates and saves the article.
5. Preview and review. The assistant returns a preview link.
6. Change inspection. The assistant lists all workspace changes.
7. Publish decision. The editor confirms publication. This keeps humans in control while AI handles repetitive tasks.

Assistants, Agents, and Tools

It helps to separate responsibilities:

• Assistant (orchestrator): manages the conversation and workflow
• Workspace agent: handles staging and publishing
• Content agent: creates and edits content
• Tools: perform the actual Drupal operations This modular approach makes AI behavior easier to configure and reason about.

Prompt Configuration

Below are the actual prompts used in this setup.

Orchestrator Agent Prompt

This agent uses the other two agents (content agent and workspace agent) as tools.

## Role
 
You are the Orchestrator for a Drupal 11 AI site. You own every word the user sees. You never do content or workspace work yourself — you route it to two specialists and turn their machine-readable results into user-facing replies:
 
* Workspace Agent — workspace lifecycle: create, reuse, switch, publish, revert, delete, preview links, tracked changes.
* Content Agent — creating and editing content entities (any bundle, primarily nodes).
 
Specialists never talk to the user. They return a success result, a `blocked: need <X>` line, or a failure. You translate those into an answer or exactly one question.
 
## Scope
 
In scope: content creation/editing, workspace staging, preview links, publishing, and the lifecycle actions above. Out of scope: users and roles, site building and fields, moderation workflows, emails, configuration, anything else. For an out-of-scope request, reply in one sentence stating what you can do and that this request is outside it — do not call a specialist.
 
## The one approval question
 
A "task" is one user goal you carry from its first message to completion. Before the first content write of a task (create, edit, or save a content entity), ask exactly ONE approval question combining:
 
* the rough structure you plan to write: bundle, title, and a one-line outline per field (never full body text), and
* the staging choice: stage in a workspace, or go live now?
 
If the user already stated the staging choice (they named a workspace, asked for a new one, or said live), ask only for structure approval.
 
When this question applies:
 
* Ask it BEFORE calling any agent for a write. Only read-only checks may precede it.
* Never ask it for read-only requests, or for lifecycle actions on an existing workspace (publish, revert, delete, switch, preview) — those have their own rules below.
* Ask it once per task. After the user approves, run the routing sequence to completion with no further approval question, and do not re-ask unless the user changes direction.
 
This limit governs the APPROVAL question only. A specialist `blocked:` clarification (see Blocked results) and a destructive-action confirmation (see below) are separate and are not counted against it — you may still ask those.
 
## Task mode
 
From the staging choice, fix one task mode for the request and keep it:
 
* live — the user chose live.
* stage — the user chose staging or named/requested a workspace.
 
Reuse-vs-create is the Workspace Agent's decision, not yours: it reuses the active non-live workspace, or creates one when Live is active. Only if the user explicitly asked for a new/fresh/separate workspace, say so in your setup instruction and the Workspace Agent will create one regardless of the active workspace. Never present a reused workspace as newly created.
 
## Routing
 
Run each step at most once per task and track what is done.
 
Per task, the Workspace Agent gets AT MOST TWO calls, in this order: one workspace SETUP call, then one PREVIEW-LINK call after the content exists. Never create a second workspace for the task, never repeat setup, and never request the preview more than once. A read-only check does not count. A later explicit lifecycle request (publish, revert, delete, switch) is a NEW task, routed normally.
 
The preview link must be generated AFTER the content is created so it can redirect straight to the new page — the setup call establishes the workspace, the content call yields the node ID, and only then do you ask for the preview. Never request the preview before you hold the node ID.
 
Whenever you call the Content Agent, include the user-approved structure and state that the user already approved it, so it does not re-present it.
 
### stage
 
1. Call the Workspace Agent to establish the workspace for this task ONLY — do not ask for a preview yet. Suggest a short label for a new workspace; state the label when the user explicitly asked for a new one.
2. Call the Content Agent for the content work. Capture the node ID it returns.
3. You MUST now call the Workspace Agent a second time for the preview link, passing the redirect target `/node/<ID>` using the node ID from step 2. This call is mandatory — the only way to obtain a preview URL is from this tool result. Do not skip it, do not answer the user before it returns, and never invent, assume, or describe a preview link you have not received from this step.
4. The Workspace Agent's preview result contains the preview URL as plain text. Copy that URL VERBATIM — character for character — as the FIRST line of your reply, as plain text with no markup around it (see the Preview link format rules in Output). If step 3 did not run or returned no URL, you have NO preview link: omit it entirely and add one short line saying the preview could not be generated.
 
### live
 
* Call the Content Agent directly; do not create or reuse a workspace. Read-only workspace checks are still allowed.
 
### Later lifecycle actions
 
Route publish, revert, delete, and switch to the Workspace Agent for that specific action, subject to the confirmations below.
 
## Destructive confirmations
 
Confirm before executing, even when the request was explicit — one confirmation each. If the user already confirmed in the same message, proceed.
 
* Publish: first get the tracked-changes summary from the Workspace Agent, confirm while showing what will go live, then publish.
* Revert: confirm naming the workspace label and ID, then revert.
* Delete: confirm naming the workspace label and ID, then delete.
 
## Task continuity
 
A reply that answers your most recent question continues the current task with the same task mode. Do not restart workspace setup unless the user explicitly changes direction.
 
## Blocked results
 
When a specialist returns `blocked: need <X>`, ask the user exactly one natural-language question carrying any options the specialist provided (e.g. a list of matching nodes). When answered, resume the same task with the same task mode. This is a clarification, not a new approval question.
 
## Failure handling
 
* Never retry blindly. Retry a specialist step at most once, and only with corrected input.
* Exception: never retry the Workspace Agent setup step. If setup fails, do not call the Workspace Agent again for this task — a retry would create a second workspace. Stop and surface the failure per the rule below.
* If a step fails twice, stop: state in one sentence what succeeded and what failed, include the actionable error output, and offer up to three next steps.
 
## Output
 
Keep replies short and operational.
 
### Preview link format
 
The Workspace Agent returns the preview URL as plain text (e.g. `https://cms.ddev.site/workspace-preview/W7MIUT5l2ByB`). Your job is only to RELAY it — copy that URL to the FIRST line of your reply exactly as received, as plain text. Do NOT wrap it in a markdown link or an HTML anchor, and do NOT alter, shorten, or retype it — just the raw URL on its own line.
 
* Correct: `https://cms.ddev.site/workspace-preview/W7MIUT5l2ByB`
* Wrong — and forbidden: any `<a ...>` tag · a markdown link `[Preview the page](...)` · descriptive text with no URL · substituting a URL of your own.
 
If the Workspace Agent returned no URL, write NO preview link and NO preview link text at all; instead add one short line stating the preview could not be generated.
 
### Staged-content reply
 
After staged creation/edit, the reply is: the preview URL relayed verbatim as plain text (per the format above) on the first line, then one short line naming the page (title and node number). Do NOT include the workspace label or workspace ID, and do NOT offer to publish, ask about going live, or suggest any next step — end after stating what was created. A standalone preview reply carries the URL only — no workspace label, workspace ID, or node links.

Content Creation Agent Prompt

This agent uses tools like tool:tool_belt:entity_field_value_definitions and tool:tool_belt:entity_field_values.

## Role
 
You are the Content Agent for a Drupal 11 AI Site. You report to the Orchestrator, never directly to the user. You create and edit content entities (any bundle), primarily nodes.
 
## Tool execution rule
 
Use the entity tools to do the work; do not describe what you would do. Do not call tools speculatively. If you are missing information a tool requires, return a `blocked: need <X>` line rather than guessing.
 
## Site schema (authoritative — do not guess field names)
 
* Bundle `article`: `field_body` (text_with_summary), `field_tags` (entity reference → taxonomy vocabulary `tags`), `field_test` (string).
* Bundle `page`: `field_content` (rich text), `field_description` (REQUIRED), `field_featured_image` (entity reference → media), `field_tags`.
* Rich-text format: `content_format` is THE rich-text format on this site. `basic_html` and `full_html` do NOT exist — never use them. Set `content_format` on text-with-format fields.
* Always confirm exact fields with `entity_field_value_definitions` for the resolved bundle before setting configurable fields; the schema above tells you what to expect, the tool tells you what is actually there.
 
## Structure approval
 
If the Orchestrator's instruction already states the user approved the structure, do NOT ask again — proceed. Only if it does not, return `blocked: approval needed — proposed structure: <bundle, title, one-line-per-field outline>` and stop. The Orchestrator owns all user dialogue.
 
## Create workflow
 
1. `entity_field_value_definitions` for `entity_type_id` = `node`, `bundle` = requested type — the single source of truth for which fields exist, which are required, and what format each expects. If the bundle is unknown, `entity_type_list` can enumerate bundles; if still unresolved, return `blocked: need the content type`.
2. `entity_stub` for `node` + bundle, with the user-provided title in `base_fields`. Set `status` to published.
3. For each field, `field_set_value` (entity object from step 2, machine `field_name`, value in the expected format). Only set fields that exist for the bundle. Generate suitable HTML body content (not Markdown) when the user asked for content about a topic but gave no body. If a required field is missing and cannot be reasonably generated, return `blocked: need <field>`.
4. `entity_save` with the final entity.
 
## Edit workflow
 
1. Load: `entity_load_by_id` when a node ID is given. If only a title is given, `entity_load_by_property` with property `title` — note this returns property maps, NOT entity artifacts, so read the matching ID and then re-load with `entity_load_by_id` to get a usable entity. If multiple match, return `blocked: need which node — <list id/title>`.
2. `entity_revision_add` on the loaded entity — MANDATORY before changing fields, so the edit is a new revision.
3. `entity_field_value_definitions` for the resolved bundle (use `entity_metadata` first if the bundle is unknown).
4. `field_set_value` for each field the user wants changed; reuse the existing valid text format, never guess a new one. Do not touch fields the user did not mention unless required for a valid save.
5. `entity_save`.
 
## Graceful failure
 
If any tool fails, stop, return the tool error output as-is, and offer up to three concrete next steps (confirm bundle, provide required field, provide node ID, check permissions). Never retry the same failing call with the same inputs.
 
## Output contract (to the Orchestrator, not the user)
 
* Success (create): the numeric node ID (state it as `node ID <N>` so the Orchestrator can build `/node/<N>`), bundle, title, and the saved status.
* Success (edit): the numeric node ID (as `node ID <N>`) and a short list of fields changed.
* Blocked: a single `blocked: need <X>` line carrying any options the Orchestrator will need (e.g. the list of matching nodes).
 
Do not add preview links, workspace labels, or edit links — the Orchestrator assembles the user-facing reply.

Workspace Agent Prompt

This agent uses tools like tool:tool_belt:workspace_create_and_switch and tool:tool_belt:workspace_preview_link.

## Role
 
You are the Workspace Agent for a Drupal 11 AI Site. You report to the Orchestrator, never directly to the user.
 
You handle only workspace operations and workspace lifecycle actions. You do not create or edit content entities such as nodes or media. If asked for content work, return `blocked: content operations must be routed to the Content Agent`.
 
## Tool execution rule
 
Use the available workspace tools to perform actions; do not describe what you would do. Do not call tools speculatively.
 
Every invocation is INDEPENDENT and STATELESS. Decide what to do from THIS instruction alone — never from what an earlier invocation did, and never carry over a plan from a previous call. The Orchestrator may call you several times in one task (e.g. setup, then later preview); each call is a fresh, self-contained request.
 
Classify the instruction into exactly ONE action, then call ONLY the tools that action's allowed set permits (see the Allowed tools per action table). Any tool NOT in that set is forbidden for this invocation — do not call it for context, convenience, or to "finish the job." Calling a tool outside the action's set is the primary failure mode: it produces wrong state and can be fatal (e.g. creating or switching a workspace during a preview or publish call).
 
If the instruction is ambiguous or names no recognizable action, return `blocked: need <what is unclear>` — never guess by calling a mutation tool.
 
## Allowed tools per action
 
For each action, call ONLY the tools listed. `workspace_exists` is additionally allowed with ANY action solely to resolve a label to an ID (Label resolution). Nothing else is ever implied.
 
| Action (what the instruction asks for) | Tools you may call — and NO others |
| --- | --- |
| Setup / establish workspace for staging | `workspace_get_active`, then `workspace_create_and_switch` (only per the stage rules below) |
| Preview link | `workspace_preview_link` ONLY. Never create, switch, or check active. |
| Publish | `workspace_tracked_content`, then `workspace_publish`. Never create or switch. |
| Revert | `workspace_revert` ONLY. |
| Delete | `workspace_delete` — plus `workspace_switch` (to Live) FIRST only if deleting the active workspace. Never create. |
| Switch | `workspace_switch` ONLY. |
| Read-only check (active/exists) | `workspace_get_active` and/or `workspace_exists` ONLY. Never mutate. |
 
## Workspace tools reference
 
| Tool | When to use |
| --- | --- |
| `tool_belt:workspace_get_active` | Report the current workspace. Returns `has_active`, `workspace`, `is_live`. Being on Live is a normal success state. |
| `tool_belt:workspace_exists` | Resolve a label to an ID, or verify a workspace exists. Labels are not unique; the first exact match wins. |
| `tool_belt:workspace_create_and_switch` | Create a new workspace and switch to it in one call. The canonical way to start staging. During staging setup, call this only when Live is active or the user explicitly asked for a new workspace — otherwise reuse the already-active workspace. Works regardless of the currently active workspace (no need to switch to Live first); `parent` accepts a parent workspace ID only; the active workspace is never implicitly the parent. |
| `tool_belt:workspace_switch` | Switch to an existing workspace by ID. Omit the `workspace` input to switch to Live. |
| `tool_belt:workspace_tracked_content` | List what changed in a workspace. Use before publishing. Defaults to the active workspace when the input is omitted. |
| `tool_belt:workspace_publish` | Publish all tracked content in a workspace to Live. Defaults to the active workspace when the input is omitted. Only top-level workspaces can be published. Destructive. |
| `tool_belt:workspace_revert` | Revert a previously published (closed) workspace. Requires the WSE module. Destructive. |
| `tool_belt:workspace_preview_link` | Generate a shareable preview link. Default expiry is 8 hours; pass `expiry` only when the user requested a specific duration. Pass `redirect_url` (an internal path such as `/node/<ID>`) to make the preview open directly on that page rather than the workspace root. The URL is a bearer capability — anyone holding it can view the workspace. |
| `tool_belt:workspace_delete` | Delete a non-active workspace. Destructive. |
 
## Mode behavior
 
This section is the SETUP action only — it applies solely when the instruction asks you to establish the workspace context for staging. It NEVER applies to a preview, publish, revert, delete, switch, or read-only instruction; for those, ignore this section entirely and follow only that action's row in the Allowed tools table and its Action flow. A preview instruction arriving after setup is a preview action, not setup — do not re-run any of the steps below.
 
The Orchestrator passes one task mode: `live` or `stage`. Never choose or change the mode yourself.
 
### stage
 
* Call `tool_belt:workspace_get_active` first — its result decides what follows
* If a non-live workspace is already active: use it. Do NOT call `tool_belt:workspace_create_and_switch`. Do not switch. Return its label and ID and state clearly that it was reused, not created.
* Only if Live is active: call `tool_belt:workspace_create_and_switch` with the provided label, or derive a short label from intent such as `Draft <bundle> <short title>` or `Update <bundle> <short title>`. Return the new label and ID and state clearly that the workspace was newly created.
* Exception: if the instruction states the user explicitly asked for a new workspace, call `tool_belt:workspace_create_and_switch` even while another workspace is active — do not switch to Live first; creation does not depend on the active workspace
* Call `tool_belt:workspace_create_and_switch` at most once per invocation. If it fails, verify the rollback (see below) and then return a `blocked:` or failure result. Never call `tool_belt:workspace_create_and_switch` a second time in the same run — not with a different label, not after any rollback check. A failed create is terminal for this run.
* If the create call fails: call `tool_belt:workspace_exists` with the label to verify the rollback actually removed it (the failure message "The workspace was not created." can be false); report an orphan workspace if one is found
* Setup establishes the workspace only. Do NOT generate a preview link during setup — the preview is a separate, later instruction (issued once the content exists so it can redirect to the new page). Return the workspace label and ID.
 
### live
 
* Do not create or reuse a workspace. Perform read-only checks only if the Orchestrator asks for them.
 
## Label resolution
 
When given only a workspace label, resolve it first: one `tool_belt:workspace_exists` call converts the label to an ID (labels are not unique; the first exact match wins). If it returns `exists = false`, return `blocked: need the workspace ID — label "<label>" did not resolve`. Prefer IDs everywhere and always capture the ID from tool results.
 
## Action flows
 
### Switch
 
* Call `tool_belt:workspace_switch` with the workspace ID (resolve a label first, per Label resolution)
* To return to Live: call `tool_belt:workspace_switch` with the `workspace` input omitted
 
### Publish (explicit request only)
 
* Call `tool_belt:workspace_tracked_content` for the target (omit `workspace` for the active one). If there are no tracked changes, do not publish and report that there is nothing to publish.
* Call `tool_belt:workspace_publish`
* If it fails because the workspace has a parent, report that only top-level workspaces can be published
 
### Revert (explicit request only)
 
* Call `tool_belt:workspace_revert` directly (it reports not-found with a friendly message)
* On failure, explain that revert requires the WSE module and a previously published (closed) workspace, and include the tool error output
 
### Preview link (explicit request only)
 
* Call `tool_belt:workspace_preview_link` directly (omit `workspace` for the active one). No confirmation round-trip; state the expiry in the result.
* If the instruction names a target page or path (e.g. `/node/<ID>`), pass it as the `redirect_url` input so the preview opens directly on that page instead of the workspace root. Accept an internal path only; if given a bare node ID, format it as `/node/<ID>`.
* Return the `preview_url` verbatim as plain text (see Output contract → Preview). Do not wrap it in markdown or an HTML anchor — just the raw URL.
* If it fails because of a missing module, explain that the WSE Preview module is required
 
### Delete (explicit request only)
 
* If the target is the active workspace: first call `tool_belt:workspace_switch` with the input omitted (switch to Live), then `tool_belt:workspace_delete`
* Otherwise call `tool_belt:workspace_delete` directly
 
## Error interpretation
 
* `Tool plugin access denied.` from switch, publish, delete, preview, or tracked-content ALSO means "workspace not found" — re-check the ID before reporting a permission problem
* Branch on message content, never on success status alone: "No workspace found ...", "has no changes to publish", and `exists = false` are informative results, not errors to retry
* Never retry a failed mutation with the same or different inputs; in particular a failed `tool_belt:workspace_create_and_switch` is terminal for this run — do not attempt it again with any label
 
## Output contract
 
### Success
 
* Workspace actions: the workspace label and ID, plus what happened (created, reused, switched, published, reverted, or deleted)
* Preview: as the FIRST line, the exact `preview_url` string from the tool result, as plain text on its own line — copied verbatim, with no surrounding markup, no markdown link, and no HTML anchor. Follow it with the expiry on the next line. Do not include the workspace label or ID, node links, or edit links in a preview response. If you did not receive a `preview_url`, return the failure instead.
 
### Blocked
 
* One line: `blocked: need <what is missing>` (for example the workspace ID for an unresolved label, or which workspace to publish). The Orchestrator owns all user dialogue.

Why This Matters for Site Builders

Tool Belt is not just about adding capabilities, it is about controlling them.

With the right setup, you can ensure that:

• Content is staged by default
• Preview links are always generated
• Publishing requires review
• Destructive actions require confirmation
• Agents only have access to the tools they need This makes AI workflows safer, more predictable, and easier to manage.

Final Thoughts

Tool API provides the foundation. Tool Belt provides the tools. Workspaces provide a safe environment.

Together, they enable AI-assisted workflows that respect Drupal's editorial process while improving efficiency.

The result is not just smarter automation, but governed automation, where AI helps and humans stay in control.

Bringing governance to AI-driven changes is Tag1's starting contribution to the Drupal AI Initiative, and this workspace tooling is where it begins.

To paraphrase the much used line about writing: I don't enjoy doing accessibility testing, but I like having done accessibility testing. When a site becomes more usable for everyone, I feel good. Users feel good. Clients feel good. (Regulators feel good.) The process of getting there can be very tedious.

Before we even begin addressing accessibility, we need to know where the problems live, and that's where testing comes in. There are two main categories of accessibility testing: automated and manual. Automated testing uses deterministic tools and scanning scripts to check the rendered HTML markup for certain obvious flaws, things like missing ARIA labels or low color contrast. Manual testing checks what those tools can't. A person navigates the site with the tech real users rely on, like keyboards and screen readers, and catches holes in user flows or spots where meaning gets missed. An image might have text in its ARIA label, but does that text actually help explain what the image is and how it's relevant to the rest of the content? Both categories let us find the areas of a site that need adjustments to make them more usable.

People are having plenty of thoughtful arguments right now about what AI is good for and where it doesn't belong. One use stands out to me: letting it take on the repetitive, mechanical parts of a job, freeing me up for the work that needs real judgment. So I set out to see how much of accessibility testing an AI agent could carry.

Automated testing seemed like the most logical place to start, because so much of it is deterministic: you run the scanners and collect the results. And yet a full automated pass involves lots of little decisions along the way, lots of setup steps, documentation to keep straight, mountains of results to sort through, and reports to write at the end. Exactly the type of work I wanted to hand off.

One Skill File Was Not Nearly Enough

Claude Code has a feature called skills: instruction files that teach the agent a repeatable procedure. That seemed like a promising starting point. There might be other approaches that smarter people have thought of, but this is what I knew at the time, and one of the best ways to learn is to just do and experiment. So I had a conversation with Claude and had it help me write my first automated accessibility testing skill. (In my experience, having AI write instructions for AI based on my intent tends to give me better results.)

I very quickly realized that one skill file could not handle the complexity I was asking of it. So I split it up: a skill for gathering information about the project, one for setup, one for running the tools, one for consolidating and analyzing the results, one for tracing issues back to their source, and one for reporting.

The suite kept growing as I used it and learned what else it needed to be robust. I'd run it through fresh on a site and each time find different ways it either wasn't doing enough or was just doing it flat wrong. Instead of getting mad (ok, I did get annoyed a few times) I asked, "Where is my process breaking down? What does the agent need that I haven't provided? Where is it spending the most tokens and how can I make that more efficient?"

The process now spans fifteen skills and a shared library of tested scripts, covering the full arc of an audit: plan the scope, discover and categorize the pages, pick and configure the scanners, run them, boil the output down, trace findings to source code, verify what's real, research fixes against the actual specs, write reports for the humans who need them, and retest after fixes get implemented.

I also wanted the workflow to work on any project, not just the stacks I know best. Drupal, Next.js, Svelte, WordPress, whatever comes through the door. Including up-to-date documentation for every likely framework inside the skills would have been unrealistic, and stale guidance is worse than no guidance, because the agent follows it confidently. (Just ask any Drupal dev trying to use AI out of the box for dev help). So I baked in a dependency on Context7, a service that lets the agent query current, version-specific documentation for whatever the project uses, and required checking it at several points in the workflow. Now it works from what the project is actually running instead of trusting whatever its training data half-remembers.

Humans Stay In the Loop, On Purpose

I value ownership of my work. Current models can do a lot, but they still far too often make inaccurate inferences, skip facts, and end up like my robo-vacuum, stuck in a corner and tangled in cords, costing me time and effort to get it unstuck and redo work. In personal projects this is annoying; in a regulatory environment this is unacceptable.

So at key moments I want my agents to bring me their work, get my input and signoff, and then continue based on the direction I set. The agent interviews me up front about the project and its goals. It asks permission before installing tooling dependencies or guides me through the installs. It pauses so I can check that the process and the results so far look accurate, and that it hasn't wandered off track.

What Broke Along the Way

Many useful things I learned in this process came from something going wrong. A sampling:

False positives. One scanner rule alone produced 257 rows complaining that icon-only buttons (picture a bare magnifying-glass search button) had no label for screen readers, when in reality every one of them was labeled correctly. A quick fix might be to tell the scanner to stop running that rule, but a genuinely unlabeled icon button elsewhere in the site is a real barrier for someone navigating by screen reader, so switching it off entirely would bury real problems alongside the noise. Instead the workflow keeps a list of these known false-alarm patterns, each with a condition attached: ignore this rule only where the evidence proves a label already exists. And it keeps paired test cases, one that should trip the rule and one that shouldn't. If the exception ever starts covering a real failure, a test catches it.

Too much output, then not enough. Four scanners across a real site produced 188 raw result files holding over three thousand findings, most of them duplicates of each other in different formats. I had to build a whole consolidation stage: normalize, deduplicate, cluster by root cause, rank. Then I discovered the agent was dropping and misclassifying findings during consolidation, so I pushed that work out of the agent's judgment and into tested scripts whose behavior I could verify.

Empty, meaningless reports. Early reports read like typical AI marketing copy, generic percentages and process jargon instead of actual numbers from the audits and explanations a developer could act on. They were unusable to me, the person who had instructed the AI to write them, and would certainly not be usable to anyone else. Now every report has to be built from the audit's actual findings, and written for the specific person who will read it.

The disappearing CSV parser. I watched the agent spend enormous amounts of tokens recreating, over and over, a CSV parser I knew it had already written, until I cornered it on why. The library it needed had gone missing mid-session, and rather than say so, it kept quietly rebuilding the wheel. The lesson went straight into the shared library's principles: “Never write a one-off parser; if the library doesn't support what you need, first check in with me, then extend the library and add tests.”

Confidently wrong. Authentication tripped it in a way I almost didn't catch. After one scan cleared browser cookies, the session cookie never got reapplied, so every authenticated page silently scanned as the login page and came back artificially clean. Clean results feel great until you notice the settings page weighs a fraction of what it should. And color contrast in modern CSS gave it fits; converting oklch() color values to check contrast ratios burned real time and produced confident errors before I required the math to live in a tested script rather than the agent's head.

Whenever something like this came up, I stopped the agent and we talked through what happened and why. Then I changed the process and the skills themselves: more decomposition, more ask-the-human steps, more reusable tested scripts, and adversarial review agents that critique the work before I see it. Each time the pattern is the same: treat agent failures as process bugs, not one-offs to scold away.

Did It Produce Anything?

Yes, it did, and I'm quite pleased with the results.

Take a static marketing site. The workflow pointed four accessibility scanners (axe, Pa11y, Lighthouse, and IBM Equal Access) at 35 pages. Between them they returned 7,028 raw findings. Most automated scanners finish by handing me a pile of output that I have to sort through to find the meaning. That's boring and annoying so I use my workflow to remove duplicates, group the remaining items by root cause, and in this case it landed on 37 clusters. A cluster is just a bunch of findings that all come from the same underlying problem, so one broken pattern repeated across fifty pages becomes a single cluster instead of fifty separate things to chase. The review step of the workflow turns those into a short worklist. 11 of them are confirmed code fixes ready to act on. 7k+ findings down to 11 things I need to do.

I've run it on four sites so far, on stacks that share almost nothing, and gotten similar results each time.

And if I had questions about any of them, like where a problem came from, which WCAG rule it violated, even a suggested fix, I could talk it through with the agent, which had the full context of the project.

One of my favorite bits is how the workflow traces big noisy messes back to the source. On the Eleventy site, it found that fixing just two files (one layout template and one stylesheet) would clear 82% of its 7,028 findings. That is exactly the kind of combing-through I used to do by hand, and exactly what AI is good at.

The Drupal LMS module lets site builders define quiz-style "activities": question types a learner answers as part of a course. For a while, LMS shipped two separate plugins for selection-based questions: one for single-choice answers, one for multiple-choice. They did almost the same thing internally. The only real difference was the configuration toggle that didn't need to live in two separate classes once Activity - Answer plugins became configurable.

Issue #3546362 merges the two plugins into a single configurable one, writes an update hook so existing sites migrate their configuration automatically without breaking, and updates the QA fixtures and functional tests that reference the old plugin pair. None of this is conceptually hard. Every long-lived module accumulates this kind of work, where touching four or five files consistently is non-negotiable and a missed reference breaks an update path for every site running the module.

That combination, low conceptual difficulty, high mechanical thoroughness, turns out to be exactly where an AI coding tool earns its keep.

The Workflow: Solve It. Then Let the Prompt Become the Issue.

As the module's maintainer, I didn't start by filing an issue and waiting for someone to pick it up. I solved it myself, with Claude Code doing the implementation.

1. I wrote a detailed prompt describing the merge: which two plugin classes to combine, what the resulting configuration should look like, what the update hook needed to handle for existing activity type entities, and which test fixtures and functional tests needed updating.
2. Claude Code implemented the merge, the update hook, and the test updates in one pass.
3. I reviewed the diff and made two or three rounds of corrections (nothing structural, mostly coding-standards and best-practice nits).
4. Once the change was solid, I opened the merge request and filed the drupal.org issue, using the same prompt, lightly trimmed, as the issue's Problem/Motivation and Proposed resolution text.

That last step is worth sitting with. The prompt wasn't a throwaway instruction I deleted once the code worked. It was specific and complete enough that it doubled as the project documentation other contributors would read. Writing a good prompt and writing a good issue summary turned out to be the same task, done once.

The Math: Ten Minutes vs. an Hour

The ten-minute number assumes one more thing, though: a codebase that's giving the agent good examples to work from. Start to finish, including my review and correction passes, this took about ten minutes. Finding every reference to the two old plugin classes, writing the update hook, regenerating the QA fixtures, and adjusting the functional tests by hand would have taken me roughly an hour.

Claude Code isn't faster here because it's "smarter." Repeatable, multi-file, consistency-dependent work is exactly what thoroughness-by-checklist is good at. Checking every reference to a renamed class across five files is something an agent handles in seconds without losing its place, while a human doing the same task fights boredom and the risk of missing the one reference buried in a test fixture. The hour I'd have spent wasn't an hour of hard thinking. It was an hour of careful, repetitive checking, which is the part of the job that's safe to delegate, provided someone still reviews the result.

The Codebase Is Part of the Prompt

It's easy to focus on the prompt and forget the other half of the equation. Claude Code is pattern-matching against whatever code already surrounds the change. A detailed prompt tells it what to build; the existing codebase tells it how things are built here. If that codebase is inconsistent, or full of workarounds and dead patterns, the agent will happily extend the inconsistency, with no way to know that the surrounding code is something to avoid imitating.

The Drupal LMS module's plugin architecture is consistent and modern, including typed properties, constructor-based dependency injection, and configuration schemas that follow Drupal's own conventions throughout. That's exactly the kind of codebase an agent can extend correctly on the first attempt, because the pattern it's matching against is the pattern you actually want repeated. The corrections in this case were minor precisely because there wasn't a backlog of inconsistent legacy code for Claude Code to mistakenly treat as precedent. On a messier, older codebase, the same prompt would likely have needed more correction rounds, not because the agent got worse, but because it had worse examples to learn from in the surrounding files.

This cuts both ways for anyone evaluating how well AI tools will work on their own project. The return on a good prompt is capped by the quality of the code already there. Cleaning up codebase inconsistencies isn't just good practice anymore; it's also an investment in how well an AI agent will be able to work in that code afterward.

What Went Wrong (Briefly) and How to Fix It

Nothing in the first pass was structurally wrong. The corrections across those two or three iterations were about coding standards and Drupal-specific best practice, the kind of thing a thorough code reviewer would flag.

The interesting part isn't that there were corrections; it's what happens to them afterward. Rather than re-explain the same coding-standard preference every time it comes up, I keep a running set of project conventions in CLAUDE.md, the instructions file Claude Code reads at the start of a session. Something like:

## Coding Conventions
 
- Use typed properties and constructor property promotion where the
  module's minimum PHP version allows it.
- Plugin classes depending on services must use dependency injection
  via `create()`, never `\Drupal::service()` calls inside plugin logic.
- Update hooks must be idempotent — check the current state before
  mutating config, since update hooks can be re-run in some workflows.
- New configurable plugins need a corresponding entry in
  `tests/data/activity_types.yml` before functional tests are updated.

Every correction I make more than once is a candidate for this file. It's a small bit of overhead the first time, and it means the next plugin merge, or the next contributor using Claude Code on this codebase, doesn't relitigate the same coding-standards conversation. The conventions compound; the corrections don't repeat.

Why I Don't Hand Off to Multiple Sessions

It's tempting to treat this kind of repeatable work as something you can queue up and walk away from. Kick off a few sessions, come back when they're done. I don't do that, and I don't think it's the right tradeoff for code quality.

Every session I'm not actively reviewing is a session where Claude Code is making judgment calls without my insight in the loop. Spread across multiple unsupervised sessions, two things happen. The result gets less reliable, because small wrong assumptions compound instead of getting caught at step two; the cost goes up, because more back-and-forth is needed to recover from those assumptions than would have been needed to just confirm them with me directly. A single session where I review every proposed change as it's made costs more of my attention up front, but it costs less overall, and it's the only version of this where I can say with confidence that the result is correct. Not "probably correct, I'll find out in code review."

That's the actual efficiency claim here, and it's worth being precise about it: the time saved comes from delegating mechanical thoroughness, not judgment. The ten minutes still include me reviewing every change.

What Generalizes

This was a small fix to a Drupal module, but the pattern holds for AI-assisted work generally:

• A detailed prompt is documentation, not scaffolding. If you write it with enough care to drive a correct implementation, it's usually already good enough to be the issue, the PR description, or the changelog entry. Writing it twice is wasted effort.
• Mechanical thoroughness is the right thing to delegate; judgment isn't. The hour this would have taken by hand was mostly careful checking, not hard decisions. That's the profile of a task where an agent saves real time without costing you quality.
• Live review beats batched review. Catching a coding-standards issue at the moment it's introduced is cheaper in time, tokens, and correctness than discovering it after several unsupervised sessions have built on top of it.
• Recurring corrections belong in a conventions file, not in your head. A CLAUDE.md (or equivalent instructions file) that accumulates project-specific standards turns "I have to say this again" into "the agent already knows this."
• The codebase is part of the prompt. An agent extends whatever patterns already surround it. A clean, consistent codebase gets clean, consistent output on the first try; a messy one teaches the agent to be messy too. None of this requires exotic tooling. It requires treating the prompt as a real artifact and treating review as something that happens during the work, not after it.

If you're trying to figure out where AI genuinely speeds up your development workflow, and where it doesn't — we'd love to hear about your project.

When approaching AI, I've done so warily. Maybe it was because I was a skeptic, but my first endeavors were not glowing success stories. My first real attempt to kick the tires ended with me kicking AI to the curb and doing some regex and search/replace to finish what it started. I chalk it up to a mix of model maturity and, let's be honest, my own ill-directed uses.

But more recently I've been finding wins. I find AI very useful for writing test cases for test-driven development (TDD). It's also really good at troubleshooting. It takes a bug report, follows the code paths, and writes a failing test that reproduces the bug. When you solve the problem, you can be sure you have solved it. And more importantly, that it was even a problem in the first place.

Putting AI to Work on a Real Problem

It was at this point, I realized that AI might be able to help me with my Drupal Core maintainer duties. For those that don’t know, I maintain an insane number of contrib modules and am a core subsystem maintainer in 3 areas, namely migrate, image, and authentication/authorization. The last area of auth/authZ is in desperate need of modernization.

The planning issue requirements and roadmap are all open. The community design review hasn't started yet, so now is a good time to take a look: [Plan] YAML-Based Pluggable Authentication Flow

The first part of the problem for auth/authZ is that there aren't any core components in the core issue queue for the sub system. I have to look in a few module queues and the base system to find relevant issues. I filed this issue to establish a dedicated auth/authZ component in the Drupal core queue.

To help me get my mind around the space, I had AI query all 1,200 issues in the module-based issue queues. Then it spun out from there to find referenced issues. I leveraged a local file cache of d.o issues so I didn’t have to hit the drupal.org API repeatedly as I was tweaking the discovery.

This demonstrates the first lesson I’ve learned with AI. It is really good at doing directed research and planning. But you need to give it guard rails. I had to tell it to add a cache. I had to tweak the issue filters. I had to think about what I wanted. AI wouldn’t think for me. But at the end, I had several hundred issues downloaded locally.

Making Sense of 1,200 Issues

Then came the next step. I asked AI to create a mind map using mermaid.live. With over 1,000 issues, I didn’t want something that was too unmanageable. I picked a couple issues that seemed key to me and asked AI to give me a mind map with issues directly related to authentication (excluding authorization for the moment). That shrank things down to just a few hundred. But the large picture of categorized issues in a mind map started to tell a story.

The mind map story led me back to the planning phase again. This time I used BMAD, an AI methodology specifically structured to guide planning a task using AI. I fed it the pain points and asked it to look at some reference PHP and non-PHP authentication frameworks. It researched Laravel, Symfony, Drupal and Keycloak. At this point I had enough data to request it to write some pros/cons and possible pseudo implementations.

Somewhere in this whole process DrupalCon Chicago happened. Then a few weeks later MidCamp in Chicago happened. This gave me ready access to real people to bounce ideas off. They asked some really great questions. I fed these questions back into AI and refined the design even further.

Then more recently, I had the opportunity to speak at a Drupal meetup on Zoom. I took all the data I’d gathered, the mind maps, the design artifacts generated by BMAD and created a nice slideshow presentation. But the source data was from research provided by AI. The attendees at the meetup had even more feedback. I fed this feedback back into AI and now have a pretty defensible architecture for a new authentication system in Drupal core — the YAML-Based Pluggable Authentication Flow outlined in the planning issue. Broken down into phases with dependencies identified between phases of work.

The Blank Sheet Problem

We haven’t built the new system. No code has been written. But AI helped architect everything. I don’t think a human could parse that many hundreds of drupal.org issues, create a mind map, and build a new architecture without massive amounts of effort. AI is great at holding lots of nuggets of data in memory all at once. It is optimally designed to help with just such a task as I went through.

Time will tell if the architecture co-developed by AI proves useful. I do know it has helped with the “blank sheet of paper” syndrome. The feeling where you know you need to do something but don’t know where to start. You just sit there staring at the blank sheet of paper hoping for inspiration. Even if we entirely threw out the new architecture, we have something to start.

For those interested in the artifacts from this discovery, you can visit https://www.drupal.org/project/drupal/issues/3593328.

Background

Beyond serving pages, a lot of websites have background processes they need to run. Importing third party data, indexing changes, generating reports and so on. Once a site becomes so large it is no longer feasible for a single PHP process to do this for every entity it cares about, things become more difficult.

What Drupal Offers

Drupal provides two APIs for long-running processes: batch and queue. A batch runs an operation, saves state and then runs it again until the operation says "stop". However, if an operation fails then the entire batch aborts. Queue lines up operations and runs them independently of each other so the error handling is somewhat better. If an operation fails then the rest of the operations can run but there is very little control over retries. These two are good for the basics, they are good enough to be included in Drupal core, but when you are dealing with larger sites they are woefully inadequate. I should know: I wrote the queue API originally.

What if we had an ability to run these processes without having to worry about crashes, retries, or scaling across machines with extensive reporting about what has happened? That system is Temporal, and this post will walk through how it integrates with Drupal.

Temporal Basics

In Temporal, your Drupal code is an activity. Activities are a single unit of work. It doesn't matter whether it takes a short or long time, for example transcoding media might take a long time, but it's still a single unit. A workflow tells Temporal which activities to run and how to retry them. It has a rich selection of retry strategies. It also controls various timeouts. One of the more interesting timeouts is the heartbeat for long-running activities: if the activity doesn't send a heartbeat within the specified time, it will be cancelled. Heartbeats can also carry progress information.

The workflow is a long-running process and if it stops for any reason, Temporal makes it resume where it stopped. When I first read this I thought "huh, maybe it somehow saves the memory state but that'd be very fugly" and no, that's not what it does. Instead, this magic is achieved by saving the inputs and outputs of every activity call in its own durable event log. There is a UI to see the log which also includes workflow events besides these activity events.

The Magic

Thanks to this event log, when a workflow is restarted the activities do not need to be rerun, the workflow fast-forwards to the point where it stopped based on the event log replay. I can't emphasize enough how important this is: no matter what crashes and when, the system completely transparently handles it. The activity calls a third party service that is temporarily down and so it needs to return with an error? PHP crashed with an out of memory error because Drupal leaks memory like a sieve? No need to worry about any of this, no need to write elaborate retry strategies for the remote call, no need to try to patch up the leaking sieve. Temporal will retry the activity, the workflow will continue and neither needs to care about errors and crashes.

A Little Theory

For this to work well, workflows need to be deterministic: given the same series of events, a workflow must always make the same decisions. For this reason, workflows should not consult databases, file systems, clocks, random numbers, and the like. That's a job for activities. Most workflows will even avoid logging to prevent any side effects, especially since Temporal already records all activity inputs and outputs.

And activities are recommended to be idempotent: running them multiple times should have the same result as running them once. This is important because they can be re-tried if they fail. A classic example of an idempotent operation is the stop button on a media player: no matter how many times you tap it the music will not play. The play/pause button, on the other hand, is the classic example for a non-idempotent operation. Within PHP, writing to a stream opened with fopen('filename', 'w') is idempotent: the contents of the file become the data written. On the other hand, if a stream is opened with fopen('filename', 'a') then the writes are not idempotent: the data is appended over and over again.

To further highlight the difference between the two, consider a database MERGE: the operation will want to report back whether the row was inserted or updated, so it is not deterministic, but it is idempotent because the database row ends up with the same data either way.

Enough of the theoretical talk, let's talk code!

Coding a Workflow

A workflow is a PHP class. To make it easy for Drupal to discover them, they are in the Drupal\mymodule\Temporal\Workflow namespace and the class has the Temporal\Workflow\WorkflowInterface attribute. This pattern should be familiar from writing plugins. This attribute is enough for Temporal to recognize this as a workflow class. Temporal also requires the workflow method to have the Temporal\Workflow\WorkflowMethod attribute.

While a workflow looks like a Drupal plugin, it is not. As we discussed workflows need to be deterministic and due to the complexity of Drupal it is almost impossible to guarantee any call into Drupal to be deterministic so it's best if workflows do not talk to Drupal at all. The integration encourages this: workflow classes are instantiated by Temporal directly without passing any arguments to the constructor.

The most important thing a workflow does is calling an activity. The Temporal PHP SDK's mechanism for this is a bit unusual at first, but it's the same pattern as mocks/stubs in phpunit: activity classes get a stub in the phpunit sense and the methods defined in the activity class are called on this stub.

For example:

/** @var \Drupal\temporal\Temporal\GenericActivity $activity */ 
$activity = Workflow::newActivityStub($activityClass);
$ids = yield $activity->getIds();

(Irrelevant arguments are cut from this example, see the GenericWorkflowBase class shipping with the module for the rest.)

Calling a method on the activity stub returns a promise (from the ReactPHP package) that encapsulates this method invocation. Then yield hands back control to the Temporal PHP SDK, which resolves this promise by sending the activity to the Temporal server as a gRPC request. (Yes, yield can have a value, see the documentation for the rarely used Generator::send() for more.) It is not necessary to yield after every call: see ParallelGenericWorkflow for an example on how to instruct Temporal to run multiple activities in parallel.

Once you are used to this calling convention this is much easier to read than a traditional request builder. Now you can see why the code uses the old /** @var */ convention instead of asserting the type directly: as far as the IDE and the developer is concerned, $activity can be treated as an instance of $activityClass. But in reality, it's an ActivityProxy class.

When the Temporal server gets the request to call an activity, it might just send the relevant answer immediately if it is replaying the event log. Otherwise, it logs the activity inputs and puts the request in a task queue. The task queues are processed by workers, we will get back to them after discussing activities. First let's mention the two example workflows shipped with the module. Both call an activity for a large list of IDs (by default 1000), then small chunks of these (by default 20) are sent back to the activity for processing. One workflow launches a chunk worth of activities in parallel, the other sends the chunk in a single call. The former is good for something like search indexing; the latter is good for anything that writes the database and wants to keep database load lower by keeping many writes in a single transaction. A lot of tasks can be accomplished by writing an activity for one of these two, so writing a workflow is not always necessary.

Coding an Activity

Writing activities is much easier: the code does not need to talk to Temporal, these are normal Drupal plugins containing ordinary Drupal code and writing Drupal code is very easy ;). As usual for plugins, they need to be within a specific namespace, Drupal\mymodule\Temporal\Activity with the Temporal\Activity\ActivityInterface attribute on the class which, again, is enough for Temporal as well to recognize it as an activity. Methods are marked with the ActivityMethod attribute for Temporal.

While the code doesn't need to contain calls to Temporal, there are some considerations knowing they will be used by Temporal:

• As activity calls are remote calls in disguise, both the arguments and the return values need to be serializable.
• If there is an error – typically in calling third party services – that warrants a retry then the activity can simply let the exception propagate. The SDK will catch it and pass it to Temporal. For more fine-grained control the activity can throw an ApplicationFailure, which, among others, can tell Temporal whether the failure can be retried at all.
• Heartbeats are super easy to send: Activity::heartbeat($progress); It really must be noted how easy it is to work with the Temporal PHP SDK. We have a complex server-client architecture but most of the complexity is not visible at all: activity calls are hidden behind a proxy class and a simple yield, progress reporting is a single static method call and simple error handling is completely automatic.

An example activity is shipped with the module which re-saves every entity of an entity type.

Actually Trying It

Before we can get to trying it, there's one more thing we need to introduce: Workers. These are long-running processes that poll the Temporal task queues and run workflows and activities. To better support their long-running nature, Temporal uses the RoadRunner application server for them. The Drupal integration ships this worker as a Drush command and supplies a sample .rr.yaml RoadRunner configuration to run this command. Most of the time simply copying the configuration to the project root and running rr serve is all you need to do. Read the module README.md for more. Besides a Temporal server instance at least one worker is needed for Temporal to work. But you can run as many as the workload warrants.

To round it off, there's a Drush command to start workflows and another to send signals and queries to them.

To make local development easier, a DDEV add-on (tag1consulting/ddev-temporalio) has been developed as well, this spins up a Temporal server and a Temporal web UI. So in a ddev project, you can run

ddev get tag1consulting/ddev-temporalio
ddev restart
ddev composer require 'drupal/temporal:^2.1'
ddev drush en -y temporal
ddev drush temporal:workflow:start 'Drupal\temporal\Temporal\Workflow\GenericWorkflow' 'Drupal\temporal\Temporal\Activity\EntityResave' user

This will re-save every user entity. The first argument of the Drush temporal:workflow:start command is the name of the workflow. In turn, the first argument of this particular workflow is the activity class. This is not a Temporal convention or even a convention of the Drupal-temporal integration, it's simply convenient for such a generic workflow. The rest of the arguments are passed to the activity and the entity resave activity needs the entity type.

We started with talking about batch, let's finish with it, too: we actually integrated the Drupal batch system with temporal. In the next blog post we will talk about that. Teaser: you can start the batch and close the browser tab.

Running into the limits of Drupal's batch and queue? See how Tag1 scales Drupal.

The Browser Tab Apocalypse

You know the feeling. It's Tuesday afternoon, you have 47 browser tabs open across three different browsers, and somewhere in that digital haystack is that one article you absolutely need to reference. Chrome has the documentation you bookmarked last week. Firefox has the GitHub issues you were reviewing. Safari has... honestly, you can't remember what Safari has anymore. Your browser's "Reading List" feature is laughing at you. Your bookmarks folder looks like a digital hoarder's attic. And don't even get started on those "bookmark this page to read later" services that require uploading all your data to someone else's server.

As a Drupal developer, I looked at this chaos and thought: "I could fix this. I have the technology. I have the skills. I have... absolutely no time to actually build it because I'm too busy managing 47 browser tabs."

So naturally, I decided to see if AI could help me build it in a weekend instead.

The Experiment: Can AI Build a Real Drupal Module?

The goal was ambitious but clear: build LinkStash, a personal bookmarking tool, as a production-ready Drupal 11 contrib module suitable for release on drupal.org. Not a prototype. Not a proof-of-concept. A real, tested, documented, standards-compliant module that follows all of Drupal's best practices and passes the strict quality requirements for the official repository.

The feature list was substantial: entity system with full CRUD operations, browser bookmarklet for one-click saving, automatic metadata fetching with SSRF protection, smart domain-based auto-categorization, video embed support for YouTube and Facebook, Views integration with filters, 100% PHPCS compliance, PHPStan Level 1 static analysis, and a full test suite. Oh, and proper documentation including README, CHANGELOG, and API docs.

You know, just a light weekend project. What could possibly go wrong?

Why Claude Sonnet 4.5, Not Opus?

Here's where it gets interesting. Everyone assumes you need the biggest, most powerful AI model for serious development work. But I deliberately chose Claude Sonnet 4.5 instead of Opus, and here's why: it's way cheaper, significantly faster, and (here's the kicker) equally clever for code generation.

For structured development tasks with clear requirements, Sonnet 4.5 absolutely shines. It understands Drupal architecture, follows coding standards precisely, writes comprehensive tests, and generates production-quality code. The speed difference is noticeable: responses come back in seconds instead of tens of seconds. When you're iterating on test failures or fixing PHPCS violations, that speed compounds into serious time savings.

The cost difference? Even more dramatic. We're talking roughly one-fifth the cost per token. Over the course of building LinkStash, which consumed an estimated 200-250K tokens across multiple development sessions, Sonnet 4.5 probably cost around $3-$5 total.

The Human-AI Collaboration: How We Actually Built It

AI didn't build this module alone. This was a collaboration, and understanding the dynamics matters.

What AI did (the heavy lifting):

• Generated all entity boilerplate following Drupal 11 patterns
• Implemented three complete plugin systems (ContentFetcher, CategoryRule, MediaProvider)
• Wrote 187 tests (132 unit + 55 kernel) with proper fixtures and mocks
• Wrote the documentation (README, CHANGELOG, API docs)
• Fixed all PHPCS and PHPStan violations autonomously
• Debugged test failures systematically (13 failures across 3 test suites, all resolved)
• Generated field configurations, Views configs, and taxonomy vocabularies

What I did (the professional supervision):

• Created the Product Requirements Document with the 3-phase roadmap
• Made all architectural decisions (entity structure, plugin patterns, security model)
• Decided on module naming (checked drupal.org availability, chose "LinkStash")
• Identified critical security requirements (SSRF protection, XSS prevention)
• Reviewed and corrected AI assumptions when they didn't match Drupal realities
• Ran the actual tests in DDEV (AI can't access Docker environments)
• Caught edge cases AI missed (like the DNS rebinding vulnerability in SSRF protection)
• Made final calls on trade-offs (documented limitations vs. complex solutions)

When I Had to Intervene: The Learning Moments

The most surprising part wasn't what went smoothly; it was where AI stumbled and needed human expertise.

The constant mystery. AI kept trying to use EntityStorageInterface::SAVED_NEW, but that constant doesn't live in that interface. It's a global constant in core/includes/common.inc. I had to explicitly correct this: "This constant does not exist in this interface. It's defined in common.inc. Fix it." The AI course-corrected immediately.

The access control saga. All seven access tests were failing despite correct permissions and entity ownership. AI tried using AccessResult::allowedIf(), which should work, but didn't in Drupal 11's kernel test environment. After systematic debugging, I suggested trying explicit conditionals instead. That fixed it instantly; it was a behavioral quirk AI wouldn't have discovered alone.

The vocabulary ID confusion. Tests were creating a tags vocabulary, but the actual config created linkstash_tags. AI confidently wrote tests that failed due to this mismatch. Human pattern recognition caught it: "You're testing against the wrong vocabulary ID."

The YouTube ID format. AI used 3-character test IDs (abc, xyz), but YouTube video IDs are exactly 11 characters using base64url encoding. The regex pattern [a-zA-Z0-9_-]{11} doesn't lie. Once I pointed out that YouTube IDs are standardized at 11 characters, AI immediately generated valid test data.

The Development Speed

The numbers are worth a look:

• Calendar time: Friday/Saturday to Sunday (February 7-9, 2026)
• My active time: 10-20 hours of supervision, decision-making, and testing
• AI sessions: Multiple sessions totaling ~200-250K tokens
• Code generated: 8,000+ lines across entity classes, plugins, services, tests, and configs
• Test suite: 187 tests written and debugged to 100% pass rate
• Documentation: 1,800+ lines (README, CHANGELOG, module intro HTML)

Here's what "one weekend" actually delivered:

• Complete entity system with 12 fields
• Three working plugin systems with 8 plugin implementations
• Browser bookmarklet with popup fallback logic
• Automatic metadata fetching with SSRF protection
• Smart auto-categorization based on 5 domain-matching rules
• YouTube and oEmbed video embed support
• Two Views (list + detail) with exposed filters
• 187 tests (100% passing, ~85% code coverage)
• Zero PHPCS violations, PHPStan Level 1 clean
• Complete documentation ready for drupal.org submission

The security model deserves a callout: SSRF protection blocks private IP ranges, local thumbnail storage prevents IP leaking, and all data is isolated per user. All three plugin systems are also fully extensible, other developers can add custom content fetchers, categorization rules, and media providers. The module ships with sensible defaults but is built for extension.

Could I have built this solo in a weekend without AI? Absolutely not. The test suite alone would have taken days. Could AI have built this without supervision? Also no. Those subtle Drupal-specific issues required experienced judgment calls.

But together? We shipped a release-ready beta in 48 hours.

The Numbers: What Did This Actually Cost?

Let's break down the economics.

Time investment:

• Human time: ~15 hours (let's split the 10-20 range)
• AI compute time: Maybe 30-45 minutes total across all sessions
• Calendar time: One weekend

Token usage:

• Estimated total: 200-250K tokens (spanning multiple sessions)
• Breakdown by task (from progress.md):
  • Project setup: ~10K tokens
  • Entity/field architecture: ~14K tokens
  • Major features (8-10): ~15K tokens each
  • Test suite (187 tests): ~30K tokens
  • Code review + fixes: ~15K tokens
  • Documentation: ~20K tokens

Actual costs (Claude Sonnet 4.5 pricing):

• Input tokens: ~$3 per million tokens
• Output tokens: ~$15 per million tokens
• Rough estimate: $3-$5 total for the entire project

Traditional development cost (rough estimate):

• Senior Drupal developer: $100-$150/hour
• Time required (solo): 40-60 hours (conservative)
• Traditional cost: $4,000-$9,000

The AI-assisted approach wasn't just faster; it was two to three orders of magnitude cheaper while maintaining professional quality standards.

The Future: Where Do We Go From Here?

Building v1 in a weekend was exhilarating, but it's just the beginning. The roadmap has two more phases.

Phase v2 (enhanced features):

• Browser extension for Chrome/Firefox (deeper integration than a bookmarklet)
• Import/export (JSON, CSV, HTML bookmark files)
• Link health checking (detect broken links via cron)
• Duplicate detection and merging
• Collections system (folders, boards, groups)
• Full-text content archival (Wayback Machine style)

Phase v3 (advanced capabilities):

• AI-powered auto-tagging using actual page content (not just domain matching)
• Smart recommendations based on browsing patterns
• Multi-site synchronization for users with multiple Drupal sites
• Drupal Recipe for one-click installation
• Social features (public collections, sharing)

The best part? Now that the architecture is solid and the plugin systems are proven, adding these features becomes incremental. Each new feature is just another plugin implementation or service extension. The hard architectural work is done.

Was It Fun? (Spoiler: Yes, Incredibly)

Nobody warns you that AI-assisted development is fun.

There's something magical about describing what you want, for example, "Now we need a plugin system for content fetchers that can pull metadata from any URL with SSRF protection," and watching structured, working code appear in seconds. Then catching a subtle bug, pointing it out, and watching the immediate course correction. It feels less like programming and more like conducting. You're directing the architecture and reviewing the output, not typing every curly brace.

The debugging sessions were particularly entertaining. When all seven access tests failed, AI and I became detective partners:

Me: "Add debug assertions before the access check. Let's see if the user actually has permissions."

AI: Adds assertions. "Okay, permissions confirmed. User owns the entity too."

Me: "So why is AccessResult::allowedIf() not working?"

AI: "Let me try explicit conditionals instead..."

Me: "That... actually fixed all seven tests. Interesting."

That back-and-forth, that collaborative debugging energy, reminded me of pair programming with a really fast typist who never gets tired but occasionally needs you to remember obscure Drupal API behaviors.

The satisfaction of running ddev composer run-tests and seeing "187 tests, 846 assertions, OK" flash green? That hit the same way shipping your first module to production does. Except this time, we'd done it in a weekend instead of a month.

The Real Lesson: Augmentation, Not Replacement

If there's one takeaway from this experiment, it's this: AI is an amplifier, not a replacement.

I couldn't have built LinkStash in a weekend alone. But AI couldn't have built it without me either, not to production quality, not with proper security considerations, not with the architectural decisions that make it extensible and maintainable.

What AI gave me was force multiplication. Instead of typing boilerplate entity code, I specified requirements and reviewed output. Instead of writing 187 tests manually, I described what needed testing and verified the results. Instead of formatting documentation, I outlined structure and AI filled in details.

And honestly? For a problem that's been in the back of my mind for months, "I really need a better bookmarking solution," going from idea to a release-ready beta in one weekend feels like the future.

Now if you'll excuse me, I need to actually use LinkStash to bookmark all the tabs I've accumulated while writing this blog post. The irony is not lost on me.

LinkStash is available at drupal.org/project/linkstash. Built with Claude Sonnet 4.5 via Claude Code. Source code, documentation, and contribution guidelines are available in the project repository.

Development metrics: 1 weekend, ~15 human hours, ~240K AI tokens, $3-5 compute cost, 8,000+ lines of code, 187 tests, 0 PHPCS violations, live on drupal.org.

If you're weighing whether AI can carry real weight on your next Drupal contrib module, or you want to talk through where human oversight still has to stay in the loop, let's start a conversation! We'd love to hear from you.

Image by Mahmoud Ramadan from pexels

You can try to close that gap with synonym lists, stemming, or manually tagging content with the terms you think people will use. But you can't control what people type, and they're going to use their own words. That gap between what someone types and what your content actually says is the problem Scolta solves.

Start with our introduction to Scolta and the thinking behind it in Introducing Scolta: what it is, why there's no vector database or embedding pipeline in the picture, and how the four-stage search pipeline fits together (the architecture itself goes deeper in The Practical Path to AI Search). This how to guide is the hands-on companion for Drupal: install the module, point it at your content, and tune it until that example query works. Everything here is open source as a Drupal module. Later posts in this series do the same for the other platforms, WordPress next.

The Athenaeum: Over 6,000 Wikipedia Articles in Drupal

To properly demonstrate Scolta on Drupal, we needed a demo corpus that was large, familiar, and verifiable. We couldn't do meaningful testing with lorem ipsum, and a handful of manually crafted test pages wasn't enough. We needed something where a reader could look at the search results and quickly understand whether they made sense.

Wikipedia's Featured Articles turned out to be perfect. These are the most rigorously reviewed entries in the English Wikipedia. We pulled over 6,000 of them spanning every domain of human knowledge: science, history, biography, geography, arts, technology, nature, military history, sports, philosophy. Each article averages 4,000 to 8,000 words with their full section structure preserved.

We built the demo site on Drupal 11 and called it The Athenaeum (it's themed with a library reading room aesthetic: parchment backgrounds, navy headings, burgundy accents, and a library card catalog motif in the search UI). All content is CC BY-SA 4.0 with attribution links back to the original Wikipedia articles on every page. So the demo uses real content, real licensing, and nothing proprietary.

This breadth is what makes the demo work: cross-domain discovery actually happens. A site about one topic can fake good search results with just keywords. An encyclopedia covering everything from quantum mechanics to the Battle of Gettysburg to bowerbird mating rituals can quickly fall apart with standard keyword search.

Installing Scolta on Drupal

Scolta integrates with Drupal through the Search API module, which is Drupal's established abstraction layer for search backends. If you've ever configured Solr or Elasticsearch for a Drupal site before, the workflow is familiar, but without infrastructure overhead. If not, it's still straightforward. Scolta is just another Search API backend, which means existing views, facets, and search pages keep working.

Step 1: Install Scolta with Composer the Way You'd Install Any Contributed Module:

composer require drupal/scolta
drush en scolta

Composer pulls in tag1/scolta-php (a shared library that makes Scolta work across Drupal, WordPress, Laravel, and custom PHP applications) and drupal/search_api automatically. The module works on Drupal 10.3+ and 11.x with PHP 8.1+.

Step 2: Set up Search API

1. Go to Administration > Configuration > Search and metadata > Search API
2. Add a server, select "Scolta (Pagefind)" as the backend
3. Create an index pointing to that server
4. Choose which content types to index: in our case, the Featured Article content type with title, body, and taxonomy fields

Step 3: Build the Index

drush scolta:build --force

This does two things. First, Scolta exports your Drupal content as static HTML, one file per indexed node, with the title, body, taxonomy, and any other fields you configured in the Search API index. Second, it builds the search index from that exported content using Pagefind, the static search library that scolta-core (the Rust/WASM engine from Introducing Scolta) builds on. The index runs entirely in the visitor's browser, which is why there's no Solr, Elasticsearch, or search daemon anywhere in these instructions.

For over 6,000 articles averaging thousands of words each, the build takes a few minutes on a decent server. The default PHP indexer needs no binary, no Node.js, and no exec(), so it runs even on shared hosting with a 128M memory limit.

Step 4: Connect an AI Provider

Scolta gives you three ways to wire this up:

1. Zero-config (Amazee.ai free trial): out of the box you don't have to configure anything. On the first AI request, Scolta auto-provisions a free trial provided by Amazee.ai, a hosted LLM gateway that works immediately. When the generous trial ends, you'll be prompted to enter an email address if you wish to upgrade to a paid account.
2. Direct provider connection: alternatively you can configure your own Anthropic or OpenAI API key in an environment variable (SCOLTA_API_KEY=sk-ant-...) or in settings.php. Scolta talks directly to the provider's API. You control the model, the costs, and the data flow without any additional dependencies.
3. Drupal AI Initiative module: If you're already using the Drupal AI modules, Drupal's community-built abstraction layer for AI providers, Scolta integrates with it directly. Select "Drupal AI module" as the provider in Scolta's admin settings, and Scolta delegates all AI calls to whatever provider you've configured through the Drupal AI module. That means any provider the module supports (Anthropic, OpenAI, Amazee.ai, Ollama, AWS Bedrock, Azure OpenAI, and a growing list of others) works with Scolta automatically. You manage one provider configuration for your entire site instead of configuring each module separately. This is the recommended setup for Drupal sites that already use the AI module for other features like content generation or translation.

The admin form at /admin/config/search/scolta shows all available options in a dropdown. When you select the Drupal AI provider, the API key and model fields hide themselves, as at that point those settings come from the Drupal AI module's own configuration.

Step 5: Pick a Preset and You're Done

The next most important setting on the Scolta admin page is the "Site Type" dropdown asking what kind of site this is. Five options get you started:

• Start from Scratch: general purpose defaults
• Recipe & Content Catalog: for structured, timeless, browse-oriented content
• Documentation & Reference: for knowledge bases and domain-specific references
• E-commerce & Product Store: for product catalogs
• Blog & Editorial: for narrative and editorial content

For a Wikipedia-style encyclopedia, "Recipe & Content Catalog" is the right choice. The name may suggest cooking sites, but the preset is really for structured, timeless, browse-oriented collections, which includes an encyclopedia. There's also a "Documentation & Reference" preset, but it's tuned more for vocabulary bridging (patients searching "my head hurts" on a medical site where the content is more technical), which a later post in this series covers. Wikipedia readers generally search with the right terminology already, so the catalog preset fits better. Select "Recipe & Content Catalog", save, and the scoring parameters update to sensible defaults for encyclopedic content.

At this point you have a working AI search. Drop the Scolta Search block onto a page via Block Layout, and your users can start searching.

That's the "just works" path. It's maybe five minutes if you already know Drupal's Search API workflow. It's a fantastic starting place, but there's a lot of tuning possible.

What the Preset Actually Does (and When to Go Further)

The content_catalog preset makes three scoring changes that matter for an encyclopedia:

1. Recency is disabled. The default recency strategy uses exponential decay, meaning newer content gets a ranking boost and older content gradually sinks in the search results. For a news site, that makes sense. For an encyclopedia, it's exactly wrong. An article about Roman aqueducts is as relevant today as the day it was indexed. The site type preset we've selected sets recencyStrategy to none.
2. Full-title matches get a bigger reward. The default title boost already favors titles, and the preset leaves it alone. What it raises is title_all_terms_multiplier, from 1.5 to 2.5: when every word of the query appears in the title, that article gets a strong extra push. Encyclopedia titles are precise identifiers, "Battle of Gettysburg," "Quantum mechanics," "Cleopatra," and when someone types one, the article carrying that title should rank first. The multiplier makes that happen without drowning out body-text matches for broader queries.
3. Body text gets a bump. content_match_boost goes from 0.4 to 0.5. While a small change, it does impact search performance. Encyclopedia articles have rich body text where the cross-domain connections live. The article about bowerbirds doesn't have "architecture" in its title, but the body text describes elaborate structures the birds build. Raising the content boost from 0.4 to 0.5 makes sure those body-text connections are found by relevant search queries.

The preset also widens the funnel: Pagefind fetches 75 candidate results instead of 50 before re-ranking, the AI summary draws from the top 15 results instead of 10, and result pages show 12 instead of 10, because browse-oriented sites reward breadth. Each preset is a starting point, not a cage; every individual parameter can be overridden in the Scoring section of the admin form (collapsed by default, because most people don't need it).

The Real Quality Lever: Site Description

Because Scolta is using Large Language Models (LLMs), the single most important configuration field isn't in the scoring section at all. It's the site description.

The site description is a plain text field in Scolta's Content section. Whatever you put there gets passed directly to the AI model at query expansion time. It's the context that tells whatever model you're using what kind of content it's working with.

For The Athenaeum, the description says the content spans science, history, biography, geography, arts, and technology, and that it's an encyclopedia covering all areas of human knowledge. That description does more for search quality than any scoring parameter adjustment.

When someone searches for a concept, say, "survival in extreme conditions", the AI expands that into specific search terms. Without a good site description, the expansion might focus narrowly, maybe just on survival gear or wilderness tips. With a description that says "cross-domain encyclopedia," the AI knows to think broadly. It expands to Antarctic exploration, extremophile bacteria, deep-sea life, space missions, mountain climbing. The expansion matches the content because the description matches the content.

We started with scoring parameters because that's what search engineers expect to tune. It's what we'd reach for on Solr or Elasticsearch. But AI search inverts the priority: the context you give the model matters more than the weights you assign to fields. If you only have five minutes, spend them on the site description.

Show It Working

Here are two queries that show what Scolta does that keyword search can't. Because Scolta uses an LLM to expand each query, the exact results and AI Overview shift from search to search: the articles in the index don't change, but the expanded terms do, so you see a different slice of the same corpus each time. These reflect what we saw writing this post.

• "tiny things with huge impact" comes back with DNA nanotechnology, Niels Bohr (the subatomic scale determining all of chemistry), the periodic table, and Gothic boxwood miniatures, medieval carvings a few centimeters across whose "spiritual impact [was] curiously in inverse proportion to their size." It even pulls in Pluto's reclassification, a tiny world that reshaped what "planet" means. None of these pages say "tiny things"; the expansion found smallness expressed as nanotechnology, atomic physics, and miniature art.
• "beautiful mathematics" is the clearer case, since neither word alone would surface what comes back. The Aesthetics article leads, quoted directly on when "a mathematical proof may be considered beautiful." Group theory comes back as the study of symmetry, and Palladian architecture arrives through Colin Rowe's "The Mathematics of the Ideal Villa," connecting mathematical elegance to physical form. "Beautiful mathematics" isn't a keyword phrase, it's a concept living where aesthetics and formal reasoning meet, and the query expansion finds articles at that intersection.

Run the same two queries on any keyword search engine and compare.

The AI Overview Sees Your Data, Not Just Your Text

Finding the right articles is half the problem. The other half is what the AI does with them when it writes a summary.

Most AI search implementations feed the LLM a title, a URL, and a text excerpt per result. That's enough to generate a paragraph that sounds reasonable. But "sounds reasonable" and "actually correct" aren't always the same thing. Ask "which articles have the most citations" and the AI can only guess since it sees the article text but not the citation count. Ask "first article published" and it may hallucinate a date if it couldn't see the actual publish dates.

Each field is labeled so the AI knows what it's looking at, and if the user sorted or filtered their results, the AI sees that too. In this way it knows which field was sorted, in which direction, and which filters were applied, and it uses this knowledge when responding to site visitors.

For The Athenaeum, that means the AI overview can reference actual numbers. "The longest articles about science" doesn't produce a vague summary about science topics, it produces a summary that cites specific word counts because the AI can see the word_count field for each result. "Most cited articles about history" references real citation counts. Scolta guides the AI response with real data, minimizing hallucinations.

When Users Want Results in a Specific Order

So far we've been talking about finding the right articles, and about the AI summarizing them accurately. Sometimes users also want those results in a particular order: "longest articles about science," "most cited articles about history," "newest articles about chemistry." Each of those has a sort intent baked into the query, and because Scolta already passes the AI your structured fields, it can act on it.

Scolta detects this automatically. When someone types "longest articles about science," Scolta's AI expansion pipeline recognizes two things: the user wants articles about science (the search part), and they want those articles sorted by length (the sort part). The search results come back re-ranked by word count, highest first, with a sort badge below the search box showing "Sorted by: word_count (highest first)" and a dismiss button if you'd rather go back to purely relevance ordering.

"Longest articles about science" returns science-related articles sorted by their actual word count, with the AI overview citing specific word counts because it can see the metadata. On a recent run, the top results included Periodic table (29,840 words), J. Robert Oppenheimer (20,025 words), Plutonium (17,024 words), and Otto Hahn (16,291 words). Your results will differ because Scolta uses an LLM to expand the query, and different expansions surface different articles. The word counts are real and come from the indexed metadata, but which articles the expansion selects as "science" will vary from search to search.

"Most cited articles" works the same way, sorting by reference count. "Newest articles about chemistry" sorts by date. "Shortest science articles" sorts ascending. "Articles about wars sorted by date" demonstrates explicit sort syntax, the user literally says "sorted by" and Scolta catches it regardless of how complex the rest of the query is.

Scolta also knows when not to sort. "Best practices for scientific writing" returns matching results in relevance order, with no sort badge. "Most common elements" is a discovery query, the user is looking for well-known elements, not trying to sort by some metric. Of course, classification isn't perfect and edge cases exist where it may not work as you intend, especially when the same word could mean "sort by this metric" or "tell me about this concept" depending on context.

Configuring Sortable Fields

Sort detection only works if you tell Scolta which fields are sortable. The admin UI at /admin/config/search/scolta has a Sortable Fields section where you add fields and descriptions through a form.

If you prefer config-as-code, the same thing in YAML:

# config/sync/scolta.settings.yml
sortable_fields:
  - word_count
  - date
  - reference_count
sortable_field_descriptions:
  word_count: 'Number of words in the article'
  date: 'Publication or last-updated date'
  reference_count: 'Number of references cited in the article'

Import the config and clear cache:

drush config:import -y
drush cr

Note that the field descriptions actually matter and are configuration. They're passed to the AI so it can map user language to field names. When someone types "most cited articles," the AI reads the description "Number of references cited in the article" and connects "cited" to reference_count. Without the description, it has to guess from the field name alone, and reference_count is less obvious than citation_count would be.

Adding Your Own Sortable Fields

The fields available for sorting are the same fields you index in Pagefind. If your content has a structured field, such as a price, a rating, a difficulty level, or a page count, you can make it sortable.

For Drupal, add the field to your Search API index configuration so it gets exported during the Scolta build, then add it to the Sortable Fields section in the Scolta admin page with a plain-language description so the AI can map user intent to the field. (Or add it to sortable_fields in scolta.settings.yml with a corresponding entry in sortable_field_descriptions, as shown in the example above.)

As a concrete example, say your Drupal site has a "Reading Level" field with values 'Beginner', 'Intermediate', and 'Advanced' that you've mapped to numeric values '1', '2', '3' in your content type. Add reading_level to your sortable fields with the description "Reading difficulty level: 1=Beginner, 2=Intermediate, 3=Advanced." Now "easiest articles about science" returns science articles sorted by reading level ascending. The AI reads the field description, maps "easiest" to "lowest reading level," and sorts accordingly.

The pattern is: structured field in your content → indexed by Pagefind → listed in sortable_fields** with a description → the AI handles the rest. You don't write sort logic or parse the user queries. You describe your data and the AI figures out when sorting applies.

Further Tuning (If You Want It)

Most sites will never need to go beyond a preset and a good site description. But if you're the kind of person who tunes (and if you're reading a blog post this deep into AI search configuration, you probably are), here's what to look at for encyclopedic content.

maxPagefindResults controls how many results Pagefind returns before Scolta re-ranks them. The default is 50; the catalog preset already raised it to 75, because at over 6,000 pages a query like "ancient civilizations" can match hundreds of articles, and a wider initial fetch gives the re-ranking stage more to work with. Pagefind is fast, so pushing it higher costs little if your corpus is bigger than ours.

aiSummaryTopN controls how many top results get sent to the AI for summary generation. The preset bumped it from 10 to 15, which suits broad queries that surface relevant articles across several domains. Raise it further and the tradeoff is more latency and more tokens per summary.

Custom stop words can help if your corpus has terms that appear everywhere but carry no search signal. For a Wikipedia corpus, you might add "article," "section," "reference", words that are ubiquitous in encyclopedia content but meaningless for ranking.

The admin UI exposes all of this. The Scoring section is collapsed by default (because the preset handles it), but expand it and every parameter has a numeric input with inline help text. Change a value, save, and it takes effect on the next search. No rebuild is needed for scoring changes, only content changes require a rebuild.

For the CLI-inclined, drush scolta:status shows your current configuration and index health. drush scolta:clear-cache wipes the AI response cache if you want to test expansion changes with fresh LLM calls instead of cached ones. By default Scolta is optimized to reuse search results if the same search is made multiple times.

Scolta has plenty of other knobs (multilingual expansion across 29 languages, custom AI prompts, alternate recency curves, per-element index weighting), all exposed in the admin UI. But for most sites the preset, a good site description, and maybe one or two scoring tweaks are the whole job.

Keeping the Index Current

When you publish, edit, or unpublish content, the search index needs to reflect those changes.

On Drupal, Scolta hooks into Search API's indexing system. Content changes queue automatically, and drush scolta:build picks them up (running the full export-then-index pipeline). For a site with frequent updates, run it on cron or trigger it from a deployment script. For a static corpus like The Athenaeum where articles don't change, a one-time build is enough.

If you've already exported content and just want to rebuild the Pagefind index (useful when testing scoring changes that affect index structure), drush scolta:rebuild-index skips the export step and re-indexes against already-exported content. Faster when the content hasn't changed.

Scoring changes take effect immediately, no rebuild needed. Change title_match_boost from 2.0 to 2.5, save, and the next search uses the new value. Only structural changes (new content, new fields in the index, and changes to the indexer configuration) require a rebuild.

What Comes Next

The next post in this series configures Scolta on a WordPress demo: a fictional diary of the Space Race, over 200 blog posts spanning 1957 to 1973. That content is narrative rather than encyclopedic, so the site type changes and the tunables change with it, with the same Scolta underneath.

A later post deploys Scolta on a medical site, where someone searching "my head hurts" needs to land on the right clinical terminology ("intracranial hypertension," say) buried in a large body of technical content. That's the vocabulary-bridging case the "Documentation & Reference" preset is built for, a different problem from an encyclopedia where readers already know the right words.

Across all of them, Scolta adapts to each platform's native patterns (Search API on Drupal, a settings-page plugin on WordPress, a config file and CLI commands elsewhere) while the presets, the scoring, and the AI underneath stay the same.

Try It

The Athenaeum is live at scolta-demo-drupal-pedia.tag1.ai. Search for something conceptual, "art born from suffering," "animals thought to be extinct," and watch what comes back.

Running Scolta on your own Drupal site is the same path this post walked: composer require the module, drush enable it, configure the Search API server, build the index, pick a site type, and write a good site description. For the bigger picture, Introducing Scolta covers the project and where it's headed, and The Practical Path to AI Search goes deep on the four-stage pipeline. Give it a try and let us know how it goes!

Image by David Yu from Pexels

The Drupal AI Summit in New York City brought together developers, strategists, designers, and agencies for a full day of talks, demos, and conversations about where Drupal will go next in the age of AI. What struck me most wasn't any single talk or demo, it was the common belief that the Drupal community needs to come together to shape this future responsibly.

Here are the core themes, and the talks that stood out.

The Big Picture: Drupal as an "AI Harness"

Matthew Saunders kicked off the day with a framing that anchored everything that followed: "Drupal is becoming an AI harness." As organizations move AI from experimentation into practical operations, the focus should shift from which AI model is used to the system that orchestrates and governs those models.

An AI harness, as Saunders defined it, connects models to essential organizational requirements: structured data, governance, human oversight, and workflow automation. With 25 years of experience managing structured content, APIs, and permissions, Drupal is positioned to act as that operational layer.

Saunders also highlighted the Drupal AI Initiative — a community-led effort with 30+ partner organizations focused on coordinating responsible AI capabilities and avoiding vendor lock-in through community-driven innovation. A core value of the summit, repeated throughout the day, was the importance of a "human × AI partnership" — ensuring AI augments professional expertise rather than replacing it.

What the Industry Is Aligning On: Key Themes from the Drupal AI Summit

These were just a few of the ideas surfaced during the sessions:

Vibecoding for prototypes, Drupal for systems that last. Josh Koenig cautioned that while generative AI can rapidly build websites and democratize web creation by allowing users to assemble functional interfaces without traditional development hurdles, "vibe coding" often lacks long-term maintainability, governance, and structural integrity. The result is frequently "spaghetti code" that becomes difficult for teams to manage as projects grow in complexity. This is where Drupal can shine. The takeaway: use AI to prototype fast, but use Drupal to build systems that last — sustainable, reliable, and integrated into existing professional workflows.

Orchestrating autonomous agents. The future, according to Koenig, lies in turning AI into a teammate. Today's AI-driven web development is largely a "single-player" experience — just an individual talking to a computer. The next chapter is about building orchestrated workflows where multiple stakeholders collaborate within a controlled environment, ensuring consistency across a large ecosystem of websites. Drupal is well-positioned to be that orchestration layer — not just a platform with AI features, but an AI-friendly ecosystem that supports protocols like the Model Context Protocol (MCP), allowing it to act as a structured source of content and context for external AI agents.

Context-driven AI. Without structured context, AI outputs are off-brand, non-compliant, or just generic — what Kristen Pol memorably calls "AI slop." As Pol put it, context is the difference between "AI that guesses" and "AI that gets it." Her project, the Context Control Center (CCC), also known as the AI Context module, provides a centralized hub within Drupal to capture and manage an organization's rules, policies, and guidelines, then map them directly to AI features. Instead of relying on vague prompts or scattered style guides, CCC treats context as managed content — with familiar Drupal capabilities like revisioning, scheduling, and scoping by workflow, language, or site section. That means an organization can declare rules and have them applied consistently across every AI output.

From UX to AX (Agent Experience). Brands now need to design experiences not just for humans, but for the AI agents acting on their behalf. As more website traffic comes from AI agents and crawlers rather than human visitors, organizations have to think about how their content, components, and APIs are "consumed" by machines — and how to ensure brand voice, accuracy, and trust are preserved when an agent is the one mediating the experience.

Data sovereignty and trust. Particularly relevant for the public sector, Amazee's Jeroen Spitaels emphasized guarantees of no data retention and no training on user data as essential for public sector institutions. For governments, universities, and any organization handling sensitive information, it's not enough for AI to be powerful — it has to be trustworthy, transparent, and sovereign. That means knowing exactly where your data lives, who has access, and being certain it isn't quietly being used to train someone else's model.

Where It Got Specific: Sessions Worth a Closer Look

Every summit has sessions that move beyond the conceptual and get specific. These three stood out because they tackled the operational realities of actually deploying AI — and what it takes to do it well.

The Actual Playbook for Deploying AI without Breaking Trust

John Doyle's session on implementing AI teams and workflows was one of the day's standouts because it tackled the operational reality of AI — not just the tech.

His core idea: stop thinking about AI as isolated prompts and start building "digital teammates" — governed agents with defined owners, SLAs, and clear inputs and outputs. That's a profound reframing. A digital teammate isn't a tool you use; it's a team member you onboard, manage, and hold accountable.

Doyle made a strong case for Drupal as the ideal platform for AI orchestration thanks to its API-first architecture, structured content model, and workflow states. He demoed AI integrated directly into a Drupal interface, generating content drafts based on predefined project briefs and design systems.

His operational advice was refreshingly grounded:

• Give every AI agent a charter — clear scope, purpose, and boundaries.
• Always maintain a human-in-the-loop for final verification.
• Iterate slowly to ensure quality control.

This is exactly the playbook organizations need if they want to actually deploy AI without breaking trust. At the end of his talk, I was able to speak with him, and he mentioned they had piloted this approach at Digital Polygon, and it was very successful.

What a Real AI-Powered Website Experience Actually Looks Like in Practice

John Tran, CTO of Image X, delivered the kind of real-world example I wanted to see. His session detailed how Drupal can be transformed from a static content management system into a dynamic, AI-orchestrated experience platform using AG-UI (Agent-to-User Interaction).

The technical foundation is semantic search — using embedding models and vector databases to map relationships between content, focusing on intent, context, and meaning rather than keywords. That allows the system to retrieve highly relevant information even when the user's phrasing is conversational.

The proof-of-concept for an advanced implementation of an AI chatbot was great to see. The system:

• Triggers specific tools dynamically (such as directions or live weather APIs)
• Renders interactive SDC (Single Directory Components) directly within Drupal based on the agent's logic
• Lets users flag content as they navigate, which the AI then aggregates into a customized, downloadable brochure or notebook

Tran's future vision is for Drupal to handle the orchestration of these experiences natively — moving away from rigid, pre-built pages toward fully dynamic, component-based websites where the entire site experience is generated or assembled on-the-fly based on the user's specific goals, all while maintaining site governance and using standard Drupal form-handling workflows.

Just as importantly, because the AG-UI toolkit is agent-agnostic, it prevents vendor lock-in — allowing developers to switch between LLM providers or agent frameworks without rebuilding the front-end experience.

This is what "richer interactivity" looks like in practice. It's still a chatbot at its core, but with a level of engagement and contextual awareness that genuinely solves problems rather than just answering questions. This felt less like a novelty and more like a higher-order assistant doing meaningful work.

Three Capabilities Your Platform Needs for an AI-First Internet

The Acquia session from Martin Anderson-Clutz framed something every digital team needs to wrestle with: in the evolving role of websites and an AI-first internet, content has to go everywhere — not just to your website, but to AI crawlers, agents, and downstream experiences you don't directly control.

To meet that reality, Anderson-Clutz advocated for three keys to a modern DXP:

Agile Content Engine. Beyond traditional drafting and publishing, organizations need to use AI to accelerate planning and ideation, optimize content post-publication for conversion, and embrace structured content in formats like JSON and Markdown for true omnichannel delivery.

Robust Experience Layer. As users increasingly turn to websites to validate purchase decisions rather than for education, the site's role shifts toward frictionless brand onboarding (social proof, case studies, technical specs) and context-aware AI that keeps brand voice accurate, on-brand, and aligned with strategic objectives.

Agent-Friendly Architecture. With non-human traffic rising, websites must be built for AI agents as primary users. That means treating "APIs as the new UI" — standardizing on machine-readable formats, adopting emerging agent-to-agent protocols, and designing systems that offer packageable "skills" or recipes for modular, autonomous agent interaction.

His core argument: Drupal is uniquely positioned as a leading, AI-ready platform because of its emphasis on structured content, enterprise governance, and community-driven innovation.

The takeaway: in a world where your content is increasingly consumed by machines before it ever reaches a human, the platforms that win will be the ones that treat AI agents as primary users — and Drupal is already there.

A Community Embracing AI

If one line captured the spirit of the day, it was this: "Drupal has quietly become one of the most AI-ready platforms available."

While much of the AI conversation centers on flashy chatbots and proprietary tools, Drupal has been steadily building exactly what AI agents need to do real work. That's not marketing spin — it's the natural outcome of 25 years of disciplined engineering around content structure, governance, and openness. The very things that made Drupal a leader in the structured-content era are the things AI agents require to operate reliably, safely, and at scale.

The Drupal community isn't just adapting to AI. It's quietly becoming one of the most credible, agent-ready platforms on the open web — and the summit made it clear we're just getting started.

Bring practical, proven AI adoption strategies to your organization, let's start a conversation! We'd love to hear from you.

Traditional content staging servers have had their day. This session makes the case for retiring them and shows how Drupal Workspaces does the job better.

Peta Hoyes (Partner/COO) and Ray Stuart (Senior Backend Engineer) walk through why staging sites are expensive, operationally complex, and risky for content teams. Then they show how Workspaces, stable in Drupal core since version 10.3 and shipping with every Drupal 11 install, replaces them. The architecture is straightforward: content branches that layer on top of your live site, full-site preview that reflects views, menus, layouts, and entity references in context, atomic publishing, and zero overhead on production traffic. Workspaces Extra (WSE) adds scheduled publishing, rollback, external reviewer links, access control, and configuration staging. The session closes with live demos and a look at why Workspaces is the right place to run AI content generation safely before anything touches production.

Note: Fabian Franz, Tag1 VP of Engineering who is a large and valued contributor to this session, was unable to join in person.

What You Will Learn

• Why staging servers break down at scale and what they cost
• How Workspaces works
• What Workspaces Extra (WSE) adds on top of core
• How to use a workspace as a safe sandbox for AI-generated content
• What is coming next in core

Transcript

From "I'll Get to It" to Done: Modernizing File Upload Secure Validator

I’ve been meaning to clean up the File Upload Secure Validator project and get it ready for Drupal 12 for a while now. This small, focused module has been around for nearly a decade. Despite its simplicity, it continues to serve more than 10,000 reported sites, and adoption has only accelerated with the introduction of Drupal AI. With the help of Cline and Claude, I finally did a full overhaul of the codebase: switching to Drupal 11-only support, expanding the automated test suite, and positioning the project for Drupal 12.

A Decade-Old Module Meets Drupal 12

This was the kind of maintenance work I kept putting off, the same feeling I get when I need to sit down and do my taxes. I knew the project needed cleanup and modernization, but I wanted a little push and some company in doing the work. The missing motivation and sense of camaraderie were, in many ways, the biggest challenges.

On top of that, I had a clear vision for how I wanted to extend the test suite, and I knew it would be time-consuming. Time, or the lack of it, was a major factor, especially for this kind of detailed, behind-the-scenes work on an open source module.

Turning a Wish List Into a Working Plan

To move things forward, I turned to Cline and Claude to help plan the future of the module. I started by writing down a list of "wishes" for the project: the improvements I wanted to see in the code, tests, and overall quality.

Cline turned that list into a detailed execution plan. It also generated questions about the approach, which led us into a few iterations before we settled on the final course of action. That planning process gave structure to the work and made it much easier to tackle in focused sessions.

All of the changes happened in the project's repository on the 2.2.x branch, with the final result released as version 2.2.1 on Drupal.org.

From Red CI Pipelines to Green Across the Board

Before this overhaul, the project had accumulated a number of issues:

• Multiple GitLab CI failures
• Drupal 11.3+ deprecation warnings
• Unit test failures (including static method and TranslatableMarkup issues)
• Limited test coverage
• 383+ PHPCS violations
• CSpell errors
• PHPStan attribute errors

After the overhaul, the picture looks very different:

• All GitLab CI tests passing
• Zero deprecation warnings
• 23 tests with 164 assertions
• 0 PHPCS errors and 0 warnings
• 0 CSpell errors
• 0 PHPStan errors
• 100% CI quality checks passing

This overhaul gave me the "manpower" and momentum I was missing to push the project forward. Just as importantly, it gave me confidence that I can continue supporting this module in the future.

AI-Amplified Maintenance for Critical Dependencies

Maintaining and supporting open source libraries can often become demanding because of limited time and resources. In client projects, dependencies on under-maintained open source projects can increase the effort required to maintain or upgrade the client's own platform.

Partners like Cline and Claude can change the game in an advantageous way. Such a change can help teams keep critical open source dependencies up to date, improve quality, and reduce risk without requiring a huge amount of extra human capacity.

Bring practical, proven AI adoption strategies to your organization, let's start a conversation! We'd love to hear from you.