WDG AI Dev Environment

What Is This System? ​

The WDG AI Development Environment is a local development platform that combines containerized WordPress environments with AI-powered code understanding. It indexes committed code for semantic search and provides AI assistants with deep knowledge of your codebase.

Core Capabilities ​

The platform addresses common development challenges by:

1. Indexing all committed code into a vector database for semantic search
2. Providing AI assistants with deep understanding of your codebase
3. Maintaining project isolation while sharing knowledge across projects
4. Enforcing standards through pre-configured tools and git hooks

How It Works: The Three Layers ​

1. Infrastructure Layer (Docker) ​

projects/
├── my-site/
│   ├── backups/           # Database backups
│   ├── config/            # Configuration files
│   ├── logs/              # Application logs
│   ├── repositories/      # Project-specific repository clones
│   │   └── my-site/       # Repository for this project
│   │       └── wp-content/
│   │           ├── themes/
│   │           ├── plugins/
│   │           ├── mu-plugins/
│   │           └── uploads/
│   ├── docker-compose.yml # Project Docker config
│   └── project.json       # Project metadata
├── client-project/
│   └── ...                # Another isolated project

Each project is completely isolated with its own:

• WordPress installation (in Docker volume, not local directory)
• MySQL database (separate database in shared MySQL container)
• PHP configuration
• Nginx virtual host
• SSL certificates

Note: WordPress files and database data are stored in Docker volumes for performance and portability, not in the project directory structure shown above.

2. Knowledge Layer (Vector Database) ​

When you commit code, git hooks trigger the indexing pipeline:

git commit -m "Add custom payment gateway" 
# ↓ Triggers post-commit hook
# ↓ Extracts code components (functions, classes, hooks)
# ↓ Generates embeddings using local AI models
# ↓ Stores in Qdrant vector database

Your code becomes searchable by meaning:

• "Find all AJAX handlers" → Returns all wp_ajax_* implementations
• "Show me data validation" → Finds sanitization and validation patterns
• "Payment integration code" → Discovers all payment-related logic

3. AI Assistant Layer (MCP) ​

The MCP server provides structured access to your codebase. AI assistants automatically use these tools when you ask questions:

# When you ask your AI: "Find refund processing code"
# It automatically calls:
search_codebase("refund processing")  # Semantic search

# When you ask: "Where is the process_order function?"
# It automatically calls:
search_functions("process_order")     # Find function definitions

# You don't call these directly - your AI assistant does

Key Concepts You Need to Understand ​

Knowledge Persistence ​

Only committed code enters the knowledge base. By design:

• Ensures code quality before indexing
• Creates versioned knowledge for tracking code evolution
• Maintains team consistency across all developers

Project Isolation vs Shared Knowledge ​

• Isolated: Each project has its own WordPress, database, and plugins
• Shared: All projects contribute to and benefit from the knowledge base
• Inherited: Wikit framework patterns available to all projects

Wikit Framework Knowledge ​

The system includes pre-indexed knowledge of:

• 50+ Gutenberg blocks with their props and patterns
• Base classes like WDG\Core\PostType and WDG\Core\Taxonomy
• Security patterns including nonce verification and data sanitization
• WDG coding standards with proper indentation and escaping

Local-First AI ​

No external API calls for code understanding:

• Embeddings: Generated locally using Sentence Transformers
• Vector search: Runs on local Qdrant instance
• Privacy: Your code never leaves your machine
• Speed: Millisecond search responses

Typical Development Workflow ​

Starting a New Feature ​

1. Create the project (if new):

wdg create client-site --init-wikit

2. Search for existing patterns (through your AI assistant):

   Ask your AI tool (Claude Code, Cursor, Gemini CLI):
   "Search for user registration form implementations"
   "Show me existing user registration patterns"
   "Find examples of form validation in the codebase"

   1
   2
   3
   4
   

   Your AI assistant will use MCP tools to search the indexed codebase.

3. Develop with AI assistance:

• AI understands your codebase structure
• Suggests patterns from successful implementations
• Follows WDG coding standards automatically
• Provides security best practices

4. Commit to update knowledge:

git add .
git commit -m "feat: Add user registration with email verification"
# Knowledge base now includes your new implementation

Finding and Reusing Code ​

Instead of grep or manual searching:

# Traditional approach
grep -r "add_action.*init" .

# AI-powered semantic search approach (ask your AI assistant)
"Search for initialization hooks for custom post types"
"Show me examples of init action usage"

The semantic search understands intent and returns relevant results even if the exact words don't match.

Available MCP Tools ​

Note: These tools are called automatically by your AI assistant (Claude Code, Cursor, etc.) when you ask questions. You don't invoke them directly - this is a reference for understanding what your AI can do.

Code Search Tools ​

search_codebase(query, project=None, file_types=None) ​

Search across all indexed code using natural language.

When to use: Finding implementations of concepts

search_codebase("validate user input")
search_codebase("ajax form submission", project="client-site")
search_codebase("responsive grid", file_types=["scss", "css"])

search_functions(function_name, project=None) ​

Find specific function definitions.

When to use: Locating exact function implementations

search_functions("process_payment")
search_functions("wdg_render_", project="my-site")  # Partial matches

search_wordpress_hooks(hook_name, hook_type=None) ​

Find WordPress hooks and their implementations.

When to use: Understanding hook usage across projects

search_wordpress_hooks("init")
search_wordpress_hooks("save_post", hook_type="action")
search_wordpress_hooks("the_content", hook_type="filter")

search_wikit_blocks(block_name=None) ​

Search through Wikit Gutenberg blocks.

When to use: Finding and understanding Wikit components

search_wikit_blocks()  # List all blocks
search_wikit_blocks("card")  # Find card-related blocks

Project Management Tools ​

get_project_info(project_name) ​

Get project configuration and status.

When to use: Understanding project setup

info = get_project_info("client-site")
# Returns: PHP version, WordPress version, active plugins, indexed status

wordpress_docs(query, type="all", get_details=False) ​

Search WordPress documentation.

When to use: Quick reference for WordPress functions

wordpress_docs("WP_Query")
wordpress_docs("wp_enqueue", type="function", get_details=True)

Understanding AI Assistant Context ​

AI Assistant Context Files ​

The system provides context files for different AI tools in the root directory:

• CLAUDE.md - Comprehensive context for Claude Code and Claude CLI
• GEMINI.md - Context for Google Gemini CLI
• .cursor/ - Directory for Cursor IDE configuration
  • cursorrules - Cursor IDE rules and patterns (auto-loaded)
  • mcp.json - MCP server configuration (auto-loaded)
• .codex/ - Directory for OpenAI Codex configuration
• .claude/ - Directory for Claude Code settings and MCP configuration
• .gemini/ - Directory for Gemini CLI settings

Each provides:

• Coding standards: Tabs for PHP, security requirements
• Project structure: Where different code belongs
• Wikit patterns: How to extend base classes
• Security checklist: What to always implement
• Available MCP tools: Which functions to use for searching

Using with Cursor IDE ​

Cursor automatically detects and loads the .cursor/ directory configuration. To use:

1. Open the project in Cursor IDE
2. The .cursor/cursorrules file is automatically loaded
3. The .cursor/mcp.json configures MCP server connection
4. Start coding with AI assistance that understands WDG patterns

The configuration includes:

• WordPress Coding Standards (WPCS) enforcement
• Wikit framework patterns and classes
• Security requirements (nonces, escaping, sanitization)
• MCP tool usage for code search
• Multi-project architecture awareness
• Pre-configured MCP server (wdg-local + chrome-devtools)

Using AI Assistants with the System ​

The platform provides specialized context for AI tools through configuration files:

• Claude Code: Uses .claude/settings.json with MCP server connection
• Cursor IDE: Auto-loads .cursor/cursorrules and MCP configuration
• Gemini CLI: Uses .gemini/settings.json for context

These configurations give AI assistants:

• Deep WordPress core knowledge
• Wikit framework expertise (patterns and blocks)
• Security-first coding practices
• Production-ready standards

No special setup required beyond the initial MCP connection.

Project Structure Explained ​

wdg-ai-dev-env/
├── projects/                   # Your WordPress projects
│   └── {project-name}/
│       ├── backups/            # Database backups
│       ├── config/             # Project configuration files
│       ├── logs/               # Application logs
│       ├── repositories/       # Project-specific repository clones
│       │   └── {repo-name}/    # Repository clone for this project
│       │       └── wp-content/ # The actual WordPress content
│       │           ├── themes/
│       │           ├── plugins/
│       │           ├── mu-plugins/
│       │           └── uploads/
│       ├── docker-compose.yml  # Project-specific Docker configuration
│       └── project.json        # Project metadata
│
├── repositories/               # Central repository storage (Wikit framework)
│   ├── wikit-core/             # Base classes and traits
│   ├── wikit-theme/            # 50+ Gutenberg blocks
│   ├── wikit-facets/           # Faceted search
│   └── wikit-app/              # Application layer
│
├── services/                   # Service configurations
│   ├── nginx/                  # Nginx proxy config
│   ├── mysql/                  # MySQL configuration
│   └── wordpress/              # WordPress base image config
│
├── mcp-server/                 # AI tool server
│   └── server.py               # FastMCP implementation
│
├── indexer/                    # Code indexing pipeline
│   ├── embedder.py             # Generates embeddings
│   └── updater.py              # Updates vector DB
│
├── cli/                        # Command-line tools
│   └── wdg                     # Main CLI executable
│
├── data/                       # Persistent data volumes
│   ├── mysql/                  # MySQL database files
│   └── qdrant/                 # Vector database files
│
└── docker-compose.yml          # Main service orchestration

Repository as wp-content Pattern ​

Projects use repositories as their wp-content directory:

# Create project with Wikit framework
wdg create my-site --init-wikit

# Structure created:
# projects/my-site/repositories/my-site/wp-content/
#   ├── themes/
#   ├── plugins/
#   ├── mu-plugins/
#   └── uploads/

# Docker mounts this to container:
# Container path: /var/www/html/wp-content
# Host path: ./projects/my-site/repositories/my-site/wp-content

This enables:

• Git tracking of all plugins/themes
• Complete project isolation
• Clean separation of code from WordPress core
• Simplified backup and migration workflows

Important: WordPress core files and database data are stored in Docker volumes, not in the local file system. This provides improved I/O performance and simplified container management.

Practical Examples ​

Example 1: Creating a Custom Post Type with AI ​

# 1. Ask AI to search for existing patterns
"Search for custom post type implementations in our codebase"

# 2. AI uses MCP tools
search_codebase("custom post type registration")
search_functions("register_post_type")
search_wikit_blocks("query")  # For display blocks

# 3. AI provides implementation following found patterns
"Based on your codebase, here's a custom post type following WDG patterns..."

Example 2: Finding Security Vulnerabilities ​

# Ask your AI assistant to search for potential issues
"Search for direct database queries without prepare statements"
"Find instances of echo without escaping"
"Show me POST access without nonce verification"

Example 3: Refactoring with Pattern Recognition ​

# Find all similar implementations
"Find all form handling code in the codebase"

# AI identifies patterns
search_codebase("form submission handling")
search_wordpress_hooks("admin_post_")

# AI suggests refactoring
"I found 5 different form handling patterns. Here's a unified approach..."

Common Issues and Solutions ​

Indexing Issues ​

Problem: Code changes not appearing in search

# Check indexing status
wdg status

# Manual reindex
wdg my-project index

# Check git hooks
ls -la .git/hooks/post-commit

MCP Connection Issues ​

Problem: AI can't access tools

# Verify MCP server
curl http://localhost:8765/health

# Check Docker services
docker-compose ps mcp-server

# Restart MCP
docker-compose restart mcp-server

Vector Database Issues ​

Problem: Search returning no results

# Check collections
wdg collections list

# Reindex a project
wdg my-project index

Getting Started Checklist ​

• [ ] System Requirements

  • Docker & Docker Compose installed
  • 8GB RAM minimum (16GB recommended)
  • 20GB free disk space

• [ ] Initial Setup

  bash

  git clone https://github.com/wdgdc/wdg-ai-dev
  cd wdg-ai-dev
  ./install.sh

  1
  2
  3
  

• [ ] Create First Project

  bash

  wdg create test-site
  wdg test-site start

  1
  2
  

• [ ] Connect AI Assistant

  • Cursor IDE: Open project (auto-loads .cursorrules)
  • Claude Code: Uses .claude/settings.json with MCP connection
  • Gemini CLI: Uses .gemini/settings.json with MCP connection
  • Test with: "Search for WordPress hooks in my codebase"

• [ ] Verify Knowledge Base

  • Ask your AI: "Search for WordPress hooks in my codebase"
  • Should return Wikit framework results

Best Practices ​

For Effective AI Assistance ​

1. Commit frequently - Incremental updates improve index accuracy
2. Write descriptive commit messages - Provides context for indexed code
3. Use semantic search first - Identify existing patterns before implementation
4. Follow existing patterns - AI tools reference established implementations
5. Request security review - Leverage indexed security requirements

For Project Organization ​

1. One repository per client - Maintains clean separation
2. Use wp-content pattern - Entire repository as wp-content
3. Consistent naming - Helps AI identify related code
4. Document unique patterns - Add to project README
5. Keep AI context files updated - Update CLAUDE.md, GEMINI.md, or your tool's config as needed

For Team Collaboration ​

1. Pull before starting - Get latest team knowledge
2. Push after features - Share your implementations
3. Index after pulls - Update local knowledge base
4. Review AI suggestions - Ensure team consistency
5. Document decisions - Help AI understand choices

Next Steps ​

• Quick Start Guide - Set up your first project
• Architecture Deep Dive - Understand the system design
• CLI Reference - Master the command-line tools
• Wikit Documentation - Learn the framework patterns
• Development Workflow - Best practices guide

Getting Help ​

• Check logs: docker-compose logs -f [service]
• Run diagnostics: wdg doctor
• Search documentation: Built-in search in these docs
• Ask the AI: "How do I debug MCP connection issues?"
• Team chat: Internal Slack #wdg-ai-dev channel