AI-assisted WordPress development isn't magic. Here's how we built it into Chisel.

There's a version of this story where you type a sentence, an agent writes a perfect WordPress theme, and the developer sips coffee while the work does itself. That's not the story we're going to tell.

The truth is less magical and more useful. Over the past year, we (the dev team at xfive) have built an AI toolkit into Chisel, our WordPress development framework, by taking everything we already knew about building WordPress sites well, from conventions to judgment calls to the things a new hire normally just picks up by watching someone else, and writing it down carefully enough for an agent to follow.

Why we brought AI into Chisel

We added AI because we kept doing the same setup work by hand: registering blocks, wiring up custom post types, enqueuing scripts, and scaffolding patterns. We wanted it done our way every time, by every developer, whether they'd been with us five years or five weeks, without trading our standards away for speed. And if we were going to bring AI into client projects, we wanted our own good experience with it first, on our own terms.

Four disciplines, not one clever prompt

Working well with an agent comes down to four separate disciplines: deciding what to hand off, briefing it clearly, judging what comes back, and taking responsibility for the result. Skip any one, and the whole thing falls over. "Prompt and pray" is really just the briefing, with the other three thrown away.

Our toolkit is those four disciplines made concrete. The rules and skills are the brief. The two human checkpoints are where a developer judges the work and owns it. And deciding which tasks are worth handing over at all is a call we make before anything starts. If you want the formal version of this, it maps closely to the 4D framework for AI fluency.

What we built is the AI toolkit

The toolkit ships with every new Chisel project, and the agent reads it at the start of every task. It's open source, and designed to be token-efficient, split into many small files the agent loads on demand rather than one giant instruction file.

At the root sits the entry point: CLAUDE.md and AGENTS.md. It's an always-loaded table of contents that carries the load-bearing rules and routes the agent to the right detail for the task. We keep both files because the kit is deliberately model-agnostic. We run it on Claude Code and on Codex, and the shared AGENTS.md convention keeps it portable.

‍

Underneath, the kit follows a simple split into what, how, and examples:

CLAUDE.md / AGENTS.md          # entry point: load-bearing rules + routing
ai/
├── ai-new-session-prompt.md   # the "start here" prompt for every session
├── rules/
│   ├── reference/             # the WHAT: facts like file locations, design
│   │                          #   tokens, block/CPT conventions, Twig,
│   │                          #   REST API, MCP workflow, WooCommerce…
│   └── templates/             # the EXAMPLES: copy-paste code scaffolds
└── skills/                    # the HOW: step-by-step procedures,
                               #   discovered and run by the agent

The reference docs are the what: where things live, how a feature works, what our naming conventions are. The skills are the how: ordered recipes for producing something, like scaffolding a block or turning a Figma design into Chisel components, which the agent discovers and follows on its own when a task calls for one. We keep those apart on purpose. A file that tries to be both is harder for an agent to follow. The templates are concrete structural scaffolds the agent copies from only when it's writing code. The loading flow is always the same: entry file, then the matching reference doc, then the matching skill, then a template if code needs copying.

We also wrote a New Session Prompt template, so everyone starts a session identically and we can be sure the agent has actually read the instructions before it touches anything.

How the agent actually works

This is where "not magic" becomes visible. The agent doesn't free-wheel from prompt to pull request. It moves through a fixed loop with two points where it stops and waits for a human.

After you describe a task, the agent loads the kit and checks whether there's work already in flight. Then it triages the request, and trivial fixes skip the ceremony and go straight to verification. For real work, it reads the relevant code and reference material, then stops to clarify and lock decisions with you. Only once decisions are locked does it write a plan. Then it stops again at the gate and waits for your go-ahead before building. After building, it verifies against build, tests, and lint, hands off a summary with an offer to commit, and loops back for the next task.

Those two stops, Clarify and Gate, matter more than anything else in the loop. At both, the agent proposes and a developer signs off before anything moves forward.

Say you ask for a hero section. The agent loads the kit, reads the relevant blocks and reference docs, then stops to clarify: an ACF block or a pattern, which fields it needs, how the heading maps to the design. You settle those questions and it writes a plan. It stops again at the gate; you approve. Only then does it scaffold the block, and the MCP inserts it into a real page so you can preview the result in WordPress, with no manual block-building. You review, it offers to commit, and it's ready for the next task.

Keeping track with progress files

For anything non-trivial, the agent keeps a written trail in plain markdown, committed to the repo under ai-progress/. It's split three ways:

• INDEX.md is the router. Every task shows up there, grouped into Active and Done, one line each. It's read first, always.
• FINDINGS.md collects incidental bugs and observations the agent notices along the way.
• changes/{NN}-{task}/ is one self-contained folder per task, holding a ROADMAP.md (scope, locked decisions, and a phase table), an append-only LOG.md, and one file per phase.

The roadmap's phase table is the only status surface.

Each phase is marked not started, in progress, done, or blocked, and every finished row carries a one-line outcome so nobody reopens settled work. A cold session reads the index, then the active roadmap, then only the current phase file. That's three small files to read, not a tour of the whole codebase.

Phase files are written when the phase starts, so they serve as the plan a human approves before any code exists.

And log lines are written toward what comes next, so the trail ends in a runway rather than a receipt. The practical payoff: the full state of a project is remembered, several people can pick up where someone else left off, and there's a genuine history of what changed and why, the kind a code reviewer relies on to understand a change and your future self relies on months later.

Why you still need to know WordPress

The toolkit only works because we already knew how to build WordPress well, everything from our conventions and architecture to the preferences that come from years of shipping. That expertise paid off most in testing and debugging. Because we know Chisel inside out, we could tell immediately when the agent was heading in the wrong direction, often as early as the plan, before a line of code existed, and steer it back.

Naming was the clearest case. Left alone, an agent gets creative with names, and consistent naming across projects, for ACF field groups and everything else, is exactly what we'd spent years standardizing, so the rules pin our conventions down. We also had to tell it to reuse existing blocks (from WordPress core, Chisel, or the project) before building new ones, because left to itself it cheerfully rebuilt from scratch what was already there.

Other rules spell out mechanical traps the agent can't infer. Our rules explain how block.json works in general, so the agent understands what belongs where, and we had to be explicit that a block's CSS must be imported into that block's JS file or Webpack won't compile it. A handful of smaller rules cover the rest: our custom ignoreScripts flag, keeping each block's scripts in its own folder instead of a global one, and the wrapper convention our patterns follow. We also prefer ACF over native blocks, which meant being explicit about what belongs in project code versus what's added through the editor.

The single most important principle is that the rules never hard-code specific values.

They describe Chisel's starter state, not any one project's customized state. The moment a project changes its button padding, its color values, or its spacer names, anything we'd written into the rules would go stale without anyone noticing, and an agent that confidently cites stale facts is worse than one that stops to look. So only stable invariants live in the rules: protected slug names, namespace conventions, file-layout patterns, build-pipeline mechanics. Everything project-specific, the agent reads from the project itself. That single decision is the difference between rules you can trust and rules that lie to you.

The WordPress MCP

The other piece is our WordPress MCP server, xfive-mcp. It's open source, built on the WordPress Abilities API and a WordPress MCP adapter, and it connects what the agent builds to a live WordPress site.

Once the agent has created a set of blocks, the MCP inserts them into a page as real Gutenberg blocks so a developer can preview the result, no manual clicking required, and it can push work straight into WordPress, deployments included. It can also create categories, generate test data like sample products, read posts, and update or remove content, all through WordPress's own functions. Most of what it deletes goes to the trash, exactly as it would from the admin, rather than vanishing. It works through WordPress instead of behind its back, which also makes it universal. It isn't tied to Chisel, so you can use it on any WordPress project.

A few things we didn't expect going in

The biggest surprise was how much better AI is at backend work than frontend, even with a Figma MCP in the mix. Backend tasks are mostly logic, and logic is where models are strong. The frontend is where it struggles, because there it has to reproduce a design faithfully and make it hold up across screen sizes and browsers. Our designs tend to be visually rich, with backgrounds and elements that span multiple sections and pieces that need to sit just so. The agent can produce something that looks right in one place, but it often breaks in other browsers, or drops or misplaces elements. The Figma side is really two different jobs: pulling content and structure out of a design into the database works well and kills the tedious copy-paste, but reproducing the visual design faithfully across browsers and screen sizes is what still fights us.

We also learned it's better to start from our idea and have the agent execute it than to let it invent an approach wholesale. Writing good instructions turned out to be an iterative craft (you test on real projects, watch where the agent stumbles, and refine), and it's a moving target, because the models themselves keep changing. One model will phrase something in a way another model then misreads, so we test across models to be sure. So the toolkit stays a permanent work in progress that a developer has to own and keep in line.

The payoff is straightforward

Repetitive work goes faster, less-experienced developers get into a project more easily because the standards are already encoded, and we have confidence our best practices are being followed rather than hoped for. It's also a genuinely different, fun way of working: thinking in terms of how agents behave and how to collaborate with them.

The first version of the toolkit took a few days to build. Everything since has been steady refinement, one project's lessons at a time. Next up is packaging the AI toolkit for npm so it's even easier to bring into a project. The process doesn't really have an endpoint, not with how fast this space moves, and it'll only get better.

Chisel itself has its own longer backstory, a decade of WordPress lessons that shaped the framework this toolkit sits on top of, and it's a separate piece in its own right. The AI toolkit and xfive-mcp are both open source, so if you want the details, the code is the real documentation.

‍