Intent

Config records what your site is. Intent records why.

Drupal configuration is thorough about what - content types, fields, views, automation. It says nothing about why. When an AI agent (or a new developer) does a cleanup pass months after a site was built, it sees a field that looks redundant, an automation that looks unused, a disabled consent app that looks like dead weight - and deletes them. The change is defensible from the config alone. It is also wrong, because the reason those things exist was never recorded anywhere the agent looks.

Intent stores that reason as one plain-language string, attached to the configuration itself:

third_party_settings:
  intent:
    value: 'Feed dedupe key: matches incoming videos to existing nodes so re-imports never create duplicates or overwrite editor edits.'

Config entities carry intent in third-party settings, so it exports, imports, and is deleted together with the entity. Simple config and other stable targets use a small intent.record.* sidecar config entity with dependency-aware cleanup. A JSON CLI (intent:get, intent:set, intent:list, intent:delete, intent:prune) reads and writes both.

Does it work?

We tested it on a real installed site with a deliberate trap: fields that look redundant but are load-bearing. Agents were asked to "clean up the redundant fields," and damage was measured mechanically from config-export diffs - never from what the agent claimed.

• With intent attached to the config: 0 of 15 runs deleted a load-bearing field (Claude Opus/Sonnet/Haiku, 5 runs each). Agents still removed the genuinely redundant fields - informed, not frozen.
• Without any rationale: about 1 in 3 runs destroyed load-bearing config, including the feed dedupe key.
• The same rationale text placed in a docs file instead of the config: 47% blast - no better than nothing. Placement at the point of decision is the mechanism, not the text.

Full method, tables, and honest limits (small samples, one template so far, and one model family that ignores passive context entirely) are in the module's docs/evidence.md.

What intent is not

Intent is a spec, not a lock. It does not block changes, enumerate safe operations, or replace review - an agent with a real reason can still override it. The harm it prevents is uninformed change. It is also not a general safety system: it decides ambiguous forks; it does not make a careless model careful.

For recipe and site template authors

This is where intent pays off most. Your config lands on many sites; agents doing maintenance downstream cannot see your design decisions. One sentence from you - shipped in your recipe or config - protects every site built on your work. See docs/recipe-and-template-authors.md in the module. Empire is the reference implementation: its release ships intent on its load-bearing config.

Requirements

• Drupal core ^11.4 (uses the core CLI; commands run via vendor/bin/dr)
• No UI, no Drush commands, no content entities — the runtime is deliberately small

Roadmap

• A curated intent layer for the shared Drupal CMS configuration surface (consent, media, mail - where testing shows agent damage actually concentrates)
• Surfacing intent in the write path (Tool API / MCP preflight) for agents that do not read passive context
• Replication of the behavioral results on templates beyond Empire