Build Your First WordPress Plugin with The Power of AI (Even if You Can’t Code!)

I have a WordPress plugin idea I'd like to develop. Here's my initial concept:

---

{{_IDEA_}}

---

I'm looking to collaborate with you to turn this into a detailed plugin request. Let's iterate together until we have a complete request that I find to be complete.

After each of our exchanges, please return the current state of the request in this format:

```request
# Plugin Name
## Plugin Description
[Description]

## Target Audience
[Target users]

## Desired Features
### [Feature Category]
- [ ] [Requirement]
    - [ ] [Sub-requirement]

## Design Requests
- [ ] [Design requirement]
    - [ ] [Design detail]

## Other Notes
- [Additional considerations]
```

Please:
1. Ask me questions about any areas that need more detail
2. Suggest features or considerations I might have missed
3. Help me organize requirements logically
4. Show me the current state of the spec after each exchange
5. Flag any potential technical challenges or important decisions

We'll continue iterating and refining the request until I indicate it's complete and ready.

Help me write a comprehensive, detailed project rules that I can used for Cursor AI. This project rules is building a WordPress plugin.

This project rules should follow the native WordPress plugin development coding standard, and sticking to core WordPress methodologies. This native approach avoids modern PHP features like Composer-based autoloading, namespaces, MVC approach, or advanced package management.

Here are some details about Cursor Project rules:

```
Rules for AI
Guide to customizing AI behavior in Cursor using project-specific and global rules for model responses

Using rules in Cursor you can control the behavior of the underlying model. You can think of it as instructions and/or a system prompt for LLMs.

Inside Cursor, we have two main ways to customize the behavior of the AI to suit your needs:

Project Rules
Rules specific to a project, stored in the .cursor/rules directory. They are automatically included when matching files are referenced.

Global Rules
Rules applied globally to all projects, configured in the Cursor Settings > General > Rules for AI section.

Learn more about how to use them in the following sections.

Project Rules (recommended)

Project rules offer a powerful and flexible system with path specific configurations. Project rules are stored in the .cursor/rules directory and provide granular control over AI behavior in different parts of your project.

Here’s how they work

- Semantic Descriptions: Each rule can include a description of when it should be applied
- File Pattern Matching: Use glob patterns to specify which files/folders the rule applies to
- Automatic Attachment: Rules can be automatically included when matching files are referenced
- Reference files: Use @file in your project rules to include them as context when the rule is applied.

Example use cases:

- Framework-specific rules for certain file types (e.g., SolidJS preferences for .tsx files)
- Special handling for auto-generated files (e.g., .proto files)
- Custom UI development patterns
- Code style and architecture preferences for specific folders

```

You can refer to this directory for examples of cursor project rules: [https://cursor.directory/rules](https://cursor.directory/rules)

# Global WordPress Standards and Best Practices (`wordpress-general.mdc`)

```
---
description: Enforce WordPress coding standards and best practices for all plugin files
globs:
  - "**/*"
alwaysApply: true
---

## Recommended project structure
```
my-plugin/
├─ my-plugin.php            ← Main plugin bootstrap (contains header)
├─ readme.txt               ← WordPress.org–style read‑me (optional)
├─ uninstall.php            ← Clean‑up on uninstall (optional)
├─ admin/                   ← Dashboard‑only code (menus, settings pages, notices)
├─ frontend/                ← Public‑facing features (shortcodes, blocks, templates)
├─ includes/                ← Core logic, helpers, custom post‑type/classes
├─ assets/
│  ├─ css/                  ← Stylesheets loaded via wp_enqueue_style
│  ├─ js/                   ← Scripts loaded via wp_enqueue_script
│  └─ images/               ← Icons or other media
└─ languages/               ← .pot / .po / .mo translation files
```

> **Why this layout?**  
> • Keeps admin, frontend, and shared logic isolated, mirroring WordPress’s own separation.  
> • Simplifies conditional loading (e.g., enqueue assets only where needed).  
> • Helps maintain predictable paths for Cursor’s glob rules (`admin/**`, `frontend/**`, etc.).  

---

- **Follow official WordPress Coding Standards** for PHP, JS, HTML, and CSS (tabs for indentation, brace style, no trailing whitespace, descriptive names).
- **Avoid modern PHP features** (Composer autoloaders, namespaces, traits, MVC frameworks). Use procedural functions or classic classes with a unique prefix.
- **Never modify WordPress core files.** Hook into WordPress via `add_action`/`add_filter`. Execute plugin logic only through hooks or on activation / deactivation.
- **Use core APIs** (Settings API, REST API, WP Cron, `$wpdb` with prepared statements, `wp_remote_get`, etc.) instead of reinventing functionality.
- **Internationalize everything.** Wrap user‑facing strings in `__()`, `_e()`, `_n()`, etc., with a single text domain that matches the plugin slug.
- **Escape output & sanitize input** (`esc_html()`, `esc_attr()`, `sanitize_text_field()`, etc.) to prevent XSS and SQLi.
- **Prefix every global** (functions, classes, constants, option keys) with a unique plugin slug (e.g. `myplugin_`).
- **Standard plugin header** and `ABSPATH` check in every PHP entry file (e.g. `if ( ! defined( 'ABSPATH' ) ) exit;`).
- **Keep code modular**; include files from `includes/` as needed with `require_once`, but avoid side‑effects inside those include files.
- **Test with `WP_DEBUG` on**, resolve notices/warnings, and document complex functions with PHPDoc.
```

# Admin Area Code (`wordpress-admin.mdc`)

```
---
description: Guidelines for WordPress plugin admin (dashboard) code and functionality
globs:
  - "admin/**"
---

- Admin code should run **only in the WordPress admin context**. Use `is_admin()` or admin-specific hooks to ensure code only executes in the dashboard (e.g. hook into `admin_menu` to add admin pages, `admin_init` for initialization).
- Use the **Settings API** for admin settings pages (e.g. `register_setting()`, `add_settings_section()`, `add_settings_field()`) instead of creating custom form handlers from scratch. This ensures settings are handled consistently by WordPress.
- When adding admin menu items or pages, use `add_menu_page()`/`add_submenu_page()` and related functions. Follow WordPress UI patterns and leverage core styles (use built-in CSS classes) for a native look and feel.
- **Validate user capabilities and intents**: wrap admin functionality with permission checks like `current_user_can()` and use nonces for actions. For example, use `wp_nonce_field()` in forms and `check_admin_referer()` to verify requests, preventing CSRF.
- If your plugin outputs lists or tables in WP Admin, consider using `WP_List_Table` for a consistent, accessible listing interface.
- Enqueue admin-only scripts/styles with the proper hook (`admin_enqueue_scripts`). Do not load plugin assets on every admin page unnecessarily; target your plugin’s pages or specific screens (check `get_current_screen()` if needed).
- Keep the admin code organized: separate display logic from processing logic. For complex HTML forms or layouts, consider moving HTML into include templates and output them via functions, while keeping business logic in PHP.
- Ensure any admin notices, messages, or outputs are translatable and escape all output (use `esc_html__()` for admin text, etc.). Follow the WordPress admin color schemes and icon guidelines if adding custom icons.

```

# Frontend/Public-Facing Code (`wordpress-frontend.mdc`)

```
---
description: Guidelines for WordPress plugin public-facing (frontend) functionality
globs:
  - "frontend/**"
---

- Frontend code should integrate smoothly with the theme and site. Use WordPress **template tags and hooks** rather than direct HTML when possible (e.g. filter `the_content` or use `shortcode` outputs to inject plugin content).
- Provide features via **shortcodes or other pluggable methods** for users to embed plugin functionality. For example, use `add_shortcode()` to register shortcodes that render your plugin’s output. Document their usage for end-users.
- Enqueue all public scripts and styles in the appropriate hook (`wp_enqueue_scripts`). Do not print raw `<script>` or `<link>` tags in HTML; use `wp_enqueue_script()`/`wp_enqueue_style()` with proper dependencies and in-footer loading as needed.
- Ensure output is safe and escapable: never output user data without escaping. Use `esc_html()`, `esc_attr()`, etc. when printing to the frontend. For URLs, use `esc_url()` and for HTML fragments use `wp_kses_post()` if needed.
- Keep frontend performance in mind: only query necessary data (use WP_Query efficiently with caching if appropriate) and avoid heavy computations in templates. Leverage WordPress caching APIs (transients, object cache) when storing expensive results.
- Make your plugin’s frontend output **responsive and accessible**. Use semantic HTML and include ARIA labels or roles if needed. Follow WordPress Theme Review guidelines for front-end output (e.g. no hard-coded inline styles that can't be overridden).
- Avoid conflicts with themes and other plugins: use unique CSS selectors or a specific namespace for your plugin’s CSS, and avoid globally enqueuing scripts that could clash (wrap your JS in a closure or use WordPress’s no-conflict handling for jQuery).

```

# Core Plugin Logic and Includes (`wordpress-includes.mdc`)

```
---
description: Guidelines for shared core logic and helper includes in the plugin
globs:
  - "includes/**"
---

- Use the `includes/` directory for shared classes, utilities, and core functions of your plugin. These files contain the business logic and should be loaded by the main plugin file as needed (e.g. via `require_once`).
- **Do not execute code in include files at load time** (other than function and class definitions). Any functional code (like hooking into actions) should be called from the main plugin file or an initialization function, not run automatically when the file is included.
- Structure your code into reusable functions or classes. It’s fine to define classes in includes (for example, a class handling a custom post type), but avoid namespaces – instead, prefix class names (e.g. `My_Plugin_Helper`) to prevent collisions.
- Leverage WordPress core APIs within your logic: for database interactions use the `$wpdb` object or WP functions, for custom post types use `register_post_type()`, for scheduling use WP Cron (wp_schedule_event), etc., rather than custom implementations.
- If your plugin defines custom REST API endpoints, register them via `register_rest_route()` in an initialization hook (e.g. `rest_api_init`), and keep the callback implementations in this includes folder. Similarly, if defining a widget, extend `WP_Widget` in includes and register it on the `widgets_init` hook.
- Keep functions focused and documented. Follow WordPress PHP coding style in these files (including Yoda conditions, spacing, etc.). Provide PHPDoc comments for complex functions or classes to describe their purpose.
- The includes should be logically organized (you can create sub-folders if necessary, e.g. `includes/api/`, `includes/helpers/`). Each file should generally encapsulate a specific piece of functionality (one class or a set of related functions).

```

# Assets (JavaScript, CSS, Images) (`wordpress-assets.mdc`)

```
---
description: Guidelines for static assets (JS, CSS, images) used by the plugin
globs:
  - "assets/**"
---

- Organize front-end assets in this directory (e.g. put CSS, JS, images in subfolders like `assets/css/`, `assets/js/`, etc.). Use WordPress functions to load them rather than hard-coding paths.
- **JavaScript**: Follow WordPress JavaScript Coding Standards. For example, use single quotes for strings, indent with tabs, and name variables descriptively. Avoid polluting global namespace; wrap your code in an IIFE or module pattern. If using jQuery, use it in no-conflict mode (WordPress includes jQuery by default) — e.g. wrap your script with `(function($){ ... })(jQuery);`.
- **CSS**: Adhere to WordPress CSS Coding Standards (proper commenting, one rule per line, etc.). Use class names that are unlikely to conflict (perhaps prefix with your plugin or unique identifier). Avoid !important if possible to let themes override styles if needed.
- Enqueue asset files through PHP: e.g. call `wp_enqueue_script()` for your `assets/js` files and `wp_enqueue_style()` for `assets/css` files, usually in the plugin’s init or specific hook. Specify dependencies (like jQuery) and version numbers (possibly use plugin version) for cache busting.
- If your build process generates minified files, load those in production (and handle dev vs prod if applicable). However, a simple plugin can be written with plain JS/CSS without a complex build pipeline, to align with WordPress’s preference for simplicity.
- Load assets conditionally: only on pages where needed. For example, if your script is only used on a shortcode or a particular page, use `wp_enqueue_script` inside that shortcode handler or on specific conditionals, so it doesn’t load site-wide unnecessarily.
- Ensure any images or media in assets are properly referenced and used. For example, if you have icons or images, use functions like `plugins_url()` or `plugin_dir_url(__FILE__)` to get the correct path to assets in your code.

```

# Internationalization and Localization (`wordpress-i18n.mdc`)

```
---
description: Ensure all user-facing text is internationalized (translatable) and localized properly
globs:
  - "languages/**"
---

- All user-facing strings in the plugin **must be wrapped in translation functions**. Use `__()` for returning translated text, `_e()` for echoing text, `_n()` for plural forms, and `_x()` or `_ex()` when context is needed. Example: `__('Hello World', 'your-plugin-textdomain')`.
- Maintain a consistent **text domain** for your plugin. The text domain should match the plugin’s slug (and the one declared in the plugin header). Every translation function call should include this exact text domain string.
- Include a `languages/` folder with a `.pot` file (translation template). Update the `.pot` file whenever strings change, so translators can create `.po` and `.mo` files for their language. In the plugin header, declare `Domain Path: /languages` so WordPress knows where to find translations.
- **Load the text domain** on plugin initialization. Call `load_plugin_textdomain( 'your-plugin-textdomain', false, dirname( plugin_basename(__FILE__) ) . '/languages' );` in an early hook (e.g. `plugins_loaded`) to make sure translations are available.
- Avoid string concatenation that would make translation difficult. Instead, use placeholders and `sprintf()` or `number_format_i18n()` for variables within translatable strings. E.g., `sprintf( __('Hello %s', 'your-plugin-textdomain'), $username )`.
- Provide translator comments where needed for clarity. For example, above a complex string you can add `// translators: %s is the username` to help translators understand context.
- Ensure locale-specific formatting is considered. Use date and time functions that respect WordPress locale (like `date_i18n()` for dates) and number formatting functions for numbers/prices in output.

```

Each of these rule files should be placed in the `.cursor/rules` directory of your WordPress plugin project. With these rules in place, the Cursor AI assistant will consistently follow WordPress’s native development practices, adhere to coding standards, utilize core APIs correctly, and handle internationalization properly across your plugin. This helps maintain a high-quality codebase that is in line with WordPress community best practices.

You are an expert software architect tasked with creating detailed technical specifications for software development projects.

Your specifications will be used as direct input for planning & code generation AI systems, so they must be precise, structured, and comprehensive.

First, carefully review the plugin requirements:

<plugin_requirements>
{{_REQUIREMENTS_}}
</plugin_requirements>

Next, carefully review the WordPress plugin guidelines:

<wp_plugin_guidelines>
{{_RULES_}}
</wp_plugin_guidelines>

Your task is to generate a comprehensive technical specification for a WordPress plugin based on all the above information.

Before creating the final specification, analyze the project requirements and plan your approach. Wrap your thought process in <specification_planning> tags, considering the following:

1. **Core Plugin Architecture & Key Workflows**
   - Overview of what the plugin does and how it integrates with WordPress.
   - Any custom post types, taxonomies, or database interactions.
   - Activation/deactivation/uninstall flows.

2. **Plugin Folder Structure & Organization**
   - How files and directories will be arranged (admin, public, includes, etc.).
   - References to the main plugin file, admin partials, public-facing templates, etc.

3. **Detailed Feature Specifications**
   - Each key feature should have user stories, implementation steps, hooks used, and any relevant admin/public UI components.

4. **Database Schema (if applicable)**
   - Description of custom tables (if needed).
   - MySQL vs. SQLite compatibility strategies (if applicable).
   - Data validation and sanitization.

5. **WordPress Actions, Filters & Hook Implementations**
   - Which hooks (actions/filters) are used or created by the plugin.
   - Purpose and flow for each.

6. **Admin Settings & UI**
   - Usage of the WordPress Settings API.
   - Menu page structure.
   - Enqueueing admin assets.

7. **Public-Facing UI (if applicable)**
   - Templates or shortcodes.
   - Enqueueing CSS/JS for the front-end.
   - Any public endpoints or custom routes.

8. **Security & Capability Checks**
   - Nonce usage.
   - Sanitization and escaping.
   - Role/capability checks for admin actions.

9. **Internationalization & Localization**
   - How text domains and translation files are set up.

In your analysis, be sure to:
- Break down complex features into step-by-step flows.
- Identify areas that require further clarification or have potential risks.
- Propose solutions or alternatives for any identified challenges.

After your analysis, generate the technical specification in **Markdown** using the structure below. Make sure the details align with WordPress plugin best practices:

```markdown
# "{Project Name}" WordPress Plugin Technical Specification

## 1. System Overview
- Core purpose and value proposition
- Key workflows
- High-level plugin architecture

## 2. Plugin Folder Structure
- Directory layout (admin, includes, public, etc.)
- Key files and their responsibilities

## 3. Feature Specification
For each feature:
### 3.1 Feature Name
- User story and requirements
- Implementation steps (hooks, functions, UI changes)
- Error handling and edge cases

## 4. Database Schema (if applicable)
### 4.1 Tables
For each table:
- Complete table schema (field names, types, constraints)
- Relationships and indexes
- MySQL/SQLite compatibility considerations (if relevant)

## 5. WordPress Hooks & Actions
### 5.1 Custom Actions / Filters
- Detailed description of each custom action/filter
- Input parameters and return values
- Usage examples

### 5.2 Core WordPress Hooks Utilized
- Explanation of how and why these hooks are being used
- Examples of callback functions

## 6. Admin Settings & UI
- Settings page structure (menu, sub-menu)
- WordPress Settings API usage
- Enqueueing admin assets (CSS/JS)
- Access control (capabilities)

## 7. Public-Facing Functionality
- Shortcodes, template tags, or public-facing pages
- Enqueueing front-end assets (CSS/JS)

## 8. Security & Capability Checks
- Nonce usage
- Sanitization and escaping patterns
- Role/capability verification

## 9. Internationalization
- Text domain configuration
- .po/.mo file placement
- Steps to generate translation files

```

Ensure that your specification is **extremely detailed**, providing specific implementation guidance wherever possible. Include concrete code snippets for complex features and clearly define any interfaces between components (e.g., how data flows between admin forms and the database).

Begin your response with your <specification_planning> analysis, then proceed with the complete Markdown technical specification. Once you are done, this document will be passed to the AI code planning system for implementation.

You are an AI task planner responsible for breaking down a complex WordPress plugin development project into manageable steps.

Your goal is to create a detailed, step-by-step plan that will guide the code generation process for building a fully functional WordPress plugin based on a provided technical specification.

First, carefully review the following inputs:

<plugin_requirements>
{{_REQUIREMENTS_}}
</plugin_requirements>

<wp_plugin_guidelines>
{{_RULES_}}
</wp_plugin_guidelines>

<technical_specification>
{{_SPECS_}}
</technical_specification>

After reviewing these inputs, your task is to create a comprehensive, detailed plan for implementing the WordPress plugin.

Before creating the final plan, analyze the inputs and plan your approach. Wrap your thought process in <brainstorming> tags.

Break down the development process into small, manageable steps that can be executed sequentially by a code generation AI.

Each step should focus on a specific aspect of the plugin and should be concrete enough for the AI to implement in a single iteration. You are free to mix both admin and public tasks if they make sense together.

When creating your plan, follow these guidelines:

1. **Start with the plugin folder structure** and essential WordPress configurations (plugin header, main plugin file).
2. **Progress through database schema** setup if needed (custom tables), along with the hooks or functions to manage plugin activation, deactivation, and uninstall.
3. **Move on to shared functionalities** in the `includes` directory, such as helper functions or hooks implementations.
4. **Break down the implementation of admin pages** (settings screens, custom post types, etc.) and any public-facing features into smaller, focused steps.
5. **Include steps for integrating** custom capabilities, roles, security checks (nonces, sanitization, escaping), and any other WordPress APIs.
6. **Incorporate steps for enqueuing assets** (CSS/JS) in both admin and public contexts.
7. Ensure that **each step** is atomic and self-contained enough to be implemented in a single code generation iteration. Each step should modify **no more than 20 files** at once (ideally fewer) to keep changes manageable. Be sure to include instructions for any manual tasks the user must perform (e.8., running SQL scripts, updating environment variables, etc.).

Present your plan using the following markdown-based format. This format is designed to integrate with the subsequent code generation phase, where an AI will systematically implement each step and mark it as complete. **Each step must be atomic** and self-contained:

```md
# Implementation Plan

## [Section Name]
- [ ] Step 1: [Brief title]
  - **Task**: [Detailed explanation of what needs to be implemented]
  - **Files**: [Maximum of 20 files, ideally less]
    - `path/to/file1.php`: [Description of changes]
  - **Step Dependencies**: [List any previous step(s) that must be completed before this step]
  - **User Instructions**: [Any manual instructions for the user, if applicable]

[Additional steps...]
```

After presenting your plan, provide a **brief summary** of the overall approach and any key considerations for the implementation process, such as security, localization, or potential risks.

Remember to:
- Ensure that your plan covers all aspects of the **WordPress plugin** technical specification.
- Break down complex features (e.g., custom admin pages, database interactions) into smaller, manageable tasks.
- Consider the **logical order** of implementation, ensuring that hooks, data structures, and dependencies are addressed in the correct sequence.
- Include steps for **error handling, data validation, and edge case** management.
- Reference **WordPress best practices** for hooks (actions/filters), capability checks, i18n, enqueuing scripts/styles, and so on.

Begin your response with your <brainstorming> analysis, then proceed to create your detailed implementation plan for the WordPress plugin based on the provided specification.

Once you are done, we will pass this specification to the AI code generation system.

Your task is to systematically implement each step of the plan, one at a time.

First, carefully review the following inputs:

{{_INPUTS_}}

Then, implement the following steps:

{{_STEP_}}

The implementation plan is a high-level guide. Use it to shape your approach, but you do not have to follow it strictly. However, you must adhere to the specified **WordPress plugin** rules, guidelines, and technical requirements.

### Documentation Requirements

-   **File-level documentation**: Purpose and scope of each file
-   **Function-level documentation**: Inputs, outputs, and logic flow
-   **Inline comments**: For complex logic or essential WordPress considerations (e.g., nonce checks, hooks usage)
-   **Edge cases and error handling**: Address potential pitfalls and how you are handling them
-   **Notes**: Any assumptions or limitations

### Guidelines

1. **Implement exactly one step** at a time from the plan.
2. Ensure all code follows **WordPress plugin best practices** and the provided technical specification.
3. Include **all necessary imports** (e.g., `require_once` or WordPress function calls).
4. Write clean, well-documented PHP code with appropriate **WordPress coding standards** (4 spaces indentation, prefixed function names, etc.).
5. **Always provide the entire file contents**—avoid ellipses or placeholders.
6. Handle edge cases: Nonce checks, validation, and escaping where appropriate (e.g., `sanitize_text_field()`, `esc_html()`).
7. **Follow the security guidelines**: capabilities checks, nonces, sanitization, prepared statements when interacting with the database.
8. Include or update **tests** (PHPUnit, if specified in the plan) or demonstration code for your plugin as needed.
9. Use **prefixed** function names and constants (e.g., `my_plugin_`) to avoid naming collisions.
10. **Type Declarations**: If employing any advanced static analysis or using typed PHP, ensure correctness. Otherwise, ensure thorough docblocks for clarity.
11. **Begin by identifying** the next incomplete step from the plan, then generate the required code.
12. Above each file’s XML entry, provide a summary titled: "**Here's what I did and why**".
13. End your overall response with:
    - "**STEP X COMPLETE. Here's what I did and why:**" – Summarize your changes
    - "**USER INSTRUCTIONS**: Please do the following:" – Provide instructions for any manual tasks needed (e.g., activating the plugin, updating WordPress settings, running SQL queries in the database, etc.).
14. If you **update the implementation plan**, append the updated steps as Markdown code blocks after the user instructions.

This structure ensures your code is clearly delineated, documented, and ready to be tested or merged into the ongoing **WordPress plugin** development process