ben/upskill-event-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs: Streamline CLAUDE.md and update Status.md with TEC CE analysis
Some checks are pending
HVAC Plugin CI/CD Pipeline / Security Analysis (push) Waiting to run
Details
HVAC Plugin CI/CD Pipeline / Code Quality & Standards (push) Waiting to run
Details
HVAC Plugin CI/CD Pipeline / Unit Tests (push) Waiting to run
Details
HVAC Plugin CI/CD Pipeline / Integration Tests (push) Waiting to run
Details
HVAC Plugin CI/CD Pipeline / Deploy to Staging (push) Blocked by required conditions
Details
HVAC Plugin CI/CD Pipeline / Deploy to Production (push) Blocked by required conditions
Details
HVAC Plugin CI/CD Pipeline / Notification (push) Blocked by required conditions
Details

Browse source 
- Simplify CLAUDE.md to focus on essential development guidance
- Remove redundant agent workflow documentation
- Add Technical Debt section documenting TEC Community Events dependency
- Update Status.md with completed TEC CE dependency analysis session

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Ben 2026-01-09 20:04:11 -04:00
parent 3d66756715
commit 3136b96d3f
2 changed files with 142 additions and 220 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

328
CLAUDE.md
View file

@ -1,286 +1,182 @@
# CLAUDE.md - HVAC Plugin Development Guide # CLAUDE.md
**Essential guidance for Claude Code agents working on the HVAC Community Events WordPress plugin.** This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
> 📚 **Complete Best Practices**: See [docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md](docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md) for comprehensive development guidelines. ## Project Overview
> 📊 **Current Status**: PHP 8+ Modernization (Phase 2) in progress - debugging union type compatibility on staging HVAC Community Events is a WordPress plugin extending The Events Calendar (TEC) suite to create a trainer community platform. It provides custom user roles (`hvac_trainer`, `hvac_master_trainer`), event management, certificate generation, venue/organizer management, and Zoho CRM integration.
> ⚠️ **Interim Status**: See [docs/PHP8-MODERNIZATION-INTERIM-STATUS.md](docs/PHP8-MODERNIZATION-INTERIM-STATUS.md) for current session progress - **Entry Point**: `hvac-community-events.php`
- **Core Classes**: `includes/class-*.php` (all use singleton pattern)
- **Templates**: `templates/page-*.php`
- **TEC Integration**: Events, venues, organizers via The Events Calendar suite
## 🚀 Quick Commands ## Commands
### Deployment (Most Common) ### Deployment
```bash ```bash
# Deploy to staging (primary command)
scripts/deploy.sh staging
# Pre-deployment validation (ALWAYS run first) # Pre-deployment validation (ALWAYS run first)
scripts/pre-deployment-check.sh scripts/pre-deployment-check.sh
# Deploy to production (ONLY when user explicitly requests) # Deploy to staging
scripts/deploy.sh staging
# Deploy to production (requires explicit user request and confirmation)
scripts/deploy.sh production scripts/deploy.sh production
``` ```
### Testing ### Testing
```bash ```bash
# Docker Development Environment # Start Docker test environment
docker compose -f tests/docker-compose.test.yml up -d docker compose -f tests/docker-compose.test.yml up -d
# Run E2E tests against Docker environment (headless) # E2E tests (headless)
HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js 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
# Run E2E tests with GNOME session browser (headed) # E2E tests (headed - requires display)
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 node test-master-trainer-e2e.js 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) ### WordPress CLI (on server via SSH)
```bash ```bash
wp rewrite flush wp rewrite flush
wp eval 'HVAC_Page_Manager::create_required_pages();' wp eval 'HVAC_Page_Manager::create_required_pages();'
wp eval 'wp_set_password("Password123", USER_ID);' # Reset password (more reliable than wp user update)
# Reset user password (when wp user update fails with password hashing)
wp eval 'wp_set_password("YourPassword123", USER_ID);'
# Example for test_master user (ID: 25 on staging)
wp eval 'wp_set_password("TestPass123", 25);'
``` ```
### Test Credentials (Staging) ### Staging Environment
```bash ```bash
# Master Trainer Test Account # SSH access
Username: test_master
Password: TestPass123
User ID: 25
Role: hvac_master_trainer
# Password Reset Method (if login fails after wp user update)
# SSH to staging server:
ssh roodev@146.190.76.204 ssh roodev@146.190.76.204
# Navigate to WordPress root and reset password:
cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html
wp eval 'wp_set_password("TestPass123", 25);'
# Why wp_set_password instead of wp user update: # Test account (staging)
# wp user update --user_pass sometimes has password hashing issues Username: test_master | Password: TestPass123 | Role: hvac_master_trainer
# wp_set_password properly hashes the password using wp_hash_password()
``` ```
## 🎯 Core Development Principles ## Architecture
### 1. **USE MCP SERVICES PROACTIVELY** ### Singleton Pattern (MANDATORY)
- `mcp__sequential-thinking__sequentialthinking` for complex planning All core classes use the singleton pattern. Never assume static methods exist:
- `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 ```php
// ✅ ALWAYS use singleton patterns // CORRECT
echo HVAC_Breadcrumbs::instance()->render_breadcrumbs(); echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();
HVAC_Venues::instance()->get_venues();
// ❌ NEVER assume static methods exist // WRONG - will fail
// WRONG: HVAC_Breadcrumbs::render(); HVAC_Breadcrumbs::render();
```
// ✅ MANDATORY in all templates ### Template Requirements
All page templates MUST include:
```php
<?php
defined('ABSPATH') || exit;
define('HVAC_IN_PAGE_TEMPLATE', true); define('HVAC_IN_PAGE_TEMPLATE', true);
get_header(); get_header();
// content here // ... content ...
get_footer(); get_footer();
``` ```
### 3. **Security-First Patterns** ### Security Patterns
```php ```php
// Always escape output // Input sanitization
echo esc_html($trainer_name);
echo esc_url($profile_link);
// Always sanitize input
$trainer_id = absint($_POST['trainer_id']); $trainer_id = absint($_POST['trainer_id']);
$email = sanitize_email($_POST['email']);
// Always verify nonces // Output escaping
echo esc_html($trainer_name);
echo esc_url($profile_url);
// Nonce verification
wp_verify_nonce($_POST['nonce'], 'hvac_action'); wp_verify_nonce($_POST['nonce'], 'hvac_action');
// Role checking (NOT capabilities) // Role checking (use roles, not capabilities)
$user = wp_get_current_user(); $user = wp_get_current_user();
if (!in_array('hvac_trainer', $user->roles)) { if (!in_array('hvac_trainer', $user->roles)) {
wp_die('Access denied'); wp_die('Access denied');
} }
``` ```
### 4. **WordPress Specialized Agents (PRIMARY DEVELOPMENT TOOLS)** ### File Structure
```
includes/
├── class-hvac-plugin.php # Main controller (singleton)
├── class-hvac-shortcodes.php # Shortcode management
├── class-hvac-scripts-styles.php # Asset management
├── class-hvac-route-manager.php # URL routing
├── class-hvac-venues.php # Venue CRUD (singleton)
├── class-hvac-organizers.php # Organizer management (singleton)
├── class-hvac-training-leads.php # Lead tracking (singleton)
├── admin/ # Admin classes
├── certificates/ # Certificate generation
├── communication/ # Email templates
├── zoho/ # Zoho CRM integration
└── find-trainer/ # Public trainer directory
**MANDATORY**: Use project-specific WordPress agents for ALL development activities: templates/page-*.php # Page templates (hierarchical URLs)
assets/{css,js}/ # Frontend assets
```bash tests/ # Docker environment and E2E tests
# WordPress Plugin Development (primary agent for features/fixes) scripts/ # Deployment and maintenance scripts
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:** ### URL Structure
- 🔧 **wordpress-plugin-pro**: New features, WordPress hooks, TEC integration, role management - Trainer: `/trainer/dashboard/`, `/trainer/event/manage/`, `/trainer/certificate-reports/`
- 🛡️ **wordpress-code-reviewer**: Security review, WordPress standards, performance analysis - Master Trainer: `/master-trainer/dashboard/`, `/master-trainer/trainers/`
- 🔍 **wordpress-troubleshooter**: Debugging, plugin conflicts, user access issues - Public: `/training-login/`, `/find-a-trainer/`
- 🧪 **wordpress-tester**: Comprehensive testing, E2E tests, deployment validation (**MANDATORY before deployments**)
- 🚀 **wordpress-deployment-engineer**: Staging/production deployments, CI/CD, backups
### 5. **Testing & Debugging Process** ## Critical Warnings
1. **Use wordpress-troubleshooter agent for systematic diagnosis**
2. **Create comprehensive test suite with wordpress-tester agent** ### NEVER Do
3. **Apply wordpress-code-reviewer for security validation** - Deploy to production without explicit user request
4. **Run mandatory pre-deployment tests with wordpress-tester** - Skip pre-deployment validation (`scripts/pre-deployment-check.sh`)
5. **Use wordpress-deployment-engineer for staging deployment and validation** - Use static method calls without verifying singleton pattern
- Re-enable monitoring infrastructure (causes PHP segmentation faults)
### Disabled Systems (DO NOT RE-ENABLE)
The following monitoring systems are PERMANENTLY DISABLED due to causing PHP segmentation faults:
`HVAC_Background_Jobs`, `HVAC_Health_Monitor`, `HVAC_Error_Recovery`, `HVAC_Security_Monitor`, `HVAC_Performance_Monitor`, `HVAC_Backup_Manager`, `HVAC_Cache_Optimizer`
## Zoho CRM Integration
Located in `includes/zoho/`. Maps WordPress data to Zoho CRM:
- Events → Campaigns
- Trainers → Contacts
- Attendees → Contacts + Campaign Members
- RSVPs → Leads + Campaign Members
**Admin Page**: `/wp-admin/admin.php?page=hvac-zoho-sync`
**Important**: Staging environment blocks all write operations to Zoho CRM. Only production can sync data.
## Docker Test Environment
### 6. **WordPress Error Detection & Site Health**
```bash ```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 docker compose -f tests/docker-compose.test.yml up -d
# Access WordPress test instance # Services:
http://localhost:8080 # WordPress 6.4 (PHP 8.2): http://localhost:8080
# MySQL 8.0: port 3307
# Services included: # Redis 7: port 6380
# - WordPress 6.4 (PHP 8.2) on port 8080 # Mailhog: http://localhost:8025
# - MySQL 8.0 on port 3307 # PhpMyAdmin: http://localhost:8081
# - Redis 7 on port 6380
# - Mailhog (email testing) on port 8025
# - PhpMyAdmin on port 8081
``` ```
### Test Framework Architecture ## Technical Debt
- **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 ### TEC Community Events Dependency
```bash The plugin still relies on "The Events Calendar: Community" (TEC CE) for event creation/editing forms via `[tribe_community_events]` shortcode. While `HVAC_Event_Manager` has custom CRUD capabilities, production code paths use TEC CE.
# 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 **Removal estimate:** 9-14 days of development work.
**Details:** See [docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md](docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md)
**DATE: August 8, 2025** **Status:** Deferred - Current implementation is functional and stable.
**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 ## Key Documentation
**DO NOT RE-ENABLE** without thorough debugging. - **[Status.md](Status.md)** - Current project status and recent changes
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture details
## 🎯 WordPress Development Workflow - **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[docs/TESTING-GUIDE.md](docs/TESTING-GUIDE.md)** - Testing procedures
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.*

34
Status.md
View file

@ -1,12 +1,38 @@
# HVAC Community Events - Project Status # HVAC Community Events - Project Status
**Last Updated:** December 21, 2025 **Last Updated:** January 5, 2026
**Current Session:** Public Map Fix (Strategy H) - In Verification **Current Session:** TEC Community Events Dependency Analysis - Complete
**Version:** 2.1.11 (Deployed to Production) **Version:** 2.1.11 (Deployed to Production)
--- ---
## 🎯 CURRENT SESSION - SCHEDULED SYNC PERSISTENCE FIX (Dec 20, 2025) ## 🎯 CURRENT SESSION - TEC COMMUNITY EVENTS DEPENDENCY ANALYSIS (Jan 5, 2026)
### Status: ✅ **COMPLETE - Documented as Technical Debt**
**Objective:** Analyze whether "The Events Calendar: Community" (TEC CE) plugin is still being used after recent refactoring.
**Findings:**
- The plugin **still actively relies on TEC CE** for event creation/editing
- Core shortcode `[tribe_community_events]` is used in 7 template/class files
- TEC CE hooks are used for field processing and form customization
- `HVAC_Event_Manager` has custom CRUD capabilities but production paths use TEC CE
**Removal Scope:**
- **Estimated effort:** 9-14 days of development
- **Key work:** Custom forms, date pickers, validation, template updates, testing
- **Risk:** Recurring events complexity, Event Tickets integration
**Decision:** Deferred as technical debt. Current implementation is functional and stable.
### Deliverables
1. ✅ **Analysis Report:** `docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md`
2. ✅ **CLAUDE.md Updated:** Added Technical Debt section
3. ✅ **Status.md Updated:** This entry
---
## 📋 PREVIOUS SESSION - SCHEDULED SYNC PERSISTENCE FIX (Dec 20, 2025)
### Status: ✅ **COMPLETE - Deployed to Production** ### Status: ✅ **COMPLETE - Deployed to Production**
@ -39,7 +65,7 @@
--- ---
## 🎯 CURRENT SESSION - PUBLIC MAP & DIRECTORY FIX (Dec 21, 2025) ## 📋 PREVIOUS SESSION - PUBLIC MAP & DIRECTORY FIX (Dec 21, 2025)
### Status: 🔄 **IN PROGRESS - Deployed to Staging (Strategy H)** ### Status: 🔄 **IN PROGRESS - Deployed to Staging (Strategy H)**