roles-wp-details

Product / PM for WordPress • Validate the plugin idea — confirm the WP-specific pain + why existing plugins fail Before investing time in development, ensure there’s a real WordPress-specific problem your plugin will solve. Research your target audience’s pain points and check the Plugin Directory for existing solutions. If similar plugins exist, identify why they aren’t meeting users’ needs (e.g. outdated, missing features, poor support). Validating the idea early prevents reinventing the wheel. Engaging with the community (support forums, reviews) can reveal unaddressed frustrations and confirm demand for your plugin. (Tip: Hosting a free version on WordPress.org can help gauge interest and validate your idea with real users  .) • /wp-pm:problem-brief [audience] [pain] Summarize the problem your plugin solves in a brief targeted statement. Specify who is experiencing the pain (e.g. “WooCommerce store owners”) and what the pain is (e.g. “difficulty managing bulk discounts”). A clear problem brief keeps development focused on real needs and communicates the value proposition to stakeholders or users. It should answer: For [audience], the plugin solves [pain]. This clarity will guide your feature decisions and marketing. • Pick the distribution model — WordPress.org vs freemium vs premium licensing Decide how you’ll distribute and monetize your plugin early on. The WordPress.org repository offers easy discovery and updates (and is often used even by commercial plugins to provide a free lite version) . A freemium model typically means a free base plugin on .org and paid upgrades or add-ons; it can build an audience quickly but requires maintaining two codebases (lite and pro). A premium-only model (selling via your own site or marketplace) lets you charge for all installs but means you handle marketing and updates outside .org. Consider your goals and resources: .org exposure can help validate your idea and attract users , whereas a premium model might suit niche, B2B, or highly support-intensive plugins. Ensure your choice aligns with how you plan to support and maintain the plugin long-term. • /wp-pm:monetization-plan [model] Create a plan for generating revenue if applicable. For a freemium model, decide which features are free vs. paid (ensure the free version is useful but leaves room for upgrades). If using licenses for a premium plugin, plan pricing tiers and renewal terms. Outline how you’ll handle license checks and updates (e.g. via a custom update server or a service) and be transparent with users. The plan should also cover any SaaS costs or integrations if your plugin relies on external services. By having a clear monetization strategy, you can build features accordingly (for example, gating pro features behind license activation gracefully). • /wp-pm:org-vs-pro-constraints [feature] When offering both a .org version and a pro version, map out which features belong in each to avoid confusion or overlap. Follow the repository guidelines by not crippling the free plugin – it should solve the core problem, while the pro adds advanced or time-saving features. For each major feature, decide if it’s core (in the free plugin) or premium. Document these decisions (perhaps in your README FAQ: “What’s in Pro vs Free”) so users know the upgrade benefits. Also, consider technical constraints: the free and paid versions must not conflict. Many developers use unique prefixes or separate namespaces so both versions can’t be active simultaneously without issues. Clearly separating features will make maintenance easier and users happier. • Name + namespace strategy — slug, prefix, text-domain, brand consistency Choose a unique plugin slug (machine name) and ensure consistency across your code and assets. The slug usually becomes the text domain for translations and the prefix for functions/classes. For example, if your plugin is “Easy Custom Foo,” a slug might be easy-custom-foo, and you might prefix functions with ecf_. Prefix everything global in your code with a unique identifier 4-5 characters long  (avoid very common words or wp_ to prevent collisions ). Use the same prefix for option names, nonces, database entries, etc. Maintain brand consistency: the plugin’s Name (for humans) should relate to the slug but can be more readable (just keep the “Plugin Name:” header matching exactly in all files). Also, set the correct Text Domain in your main file header to exactly match the plugin’s folder/slug . This ensures translation files from WordPress.org will load properly. By planning naming and namespaces from the start, you prevent conflicts and make your plugin identifiable in any WordPress environment. • /wp-pm:slug-namespace [plugin-name] Given a plugin name, craft a standardized slug and namespace/prefix. For example, for “[plugin-name],” you might derive a slug like plugin-name or a shorter variant if needed. Use that slug as the text domain and prefix (e.g. plugin_name_ for functions, PluginName\ for PHP namespaces). Document this choice so any contributors follow it. This skill ensures all code, hooks, and handles are neatly namespaced under your plugin’s identity, reducing conflict risk. • Define minimum supported WP/PHP — decide baseline + target hosting reality Determine the oldest WordPress version and PHP version your plugin will support, balancing reach vs. development convenience. Check the official recommendations: WordPress currently recommends PHP 8.0+ and works on PHP 7.2.24+ , but many sites still use older PHP. Also consider functions/APIs your plugin needs – if you rely on features added in recent WP releases, you may set a higher minimum. Look at WordPress.org “Requires at least” stats or the usage of versions. In your plugin header, declare Requires at least: X.Y and Requires PHP: A.B to inform users . It’s often wise to support at least the latest major WordPress release and maybe one or two before it (since auto-updates keep many users current). For PHP, supporting down to 7.4 or 7.2 expands compatibility, but if you need newer features or security, you might require 7.4+ or 8.0+. Make this decision early and test under those environments. This baseline will guide which functions or language features you can use. (Note: WordPress core itself will not activate a plugin if the PHP version is below your Requires PHP declaration .) • /wp-pm:support-matrix [wp] [php] List the versions of WordPress and PHP your plugin supports, and plan testing around them. For example: “Supported WordPress versions: 5.5 – 6.3; Supported PHP versions: 7.4 – 8.2.” This matrix helps in QA planning. It’s good practice to verify the plugin on the oldest and latest of each range (e.g. WP 5.5, 6.3; PHP 7.4, 8.2) to catch compatibility issues. Document this in your README or documentation so users know what environment is required. • Write a WordPress-first spec — admin pages, settings, hooks, roles, behaviors When writing your product requirements or design spec, consider WordPress conventions at every step. Describe how the plugin will integrate into WP Admin (Will it add a top-level menu or a submenu under “Settings”? What settings screens or meta boxes are needed?). Identify which hooks (actions and filters) you might leverage or provide – e.g. note “use the_content filter to inject output” or “add a custom action hook after form submission for extensibility.” Incorporate capabilities/roles in your spec: decide what capability is required to access the plugin’s settings or features (usually manage_options for settings pages, or custom caps if defining custom post types). Specify expected behaviors in different contexts – e.g. “If user lacks capability X, the menu is hidden,” or “On multisite, settings are per site.” A WordPress-centric spec ensures you plan features the “WP way.” It’s also helpful to plan how the plugin will behave on activation, upgrade, and deletion (in line with WP life-cycle hooks). By detailing admin UI elements and hook points in the spec, development will align with core UX patterns and integrate smoothly into the WordPress experience. • /wp-spec:plugin-prd [feature] [wp-context] Generate a mini product requirement description for a feature in WordPress context. For example, given a feature (“schedule automatic backups”), describe it in WP terms: “The plugin will add an admin page ‘Backup Settings’ under Tools menu, where administrators (capability manage_options) can schedule automatic backups. It will use WP-Cron to trigger backup events and provide a settings field for frequency (daily/weekly). When a backup runs, it uses WordPress filesystem APIs to create a ZIP of /wp-content and exports the database. Upon success, it will email the site admin and log an entry in a custom post type ‘Backup Log’. There will be an action hook pluginname_backup_completed after each backup.” This kind of context-rich spec aligns the feature with WordPress concepts (cron, roles, filesystem, CPT, hooks) and makes development clearer.

⸻

Plugin Engineering Core (PHP / WordPress APIs) • Choose plugin architecture — structure, autoloading, responsibilities Plan your plugin’s code structure before you start coding. Small, single-file plugins can be simple, but for anything substantial, organize code into classes and files. Decide if you’ll use a functional approach or OOP. Many developers set up a main plugin class or use a loader pattern. Consider using PSR-4 autoloading (perhaps via Composer) to automatically load classes. Define clear responsibilities for each component (e.g. one class for admin UI, one for front-end functionality, separate files for custom post types or widget definitions). The WordPress Plugin Handbook suggests using classes for large plugins and splitting code into logical parts (admin vs public)  . For example, you might have an /includes folder for core logic, /admin for admin-only code, /public for front-end code . Ensuring a clean architecture (MVC, if applicable, or at least separation of concerns) will make maintenance and scaling easier. Also, mitigate global scope usage – perhaps have a singleton or a static instance for your plugin to avoid global variables. • /wp-dev:architecture [type] Outline an architecture style for the plugin (e.g. “MVC” or “Singleton-based” or “Modular with Hooks”). For instance: Type: MVC. Plan to separate data handling, logic, and presentation. Use WordPress hooks as the “Controller” mechanism that triggers logic in response to events (like saving a post). The Model could be classes that interact with the database (options, custom tables, etc.), View could be PHP templates for output (loaded via functions), and Controller code in the main plugin file that hooks everything together. Detailing this ensures the development team knows how to implement new features consistently within that architecture. • Create plugin scaffold — header, main file, loader, activation/deactivation Start your plugin with the essential files and boilerplate code. The main plugin PHP file should contain the plugin header comment (with Plugin Name, URI, Author, Version, etc.)  . Include safety checks like if ( ! defined('ABSPATH') ) exit; at top of PHP files to prevent direct access . Set up activation and deactivation hooks using register_activation_hook() and register_deactivation_hook()   to handle setup and cleanup (e.g. flushing rewrite rules, initializing default options)  . For structure, you might create a loader class or simply include required files from the main file. It’s helpful to scaffold the directories (as mentioned: admin, public, includes, languages, etc.) . You can use WP-CLI to generate a plugin scaffold quickly (wp scaffold plugin ) which produces a basic file structure with sample code and even a PHPUnit test setup . Ensure your scaffold includes an uninstall handler (either an uninstall.php or using register_uninstall_hook) for complete cleanup. Having a solid scaffold means from day one your plugin adheres to WP conventions and has the basic wiring for longevity. (Remember to include a readme.txt and license file in your scaffold as well.) • /wp-dev:scaffold [slug] Generate a basic file structure for a new plugin identified by [slug]. This typically includes: • Main PHP file named after the slug, with plugin header and basic class/function definitions. • uninstall.php for uninstall cleanup if needed. • Subfolders like /includes/ for core logic, /admin/ for admin-facing code (e.g. settings pages), /public/ for front-end code, /languages/ for .pot files. • Perhaps a tests folder if using tests. Using WP-CLI (wp scaffold plugin-tests) can set up a testing framework . By scaffolding, you ensure consistency and save time. This skill yields a ready-to-go plugin skeleton so developers can jump straight into writing features. • Plan data storage — Options API vs meta vs CPT vs custom tables Decide how and where your plugin will store its data. WordPress offers multiple storage APIs: Options (wp_options table) for site-wide settings, Metadata (post meta, user meta, comment meta) for data tied to specific objects, Custom Post Types (CPTs) for content-like data, or even Custom Database Tables for complex, highly relational data. Choose the simplest that fits your needs: for example, a plugin with a few global settings can use the Options API (add_option(), get_option()) . If you need to store multiple entries of a certain entity, consider a CPT (which gives you WP admin UI, querying via WP_Query, etc. out of the box  ) – but note CPT data is stored in posts and postmeta tables, which is great for “publishable” content but may be overkill for ephemeral data. Post meta is useful for storing additional info related to posts/users but not ideal for large or highly queried datasets due to performance (unindexed key-value queries) . Custom tables can be optimal for complex data or large datasets, at the cost of more complexity – you’ll need to handle CRUD and possibly version upgrades of schema. According to WordPress experts, if your data is very “post-like” and not huge in volume, a CPT with meta is beneficial due to built-in UI and caching  . If the data is more complex (e.g. many-to-many relationships, or large volumes requiring efficient queries), custom tables might be warranted  . Document your choice in the design spec so it’s clear. Also plan how to retrieve and update this data (perhaps providing wrapper functions or using WP APIs). • /wp-dev:data-plan [entities] For each major data entity in your plugin, decide storage and outline its structure. For example, if [entities] = “Event bookings”, the plan could be: Use a Custom Post Type “event_booking” for each booking, storing customer info and event ID as post meta. Booking status and date will also be post meta for querying. This leverages WP’s posts table for primary data and meta for details. Alternatively, if performance tests show scaling issues at >10k bookings, consider moving to a custom table wp_event_bookings with columns for customer, event, date, status (indexed appropriately). Such a plan ensures everyone knows where data lives and how to work with it. It also flags any potential future migration (if starting simple with options/meta but leaving room for custom table later). • Register settings properly — Settings API + sanitization callbacks When creating plugin options pages, use the WordPress Settings API for robust handling. This means calling register_setting() with a sanitization callback , so any data users input on your settings screen gets validated/cleaned before saving. The Settings API allows defining sections and fields, which ensures your form output and saving logic are consistent with WP’s standards  . Provide meaningful sanitization for each setting: e.g. use sanitize_text_field for text, intval for numbers, validate emails or URLs with proper functions. By using the Settings API, you also automatically get security benefits like nonce checking and current_user_can(‘manage_options’) enforcement for saving options . Example:

add_option('myplugin_options'); // maybe add default if needed
register_setting('myplugin_options_group', 'myplugin_options', 'myplugin_sanitize_options');

Here “myplugin_sanitize_options” would check each option value. Additionally, escape output when rendering form fields. Using this API yields a settings page that looks and behaves like core (with the WP admin styles, and your values saved in the options table safely). Always test saving with valid and invalid data to ensure your sanitization works (e.g. try injecting HTML or script – the sanitization callback should strip or escape it). Following these practices prevents malicious or malformed data from entering your database  .

•	/wp-dev:settings-api [settings]

Create a checklist or snippet for adding a setting named [settings] using the Settings API. For instance, if [settings] = “newsletter_signup (checkbox)”: 1. Register: register_setting('myplugin_options_group', 'newsletter_signup_option', 'absint'); (using absint to sanitize to 0/1). 2. Add Section (if not already): add_settings_section('myplugin_main', 'Main Settings', null, 'myplugin'); 3. Add Field: add_settings_field('newsletter_signup_option', 'Enable Newsletter Signup', 'myplugin_render_checkbox', 'myplugin', 'myplugin_main'); – where myplugin_render_checkbox() echoes a and checks it if option == 1. 4. In the settings page form (e.g. created via add_options_page), call settings_fields('myplugin_options_group') and do_settings_sections('myplugin') inside a

. This outline ensures all parts (registration, field output, and form wrappers) are covered. It’s a template you can reuse for multiple settings with different field types and sanitizers. • Hook into actions/filters — implement features via hooks (WP way) Embrace WordPress’s hook system to integrate your plugin rather than hacking core or output directly. Identify key actions or filters where your code should run. For example, use add_action('init', ...) to register custom post types or shortcodes, add_action('admin_menu', ...) to add admin pages, or add_filter('the_content', ...) to inject front-end content. Implementing features “the WP way” means your plugin will play nicely with others and WordPress updates  . Also consider providing your own hooks in your plugin (do_action/do_filter) to allow extensibility . When hooking, always pass a unique function name or class method (prefixed as above) and a sensible priority. For complex plugins, mapping out a hook plan is helpful: e.g. “On plugins_loaded -> load text domain; On init -> register post type and do other setup; On wp_enqueue_scripts -> enqueue front-end assets,” etc. By relying on hooks, you ensure your plugin runs at the right times and can be overridden or extended by others. This leads to better compatibility. (Remember: Always return values in filters, and don’t echo in unexpected places in actions – maintain expected behavior of hooks.) • /wp-dev:hook-map [feature] Outline which hooks will be used to implement [feature]. For instance, if [feature] is “add a custom banner after posts,” the hook map could be: Use the_content filter to append banner HTML at the end of post content . Additionally, hook wp_enqueue_scripts to load CSS for the banner on front-end. If banner should be customizable in admin, hook admin_init to register a setting and admin_menu to add a submenu for banner settings. This map clarifies the integration points for the feature, serving as a mini implementation plan. It ensures no core files are touched – everything is done via WordPress hooks – and helps new contributors see at a glance how the feature ties into WP’s lifecycle. • Prevent conflicts — prefixes, no globals, safe handles, compatibility habits Conflict prevention is crucial for plugins, given the shared global space. Namespaces/Prefixes: As noted, prefix all your functions, classes, constants, and global variables with your plugin’s unique prefix . Better yet, use PHP namespaces if possible to encapsulate classes. Avoid creating variables or defining constants in the global scope unless necessary (and if so, prefix them uniquely). No redeclaring core or common things: never use names that might already exist. For enqueueing scripts/styles, use distinctive handles (e.g. 'myplugin-slider-js' rather than 'slider') so they don’t clobber other plugins’ enqueues. Function exists checks: If you must create a function in global namespace, consider wrapping it:

if(! function_exists('myplugin_helper')){ function myplugin_helper(){ … } }

– though note this can mask conflicts rather than solve them (better to always prefix to avoid name collision in the first place) . Avoid modifying global $wpdb, $post etc. beyond use – don’t unset or change them unexpectedly. CSS/JS conflicts: scope your CSS (e.g. prefix class names or limit styles to a specific admin page via IDs) to avoid affecting other plugins or themes. Use wp_enqueue_style for CSS with a unique handle so it can be dequeued if needed. jQuery/$ in JS: use WordPress’s safe mode (no-conflict) by wrapping your JS in a closure or use jQuery instead of $ unless you ensure noConflict. Compatibility checks: If you integrate with other plugins (like WooCommerce), check they’re active with function_exists or class exists before calling their functions. Periodically review your prefix against the plugin directory (to ensure no one else accidentally used the same). Following these habits will minimize “plugin conflict” issues where two plugins try to do the same thing or use the same names. The WordPress Plugin Handbook explicitly recommends using a 5+ character unique prefix to avoid collisions .

•	/wp-dev:conflict-audit [codebase]

Perform a conflict audit on [codebase] by scanning for any un-prefixed or potentially clashing identifiers. For example, search the code for generic names: function names like translate(), class names like Logger, global variables like $helper – these should be renamed to something unique (myplugin_translate, MyPlugin_Logger, $myplugin_helper). Check asset handles in enqueue calls – ensure none are common words. Review any third-party libraries included: if you bundle one, make sure it’s not loading in a way that conflicts (some plugins prefix the library classes or functions as well). The output of this audit is a list of items to change for better isolation, e.g.: “Rename function calculate_total() to myprefix_calculate_total().” Doing this audit and refactoring accordingly greatly reduces the chance of conflicts in user environments. • Multisite compatibility — per-site vs network, activation + UI behavior If your plugin will run on WordPress Multisite, plan for how it behaves in that context. Decide whether it can be activated per individual site, network-wide, or both. If there are shared settings across the network, you might use the network options (e.g. add_site_option()) and provide a network-admin settings page. On network activation, consider that register_activation_hook runs only once (on the main site) – so if you need to set up data on each subsite, you might have to iterate through sites on activation  . The same goes for uninstall – ensure you clean up across all sites if appropriate. UI considerations: If the plugin is useful only to superadmins, you may want to surface its menu in the Network Admin. WordPress provides hooks like network_admin_menu for adding network-level pages . Conversely, if settings are per site, keep the menu in each site’s admin (and possibly hide it when network-activated if only superadmin should change them). Also handle is_multisite() in your code for any assumptions (like using blog_id in custom table names to avoid collisions when each site writes to a table  ). Test scenarios: activate on one site vs network; ensure no unwanted data bleed between sites. Following the Multisite compatibility guidelines will make your plugin usable for those running WordPress networks without issues (note: by default, a plugin is activatable per site; adding “Network: true” in the header forces only network activation  ). Only mark that if your plugin must be network-wide. Document any multisite-specific behavior in your readme. • /wp-dev:multisite-plan [mode] Outline how the plugin operates under [mode] in multisite. For example: if [mode] = “Network Only”, plan that the plugin will be activated network-wide and available to Super Admins only. State that settings will be global (use add_site_option) and stored once for the network. The admin UI will reside in the Network Admin dashboard (hook into network_admin_menu). If [mode] = “Per Site”, note that each site can activate the plugin and have its own settings in that site’s options table; if network-activated, it will simply enable on all sites with separate configurations. If [mode] = “Hybrid”, describe which parts are network-wide vs site-specific (e.g. “License key is network-wide, but each site can enable/disable the features”). This plan ensures no ambiguity when implementing multisite support. It will also highlight if you need to use site-specific functions (get_option vs get_site_option) or loops on all sites for certain tasks . • Uninstall cleanup — uninstall.php + safe optional data removal Responsible plugins clean up after themselves when the user deletes the plugin (not just deactivates). Implement an uninstall routine to remove plugin options, custom tables, or meta entries that your plugin added, but only do so on uninstall to avoid data loss on simple deactivation . Use either an uninstall.php file or the register_uninstall_hook() in your main file to hook a cleanup function . In that routine, delete options with delete_option() (and delete_site_option() for network data) , remove custom database tables if any (using direct SQL or $wpdb->query with DROP TABLE ), and purge any custom post types or taxonomy data if it’s something the user would expect removed. Important: Only remove user data if it’s clear that’s the behavior – some plugins opt to leave data (so if the user reinstalls, their settings are intact). A good approach is to offer a setting “Remove all data on uninstall?” so the admin can decide. If you do remove posts or CPT content, consider that might be user-generated content – usually plugins do not delete posts on uninstall without explicit user consent. For transient caches or logs your plugin created, you can safely clean those. Also, guard your uninstall.php with the proper check:

if( ! defined('WP_UNINSTALL_PLUGIN') ) exit;

to ensure it only runs in the WordPress uninstall context . Document your uninstall behavior. By adhering to the uninstall best practices, your plugin won’t leave clutter in the database, which users and the Plugin Review Team appreciate  .

•	/wp-dev:uninstall-policy [data]

Define what happens to [data] when the plugin is uninstalled. For example, if [data] = “custom post type entries (events)”, your policy might be: On uninstall, do not delete Events posts, to avoid content loss – we only remove plugin settings and meta. Users can delete Events manually if desired. Or if [data] = “plugin settings and transient cache”, policy: All plugin options and transients will be removed from the database on uninstall to free space . Clearly stating this ensures you implement accordingly and users (or support team) know what to expect. If certain data should be retained (maybe for future reactivation), note that too. • Database + migrations — schema versioning + upgrade routines If your plugin uses custom database tables or has significant data structure changes over time, implement a scheme for managing DB schema versions. For custom tables, you might create them on plugin activation (using SQL CREATE TABLE with dbDelta() which WordPress provides to handle table creation/alteration safely ). Store a schema or plugin version (e.g. in an option like 'myplugin_db_version'). On plugin load, check this stored version against your code’s expected version – if they differ, run an upgrade routine. For example, if version increases, maybe you add a new column to a table or migrate option values to a new format. Use ALTER TABLE via dbDelta() or manual queries to adjust schema . Ensure to wrap these in proper checks and maybe backups. The key is to not rely solely on activation hook for upgrades – since users can update the plugin without deactivating/reactivating. Instead, perform version checks at runtime (e.g. on admin_init)  . Using semantic versioning for your plugin helps; just ensure the part that indicates a schema change triggers the routine. Also consider large datasets – break migrations into batches if needed. By maintaining a migration function, you prevent inconsistencies when users update. Always test upgrading from an older version to the newest to verify the routine works. And increment your plugin version in a way that version_compare sees as higher (WordPress will compare the version strings to prompt updates ). Overall, a disciplined approach to DB changes will save you and your users from crashes or data loss on plugin updates. • /wp-dev:migration-plan [schema] Provide a migration game plan for changes in [schema]. For instance, if [schema] refers to a custom table structure v1 to v2: Plan: Add a new column last_login to wp_member_records. Steps: 1) Check current schema version option. 2) If less than 2.0, alter the table via ALTER TABLE wp_member_records ADD last_login DATETIME DEFAULT NULL using $wpdb->query or dbDelta() with updated SQL . 3) Update the stored schema version option to 2.0. 4) Optionally, populate last_login for existing rows if data available (this might need a separate loop if heavy). Ensure to wrap this in a function upgrade_to_2_0() and call it on plugin load if needed. This plan can also mention using dbDelta rules: e.g. remember to include the exact same collation engine etc. The output is effectively pseudo-code or checklist for performing the DB upgrade safely. Having this written down makes coding it straightforward and ensures no step is missed (like updating the version option, which is crucial). • Cron tasks (if needed) — WP-Cron schedule + duplicate guards If your plugin needs to perform periodic tasks (cleanup, sending emails, syncing data), leverage WP-Cron rather than real cron, so it works in any environment. Use wp_schedule_event() to schedule recurring events on plugin activation (e.g. daily) . Always check for existing scheduled events with wp_next_scheduled() before scheduling a new one   – this avoids duplicate scheduling if activation runs again or if the event is already set up. Decide on an appropriate recurrence interval (WordPress has defaults like hourly, daily, or you can add a custom interval). When scheduling, also hook a function to the custom cron hook you name (e.g. add_action('myplugin_cron_hook', 'myplugin_cron_function')). In your cron callback, implement the task and be sure to fail gracefully (use locking if needed to prevent overlaps – e.g. using transients or wp_cron() check – though WP-Cron won’t run the same event twice at the exact same time unless you mis-schedule). On plugin deactivation, clear scheduled events via wp_unschedule_event() or wp_clear_scheduled_hook   to tidy up. This is important because orphaned cron jobs can lead to errors after plugin removal . Also consider using WP_BACKGROUND_PROCESS or action scheduler for heavy lifting in background if WP-Cron is not reliable enough – but for most cases WP-Cron suffices. Document the cron job in your readme (so admins know the plugin will run tasks in the background). With this approach, your scheduled features will run reliably and won’t stack up multiple events accidentally. • /wp-dev:cron-plan [job] Develop a cron execution plan for [job]. Suppose [job] = “expire old coupons”. Plan could be: Schedule a daily WP-Cron event 'myplugin_expire_coupons_daily'. On plugin activation, use:

if( ! wp_next_scheduled('myplugin_expire_coupons_daily') ){ wp_schedule_event(time(), 'daily', 'myplugin_expire_coupons_daily'); }

Hook a callback:

add_action('myplugin_expire_coupons_daily','expire_coupons_callback'); function expire_coupons_callback(){ // fetch coupons expiring today, mark them expired }

On deactivation:

wp_clear_scheduled_hook('myplugin_expire_coupons_daily');

This ensures one daily execution. Also implement a locking mechanism using an option or transient ‘coupons_job_running’ to avoid overlaps if one run takes very long. This plan can be adjusted for different [job] requirements (e.g. using a custom recurrence or scheduling a one-time event with wp_schedule_single_event). It serves as a blueprint for reliably running [job] via WP-Cron with no duplicates   and proper cleanup.

•	Logging/diagnostics — status page + exportable logs (privacy-aware)

For easier support and debugging, consider building logging into your plugin. Use WordPress debugging functions (error_log() when WP_DEBUG is on, or WP_DEBUG_LOG to write to debug.log) for low-level logs. For admin-facing diagnostics, you could maintain a log (in an option or custom post type) of significant events (e.g. “API sync completed” or “Error retrieving data: …”). Provide a Status/Diagnostics page in the admin where site admins can see plugin health: environment info (WP version, PHP, etc.), last run times of cron jobs, count of records, etc. Include a way to export logs (e.g. a textarea or download button for a log file) so users can provide it when reporting issues. Important: be privacy-aware – if logs might contain personal data (emails, user IDs), make sure to obfuscate or allow admins to clear them, and ensure these are included in GDPR export/erase if applicable  . Avoid logging sensitive info like passwords or nonces. Use transient debugging modes – e.g. only log extensively when a debug constant or setting is enabled, to avoid performance hit or huge log buildup in production  . By implementing diagnostics, you make it easier to support your plugin (less guesswork) and empower savvy users to self-diagnose common issues. It’s also a mark of a mature, enterprise-ready plugin to have a built-in status report. Document how to use these tools (perhaps in your FAQ: “How do I enable debug mode?”). • /wp-dev:diagnostics-screen [signals] Design an admin “Diagnostics” screen that shows [signals] from your plugin. For example, for a caching plugin, [signals] could include: cache size, number of cached items, last purge time, current configuration, and recent errors. Layout: a table or list of key–value pairs (Signal → Current status/value). E.g.: Cache Directory Writable: Yes/No; Cache Entries: 124 files (~32 MB); Last Cache Clear: 2024-01-10 14:32:00; WP Cron Schedule: Next cache preload in 6 hours. Additionally, include buttons like “Clear Cache Now” or “Download Log” if relevant. Ensure each signal updates in real-time (or on page load). If implementing an export, perhaps compile all signals + recent log lines into a text area for copy-paste. This skill yields a plan for exactly what diagnostics to show, making implementation straightforward. It helps identify which pieces of plugin state are most useful for troubleshooting so you can gather them in one place.

⸻

WP Admin UX (WP-Admin patterns) • Build the admin UI — menus, pages, forms, notices, WP patterns Design your plugin’s admin interface to feel native to WordPress. Determine where in the admin menu it belongs: small settings often go under Settings or Tools as a submenu , whereas large plugins might warrant their own top-level menu (with an icon). Adhere to the WordPress admin styles by using the correct markup and classes (e.g. wrap settings forms in

and use submit_button() for Save buttons). Use the Settings API for forms as discussed, which yields familiar UI controls . Provide context-sensitive notices: for example, after saving settings, use add_settings_error() and settings_errors() to show an updated message (WordPress will automatically display it). Use the standard WP notice classes (notice notice-success/error) for any custom admin notices – this ensures they match core styling. Keep pages clean: rely on WordPress typography and spacing; avoid heavy custom CSS in the admin. If the plugin performs actions that need user feedback (like “import completed” or “error occurred”), display admin notices at the top of the relevant page upon reload, using admin_notices hook, and make them dismissible if appropriate  . For complex UIs, consider leveraging existing WP components (like list tables for listing items, the media uploader for selecting files, etc.) rather than reinventing. Always test your admin UI on different screen sizes and with the admin color schemes if possible, to ensure it remains accessible. By following core UI patterns and using existing markup structures, your plugin will “feel” like part of WordPress – which improves user trust and usability. • /wp-admin:menu-ia [pages] Plan the information architecture for admin menus/pages. Suppose [pages] is a list like “Settings, Logs, Tools”. Determine hierarchy: e.g. Top-level menu: “My Plugin” (icon dashicon-admin-generic), which opens to a Settings page by default. Under it, Logs and Tools as submenus. Or, if minor: put Settings under WordPress Settings menu (no top-level), and maybe have a Tools page under Tools for one-off utilities. Write out: “My Plugin will add: (a) ‘My Plugin Settings’ link under Settings menu for configuration, (b) if user is admin, a submenu under Tools called ‘My Plugin Cleanup’ for maintenance tasks.” This ensures clarity before coding add_menu_page or add_options_page calls. Include parent slugs and page titles in the plan. For example: “Use add_options_page( 'My Plugin Settings', 'My Plugin', 'manage_options', 'my-plugin', ... ) for the main settings. Use add_management_page( 'My Plugin Cleanup', 'Cleanup Tool', 'manage_options', 'my-plugin-cleanup', ... ) for the tool.” Having this plan prevents confusion and helps ensure all needed pages are accounted for and accessible in a logical place . • /wp-admin:settings-ui [fields] Sketch the UI layout for [fields] on a settings page. For instance, if [fields] = “API Key (text), Enable Feature X (checkbox), Mode (select)”, describe grouping and appearance: Under a section “General Settings,” have a text input for API Key (with description “Get this from your account”), a checkbox for Enable Feature X (label “Enable advanced mode”), and a dropdown for Mode with options A, B, C. All fields will be in a that uses table.form-table layout with proper

headings for labels . The API Key field should mask the key if sensitive (maybe use type="password"). The checkbox should be checked by default if the feature is enabled by default. Provide an explanation below it using ... for clarity. The select field should default to Mode B (if that’s recommended). Ensuring to use settings_fields() for the nonce and option group. Essentially, this skill yields a wireframe or description of how the settings page will look and behave, making sure each [fields] is represented with the correct HTML control and following WP patterns (e.g. no custom React or fancy UI unless necessary; stick to what users expect in WP admin). • Add onboarding inside WP — first-run steps + safe defaults Improve user experience by guiding them when the plugin is first activated. This could be as simple as redirecting the user to a welcome page or setup wizard on activation (but note: [the Plugin Guidelines advise against intrusive pushy onboarding; if you do a redirect, do it only on first activation and make it useful] ). In that onboarding page or in dismissible admin notices, provide “next steps”: e.g. “Go to Plugin Settings to configure API key” or highlight essential setup tasks. Set safe defaults for settings so the plugin can function in a basic way without immediate user configuration. For example, if your plugin sends emails, default it to off or to a safe mode until configured. If appropriate, include sample data or presets on first run (maybe a sample post or a default configuration) to help users understand the plugin. Always allow users to skip or dismiss onboarding instructions. Use the WP pointer or admin notice for a quick tour if needed, but don’t overdo it – a short README or an entry on the plugin’s Settings page with “Getting Started” info may suffice. By thoughtfully onboarding, you reduce confusion and support requests. Ensure that any first-run actions (like creating default options or pages) are wrapped so they only run once. Testing the plugin on a fresh site can help verify the out-of-box experience – aim for the plugin to work (or at least not break anything) immediately upon activation, and gently guide the admin to optimal setup. • /wp-admin:onboarding [setup-steps] List the [setup-steps] for new users after activating the plugin. For instance, steps might be: “1) Configure API Key: Go to Settings → PluginName and enter your API key. 2) Adjust Feature X: Feature X is on by default, you can turn it off in the settings if you don’t need it. 3) Run Initial Sync: Visit the Tools → PluginName page to import your existing data.” Present these in an admin notice or welcome page. Also consider adding a “Documentation” or “Getting started” link in the plugin’s description on the Plugins page (some plugins put helpful links in the plugin row meta). The onboarding plan should ensure a user isn’t left wondering “What now?”. For each step, mention where to go and what to do, using WordPress terminology (“Settings page”, “Tools menu”, etc.). You might implement this by setting a transient on activation and then showing a notice with these steps (with dismiss button). By enumerating these steps ahead of time, development can implement onboarding messages that are concise and cover all critical first actions for the user. • Update/upgrade UX — notices for breaking changes + migrations + “what’s new” When releasing new versions, especially those with breaking changes or major new features, communicate this within WP Admin to the site admins. If a version introduces something that requires user attention (e.g. re-saving settings, migrating data, or a feature removal), use an admin notice on upgrade to explain. For example: “PluginName has updated and requires a database update. Please backup your database and click here to run the updater.” – then perhaps trigger your migration routine. WordPress auto-updates won’t automatically inform about plugin changes, so it’s on you to show a “What’s New” page or notice. Some plugins do a one-time redirect to a “About this update” page (just ensure it only happens once and is not too disruptive ). Alternatively, an admin notice: “PluginName updated to v2.0 – we’ve redesigned the interface and added X feature. [See what’s new].” Provide a link to your full changelog or documentation. Also, handle breaking changes gracefully: if you removed a setting or feature, and you detect the user had it configured, notify them of the change and any manual steps needed. Always make notices dismissible so they can be closed once read . Use consistent styling (the core notice classes). For critical things (like “Please update your shortcode usage due to changes”), maybe use notice-warning class to draw attention. In summary, treat plugin updates as an opportunity to re-engage and educate the user (short of spamming them). A well-crafted upgrade UX can make the difference between user frustration and appreciation when you roll out big changes. • /wp-admin:update-notices [release] Draft the admin notice content for [release]. For example, if [release] = “2.5 major update”, the notice might read: “PluginName has been updated to version 2.5! 🎉 This release includes a new Reports dashboard and improves performance. Important: After updating, please go to the PluginName settings and click ‘Recalculate’ to update your reports data. [View full changelog].” Indicate this notice should only appear once after upgrading (you might set a transient or option on upgrade and clear it after showing). Also decide notice type: success info, warning, etc. If [release] had breaking changes: “Notice: PluginName 3.0 made changes to shortcode names. Your site is currently using old shortcodes which will stop working in 30 days. Please replace [oldshortcode] with [newshortcode]. [Learn more].” This would be a warning that maybe persists until fixed or dismissed. Planning these notices ensures you won’t forget to inform users about critical post-update steps or highlights. Each notice should be concise, actionable, and not overly technical. • Accessibility check — labels, keyboard, admin UI a11y expectations Before releasing the admin UI, perform an accessibility review. Ensure every form field has a proper (or aria-label if a visual label isn’t present) – this is essential for screen readers. Use semantic HTML for structure (headings, lists) rather than arbitrary s. Check color contrast of any custom elements or ensure you mostly rely on WordPress core styles which are designed for sufficient contrast. Test that the interface can be navigated via keyboard only: all interactive elements (links, buttons, form controls) should be reachable with Tab, and nothing should trap focus. If you have dynamic features (tabs, modals), implement them in a way that respects ARIA practices (e.g. set aria-expanded on toggle buttons, focus management when modal opens/closes). Include visible focus states (don’t remove outlines without providing an alternative). For any images or icons (like if you have a custom logo on your settings page), provide alt text or aria-hidden if purely decorative. If you output admin notices or errors, ensure they use proper roles (WordPress notices have role="alert" for errors which is good). Use tools or browser extensions to audit for WCAG AA compliance, which WordPress aims for . By making your admin UX accessible, you not only comply with regulations but also improve usability for all users. Remember the mantra: accessible code is required in WordPress core and expected in plugins – new or updated code should meet WCAG 2.2 AA standards . Taking the time to double-check labels and interactions (perhaps using a screen reader yourself for a quick test) can reveal issues to fix. It’s much easier to build accessibility in from the start than to retrofit later. • /wp-admin:a11y-checklist [screens] Prepare an accessibility checklist for [screens] (replace with specific admin screens in your plugin). For example, for a “Settings” screen and a “Report” screen, checklist: • All form fields on Settings screen have associated elements (verify by clicking labels to see if cursor focuses input). • The Settings save button can be activated via Enter key when focused (standard	. • Ensure focus order is logical: test tabbing through Report filters, results, and links. • Color contrasts: verify text vs background for all custom UI elements meets contrast ratio ~4.5:1 for normal text. • If any Ajax actions or dynamic updates happen (like toggling a setting section), ensure an appropriate ARIA live region or focus shift so screen reader users are informed. This checklist can be used during development and QA to manually verify each item. It encapsulates the a11y expectations for your plugin’s admin screens so nothing is overlooked. Consider also asking an actual user from the WP Accessibility team or using tools like WAVE on your screens as part of this checklist. ⸻ Frontend + Editor (Shortcodes / Blocks / Widgets) • Add frontend outputs — shortcodes/widgets/template hooks Determine how your plugin’s functionality will present on the front-end (if applicable). Common methods: Shortcodes, Widgets, or template hooks. Shortcodes are small codes users can put in posts like [myplugin_gallery id=123] – if your plugin outputs content within post/page content, a shortcode is appropriate. Register it with add_shortcode() providing a callback that returns HTML  . Document the shortcode attributes and usage for users. Widgets: if the plugin output is more suited to sidebars or other widget areas (e.g. a newsletter signup form, a list of posts), create a widget by extending WP_Widget. Widgets allow configuration via Appearance → Widgets (or Customizer) and let users place plugin content in sidebars. Template hooks: for plugins deeply integrated with themes (like injecting something after post content or in the header), you might rely on theme hooks. For example, many plugins use wp_head or wp_footer actions to inject global content (scripts, meta tags), or specific hooks provided by popular themes. If you expect theme developers to integrate, you can provide template functions or recommend where to call them. Another modern approach is Template Parts or Full Site Editing blocks – but that’s advanced; alternatively, simply provide a PHP function that users can call in their theme if they want (e.g. ). Ensure any front-end output follows best practices: escaped properly, and wrapped in identifiable containers (with CSS classes or IDs prefixed to avoid conflicts). Also, front-end should respect user roles if needed (e.g. don’t show admin-only info to public). By planning these outputs, you guarantee that users have an intuitive way to integrate the plugin’s features into their site layout. Each method (shortcode, widget, template tag) has its use cases – you might even offer multiple for flexibility. Just maintain consistency: e.g. a shortcode and a widget for the same feature should produce similar HTML output so styling is consistent. • /wp-fe:rendering-plan [surface] Outline how content will be rendered on the [surface] of the site. Suppose [surface] = “Post content area (for recipe plugin)”. Plan: The plugin will use a shortcode [recipe] that outputs the recipe HTML (ingredients list, steps, etc.) inside the post. Users insert this shortcode where they want the recipe to appear. Alternatively, provide a Gutenberg block for recipes (see below). The shortcode callback will gather recipe data (from post meta or a CPT) and return a structured HTML (perhaps a containing headings and lists). Ensure the HTML is semantic (use for recipe title, for ingredients, etc.). Also, add a filter on the_content to automatically append recipe data at the end of posts of type “Recipe” if user forgets the shortcode. Essentially, this plan describes exactly how and when output is injected on the front-end. If [surface] were something like “Site footer”, you might plan: Use the wp_footer action to inject HTML (with an option to disable in settings). Having this plan makes implementation straightforward and reveals any potential issues (like needing to conditionally add assets only on pages where shortcode appears, etc.). • Create a Gutenberg block (if needed) — attributes, editor UI, render strategy If your plugin benefits from a Gutenberg (block editor) block, you should create one for a better user experience in modern WordPress. Define the block’s attributes (data it will store), its editor appearance, and how it renders on the front-end. For example, a “Testimonial” block might have attributes: author name (string), photo (image URL/id), quote text (string). In the editor, you’d provide controls to fill these in (using React components like text inputs, media uploader, etc.). You decide if it’s a static block (content saved directly in post content) or a dynamic (server-side rendered) block where render_callback in PHP generates output on view  . Dynamic blocks are useful if content needs to be up-to-date (e.g. a block that lists latest posts). Plan the block’s JSON metadata (in block.json): its name, title, category, icon, attributes, and default content or styles  . Also, consider internationalization (all text labels in JS should be translatable via provided scripts). Block CSS/JS: decide if it needs custom styles (probably yes) and ensure to enqueue those for both editor and front. Use wp_enqueue_script/style in the editor_script/editor_style and style keys of block.json . The block’s editing experience should as closely as possible preview the front-end result (Gutenberg encourages “what you see is what you get”). Thus, if your block output has styling, include that in the editor_style so authors see it. Document any block-specific instructions (like if the block requires an API key to function, handle that gracefully by showing a placeholder prompt in editor). By creating a block, you integrate with the block editor’s user flow – which is a big plus for user experience. Just ensure you also gracefully degrade (if someone not using block editor, maybe provide a shortcode fallback or legacy widget). • /wp-block:block-spec [block] Define the specification for a new block [block]. For instance, if [block] = “FAQ Accordion Block”: • Name/Slug: myplugin/faq-accordion (appears as core/mine in code). • Title: “FAQ Accordion” (shown in block inserter). • Category: e.g. “Widgets” or “Design” (where it appears in inserter). • Icon: choose a dashicon or SVG (perhaps “editor-help” for FAQ). • Attributes: e.g. faqItems (array of objects with question & answer), each having { "question": {"type": "string"}, "answer": {"type": "string"} }. • Editor UI: In editor, it could use InnerBlocks (each question-answer pair as a nested block) or a custom sidebar control to add Q&A. Possibly simpler: a repeater field UI in block. Outline: user can click “Add FAQ” and gets two textareas for Q and A. • Front-end Render: each Q&A will output as an accordion (e.g. Q… A… ), and include a script to toggle answers. Could use a small inline JS or depend on an existing library. • Styling: default styles to hide answers initially and reveal on click (for front-end). In editor, likely always show answers expanded for ease of editing. • Dynamic or static: Possibly static – save the HTML so it works even if plugin deactivated (though then accordion behavior might break without JS). Or dynamic – output only container in post content and use render_callback to generate Q&A markup (ensuring up-to-date JS is loaded). • Translation: Ensure question and answer labels in editor are translatable. This spec covers everything from user interface to output for the block. It serves as blueprint so developers writing the block code know what to build and how it should function. • /wp-block:attributes-schema [block] Provide the JSON-like schema of attributes for the [block]. Suppose [block] = “Testimonials Slider”: attributes could be: attributes: { testimonials: { type: 'array', default: [], source: 'query', selector: '.testimonial', query: { name: { source: 'text', selector: '.testimonial-name' }, quote: { source: 'text', selector: '.testimonial-quote' }, imageUrl: { source: 'attribute', selector: '.testimonial-img img', attribute: 'src' } } }, autoplay: { type: 'boolean', default: false } } Explain each: testimonials is an array of testimonial items, each with name (text), quote (text), imageUrl (from an image tag’s src). autoplay is a boolean for whether the slider auto-advances. This schema tells Gutenberg how to serialize the block content to HTML and back. For dynamic blocks, the attributes might be simpler because rendering is done server-side (you might then rely on save() returning null and using PHP). But it’s still useful to outline for consistency. This plan ensures all needed data points are captured and have proper default types. By explicitly writing the attributes schema, you avoid runtime mistakes and can communicate to others (or in docs) what each attribute does. • Handle assets correctly — enqueue, deps, versions, conditional loading Front-end assets (JS, CSS, images) should be added using WordPress enqueue functions so they integrate with core and other plugins. Use wp_enqueue_script() and wp_enqueue_style() in appropriate hooks (e.g. wp_enqueue_scripts for front-end) . Set dependencies for your scripts/styles explicitly: e.g. if your script needs jQuery, include array('jquery') in the deps argument . Provide a version number (usually use your plugin version or a file hash) so browsers can bust cache on updates . Conditional loading: don’t load all assets on every page if not needed. If your plugin has a front-end widget that only appears via shortcode or on certain pages, you can check is_page() or better, only enqueue when the shortcode is present. One strategy: use wp_enqueue_scripts normally for assets needed globally (rare), but for content-specific assets, enqueue them within the shortcode callback or block rendering function (so it only adds if the shortcode/block is used). For admin, use admin_enqueue_scripts and check $hook to only load on your plugin’s admin pages  . Always namespace your handles (like 'myplugin-style') to avoid conflicts. If using inline scripts or style tags, minimize them – better to output needed data via wp_localize_script() for dynamic data to your JS . Also consider performance: aggregate or minify assets (you might have a build step that produces minified files for release). But if using WP’s built-in dependencies (like using core-bundled jQuery UI), leverage those instead of adding new files . Lastly, if your plugin outputs HTML that might be affected by theme CSS, ensure your CSS loads after theme (set proper dependency or in footer) and be specific enough to override only where needed. By handling assets thoughtfully, you reduce bloat and prevent breakage: users will appreciate that your plugin isn’t injecting tons of CSS/JS on pages where it’s not used. • /wp-assets:enqueue-plan [scripts] [styles] Plan out the enqueueing for [scripts] and [styles] in your plugin. For example, if [scripts] = “frontend slider JS, admin settings JS” and [styles] = “frontend slider CSS, admin CSS”, the plan could be: • Frontend CSS: myplugin-slider.css – enqueue on pages where shortcode [slider] is present. Implementation: in the shortcode handler, call wp_enqueue_style('myplugin-slider', plugins_url('css/myplugin-slider.css', FILE), array(), '1.0.0'). Alternatively, if using a block, enqueue via block’s style in block.json so it loads automatically when block is used. • Frontend JS: myplugin-slider.js (depends on jQuery) – enqueue alongside the CSS in the same conditions. Use 'jquery' as a dependency , ensure it’s in footer ($in_footer=true). Possibly use wp_localize_script to pass in user options (like autoplay speed). • Admin CSS: myplugin-admin.css – enqueue on our plugin settings pages only. Implementation: use add_action('admin_enqueue_scripts', function($hook){ if($hook == 'settings_page_myplugin'){ wp_enqueue_style('myplugin-admin', ...); } }). • Admin JS: myplugin-admin.js – similarly, only on relevant admin pages, depend on wp-util if using WP JS utilities, etc. Version all as plugin version. • Images: If the slider uses arrow images or such, ensure these are referenced correctly (perhaps via CSS or with plugins_url() so paths are correct). • Other: No assets loaded on front-end when plugin features not used (good). Use core dashicons if possible instead of custom icons to avoid extra files. Summarizing this in text ensures each asset has a purpose, a loading condition, and we’re not forgetting to deregister on uninstall or similar (though usually leaving registration is fine; main thing is conditional enqueue). This plan guides the actual coding in functions.php or main plugin file for asset management and helps avoid common pitfalls like loading stuff everywhere or missing an asset when needed. ⸻ Integrations (REST / AJAX / External services) • Add REST API endpoints (if needed) — routes, permission callbacks, validation If your plugin exposes data or operations that could benefit external clients (JavaScript apps, mobile apps, or other sites), consider adding custom REST API endpoints. Use register_rest_route() on the rest_api_init hook to create endpoints  . Define a namespace (e.g. 'myplugin/v1') and resource path (e.g. ‘/items’) . Provide an array of options including supported HTTP methods and callback function, and crucially a permission_callback to secure the endpoint . The permission callback should check user capabilities or auth status (for public data, it can return true; for protected actions, verify nonce or user cap). Implement input validation: you can define endpoint arguments with args in register_rest_route and include validate_callback or sanitize_callback for each, or manually inspect $GET/$POST in your callback (but using the REST infrastructure is cleaner). For example, if an endpoint expects an integer ID, ensure it’s numeric; if expecting certain values, validate accordingly. Use WP’s REST response objects (WP_REST_Response) for structured responses and proper status codes. If your plugin’s endpoints modify data, protect against CSRF by requiring an authenticated nonce or OAuth token (note: the permission_callback typically handles this by checking is_user_logged_in() or specific caps). Document these endpoints for developers. Also, consider performance and security implications: don’t expose sensitive data without auth, and don’t allow dangerous actions without capability checks. By leveraging the REST API, your plugin’s data can be accessed in a standard JSON format and you avoid reinventing an AJAX/JSON system from scratch. Test your endpoints via /wp-json/your-namespace/route once implemented to verify outputs and permission denials are as expected (you should get 401/403 for unauthorized calls)  . • /wp-rest:endpoint-spec [routes] Outline the specification for REST routes [routes] your plugin will add. For example, if [routes] includes “GET /contacts” and “POST /contacts”, spec could be: • GET /myplugin/v1/contacts: Retrieves a list of contacts. Auth: requires current user to have list_contacts capability (permission_callback checks this). Args: support per_page (int, default 10, validate as positive int) and page (int, default 1). Response: JSON with an array of contacts (id, name, email) and pagination headers (X-WP-Total). • POST /myplugin/v1/contacts: Creates a new contact entry. Auth: user must have edit_contacts. Args: expects name (string, required), email (string, required, validate as email). Process: on success, returns 201 Created with the new contact data; on error (validation fail), returns WP_Error with 400 status. • (If needed, detail DELETE or others similarly.) Include what underlying functions these call (e.g. MyPlugin_Contacts::create()), and note any special cases (maybe “if email exists, return error 409”). This spec ensures implementation of the REST endpoints is consistent and covers security (caps) and data integrity (validation). It will also serve as documentation for API consumers. • Implement AJAX actions (if needed) — admin-ajax, nonces, caps For classic themes or quick admin requests not suitable for REST, you can use admin-ajax.php. Define your action endpoints by hooking into wp_ajax{action} (for logged-in) and/or wp_ajax_nopriv{action} (for guests) . For each AJAX action, do a capability check at the top of your handler function (e.g. current_user_can('manage_options') if appropriate) and a check_ajax_referer( 'myplugin_nonce' ) to validate the nonce . Nonces for AJAX are usually passed via wp_localize_script() as discussed, or by adding a hidden field in a form. Ensure your JavaScript calls the AJAX URL admin_url('admin-ajax.php') with the correct action parameter and nonce. Structure your handler to output a JSON response (you can use wp_send_json_success() and wp_send_json_error() which also call wp_die() for you) . For example, if the AJAX action is “myplugin_do_task”, in JS you do: jQuery.post(ajaxurl, { action: 'myplugin_do_task', security: myplugin.securityNonce, data: value }). In PHP: add_action('wp_ajax_myplugin_do_task', 'myplugin_do_task_callback'); function myplugin_do_task_callback(){ check_ajax_referer('myplugin_nonce'); if( ! current_user_can('edit_posts') ){ wp_send_json_error('Not allowed', 403); } // Process the task... if($success){ wp_send_json_success(array('message'=>'Task done')); } else{ wp_send_json_error('Error occurred'); } } Always wp_die() or use the wp_send_json functions to terminate, otherwise WordPress will output a 0. Using the proper hooks and nonce check protects against unauthorized use of admin-ajax (which could be a vector for CSRF if not protected). Also, remember admin-ajax runs with full WP loaded, so for heavy tasks consider optimizing or offloading to background processing. Keep your AJAX output lean (no extra HTML unless needed). This approach will allow your plugin’s JS to communicate securely with WordPress for dynamic features (like form submissions, background processing triggered by users, etc.) without reloading the page. • /wp-ajax:action-spec [actions] Describe the AJAX actions [actions] your plugin will support. For example, if [actions] = “save_settings, fetch_report”: • Action: myplugin_save_settings (triggered from settings page via AJAX when “Save via AJAX” button is clicked). Auth: only users with manage_options. Nonce: myplugin_admin_nonce. Request Data: an array of settings fields (validated in PHP similar to normal form save). Response: JSON success with a message or the updated settings. • Action: myplugin_fetch_report (maybe triggered to load a report via AJAX on the front-end). Auth: if this is front-end for logged-in users, perhaps requires nonce but no cap if all visitors can do it – still use nonce to prevent automated abuse. Request: maybe a report ID or date range. Response: JSON containing the report data (or HTML fragment to insert). Use wp_send_json_success({data}). For each action, note if wp_ajax_nopriv_ is needed (i.e. if non-logged-in should access – e.g. a public form submission). Also note any rate limiting or special security considerations (like maybe these actions call external APIs, so treat carefully). With this spec, the implementer knows to create e.g. two functions myplugin_save_settings_callback and myplugin_fetch_report_callback, include appropriate add_action hooks for each, and how to structure the JavaScript to call them. It also ensures no AJAX entry point is left unsecured or undocumented. • Commercial licensing (if premium) — keys, update server, graceful expiry UX If your plugin uses a licensing system for premium features, design it in a user-friendly and secure way. License Keys: Provide a settings field for users to enter their license/API key. Validate the key format (e.g. certain length/characters) client-side lightly and definitely server-side (perhaps by an API call to your license server). Activation: When a key is entered, possibly perform an activation call (to your server) to register the site, and store an activation status locally (option meta). Use https for any such calls. Update Server: Premium plugins can still use WordPress auto-update mechanism by hooking into pre_set_site_transient_update_plugins to add your plugin’s update data if license is valid. Or simpler, use an established solution (like EDD Software Licensing or Freemius) which provides an update endpoint. Plan how often the plugin checks for updates (maybe leveraging the cron to avoid hitting your server too often). Graceful expiry: If a license expires or is invalid, do not break the site. The plugin should ideally continue functioning in core areas but might disable updates or certain premium features. For example, some plugins just stop delivering updates/support while allowing existing features to continue – decide your approach. In the UI, show the license status: e.g. “License active (expires 2024-01-01)” or “License invalid or expired – please renew to continue receiving updates.” Provide links to renewal or troubleshooting if the key fails. Ensure that even without a valid license, the free aspects still work (don’t white-screen or anything). Also consider an offline mode: if your license server is down, the plugin should fail open (assume license okay for some time) to not penalize users for connectivity issues. Security: protect any license-related endpoints with nonces and capability checks (likely only admins manage licenses). Data privacy: be transparent that the plugin contacts an external server for license verification – possibly mention this in readme or settings (“This plugin will connect to example.com to validate your license”). Overall, aim for the licensing to be as unobtrusive as possible for legit users while still protecting your business. • /wp-pro:licensing-flow [model] Outline the licensing flow for your plugin’s [model]. For example, if [model] = “Freemium with Pro upgrades”: • Free Version (.org): no license needed. Contains code to recognize when Pro is installed/activated (perhaps a separate plugin or add-on) and hides redundant settings. Maybe provides a “Go Pro” call to action in the settings with link to purchase. • Pro Version: distributed outside .org, requires license activation. Flow: After installing Pro, user sees a notice “Please activate your license to enable updates.” The settings page shows a License section with an input. User enters key and clicks “Activate”. Plugin sends https://yoursite.com/license-api/activate with key and site URL. If response OK (active), store license status (option: license_key and license_status=valid along with expiry or plan info). Schedule a cron to periodically verify or ping for updates. If activation fails (key invalid or max installs), show error message. • Update Checks: The Pro plugin hooks into update checks; when WP checks for plugin updates, plugin adds its info if license_status is valid (or even if expired, could still notify but not allow download). Update package URLs are protected (maybe require key as param or a token). • Expiration: If license expires, plugin should inform the user in WP Admin (non-intrusive banner “Your PluginName license expired on 2023-12-31. Renew for continued support and updates.”). Possibly continue functioning but disable update retrieval. The features ideally keep working – unless your model is subscription-based functionality (then you might disable the feature but again, do so gracefully and communicate it). • Deactivation: Provide a way to deactivate license on a site (in case the user is moving it). Simply a button “Deactivate License” that calls your API to free the activation slot. This flow covers end-to-end user experience for licensing. It ensures your implementation to be consistent and user-friendly, handling edge cases like server down or license misuse. Having it written helps when coding the license manager module and also for support docs. ⸻ Security / Privacy / Compliance for WordPress • Enable debugging (dev only) — safe debug setup without leaking in prod As a developer, you’ll use WP_DEBUG and other debug tools during development – but ensure none of that debug info shows on live sites. Encourage developers or site admins to turn on WP_DEBUG in staging or set define('WP_DEBUG_LOG', true) to collect logs  . In your plugin, you can add if ( defined('WP_DEBUG') && WP_DEBUG ) { … } around debug-specific code (like verbose logging or developer UI panels) so it doesn’t execute in production where WP_DEBUG is false . Provide a config or constant to enable plugin-specific debug mode (for example, define(‘MYPLUGIN_DEBUG’, true) to log extra info) – but default it off. Ensure any debug messages you log do not expose private data or sensitive info (if you log user input or API responses, strip or anonymize personal details). If using error_log, prefix messages with your plugin name to identify them. If you have a custom debug page in the plugin, hide it behind an administrator check or only load it when WP_DEBUG is true, to avoid performance overhead and information disclosure. On production, any caught exceptions or errors should fail gracefully – perhaps show a generic error message to users and log the details to debug.log for the admin. Never output raw PHP errors to users in production. Use @ini_set('display_errors',0) as WP does by default when WP_DEBUG is false . Essentially, test your plugin with debugging off to see that it behaves cleanly (no stray var_dump or warnings). And test with debug on to ensure it provides useful info for you without crashing. Having a safe debug setup means you and advanced users can troubleshoot issues without compromising the site’s stability or security. • /wp-sec:debug-safety [env] Describe how to maintain debug safety in [env] (likely “production environment”). For instance: In production, set WP_DEBUG to false and WP_DEBUG_DISPLAY to false so that PHP warnings/notices are not shown to end-users . Our plugin honors these settings and will not output any debug information unless WP_DEBUG is true. For extra safety, our plugin checks wp_get_environment_type(): if it returns ‘production’, we explicitly disable certain debug behaviors (like an on-screen SQL log or developer menu). We ensure any temporary debug code (like writing to a file) is conditioned on a constant that defaults off. We also avoid using var_dump/print_r directly; instead, use error_log which goes to a secure log when enabled. In summary, on a live production site, the plugin will run in quiet mode – any internal errors will be logged to debug.log (if enabled) or suppressed, and users will not see raw error messages. This statement can be part of developer documentation or comments, and it guides maintaining a strict separation between dev verbosity and production silence, which is a professional approach to WP development. • Security hardening — nonces, escaping, sanitization, prepared queries, uploads Develop your plugin with a security-first mindset in line with WordPress standards: Nonces to protect forms and actions (prevents CSRF). Whenever you create a form or link that performs an update or sensitive action, use wp_create_nonce() and verify it on processing (check_admin_referer() or check_ajax_referer() for AJAX) . This ensures the request is intentional and from a valid user session. Escaping output: any data coming from the database or user input that is output in HTML needs escaping to prevent XSS. Use functions like esc_html(), esc_attr(), esc_url() at the point of output (remember “escape late” principle)  . For example, when echoing a setting value in an input field, do echo esc_attr( $value ). Sanitization & Validation of input: before saving any user-provided data (from a form, API, etc.), clean it. Use sanitize_text_field() for plain text , sanitize_email() for emails, sanitize_file_name() for filenames, etc. . If expecting a number, cast to int; if expecting a specific format, use regex or WP provided validation. Also enforce capabilities – e.g. even if a nonce is valid, double-check current_user_can() for critical operations (a non-admin could potentially trick an admin into triggering something, but capability checks add a layer of safety). Database queries: use $wpdb->prepare() for any direct SQL with user input to avoid SQL injection. Eg: $wpdb->get_results( $wpdb->prepare("SELECT * FROM {$wpdb->prefix}mytable WHERE status=%s", $status) );. Or use the ORM-like WP functions (like WP_Query with args) which handle preparation internally. File uploads: if your plugin handles file uploads, use wp_handle_upload() to let WordPress manage it and check file types. Limit allowed file types to only what’s necessary (perhaps use wp_check_filetype() to validate extension/MIME). Save uploads in wp-content/uploads/... not an untrusted custom folder unless needed, and consider scanning or at least not executing uploaded files (e.g. if you allow SVGs, sanitize them; if you allow images, no extra actions needed since they’re not executed). Also, apply principle of least privilege: if your plugin uses external APIs, secure the API keys (don’t expose in front-end), and make remote requests safe (use wp_safe_remote_get() which checks SSL). If caching data, be mindful if any sensitive info is cached in public locations. Essentially, every time data crosses boundaries (user input to server, server data to output), apply the appropriate measure: validate or sanitize on input , escape on output . By following these practices, your plugin will align with WordPress’s robust security approach and protect both site owners and their visitors from common vulnerabilities. • /wp-sec:hardening-checklist [feature] Create a hardening checklist for [feature] of the plugin. For example, if [feature] is “CSV import/export”: • Nonce: Confirm that the import form submission has a hidden nonce field, and the processing code calls check_admin_referer('myplugin_import_nonce'). • Capability: Ensure only users with appropriate capability (maybe manage_options) can access the import/export page and perform the action. • File Handling: When importing CSV, use WordPress functions to handle the upload (wp_handle_upload). Only allow .csv extension, and perhaps check MIME text/csv. If parsing CSV, guard against extremely large files (maybe set a file size limit) to prevent denial of service. • Sanitize Data: Each field read from CSV should be sanitized before insertion. E.g., if CSV has username and email, run sanitize_user() and sanitize_email() respectively on each. Don’t eval or directly execute any content from CSV. • Escaping: For export, when generating CSV output, ensure that any data included (which might contain commas, quotes, newlines) is properly escaped or enclosed in quotes per CSV format to prevent breaking the structure. • Database: Use prepared statements or WP functions when inserting imported data into database. E.g., use $wpdb->insert() which prepares internally, or sanitize then use in a prepare(). • Feedback: After import, do not display raw imported data in an HTML success message (to avoid XSS if CSV contained malicious content). Instead, just say “X records imported successfully.” Log details to a debug log if needed. • Privacy: If the CSV contains personal data, treat it carefully. Don’t store the file permanently unless necessary (and if so, perhaps delete it after import or on plugin uninstall). This checklist can be applied during development and testing of the CSV import/export to ensure all security angles are covered. It’s basically a specific application of general security practices to a particular feature. Doing this for each major feature (like user input forms, data display, external API integration) would ensure comprehensive coverage. • Privacy/GDPR alignment — stored data, consent, export/erase support if needed In the era of privacy laws (GDPR, etc.), design your plugin to handle personal data responsibly. First, identify what personal data (if any) your plugin stores: e.g. user emails, names, IP addresses, etc. If your plugin collects new personal data (say, via a form), consider adding a privacy notice or requiring user consent for that collection. For example, if you have a newsletter signup checkbox, ensure there’s a statement like “Your email will be stored for newsletter purposes” and only store it if they opt-in (don’t pre-check without consent). Use WordPress’s built-in Personal Data Export/Eraser hooks if applicable  . That means: if your plugin stores personal info outside of the normal WordPress user or comment tables, integrate with the Privacy tools. For instance, use wp_privacy_register_exporter() to allow site admins to include your plugin’s data in a user’s export upon request, and wp_privacy_register_eraser() to erase personal data your plugin holds  . An example: a plugin that stores form submissions (with name, email) should, when asked to export data for a given email, retrieve any entries with that email and return them in a structured format for export. And for erasure, perhaps delete or anonymize those entries (maybe replace name with “Deleted” and email with “[redacted]”). If certain data needs to be retained for legitimate reasons, document that. Also, data minimization: don’t collect more info than needed for functionality. If your plugin sends data to an external service (like an analytics or a remote API), disclose this in your plugin readme or admin screen (“Note: This plugin connects to Example API to fetch stock photos, transmitting query terms and your site’s API key”). Obtain consent if required (some plugins have a setting “Allow usage tracking” which is opt-in). For cookies: if your plugin sets any cookies (e.g. for tracking or functionality), list them and ensure they are covered by the site’s cookie consent if needed. Provide guidance in your readme’s Privacy section (the Plugin Directory allows a Privacy section) about what your plugin does with data. By aligning with GDPR and similar, you not only avoid legal issues but also make it easier for site owners to use your plugin without compromising their compliance. WordPress core’s privacy API and guidelines are there to help – make use of them so that things like “Personal Data Export” just work with your plugin’s data as well  . • /wp-sec:privacy-map [data-types] Make a privacy data map for the [data-types] your plugin handles. For example, if [data-types] = “Customer inquiries (name, email, message), IP addresses (logged for security)”: • Customer Inquiries: Collected via a contact form. Fields: name (personal), email (personal), message (could contain personal info). Stored in custom DB table wp_inquiries. Retention: kept indefinitely unless deleted by admin. Use: only for site owner to respond to inquiries. Consent: user must tick “I consent to having this site collect my info via this form” (and that consent is recorded, perhaps as a boolean in the DB or simply implied by submission). Export/Erase: The plugin registers an exporter so that if a user requests their data, any inquiries with their email are included (with fields Name, Email, Message, Date). For erasure requests, the plugin either deletes those inquiries or anonymizes the personal fields (e.g. “[Removed at user request]” in name/message, blank out email). • IP addresses: Captured in a log table for security (e.g. failed login attempts if plugin had that feature). Considered personal data under GDPR. The plugin should mention that it logs IPs for security purposes. Possibly provide a setting to anonymize IPs (e.g. only store partial IP). Consent: not explicitly asked because it’s under legitimate interest (security), but documented in privacy policy that IPs are logged. Export/Erase: If a user requests export of their data identified by email or user ID, IP logs might not be easily tied to a specific user unless you also log user ID. If they are, include them. For erasure, you could delete or anonymize IP entries older than X days regularly (data minimization) or specifically remove those related to the user. The privacy map clearly lays out each data type, why it’s collected, how long it’s kept, and how the plugin facilitates compliance. This is useful for admins writing their privacy policies and for your own development to implement necessary features. You could also use this to create a Privacy Policy suggestion (many plugins output an example text for site owners to include in their policy – WordPress has a mechanism to add “Privacy Policy content” via add_privacy_policy_content() with a boilerplate for your plugin ). Ensuring each data-type is accounted for will keep your plugin on the right side of privacy best practices and user trust. ⸻ QA / Compatibility (WordPress reality checks) • Set up dev environment — local WP, clean site, sample content Establish a reliable development and testing environment to build and verify your plugin. Typically, set up a local WordPress installation (using tools like Local, XAMPP/LAMP, Docker WP environment, etc.) with the same version of WordPress you target. Use a clean site with no other plugins initially to test your plugin in isolation. Create sample content relevant to your plugin – e.g. if your plugin deals with custom post types or shortcodes, add some posts/pages using those to simulate real usage. This might include dummy users, terms, comments, or whatever data your plugin touches. Having a known dataset makes it easier to predict outcomes and spot regressions. Also, maintain a baseline site (perhaps exporting the DB so you can reset as needed) so you can always test fresh installation scenarios. For front-end features, include a variety of theme data (maybe the TwentyTwenty theme for simplicity and a custom one if needed). This environment should also have debugging tools like Query Monitor or error logs enabled so you can catch warnings. Additionally, consider setting up multiple environments: one matching minimum supported versions (e.g. WP 5.x, PHP 7.4) and one on latest (WP 6.x, PHP 8.x) to catch compatibility issues early. Document instructions for setting up the dev environment (for team members or contributors) – e.g. “Clone repo, run npm install for build tools, then use WP-CLI to scaffold a test site.” By front-loading environment setup, you reduce the friction in testing every aspect of your plugin under controlled conditions. Regularly update this environment (update WP, etc.) to catch changes that might affect your plugin. • /wp-qa:local-setup-checklist [stack] Provide a checklist for setting up a local test environment [stack]. If [stack] = “LAMP on Windows” for example: • Install a web server (Apache) + PHP (ensure version matches target, e.g. PHP 8.0) + MySQL (or MariaDB). XAMPP could be used for simplicity. • Download WordPress latest (or specific version) and set it up at http://localhost/wordpress. • Create a database and user for WordPress, update wp-config accordingly. • In wp-config.php, enable WP_DEBUG and WP_DEBUG_LOG  so we capture errors in wp-content/debug.log. • Install a basic theme like TwentyTwentyOne. • [Optional] If using tools like Node for build, install Node.js LTS. • Check out the plugin code into wp-content/plugins/yourplugin. • Activate the plugin through wp-admin. Verify no errors upon activation. • Seed some content: create a few posts, pages, maybe import a WP theme unit test data set for general content. If plugin uses specific data (like CPT), create those entries. • Test sending emails (if plugin does) – might need MailHog or similar if local server can’t send emails. • Verify pretty permalinks are enabled (if plugin uses custom rewrite rules). • Document how to run plugin’s unit tests (e.g. “run phpunit in plugin folder” if configured). This checklist ensures anyone can quickly spin up a dev/test environment that mirrors what you need. For different stacks (VVV, Docker, etc.), you could have a variant, but the core is to have a reproducible environment. • Compatibility testing — WP/PHP matrix + popular themes/plugins + hosts Once the plugin works in a clean environment, test it across a matrix of WordPress and PHP versions that you intend to support. For example, if you support WP 5.8+, test on 5.8, latest 6.x; and for PHP, test on your min (say 7.4) and a newer one (8.1/8.2) to catch deprecation issues. Tools like WP CLI or Docker can let you swap versions easily. Next, test alongside popular plugins especially those in similar domain or big ones like WooCommerce, Yoast SEO, etc., to ensure no conflicts or ensure integration if needed. For instance, if your plugin adds content to posts, check it with a page builder plugin active, or if it’s an e-commerce addon, obviously test with WooCommerce enabled. Also, test with a variety of themes: at least a default theme (which usually is plain and works), and a few popular ones (some themes heavily modify admin or front-end which could affect your plugin). If your plugin outputs UI, see if it blends in or any CSS conflicts arise in those themes. Check in multiple browsers for front-end output (Chrome, Firefox, Safari) especially if you use JS/CSS heavily. Additionally, try different hosting environments: if possible, test on a Linux vs Windows environment (path issues), different MySQL versions (or MariaDB), maybe an environment with older cURL or strict security (some hosts disable certain PHP functions). If not physically testing on hosts, at least keep those considerations – e.g., ensure file operations use WP Filesystem API for compatibility with different FS setups. Another angle: test with localization – switch WP site to another language to ensure your text domains and translations work (even if you only have the .pot with no translations, testing switching ensures no strings left unwrapped in __()). By performing a thorough compatibility test matrix, you can confidently declare “tested up to X” and that your plugin “plays well with others.” It also reduces support burden down the line. Document any known incompatibilities (if something doesn’t work with a certain plugin or environment and it’s not feasible to fix, at least note it). • /wp-qa:compat-matrix [targets] Define the compatibility matrix for [targets]. If [targets] = “WordPress 5.9–6.3, PHP 7.3–8.2, WooCommerce, Yoast”, outline testing: • WordPress: Test plugin on 5.9 (oldest supported) and 6.3 (latest). Ensure all features function, and no deprecated notices in debug log. • PHP: Test on PHP 7.3 (lowest supported – though note WP’s current min is 7.4, but if you claim 7.3, test it) and PHP 8.2 (highest, with error_reporting on to catch deprecations). Look at debug log for “deprecated” or “warning” messages (e.g. certain functions might be deprecated in PHP 8). Fix or suppress appropriately. • WooCommerce: Install latest WooCommerce and activate. If plugin integrates, test integration (e.g. if your plugin adds a tab in product page, see if it appears). Even if unrelated, just browse around with both active to ensure no obvious JS errors or performance issues. Check the Woo pages to see that your plugin’s assets aren’t accidentally loading everywhere (unless needed). • Yoast SEO: Similarly, have it active and ensure, for example, if your plugin adds meta boxes or custom post types, Yoast doesn’t break or vice versa. If your plugin adds content to posts, see if Yoast’s analysis picks it up or not (could be fine if not, but just note it). • Other: list any specific known heavyweights or page builders (Elementor, etc.) if relevant. Present this as a table perhaps in documentation or internally. Mark each combination as “Pass” or any issues found. This becomes both a plan and a record of what was verified. If issues found, address them or list them. This matrix will reassure users (and the plugin team) that you’ve considered compatibility thoroughly. • Performance review — queries, hooks, caching/transients, avoid global slowdowns Analyze your plugin for any potential performance bottlenecks. Review all custom database queries – are they using proper indexes or could they be heavy on large sites? Use the Query Monitor plugin to see query count and time on pages where your plugin is active. If you find a query running too often or without caching, consider using the Transients API or WP Object Cache. For example, if your plugin computes a costly statistic on every page load, cache that result in a transient for some minutes . Only query what you need: use SELECT specific_columns instead of SELECT * when possible. Check loops: if you have nested loops or complex computations, see if they scale with number of posts/users, etc., and test on a site with a lot of data (maybe generate dummy posts using WP-CLI to simulate scale). Make sure you’re not hooking into extremely high-frequency hooks (like every the_content) with heavy code unless necessary. If you do hook into something like init or wp_head, ensure the code is optimized (no unnecessary queries or disk writes on each page). Offload lengthy tasks to background (via cron or asynchronous processing) instead of doing during page request. Profile memory if your plugin handles large data (maybe using the WP debug tools). Another important point: avoid loading too much on every admin page – only load your heavy scripts or data when on your plugin’s specific admin screens (using admin_enqueue_scripts with conditional, as mentioned)  . Use pagination for listing data in admin to not overwhelm. If your plugin adds columns to admin tables, ensure using manage_posts_custom_column efficiently (no heavy query per row; maybe bulk preload data). Also consider front-end impact: if your plugin adds CSS/JS, minify it and combine if appropriate, and load only when needed. Check that you’re not doing things like starting a PHP session or something site-wide that could slow down or conflict with page caching. In summary, make your plugin as lazy as possible – do work only when needed and as little as needed – and utilize WordPress caching APIs for repeated tasks  . Document any server requirements if your plugin is resource-intensive (like “requires at least 128MB PHP memory”). After making improvements, re-test with Query Monitor or similar to ensure lower impact. This performance vigilance will result in a smoother experience on both small and large sites, and often also correlates with better code quality. • /wp-qa:perf-review [pages] Conduct a performance review for [pages] affected by your plugin. For example, if [pages] = “Front-end post load, Admin listing page”: • Front-end Post Page (where plugin maybe injects content): Load a sample post and measure queries and load time with plugin active vs. inactive. Check the number of queries added. Suppose you see it added 5 queries – examine them: if they are duplicate or can be combined, optimize. Use the transient cache if those queries don’t need to run every time (e.g. caching counts). Ensure no slow query (use EXPLAIN in SQL if needed to see if proper indices are used). • Time the page generation using Query Monitor’s timeline – see if any particular hook or function of plugin is slow. If yes, profile that function (maybe using xdebug or manual microtime logging). • Admin Listing (maybe a CPT list or settings page): If the plugin adds an admin menu listing posts or entries, make sure it paginates (e.g., shows 20 at a time). Measure the memory usage on that page – if loading 1000 entries at once, that’s a problem; adjust to using WP_List_Table with pagination. Check for any expensive operations when bulk actions are performed. • Check asset sizes: front-end maybe +50KB CSS/JS from plugin – acceptable, but if it’s much larger, consider trimming or letting users dequeue parts if not used. • Simulate multiple concurrent users (just a mental check or actual load test if possible) – ensure no obvious bottleneck like writing to a file on each page (which could lock). After review, note down any changes: e.g. “Optimized query X by adding index on column Y in custom table” or “Added caching to function Z which reduced page load by 30ms.” The output of this review is both improvements done and any tips to users (“enabling object cache will benefit this plugin significantly” – you could mention if true). If you find that on large sites (like 10k posts) something is slow, consider it a bug to fix now, not later. This systematic review will ensure your plugin doesn’t cause a site to slow down and will uphold WordPress’s standard of performance. • Automated tests (as possible) — WP test suite + smoke tests for key flows It’s highly beneficial to include at least some automated tests for your plugin, even if just basic ones, to catch regressions. Set up the WordPress PHPUnit test suite for plugins (WP-CLI can scaffold it as mentioned, giving you a bootstrap that loads WordPress testing environment) . Write tests for critical functions: e.g. if you have a function that calculates a value or sanitizes input, write unit tests for various inputs and expected outputs. Use the WP test framework to create dummy posts/users etc. (for instance, use wpInsertPost in tests to simulate content and then run your plugin’s code). Also test integration points: e.g. if you register a shortcode, write a test that do_shortcode(’[yourshortcode]’) returns expected HTML. Smoke tests: These are basic end-to-end tests verifying that major features don’t break. For example, you might simulate an admin saving settings and then verify the option is stored. Or simulate a front-end form submission (perhaps by calling the PHP function that handles it) and checking the result. WordPress testing library allows calling AJAX handlers too (though a bit advanced). If GUI tests are desired, consider using Cypress or Playwright for a few scenarios (like load WP admin, click plugin menu, fill form, submit, verify result) – though that’s more involved. At minimum, aim to run PHPUnit tests on multiple PHP versions (this can be done via GitHub Actions for open source easily, running tests on 7.4, 8.0, 8.1 etc.). Having automated tests will greatly help when making future changes – you’ll know quickly if something fundamental broke. Additionally, run the WordPress Code Standards checks (PHP_CodeSniffer with WP rules) as part of CI, so your code stays consistent and catches things like unsanitized output. Even if you can’t test UI manually in CI, a set of functional tests that call your core classes and functions is very useful. Focus on the key flows: installation (maybe test that activation sets default options), data CRUD (create/read/update of plugin’s data), and any calculations. Over time, expand the test coverage. This practice not only increases reliability but also communicates to users/devs that the plugin is professionally maintained. • /wp-qa:test-plan [critical-flows] Develop a test plan for [critical-flows] in your plugin. If [critical-flows] = “User registration form submission, Data export feature”: • User Registration Form (assuming your plugin adds extra fields to WP registration): Test Cases: 1. Submit form with valid data -> expect user created, extra fields saved (verify in database that meta is correct). 2. Submit form with missing required field -> expect form returns error message and no user created. 3. Submit form with invalid email -> expect validation error “invalid email”. 4. Security: try submitting with a bad nonce or as an unauthenticated context (if supposed to be authenticated) -> expect rejection (maybe 403 or redirect to login). Automate: Possibly use PHPUnit to simulate form processing function by calling it with sample $_POST data (WordPress testing allows setting globals) and checking outcomes. Or use a tool like Behat (there’s a WP Behat extension) to simulate a browser form submission. • Data Export Feature: (maybe your plugin’s custom data export via Tools) Test Cases: 1. As admin, request export for a user that has plugin data -> expect generated file contains that data properly formatted (e.g. CSV columns match). 2. For user with no data -> expect export file maybe just headers or a message “no data” but operation completes gracefully. 3. Unauthorized user (say a subscriber tries to access export page) -> expect access denied. 4. Malicious input: (if export takes query parameters, try injection to ensure it’s handled, but likely not applicable if it’s just a button). Automate: Could call the function that generates export and verify output contents. If writing to filesystem, check the file. Clean up after test (remove file). This test plan enumerates things to verify manually or in automated tests. It ensures that the most critical flows (ones that users rely on and that could break or cause support issues if not working) are always checked before release. It also indicates any edge cases to test (invalid input, permission checks). In sum, it’s like a checklist that QA or developers run through to say “yes, these fundamental things still work in version X.Y”. ⸻ Release / Distribution (WordPress.org + packaging) • Establish coding standards — WPCS + PHPCS + formatting rules Consistency and quality in code are important for long-term maintenance and community contributions. Adopt the WordPress Coding Standards for PHP (and JS/CSS to extent). This means things like: indentation with tabs, Yoda conditions, proper spacing, naming conventions (snake_case for functions, camelCase for variables in JS, etc.), escaping and sanitization practices as earlier. You can set up PHPCS (PHP Code Sniffer) with the WordPress Coding Standards ruleset to automatically flag deviations. Many IDEs can auto-format a lot of this or show warnings. Run PHPCS on your code periodically (or integrate into your build/CI pipeline)  to catch issues early. Also decide on other format preferences: for example, if using Prettier or eslint for JS formatting – align them to WP’s styles (which generally mirror core’s ESLint config). Document any exceptions or additional rules (maybe you want 120 char line length instead of 80, etc.). Beyond formatting, coding standards also include documentation: ensure every function, class, file has appropriate PHPDoc blocks (explaining parameters, return types, tags like @since, @param, @return). This not only helps others reading the code but also the Plugin Directory scanner might flag if no header docs on functions – possibly not, but it’s good practice. A consistent style makes the code base easier to read and reduces likelihood of errors (like missing text domain on translations or output not escaped because PHPCS can warn about that). Encourage using tools like Composer with WPCS or a package like WP Dev Lib to facilitate this setup. When contributions come in, run them through the standards check. It may seem pedantic, but having a clean codebase is also a reflection of plugin quality. The Plugin Team often recommends using WPCS to catch things before submission – it can even catch some security issues (like direct database queries without prepare). In summary, pick the standard (WordPress’s) and stick to it; use automated linters to enforce where possible . • /wp-release:standards-setup [repo] Detail how to set up coding standard checks for [repo] (your plugin’s repository). For example: We will integrate WordPress Coding Standards in the development workflow. Steps: 1. Add phpcs.xml config file at repo root targeting the WordPress-Core and WordPress-Extra rulesets (and WordPress-Docs for documentation maybe). Exclude any third-party libraries directory. 2. Require the WordPress-Coding-Standards/wpcs via Composer as dev dependency, along with PHPCS. 3. Add an npm script or composer script like "lint": "phpcs --standard=phpcs.xml" to easily run checks. 4. Optionally, add ESLint with eslint-config-wordpress for JS and stylelint for CSS with WordPress rules. 5. In CI (like GitHub Actions), configure a job to run composer install && composer run lint on push or pull request, so any standard violations are caught automatically. 6. Document in CONTRIBUTING.md that new code must pass PHPCS checks. Also mention formatting tools: maybe use EditorConfig to enforce basic indent settings, etc., included in repo. Summarize any key rules (like “please use Yoda conditions and escape all output, PHPCS will remind you”). This setup ensures that the repo is ready to maintain code style – it’s a one-time effort that pays off with every contribution and release. • Build & release pipeline — versioning, changelog, clean zip, build assets Plan how you go from development to a released plugin package. Versioning: decide on semantic versioning (e.g. Major.Minor.Patch). Update the plugin’s main file header and readme “Stable tag” to this new version when releasing  . Changelog: maintain a changelog in readme.txt (under == Changelog == section) summarizing new features, fixes since last release. Also possibly maintain a CHANGELOG.md for more detailed internal record. Build assets: if you use SCSS, TypeScript, or other sources, compile/minify them for release (maybe via npm run build that outputs to a dist/ folder or directly updates files in assets/). Ensure the built files have correct version strings (some do wp_enqueue_script( 'handle', 'file.js', ..., PLUGIN_VER, true), so update PLUGIN_VER constant). Clean zip: before packaging, remove any dev-only files – e.g. you might exclude tests/, .github/, composer.json, etc., from the distribution. If using SVN for .org, you simply won’t add those to trunk. If distributing on your site, create a script that zips the plugin folder excluding those files (many use svn export or gulp-rimraf tasks to prepare a clean folder). Check that the final zip has everything needed: main plugin file, all PHP/asset files, languages (.pot file at least), readme.txt, license. No sensitive info or keys. Release process: if on .org, committing to SVN trunk and tagging the version (the readme Stable tag should match tag name) will publish it  . For Git-driven, maybe use GitHub Actions to deploy to SVN or simply do it manually carefully. Announcement: update the changelog which will appear on .org, maybe draft a blog post or tweet if significant. Possibly mark the release on GitHub with notes if open source there. Also ensure any version constants in code are updated (some plugins keep a define('PLUGIN_VERSION','1.2.3')). After release, test the upgrade process from previous version on a dummy site. By having a clear pipeline, you reduce mistakes like forgetting to include a file or mis-numbering version. Tools can help: some use grunt-wp-deploy or svn-ci scripts. But even a manual checklist is fine: bump version, build, test, zip, upload. Document this pipeline so future maintainers know how to cut a release properly. • /wp-release:package-plan [version] Outline the steps to prepare and publish version [version] of the plugin. Example for version 2.0.0: 1. Code Freeze: Merge all final changes intended for 2.0.0 into the main branch. Ensure PHPCS linter passes and tests are green. 2. Bump Version: Update plugin header to 2.0.0 . Update readme.txt Stable tag to 2.0.0 . Update any internal version constants. Update changelog section: under == Changelog == add “= 2.0.0 =” with bullet points of changes. 3. Build: Run npm run build to compile/minify JS/CSS. Confirm dist/ files are updated. 4. Package: Create a clean directory for release. Copy plugin files except exclude: .git, node_modules, tests, etc. (We use an export script or do it manually). Ensure readme.txt and all needed files are in place. 5. Smoke Test Package: Install this packaged folder on a fresh WP site to ensure it activates and basic features work (quick sanity test that no file is missing, etc.). 6. SVN Commit: In SVN trunk, replace with new files (or if using GitHub action, push to SVN trunk). Commit with message “Preparing for 2.0.0 release”. Then copy trunk to tags/2.0.0 and commit. (If manual, also update Stable tag in trunk readme if needed). 7. Wait for .org: Check the plugin page after a few minutes to ensure the new version shows and assets (banner, etc. if any changes) look right. 8. Announce: Optionally, create a GitHub release or tweet announcing 2.0.0 highlights. 9. Support: Monitor support forum for any bug reports related to the new release and be ready to issue a quick 2.0.1 if a hotfix is needed. This package plan ensures nothing is overlooked (version bump in multiple places, including doing the tag). It’s essentially a release checklist specific to the version but can be generalized for any version. Great for consistency and avoiding the “Oops, I released but forgot to update Stable tag, now .org isn’t showing new version” scenario. • Internationalization (i18n) — text domain + strings + .pot generation Make your plugin translatable so it can reach a wider audience. Use a consistent text domain (matching the plugin slug) for all __() or _e() etc. calls . Wrap every user-facing string in these functions – including default settings or any admin notices, etc. (the only exceptions might be dynamically concatenated bits, where you’d use sprintf with placeholders inside __()). If your plugin is on .org, .org will handle translation delivery, but you need to ship a .pot file (portable object template). You can generate this using tools: e.g. WP-CLI has wp i18n make-pot . languages/yourplugin.pot --exclude=node_modules. Or Poedit can scan and generate one. Ensure the pot file contains all strings and is placed in /languages folder (or /lang). Also load the text domain in your plugin: call load_plugin_textdomain('your-text-domain', false, dirname(plugin_basename(FILE)).'/languages') on init or earlier . That allows WordPress to find translations. Verify by using a dummy translation (e.g. use a tool like Loco Translate or just manually modify a .mo file) to see if a sample string translates. Also double-check you didn’t accidentally make typos in text domain in any call – any mismatch means that string won’t get translated (PHPCS can catch inconsistent text domain usage). If your plugin outputs dates or times, use date_i18n() for localization. For any plural or gendered strings, use _n() for plural forms. The .pot generation should ideally be part of your release process (update it each release so new strings are available for translators). If the plugin is not on .org but elsewhere, you might need to ship .mo/.po for languages you provide. But on .org, you don’t include .mo – only the .pot (and maybe an initial .po for English). The community or your team can then translate via translate.wordpress.org. By ensuring full i18n support, you not only comply with plugin guidelines but also greatly expand usability. It’s much easier to do this during development than to retrofit. Check even trivial strings like “OK” or “Submit” are wrapped – those often get missed. After release, check the translation project on .org to ensure your strings show up (the presence of a fresh .pot triggers update there). • /wp-release:i18n-check [domain] Perform an i18n review before release focusing on [domain] (the text domain). For example, if [domain] = “myplugin”: • Search the code for (, _e(, _n(, etc. and ensure every instance uses ‘myplugin’ as the domain . No core domains or other plugin domains should be present (common mistake is copying sample code that uses ‘plugin-example’). Use PHPCS rule or grep to find any mismatches. • Check that dynamic strings are properly handled. E.g., if concatenating, ensure translators have full sentences. Instead of "Hello ".$name, have a placeholder: sprintf(("Hello %s","myplugin"), $name). • Look at any strings with placeholders and ensure context is clear or use translators comments (/* translators: ... */) for clarification if needed. • Update the .pot file: run the command to extract strings. Open the .pot to spot-check a few entries that they look correct (no odd things like untranslated words or dev comments). • Confirm load_plugin_textdomain is called early enough (ideally on plugins_loaded or init). If you have separate admin vs public, it’s fine to load in each or one central place. • If you introduced new strings this release, ensure they are added in readme’s changelog (translators might want to know significant new strings count, optional). • Validate the .pot using POEdit or msgfmt to ensure no syntax issues. • If you have language packs you maintain (for example you provide some translations yourself), update those .po/.mo from the .pot, increase their version if needed. But usually rely on .org. This i18n check ensures that when you release, translators can immediately start working on any new strings and that your plugin will display in users’ languages. It’s part of a professional release routine especially as your user base grows globally. • Write WordPress.org assets — readme.txt, screenshots, banners, FAQs To have a good presence on the Plugin Directory, prepare the necessary assets: readme.txt is crucial (it was addressed partially above regarding content like changelog and header). Ensure readme is up to date: good short description (<=150 chars)  , clear long description explaining what the plugin does and its features, maybe usage instructions. Include a Screenshots section with captions that explain each screenshot (the actual images named screenshot-1.png, screenshot-2.png, etc., to be uploaded via SVN). Good screenshots can dramatically help users understand your plugin UI/UX – take them on a clean test site (preferably using default theme to avoid too much custom styling), crop to relevant area, and maybe add highlights if needed. If possible, create an appealing banner image (1544x500 px) which shows either your plugin name or illustrative graphic – not required but makes your plugin page look more professional. For FAQs, think of common questions or edge cases and list them in Q/A format. E.g. “Q: Does this work with multisite? A: Yes, with limitations X.” or “Q: How do I get an API key? A: Sign up at example.com, then enter it in plugin settings.” That saves you support effort later. Also mention any known conflicts or requirements here. Tags: ensure relevant tags (5 max) in readme header so people can find your plugin in searches . Contributors: add any .org usernames who contributed code or translations. After writing/changing these, use the Readme Validator to check formatting  (a badly formatted readme can break your listing). The readme is essentially your marketing copy and documentation – spend time to make it clear, helpful, and free of spelling errors. For plugin updates, update the Tested up to, etc., in readme so users see it’s actively maintained . If you have a donate link or website, put that in header too. The combination of a good description, helpful screenshots, and maybe a banner can significantly increase user trust and adoption. • /wp-org:readme-draft [slug] Create a draft of the readme.txt for [slug] (the plugin slug). For example, [slug] = “awesome-plugin”: === Awesome Plugin === Contributors: yourwporgusername Donate link: https://example.com/donate Tags: custom widget, posts, design Requires at least: 5.5 Tested up to: 6.3 Requires PHP: 7.2 Stable tag: 1.0.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Awesome Plugin provides a set of custom widgets and design tools to enhance your WordPress site easily. == Description == Awesome Plugin lets you add beautiful custom widgets to your sidebar, including a profile card, recent posts with thumbnails, and a social links panel. It also adds some design customizations like custom background patterns for widgets. No coding required – everything is configurable via the Widgets screen. Features: Profile Card Widget: Display an avatar, bio, and social media links. Recent Posts Widget: Show recent posts with featured image thumbnails. Styled Categories: Optionally restyle your Categories widget with icons. Widget Backgrounds: Choose from 5 background patterns for widget areas. This plugin is ideal for bloggers who want to personalize their sidebar. It uses WordPress best practices – no extra scripts on pages where not needed, and minimal styling to blend with your theme. == Installation == Upload the awesome-plugin folder to the /wp-content/plugins/ directory, or install via the Plugins menu in WordPress. Activate the plugin through the 'Plugins' menu. Go to Appearance -> Widgets. You will see new widgets: "Profile Card", "Awesome Recent Posts", etc. Drag them into a sidebar and configure the options. Save and view your site – the widgets should appear with the chosen styles. == Frequently Asked Questions == = Can I use this plugin with any theme? = Yes, Awesome Plugin is designed to work with any theme. It inherits your theme's fonts and basic styling. The background pattern feature might look better on themes with wider sidebars. = How do I add my social links in the Profile Card? = In the Profile Card widget settings, there are fields for Facebook, Twitter, Instagram URLs. Fill those in (or leave blank any you don't want to show). Ensure you include the full URL (including http:// or https://). = Is this plugin GDPR compliant? = The plugin does not collect or send any personal data. It simply displays content from your site. If you use it to display personal info (like your profile), that's content you added to your site intentionally. == Screenshots == Profile Card Widget in action – Shows the profile card with avatar, name, bio, and social icons in the TwentyTwenty theme sidebar. Recent Posts Widget – Displays recent posts with thumbnail images and titles. Widget settings – Configuration options for the Profile Card widget in the admin. Background pattern options – The patterns you can choose for widget backgrounds. == Changelog == = 1.0.0 = Initial release of Awesome Plugin with Profile Card, Recent Posts, Styled Categories, and Widget Backgrounds. == Upgrade Notice == = 1.0.0 = First version. This draft covers the essential sections. It can be tweaked for style and length (make sure Description isn’t too long; break into paragraphs for readability). The FAQ addresses likely user questions. The short description at top is within 150 chars. Tags are chosen relevantly. Once this is polished, it will be ready to include with the plugin submission. • WordPress.org submission — guideline readiness + review response prep Before submitting your plugin to the .org repository, double-check it meets all Plugin Guidelines  . This includes: GPL-compatible license (you’ve set that in header, and any bundled libs are also GPL or compatible), no phoning home without consent (if you have tracking, ensure user opt-in), no branding violations (don’t include “wordpress” in plugin name or slug improperly), no obfuscated code, no security issues (you’ve done your security and privacy checks), and no spam/unauthorized links (don’t insert links on user site front without their knowledge, etc.). Ensure your readme and assets are complete as above. When you submit (via the Add Plugin page), you’ll need a slug – using your desired slug is ideal, but if it’s taken, be ready with an alternative. The plugin review team will manually review the code for a first submission or major changes. They may respond asking for changes. Be prepared to respond professionally: if they flag issues, fix them promptly and reply via email with how you addressed each point. Common things they might flag: missing escaping, using file_get_contents instead of WP HTTP API, including your own outdated jQuery, using create_function (deprecated), big issues with naming collisions, etc., or not sanitizing input. If you get no response for a while (they aim for within a couple weeks), be patient (don’t harass them; they are volunteers). Once approved, you’ll get an email and an SVN repo. Then you push your code and it goes live. Also be ready to handle support – after launch, users may post questions; being responsive there improves your plugin’s reputation. Internally, have a plan for how to handle bug reports or feature requests – maybe set up a GitHub issues page or use the support forum. For updates, note that any time you commit a new version, there’s no manual review unless something triggers it (like security issues reported). But major updates can be also pre-reviewed if you ask. So maintain guideline compliance with each update. Also consider hooking into the Plugin Asset system (the assets## Product / PM for WordPress • Validate the plugin idea — confirm the WP-specific pain + why existing plugins fail Before building anything, ensure there’s a real WordPress-specific pain point your plugin will solve. Research how people currently handle that problem and why existing plugins might not fully address it (missing features, poor UX, etc.). Validating demand can involve surveying your target audience and analyzing support forums or reviews of similar plugins. A great idea should fill a gap or do something significantly better than what’s out there. Using the WordPress.org repository for a free MVP can also help gauge interest and get early feedback (the plugin repo “is a great way to validate your plugin idea”). • /wp-pm:problem-brief [audience] [pain] Key Points: When crafting a problem brief, clearly articulate who the target audience is (e.g. “small business site owners using WooCommerce”) and the specific pain point they face in WordPress. Focus on the user’s perspective: what workflow is frustrating or inefficient? Why is it a problem in a WordPress context? For example, “Non-technical bloggers (audience) struggle to optimize images for speed (pain), because existing plugins are too complex.” A concise problem statement like this guides development to ensure your plugin provides a real solution. It’s also useful for marketing, as you can communicate the pain point and your solution clearly to potential users (keeping messaging focused on solving that pain rather than just building tech for tech’s sake). • Conduct an alternatives scan — research competing plugins (/wp-pm:alt-scan [competing-plugins]) Before finalizing your plugin concept, perform a scan of existing competing plugins. Search the WordPress.org plugin repository (and other marketplaces) for keywords related to your idea. Install and try out the top-rated or most popular ones. Note their feature sets, pricing models, user reviews, and any common complaints or feature requests. This competitive analysis helps you identify how to differentiate your plugin. Perhaps you’ll focus on a niche use-case the others ignore, or offer a simpler UI. Document the strengths and weaknesses of each competitor. WordPress has tens of thousands of plugins, so demonstrating why yours is needed (what gap it fills) is crucial to justify its creation. This research will also inform your plugin’s positioning and the value proposition you emphasize. • Pick the distribution model — WordPress.org vs freemium vs premium licensing Decide early how you’ll distribute and monetize your plugin, as it affects development and marketing. WordPress.org (free) distribution gives you exposure to millions of users and is often used for community goodwill or as a lead generator for a premium upgrade. Freemium model means a free base plugin (on .org) plus paid add-ons or a pro version; this balances reach and revenue, but you must manage two codebases (ensure the free version doesn’t violate .org rules by upselling too aggressively). A premium-only model (selling via your own site or a marketplace) means you can monetize all users but have to attract them without .org’s exposure. Consider your audience: if they expect free solutions, a freemium approach might work best. Also, if you choose commercial licensing, plan for how you’ll handle license keys and updates (e.g. a secure API to deliver updates to paying customers). Each model has trade-offs in support burden and revenue, so choose one aligned with your business goals and be transparent about it in your documentation. • /wp-pm:monetization-plan [model] Key Points: For the chosen monetization model, outline a plan covering pricing, feature split, and infrastructure. If freemium, decide which features are free vs. paid (ensure the free plugin is useful on its own, to comply with .org guidelines about not crippling functionality). If premium, decide on one-time purchase vs. subscriptions, and how you’ll sell (your own site, a marketplace, etc.). Plan a license key system for premium users to enable updates—WordPress doesn’t do this for you outside .org, so you may integrate an update API or use a service. Also, consider how you’ll support users (paid customers might expect faster support SLA). Document this plan internally so that development can be structured (e.g. using hooks or modules that can be unlocked for premium). A solid monetization plan ensures your plugin is sustainable and users understand the value they get for free vs. paid. • Consider .org vs pro version constraints (/wp-pm:org-vs-pro-constraints [feature]) If you adopt a dual free/pro plugin strategy, carefully delineate what each version includes. WordPress.org rules require that the free plugin must not serve just as a teaser; it should have real, usable functionality on its own. You might offer basic features for free and put advanced or “power-user” features in the Pro edition. For each major feature, decide if it’s essential for broad use (likely in the free version) or a value-add for niche cases (could be pro). Also consider technical constraints: the free plugin can include upgrade prompts, but they should be subtle and not hijack the admin interface (constant nags or locked screens violate .org guidelines). Perhaps implement gentle notices or a settings page section listing premium benefits, without affecting normal use of the free plugin. By clearly separating features, you avoid confusion and ensure users have a smooth experience on both versions. • Name and namespace strategy — slug, prefix, text-domain, brand consistency Pick a unique plugin name/slug and use a consistent prefix/namespace in your code to avoid conflicts. The plugin slug (machine name) should be short and unique (and will dictate your text domain and URL on .org). For example, if your plugin is “Easy Custom Posts,” a slug might be easy-custom-posts. All your functions, classes, option names, etc. should be prefixed with a unique identifier, often an acronym of your plugin name, to prevent collisions  . E.g. ecp_activate() or class ECP_Admin. WordPress.org now requires the text domain to exactly match the plugin’s slug for translations, so set Text Domain: easy-custom-posts in your header and use ('some string','easy-custom-posts') in code. Consistent branding (in function names, UI labels, and documentation) makes your plugin look professional and avoids confusion with others. Best practice: a prefix of at least 4-5 characters is recommended  (to reduce chance of overlapping with core or popular plugins). If your plugin interacts with others (like an add-on), avoid using their reserved prefixes (wp, Woo, etc.) to stay compatible . • /wp-pm:slug-namespace [plugin-name] Key Points: Provide your [plugin-name] with a proper slug and code namespace strategy. For instance, given plugin name “My Form Builder,” you might choose slug my-form-builder. Use that slug as the text domain and as the basis for all global identifiers. This means prefix all custom functions, hooks, database options, etc. with mfb or similar. In modern PHP, you can also use actual namespaces or autoloaded classes — e.g. namespace MyFormBuilder... — which effectively prevent naming collisions. The goal is to ensure your plugin’s code doesn’t conflict with any other theme or plugin in the WordPress ecosystem. WordPress hosts thousands of plugins, so pick a prefix that is not a common word . Consistency here also aids debugging: anyone reading the code or support logs can immediately identify which plugin a function or setting belongs to by its prefix. • Define minimum supported WP & PHP versions — decide baseline vs. target hosting reality Determine the oldest WordPress version and PHP version your plugin will support, and declare them in your plugin’s readme header (Requires at least: X.Y and Requires PHP: X.Y). This decision should balance using modern features with not excluding too many users. Check the WordPress.org Stats for usage of versions: for instance, as of 2026, a vast majority of sites run fairly recent WP core (WordPress generally encourages staying updated), and WordPress itself runs on PHP 7.2+ (with PHP 8+ recommended). It’s often reasonable to require at least WordPress 5.0+ (if you need the Block Editor or other new APIs) and PHP 7.4+ or 8.0+, given older versions are end-of-life. Setting a higher minimum PHP (like 7.4) helps you use newer language features safely. Just be sure to test on that lowest version. Document these requirements clearly; WordPress will prevent installation on sites not meeting the PHP requirement and will show it on your plugin listing. Also, consider the “target hosting reality” – e.g. many budget hosts now offer PHP 8+, but some laggards might still be on 7.x. If a significant chunk of your audience might be on older environments, you may choose to be more lenient initially. In any case, code defensively: if using functions introduced in newer WP/PHP, guard them or provide fallbacks when possible. • /wp-pm:support-matrix [wp] [php] Key Points: Create a support matrix listing which WordPress versions and PHP versions ([wp] core and [php] engine) you will support and test against. For example: “Supported WordPress: 5.2–6.3; Supported PHP: 7.4, 8.0, 8.1”. This matrix should be guided by both WordPress’s official recommendations and your user base. WordPress core’s minimum PHP is 7.2 (but it recommends 8.0 or higher), so supporting 7.4+ is a common choice in 2026. Likewise, decide if you’ll support older WP (some plugins maintain backward compat a few versions back). Listing this matrix helps in your README and documentation, and it informs your testing plans. It’s good practice to test your plugin with the lowest and highest versions in the matrix before release. If you drop support for older versions in an update, communicate that in the changelog (and perhaps enforce it via the “Requires at least” header). Keeping this matrix up-to-date ensures users know what to expect and reduces support tickets from unsupported setups. • Write a WordPress-first spec — admin pages, settings, hooks, roles, behaviors When detailing your plugin’s functional spec or PRD (Product Requirements Document), frame it in WordPress terms. This means thinking through how it will integrate into WP admin and workflow: Will it add an admin menu or sub-menu (and under which heading)? What settings pages or options will it provide (using Settings API or custom UI)? Identify any new custom post types or taxonomies if relevant, or custom database tables. Define what user roles/capabilities are required for various actions (for example, only Administrators can change plugin settings, etc.). Consider using existing WP hooks where possible to implement behaviors (e.g. hooking into the_content filter to modify output, or firing custom actions on certain events). Outline how the plugin will behave in typical WP flows – e.g. on plugin activation, on post save (if your plugin ties into content), on front-end page load, etc. Incorporating WordPress patterns from the start (like nonces for form actions, respecting WP Cron for scheduling, etc.) will make your plugin feel native and reduce surprises. Essentially, design with “the WordPress way” in mind: leverage core APIs and ensure your plugin plays nicely with core settings (like multisite, localization, the REST API if needed, etc.). A clear spec focused on WP context will guide development and result in a more robust integration. • /wp-spec:plugin-prd [feature] [wp-context] Key Points: For each major [feature] of your plugin, describe it in the [wp-context] of how it will work within WordPress. For example, if the feature is “scheduled content cleanup,” note that you’ll use WP-Cron to schedule it (instead of a custom cron job) . If a feature is “user submissions form,” mention using admin-post.php or REST API endpoints to handle the form, with proper nonces for security. Essentially, tie every feature to a WordPress concept: hooks, shortcodes, blocks, user roles, meta boxes, etc. This will ensure your feature list isn’t abstract but grounded in implementable WP terms. In the PRD, you might have entries like “Feature: Export data to CSV – Implementation: add an admin page under Tools menu, accessible to users with manage_options capability, include a nonce-protected form to trigger CSV generation, and use WP Filesystem API to stream the download.” This level of detail (what WP capability, which hook or API to use, etc.) makes the development tasks clear and aligns them with best practices from the start. ⸻ Plugin Engineering Core (PHP / WordPress APIs) • Choose plugin architecture — structure, autoloading, responsibilities Decide on an appropriate code architecture based on your plugin’s size and complexity. For a small, single-purpose plugin, a simple procedural approach (all logic in a single file or a couple of files with functions) might suffice. For larger plugins, lean towards an organized structure with classes or namespaces to encapsulate functionality. WordPress doesn’t enforce a specific pattern, but common choices include: a singleton main class, static loader classes, or a more modular MVC-like separation. Plan how you’ll autoload classes (you can use PSR-4 autoloading via Composer, or manually require_once files). Determine responsibilities: e.g., have a clear separation between admin-facing code and front-end code. Best practice: separate your code into folders like /admin and /public (and maybe /includes for shared logic), so you only load what’s needed in each context. Also consider using design patterns like Hooks Loader (a class that registers all actions/filters in one place) to keep things tidy. A thought-out architecture will make maintenance easier as the plugin grows and will prevent the “one giant file with spaghetti code” scenario. • /wp-dev:architecture [type] Key Points: Document the chosen architecture [type] in your developer notes. For example, “Object-Oriented, singleton main class” or “Modular classes with namespacing”. Clarify how different parts of the plugin interact. If using a loader or plugin factory, mention that. If adopting an established boilerplate (like the WP Plugin Boilerplate), note any deviations from it. Outline your directory structure and what goes where: e.g. “All custom post type definitions in includes/class-myplugin-cpt.php, all admin page handlers in admin/ directory, front-end display logic in public/ directory.” By specifying the architecture, new contributors or your future self can quickly grasp the project structure. This section might also cover performance considerations of the architecture: e.g., “Uses conditional loading: admin code is only loaded on is_admin() to avoid overhead on front-end.” A clear architecture plan ensures consistency as multiple developers work on the plugin. • Create plugin scaffold — header, main file, loader, activation/deactivation Set up the basic scaffolding of your plugin. This includes the main plugin file (with the header comment containing Plugin Name, Author, Version, etc. as required), and any initial include/require logic to load other files. Implement activation and deactivation hooks early for any setup/cleanup tasks . For example, use register_activation_hook(FILE, 'yourprefix_activate') to maybe set default options or create database tables, and register_deactivation_hook(FILE, 'yourprefix_deactivate') for cleanup like clearing scheduled cron events. Ensure these callbacks are defined and, if needed, perform capability checks or environment checks inside them. The scaffold should also include a basic file/folder structure as planned. If you prefer automated tools, you can use WP-CLI: running wp scaffold plugin will generate a starter plugin with sample files and even a PHPUnit test setup. This can speed up initial setup, giving you a standardized foundation (including a uninstall.php file if you choose to generate one). The goal is to have a functional “Hello World” plugin structure that activates without errors, to which you can then start adding real functionality. • /wp-dev:scaffold [slug] Key Points: When scaffolding the plugin identified by [slug], make sure to include all WordPress-required elements. The main plugin PHP file should have the proper header with at least Plugin Name and other fields (like Requires at least and Tested up to if applicable). If your plugin will need to run upgrade routines or has settings, consider adding an uninstall.php at this stage (for future data clean-up) or at least a placeholder for it. Set up the loader pattern if using one – e.g., a static function to include required files (only when needed, such as admin files on admin pages). Also, implement a safety check at the top of each PHP file to prevent direct access (commonly defined('ABSPATH') || exit; to ensure the file is not executed outside WordPress context). This is a basic security step for your scaffold. In summary, scaffolding means creating the skeletal plugin so that it can be activated and deactivated cleanly, laying the groundwork for all future code. • Plan data storage — Options API vs meta vs CPT vs custom tables Decide how you will store any persistent data your plugin needs. WordPress offers multiple mechanisms: the Options API (simple name–value pairs stored in the wp_options table), various meta (post meta, user meta, comment meta tied to existing objects), Custom Post Types (CPTs) (leveraging posts table to store structured data with fields via meta or taxonomies), or entirely custom tables in the database. Each has pros and cons. For small amounts of settings (configuration toggles, API keys, etc.), using the Options API is straightforward – e.g. get_option('myplugin_settings') . If your plugin manages entries that naturally align with content (like “FAQs” or “Recipes”), a CPT is convenient and gives you free admin UI and WP_Query support. Post meta is great for attaching extra info to posts/users, but can become slow if you need to query by that data extensively (since meta queries can be inefficient for large data sets). If you expect to store a lot of records or need complex queries (especially many-to-many relationships, or data not fitting WP’s post schema), a custom table might be justified – but remember to use the WPDB and prepare statements for security. As a rule: try to use native structures (options or CPT) unless performance or data complexity forces a custom table. Document this decision so it’s clear to others. For example, “Plugin will use a custom post type ‘faq’ to store FAQs, with meta for additional fields, because it allows using the WP editing interface and list table for entries. We considered custom tables but decided against due to wanting revision support and avoiding reinventing the wheel.” If custom tables are used, plan migration and cleanup on uninstall. • /wp-dev:data-plan [entities] Key Points: List out the data [entities] your plugin will handle (e.g. “form submissions”, “scheduled tasks”, “widget settings”) and decide for each where to persist it. For each entity, note the storage choice: Option (for global settings or small bits of data), Meta (attached to a WordPress object), Custom Post (if treating entries as content), or Custom DB table (for complex or heavy data). For example: “User preferences – stored as user meta; Plugin global option ‘myplugin_settings’ – stored in options table; Custom data ‘Deals’ – stored as a custom post type deal with custom fields for price.” Justify each choice briefly using WP best practices: e.g., “Using CPT for Deals gives us the benefit of WP’s built-in post UI and queries, and deals behave like content (can be published/drafted).” If any entity demands a custom table (e.g., a log of 10,000 transactions that would be inefficient as posts), mention that and outline how you’ll create and index that table. This planning ensures no part of your plugin’s data is left without a deliberate storage strategy, and it aligns your development with WordPress’s data handling strengths. • Register settings properly — Settings API + sanitization callbacks If your plugin has settings, use the Settings API to handle them rather than raw form handling. This provides a standardized way to register settings, sections, and fields, and ensures user inputs are sanitized before saving  . Steps include: call register_setting( $option_group, $option_name, $sanitize_callback ) to register each option or option array your plugin uses . Provide a sanitize callback that will receive and clean the input (e.g., sanitize_text_field for simple text, custom callbacks for more complex data) . Use add_settings_section and add_settings_field to generate your settings page fields in the admin, which ensures they are output with proper markup and tied to the registered setting. The Settings API not only helps with output consistency (your settings page will look like WordPress core screens ) but also automatically handles things like user capability checks and nonce generation for the form . By using it, you avoid writing repetitive validation code and you integrate with core’s expectation that plugin settings are under an option name and sanitized on save. Remember to also escape settings on output (when rendering in HTML) even if they are sanitized on save, as a defense in depth. In summary, do not just update options directly from $POST; funnel them through the Settings API pipeline for robust handling. This approach gives you free security benefits (like default nonce protection of the submission ) and aligns with user expectations for plugin settings pages. • /wp-dev:settings-api [settings] Key Points: For each plugin [settings] page or setting group, implement it via the Settings API. Identify the unique option names you’ll use (e.g. myplugin_options as an array or multiple option keys) and register them with register_setting. Include a validation/sanitization callback in the registration to clean user input. For instance, if you have a setting “welcome_message”, you might register it like: register_setting( 'myplugin_options_group', 'myplugin_welcome_message', 'sanitize_text_field' ); – this ensures whenever that setting is saved, WordPress will run sanitize_text_field on it . For more complex settings (like an array), you might write a custom function to validate each sub-value. Also, plan the user interface for settings: use add_settings_section for grouping fields and add_settings_field for each input, specifying which HTML callback renders it (perhaps using WordPress field HTML for consistency). This structured approach means your settings page form will automatically include the proper nonce and submit to options.php (WordPress core handler) which checks user capabilities (manage_options) and calls your sanitization callback  . Document in code comments or dev notes which settings exist and how they’re sanitized, for future maintainers. This not only improves security (by whitelisting expected input)  but also future-proofs your plugin if WordPress changes how settings are stored or handled, since you’re using the official API. • Hook into actions/filters — implement features “the WordPress way” WordPress is driven by its hooks system (actions and filters), and your plugin should leverage this to integrate seamlessly. Identify the core actions or filters that relate to your plugin’s functionality and attach your callbacks to them . For example, if your plugin needs to modify post content, use the the_content filter; if it should do something on user login, use the wp_login action, etc. Implementing features via hooks ensures you’re not hacking core and that your code runs at the appropriate time in WordPress’s execution flow . Also, create custom hooks in your plugin where appropriate to allow extensibility (e.g., do do_action('myplugin_after_something', $data) so other plugins or themes can extend your plugin’s behavior). This hook-oriented architecture is idiomatic to WordPress and improves compatibility. For each major functionality, decide if it can be triggered by an existing WordPress hook. For instance, instead of creating a custom cron runner, you might tie into init or a WP-Cron schedule. Document which hooks you’re using and why. Example: “Uses admin_notices action to display success messages after settings save” or “Filters widget_text to support shortcodes in our custom output”. By deeply integrating with WordPress’s hook system, your plugin will behave predictably alongside others (since everyone’s sharing the same event system), and you reduce the need for manual checks or timing issues – let WordPress call your code at the right moment. • /wp-dev:hook-map [feature] Key Points: Make a hook map that lists each plugin [feature] and the WordPress hooks it relies on or provides. For example: “Feature: Auto-publish custom post – Hook: save_post (priority 10) to intercept saves and publish under conditions” or “Feature: Custom SEO meta output – Hook: wp_head to output meta tags, and filter pre_get_document_title for the title”. By mapping features to hooks, you verify that you are indeed implementing things at the correct points in WP’s lifecycle. This map also reveals if you’re not using hooks where you should – if any feature is accomplished by direct modification of core behaviors, consider if a hook exists for it. Additionally, if your plugin introduces its own hooks (actions/filters that developers can use), list them here: e.g. “Action myplugin_after_form_submit – fires after form submission is processed, for others to extend.” Providing this in documentation (like in a developer section of your readme or a wiki) can attract other devs to integrate with your plugin. Ultimately, a hook map is both a design and debugging aid, ensuring a clear contract of when and how your plugin interacts with the WordPress ecosystem . • Prevent conflicts — use unique prefixes, no globals, safe resource handles, compatibility habits Plugin conflicts are often due to shared names or overriding things unexpectedly. Continue the practice of prefixing everything unique to your plugin (functions, classes, global variables, option names) with your plugin’s slug or identifier . Avoid introducing unnecessary globals; if you must use one (like a global instance of your main class), prefix it clearly ($myplugin_instance). When enqueuing scripts or styles, use unique handles (e.g., wp_enqueue_script('myplugin-slider', ...); not just 'slider') so you don’t clash with core or another plugin’s assets. The same goes for image filenames, CSS class names, or HTML IDs your plugin outputs – namespace them (e.g., .mfp-gallery rather than .gallery). Do not use reserved prefixes like wp or __ which are used by WordPress core . When adding admin menu items or custom roles/caps, ensure their slug/names are unique. Perform a quick conflict audit of your codebase: scan for any very common names or overly generic terms. For example, a function named update_database() is too generic – make it myplugin_update_database(). Use tools like PHPCS with the WordPress Coding Standards rules, which will catch some bad practices. Also, follow compatibility habits: check for existence of functions/classes before defining (use function_exists if there’s a chance another plugin declared the same function) , and wrap your functionality so it only runs in appropriate contexts (e.g., don’t output admin notices on front-end). By proactively preventing conflicts, you save users from white screens or odd bugs when multiple plugins are active together. Remember that with thousands of plugins in the ecosystem, collisions are a real risk – but a disciplined approach to namespacing and scoping will mitigate most issues  . • /wp-dev:conflict-audit [codebase] How to perform: Conduct a conflict audit on your plugin’s [codebase] by searching for any unprefixed or generic identifiers. For instance, scan all function definitions, class names, constants, and global variables for names that aren’t uniquely yours. If you find any, rename them with your prefix. Check asset handles in your wp_enqueue_script/style calls – ensure each handle is prefixed (e.g., search your code for wp_enqueue_script( and see what strings you pass as handle). Look at any external libraries you include: are you loading an outdated jQuery plugin that might conflict? If so, maybe use the one bundled with WP if available, or wrap it to avoid global leaks. Test your plugin alongside other popular plugins that do similar things or use the same libraries – do they both work together? For example, if two plugins include the same PHP library class with the same name, that’s a conflict – consider using PHP namespaces or include guards (class_exists) . Use WP_DEBUG and WP_DEBUG_LOG during testing to spot any “cannot redeclare function” or “class already defined” errors (which indicate conflicts). The conflict audit should also verify you’re not modifying any global WordPress variables or output buffers in a way that persists beyond your scope. Essentially, treat every piece of your plugin as if it lives in a sandbox – check that nothing “leaks” into the global WP environment unless intentionally. Document the audit results and changes: e.g., “Renamed function X to Y to avoid collision with plugin Z.” This step greatly reduces the chance of users encountering compatibility issues when your plugin is one among many on a site. • Ensure multisite compatibility — handle per-site vs network-wide mode If WordPress Multisite support is needed, design for it upfront. Determine if your plugin should behave on a per-site basis (likely default) or have any network-wide features when network-activated. At minimum, test activating your plugin on a Multisite network: if network-activated, your activation hook should run for each site or appropriately handle shared data. Use the is_multisite() check in your activation routine if needed, and note that register_activation_hook passes a $network_wide parameter to your function (you can use this to set up options on all sites in the network if required). For settings pages: if your plugin has a config, should it appear in each site’s admin, or only once in the Network Admin? You might choose to add menu pages via network_admin_menu for network-wide settings. Plan how data is stored in multisite: site options vs. network options (add_option vs add_site_option for network-wide data) . Consider using the Network: true header in your plugin file if it only makes sense network-wide (this forces network activation). Also account for multisite when cleaning up on uninstall: provide a way to remove data from all sites, perhaps by iterating with get_sites() if the plugin was network-active. Document any multisite constraints: e.g., “In Multisite, plugin settings are per site” or “Use the network admin to configure global plugin settings.” Ensuring this from the start will prevent surprises, such as duplicate tasks running on every site when they should run once globally, or data not being isolated per site. WordPress’s APIs (like get_option vs get_site_option) make it possible to adapt – you just need to incorporate them consciously based on the desired scope of your plugin’s features. • /wp-dev:multisite-plan [mode] Key Points: Clearly state whether your plugin runs in single-site mode, multisite network mode, or both ([mode]). If both, outline how it behaves in each. For example: “In multisite, when network-activated, the plugin will … (e.g., create a settings page in Network Admin only and use network options). When activated on individual sites, it functions independently on each site.” If the plugin is meant to be network-only, use Network: true in the header so WP prevents single-site activation. If it’s per-site only, you might leave network activation possible but simply operate per site. Note any differences: e.g., maybe an expensive cron job should only run on the primary site when in a network – you can check is_main_site() to enforce that. Your multisite plan should also cover data handling: if a user triggers a personal data export/erase (GDPR tools) and your plugin stores user data, ensure you hook into those for each site or network-wide as appropriate. Another consideration: User roles – in multisite, a network admin has super admin capabilities which you might need to check (like using is_super_admin() if needed). Summarize: “Multisite Plan: The plugin can be activated per site or network. On network activation, it will create one global settings page and use site options for each site’s data, aggregated if needed. On per-site activation, it behaves normally on that site only.” This clarity in planning ensures you don’t overlook edge cases (like someone network-activating and expecting a centralized config). Test your assumptions in a multisite sandbox. By having a multisite plan, you make your plugin friendlier to WordPress installations that run multiple sites, which is common for larger organizations or educational institutions. • Uninstall cleanup — implement uninstall.php for safe data removal Plan how your plugin will clean up after itself upon uninstall (when the user deletes the plugin permanently). If your plugin adds database entries (options, custom tables, meta data, etc.), consider removing them to avoid clutter, but make it optional or clearly documented if data loss could surprise the user. WordPress offers two main ways: an uninstall.php file or using register_uninstall_hook in your main file. Using uninstall.php is straightforward – WordPress will execute it if the plugin is deleted via the admin, as long as that file exists. In it, you should check if (!defined('WP_UNINSTALL_PLUGIN')) exit; at top to ensure it’s only run in the proper context. Then, delete your plugin’s options (use delete_option and delete_site_option for network options), custom user/meta data, and any custom tables (drop them carefully with $wpdb->query, as in the official example). Never attempt to remove things not created by your plugin. You might provide a setting “Remove all data on uninstall” for the user to opt-in to destructive cleanup, which is a user-friendly approach. Also, do not confuse deactivation with uninstall: deactivation is temporary (so you usually don’t delete data then ), whereas uninstall means the user is done with the plugin and likely wants all traces gone . Follow the principle: if it’s easy for the user to recreate or if keeping it poses risks, clean it up; if it’s user-generated content (like custom post entries), maybe leave it or at least warn. Document what your uninstall routine does. For example, “Uninstall: removes all plugin settings and custom DB tables, but leaves custom posts intact (since those might be user content).” Implementing a proper uninstall routine keeps the WordPress database tidy and signals that your plugin is well-behaved, as it doesn’t leave orphaned data . • /wp-dev:uninstall-policy [data] Key Points: Define your plugin’s uninstall policy for each type of [data] it creates. List out the data artifacts (options, custom tables, custom post types, user roles/caps, transients, etc.) and state whether each will be removed on uninstall. For example: “On uninstall, the plugin will delete its custom options (myplugin_options), transient cache (transient_myplugin_*), and custom database table wp_myplugin_logs. It will not delete custom post type entries or media uploads created by the plugin, to avoid deleting user content.” Implement this in uninstall.php or via register_uninstall_hook accordingly. If some data requires conditional removal (e.g., only remove user meta if a certain setting was enabled), code that logic. Also handle multisite: if network-activated, loop through blogs to delete per-blog options or meta as needed (but note, this can be intensive – WordPress’s guideline warns that looping all sites for deletion could be resource-heavy). Perhaps leave a note encouraging manual cleanup in extreme cases. By being explicit in your uninstall strategy, you ensure no surprises: users who expect a clean removal get it, and those who might want data preserved know what to expect. Including this in your documentation or even a prompt (“Do you want to remove all plugin data?”) can be good. Technically, your uninstall script should cover all data listed in this policy. This thoroughness is part of WordPress plugin best practices  and can help your plugin approval as the review team often checks for a proper uninstall routine (especially if your plugin creates tables or stores lots of data). • Database migrations — schema versioning and upgrade routines Plan for the possibility that your plugin’s data schema might change in future updates (new options, altered table structure, etc.). Implement a simple schema versioning system: for instance, store a version number in the database (maybe as an option like myplugin_db_version). On each plugin activation or load, check that against the current code’s expected version, and if it’s lower, perform upgrade steps then update the stored version. For example, if version 1.0 had an option myplugin_options and in 1.1 you split it into two options, your upgrade routine could detect old version “1.0”, then read the old option, migrate its values to new options, delete the old one, and set version to “1.1”. For custom tables, use the WordPress function dbDelta() which is specifically made to compare and alter table schemas safely. You would define your table SQL (with the new columns or indexes) and call dbDelta($sql) on plugin upgrade – it will create or modify tables to match the schema. Always wrap such operations in proper checks (and maybe backups or warnings if it’s destructive). Keep performance in mind: don’t run heavy migrations on every page load – only do it on admin or activation (some plugins trigger upgrades on an admin visit to avoid race conditions). Document your upgrade routine in changelogs so users know if an update will do a one-time DB operation. Also, test the upgrade path from an old version to new thoroughly, possibly with large data, to ensure it completes without timeouts. By engineering migrations, you allow your plugin to evolve without breaking existing installations. Many successful plugins use an internal version and an upgrade hook to manage this smoothly. • /wp-dev:migration-plan [schema] Key Points: Outline a migration plan for your plugin’s data [schema]. This includes specifying a current schema version (e.g., an integer or semantic version for your data model) and what changes are introduced at each version. For instance: “Schema v1: initial release, one table wp_myplugin with columns A, B. Schema v2: added column C to wp_myplugin. Schema v3: split settings option into two separate options.” Then describe how your code will detect and apply these changes. Example plan: “On plugin init, check option myplugin_db_version. If < 2, run function upgrade_to_v2() which uses dbDelta to add the new column; if < 3, run upgrade_to_v3() to migrate settings.” Note any special considerations, like copying data from an old structure to a new one, or populating new fields with default values. Also consider rollbacks: if a user downgraded the plugin, would your migration have irreversibly altered data? Ideally, design migrations that add non-breaking changes (like new columns that older versions would ignore) or at least warn users that once upgraded, going back is unsupported. A migration plan also involves testing on staging sites or backup sets of data. You might incorporate logging during migration (maybe using error_log or admin notices) to record that an upgrade happened – useful for support if something goes wrong. In summary, a migration plan ensures your plugin can handle upgrades gracefully, keeping user data intact and eliminating manual database fixes. It’s a mark of a mature plugin that doesn’t just assume fresh install every time. • Scheduled tasks (Cron) — use WP-Cron events with safe duplication guards If your plugin needs to perform periodic tasks (cleanup, external sync, email reports, etc.), use WP-Cron rather than system cron so it works across all hosting environments. Register a scheduled event with wp_schedule_event() on plugin activation (or on an admin action) specifying a recurrence and a custom hook name. Always check if the event is not already scheduled with wp_next_scheduled() before adding, to avoid duplicate scheduling. For example: if (!wp_next_scheduled('myplugin_cron_hook')) { wp_schedule_event(time(), 'hourly', 'myplugin_cron_hook'); } Then hook a function to myplugin_cron_hook to do the work. Within that function, you might still implement a duplication guard (especially if there’s any chance the task could overlap or if multiple events could fire due to race conditions). Sometimes a transient “lock” is used: set a transient when task starts and skip if one is found already (to prevent re-entry). Ensure to unschedule your event on plugin deactivation or uninstall using wp_unschedule_event() or clear_scheduled_hook('myplugin_cron_hook'), so it doesn’t orphan. Also, use appropriate recurrence intervals – WP has built-in schedules like ‘hourly’, ‘twicedaily’, ‘daily’, or you can add custom intervals. Don’t schedule tasks more frequently than needed (and document if your plugin might need DISABLE_WP_CRON off or any special setup). WP-Cron runs when someone visits the site (or via CLI cron), so consider that reliability (on low-traffic sites, cron jobs may run late). If precise timing is critical, advise the admin to set up a real cron hit to wp-cron.php. In any case, by using WP-Cron, your plugin plays by WP rules and will run in a wide range of hosting setups. The key is to avoid duplicate executions and to clean up after itself, which you handle with the checks and unscheduling mentioned. • /wp-dev:cron-plan [job] Key Points: For each cron [job] your plugin needs, specify the schedule and safeguards. Define: When (e.g., “hourly at approximately :00 minutes”), What (the task description), and How (the hook name and function). For example: “Job: expire outdated entries – scheduled daily via WP-Cron on hook myplugin_expire_hook, runs myplugin_expire_function() which deletes entries older than 30 days.” Note the recurrence (daily) and any conditions inside the function (like it processes max X items per run to avoid timeouts). Include a plan for registration: “The event is scheduled on plugin activation if not already present.” And for removal: “It’s cleared on plugin deactivation/uninstall”. Also mention duplication guard if applicable: e.g., “Function uses a transient lock so if a previous run is still in progress, it will not start a new one.” If you have multiple jobs, list each separately. If your plugin allows user-configurable scheduling (say user can choose to run something hourly or daily), note that and how you’ll update the schedule (like unschedule old and schedule new on option change). By writing out this cron plan, you ensure no cron task is forgotten or behaves unpredictably. It also helps during debugging – knowing “myplugin_expire_hook” fires daily means if something related isn’t happening, you can check if the cron is registered. In sum, the cron plan makes background tasks predictable and well-managed in the WordPress Cron system. • Logging & diagnostics — provide a status page and privacy-safe logs Building in some diagnostics can greatly help in supporting your plugin. Consider adding a debug or status page in the admin (for admin eyes only, capability check manage_options). This page could show things like current plugin settings, environment info (WP version, PHP version, active theme), and whether required background processes (like cron events or external API connections) have run successfully. Providing an exportable log of key events or errors is valuable. You might maintain a simple log (in an option or custom table, or even a debug file) of recent plugin actions – e.g., “Mail sent to X at Y time” or “API sync failed with error Z at 12:00”. If implementing logging, ensure it’s privacy-aware: do not log personal data (or if you do for debugging, provide a way to erase it and mention it in the privacy policy). WordPress offers built-in tools for personal data export/erasure; if your logs contain personal info, integrate with those (using the hooks in the Privacy API   to erase such info on request). Also, wrap any debug logging so it only operates when WP_DEBUG or a specific constant is true, to avoid performance hit or exposing info in production. You can utilize error_log() for server logs (when WP_DEBUG_LOG is on) or store events in a custom post type or option for retrieval. Provide a button on the status page like “Download Debug Log” which compiles recent entries into a text file, so users can share it with you for support. Make sure to sanitize any output here (so, if showing an error message, escape it to prevent any rogue HTML from breaking the admin). Having a diagnostics page and logs can turn a 5-cycle support thread into a quick resolution, as you (and the user) can quickly see what’s going wrong (e.g., an API key is invalid as per log entry). Emphasize that these logs are for admin use, and do not publicly expose them (capability check and maybe nonces to download). This commitment to transparency and troubleshooting sets your plugin apart by making it easier to diagnose issues without digging into code. • /wp-dev:diagnostics-screen [signals] Key Points: Design a diagnostics or status screen that presents important [signals] about plugin health. Determine which signals matter: for instance, “Is the plugin connected to API?” (yes/no), “Number of items processed in last cron run”, “Last error message (if any)”, “Current version of plugin and DB schema”, etc. Each signal should be derived from data your plugin can gather. Plan how you’ll fetch and display these: you might use admin_notices for urgent warnings (e.g. “API key missing!”), but a dedicated page can have a section “System Status” with green/red indicators. For example: Email Send Status: OK (last sent 2026-02-02 14:00) or ERROR (could not connect to SMTP). Also list configuration info: e.g., “WP Memory Limit: 40M”, which can hint if resources are an issue. If your plugin has background tasks, show when they last ran or if one is queued. Ensure sensitive info (like API keys or user data) is either masked or omitted on this screen to keep it privacy-safe. Provide guidance on this page as well – e.g., “If you encounter issues, click ‘Export Debug Info’ to download technical details to share.” That export could include the signals plus sanitized config (like which add-ons enabled, etc.). Since this is a lot of info, structure it with headings and maybe make it collapsible for sections. By implementing [signals] monitoring, you effectively create a “health check” for your plugin. This not only helps in support scenarios but also builds trust with savvy users who appreciate transparency. Where possible, integrate with WordPress Site Health (you can add your plugin’s info to the Site Health info tab via filters) – for example, adding a section “MyPlugin” with key info. Summing up, a diagnostics screen turns implicit plugin state into explicit signals that can be acted on, greatly easing troubleshooting and maintenance. ⸻ WP Admin UX (WP-Admin patterns) • Build the admin UI — menus, pages, forms, notices, using WP patterns Aim to make your plugin’s admin interface feel like a natural extension of WordPress. Add menu items appropriately: if it’s a major feature, a new top-level menu might be fine; otherwise, tuck it under an existing section like Settings or Tools for less clutter. Use the WordPress administration menus API (add_menu_page, add_submenu_page) with proper capability checks (usually manage_options for settings) so only authorized users see them. When designing admin pages, follow core UI patterns: use the Settings API for forms (it will generate fields with proper markup), use WP styles (the default admin CSS) for any custom HTML so it looks consistent (e.g., use classes like regular-text on text inputs for consistent sizing). If showing lists of data, consider using List Tables (WP_List_Table class) to get the standard table styles with sorting, pagination, etc. Ensure to include the screen icon and page title in as core does. Provide helpful admin notices for user actions: for example, after saving settings, add an admin notice “Settings updated” using the admin_notices hook and CSS classes like notice notice-success for success or notice notice-error for errors. Make notices dismissible if they are persistent. Also adhere to accessibility: every form field needs a (use	in a settings table structure, as WP does) for screen readers, and use proper heading structure ( for main headings on your pages, matching the admin’s hierarchy). In short, imitate core screens: if unsure, open a similar core settings page and inspect how it’s built (the General Settings page, for instance, for a form layout). WordPress provides many helper functions (like settings_fields() to output the needed hidden fields for settings forms , or do_settings_sections() to output your registered sections and fields) – use them rather than custom HTML where possible. This yields a clean, “WordPress-y” admin UI that users find familiar and intuitive, and it ensures things like styling and responsiveness are handled by WordPress’s own admin CSS. • /wp-admin:menu-ia [pages] Key Points: Plan the information architecture of your plugin’s admin [pages]. List what admin pages or screens your plugin will add and where. For example: “Main Settings (under Settings menu), Bulk Import page (top-level menu), Tools subpage (under Tools menu)”. Consider hierarchy: maybe you have a top-level menu “My Plugin” with subpages for different modules/settings. Use clear, short names for menu items (12-13 characters fit well in the menu design). Note the menu position if needed (though WordPress may shift things, you can suggest a position or just accept default which usually places new menus below core ones). For each page, decide its purpose: settings, reports, logs, etc., so you don’t overload one screen with too much. Also, specify navigation between pages: e.g., on your main plugin page, provide tabs or links to subpages if applicable (WordPress does this with tabbed navigation for some settings sections – you can mimic by checking $_GET['tab'] or using the Settings API to separate sections). Ensure pages have unique slugs and that you use the correct hook to output their content (often via the function you pass to add_menu_page/add_submenu_page). Additionally, mark down any context-sensitive help you’ll add – WordPress has a Screen Options/Help system; you might populate the Help tab with brief usage instructions. The menu IA should prioritize user needs: e.g., if the primary interaction is configuring settings once, that might just be one page; if ongoing management is needed (like managing custom post entries), those might actually be in WordPress’s existing screens (like a custom post type’s edit list). Sometimes the best admin UI is leveraging core UI – e.g., instead of building a custom list page, registering a CPT and letting users use the Posts list table UI. Document those decisions too. Once the IA is settled, you have a blueprint: “Our plugin will add: 1) a top-level ‘My Plugin’ menu with an icon, leading to a Welcome/Overview page, 2) a subpage for Settings, 3) a subpage for Logs.” This clarity will guide development of each page and ensure you don’t unintentionally bury important functions or confuse the user with where to click. • Design setting forms and fields — follow WP styles and structure (/wp-admin:settings-ui [fields]) When creating settings UI, consistency and clarity are key. List the specific [fields] you need to present (text inputs, checkboxes, selects, etc.), and group them into logical sections. Use the WordPress settings page structure: typically a wrapping your settings, then call settings_fields( 'your_option_group' ) to output the nonce and hidden fields , and do_settings_sections( 'your_page_slug' ) to output all fields registered to that page. This automatically lays out fields in a table with labels in the left column and inputs on the right, matching the style of core settings pages. For field types: use core form controls CSS classes (regular-text for , etc.), and if you have something like a color picker or media uploader, leverage WordPress’s built-in widgets (e.g., the color picker script, the media library). Ensure every field has an associated for accessibility (the Settings API add_settings_field helps with this by providing a spot for the label). For options that are boolean (on/off), consider using a checkbox with a descriptive label. For multiple choices, a dropdown or radio group might be appropriate. Keep text adjacent to fields to explain them (or use the description argument in the Settings API to have a help text under the field). Maintain spacing and styling by inspecting a similar core page – e.g. the Reading Settings page has a mix of checkboxes and text inputs and provides a good template. Also, handle validation feedback: if a user submits invalid data, you can use add_settings_error() to show a message on the settings page (this will display via settings_errors() if you include that) . This is the proper way to show specific error messages for settings fields in WP. By planning the form field structure, including field IDs/names and types, you ensure that development is straightforward and nothing is forgotten. A snippet example for plan: “Section: API Settings – Fields: api_key (text), enable_feature (checkbox). Section: Display Options – Fields: items_per_page (number), show_thumbnails (checkbox).” With such a plan, you implement using the Settings API calls and get a professional-looking settings UI that matches WP’s look and feel. • Add onboarding within WP-Admin — first-run pointers and safe defaults Consider the first-run experience: when a user activates your plugin, how do they know what to do next? A good practice is to provide onboarding guidance directly in the WP dashboard. This could be a one-time admin notice or a guided tour. For example, upon activation, you might add a dismissible admin notice saying “Thanks for installing MyPlugin! Go to [Settings -> MyPlugin] to configure it.” with a call-to-action link. Ensure this notice only shows once or until dismissed (use is_admin() and maybe an option or transient to track that it’s been shown). Alternatively, if your plugin truly needs an initial setup wizard, you can redirect the user to a welcome page on activation (but be cautious: .org guidelines discourage aggressive redirects/popups; if you do it, make it useful and only once). Another gentle onboarding technique is adding small help text or tips on your plugin’s pages themselves (for instance, if a settings page is empty until something is configured, provide a prompt like “You haven’t set up X yet, click here to do it”). Also, safe defaults: ensure that, even if the user does nothing after activation, the plugin either does nothing (neutral) or has sensible defaults that won’t break anything. For instance, if your plugin adds a front-end widget, perhaps default it to off until configured. Or ship with a reasonable default configuration so it starts working in a basic way without user input. Many users activate plugins and expect them to work out-of-the-box; meeting that expectation improves user satisfaction. Document any essential steps prominently (if, say, the user must get an API key, mention that in the notice with a link to instructions). In summary, onboarding is about reducing the learning curve: use admin UI elements – notices, help tabs, welcome pages – to guide the user. And by providing default settings that are likely what 80% of users want, you save most users from even needing to change settings (but always allow changes for the 20% who need customization). This thoughtful onboarding can decrease support queries and increase active usage of your plugin from the get-go. • /wp-admin:onboarding [setup-steps] Key Points: Draft a brief onboarding guide with [setup-steps] that typical users should follow after activation. For instance: “1) Go to Settings -> MyPlugin and enter your API key. 2) Navigate to Appearance -> Widgets to add the MyPlugin widget to your sidebar. 3) (Optional) Visit the Reports page under Tools -> MyPlugin to see data.” Use this list to inform the content of your welcome notice or welcome page. If feasible, implement some of these steps interactively: e.g., include a “Quick Setup” link that jumps the user directly to the relevant settings page (maybe even pre-filling something). Ensure each step is described in user-friendly terms (refer to WordPress UI labels exactly so they can find them). Additionally, think about the first-run default settings: document what they are so you can tell users “By default, X is enabled and Y is set to 10.” If appropriate, you might include a “Getting Started” or “Setup” section in your plugin’s readme/FAQ as well, but many users won’t read that, so surfacing it in the dashboard is key. The onboarding plan might also include adding a pointer (the little blue tooltips WordPress sometimes uses) – though those aren’t as commonly used now, a plugin can enqueue wp-pointer script to highlight a new menu or button. If you do that, plan which screen and element to point at and with what message. Finally, decide when onboarding is considered complete – often after a user saves settings or dismisses a welcome notice, you stop nagging them. In code, you might set an option “myplugin_onboarded” to true. All these steps aim to reduce the “What now?” moment right after activation. By detailing them under /wp-admin:onboarding, you have a checklist to implement and can ensure no crucial guidance is missed. • Improve update UX — inform users of changes, migrations, or new features Each time your plugin updates (especially major releases), try to communicate “what’s new” or any important actions the user might need to take. This can be done via a few mechanisms: admin notice on update, a highlighted changelog/updates page, or even an automated guided tour of new features. At minimum, consider showing a one-time admin notice after an update if there were significant UI changes or required setting changes: e.g., “MyPlugin updated! We’ve moved the analytics chart to its own page and added new settings for X.” Make this notice dismissible and not overwhelming. Another practice is to include an Upgrade Notice in your readme for critical updates; users see this in the plugin installer before they update. But in WP-Admin, after update, you could redirect to a What’s New page (some plugins do this on major versions – it’s acceptable if done only on major updates and clearly useful to the user). Alternatively, integrate into the Site Health/Plugin auto-update message system or just rely on good changelogs. If your update includes a data migration that might take time, inform the user via an admin notice like “MyPlugin is optimizing your data in the background, some features will be available once that’s done.” Also, handle any breaking changes gracefully: if you removed a feature, and the user had it enabled, you might want to show a notice or automatically adjust things to the nearest equivalent. The key is not to silently change or remove functionality without hinting to the user – that can cause confusion or make them think something broke. On the flip side, if you added a great new feature, a subtle pointer to it can increase user delight (“Check out the new Export tool under Tools -> MyPlugin!”). But don’t overdo it – keep notices brief and only on the dashboard (not every page view). Also ensure to remove or hide update messages after first view so they don’t linger. By treating updates as part of the UX, you maintain trust: users feel the plugin is transparent and helpful about changes, rather than being caught off guard. • /wp-admin:update-notices [release] Key Points: Prepare update notices or a mini “release notes” for the upcoming [release] of your plugin. Summarize what changed in non-technical terms: “Improved performance of data sync, added new filter options, fixed the login bug.” Identify if any user action is needed: “After updating, you’ll need to re-connect your account due to API changes” or “No action needed – all settings carried over automatically.” Decide how to present this: maybe as an admin notice that appears once after the update. If it’s a major release (say 2.0), you might even do a one-time redirect to a welcome page detailing the changes (but ensure this is a conscious decision and the page provides clear value, not just marketing). For smaller releases, a notice or just relying on the readme may suffice. If your plugin has a settings page, you could also incorporate a small “version badge” or link to release notes there. Implementation tip: You can store the plugin version in an option on each run, and if current_version > stored_version, trigger your update notice logic, then update the stored version. That way it only fires when an update actually occurred. Think also about localization – if you output a notice, make sure the text is internationalized so users in other languages get it in their language (if translated). The update notice plan should be part of your release process: every time you bump the version, consider if a notice is warranted. For a simple bugfix update, probably not; for anything with UI or feature impact, likely yes. As part of the plan, draft the exact wording for the notice for this release so you can just plug it into code or the readme’s Upgrade Notice section. This proactive communication makes updates smoother and reduces confusion, support tickets, or worst-case, users disabling the plugin because something changed unexpectedly. • Accessibility (a11y) check — ensure admin UI meets accessibility standards WordPress places a high priority on accessibility, and your plugin’s admin UI should be usable by people with assistive technologies (screen readers, keyboard-only navigation, etc.). Conduct an a11y review of your pages: ensure sufficient color contrast for any custom UI elements (stick to WP core colors if possible, which are designed for contrast). All interactive controls should be reachable via keyboard (e.g., can you tab to every link or button and activate it with Enter/Space?). All form fields need labels or aria-label attributes so screen readers can announce them properly. If you use icons or images to convey info, provide alternative text (via alt attributes or aria-hidden if purely decorative). Use proper HTML semantics: headings in increasing order ( then , etc., no skipping levels arbitrarily) – this structure helps assistive tech users navigate the page content logically. For dynamic content (like tabs or modals), ensure focus management (focus goes into a modal when opened and returns after closed) and provide aria- attributes (like role="dialog" and labels for modals). If your plugin adds columns to a list table or new admin tables, ensure to use scope on table headers or other table markup best practices. You can utilize tools: run your admin screens through browser extensions or tools like WAVE or AXE to detect obvious accessibility issues. Also, test using only the keyboard to make sure no required action is mouse-only. WordPress accessibility coding standards require meeting WCAG 2.1 AA for any new admin interfaces  , so aim for that. Additionally, consider users with different needs: if you have any animations or auto-updating content, provide a way to pause or a polite live region announcement for screen readers. Document any known a11y limitations and plan to fix them. Ultimately, an accessible plugin not only widens your user base but also ensures your plugin could be considered for inclusion in WordPress core one day (if it aligns), since core will only adopt a feature if it meets their a11y guidelines. Treat accessibility as a required part of UX, not an afterthought, and you’ll produce a more robust, user-friendly product for everyone. • /wp-admin:a11y-checklist [screens] Key Points: Create an accessibility checklist for the admin [screens] your plugin adds. Go through each screen and verify: 1) Keyboard navigation – Can you reach all interactive elements (links, buttons, inputs) via Tab/Shift+Tab in a logical order? Is focus visible (the outline) on all of them? 2) Screen reader labels – Does every form field have an associated or aria-label/aria-labelledby? Are section headings present for grouping content (so screen reader users can skim by headings)? 3) Color contrast – If you defined any custom text or background colors (in notices or banners), do they meet contrast requirements (generally a 4.5:1 ratio for normal text)? Use a tool to check any non-standard color usage. 4) ARIA attributes – For any advanced UI controls, did you add appropriate roles and properties? e.g., if you have a tab interface, use role="tablist", role="tab", aria-selected, etc., as per ARIA authoring practices. If you have error messages appearing dynamically, use role="alert" or similar so screen readers notify instantly. 5) Skip links or structure – If your page is long or complex, consider adding a “Skip to main content” link or ensure landmarks ( , with role) are in use. 6) Test with screen reader – If possible, actually turn on VoiceOver (Mac) or NVDA (Windows) and navigate your plugin’s interface, listening to the announcements. Does it make sense? Are controls properly named? Address any “Unnamed button” or confusing output. 7) Test at different zoom levels – Zoom the browser to 200% and see if your UI still works (responsive/adaptive design should handle this). After completing this checklist, list any issues found and fix them. For example, you might note: “Settings checkbox missing label – FIXED by adding . Notice dismiss button lacked screen-reader-text – FIXED by adding hidden text inside.” This checklist ensures you systematically cover accessibility, which might otherwise be overlooked in development. It’s much easier to build it in from the start than to retrofit later. By checking off all items for each screen, you can be confident your plugin meets WordPress’s accessibility coding standards  and, more importantly, can be effectively used by all WordPress administrators. ⸻ Frontend + Editor (Shortcodes / Blocks / Widgets) • Add frontend outputs — use shortcodes, template hooks, or widgets appropriately If your plugin needs to display content on the front-end (posts or pages), decide the integration method that best fits the use case: Shortcodes, Widgets, or template hooks. Shortcodes are good if users should embed something within post content (e.g., [myplugin_gallery id=123]) – they are easy to add via the post editor and you can parse them using the Shortcode API (add_shortcode) . Widgets (via Appearance > Widgets or block-based widgets screen) are suitable for sidebars or footers; you’d register a widget class extending WP_Widget if supporting classic widgets. In modern context, you might build a Block instead of a widget (see below), but if wide theme support for legacy sidebars is needed, a widget is fine. Template hooks: If the plugin needs to inject HTML at certain spots (like after post content or in the ), consider using existing theme hooks or filters. For example, to add a banner after content, you might hook the_content filter to append your HTML (with conditions to only do it for certain posts). Or to include CSS/JS, you’d use wp_enqueue_scripts (with proper conditions so it only loads on pages where needed). Evaluate what control the user has: shortcodes and widgets give them direct placement control. Automatic template hooks (like always appending after content) might need on/off toggles because not everyone will want that. Document any usage: e.g., if you provide a shortcode, include usage instructions in your readme or a small “Help” link in the settings page. Technically, ensure your front-end functions only run in the front-end (wrap them with ! is_admin() checks or similar if they’re hooked broadly). Also, sanitize and escape any dynamic output for safety (use esc_html, etc., when outputting user-provided data to front-end to prevent XSS ). If your plugin outputs something like a form, implement nonces and validation on submission. In summary, add front-end output features in a WordPress-standard way: shortcodes for inline content embedding , widgets for sidebar components, or theme/template integrations through actions/filters. This makes your plugin flexible and theme-independent. • /wp-fe:rendering-plan [surface] Key Points: Make a plan for how content will be rendered on the [surface] (meaning front-end surface: post content, sidebar, etc.). Identify each place your plugin might inject output. For example: “In post content – via a shortcode [myplugin], which calls a render function that outputs an HTML gallery. In sidebars – via a widget ‘MyPlugin Widget’ that outputs a summary box. After each post – via hooking the_content filter if user enabled the ‘auto-append’ option.” For each, note any dependencies: does it require assets (CSS/JS) to be enqueued? If yes, mention “enqueue myplugin.css and myplugin.js on pages where shortcode is present or widget is active.” If the output depends on query variables or template context, mention that (e.g., if hooking into template files via woocommerce_after_single_product hook or similar, ensure those hooks exist and you add conditional checks to avoid breaking other pages). Also plan how the user can disable or modify these outputs: maybe an option “Automatically add to content [yes/no]” that toggles the content hook. For shortcodes, decide on attributes and their default values to allow customization (list them: [myplugin type="grid" size="large"]). For each rendering surface, outline the HTML structure you’ll output (keeping it minimal and allowing theme styling – maybe your CSS just ensures basic layout, and you use appropriate semantic elements). If you expect users might want to override the output via theme, consider offering a template file (some plugins allow copying a PHP template to the theme directory for customization). Note if you’ll do that. By creating this rendering plan, you ensure no front-end output is overlooked and you adhere to WordPress norms. For example, using shortcodes means user can place it anywhere (even in text widgets if enabled) and multiple times on a page – test and plan for that (ensuring your code can handle multiple instances gracefully). The plan should also consider performance: if your output involves queries, ensure you don’t run a heavy query on every single post page unless needed (cache results or use transients if possible). Summarize: front-end surfaces and methods of output = well-defined, so implementation follows easily. • Create a Gutenberg block (if needed) — attributes, editor UI, front-end render With the Block Editor (Gutenberg) now dominant for content creation, consider offering a custom block for your plugin’s functionality if it’s something users would insert into posts/pages. Blocks provide a more user-friendly way than shortcodes (with rich preview and settings in editor). To create a block, define its attributes (data it will capture, like text, number, or select options) and how it should be edited vs. saved. Plan the editor UI: maybe use React components for controls (like TextControl, ToggleControl from @wordpress/components). Also decide if the block will be static (content saved in post content) or dynamic/server-side (rendered via PHP on the front). Dynamic blocks are useful if content changes frequently or relies on server logic (you’d use register_block_type with a render_callback in PHP). Static blocks output saved HTML (with potential placeholders for data). Determine your approach: e.g., a “MyPlugin Gallery” block might allow selecting images and layout in the editor (storing image IDs and layout choice as attributes), and on front-end output the gallery markup accordingly. Outline block metadata: title, icon, category (probably “widgets” or “embed” depending on what fits), and support features (like aligning or custom class support) in block.json. Then list attributes: e.g., images: { type: 'array', default: [] }, layout: { type: 'string', default: 'grid' }. For each attribute, note how user sets it (perhaps a panel in sidebar with a select dropdown for layout, and a media picker for images). Think about preview: in many cases, you can show a live preview in the editor similar to front-end using save function for static or by calling your render callback in an edit component for dynamic. Also ensure your block is internationalized (text strings in edit UI use __() etc.) and consider accessibility (labels for controls). From a coding perspective, decide if you will hand-code the block or use @wordpress/create-block scaffolding which sets up build config. Also consider backward compatibility: if someone is still on Classic Editor, you might maintain the equivalent functionality as a shortcode so they’re not left out. Many plugins do both: register a block that essentially wraps a shortcode in the front-end, for example. Once decided, implement accordingly. Creating a block definitely improves UX for block editor users: they get to insert your plugin’s feature with a nice interface rather than remembering a shortcode syntax. If your plugin’s feature is visual or complex, a block is worth the effort. Ensure to test the block thoroughly: in editor (is it intuitive?), and in front (does it degrade gracefully if disabled, etc.). Document block usage in your readme (“This plugin provides a Gutenberg block named MyPlugin Gallery under the Media category.”). By offering a custom block, you future-proof your plugin in the growing block-based ecosystem of WordPress. • /wp-block:block-spec [block] Key Points: Write down a specification for the [block] you intend to create. Include: Block Name/Slug (e.g., my-plugin/gallery), Title (human name, e.g., “MyPlugin Gallery”), Category (common ones are text, media, design, widgets, embeds), and an Icon (Dashicon slug or SVG for the inserter). Then detail the block’s purpose: “Allows user to insert a gallery of selected images with MyPlugin’s unique layout.” Enumerate the features: “User can choose layout style (grid or slider), choose images (from Media Library), and set an optional caption.” Outline its editing experience: perhaps when inserted, it shows a button “Select Images” that opens Media Library; once images chosen, it displays a placeholder gallery preview in editor (maybe a static image or a simplified rendering). The sidebar might have controls: a dropdown for layout, a toggle for “Show Captions”. Define attributes corresponding to each adjustable feature: e.g., images (array of IDs), layout (string, default ‘grid’), showCaptions (boolean, default true). Note which attributes should be saved to the block comment markup and how (most likely JSON in HTML comments if dynamic, or as part of saved content if static). Decide if block content is static HTML (e.g., save with markup containing image tags) or dynamic (save as a self-contained commented block that calls server on render). Given complexity (like multiple images), a dynamic block might be cleaner (render in PHP using those IDs). If dynamic, note the render_callback function name, which will use get_posts() or similar to fetch images and output the gallery HTML. Also ensure your front-end already has styling for these outputs; you might enqueue a front-end CSS for the block. Include that in spec: “Block will enqueue myplugin-frontend.css on view.” Consider reusability: can this block be used multiple times? (Yes, ideally). If so, your code should handle multiple instance separation (for example, unique IDs in HTML if needed). Finally, describe any fallback: e.g., if someone using the block disables the plugin, what happens? By default, the block content might show “Unsupported block” – if it’s dynamic with no content saved. Not much you can do except advise users; some plugins save a static version as HTML comment too for fallback. Having this block spec ensures when you or someone else builds it, all necessary details are known, and it aligns with user expectations. It’s effectively a mini-PRD for that Gutenberg block. • /wp-block:attributes-schema [block] Key Points: Define the attributes schema for the [block] in detail (this often lives in block.json). For each attribute, provide: name, type, default, and any source if saving to HTML. Example: "attributes": { "images": { "type": "array", "items": { "type": "number" }, "default": [] }, "layout": { "type": "string", "default": "grid" }, "showCaptions": { "type": "boolean", "default": true } } This indicates images will be an array of numbers (image IDs) with default empty array, layout a string defaulting to “grid”, etc. If any attribute corresponds to something you want saved in post content (via HTML), specify that. For example, if this were a simple block and you wanted to save the content of a caption within the block, you might use "source": "html", "selector": "p.caption" to pull from the saved markup. But for more complex/dynamic blocks, you often don’t save in HTML but rely on the attributes JSON. Note if an attribute is not user-editable (perhaps a calculated value) or if it should not be serialized. Most will be. Also, consider if some attributes should be transient vs persistent – e.g., maybe you keep track of something like “hasBeenEdited” not to output. It’s rare, but thinking through ensures no attribute collisions. Once attributes are set, list any validation needed: e.g., if layout should only be “grid” or “slider”, ensure UI restricts that or you validate on render. If using server-side render (render_callback), note that the PHP will receive attributes in $attributes array and you should validate types there too (don’t assume a string is as expected without checking, though block editor does most validation). With the schema in place, it’s easier to implement both the JS (in registerBlockType) and PHP (register_block_type reading block.json). Finally, consider legacy content: if you are replacing a shortcode with a block, you might implement deprecated patterns to convert shortcodes to blocks on paste, etc., but that can be complex. At minimum, clearly mapping attributes ensures the user input from block controls will produce the correct front-end output. This attribute schema plan is basically a contract for how your block stores its data – making sure it’s well-considered (covering all you need, nothing extraneous, using correct data types) leads to a stable block definition that won’t need breaking changes later (block attributes changes can break content or require migrations). It’s much like a database schema for your block content, so treat it with the same planning effort. • Handle assets correctly — enqueue scripts/styles with dependencies & versioning Deliver your plugin’s CSS and JS assets in the proper WordPress way. Use wp_enqueue_script() and wp_enqueue_style() to add your front-end and admin assets, rather than printing raw ), array('jquery'), '1.2.0', true );. That lists jQuery as a dependency, uses the plugin file URL, and version 1.2.0. The version is important for cache-busting – you can even use filemtime() of your asset file to version it during development, but in release, often plugin version or asset version is fine. The last argument true in script enqueue loads it in the footer (good practice for front-end performance, unless it’s needed in head). For conditional loading, hook your enqueue to specific pages: for admin assets, use admin_enqueue_scripts and check $hook to only load on your plugin’s admin pages. For front-end, if your asset is only needed on certain post types or when a shortcode is present, you might set a flag when shortcode executes and enqueue then, or use wp_enqueue_scripts with a global condition (e.g., check is_singular('product')). Do not blanket-load heavy scripts on every page if not necessary. Name your script/style handles uniquely (as mentioned earlier) to avoid conflict. Also ensure if using 3rd-party libraries, you handle registration correctly: if WP already includes a library (like moment.js, React, etc.), use that as a dependency instead of bundling anew. For editor (Gutenberg) blocks, enqueue block editor scripts via enqueue_block_editor_assets and front scripts via enqueue_block_assets, with correct wp-blocks, wp-editor dependencies as needed. Another best practice: use asset.php generated by build tools (if using Webpack with @wordpress/scripts) to automatically manage dependencies and versions for block scripts. Regarding CSS: try to scope it so it doesn’t unintentionally override themes (maybe prefix classes or limit to a container). For front-end CSS, often minimal styling is provided to let the theme handle aesthetics. For admin CSS, ensure it doesn’t conflict with core or other plugins by scoping to your admin page or using unique classes. Always test that your assets load as expected (check page source or Network tab). Improper handling (like forgetting to include jQuery dependency) can break functionality or cause console errors. Additionally, clean up on deactivation if needed – usually, styles/scripts only load when plugin is active (since code enqueuing is in plugin), but if you added any persistent admin pointers or such, remove them. Also, avoid loading your scripts if the same functionality is provided by core in a given context (e.g., don’t load a second copy of block editor in a meta box). By carefully managing how and when assets load, you improve performance and avoid conflicts. WordPress core even provides several default dependencies (listed in wp_enqueue_script reference) you can leverage for common needs. And always set WP_DEBUG on and check for any 404 on asset loading or any missing dependency warnings in debug log to catch mistakes. With this approach, your plugin’s assets will integrate smoothly with WordPress’s loading system and minimize bloat or conflict. • /wp-assets:enqueue-plan [scripts] [styles] Key Points: Make an enqueue plan enumerating each [scripts] and [styles] file your plugin will use, and when/how to enqueue them. For example: • Admin JS (admin.js) – Enqueue on plugin’s settings pages (admin_enqueue_scripts when $hook matches plugin page) with deps ['jquery','wp-util'] (if using wp.template for example), in footer. Version by plugin version. • Admin CSS (admin.css) – Enqueue on same pages, no special deps (just core styles), version by plugin version. • Front JS (public.js) – Enqueue on pages where shortcode is present. Implementation: hook into the shortcode output; when processing, call wp_enqueue_script('myplugin-public', ... ). Dep ['jquery'] if needed. Footer true. Or, if it must run earlier, ensure proper placement. • Front CSS (public.css) – Enqueue whenever front JS is enqueued (to style plugin output). Possibly no dep, or maybe dep on dashicons if using those icons (then include ‘dashicons’ in array and ensure wp_enqueue_style('dashicons')). • Block Editor JS (blocks.build.js) – Enqueue on block editor screens (enqueue_block_editor_assets), deps like ['wp-blocks','wp-element','wp-i18n'] as needed, version from build process (maybe link to blocks.asset.php). • Block Editor CSS (blocks.editor.css) – Enqueue on block editor screens, for styling the block in editor (if needed). • Front-end Block CSS (blocks.style.css) – Enqueue on frontend whenever block is present. WordPress can do this automatically if registered in block.json under “style”. If not, manual: since blocks output HTML with classes, include this style globally or conditionally if possible. Also list external assets if any (like say you include a lightslider.js). For those, consider using wp_register_script to register it with proper version and enqueue it as a dependency to your main script. The plan should include any conditional logic: e.g., “Only enqueue carousel.js if [gallery] shortcode used AND layout=carousel selected.” Possibly you decide to always enqueue minimal CSS for safety, but heavy JS only when needed. Also plan handle naming: ex. myplugin-admin-css, myplugin-block, etc. The plan might note to use plugins_url() or plugin_dir_url(FILE) to form paths. Also mention if any assets require localization: e.g. you might do wp_localize_script('myplugin-public', 'MyPluginData', array( 'ajax_url' => admin_url('admin-ajax.php'), 'nonce' => wp_create_nonce('myplugin_nonce') )); to pass dynamic data. Plan those global objects and values so you implement them correctly. Lastly, plan the removal on cleanup if needed (though usually just deactivating stops enqueues naturally). With this thorough list, you can implement all enqueues systematically and ensure nothing is missing or mistakenly loaded. It will also reveal if you have too many assets (maybe you can combine or load only when necessary). This preempts issues like forgetting to include a required script or loading something at wrong time. Essentially, it’s a deployment checklist for assets: what, where, dependencies, version. Following it yields a polished integration in the WordPress asset pipeline with no surprises. ⸻ Integrations (REST / AJAX / External services) • Add REST API endpoints (if needed) — define custom routes, callbacks, permissions If your plugin needs to expose data or operations via the WordPress REST API (for JavaScript use or external access), create custom REST endpoints. Determine the routes you want, their methods, and what they should do. For example, you might have a route like /myplugin/v1/items to GET a list of items or POST to create a new item. Use register_rest_route( 'myplugin/v1', '/items', {...} ) inside a rest_api_init action callback  . For each route, provide an array of options including methods (GET, POST, etc.), a callback function to execute, and importantly a permission_callback  . The permission callback should check user capabilities or authentication and return true/false. For open data that doesn’t require auth (rare in plugins), you might return true for GET but usually you ensure a user is logged in or has a certain role. If the route is for admin-side AJAX, you might just enforce current_user_can('manage_options') for example. Also define any arguments your endpoint accepts and validate them (you can use the args option in register_rest_route to have the REST API handle validation, sanitization, and error reporting for parameters ). For instance, if expecting an ‘id’ param, specify it should be an integer. In your callback, do the core logic: probably retrieve or modify data and then return a result (preferably as a WP_REST_Response or an array which WP will convert to JSON). Use the helper rest_ensure_response() to wrap data properly . Consider response codes and messages carefully. The REST API also handles output escaping (it returns JSON), but ensure any internal data is sanitized on output if needed. Document your endpoints for devs: e.g., in README or code comments, note “GET /myplugin/v1/items – returns list of items (requires Editor or above)”. Test endpoints with tools like Postman or the browser console (wp.apiFetch) to make sure they work and enforce permissions. Also consider naming: use a namespace (myplugin/v1) to avoid collisions . If you later need to change the API in backward-incompatible ways, create a v2. By integrating with the REST API, you allow more flexible interactions – for example, your plugin’s JS can fetch data asynchronously, or external apps can use API keys/auth to interact. It’s the modern way to add AJAX-like functionality as well. If you do use admin-ajax for something, weigh converting it to REST: REST is more standardized and faster (no admin bootstrap overhead). That said, for simple internal calls, admin-ajax is fine. If implementing both, ensure you don’t duplicate code – maybe have both endpoints call the same underlying function. Overall, adding REST endpoints extends your plugin’s reach and is essential if building a SPA-like interface or integrating with other systems. • /wp-rest:endpoint-spec [routes] Key Points: List the REST [routes] you will implement, with details for each. For example: • GET /myplugin/v1/items – Description: returns collection of items. Permissions: logged-in users with read capability. Args: optional search (string), page (int). Response: JSON array of item objects (fields: id, title, etc.). • POST /myplugin/v1/items – Description: create a new item. Permissions: users with edit_posts (for example). Args: title (string, required), content (string, optional). Response: JSON object of created item or error. • DELETE /myplugin/v1/items/(?P\d+) – Description: delete item by ID. Permissions: maybe only admins (manage_options). Args: (id from URL). Response: success message or error. For each, plan the callback function name (like myplugin_get_items), and what that callback will do – e.g., retrieve posts of a custom post type, or query an external API, etc. Note if you’ll utilize any WP REST infrastructure like WP_REST_Controller (if your items correspond to CPT, you could extend the controller for posts). However, custom endpoints often just use custom callbacks. Also plan the permission_callback for each: e.g. 'permission_callback' => function() { return current_user_can('edit_posts'); } for certain actions . If different HTTP methods on same route have different permissions, you might register them separately or handle inside. For inputs, specify validation: perhaps 'validate_callback' => function($param, $request, $key) { ... } for complex cases; or simpler, use built-in by specifying 'type' => 'integer' or 'format' => 'email' in the args schema, etc. The spec ensures you don’t forget edge cases, like “What if item not found on GET by ID? – we will return 404 using return new WP_Error('myplugin_not_found', 'Item not found', array('status'=>404));.” Also consider performance: if the GET could return many items, plan pagination (maybe require page param, and return total count in headers or response). Mark which endpoints are primarily for internal use (by your plugin’s JS) vs external – though all are technically external once published. If any should be protected via nonce (for example, if you want to ensure requests come from your site’s editor, you could require a nonce in request headers and validate with wp_verify_nonce in permission callback). However, usually is_user_logged_in and capability checks suffice for protection. Summarize each route’s responsibilities and error conditions. Once you have this blueprint, implementing in register_rest_route calls becomes straightforward, and you can unit test each with known inputs/outputs. It also communicates to anyone reviewing the code what your API looks like. A well-designed endpoint spec leads to a robust, RESTful integration in WordPress, aligning with core’s patterns and providing a clean interface for third-party consumption if needed. • Implement AJAX actions (if not using REST) — use admin-ajax with nonces and caps For parts of your plugin that need server-side processing initiated from the browser (like form submissions or button clicks in the admin that shouldn’t reload the page), you can use admin-ajax.php as a classic AJAX handler (particularly if not leveraging REST for this). Admin AJAX in WordPress uses action hooks wp_ajax_[action] (for logged-in users) and wp_ajax_nopriv_[action] (for non-logged users). Choose an action name unique to your plugin, e.g., myplugin_do_task. In your JavaScript (or form), send a POST or GET to admin-ajax.php with action=myplugin_do_task plus any data. In PHP, hook add_action('wp_ajax_myplugin_do_task', 'myplugin_do_task_callback') (and if needed, the _nopriv one for non-logged users). In the callback, first and foremost, verify the nonce (and any other security checks). Typically, you printed a nonce into the page or JS via wp_localize_script earlier; now use check_ajax_referer('myplugin_nonce') to validate it. If it fails, you can wp_die('Nonce check failed', 403); (WP will respond -1 by default on failure). Next, verify capabilities if needed (for example, if this should only be done by admins, do current_user_can('manage_options') and wp_die if false). Then process the request: e.g., perform database update, or call an external API, etc. Return a response. In admin-ajax context, you usually output using echo or wp_send_json_success()/wp_send_json_error() for structured data . Remember to call wp_die() or simply wp_send_json which will die for you, to end execution . Also, because admin-ajax essentially loads the whole WP environment, ensure your callback is efficient (no unnecessary queries). Keep in mind admin-ajax runs even if not on WP admin, so if your action is for front-end visitors not logged in, you must hook the _nopriv variant and handle accordingly (no current_user, maybe some other auth token). Document the AJAX actions: it’s helpful for other devs to know “myplugin_do_task expects POST fields X, returns JSON Y.” But if it’s purely internal, inline comments may suffice. Compare to REST: admin-ajax is simpler to implement for small things (no need to register route) and especially if you rely on WP admin sessions. But REST is more powerful for broader use. In some cases, you might use admin-ajax for admin-side interactions (like a settings page doing something behind the scenes) because you know user is logged and you want to reuse WP admin context. That’s fine. Just ensure all standard security: nonces to prevent CSRF, capability checks, sanitize input (use sanitize_text_field or similar on $_POST data). And of course, test these flows: open browser dev tools, watch the network request, ensure responses come back as expected. By doing AJAX via admin-ajax robustly, you provide a smoother user experience (no full reloads) while maintaining security akin to form submissions. It’s essentially an older parallel to REST but still widely used. • /wp-ajax:action-spec [actions] Key Points: List the AJAX [actions] you will support, with the following details for each: Action name, Use case, Request data expected, Response data/output. For example: • Action: myplugin_refresh_stats – Use: When user clicks “Refresh Stats” button on plugin dashboard, fetches latest stats via AJAX. Expects: POST with nonce: myplugin_nonce and maybe an entity_id. Response: JSON containing updated stats (counts, etc.) or error message. Permissions: Only admin (check manage_options). • Action: myplugin_form_submit – Use: Handles submission of a front-end form for non-logged users (e.g., a feedback form). Expects: POST with fields (name, email, message) + a nonce field (nonce created with wp_create_nonce('myplugin_form')). Response: JSON success or error. Permissions: No login required (so use wp_ajax_nopriv_myplugin_form_submit), but still verify nonce for CSRF and possibly do additional spam check. For each action, note any special considerations: throttle frequency (maybe you set a transient to prevent rapid re-submits), large data (maybe chunk output), etc. Plan how you generate the nonce on the page (e.g., via wp_localize_script as earlier, assigning ajax_url and nonce). The spec should map out the user flow: “User clicks X -> triggers JS function -> sends jQuery $.post to admin-ajax with action Y -> PHP handler does Z -> returns [this] -> on success JS updates the UI, on error shows a message.” Write the pseudo-code for PHP handler: “verify nonce, if fail wp_send_json_error( ‘Unauthorized’, 401 ); else do logic (perhaps call internal function or WP function), then wp_send_json_success( $result_array ).” This ensures you include proper HTTP status if relevant (though wp_send_json_success always returns 200 with success = true wrapper). Also, think if any actions should be combined – sometimes multiple buttons could use one action with a parameter telling what to do, but clarity might suffer. Usually one action per distinct operation is fine. Check if similar core AJAX exists for your need (e.g., core has some actions for common tasks). Unlikely, but for example, for media you’d use core’s endpoints rather than reinvent. If applicable, list dependency: “This AJAX calls uses WP’s media AJAX to upload images (so we rely on core handlers).” Another factor: if front-end, do you want to support sites with page caching (where admin-ajax is not cached)? It usually works since it’s POST and to admin-ajax which isn’t cached. Fine. The spec should also mention “ensures to call wp_die() at end of handler to terminate properly” (even though send_json does). Summing up: after writing this, you’ll have a to-do list to implement each action hook and the corresponding JS. It acts as a contract that JS and PHP dev sides can follow. A thorough action spec prevents missing a nonce or forgetting to output the right format. It’s especially useful if multiple people are working on plugin (one can do JS side, one PHP, but align via this spec). It’s also helpful for documentation if you ever allow others to hook or use your AJAX endpoints (less common, but if someone wanted to programmatically trigger your plugin’s AJAX, they’d need to know these details). • Implement commercial licensing (premium) — license key activation, remote updates, graceful expiry If your plugin has a premium version or add-on with licensing, plan how to handle license keys and updates. For a premium plugin not on .org, you’ll need a system to deliver updates (commonly through a private update API or integrating with a service like Freemius, EDD Software Licensing, etc.). Decide on the license model: e.g., one key per purchase, maybe domain-limited or user-limited, with an expiry (annual subscription or lifetime). In your plugin settings, provide a License Key field where users can enter their key. When they do, you typically validate it against your server: likely using a remote POST request (like wp_remote_post() to your site’s API endpoint) sending key and site URL, and get back active/expired status. Ensure to use HTTPS for such calls and maybe some form of signing to prevent tampering. Once activated, store the key and activation status (probably in an option). For updates: WordPress can update plugins if they provide metadata via the Updates API. You might implement a custom updater class (there are library examples that hook into pre_set_site_transient_update_plugins to inject your plugin update info if license is valid). Outline that flow: “On admin init, if license valid, call our update API endpoint to check if a new version is available, then feed results to WordPress’s updater.” Or if using a licensing plugin (like EDD or WooCommerce API Manager), use their provided updater class. The key is to only allow updates if license is valid (or maybe allow updates but with notices if invalid, depending on strategy). Also consider graceful expiry: if a license expires, decide what happens in the plugin. Often, the plugin continues functioning but stops getting updates and support; you might show an admin notice “License expired, please renew to get updates” – but do not cripple the plugin’s core functionality out of nowhere (that’d anger users). If you intend to disable features on expiry, be very upfront about it and implement it cleanly (e.g., certain pro features become read-only or are locked behind a notice). Plan how often to re-verify licenses: maybe at every update check or daily via cron to see if a key was revoked. Also handle edge cases: user enters invalid key – show error; user deactivates license on one site (you might have a “Deactivate license” button to free up activation slots). The licensing system often involves storing some unique site ID or hash in the licensing server when activated. From plugin side, sending domain and maybe an MD5 of something. Document where your license verification URL is (for yourself or if anyone might extend). The graceful part: ensure that if license is missing or invalid, the plugin doesn’t break the site or spam the user. A subtle notice periodically is enough. And if license is valid, do not annoy with notices. Also, avoid too-frequent calls home (could slow admin) – perhaps check license status weekly or at update checks. Summarize: build a small licensing module in your plugin: a settings field for key, an activation function (calls remote, gets response, stores status), an updater integration (if building one), and a notification system for expiry. Include security: the license key is sensitive (someone could use it if they find it), so if storing in DB, consider obscuring it (though DB admins could see it – that’s usually okay). At least, don’t expose it in page HTML anywhere. For remote calls, authenticate them (some license APIs require a secret or the key itself is enough if unpredictable). By planning this out, you ensure the premium user experience is smooth (enter key -> see “Activated” and get updates) and the system is robust against abuse (like invalid keys trying to get updates will be rejected). This is one of the trickier parts as it spans beyond just plugin code into e-commerce systems, so clarity here saves headaches later. • /wp-pro:licensing-flow [model] Key Points: Describe the licensing flow for your premium [model]. For instance, if using Easy Digital Downloads (EDD) licensing on your site: User purchase: They get a license key (maybe via email or account). Activation in plugin: They input key in plugin settings and click “Activate License”. Plugin requests (via wp_remote_get) to https://yoursite.com license API with edd_action=activate_license&license=[key]&item_id=[product_id]&url=[home_url]. API Response: JSON indicating success or fail. Plugin parses it. If success, store license status = valid (and maybe expiration date if provided). If fail, show error (maybe expired or invalid). Updates: The plugin includes a updater class that hooks into WP updates. That class on each update check sends edd_action=check_license&license=[key]&item_id=[id]&url=[url] or fetches a package URL (some systems do one or both). If license valid and update available, returns info including download_url. The plugin then passes this to WordPress, allowing the update. If license invalid or expired, the check might either not return update or return a download_url that leads to an expired notice (depending on how you set it up). The plugin updater should handle that gracefully (perhaps notify user “Update available but license inactive”). Deactivation (optional): If user clicks “Deactivate License” in plugin, send edd_action=deactivate_license to server to free up usage count, and delete local key or mark it inactive. Renewal: Outside plugin scope (happens on your site), but plugin could periodically remind “Your license will expire in 10 days” if you get that info. (Usually license API can tell expiration timestamp). If using a different system (like a custom one), outline similar steps. If using a marketplace (like CodeCanyon), often they don’t have an API, so you might skip licensing entirely or implement a one-time purchase code verification with your own server. Write that scenario out. E.g., “User enters purchase code, plugin sends to our server to verify against Envato API, then we treat it as key. But since no auto-update from Envato, we supply updates ourselves via our server.” Also, if the plugin has a free + pro separate plugin model, then the pro plugin might simply check license for support/updates. In that case, note if the free one should detect pro installation or if any special integration needed. Clarify how graceful degradation works: e.g., if license is expired, the plugin doesn’t disable features immediately, it just stops updates and shows renewal notice. Or if license is really tied to usage (like a SaaS connection), maybe then features would stop if expired (like a payment gateway plugin might disable transactions if license expired – though that’s usually not done to avoid harming end-users; it’s a choice). Make that call and justify. Finally, ensure the privacy implications: If you’re sending site URL or user email to your server as part of license verification, that should be disclosed in plugin’s privacy notice (if any). WordPress.org guidelines require telling about external connections. Since premium plugin might not be on .org, less an issue, but still good practice. Summarizing the licensing flow in the spec ensures you and any collaborator know exactly how the premium aspect works step by step, preventing confusion like forgetting to implement deactivation or handling error codes. It’s essentially a user story of a paying customer’s interaction with the plugin’s licensing: Activation -> Usage -> Renewal. Ensure each step has a corresponding part in code to handle it.