Skip to main content

MASTER Drupal AI Integration Plan - Agent Orchestration

MASTER DRUPAL AI INTEGRATION PLAN

Multi-Agent Orchestration for Complete Drupal AI Ecosystem Integration

Created: 2026-01-08 Status: IN EXECUTION Agents Required: 45 specialized agents Completion Target: Q1 2026

CRITICAL RULES - NEVER VIOLATE

Rule #1: CHECK DRUPAL.ORG FIRST

BEFORE writing ANY custom code, ALWAYS:

  1. Search Drupal.org for existing modules
  2. Check if Drupal core provides the functionality
  3. Review contrib module APIs and services
  4. Use existing solutions - DO NOT REINVENT THE WHEEL

Rule #2: FOLLOW THE DRUPAL WAY

  • Use dependency injection (NO \Drupal:: calls)
  • All lines 80 characters
  • Proper type hints and return types
  • DocBlocks for all functions
  • declare(strict_types=1); at top of all PHP files
  • Use Drupal services, plugins, and hooks

Rule #3: DRY (Don't Repeat Yourself)

  • Check ALL existing modules before creating new code
  • Reuse services across modules
  • Abstract common patterns into shared base classes
  • Use Drupal traits for shared functionality

Rule #4: LATEST CODE ALWAYS

  • Pull from remote BEFORE starting work
  • Verify you have latest from Drupal.org
  • Check issue queues for patches
  • Review recent commits

PHASE 0: PRE-EXECUTION AUDIT (AGENTS 1-5)

Agent 1: Remote Repository Auditor

Task: Audit ALL GitLab repos for Drupal projects Deliverable: DRUPAL-PROJECTS-INVENTORY.csv

Commands:

glab api '/groups/blueflyio%2Fagent-platform/projects?per_page=100' | \
  jq -r '.[] | select(.name | test("drupal|recipe|ai_|mcp_"; "i")) |
  {name, web_url, last_activity_at, open_issues_count}' > inventory.json

Output: Complete list of all Drupal-related projects with:

  • Project name
  • GitLab URL
  • Last activity date
  • Open issues/MRs
  • Drupal version
  • Dependencies

Agent 2: Drupal.org Module Auditor

Task: Search Drupal.org for EVERY module we might need Deliverable: DRUPAL-ORG-MODULES.md

Modules to Check:

  • drupal/ai - AI provider interface (48+ providers)
  • drupal/ai_agents - Agent management
  • drupal/ai_mcp - Model Context Protocol
  • drupal/ai_vector - Vector database integration
  • drupal/eca - Event-Condition-Action
  • drupal/flowdrop - Visual workflow builder
  • drupal/flowdrop_ai_provider - FlowDrop AI integration
  • drupal/flowdrop_ui_agents - FlowDrop agent UI
  • ? drupal/ai_orchestrator - Agent orchestration
  • ? drupal/ai_anthropic - Anthropic provider
  • ? drupal/ai_openai - OpenAI provider
  • ? drupal/ai_langchain - LangChain integration
  • ? drupal/ai_search - AI-powered search
  • ? drupal/ai_content - AI content generation
  • ? drupal/gitlab_integration - GitLab integration
  • ? drupal/json_api_extras - Enhanced JSON:API
  • ? drupal/graphql - GraphQL API
  • ? drupal/key - API key management
  • ? drupal/token - Token system
  • ? drupal/webform - Form builder
  • ? drupal/rules - Business rules engine

Action: For EACH module:

  1. Check if it exists on Drupal.org
  2. Read documentation
  3. Check recent issues/patches
  4. Verify D11 compatibility
  5. Document API and services
  6. List what it REPLACES (so we don't rebuild)

Agent 3: Local Repository Sync Manager

Task: Pull latest from ALL local Drupal repos Deliverable: All repos at HEAD, conflicts documented

Script:

#!/bin/bash
DRUPAL_REPOS=(
  "secure_drupal_recipe.bare"
  # Add all from Agent 1's inventory
)

for repo in "${DRUPAL_REPOS[@]}"; do
  echo "=== Updating $repo ==="
  git -C "_Source/$repo" fetch --all --prune
  git -C "_Source/$repo" pull --rebase
done

Agent 4: DRY Validation Auditor

Task: Check for duplicate code across ALL Drupal modules Deliverable: CODE-DUPLICATION-REPORT.md

Tools:

# Use PHPMD Copy/Paste Detector
phpmd all_drupal_custom/ text codesize,unusedcode,naming

# Use PHP Copy/Paste Detector
phpcpd all_drupal_custom/modules/

Report:

  • Files with duplicate code
  • Common patterns that should be abstracted
  • Services that should be shared
  • Traits/base classes to create

Agent 5: Drupal Standards Validator

Task: Validate ALL existing code against Drupal standards Deliverable: STANDARDS-VIOLATIONS.md

Tools:

# PHPCS with Drupal standards
phpcs --standard=Drupal,DrupalPractice \
  --extensions=php,module,inc,install,test,profile,theme \
  all_drupal_custom/

# PHPStan level 8
phpstan analyse all_drupal_custom/ --level=8

# Check line length
grep -r ".\{81,\}" all_drupal_custom/ --include="*.php"

PHASE 1: DRUPAL.ORG MODULE RESEARCH (AGENTS 6-15)

Each agent researches ONE module thoroughly

Agent 6: drupal/ai Research

Task: Deep dive into drupal/ai module Deliverable: research/drupal/09-ai-module-analysis.md

Research:

  • All provider plugins available
  • Service architecture
  • How to extend with new providers
  • Configuration options
  • API examples
  • GitLab AI Gateway integration possibilities

Agent 7: drupal/ai_agents Research

Task: Deep dive into drupal/ai_agents module Deliverable: research/drupal/10-ai-agents-module-analysis.md

Research:

  • Agent entity structure
  • Tool system architecture
  • How to define custom tools
  • Agent execution lifecycle
  • Multi-agent orchestration
  • OSSA compatibility

Agent 8: drupal/eca Research

Task: Deep dive into drupal/eca module Deliverable: research/drupal/11-eca-module-analysis.md

Research:

  • Event system (200+ events)
  • Condition system (70+ conditions)
  • Action system (500+ actions)
  • BPMN.io integration
  • AI-enhanced ECA patterns
  • Custom event/condition/action creation

Agent 9: drupal/flowdrop Research

Task: Deep dive into drupal/flowdrop module Deliverable: research/drupal/12-flowdrop-module-analysis.md

Research:

  • DAG execution engine
  • Node types available
  • Custom node creation
  • Svelte UI architecture
  • Integration with ai_agents
  • Workflow export/import

Agent 10: drupal/ai_mcp Research

Task: Deep dive into drupal/ai_mcp module Deliverable: research/drupal/13-ai-mcp-module-analysis.md

Research:

  • MCP server implementation
  • MCP client implementation
  • Tool registration
  • How to expose Drupal entities as MCP tools
  • Integration with external MCP servers

Agents 11-15: Additional Module Research

  • Agent 11: drupal/ai_vector - Vector database integration
  • Agent 12: drupal/key - API key management
  • Agent 13: drupal/graphql - GraphQL API
  • Agent 14: drupal/json_api_extras - Enhanced JSON:API
  • Agent 15: drupal/webform - Form builder integration

PHASE 2: INTEGRATION MODULE DEVELOPMENT (AGENTS 16-30)

Only create modules if functionality doesn't exist in contrib

Agent 16-17: blueflyio_ai_gateway (IF NEEDED)

Task: Create GitLab AI Gateway integration Pre-check: Does drupal/ai support custom providers?

If YES: Use provider plugin system, don't create new module If NO: Create minimal integration module

Deliverable:

  • Module OR documentation on using existing provider system
  • Configuration for GitLab AI Gateway endpoint
  • Token tracking integration

Agent 18-19: blueflyio_ossa_bridge (IF NEEDED)

Task: Bridge Drupal AI Agents to OSSA Pre-check: Can drupal/ai_agents export to OSSA format?

If YES: Document export process If NO: Create bridge service

Deliverable:

  • OSSA manifest generator service
  • Validation against OSSA v0.2.8
  • Sync to GitLab components

Agent 20-21: blueflyio_eca_ai (IF NEEDED)

Task: AI-enhanced ECA automation Pre-check: Does drupal/eca have AI action plugins?

If YES: Document usage If NO: Create AI action plugins for ECA

Deliverable:

  • ECA action plugins for AI calls
  • Condition plugins for AI evaluation
  • Examples and documentation

Agent 22-23: FlowDrop ECA Bridge (IF NEEDED)

Task: Convert FlowDrop workflows to ECA Pre-check: Can FlowDrop export to ECA format?

Deliverable:

  • Conversion service
  • Both directions (FlowDrop ECA)
  • UI integration

Agent 24-25: Agent Marketplace UI

Task: Create agent discovery and installation UI Pre-check: Does drupal/ai_agents have marketplace features?

Deliverable:

  • Agent listing page
  • Search and filtering
  • Installation workflow
  • Rating and reviews

Agent 26-27: GitLab Integration

Task: GitLab API integration for Drupal Pre-check: Does drupal/gitlab_integration exist?

Deliverable:

  • GitLab API client service
  • Webhook receivers
  • MR entity type
  • Issue entity type
  • CI/CD status displays

Agent 28-29: Vector Search Integration

Task: Integrate vector search with Drupal search Pre-check: Does drupal/ai_vector provide search integration?

Deliverable:

  • Search API integration
  • Views integration
  • Vector similarity search
  • Hybrid search (keyword + vector)

Agent 30: Custom Code Validator

Task: Validate that we're not reinventing the wheel Deliverable: Report of any custom code that duplicates contrib

PHASE 3: DOCUMENTATION (AGENTS 31-40)

Agent 31: Master Architecture Documentation

File: developer-guides/drupal/ai-architecture.md Content: Complete system architecture with all integrations

Agent 32: Quick Start Guide

File: developer-guides/drupal/quick-start-ai.md Content: 15-minute setup guide from zero to first agent

Agent 33: ECA + AI Patterns

File: developer-guides/drupal/eca-ai-patterns.md Content: 25+ common ECA + AI automation patterns

Agent 34: FlowDrop Tutorials

File: developer-guides/drupal/flowdrop-tutorials.md Content: Step-by-step FlowDrop workflow creation

Agent 35: Agent Development Guide

File: developer-guides/drupal/agent-development.md Content: How to create custom agents from scratch

Agent 36: OSSA Compliance Guide

File: developer-guides/drupal/ossa-compliance.md Content: Ensure Drupal agents meet OSSA spec

Agent 37: GitLab Integration Guide

File: developer-guides/drupal/gitlab-integration.md Content: Complete GitLab Duo + Drupal integration

Agent 38: API Reference Generator

File: api-reference/drupal/*.md Content: Auto-generate API docs from code

Agent 39: llms.txt Generator

File: drupal/llms.txt Content: AI-friendly documentation index

Agent 40: Video Tutorial Scripts

File: tutorials-and-examples/drupal/video-scripts/ Content: Scripts for 10 video tutorials

PHASE 4: TESTING & DEPLOYMENT (AGENTS 41-45)

Agent 41: Unit Test Generator

Task: Generate PHPUnit tests for all custom services Coverage Target: 80%+

Agent 42: Integration Test Suite

Task: Create Drupal functional tests Tests: Agent execution, ECA workflows, FlowDrop conversions

Agent 43: DDEV Environment Setup

Task: Complete DDEV configuration Deliverable: One-command environment setup

Agent 44: CI/CD Pipeline Generator

Task: Create GitLab CI templates for Drupal modules Deliverable: Reusable component for all Drupal modules

Agent 45: Production Deployment Validator

Task: Pre-production checklist automation Deliverable: Automated validation before deploy

AGENT ORCHESTRATION STRATEGY

Sequential vs Parallel Execution

Sequential (Must complete in order):

  • Phase 0 Agents 1-5: Must complete before Phase 1
  • Agent 2 (Drupal.org audit) must complete before Phase 2

Parallel (Can run simultaneously):

  • Phase 1 Agents 6-15: All can run in parallel
  • Phase 2 Agents 16-30: Can run in parallel after Phase 1
  • Phase 3 Agents 31-40: Can run in parallel after Phase 2

Execution Plan

Day 1: Phase 0 - Audit (Sequential)

# Spawn agents in sequence
claude-agent spawn --task "Agent 1: Remote Repo Audit"
claude-agent spawn --task "Agent 2: Drupal.org Module Audit"  # Wait for 1
claude-agent spawn --task "Agent 3: Local Sync"  # Wait for 1
claude-agent spawn --task "Agent 4: DRY Validation"  # Wait for 3
claude-agent spawn --task "Agent 5: Standards Validation"  # Wait for 3

Day 2-3: Phase 1 - Research (Parallel)

# Spawn all 10 research agents at once
for agent in {6..15}; do
  claude-agent spawn --task "Agent $agent: Module Research" &
done
wait

Day 4-7: Phase 2 - Development (Parallel with checks)

# Each agent checks if custom code is needed first
for agent in {16..30}; do
  claude-agent spawn --task "Agent $agent: Integration" \
    --pre-check "Verify no contrib solution exists" &
done
wait

Day 8-10: Phase 3 - Documentation (Parallel)

# All documentation agents can run simultaneously
for agent in {31..40}; do
  claude-agent spawn --task "Agent $agent: Documentation" &
done
wait

Day 11-12: Phase 4 - Testing (Mixed)

# Tests and deployment in sequence
claude-agent spawn --task "Agent 41: Unit Tests"
claude-agent spawn --task "Agent 42: Integration Tests"
claude-agent spawn --task "Agent 43: DDEV Setup"
claude-agent spawn --task "Agent 44: CI/CD Pipeline"
claude-agent spawn --task "Agent 45: Deploy Validation"

VALIDATION CHECKLIST (Before ANY code is written)

Pre-Code Validation (MANDATORY)

For EVERY task, ask:

  1. Does Drupal core provide this functionality?
  2. Does a contrib module provide this functionality?
  3. Can I extend an existing module instead of creating new?
  4. Have I read the module's documentation?
  5. Have I checked the module's issue queue?
  6. Have I reviewed recent commits?
  7. Is this functionality in another module I already have?
  8. Can I use a service/plugin/hook instead of custom code?

If YES to any of above DO NOT WRITE CUSTOM CODE

Drupal Standards Validation

For ALL code written:

  1. All lines 80 characters
  2. declare(strict_types=1); at top
  3. Dependency injection (no \Drupal:: calls)
  4. Type hints on all parameters
  5. Return types declared
  6. DocBlocks with @param and @return
  7. PHPCS passes (Drupal, DrupalPractice)
  8. PHPStan level 8 passes
  9. No duplicate code (checked with phpcpd)
  10. Services properly registered in *.services.yml

PROGRESS TRACKING

Wiki Pages to Create

All documentation goes in: /Users/thomas.scola/Sites/Agent-platform/_Source/_WIKIs/technical-docs.wiki/

Required pages:

  • developer-guides/drupal/MASTER-DRUPAL-AI-INTEGRATION-PLAN.md (this file)
  • developer-guides/drupal/DRUPAL-ORG-MODULES-CATALOG.md (Agent 2 output)
  • developer-guides/drupal/DRUPAL-PROJECTS-INVENTORY.md (Agent 1 output)
  • developer-guides/drupal/CODE-DUPLICATION-REPORT.md (Agent 4 output)
  • developer-guides/drupal/STANDARDS-VIOLATIONS.md (Agent 5 output)
  • research/drupal/09-ai-module-analysis.md (Agent 6)
  • research/drupal/10-ai-agents-module-analysis.md (Agent 7)
  • research/drupal/11-eca-module-analysis.md (Agent 8)
  • research/drupal/12-flowdrop-module-analysis.md (Agent 9)
  • research/drupal/13-ai-mcp-module-analysis.md (Agent 10)
  • (Continue for all 45 agents...)

GitLab Issues

Create issues for:

  • Each custom module (ONLY if needed after Drupal.org check)
  • Integration tasks
  • Documentation tasks
  • Testing tasks

Metrics Dashboard

Track in Drupal:

  • Agents spawned: 0/45
  • Tasks completed: 0/45
  • Custom modules created: 0 (goal: minimize)
  • Contrib modules used: 0 (goal: maximize)
  • Documentation pages: 1/40
  • Test coverage: 0%
  • Standards compliance: 0%

CRITICAL SUCCESS FACTORS

1. Drupal.org FIRST, Always

Before ANY code: Check if it exists in contrib

2. Latest Code ALWAYS

Before ANY work: Pull from remote, verify latest

3. DRY Everywhere

During development: Reuse, abstract, share

4. Standards ENFORCED

After ANY change: Run phpcs, phpstan, line length check

5. Documentation CONCURRENT

As you work: Document immediately, not later

EMERGENCY PROTOCOLS

If Stuck on Drupal.org Research

Action: Ask in Drupal Slack #ai or #support

If Duplicate Code Found

Action: Immediately refactor before continuing

If Standards Violation Found

Action: Stop, fix, then continue (don't accumulate debt)

If Custom Code Seems Necessary

Action: Triple-check Drupal.org, ask maintainers, review issue queues

NEXT ACTIONS (RIGHT NOW)

Priority 1: Spawn Agent 1 (Remote Repo Audit) Priority 2: Spawn Agent 2 (Drupal.org Module Audit) Priority 3: Spawn Agent 3 (Local Sync) Priority 4: Spawn Agent 4 (DRY Validation) Priority 5: Spawn Agent 5 (Standards Validation)

After Phase 0 Complete: Review outputs, spawn Phase 1 agents

Status: AWAITING EXECUTION Last Updated: 2026-01-08 04:23 UTC Owner: Thomas Scola Agents Spawned: 0/45 Completion: 0%