CLIENT PLUGIN BUILD PLAYBOOK v1
Status: Active
Owner: Phil
Applies to: All custom WordPress plugins built for clients including internal commercial projects such as For Any Occasion
PURPOSE
This playbook sets the standing rules for planning, building, rebuilding, refactoring, debugging, simplifying, validating, packaging, releasing, and supporting custom client plugins.
Read this playbook before making any technical decision on a client plugin build.
CORE PRINCIPLES
Every plugin must aim to be:
clean
modular
fast
maintainable
scalable
commercially useful
safe to update
easy to debug
easy to hand over
A plugin should become stronger over time, not messier.
SOURCE OF TRUTH RULE
Use these sources in order:
Latest uploaded stable plugin = live technical truth
Latest approved brief or agreed scope = commercial truth
This playbook = operating rulebook
If these conflict:
inspect first
identify the gap clearly
explain clearly
agree direction before building
Never assume the live website reflects the best code version.
BUILD BASE RULE
Always build from the latest uploaded stable plugin unless instructed otherwise.
If a rollback version is uploaded, that becomes the new stable base.
Rules:
never build from memory
never assume newest means safest
never rebuild from older copies unless instructed
uploaded stable plugin is the working base
BUILD MINDSET RULE
Approach every build as expert level engineering work.
Always aim to:
simplify
optimise
reduce moving parts
remove friction
improve speed
improve maintainability
reduce future support burden
Do not accept bloated, messy, duplicated, rushed, or fragile solutions when a cleaner one exists.
SCOPE CONTROL RULE
Only build what is agreed for the current phase.
Separate clearly:
bugs
enhancements
refactors
future ideas
optional upgrades
Do not silently expand scope.
Log extras for future phases.
ARCHITECTURE RULE
Build one clean WordPress plugin with internal modular structure.
Core should handle:
boot
module loading
shared helpers
config
settings
permissions
logging
health checks
shared UI systems
Modules should be:
self-contained
loosely coupled
reusable
cleanly registered
easy to remove or extend
UNIFIED CODE RULE
Use one shared method for repeated jobs.
Standardise where possible:
settings handling
AJAX/request handling
logging
notices
tables/lists
modal systems
asset loading
naming conventions
permission checks
Do not solve the same problem three different ways inside one plugin.
SLIMLINE CODE RULE
Every file, function, asset, dependency, and feature must justify its place.
Avoid:
unnecessary libraries
duplicate utilities
dead CSS
dead JS
retired handlers
oversized files
wrapper code with no value
patch-on-patch systems
Prefer lean clear code.
CONFIG-FIRST RULE
Where sensible, place changeable logic into config rather than hardcoded logic.
Examples:
labels
feature toggles
API endpoints
roles
UI options
supported post types
colours
version markers
limits
module states
This improves reuse and future updates.
ONE SOURCE OF TRUTH RULE
Shared business logic must live in one controlled place only.
Single truth examples:
version numbers
plugin options
labels
permissions
feature flags
route names
core selectors
integration keys
If drift exists, unify before extending.
CORE VS CUSTOM RULE
Separate clearly:
Core systems:
framework logic
shared UI
helpers
settings
diagnostics
Client custom systems:
branding
business rules
workflow steps
front-end experiences
bespoke integrations
Do not tangle reusable code with one-off code.
PERFORMANCE RULE
Speed is a priority.
Optimise for:
fast page load
fast admin screens
instant UI reactions
minimal queries
lightweight assets
low friction workflows
Avoid:
loading assets everywhere
unnecessary AJAX
repeated database calls
large blocking scripts
laggy interfaces
Plugins should feel premium and immediate.
UI RULE
Interfaces should feel:
clean
compact
clear
premium
on-brand
easy to learn
Use shared tokens or central styling systems where possible.
Avoid random one-off controls.
INTEGRATION SAFETY RULE
When working with tools such as WooCommerce, Elementor, LearnDash or Advanced Custom Fields:
inspect real hooks first
verify data structures
fail gracefully if missing
isolate integration code
do not assume updates keep behaviour identical
DATA SAFETY RULE
Protect existing data.
Rules:
preserve settings on upgrade
avoid destructive changes casually
migrations must be deliberate
reversible where possible
backups recommended before structural changes
Never risk client data for convenience.
DEBUGGER STANDARD
Serious client plugins should include an internal debugger unless clearly unnecessary.
Standard tools:
debug mode on/off
log viewer
recent errors
request failures
version snapshot
environment snapshot
config visibility
health checks
copy logs
clear logs
Rules:
admins only
no sensitive data exposure
disable cleanly on live sites if needed
HEALTH CHECK RULE
Before major builds or releases run health checks.
Check:
missing assets
invalid paths
duplicate hooks
module registration
version drift
dependency issues
bloated files
stale legacy markers
config drift
If risks are found:
stabilise first unless directed otherwise
REWRITE RULE
Do not patch weak systems when a clean rebuild is safer.
Where justified:
rewrite cleanly
reduce total code
improve structure
preserve user-facing behaviour unless agreed otherwise
High-risk rewrites should have rollback points.
TROUBLESHOOTING RULE
Do not guess.
Workflow:
inspect code
reproduce issue
gather evidence
use browser diagnostics where relevant
identify root cause
fix correctly
retest
package only when stable
VALIDATION BEFORE DELIVERY
Confirm:
plugin installs
plugin activates
no fatal errors
assets load
settings save
modules load
front-end works
admin works
debugger works
version consistent
overwrite works
no obvious console errors
PACKAGING RULE
Packaging is part of the build.
Before presenting:
ZIP created successfully
correct folder structure
correct filenames
downloadable package
install tested where possible
Never claim complete before packaging is genuinely ready.
VERSION RULE
Use one version only across the whole plugin.
Must match everywhere:
plugin header
constants
PHP files
JS files
CSS files
admin footer
visible UI version areas
ZIP filename
No mismatches.
NAMING RULE
Use clear stable naming.
Examples:
Folder name: client-plugin-slug
Main file: client-plugin-slug.php
ZIP: client-plugin-slug-vx-x-x.zip
Use prefixes for:
PHP functions
classes
options
AJAX actions
JS globals
DOCUMENTATION AND HANDOVER RULE
Each serious plugin should have simple support notes covering:
what it does
key settings
dependencies
known limits
debug location
rollback version
future opportunities
PROTECTED SYSTEMS RULE
Identify areas that must not be casually destabilised.
Examples:
checkout flow
lead capture forms
booking flow
search systems
saved selections
admin data tools
client dashboards
Use extra caution before touching them.
OUTPUT REQUIRED FOR EVERY BUILD
Every release response should include:
ZIP filename
version
summary of changes
testing checklist
rollback notes
upgrade notes if relevant
STANDING INSTRUCTION
Read this playbook first.
Inspect uploaded stable plugin second.
Use the plugin as technical truth.
Use this playbook as the operating rulebook.
Build modularly.
Keep code slimline.
Use unified systems.
Diagnose properly.
Protect data.
Package properly.
Only present builds when genuinely ready.
