# WordPress Plugin Development Guidelines for Cursor AI

1 - only build or make changes wihin this a1ai folder. 

2 - always review rules.md before writing code

3 - document all changes after every prompt is finished in the CHANGELOG.md file. Start with what my prompt was, which file(s) were edited, which lines, and anything else pertinent to remember.

4 - when issues arise and I have to work on a problem multiple times I will use an * asterisk at the beginning of my prompt which means review recent information in the CHANGELOG.md file for refernce of what we are doing or have done. ** means dig deep into the file, *** means review everything.

## Code Structure and Organization

1. Always follow the WordPress plugin directory structure:
   - Main plugin file named after the plugin: `my-plugin.php`
   - `/includes/` for class files and core functionality
   - `/admin/` for admin-specific code
   - `/public/` or `/frontend/` for public-facing code
   - `/languages/` for translation files

2. Use proper file header comments in the main plugin file:
   ```php
   /**
    * Plugin Name: My Plugin Name
    * Plugin URI: https://example.com/plugin
    * Description: Clear description of what the plugin does
    * Version: 1.0.0
    * Author: Plugin Author
    * Author URI: https://example.com
    * Text Domain: my-plugin
    * Domain Path: /languages
    * License: GPL-2.0+
    * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
    */
   ```

3. Always include direct file access prevention in every PHP file:
   ```php
   // If this file is called directly, abort.
   if (!defined('WPINC')) {
       die;
   }
   ```

## Naming Conventions and Prefixes

4. Use unique, descriptive prefixes (at least 4 characters) for:
   - Function names: `myplugin_function_name()`
   - Class names: `My_Plugin_Class_Name`
   - Constants: `MYPLUGIN_CONSTANT_NAME`
   - Options: `myplugin_option_name`
   - Hooks: `myplugin_hook_name`

5. Avoid generic function names and prefixes like "wp_", "wordpress_", "_", or "__" (reserved for WordPress core).

6. Match text domain with the plugin slug for proper translation support.

## Proper API Usage and Integration

7. Use WordPress hooks (actions and filters) for extending functionality, not direct function calls.

8. Always use proper WordPress APIs:
   - Database: Use `$wpdb` with prepared statements
   - Options: Use Options API (`get_option`, `update_option`)
   - Settings: Use Settings API for admin configuration
   - HTTP: Use WordPress HTTP API (`wp_remote_get`, `wp_remote_post`)
   - AJAX: Use WordPress AJAX API with nonces

9. Enqueue scripts and styles properly:
   - Use `wp_register_script()` and `wp_enqueue_script()` for JavaScript
   - Use `wp_register_style()` and `wp_enqueue_style()` for CSS
   - Never include inline styles or scripts unless absolutely necessary
   - Set proper dependencies and versions

## Security Best Practices

10. Always validate, sanitize, and escape data:
    - Sanitize input: `sanitize_text_field()`, `sanitize_email()`, etc.
    - Validate data types and ranges
    - Escape output: `esc_html()`, `esc_attr()`, `esc_url()`
    - Follow the pattern: "Sanitize early, validate thoroughly, escape late"

11. Implement proper nonces for all form submissions and AJAX requests:
    - Generate nonces with `wp_create_nonce()`
    - Verify with `wp_verify_nonce()`
    - Include nonce fields with `wp_nonce_field()`

12. Check user capabilities before performing actions:
    - Use `current_user_can()` for permission checks
    - Combine with nonce verification for secure operations

13. Prepare all SQL queries:
    - Use `$wpdb->prepare()` for queries with variables
    - Never concatenate variables directly into SQL

## Performance and Resource Usage

14. Use WordPress transients or object cache for expensive operations:
    - `set_transient()` and `get_transient()` for temporary data
    - Define reasonable expiration times

15. Load assets only when needed:
    - Register all assets but only enqueue on specific pages
    - Use conditional logic to determine when to load

16. Implement proper database architecture:
    - Use `dbDelta()` for creating/updating tables
    - Include indexes for frequently queried columns
    - Follow WordPress table naming: `{$wpdb->prefix}your_table_name`

## Internationalization and Accessibility

17. Make all user-facing strings translatable:
    - Use `__()`, `_e()`, `esc_html__()`, `esc_html_e()` functions
    - Include text domain matching the plugin slug
    - Load text domain with `load_plugin_textdomain()`

18. Follow accessibility best practices:
    - Use semantic HTML elements
    - Implement proper ARIA attributes
    - Ensure keyboard navigation works
    - Maintain sufficient color contrast

## Data Handling and Privacy

19. Respect user privacy and GDPR compliance:
    - Document all data collection in the readme.txt
    - Provide data export and erasure methods
    - Implement properly with the Privacy API if storing user data
    - Integrate with `wp_privacy_personal_data_exporters` and `wp_privacy_personal_data_erasers`

20. Disclose third-party service usage:
    - Document all external API connections
    - Detail what data is sent and when
    - Include links to terms and privacy policies of external services

## Error Handling and Debugging

21. Implement proper error handling:
    - Use try/catch blocks for expected exceptions
    - Log errors appropriately, not to screen
    - Return WP_Error objects for API functions

22. Add debug logging:
    - Use `WP_DEBUG_LOG` compatible logging
    - Conditional debug output based on `WP_DEBUG`
    - Make logs human-readable

## Plugin Submission and Documentation

23. Include comprehensive readme.txt with:
    - Clear description
    - Proper installation instructions
    - Changelog
    - FAQ section
    - Screenshots
    - External service documentation if applicable
    - Stable tag matching version

24. Maintain code quality:
    - Use PHPDoc comments for classes and functions
    - Comment complex operations
    - Follow PSR-1/PSR-2 or WordPress Coding Standards

## External Service Integration

25. When connecting to external services:
    - Always use API keys stored securely
    - Implement proper error handling for API failures
    - Cache responses when appropriate
    - Document fully in readme.txt what data is sent/received

26. Include fallbacks when external services are unavailable

## Updates and Compatibility

27. Test thoroughly with:
    - Latest WordPress version
    - Popular plugins for compatibility
    - Multiple PHP versions (7.4+ recommended)
    - Different server environments

28. Implement proper upgrade routines:
    - Use version comparison for update logic
    - Include database migration functions when needed
    - Preserve user settings during updates