upskill-event-manager/CLAUDE.md

CLAUDE.md - HVAC Plugin Development Guide

Essential guidance for Claude Code agents working on the HVAC Community Events WordPress plugin.

📚 Complete Best Practices: See docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md for comprehensive development guidelines.

📊 Current Status: PHP 8+ Modernization (Phase 2) in progress - debugging union type compatibility on staging

⚠️ Interim Status: See docs/PHP8-MODERNIZATION-INTERIM-STATUS.md for current session progress

🚀 Quick Commands

Deployment (Most Common)

# Deploy to staging (primary command)
scripts/deploy.sh staging

# Pre-deployment validation (ALWAYS run first)
scripts/pre-deployment-check.sh

# Deploy to production (ONLY when user explicitly requests)
scripts/deploy.sh production

Testing

# Docker Development Environment
docker compose -f tests/docker-compose.test.yml up -d

# Run E2E tests against Docker environment (headless)
HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js

# Run E2E tests with GNOME session browser (headed)
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 node test-master-trainer-e2e.js

# Run comprehensive test suite
node test-comprehensive-validation.js

# Use MCP Playwright when standard Playwright fails
# (The MCP tools handle display integration automatically)

WordPress CLI (on server)

wp rewrite flush
wp eval 'HVAC_Page_Manager::create_required_pages();'

🎯 Core Development Principles

1. USE MCP SERVICES PROACTIVELY

• mcp__sequential-thinking__sequentialthinking for complex planning
• mcp__zen-mcp__codereview with GPT-5/Qwen for validation
• mcp__zen-mcp__thinkdeep for complex investigations
• WebSearch for documentation and best practices
• Specialized Agents: Use agents from user's .claude directory for debugging, architecture, security

2. WordPress Template Architecture (CRITICAL)

// ✅ ALWAYS use singleton patterns  
echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();

// ❌ NEVER assume static methods exist
// WRONG: HVAC_Breadcrumbs::render();

// ✅ MANDATORY in all templates
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
// content here
get_footer();

3. Security-First Patterns

// Always escape output
echo esc_html($trainer_name);
echo esc_url($profile_link);

// Always sanitize input  
$trainer_id = absint($_POST['trainer_id']);

// Always verify nonces
wp_verify_nonce($_POST['nonce'], 'hvac_action');

// Role checking (NOT capabilities)
$user = wp_get_current_user();
if (!in_array('hvac_trainer', $user->roles)) {
    wp_die('Access denied');
}

4. WordPress Specialized Agents (PRIMARY DEVELOPMENT TOOLS)

MANDATORY: Use project-specific WordPress agents for ALL development activities:

# WordPress Plugin Development (primary agent for features/fixes)
claude --agent wordpress-plugin-pro "Add event validation system"

# Code Review (MANDATORY after any code changes) 
claude --agent wordpress-code-reviewer "Review security of latest changes"

# Troubleshooting (first response to any issues)
claude --agent wordpress-troubleshooter "Debug event creation form issues"

# Testing (MANDATORY before any deployment)
claude --agent wordpress-tester "Run comprehensive test suite for staging deployment"

# Deployment (for all staging/production deployments)
claude --agent wordpress-deployment-engineer "Deploy latest changes to staging"

Agent Selection Guide:

• 🔧 wordpress-plugin-pro: New features, WordPress hooks, TEC integration, role management
• 🛡️ wordpress-code-reviewer: Security review, WordPress standards, performance analysis
• 🔍 wordpress-troubleshooter: Debugging, plugin conflicts, user access issues
• 🧪 wordpress-tester: Comprehensive testing, E2E tests, deployment validation (MANDATORY before deployments)
• 🚀 wordpress-deployment-engineer: Staging/production deployments, CI/CD, backups

5. Testing & Debugging Process

1. Use wordpress-troubleshooter agent for systematic diagnosis
2. Create comprehensive test suite with wordpress-tester agent
3. Apply wordpress-code-reviewer for security validation
4. Run mandatory pre-deployment tests with wordpress-tester
5. Use wordpress-deployment-engineer for staging deployment and validation

6. WordPress Error Detection & Site Health

# All E2E tests now include automatic WordPress error detection
# Tests will fail fast if critical WordPress errors are detected:
# - Fatal PHP errors (memory, syntax, undefined functions)
# - Database connection errors
# - Maintenance mode
# - Plugin/theme fatal errors
# - HTTP 500+ server errors

# If test fails with "WordPress site has critical errors":
# 1. Restore staging from production backup
# 2. Re-seed test data to staging:
bin/seed-comprehensive-events.sh
# 3. Re-run tests

🏗️ Architecture Overview

WordPress Plugin Structure:

• Entry Point: hvac-community-events.php
• Core Classes: includes/class-*.php (singleton pattern)
• Templates: templates/page-*.php (hierarchical URLs)
• User Roles: hvac_trainer, hvac_master_trainer
• URL Structure: /trainer/dashboard/, /master-trainer/master-dashboard/

⚠️ CRITICAL REMINDERS

Never Do

• ❌ Deploy to production without explicit user request
• ❌ Skip pre-deployment validation
• ❌ Use static method calls without verification
• ❌ Create standalone fixes outside plugin deployment
• ❌ Assume template patterns without checking existing implementation

Always Do

• ✅ Use WordPress agents as first choice for ALL development tasks
• ✅ Use MCP services and specialized agents proactively
• ✅ Test on staging first
• ✅ Apply consistent singleton patterns
• ✅ Escape all output, sanitize all input
• ✅ Create comprehensive test suites before making fixes
• ✅ Reference the detailed best practices document

📚 Key Documentation

Essential Reading:

• Status.md - Current project status and known issues
• docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md - Complete development guide
• docs/MASTER-TRAINER-FIXES-REPORT.md - Recent major fixes and lessons learned

Reference Materials:

• docs/ARCHITECTURE.md - System architecture
• docs/TROUBLESHOOTING.md - Common issues
• docs/WORDPRESS-BEST-PRACTICES.md - WordPress standards
• docs/TEST-FRAMEWORK-MODERNIZATION-STATUS.md - Testing infrastructure overhaul

🧪 Docker Testing Infrastructure (New)

STATUS: August 27, 2025 - FULLY OPERATIONAL

Docker Environment

# Start hermetic testing environment
docker compose -f tests/docker-compose.test.yml up -d

# Access WordPress test instance
http://localhost:8080

# Services included:
# - WordPress 6.4 (PHP 8.2) on port 8080
# - MySQL 8.0 on port 3307
# - Redis 7 on port 6380
# - Mailhog (email testing) on port 8025
# - PhpMyAdmin on port 8081

Test Framework Architecture

• Page Object Model (POM): Centralized, reusable test components
• 146 Tests Migrated: From 80+ duplicate files to modern architecture
• 90% Code Reduction: Eliminated test duplication through shared patterns
• Browser Management: Singleton lifecycle with proper cleanup
• TCPDF Dependency: Graceful handling of missing PDF generation library

Testing Commands

# Run comprehensive E2E tests (ready for next session)
HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js
HEADLESS=true BASE_URL=http://localhost:8080 node test-comprehensive-validation.js

🚨 CRITICAL WARNING: Monitoring Infrastructure Disabled

DATE: August 8, 2025
The monitoring infrastructure is PERMANENTLY DISABLED due to causing PHP segmentation faults.

Disabled systems: HVAC_Background_Jobs, HVAC_Health_Monitor, HVAC_Error_Recovery, HVAC_Security_Monitor, HVAC_Performance_Monitor, HVAC_Backup_Manager, HVAC_Cache_Optimizer

DO NOT RE-ENABLE without thorough debugging.

🎯 WordPress Development Workflow

1. Start with WordPress Agents: Choose appropriate agent based on task type
2. Plan with Sequential Thinking: Agents will use mcp__sequential-thinking for complex tasks
3. Research Best Practices: Agents will use WebSearch for WordPress documentation
4. Apply Consistent Patterns: Agents understand WordPress singleton patterns
5. Test Comprehensively: MANDATORY wordpress-tester for all test suites and validation
6. Review Security: MANDATORY wordpress-code-reviewer after code changes
7. Pre-Deploy Testing: MANDATORY wordpress-tester before any deployment
8. Deploy Systematically: wordpress-deployment-engineer for staging first
9. Validate with MCP: Agents will use mcp__zen-mcp__codereview for quality assurance

🚀 Quick Agent Command Reference

# Feature Development
claude --agent wordpress-plugin-pro "Implement trainer approval workflow"

# Bug Fixes  
claude --agent wordpress-troubleshooter "Fix event creation form validation"

# Security & Code Quality
claude --agent wordpress-code-reviewer "Review user authentication system"

# Testing (MANDATORY before deployments)
claude --agent wordpress-tester "Run full test suite before staging deployment"

# Deployments
claude --agent wordpress-deployment-engineer "Deploy v2.1 to staging environment"

---

This guide provides essential information for Claude Code agents. For comprehensive details, always refer to the complete best practices documentation.