Category: Code Generation with AI

I want to learn how to build a AI Chat web app using React and Firebase.

Here's the tech stack I want to used:

Frontend: 

- React 18 (typescript) with Vite: For building the user interface.
- React Router v6: For client-side routing.
- React useContext: For context and global state management.
- Shadcn UI: For building the UI components.
- Tailwind CSS: For styling components.
- Framer Motion: For animations and transitions.
- Lucide React: For icons.
- Sonner: For displaying toast notifications.

Backend: 

- Firebase: For database and backend logic.
- Firebase Firestore: For database.

AI Integration:

- Firebase AI Logic: For calling the Gemini AI API via Firebase JS SDK.

Authentication:

- Firebase Auth: For authentication for both frontend and backend. The frontend will use the Firebase JS SDK (modular) and the backend will use the Firebase Admin SDK.

Note that this AI Chat web app is frontend only app. No backend server. We will be using Firebase Auth for authentication. 

Firestore is used for storing the user's messages and the AI's responses. Since there is no backend server, we will need to setup a strong security rules for the Firestore database so that only the authenticated users can access their own data and not other users' data. We need to make this as secure as possible.

As for the AI part, we will be using Firebase AI Logic so that we don't need to have a backend to call the Gemini API. We will be using the Firebase JS SDK to call the Gemini API.

Help me compile a detailed and comprehensive step-by-step guide on how to do this. 

Make sure to use the latest information only. 

The guide needs to start from the beginning and end with the advanced stuff.

{{_GUIDE_HERE_}}

===============================================

Based on the guide above, help me do a research and create a project rules document for a project to create a Frontend only web application using React and supported Firebase services for authentication, database, and AI services.

You need to keep the project rules document generic so that it can be used for any type of web application.

I have a frontend-focused web app idea I'd like to develop using React with Vite for the frontend and Firebase services for the backend infrastructure. 

Here's my initial concept:

-----
{{_IDEA_}}
-----

I'm looking to collaborate with you to turn this into a detailed project request. As we develop this project, I want you to:

1. Use web_search tools if you need more information to clarify the request
2. If the project involves rich text editing with TipTap, use the docs-mcp server to gather information:
   - Call list_doc_sources tool to get the available llms.txt file
   - Call fetch_docs tool to read it
   - Reflect on the URLs in llms.txt
   - Reflect on the input question
   - Call fetch_docs on any URLs relevant to the question
   - Use this information to provide comprehensive TipTap implementation guidance
3. Document which sources were used for each finding
4. Help me craft optimal solutions following the project rules.

Let's iterate together until we have a complete request that I find to be comprehensive and well-architected.

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

```request
# Project Name
## Project Description
[Description]

## Target Audience
[Target users]

## Research Findings
### Documentation References
- [ ] [Key documentation reference]
    - [ ] [Relevant details from documentation]
### Best Practices
- [ ] [Researched best practice]
    - [ ] [Implementation consideration]

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

## UI/UX Design Concept
### Visual Design
[Describe the overall visual aesthetic, color schemes, typography choices, and design philosophy. Include references to modern design trends like glassmorphism, dark mode preferences, micro-animations, etc.]

### Layout Structure
[Detail the main layout components including navigation patterns, responsive breakpoints, sidebar/header arrangements, and how content areas are organized]

### User Flow
[Explain the primary user journeys through the application, from entry points to key actions, including authentication flows, onboarding sequences, and task completion paths]

### Interactive Elements
[Describe hover states, transitions, loading states, error states, and micro-interactions that enhance the user experience]

### Accessibility Considerations
[Outline ARIA labels, keyboard navigation support, color contrast requirements, and other accessibility features]

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

## Type Definitions
### User Types
- User
  - uid: unique identifier
  - email: user email address
  - displayName: optional display name
  - photoURL: optional profile photo URL
  - role: user role (user, admin, etc.)
  - createdAt: timestamp of account creation
  - [additional user fields]

### [Feature Entity Types]
- [EntityName]
  - id: unique identifier
  - [field]: [description and constraints]
  - [field]: [description and constraints]
  - createdAt: timestamp
  - updatedAt: timestamp

### [Additional Entity Types]
- [EntityName]
  - [field]: [description and constraints]
  - [relationships to other entities]

### Enums and Constants
- [EnumName]
  - [VALUE]: [description]
  - [VALUE]: [description]

## Technical Requirements
### Frontend (React/Vite)
- [ ] [Implementation requirement]
    - [ ] [Specific feature to utilize]

### Firebase Services Architecture
- [ ] [Firestore Database Design]
    - [ ] [Collection structure]
    - [ ] [Document schema]
- [ ] [Firebase Authentication]
    - [ ] [Auth providers to implement]
    - [ ] [User profile management]
- [ ] [Firebase Storage]
    - [ ] [File types and organization]
- [ ] [Firebase AI Logic/Gemini API]
    - [ ] [AI features to implement]
- [ ] [Security Rules]
    - [ ] [Firestore rules]
    - [ ] [Storage rules]

### State Management
- [ ] [React Context providers needed]
    - [ ] [Custom hooks to create]

### Cloud Functions (Background Only)
- [ ] [Authentication triggers]
- [ ] [Firestore triggers]
- [ ] [Scheduled functions]

## Project Structure
- [ ] [Folder organization following the recommended structure]
- [ ] [Key files and their purposes]

## Performance & Security Considerations
- [ ] [Performance optimizations]
- [ ] [Security measures]
- [ ] [Cost optimization strategies]

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

Please:
1. Use web_search tool if you need more information to clarify the request
2. For TipTap or other rich text editing needs, use the docs-mcp server as described above
3. Ask me questions about any areas that need more detail
4. Suggest features or considerations I might have missed, based on your research
5. Show me the current state of the spec after each exchange
6. Flag any potential technical challenges or important decisions regarding:
   - React 19+ implementation with concurrent features
   - Firestore database design and denormalization strategies
   - Real-time data synchronization patterns
   - Authentication flow with multiple providers
   - AI integration with Firebase AI Logic/Gemini API
7. Recommend appropriate UI/UX features using Shadcn UI and Tailwind CSS, ensuring the design creates an engaging, modern experience
8. Advise on best practices for Firebase implementation including:
   - Optimal Firestore data structure for minimizing reads
   - Security rules that enforce data integrity
   - Cloud Functions usage (remember: background triggers only, no REST APIs)
   - File storage organization and optimization
   - Cost-effective query patterns
9. Suggest project structure that follows the frontend-first architecture principles
10. Define comprehensive type structures that support TypeScript's strict mode and enable excellent developer experience

We'll continue iterating and refining the request until I indicate it's complete and ready. I want to ensure the project leverages Firebase's strengths like:
- Real-time data synchronization with Firestore
- Comprehensive authentication with multiple providers
- Serverless backend with Cloud Functions (for background tasks only)
- Integrated AI capabilities with Gemini API
- Robust security with Firebase Security Rules
- File storage with automatic CDN distribution
- Frontend-first architecture with minimal backend complexity

Let's start by discussing my concept and identifying the key components that would benefit from Firebase's services while maintaining a simple, frontend-focused architecture.

Based on the requirements and the project rules, give me the whole Firestore Schema and its security rules (put this in one artifact). Then, give me the complete user journey flow for this web app (put this in another artifact).

Help me update the Project requirements by adding in the complete recommended project structure

First, read the following files:

- @notes/rules.md
- @notes/requirements.md
- @notes/user_journey.md
- @notes/firestore_schema.md

Then, think hard about the project, and craft a plan to create a complete, production-ready HTML UI design based on the provided project specification. The HTML will eventually be converted to a React application, so include appropriate annotations.

## Instructions:

### 1. Project Analysis

**Carefully analyze the project specification** including:

- Project description and target audience
- Desired features and functionality
- UI/UX design concepts and requirements
- Technical requirements and architecture
- User journey and workflows
- Data types and structures

### 2. File Organization

**Create multiple HTML files** organized as follows:

#### File Structure:
```

│ ├── pages/ # Page components
│ │ ├── landing-page.tsx
│ │ ├── login-page.tsx
│ │ ├── signup-page.tsx
│ │ ├── dashboard-page.tsx
│ │ ├── new-session-page.tsx
│ │ ├── review-session-page.tsx
│ │ ├── session-history-page.tsx
│ │ ├── session-detail-page.tsx
│ │ ├── categories-page.tsx
│ │ └── not-found-page.tsx

```

#### Naming Conventions:
- Use lowercase with hyphens for file names (e.g., `user-profile.html`, `category-management.html`)
- Name files based on their primary function or feature
- Keep names concise but descriptive

#### When to Split Files:
- Create separate files for distinct user flows
- Split when a page has fundamentally different layout/navigation
- Separate authenticated vs. non-authenticated views
- Isolate complex features that would make a single file unwieldy
- Consider creating 3-8 HTML files for a typical application

### 3. Cross-File Considerations
- Include navigation links between pages using standard `<a href="...">` tags
- Maintain consistent header/navigation across files
- Use the same CDN links and base styles in each file
- Include comments indicating which page links to which
- Add `<!-- @ROUTE: /path/to/page -->` annotations for React Router planning

### 4. Technology Stack
**Use the following technologies in each file**:
- Tailwind CSS (via CDN) for styling
- Font Awesome icons (via CDN) for iconography
- Modern semantic HTML5
- Vanilla JavaScript for interactions (can be shared via `<script>` tags)
- Custom CSS animations where appropriate

### 5. React Conversion Annotations
**Include these annotations throughout all files**:
- Mark components with `<!-- @COMPONENT: ComponentName [description] -->`
- Mark state with `<!-- @STATE: stateName:type = defaultValue -->`
- Mark events with `data-event="eventType:handlerName"`
- Mark data bindings with `data-bind="dataPath"`
- Mark mock data with `data-mock="true"`
- Mark lists with `<!-- @MAP: array.map(item => ( -->` and `<!-- @END_MAP )) -->`
- Add implementation notes with `data-implementation="description"`
- Add functionality notes with `<!-- @FUNCTIONALITY: description -->`
- Add route annotations with `<!-- @ROUTE: /path -->` at the top of each page

### 6. Component Sharing Strategy
For components that appear across multiple pages:
- Implement fully in the first occurrence
- In subsequent files, use simplified versions with a comment: `<!-- @COMPONENT_REF: ComponentName (see index.html) -->`
- This shows placement without duplicating complex code

### 7. Design Guidelines
**For each file, maintain**:
- Clean, modern interface that matches the project's tone
- Consistent spacing, typography, and color schemes
- Proper visual hierarchy
- Loading states, empty states, and error states where appropriate
- Smooth transitions and micro-interactions
- Accessibility with proper ARIA labels and semantic HTML

### 8. Required UI Elements
**Include across files as appropriate**:
- Navigation (consistent header/nav, contextual sidebars)
- Forms with validation states
- Buttons with hover/active states
- Cards, lists, and data displays
- Modals, dropdowns, and overlays (define once, reference elsewhere)
- Status indicators and progress bars
- Empty states and loading skeletons

### 9. JavaScript Functionality
**Organize JavaScript as follows**:
- Include page-specific JavaScript in each file
- For shared functionality, include a comment: `<!-- @SHARED_SCRIPT: functionality-name -->`
- Demonstrate interactions relevant to each page
- Show/hide modals and dropdowns
- Toggle states and UI elements
- Simulate data updates
- Handle responsive behavior

### 10. File-Specific Requirements

#### For index.html:
- Include global styles and configurations
- Define color schemes and CSS variables
- Show the main entry point or dashboard
- Include primary navigation structure

#### For auth.html:
- Login and signup forms
- Password reset flow
- Social authentication options
- Form validation examples

#### For feature pages:
- Focus on specific functionality
- Include relevant modals/overlays
- Show different states of the feature
- Include feature-specific navigation

### 11. Data Representation
**In each file**:
- Use realistic mock data relevant to that page
- Show different states (loading, success, error, empty)
- Demonstrate data relationships
- Include variety to show edge cases

### 12. Responsive Design
**Ensure each file has**:
- Mobile-first approach
- Proper breakpoints
- Touch-friendly interfaces
- Collapsible menus and adaptive layouts

### 13. Output Format

Here are the locations of the files that you will create:

- @notes/ui/landing-page.html
- @notes/ui/login-page.html
- @notes/ui/signup-page.html
- @notes/ui/dashboard-page.html
- @notes/ui/new-session-page.html
- @notes/ui/review-session-page.html
- @notes/ui/session-history-page.html
- @notes/ui/session-detail-page.html
- @notes/ui/categories-page.html
- @notes/ui/not-found-page.html

### 14. Quality Standards
Each HTML file should:
- Be a complete, valid HTML document
- Include all necessary meta tags and viewport settings
- Have organized, commented code
- Work independently while maintaining visual consistency
- Accurately represent the application's functionality
- Be detailed enough for straightforward React conversion

Remember: These HTML files collectively form a high-fidelity prototype that accurately represents the final application's look, feel, and functionality. They should be comprehensive enough that a React developer can understand the component structure, routing needs, and state management requirements for the entire application.

Based on the requirements, Firestore schema, user journey, proposed UI for this web app and the project rules, please create a detailed implementation plan for the project.
The implementation plan should focus on the following phrases:
0/ Project setup and configuration: 
    - In this phrase, we will setup the project, install the dependencies, and configure the project.
    
1/ App structure setup:
    - In this phrase, we will create the:
        - Folder structure and file organization
        - Setup the types and interfaces
        - Setup the utils and helpers in the lib folder
        
2/ Project hooks and context:
    - In this phrase, we will create the: 
        - Project hooks in the hooks folder 
        - Project context and providers in the context folder
        
3/ Project main layout and authentication components:
    - In this phrase, we will create the:
        - Project main layout in the components/layout folder
        - Project authentication components in the components/auth folder
        
4/ Project features and its components:
    - In this phrase, we will create the 
        - project features and its components in the components/{feature_name} folder
        
5/ Project pages:
    - In this phrase, we will create the:
        - Project pages in the pages folder
6/ Setup App.tsx:
    - In this phrase, we will create the:
        - App.tsx for the main app component. This is the entry point of the app. It should have all the providers, routes, and any other global setup needed.
        
7/ Cloud functions:
    - In this phrase, we will create the 
        - Cloud functions for the app in the functions folder. This will include all the background triggers, and the scheduled functions needed for the app.
The implementation plan should be in checklist format. No need to include any codes yet. However, you can include the file names, the folder names, what libraries to use or install, some code snippets (ONLY if you deem it absolutely necessary).
Put it in an artifact

Based on the @notes/plan.md , help me implement the below:

{{_STEP_}}

Now, think harder, plan properly, create a todo list, and then execute the tasks. Once you've done , please update the @notes/plan.md

if you are working on any UI component or page, make sure to read the UI design in @notes/ui/ first. For example:

- if you are working on the {{_PAGE_1_}} or its components, read the {{_PAGE_1_}}.html file.
- if you are working on the {{_PAGE_2_}} or its components, read the {{_PAGE_2_}}.html file.
- if you are working on the {{_PAGE_3_}} or its components, read the {{_PAGE_3_}}.html file.
- If you are working on the {{_PAGE_4_}} or its components, read the {{_PAGE_4_}}.html file.
...{{_CONTINUE_FOR_MORE_PAGES_}}

This is just reference, you don't need to follow it exactly. You should always prioritize using the shadcn ui components and the shadcn ui design system. Only if you are sure that the shadcn ui component is not available, you can create a custom component. If you need to create custom styling, please use tailwind css. Only use custom css if the styling you need cannot be achieved with tailwind css.

If you need any info about any libraries, sdk, or documentation, you can use web search to look for more information.

Lastly, please update the @CLAUDE.md file with the current context of the project.

# Context Prime

> Follow the instructions to understand the context of the project.

## Run the following command

eza . --tree -git-ignore --ignore-glob="node_modules|.git|tmp"

## Read the following files

> Read the files below and nothing else.

CLAUDE.md
notes/rules.md
notes/requirements.md
notes/user_journey.md
notes/firestore_schema.md
notes/plan.md

- Run `npm run lint` to check for linting errors
- If errors are found:
  a. Analyze each error type and location
  b. Read the affected files and understand the context
  c. Apply appropriate fixes based on ESLint rules
  d. Save the fixed files
  e. Re-run `npm run lint` to verify fixes
  f. Repeat this process until no errors remain
- Document any manual fixes that were needed

- Run `npx tsc --noEmit --project tsconfig.app.json` to check for TypeScript errors
- If errors are found:
  a. Analyze each TypeScript error carefully
  b. Read the affected files and understand the type issues
  c. Apply appropriate type fixes (add type annotations, fix type mismatches, etc.)
  d. Save the fixed files
  e. Re-run `npx tsc --noEmit --project tsconfig.app.json` to verify fixes
  f. Repeat this process until no errors remain
- You can ignore errors are primarily missing implementations rather than fundamental type conflicts.
- Document any complex type fixes applied

Analyze and think about what could be the potential problem, list down all the potential causes, single out the most likely cause of this issue, craft a plan on how to solve this, and then execute it.

in @{{_FILE_}}, I having issue of {{_ISSUE_}}. 

I want to {{_DESIRED_RESULT_}}. Please put console log across the file so that I can know exactly where went wrong.

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