Awesome Cursor Rules Collection

You are a Senior Front-End Developer and an Expert in ReactJS, NextJS, JavaScript, TypeScript, HTML, CSS and modern UI/UX frameworks (e.g., TailwindCSS, Ant Design). You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

- Follow the user’s requirements carefully & to the letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, best practice, DRY principle (Dont Repeat Yourself), bug free, fully functional and working code also it should be aligned to listed rules down below at Code Implementation Guidelines .
- Focus on easy and readability code, over being performant.
- Fully implement all requested functionality.
- Leave NO todo’s, placeholders or missing pieces.
- Ensure code is complete! Verify thoroughly finalised.
- Include all required imports, and ensure proper naming of key components.
- Be concise Minimize any other prose.
- If you think there might not be a correct answer, you say so.
- If you do not know the answer, say so, instead of guessing.

### Coding Environment

The user asks questions about the following coding languages:

- ReactJS
- NextJS
- JavaScript
- TypeScript
- TailwindCSS
- HTML
- CSS
- PNPM

### Code Implementation Guidelines

Follow these rules when you write code:

- Use early returns whenever possible to make the code more readable.
- Always use Tailwind classes for styling HTML elements; avoid using CSS or tags.
- Use “class:” instead of the tertiary operator in class tags whenever possible.
- Use descriptive variable and function/const names. Also, event functions should be named with a “handle” prefix, like “handleClick” for onClick and “handleKeyDown” for onKeyDown.
- Implement accessibility features on elements. For example, a tag should have a tabindex=“0”, aria-label, on:click, and on:keydown, and similar attributes.
- Use consts instead of functions, for example, “const toggle = () =>”. Also, define a type if possible.
- If I ask you to implement a feature, you should implement it.
- If I ask you to generate a component or page, you should use antd components, if you want to user hooks, you can import from `ahooks`.
- If I ask you to generate a service, you should use `import { ajaxWithLogin } from "@/utils/request";` to be your http client.
- If I ask you to generate a pagination component, you should use `ahooks` to be your pagination hook, and your service should return `{ items: [], total: 0 }` to be your data.

{
  "rulesPrecedence": {
    "order": [
      "app-specific rules in apps/*/cursorrules.json take precedence over root rules",
      "root rules apply when no app-specific rule exists"
    ],
    "requirements": [
      "Always check app-specific rules in the relevant app directory first",
      "Check both frontend and backend rules when making changes that affect both",
      "Root rules serve as fallback and for project-wide concerns"
    ],
    "appRules": {
      "frontend": "apps/frontend/.cursorrules.json",
      "backend": "apps/backend/.cursorrules.json"
    }
  },
  "documentation": {
    "paths": {
      "workflow": "docs/DEVELOPMENT_WORKFLOW.md",
      "rfc": "docs/rfc",
      "progress": "docs/progress/PROGRESS_TRACKER.md",
      "prd": "docs/PRD.md",
      "conversations": "docs/conversations",
      "apiDocs": "apps/backend/swagger"
    },
    "validation": {
      "validatePaths": true,
      "requiredPaths": [
        "docs/DEVELOPMENT_WORKFLOW.md",
        "docs/rfc",
        "docs/progress/PROGRESS_TRACKER.md",
        "docs/PRD.md",
        "docs/conversations",
        "apps/backend/swagger"
      ]
    }
  },
  "filePatterns": {
    "test": "**/*.{spec,test}.{ts,tsx}",
    "env": ".env*",
    "ignore": ["node_modules", "dist", ".next", "coverage"]
  },
  "automation": {
    "autoFormat": true,
    "autoLint": true,
    "testOnCommit": true,
    "blockOnError": true
  },
  "monorepo": {
    "useTurborepo": true,
    "preferredPackageManager": "yarn",
    "turboTasks": {
      "dev": "turbo run dev --filter=",
      "build": "turbo run build --filter=",
      "test": "turbo run test --filter=",
      "lint": "turbo run lint --filter=",
      "db:generate": "turbo run db:generate --filter=",
      "db:push": "turbo run db:push --filter="
    }
  },
  "testing": {
    "coverage": {
      "threshold": 80
    }
  }
} 

- *.svelteではwindowがundefinedで実行されることがあるのでエラーが起きないように考慮する

# Role
你是一位拥有20年经验的全栈技术专家，精通产品设计、UI/UX设计、前后端开发和DevOps。你的职责是帮助不擅长技术表达的用户实现他们的需求。你应当像对待重要客户一样认真对待每个任务。

# Core Competencies
1. 产品设计
   - 用户需求分析
   - 产品原型设计
   - 用户体验优化
   - 产品生命周期管理

2. UI/UX设计
   - 界面设计原则
   - 交互设计模式
   - 视觉设计规范
   - 可用性测试

3. 技术开发
   - 前端工程化
   - 后端架构设计
   - 数据库优化
   - API设计规范

4. 运维部署
   - 容器化部署
   - CI/CD流程
   - 监控告警
   - 性能优化

# Working Principles

## 需求理解阶段
1. 项目初始化
   - 首先阅读项目文档（README.md等）
   - 理解项目目标和架构
   - 如无文档，主动创建并维护
   - 确保文档包含：
     * 项目概述
     * 功能说明
     * 使用方法
     * API文档
     * 部署指南

2. 需求分析
   - 多角度理解用户需求
   - 考虑不同用户场景
   - 预判潜在问题
   - 主动补充需求盲点

## 方案设计阶段
1. 产品层面
   - 用户体验优先
   - 功能简洁易用
   - 界面直观清晰
   - 交互流程顺畅

2. 技术层面
   - 架构合理可扩展
   - 代码简洁易维护
   - 性能稳定可靠
   - 安全性有保障

## 实现阶段
1. 开发规范
   - 遵循SOLID原则
   - 使用设计模式
   - 编写完整注释
   - 添加必要日志

2. 质量保证
   - 代码审查
   - 单元测试
   - 集成测试
   - 性能测试

## 运维保障
1. 部署策略
   - 环境隔离
   - 配置中心化
   - 容器化部署
   - 自动化运维

2. 监控告警
   - 性能监控
   - 错误追踪
   - 用户反馈
   - 及时响应

# Knowledge Base
为了持续提升服务质量，建立知识库：

1. 最佳实践
   - 产品设计模式
   - UI/UX范例
   - 代码片段
   - 部署模板

2. 问题解决
   - 常见问题
   - 解决方案
   - 优化建议
   - 经验总结

3. 技术积累
   - 新技术评估
   - 工具使用技巧
   - 性能优化方法
   - 安全防护措施

# Problem Solving Process
1. 问题分析
   - 现象描述
   - 原因分析
   - 影响评估
   - 解决优先级

2. 方案制定
   - 多方案对比
   - 可行性分析
   - 成本评估
   - 风险控制

3. 实施与反馈
   - 方案实施
   - 效果验证
   - 用户反馈
   - 持续优化

# Continuous Improvement
1. 项目复盘
   - 记录经验教训
   - 总结最佳实践
   - 更新知识库
   - 优化工作流程

2. 技能提升
   - 跟踪技术趋势
   - 学习新技术
   - 分享经验
   - 持续成长

# Communication Guidelines
1. 与用户沟通
   - 使用通俗易懂的语言
   - 主动确认需求理解
   - 及时反馈进展
   - 耐心解答问题

2. 文档维护
   - 及时更新文档
   - 保持文档准确性
   - 注重文档可读性
   - 完善使用示例

# Research Assistant Guidelines

## Project Structure
1. Source PDFs stored in `sources_pdf/`
2. Markdown conversions in `sources_markdown/`
3. PNG extractions in `sources_png/`
4. Draft documents in root directory
5. Scripts for file processing in `scripts/`

## Information Accuracy & Citations
1. Verify all information against primary sources
2. Use requested citation format:
   ```markdown
   IEEE Example: [1] A. Author, B. Author, "Title of paper," Journal Name, vol. 1, no. 2, pp. 123-456, 2023.
   APA Example: Author, A., & Author, B. (2023). Title of paper. Journal Name, 1(2), 123-456.
   ```
3. Include DOI or permanent links:
   ```markdown
   DOI: 10.1234/journal.2023.1234
   arXiv: arXiv:2301.12345
   ```
4. Distinguish peer-reviewed vs non-peer-reviewed sources
5. Track citation networks and cross-references

## Document Management
1. Make changes file-by-file with verification
2. Preserve existing document structures
3. Use markdown for academic writing:
   ```markdown
   # Main Title
   ## Section Heading
   ### Subsection

   Key finding from [1] shows...
   ```
4. Maintain consistent formatting and hierarchy

## Image and Table Management
1. Center all images using markdown div syntax and set standard width:
   ```markdown
   <div style="width: 500px;">

   ![Description of Image](sources_png/paper_id/page_001.png)

   </div>

   *Note: Description of the content. Adapted from Author et al. (YEAR), Fig. X.*
   ```
2. Use standard image width:
   - All figures and diagrams: 500px
   - Add blank lines before and after the div and image for better readability
3. Format figure captions:
   - Start with "Figure N:" for numbering in the document
   - Follow with descriptive title
   - End with *Note: [Description]. Adapted from [Author] ([Year]), Fig. [X].* where X is the original figure number
4. Format tables with clear headers and citations:
   ```markdown
   **Table 1: Descriptive Title**
   | Column 1 | Column 2 | Column 3 |
   |----------|----------|----------|
   | Data     | Data     | Data     |

   *Note: Description of the table. Adapted from Author et al. (YEAR), Table X.*
   ```
5. For tables synthesized from multiple sources:
   ```markdown
   *Note: Framework synthesized from multiple sources: Author1 et al. (YEAR1), Author2 et al. (YEAR2), Author3 (YEAR3).*
   ```

## Source Integration Workflow
1. Example of finding content in sources_markdown:
   ```markdown
   # In sources_markdown/paper_id.md:
   "The measured value was X with Y latency..."

   # In draft.md:
   Recent studies have shown promising results, achieving X with Y latency [1].
   ```

2. Example of matching images:
   ```markdown
   # In sources_markdown/paper_id.md:
   Figure X: Description of diagram (page N)

   # In draft.md:
   <div style="width: 400px; margin: 0 auto; text-align: center;">
   ![Description](sources_png/paper_id/page_00N.png)
   </div>

   Figure M: Description of the system components - adapted from [1].
   ```

3. Example of integrating tables:
   ```markdown
   # In sources_markdown/paper_id.md:
   | Parameter | Value |
   |-----------|-------|
   | X | Y |

   # In draft.md:
   Table N: Analysis of Parameters

   | Parameter | Value | Source |
   |-----------|-------|--------|
   | X | Y | [1] |
   | A | B | [2] |
   ```

## Research Best Practices
1. Example of balanced viewpoint presentation:
   ```markdown
   While Method X shows superior performance in metric A [1], Method Y demonstrates advantages in metric B [2]. The trade-off between these factors remains an important consideration.
   ```

## Communication Standards
1. Example of formal academic writing:
   ```markdown
   Previous studies have demonstrated the effectiveness of approach X in context Y [1]. However, certain limitations persist in specific scenarios [2].
   ```

## Document Formatting
1. Example of consistent heading structure:
   ```markdown
   # Review Title
   ## Background
   ### Historical Context
   ### Current State
   ## Methods
   ### Approach
   ### Implementation
   ```

2. Example of table formatting:
   ```markdown
   Table N: System Parameters

   | Component | Parameter | Value |
   |-----------|-----------|-------|
   | X | Type A | Value 1 |
   | Y | Type B | Value 2 |

   Note: Measurements under standard conditions [1].
   ```

On va créer un "elevation image generator"

En gros l'utilisateur peu drag-n-drop une image, on va ensuite appliquer des shadow via des paramètres et des slides.

Ensuite l'utilisteur pourra créer l'image de son côté.

This is boostraping our kali system with various settings / tools / things

detauls to keep in mind:
* xfce
* kali

# Project Rules and Conventions

## Package Management

- Always use pnpm for package management
- Lock file (pnpm-lock.yaml) must be committed
- Use semantic versioning (^) for better dependency management
- Regular updates through automated tools (Renovate)

## Code Style

- Use TypeScript for all files
- Enforce strict TypeScript mode
- Use ESLint with Next.js recommended rules
- Follow Prettier formatting
- Use named exports instead of default exports
- Use arrow functions for consistency

## TypeScript and Data Validation

- Define Zod schemas for all data structures
- Always provide default values for optional fields
- Match Prisma schema types exactly in Zod schemas
- Use strict type checking (no any, unknown when possible)
- Define reusable type definitions in separate files
- Use type inference where possible
- Document complex types with JSDoc comments
- Handle nullable and optional fields explicitly

## Database and Models

- Always define complete Zod schemas for Prisma models
- Include all required fields in create/update operations
- Use enums for status and type fields
- Validate data before database operations
- Handle JSON fields with proper type definitions
- Keep Prisma schema and Zod schemas in sync

## UI Components

- Mobile-first approach for all components and layouts
- Design and test on mobile before desktop
- Use shadcn/ui as the primary component library
- Customize components through tailwind.config.ts
- Follow shadcn/ui's styling conventions
- Keep components atomic and reusable
- Use CSS variables for theming
- Ensure touch-friendly interactions
- Minimum tap target size of 44x44px
- Avoid hover-only interactions

## Responsive Design

- Start with mobile layout (375px width)
- Add breakpoints only when needed
- Use relative units (rem, em) over pixels
- Test on real mobile devices
- Consider network conditions
- Optimize images for mobile
- Ensure readable font sizes (min 16px)
- Account for touch interactions
- Consider offline capabilities

## Project Structure

- Follow the structure defined in PRD.md
- Keep components atomic and reusable
- Place types in separate .d.ts files
- Use barrel exports (index.ts) for cleaner imports

## State Management

- Use React Query for server state
- Use React Context for global UI state
- Implement proper loading and error states

## Internationalization

- All text must be in translation files
- Use next-intl for translations
- Follow the locale structure: /[locale]/[path]

## Internationalization (i18n) Rules

- All user-facing text must be internationalized using next-intl
- Never hardcode text strings directly in components or pages
- Place all translations in /messages/{locale}.json files
- Use semantic keys following the pattern: {page}.{section}.{element}
- Example: "home.hero.title"
- Comments in translation files should describe context
- Include placeholder documentation in translation strings
- Handle pluralization using ICU MessageFormat
- Maintain consistent casing in translation keys
- Group related translations under common namespaces
- Keep translation keys in sync across all locale files
- Document any new translation keys in PR descriptions
- Test all translations in development mode
- Validate translation files for missing/unused keys

## Translation File Structure

messages/
├── en.json # English (default)
├── es.json # Spanish
└── fr.json # French

## Translation Key Examples

{
"common": {
"buttons": {
"submit": "Submit",
"cancel": "Cancel"
},
"errors": {
"required": "{field} is required"
}
},
"pages": {
"home": {
"hero": {
"title": "Welcome",
"description": "Description here"
}
}
}
}

## API and Backend

- Use tRPC for type-safe API endpoints
- Implement proper error handling
- Follow REST principles for API design
- Use Prisma for database operations
- Define complete input/output types for all endpoints
- Validate all incoming data with Zod

## Environment Variables

- Never commit .env files
- Use .env.example for documentation
- Prefix all environment variables with NEXT*PUBLIC* for client usage
- Document all required environment variables

## Git Conventions

- Use conventional commits
- Branch naming: feature/, bugfix/, hotfix/
- Squash commits when merging
- Write descriptive commit messages

## Testing

- Write unit tests for utilities
- Write integration tests for API endpoints
- Use React Testing Library for component tests
- Test error states and edge cases
- Test data validation

## Performance

- Optimize images using next/image
- Implement proper code splitting
- Use proper caching strategies
- Monitor and optimize bundle size

## Security

- Implement proper input validation
- Use proper CORS settings
- Follow OWASP security guidelines
- Handle sensitive data appropriately
- Validate all user inputs
- Sanitize data before storage

# Project-Specific Instructions (To Be Used With Cursor)

# Project Guidelines and Standards

## Project Documentation

For detailed project information, refer to:

- Project Overview & Requirements: /docs/project.md
- API Documentation: /docs/api.md
- Development Backlog: /docs/backlog.md
- Feature Specifications: /docs/features/

## Technology Expertise

We are specialists in:

- Remix.js (Modern React Framework)
- TypeScript
- TailwindCSS
- shadcn-ui (Component Library)
- Node.js (20+)
- Vite

## Core Principles

### Architecture

- Follow Remix's nested routing pattern
- Implement loader/action pattern for data handling
- Use Resource Routes for API endpoints
- Keep components atomic and composable
- Implement progressive enhancement where possible
- Use shadcn-ui components as building blocks

### File Structure & Organization

- Follow consistent directory structure:
  ```
  ~/
  ├── components/
  │   ├── ui/          # shadcn-ui components
  │   ├── features/    # feature-specific components
  │   ├── layout/      # layout components
  │   └── auth/        # auth components
  ├── stores/          # Zustand stores
  ├── api/             # API integration
  │   ├── config/      # API configuration
  │   ├── hooks/       # React Query hooks
  │   ├── services/    # API services
  │   └── types/       # API types
  ├── lib/             # Utilities
  ├── styles/          # Global styles
  └── routes/          # Remix routes
  ```
- Follow naming conventions:
  - Files: kebab-case (user-profile.ts)
  - Components: PascalCase (UserProfile.tsx)
  - Hooks: use- prefix (use-auth.ts)
  - Stores: -store suffix (auth-store.ts)
  - Services: -service suffix (user-service.ts)
  - Types: .d.ts extension for definitions
- Keep files under 200 lines
- Maximum nesting depth of 3 levels
- Use meaningful names
- Implement proper TypeScript types

### Testing Strategy

- Directory Structure:

  ```
  ~/tests
  ├── e2e/            # End-to-end tests with Playwright
  │   ├── features/   # Feature-based tests
  │   └── mocks/      # Test mocks if needed
  └── unit/           # Unit tests with Vitest
  ```

- E2E Testing (Playwright):

  - Test critical user flows
  - One test file per feature/route
  - Use page objects for complex flows
  - Mock API responses using Remix resource routes
  - Test files end with .spec.ts
  - Run tests with `npm run test:e2e`

- Test File Naming:

  - E2E Tests: `feature-name.spec.ts`
  - Unit Tests: `component-name.test.ts`

- Best Practices:
  - Write tests before fixing bugs
  - Mock only when necessary
  - Keep tests independent
  - Use meaningful test descriptions
  - Test error states and edge cases
  - Follow AAA pattern (Arrange, Act, Assert)

### Code Style

- Use TypeScript strict mode
- Prefer functional components
- Use named exports over default exports
- Keep components under 350 lines
- Use meaningful variable names (no abbreviations)
- Implement proper TypeScript interfaces/types

### Component Architecture

- Use shadcn-ui components as foundation
- Always compose complex components from simpler ones
- Customize components using theme tokens only
- Follow shadcn-ui's composition pattern strictly
- Maintain accessibility features
- Use Radix primitives for complex interactions
- Create variants using cva (class-variance-authority)
- Document all component variants and props
- Keep component stories updated

### Design System

- Follow shadcn-ui's design system strictly
- Embrace minimalism - less is more
- Use theme variables for colors exclusively
- Implement dark mode support by default
- Maintain consistent spacing using tailwind classes
- Follow 8px grid system
- Use semantic color naming
- Prefer whitespace and typography for hierarchy
- Use subtle animations purposefully
- Follow visual hierarchy principles
- Use negative space effectively
- Design for scalability and reuse

### State Management

- Client State (Zustand):

  - Keep stores small and focused
  - Use middleware when needed (persist, devtools, immer)
  - Follow store slicing pattern
  - Use selectors for state access
  - Avoid storing derived state
  - Implement proper cleanup
  - Use shallow equality checks
  - Document interfaces and actions

- Server State (React Query):
  - Use proper query keys and caching
  - Handle loading and error states
  - Type all responses
  - Use suspense when appropriate
  - Enable devtools in development
  - Implement optimistic updates
  - Handle offline scenarios
  - Use infinite queries for pagination

### Authentication & Security

- Authentication:

  - Use Zustand for auth state
  - Implement JWT-based auth
  - Handle token expiration
  - Secure token storage
  - Implement proper login/logout flow
  - Remember user preferences
  - Clear sensitive data on logout

- Authorization:

  - Use protected routes with role-based access
  - Handle unauthorized access gracefully
  - Implement loading states
  - Type-safe role definitions
  - Example protected route:
    ```tsx
    <ProtectedRoute requiredRole='admin'>
      <AdminDashboard />
    </ProtectedRoute>
    ```

- Security:
  - Implement CSRF protection
  - Use proper authentication headers
  - Sanitize all inputs/outputs
  - Use refresh token rotation
  - Implement proper CORS settings
  - Use environment variables for secrets
  - Never expose sensitive data
  - Implement rate limiting
  - Use HTTPS only

### Navigation & Layout

- Navigation:

  - Use Radix Navigation Menu
  - Separate public/private routes
  - Role-based navigation items
  - Handle mobile navigation
  - Use theme tokens for styling
  - Manage z-index properly

- Layout:
  - Use consistent layout structure:
    ```tsx
    <RootLayout>
      <ProtectedRoute>
        <PageContent />
      </ProtectedRoute>
    </RootLayout>
    ```
  - Implement responsive patterns
  - Maintain consistent spacing
  - Handle nested layouts when needed

### Error Handling

- Use error boundaries strategically
- Handle different error types:
  - Network errors
  - Validation errors
  - Authentication errors
  - Authorization errors
- Show user-friendly messages
- Implement proper retry mechanisms
- Log errors appropriately
- Handle offline scenarios
- Implement form validation

### Performance

- Implement code splitting
- Use proper caching strategies
- Optimize assets and payloads
- Use compression
- Implement request cancellation
- Use proper batch requests
- Monitor performance metrics
- Use proper meta tags for SEO
- Handle loading states gracefully

### Testing & Quality

- Testing Structure:

  ```
  ~/
  ├── tests/
  │   ├── unit/              # Unit tests
  │   ├── integration/       # Integration tests
  │   ├── e2e/              # End-to-end tests
  │   ├── fixtures/         # Test data
  │   ├── mocks/           # Mock implementations
  │   └── utils/           # Test utilities
  ```

- Coverage Requirements:

  - Maintain minimum 85% code coverage
  - 100% coverage for critical paths
  - Track coverage trends in CI
  - Coverage requirements:
    ```
    - Statements: 85%
    - Branches: 85%
    - Functions: 85%
    - Lines: 85%
    ```

- Unit Testing (Vitest + RTL):

  - Test individual components in isolation
  - Mock external dependencies
  - Test component props and events
  - Test hooks independently
  - Test utility functions
  - Test store actions and selectors
  - Follow AAA pattern (Arrange, Act, Assert)
  - Example:
    ```tsx
    describe('Button', () => {
      it('should call onClick when clicked', () => {
        const onClick = vi.fn()
        render(<Button onClick={onClick}>Click me</Button>)
        userEvent.click(screen.getByText('Click me'))
        expect(onClick).toHaveBeenCalled()
      })
    })
    ```

- Integration Testing:

  - Test component interactions
  - Test data flow between components
  - Test store integration
  - Test form submissions
  - Test API integration
  - Use MSW for API mocking
  - Example:

    ```tsx
    describe('LoginForm', () => {
      it('should handle successful login', async () => {
        const user = userEvent.setup()
        render(<LoginForm />)

        await user.type(screen.getByLabelText('Email'), 'test@example.com')
        await user.type(screen.getByLabelText('Password'), 'password')
        await user.click(screen.getByText('Login'))

        expect(await screen.findByText('Welcome')).toBeInTheDocument()
      })
    })
    ```

- E2E Testing (Playwright):

  - Test critical user flows
  - Test across multiple browsers
  - Test responsive design
  - Test accessibility
  - Record test videos
  - Take screenshots on failure
  - Example:
    ```typescript
    test('user can login and access dashboard', async ({ page }) => {
      await page.goto('/')
      await page.fill('[aria-label="Email"]', 'user@example.com')
      await page.fill('[aria-label="Password"]', 'password')
      await page.click('button:has-text("Login")')
      await expect(page).toHaveURL('/dashboard')
    })
    ```

- API Mocking (MSW):

  - Mock API responses
  - Test error scenarios
  - Test loading states
  - Example:
    ```typescript
    const handlers = [
      rest.get('/api/users', (req, res, ctx) => {
        return res(ctx.json([{ id: 1, name: 'John' }]))
      }),
      rest.post('/api/login', (req, res, ctx) => {
        return res(ctx.json({ token: 'fake-token' }))
      })
    ]
    ```

- Testing Best Practices:

  - Write tests before fixing bugs
  - Update tests when modifying features
  - Use meaningful test descriptions
  - Test error scenarios
  - Test edge cases
  - Use proper assertions
  - Clean up after each test
  - Use shared test utilities
  - Document test requirements
  - Follow test-driven development when possible
  - Testing Philosophy:
    - Tests should drive implementation, not the other way around
    - Don't modify tests to make them pass - fix the implementation
    - Only mock what's necessary (external APIs, time-dependent operations)
    - Mocking should not be used to make a failing test pass
    - If a test fails, understand why and fix the underlying issue
    - Tests should reflect real user behavior and requirements
    - Keep tests as close to production behavior as possible
  - Mocking Guidelines:
    - Only mock external dependencies
    - Mock HTTP requests and API calls
    - Mock time-dependent operations
    - Mock complex browser APIs when needed
    - Never mock to hide implementation problems
    - Document why a mock is necessary
    - Keep mocks as simple as possible

- Continuous Integration:

  - Run all tests on PR
  - Block merging on test failure
  - Generate coverage reports
  - Run E2E tests in CI
  - Cache test results
  - Parallelize test execution
  - Monitor test duration

- Testing Quality:

  - No flaky tests
  - Fast execution
  - Independent tests
  - Clear failure messages
  - Easy to maintain
  - Follow testing patterns
  - Use testing utilities
  - Document complex tests

- Accessibility Testing:
  - Test with screen readers
  - Test keyboard navigation
  - Test color contrast
  - Test ARIA attributes
  - Test focus management
  - Use accessibility testing tools

use gpt-4o for all openai calls
we're using vitest
use bun instead of tsx

    You are an expert in WordPress, PHP, and related web development technologies.
     
    Core Principles
    - Provide precise, technical PHP and WordPress examples.
    - Adhere to PHP and WordPress best practices for consistency and readability.
    - Emphasize object-oriented programming (OOP) for better modularity.
    - Focus on code reusability through iteration and modularization, avoiding duplication.
    - Use descriptive and meaningful function, variable, and file names.
    - Directory naming conventions: lowercase with hyphens (e.g., wp-content/themes/my-theme).
    - Use WordPress hooks (actions and filters) for extending functionality.
    - Add clear, descriptive comments to improve code clarity and maintainability.
    
    PHP/WordPress Coding Practices
    - Utilize features of PHP 7.4+ (e.g., typed properties, arrow functions) where applicable.
    - Follow WordPress PHP coding standards throughout the codebase.
    - Enable strict typing by adding declare(strict_types=1); at the top of PHP files.
    - Leverage core WordPress functions and APIs wherever possible.
    - Maintain WordPress theme and plugin directory structure and naming conventions.
    - Implement robust error handling:
      - Use WordPress's built-in debug logging (WP_DEBUG_LOG).
      - Implement custom error handlers if necessary.
      - Apply try-catch blocks for controlled exception handling.
    - Always use WordPress’s built-in functions for data validation and sanitization.
    - Ensure secure form handling by verifying nonces in submissions.
    - For database interactions:
      - Use WordPress’s $wpdb abstraction layer.
      - Apply prepare() statements for all dynamic queries to prevent SQL injection.
      - Use the dbDelta() function for managing database schema changes.

    Dependencies
    - Ensure compatibility with the latest stable version of WordPress.
    - Use Composer for dependency management in advanced plugins or themes.

    WordPress Best Practices
    - Use child themes for customizations to preserve update compatibility.
    - Never modify core WordPress files—extend using hooks (actions and filters).
    - Organize theme-specific functions within functions.php.
    - Use WordPress’s user roles and capabilities for managing permissions.
    - Apply the transients API for caching data and optimizing performance.
    - Implement background processing tasks using wp_cron() for long-running operations.
    - Write unit tests using WordPress’s built-in WP_UnitTestCase framework.
    - Follow best practices for internationalization (i18n) by using WordPress localization functions.
    - Apply proper security practices such as nonce verification, input sanitization, and data escaping.
    - Manage scripts and styles by using wp_enqueue_script() and wp_enqueue_style().
    - Use custom post types and taxonomies when necessary to extend WordPress functionality.
    - Store configuration data securely using WordPress's options API.
    - Implement pagination effectively with functions like paginate_links().

    Key Conventions
    1. Follow WordPress’s plugin API to extend functionality in a modular and scalable manner.
    2. Use WordPress’s template hierarchy when developing themes to ensure flexibility.
    3. Apply WordPress’s built-in functions for data sanitization and validation to secure user inputs.
    4. Implement WordPress’s template tags and conditional tags in themes for dynamic content handling.
    5. For custom queries, use $wpdb or WP_Query for database interactions.
    6. Use WordPress’s authentication and authorization mechanisms for secure access control.
    7. For AJAX requests, use admin-ajax.php or the WordPress REST API for handling backend requests.
    8. Always apply WordPress’s hook system (actions and filters) for extensible and modular code.
    9. Implement database operations using transactional functions where needed.
    10. Schedule tasks using WordPress’s WP_Cron API for automated workflows.