Document Type: Standard
Status: Active
Authority: HeadOffice
Applies To: All MWMS PHP, WordPress plugin, admin UI, Supabase, and Brain implementation work
Parent: Governance
Version: v1.0
Last Reviewed: 2026-04-28
Purpose
This standard defines how MWMS plugin builds must be coordinated so PHP files, plugin modules, admin pages, Supabase logic, and AI-assisted outputs remain easy to understand, update, debug, and extend.
Its purpose is to prevent:
• oversized plugin files
• confusing build instructions
• scattered logic
• fragile edits
• repeated debugging caused by unclear structure
• future rework caused by poor modularity
• M needing to guess where code belongs
MWMS plugin development must be simple to follow, simple to replace, and simple to repair.
Scope
This standard applies to:
• WordPress plugins
• MWMS Brain plugins
• admin pages
• PHP modules
• Supabase handlers
• render helpers
• save handlers
• status handlers
• queue screens
• record screens
• AI-generated code outputs
• M’s development tasks
It governs how plugin work is coordinated and delivered.
It does not govern:
• Canon promotion
• Brain authority rules
• financial decisions
• testing strategy
• campaign execution
Core Principle
Plugin builds must be coordinated through clear modular structure.
The developer should always know:
• what file controls the page
• what file saves data
• what file renders the UI
• what file talks to Supabase
• what file handles actions
• what can be safely replaced
If the structure is hard to explain, the plugin is too messy.
Build Coordination Rules
Rule 1 — One Task At A Time
Each build instruction must focus on one clear task.
Correct:
Build Opportunity Intake Queue.
Incorrect:
Build intake, research handoff, dashboard, finance review, and automation.
Rule 2 — Simple Instructions Are Allowed
The operator does not need to provide a full technical template.
The operator may give a simple instruction such as:
Build the intake queue.
The AI must translate that into compliant technical guidance.
Rule 3 — AI Must Enforce Structure
The AI must silently enforce:
• correct Brain scope
• correct phase boundary
• correct file structure
• full-file output
• modular PHP structure
• Supabase naming discipline
• no premature feature expansion
The operator should not need to remember every technical rule.
Rule 4 — Main Plugin File Must Stay Light
Main plugin files should only handle:
• plugin header
• constants
• includes
• hooks
• initialization
They should not contain large UI screens or complex business logic.
Rule 5 — Split Files By Responsibility
Plugin files should be grouped by job.
Preferred structure:
admin/pages/
admin/actions/
admin/helpers/
admin/render/
admin/assets/
includes/
Example:
admin/pages/opportunity-intake-queue.php
admin/pages/opportunity-intake-record.php
admin/actions/opportunity-intake-save.php
admin/actions/opportunity-intake-status.php
admin/helpers/opportunity-intake-data.php
admin/render/opportunity-intake-render.php
Rule 6 — File Names Must Be Predictable
File names must clearly describe their purpose.
Correct:
opportunity-intake-queue.php
opportunity-intake-record.php
research-handoff-save.php
Incorrect:
new-page.php
functions2.php
test-fix.php
stuff.php
Rule 7 — Functions Must Be Named Clearly
PHP functions must describe what they do.
Correct:
mwms_affiliate_render_opportunity_intake_queue()
mwms_affiliate_save_opportunity_intake_record()
mwms_affiliate_update_opportunity_status()
Incorrect:
save_data()
do_update()
render_page()
Rule 8 — Full File Output Is Required For Replacement
When code is provided for M to paste into a file, it must be:
• complete
• copy-paste ready
• full file replacement
• not a fragment
• not a patch
M should not need to manually assemble code.
Rule 9 — No Hidden Coupling
One plugin page must not secretly depend on unclear logic in another file.
If a file depends on another file, that relationship must be obvious through:
• require_once include
• clear function name
• clear helper file
• clear data flow
Rule 10 — Supabase Logic Must Be Isolated
Supabase calls should be kept in data/helper files where practical.
UI files should not become crowded with raw data-access logic.
Preferred pattern:
Page file → calls helper
Helper file → talks to Supabase
Render file → formats output
Rule 11 — UI Must Be Easy To Debug
Each admin page should make it clear:
• what data is loaded
• what actions are available
• what happens after save
• where errors appear
• where success messages appear
No silent failures.
Rule 12 — Status Actions Must Be Explicit
Status-changing buttons must clearly map to one allowed status.
Example:
Move To Under Review → under_review
Reject → rejected
Escalate → escalated
No unclear labels.
Rule 13 — Validation Must Be Close To The Action
If an action requires fields, the validation must happen before the action completes.
Example:
Escalate must check required fields before setting status to escalated.
Rule 14 — Future Features Must Not Be Built Early
Plugin files may include future-safe nullable fields when required for lineage.
But they must not build future systems early.
Allowed:
offer_intel_id as nullable future linkage field.
Not allowed:
building Offer Intelligence UI during Phase 1 intake.
Rule 15 — Every Build Must Be Testable
A build is not complete until M can test it.
Each build step must have simple checks:
• page loads
• record saves
• data persists after refresh
• status updates
• no PHP warnings
• no broken UI
Daily Working Method
The operator gives a short task.
Example:
Build the intake record form.
The AI responds with:
• correct scope
• exact files needed
• full file output when needed
• testing steps
• warnings if the task tries to overbuild
M implements the file.
M reports:
• works
• error message
• screenshot
• code file
The AI then fixes the next smallest problem.
Required Plugin Build Flow
Every plugin feature should follow this order:
- Confirm active Brain and scope
- Confirm what is not allowed
- Identify existing files
- Add or replace one file at a time
- Keep data logic separate from render logic where practical
- Test save/load/status behaviour
- Fix warnings before adding more features
- Stop when the phase definition of done is reached
PHP Coordination Pattern
Preferred PHP structure:
Main plugin file
→ loads page files
→ loads action files
→ loads helper files
→ registers menu/hooks
Page file
→ controls screen layout
Action file
→ handles POST/status/save actions
Helper file
→ fetches and saves data
Render file
→ outputs reusable UI blocks
Asset file
→ loads CSS/JS only when needed
Error Handling Rules
Plugin code must handle:
• missing fields
• null values
• empty strings
• failed Supabase responses
• invalid status actions
• missing IDs
• refresh persistence
Never show:
• undefined index warnings
• null string warnings
• broken layout
• silent failed save
Phase Discipline
Each task must stay inside the active phase.
For Opportunity Intake Phase 1, allowed work is:
• intake table
• intake form
• intake queue
• status changes
• save/edit persistence
• reject
• escalate status only
Not allowed:
• Offer Intelligence UI
• Research automation
• Finance logic
• dashboards
• AI logic
• scoring systems
• forecasting
• measurement planning
Governance Role
This standard allows HeadOffice to keep plugin development controlled without forcing M or the operator to use painful templates.
It keeps development:
• clear
• modular
• testable
• easy to update
• easy to debug
• aligned with MWMS architecture
Relationship To Other MWMS Standards
This standard works alongside:
• MWMS PHP Build And Modularity Standard
• MWMS Supabase Naming Standard
• MWMS AI Output Standard Full File Delivery Rule
• MWMS Brain Routing Rule
• MWMS MCR To Brain Copy Rule
• MWMS Opportunity System Implementation Brief For M
Drift Protection
The system must prevent:
• giant all-in-one plugin files
• unclear instructions
• patch-style code delivery
• mixed responsibilities inside one file
• hidden Supabase logic inside UI screens
• future phase logic appearing early
• unclear status actions
• code that M cannot easily replace
• debugging that requires guessing
Architectural Intent
This standard makes MWMS plugin development practical.
It allows the operator to speak simply while the AI maintains technical discipline.
It converts plugin development from:
confusing instruction chains
→
clear coordinated build steps
The system becomes easier to build because the rules live in MCR, not in M’s head.
Change Log
Version: v1.0
Date: 2026-04-28
Author: HeadOffice
Change: Initial creation of MWMS Plugin Build Coordination Standard defining simple operator instructions, modular PHP coordination, full-file delivery, debugging discipline, and phase-safe plugin build rules.
END MWMS PLUGIN BUILD COORDINATION STANDARD v1.0