requires: image, responsive_image, breakpointdescribes: Wire Drupal responsive image styles, breakpoints, and field display modes from declared image use-cases per content type.
Scope, eventually
Load on demand. Not installed. Updated when the modules and core the recipe sits on move, because I have been refining my atomic guides by hand long enough to know the same maintenance applies one layer up. I am wiring the update automation into my own setup right now, but the format is what matters. The format has to allow that automation for anyone who wants to build it, not depend on any one person owning it.Then I realized I needed opinions in a form the framework could carry. Some opinions are rules. Use drush commands, not raw PHP, when you need to do something to Drupal from the command line. Use Composer in the right order when you remove a module. Mobile-first breakpoints with sizes-based responsive images for content body, breakpoint-based for art-directed hero. Rules. One rule, applied across many contexts.—
Research, and the guides
produces: image styles, responsive image styles, field display config per view mode per content typeSo I broke them apart. One decision per file. One question, one answer. Published online so we could both reach them from any project, and so the agent could fetch only what the current task needed. That is the atomic guides. Around 1,600 of them now, across 88 topics, with routing metadata that lets the agent decide which one to read for which question.I was surprised by how often the first sentence I wrote into scope made me realize I had been about to build the wrong thing.Scope is the first step in my workflow now, but it was not the first step I added. It became the first step after I watched the AI solve a different goal than the one I had asked for, over-engineer changes that did not need engineering, and reach for the wrong abstraction often enough that I needed a step that just stopped the work and named what we were actually doing.
Design, implementation, and a lot of review
Hence recipes. Not a guide, because guides are atomic and a recipe carries orchestration over multiple atoms. Not a playbook entry, because that is a single rule, and an orchestration is by definition more than one decision. Not a skill, because a skill is something the AI installs, sitting in the agent’s front-matter for every session, whether this project needs responsive image wiring or not. A recipe is something the agent reads when this project needs this capability, and skips otherwise.I do this in Drupal because Drupal is my community. The pattern is the same anywhere there is a stable capability layer above atomic APIs. Next.js. Rails. Design systems. Anywhere the orchestration of a named feature is repeatable but the choices inside it are project-specific.
Opinions, and the playbook
After scope and research came design and implementation. The patterns here are well-trodden. Phase the work. Set acceptance criteria before writing. Test first when the test is cheaper than the code it is checking. Ask the human at each step that is hard to reverse. Nothing original. The win is consistency. The AI does not do this on its own unless I make the workflow visible, so I made it visible.I called this layer the playbook, at the project level. Local rules always win on conflict. Published sets you can subscribe to for the patterns you keep using across projects. That worked. The agent stopped reaching for raw PHP when drush was the right tool, and stopped picking breakpoint-based responsive images for body content where sizes-based was the cleaner answer.
The wall
Working on the biggest tool I am still building, the one that takes a brand definition and walks all the way to an implemented app, I hit a wall I had to name.That worked, until I noticed the AI was missing pieces. Not in the small guides. In the structured ones, the ones with sequences and decisions. When you ask the AI to read a guide via WebFetch, the content gets summarized on the way in. Some steps survive. Some get described in vaguer language. Some get dropped. The agent does not know which is which.The mental model is straight. The first ten lines describe the feature, like a skill’s frontmatter, so the agent can read just that and decide whether to keep going. Roughly:Research came next. I started with local frameworks for the Drupal work I do a lot of. ECA module workflows. AI module pipelines. Each framework grew the way these things grow, full of decisions I had made and forgotten and made again differently. Eventually the frameworks got too big to share with my wife. She would not have read them, and I could not have pointed her at one piece without dragging in twenty others.I built my AI tooling first to help me work on Drupal projects and sites, and on the Claude Code plugins I develop. My wife uses the same tooling in her job now, which is the part that turned a personal hack into something I had to actually maintain.
Recipes
—So I forced curl. Bytes in, bytes read. No summarization layer between the agent and the content. The skill that fetches my guides is built around this rule, and three different places in its prose remind the agent why curl is mandatory. The rule is enforced by the skill, not by a hook, but the skill is invoked on every fetch, so in practice it holds.
| Use drush is a playbook instruction. It is a rule about how to do a class of things in this project when I am using Drupal. That shape is fine. The playbook holds it well.Use drush is a playbook instruction. It is a rule about how to do a class of things in this project when I am using Drupal. That shape is fine. The playbook holds it well. |
I had no artifact for the second one. The playbook covers pieces. There is even an entry called responsive-image-sizing-per-context, which is a real rule that applies in a real way. But the end-to-end orchestration of wire-responsive-images-for-this-project lives in chat threads, where I walk the agent through the project’s image strategy by hand. 16:9 at full width for a hero. 16:9 in a card, same ratio but a different image style because the rendered size is different. 4:3 portrait somewhere else. Every project has its own strategy, and the agent has to translate it into image styles, breakpoints, and field display assignments per view mode per content type. I keep saying roughly the same sequence with slightly different wording, and the agent keeps doing roughly the same thing with slightly different quality.Below that header, the body. The opinion (how we do it, what we refuse to do). The sequence of steps, each citing its atomic source so the agent fetches the decision rather than guessing it. The data flow from the declared inputs to the applied Drupal state. The repetition pattern (once, per content type, per view mode). The contract for what state the recipe reads before it acts. References, with the curl rule honored, so the agent reads bytes and not summaries.I am sharing this to see if it resonates. I built each layer of my tooling because something was breaking when I did not have it, and recipes are the latest piece in that sequence. Orchestration plans for named capabilities. Loaded on demand. Not installed. I would like to know whether other people running AI on real projects are hitting the same wall, the one where you can feel the difference between a rule and an orchestration but you have no artifact to hold the second one. If you are hitting it, I would like to hear from you.Scope is not necessarily specs. Specs are how. Scope is what we are even doing here, and what we are not doing, and what counts as done. Now it runs before anything else, and short alignment checks ride along through the later stages so the agent does not drift back into its own version of the goal.
