STD-DRUPAL-AI-001: Drupal AI Initiative Architecture & Net-Negative Ownership Policy¶

Status: Approved Governing Standard Owner: Bluefly Engineering / DrupalWorks Beads: bc-6m1b, bc-qysf, bc-5o48

1. Prime Directive¶

Bluefly owns composition and consumption — not unnecessary custom code.

We follow a strict net-negative ownership policy: 1. Core → Contrib → Recipes → Canvas/SDC → ECA/FlowDrop → Drupal AI → Tool API/MCP → only then custom code as a last resort. 2. If an upstream project, module, or recipe already provides a capability (agent execution, tool bridging, RAG search, recipe validation, security audit), Bluefly projects MUST configure or contribute to the upstream project. 3. Custom PHP scripts, hand-crafted bash parser formulas, and custom agent runtimes are forbidden when an upstream Contrib module exists.

2. Upstream 6-Stage Outside AI Roadmap Alignment¶

All Bluefly agentic Drupal operations follow the upstream Drupal AI Initiative roadmap (git.drupalcode.org/project/ai_initiative, work item 3576908):

Stage 1: Supported Drupal Baseline (drupal_cms_ai recipe)
  ↓
Stage 2: Scoped Attributable Authority (simple_oauth + mcp_server_oauth)
  ↓
Stage 3: Machine-Readable Site Discovery (Tool API / OpenAPI)
  ↓
Stage 4: Governed Operations (Tool API + Tool Belt + mcp_server)
  ↓
Stage 5: Verification & Observability (WITNESS + Drupal AI Observability)
  ↓
Stage 6: Drupal-Native Recipes & Handoff (drush recipe)

Stage 4 Execution Law (Governed Interfaces)¶

Tool API (drupal/tool) & Tool Belt (drupal/tool_belt) are the sole governed execution surfaces for Drupal capabilities.
MCP Server (drupal/mcp_server) is the mandatory external transport bridge for STDIO and HTTP MCP agents (Claude Code, Cursor, external LLM agents).
No synthetic users or role mutation: Actions run as the authenticated person or bounded service identity.

3. Canonical 10-Layer Package Baseline¶

All Bluefly Drupal projects inherit this composition stack:

Layer	Upstream Capability Owner	Package(s)
1. Baseline	Drupal CMS AI Recipe	`drupal/drupal_cms_ai`
2. Drupal AI	Drupal AI Core & Agents	`drupal/ai`, `drupal/ai_agents`, `drupal/ai_agents_debugger`, `drupal/ai_agents_ossa`, `drupal/ai_context`, `drupal/ai_dashboard`, `drupal/ai_integration_eca`, `drupal/ai_policy_gateway`
3. Providers	LLM Provider Modules	`drupal/ai_provider_openai`, `drupal/ai_provider_anthropic`, `drupal/ai_provider_ollama`
4. Tool API	Executable Capability Engine	`drupal/tool`, `drupal/tool_belt`
5. MCP Transport	External Agent Transport	`drupal/mcp_server`, `drupal/mcp_tools`
6. Canvas / UI	Modern Component Builder	`drupal/canvas`, `drupal/canvas_builder`, `drupal/canvas_ai_seo`, `drupal/ai_playwright`
7. Workflow	Event Automation & Modeler	`drupal/eca`, `drupal/ai_integration_eca`, `drupal/modeler_api`, `drupal/modeler`, `drupal/bpmn_io`, `drupal/flowdrop`, `drupal/flowdrop_ai_search`, `drupal/orchestration`
8. Search / RAG	Semantic Search API	`drupal/search_api`, `drupal/ai_search`, `drupal/ai_search_block`, `drupal/ai_vdb_provider_qdrant`
9. Infrastructure	Key & Metadata	`drupal/key`, `drupal/metatag`, `drupal/simple_sitemap`
10. Performance	SDC Critical CSS	`drupal/sdc_critical_css`, `drupal/non_critical_css`

Explicit Exclusions¶

drupal/ai_logging is EXCLUDED. Use Drupal AI's native AI Observability submodule for PSR-3/OpenTelemetry integration.
Legacy drupal/mcp is DEPRECATED. Migrate to drupal/mcp_server.

4. Package Resolution Discipline¶

{
  "minimum-stability": "alpha",
  "prefer-stable": true
}

Do not pin exact versions. Allow Composer to resolve the newest compatible release across the ecosystem.