Development Workflow

A complete guide to developing WordPress sites with WDG AI Development Environment.

Typical Development Flow

%%{init: {'theme':'neutral'}}%%
graph TD
    A[Create Project] --> B[Clone/Create Repos]
    B --> C[Start Development]
    C --> D[Code & Test]
    D --> E[Index for AI Search]
    E --> F[Use AI Assistant]
    F --> D
    D --> G[Build & Deploy]

Starting a New Project

1. Project Setup

bash

# Create project with Wikit template
wdg create client-site

# Start the project
wdg start client-site

# Access the site
open https://client-site.localhost:6443

2. Repository Structure

Your project starts with this structure:

projects/client-site/
├── docker-compose.yml       # Container config
├── .env                     # Environment variables
├── .wp-content-link        # Repository mapping
└── repositories/
    └── custom-theme/       # Your theme (from template)
        ├── style.css
        ├── functions.php
        ├── package.json
        └── block-editor/   # Gutenberg blocks

3. Add Your Repositories

bash

# Add existing plugin
wdg client-site repo add https://github.com/team/custom-plugin.git

# Add another theme
wdg client-site repo add https://github.com/team/brand-theme.git

# List repositories
wdg client-site repo list

Daily Development Workflow

Morning Routine

bash

# 1. Update framework repositories
wdg update

# 2. Start your project
wdg start client-site

# 3. Pull latest changes
wdg client-site repo sync

# 4. Re-index if needed
wdg index client-site

Active Development

File Watching & Hot Reload

bash

# Terminal 1: Watch theme files
cd projects/client-site/repositories/custom-theme
npm run watch

# Terminal 2: Watch logs
docker logs wdg-wp-client-site -f

Making Changes

Edit files directly in projects/client-site/repositories/
Changes sync instantly to WordPress container
Browser auto-refreshes with hot reload

Using AI Assistant

bash

# Index your latest changes
wdg index client-site

# Connect Claude Desktop to search your code
# MCP server at http://localhost:6765

Example Claude queries:

"Find all custom post types in client-site"
"Show me how authentication is handled"
"Find similar implementations to this function"

Testing Workflow

Local Testing

bash

# Run theme tests
cd projects/client-site/repositories/custom-theme
npm test

# Check PHP syntax
docker exec wdg-wp-client-site php -l wp-content/themes/custom-theme/*.php

# WordPress debug log
docker exec wdg-wp-client-site tail -f /var/www/html/wp-content/debug.log

Database Operations

bash

# Export before major changes
wdg client-site db export backup-$(date +%Y%m%d).sql

# Import test data
wdg client-site db import test-data.sql

# Reset to fresh WordPress
wdg client-site db reset

Team Collaboration Workflow

Setting Up for Team

Share repository access

bash

# Team member clones main repo
git clone https://github.com/team/project-repos.git

# Setup their environment
cd project-repos
wdg create client-site
wdg client-site repo attach ./theme
wdg client-site repo attach ./plugins

Sync configurations

bash

# Export your database
wdg client-site db export initial-content.sql

# Commit to repo
git add initial-content.sql
git commit -m "Add initial content"
git push

Team member imports

bash

# Pull latest
git pull

# Import database
wdg client-site db import initial-content.sql

# Start developing
wdg start client-site

Git Workflow Integration

bash

# Install git hooks for consistency
wdg client-site repo hooks custom-theme

# Now commits trigger:
# - Code formatting
# - Linting
# - Pre-commit tests

Managing Conflicts

bash

# Before pulling changes
wdg client-site db export my-changes.sql

# Pull and merge
cd projects/client-site/repositories/custom-theme
git pull
# Resolve conflicts

# Re-index after merge
wdg index client-site

Theme Development Workflow

Creating Blocks

bash

# Navigate to theme directory
cd projects/client-site/repositories/client-site-theme

# Create new Gutenberg block using @wordpress/create-block
npx @wordpress/create-block testimonial-slider

# This generates:
# - block.json
# - src/edit.js
# - src/save.js
# - src/editor.scss
# - src/style.scss

Building Assets

bash

# Navigate to theme directory
cd projects/client-site/repositories/client-site-theme

# Install dependencies
npm install

# Build assets
npm run build

# Watch for changes
npm run watch

The theme's package.json exposes these scripts: start, build, watch, scss, postcss, build:js, build:css, build:vendor, build:stylecss, watch:js, watch:css, check-updates, update. There is no build:production, package, analyze, lint:fix, optimize:images, critical:css, or docs:generate script.

Theme Build

bash

# Build production assets through the CLI
wdg client-site build

# Or run the build script directly
cd projects/client-site/repositories/client-site-theme
npm run build

Plugin Development Workflow

Plugin Structure

php

// plugins/my-plugin/my-plugin.php
<?php
/**
 * Plugin Name: My Custom Plugin
 * Version: 1.0.0
 */

// Your code here

Testing Plugins

bash

# Activate plugin
docker exec wdg-wp-client-site \
  wp plugin activate my-plugin --allow-root

# Run plugin tests
docker exec wdg-wp-client-site \
  bash -c "cd wp-content/plugins/my-plugin && phpunit"

Debugging Workflow

Enable Debug Mode

Edit projects/client-site/.env:

bash

WP_DEBUG=true
WP_DEBUG_LOG=true
WP_DEBUG_DISPLAY=false

View Logs

bash

# WordPress debug log (project-scoped, supports --follow/--tail=N/--since=/--grep=)
wdg client-site logs debug --follow

# PHP and nginx logs
wdg client-site logs php
wdg client-site logs nginx

# All project logs
wdg client-site logs all

# Raw container access (fallback)
docker exec wdg-wp-client-site tail -f /var/www/html/wp-content/debug.log

Using Xdebug

Add to projects/client-site/docker-compose.yml:

yaml

environment:
  XDEBUG_MODE: debug
  XDEBUG_CONFIG: client_host=host.docker.internal

Performance Optimization Workflow

Profiling

bash

# Install Query Monitor plugin
docker exec wdg-wp-client-site \
  wp plugin install query-monitor --activate --allow-root

# Access at: /wp-admin/admin.php?page=qm

Caching

bash

# Or use the wdg command shorthand
wdg client-site wp plugin install redis-cache --activate

# Enable object cache
wdg client-site wp redis enable

Asset Builds

bash

# Build production assets
cd projects/client-site/repositories/custom-theme
npm run build

# Build individual bundles
npm run build:js
npm run build:css

Deployment Workflow

Pre-Deployment Checklist

bash

# 1. Run all tests
npm test
phpunit

# 2. Build production assets
npm run build

# 3. Export content
wdg client-site db export production-ready.sql

# 4. Create deployment package
./scripts/create-deployment.sh

Deployment Package Structure

deployment/
├── database/
│   └── production-ready.sql
├── themes/
│   └── custom-theme/
├── plugins/
│   └── custom-plugin/
└── deploy.sh

Deployment Script

bash

#!/bin/bash
# deploy.sh

# Upload files
rsync -avz themes/ user@server:/var/www/wp-content/themes/
rsync -avz plugins/ user@server:/var/www/wp-content/plugins/

# Import database
ssh user@server "wp db import production-ready.sql"

# Clear caches
ssh user@server "wp cache flush"

AI-Assisted Development Workflow

1. Index Everything

bash

# Index framework
wdg index

# Index your project
wdg index client-site

# Verify collections
wdg collections list

2. Connect AI Assistant

Configure Claude Desktop:

json

{
  "mcpServers": {
    "wdg": {
      "command": "nc",
      "args": ["localhost", "6765"]
    }
  }
}

3. AI-Powered Tasks

Code Review: "Review the security of the user authentication in client-site"

Pattern Search: "Find all AJAX handlers in the project"

Refactoring: "Show me functions that could use the Repository pattern"

Bug Finding: "Find potential SQL injection vulnerabilities"

Best Practices

1. Version Control

bash

# Always commit before major changes
git add -A
git commit -m "Before refactoring user system"

# Tag stable versions
git tag -a v1.0.0 -m "First stable release"
git push --tags

2. Database Backups

bash

# Daily backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
wdg client-site db export backups/backup-$DATE.sql

3. Environment Separation

bash

# Development
wdg create client-dev

# Staging
wdg create client-staging

# Production prep
wdg create client-prod

4. Code Quality

Use the project-scoped CLI commands. lint runs PHPCS/PHPCBF and analyze runs PHPStan inside the project container:

bash

# Lint PHP (PHPCS)
wdg client-site lint

# Auto-fix violations (PHPCBF)
wdg client-site lint --fix

# Summary report, severity threshold, or include plugins
wdg client-site lint --summary
wdg client-site lint --severity=5
wdg client-site lint --include-plugins

# Static analysis (PHPStan, in-container)
wdg client-site analyze
wdg client-site analyze --level=5
wdg client-site analyze --baseline
wdg client-site analyze --include-plugins

Automation Scripts

Daily Development Script

bash

#!/bin/bash
# dev-start.sh

echo "Starting development environment..."

# Update repositories
wdg update

# Start project
wdg start client-site

# Sync repos
wdg client-site repo sync

# Re-index
wdg index client-site

# Open browser
open https://client-site.localhost:6443

# Start watching
cd projects/client-site/repositories/custom-theme
npm run watch

End of Day Script

bash

#!/bin/bash
# dev-end.sh

echo "Shutting down development environment..."

# Export database
wdg client-site db export daily-backup.sql

# Commit changes
cd projects/client-site/repositories/custom-theme
git add -A
git commit -m "End of day: $(date +%Y-%m-%d)"
git push

# Stop project
wdg stop client-site

echo "Environment shut down. Changes saved."

Pro Tip: Create aliases for common commands in your .bashrc:

bash

alias wdg-start='wdg start client-site'
alias wdg-theme='cd ~/wdg-ai-dev/projects/client-site/repositories/custom-theme'
alias wdg-index='wdg index client-site'

Development Workflow ​

Typical Development Flow ​

Starting a New Project ​

1. Project Setup ​

2. Repository Structure ​

3. Add Your Repositories ​

Daily Development Workflow ​

Morning Routine ​

Active Development ​

File Watching & Hot Reload ​

Making Changes ​

Using AI Assistant ​

Testing Workflow ​

Local Testing ​

Database Operations ​

Team Collaboration Workflow ​

Setting Up for Team ​

Git Workflow Integration ​

Managing Conflicts ​

Theme Development Workflow ​

Creating Blocks ​

Building Assets ​

Theme Build ​

Plugin Development Workflow ​

Plugin Structure ​

Testing Plugins ​

Debugging Workflow ​

Enable Debug Mode ​

View Logs ​

Using Xdebug ​

Performance Optimization Workflow ​

Profiling ​

Caching ​

Asset Builds ​

Deployment Workflow ​

Pre-Deployment Checklist ​

Deployment Package Structure ​

Deployment Script ​

AI-Assisted Development Workflow ​

1. Index Everything ​

2. Connect AI Assistant ​

3. AI-Powered Tasks ​

Best Practices ​

1. Version Control ​

2. Database Backups ​

3. Environment Separation ​

4. Code Quality ​

Automation Scripts ​

Daily Development Script ​

End of Day Script ​

Development Workflow

Typical Development Flow

Starting a New Project

1. Project Setup

2. Repository Structure

3. Add Your Repositories

Daily Development Workflow

Morning Routine

Active Development

File Watching & Hot Reload

Making Changes

Using AI Assistant

Testing Workflow

Local Testing

Database Operations

Team Collaboration Workflow

Setting Up for Team

Git Workflow Integration

Managing Conflicts

Theme Development Workflow

Creating Blocks

Building Assets

Theme Build

Plugin Development Workflow

Plugin Structure

Testing Plugins

Debugging Workflow

Enable Debug Mode

View Logs

Using Xdebug

Performance Optimization Workflow

Profiling

Caching

Asset Builds

Deployment Workflow

Pre-Deployment Checklist

Deployment Package Structure

Deployment Script

AI-Assisted Development Workflow

1. Index Everything

2. Connect AI Assistant

3. AI-Powered Tasks

Best Practices

1. Version Control

2. Database Backups

3. Environment Separation

4. Code Quality

Automation Scripts

Daily Development Script

End of Day Script