# 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](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](docs/PHP8-MODERNIZATION-INTERIM-STATUS.md) for current session progress

## 🚀 Quick Commands

### Deployment (Most Common)
```bash
# 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
```bash
# 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)
```bash
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)**
```php
// ✅ 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**
```php
// 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:

```bash
# 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**
```bash
# 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](Status.md)** - Current project status and known issues
- **[docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md](docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md)** - Complete development guide
- **[docs/MASTER-TRAINER-FIXES-REPORT.md](docs/MASTER-TRAINER-FIXES-REPORT.md)** - Recent major fixes and lessons learned

**Reference Materials:**
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture
- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues
- **[docs/WORDPRESS-BEST-PRACTICES.md](docs/WORDPRESS-BEST-PRACTICES.md)** - WordPress standards
- **[docs/TEST-FRAMEWORK-MODERNIZATION-STATUS.md](docs/TEST-FRAMEWORK-MODERNIZATION-STATUS.md)** - Testing infrastructure overhaul

## 🧪 Docker Testing Infrastructure (New)

**STATUS: August 27, 2025 - FULLY OPERATIONAL**

### Docker Environment
```bash
# 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
```bash
# 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
```bash
# 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.*