|
2 | 2 | applyTo: '**' |
3 | 3 | --- |
4 | 4 |
|
5 | | -# WordPress Plugin Development Standards |
| 5 | +# EngineScript Site Optimizer — Development Standards |
6 | 6 |
|
7 | | -## 🎯 Core Principles |
| 7 | +## Project Context |
8 | 8 |
|
9 | | -**Work Environment:** Remote GitHub Codespaces only. Never suggest local Terminal commands. |
| 9 | +- **Plugin:** EngineScript Site Optimizer — WordPress performance optimization plugin |
| 10 | +- **Text Domain:** `enginescript-site-optimizer` |
| 11 | +- **Function/Hook Prefix:** `es_optimizer_` |
| 12 | +- **Version Constant:** `ES_SITE_OPTIMIZER_VERSION` |
| 13 | +- **WordPress:** 6.5+ | **PHP:** 7.4+ |
| 14 | +- **Work Environment:** GitHub Codespaces (remote). Never suggest local terminal commands. |
10 | 15 |
|
11 | | -**WordPress First:** Use WordPress APIs, hooks, and standards exclusively. Avoid non-WP frameworks. |
| 16 | +## Code Standards |
12 | 17 |
|
13 | | -**Security Critical:** Sanitize all input, escape all output, use WordPress security functions. |
| 18 | +### WordPress & PHP |
14 | 19 |
|
15 | | -**Thorough Analysis:** Read complete files (minimum 1500 lines) for accurate code review. |
| 20 | +- Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) for PHP, JS, CSS, HTML, and accessibility |
| 21 | +- Use WordPress APIs and hooks exclusively — no raw PHP/SQL or non-WP frameworks |
| 22 | +- Prefix all functions, classes, hooks, and globals with `es_optimizer_` |
| 23 | +- Use `wp_die()` instead of `die()` or `exit()` |
| 24 | +- Use `WP_Error` for error handling; log errors without exposing sensitive data |
| 25 | +- Use PHPDoc with `@param`, `@return`, `@since` tags on all functions |
| 26 | +- Organize code by feature; use descriptive names; remove unused code |
| 27 | +- Validate all function parameters and handle edge cases gracefully |
16 | 28 |
|
17 | | -## 📋 Essential Requirements |
| 29 | +### Modern PHP |
18 | 30 |
|
19 | | -### WordPress Compatibility |
| 31 | +- PHP 7.4+ features are required; PHP 8.x features are allowed if they degrade gracefully on 7.4 |
| 32 | +- Use typed function signatures wherever possible |
| 33 | +- Before submitting changes, run `phpcs`, `phpmd`, and `phpstan` (config files present in project root) |
20 | 34 |
|
21 | | -- **WordPress:** 6.5+ minimum |
22 | | -- **PHP:** 7.4+ minimum |
23 | | -- **WooCommerce:** 5.0+ (when applicable) |
24 | | -- Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) for PHP, JS, CSS, HTML, and accessibility |
| 35 | +## Security (Critical) |
| 36 | + |
| 37 | +All code must follow OWASP Top 10 and WordPress security best practices. **Auto-identify and fix security vulnerabilities whenever found — never leave them.** |
25 | 38 |
|
26 | | -### Code Quality Standards |
| 39 | +**Input:** |
| 40 | +- Sanitize with `sanitize_text_field()`, `sanitize_email()`, `absint()`, or `wp_kses()` as appropriate |
| 41 | +- Validate nonces with `wp_verify_nonce()` on all form submissions and AJAX handlers |
| 42 | +- Use `$wpdb->prepare()` for every database query |
27 | 43 |
|
28 | | -1. **Security First:** Always sanitize input (`sanitize_*()`) and escape output (`esc_*()`) |
29 | | -2. **WordPress APIs:** Use WP functions instead of raw PHP/SQL |
30 | | -3. **Hook System:** Proper use of `add_action()` and `add_filter()` |
31 | | -4. **Internationalization:** Use `__()`, `_e()`, `esc_html__()` for all strings |
32 | | -5. **Performance:** Avoid N+1 queries, use WP caching, optimize database calls |
| 44 | +**Output:** |
| 45 | +- Escape with context-appropriate functions: `esc_html()`, `esc_attr()`, `esc_url()`, `esc_js()`, `esc_textarea()` |
| 46 | +- Use `wp_nonce_field()` for all admin forms |
33 | 47 |
|
34 | | -## 🔒 Security Requirements (Critical) |
| 48 | +**Access Control:** |
| 49 | +- Check `current_user_can('manage_options')` before any settings operation |
| 50 | +- Always include `if ( ! defined( 'ABSPATH' ) ) { return; }` at the top of every PHP file |
| 51 | +- Prevent SQL injection, XSS, CSRF, LFI, and path traversal at all times |
35 | 52 |
|
36 | | -**Input Handling:** |
37 | | -- Use `sanitize_text_field()`, `sanitize_email()`, `wp_kses()` for user input |
38 | | -- Validate with `is_email()`, `absint()`, `wp_verify_nonce()` for security |
39 | | -- Use prepared statements for database queries (`$wpdb->prepare()`) |
| 53 | +## Performance |
40 | 54 |
|
41 | | -**Output Security:** |
42 | | -- Escape all output: `esc_html()`, `esc_attr()`, `esc_url()`, `esc_js()` |
43 | | -- Use `wp_nonce_field()` and `wp_verify_nonce()` for forms |
44 | | -- Check permissions with `current_user_can()` before sensitive operations |
| 55 | +- Cache expensive operations with `wp_cache_*()` and transients |
| 56 | +- Avoid N+1 queries; optimize all database calls |
| 57 | +- Enqueue assets via `wp_enqueue_scripts()` / `wp_enqueue_styles()` with correct dependencies and version strings |
| 58 | +- Conditionally load admin assets only on relevant admin pages; conditionally load frontend assets only when needed |
45 | 59 |
|
46 | | -**Vulnerability Prevention:** |
47 | | -- Prevent SQL injection, XSS, CSRF, Local File Inclusion (LFI), and path traversal |
48 | | -- Follow principle of least privilege |
49 | | -- Auto-identify and fix security issues when found |
| 60 | +## Internationalization (i18n) |
50 | 61 |
|
51 | | -## 📝 Documentation & Versioning |
| 62 | +- Mark all user-facing strings with `__()`, `_e()`, `esc_html__()`, or `esc_attr__()` |
| 63 | +- Always use text domain `enginescript-site-optimizer` |
| 64 | +- Update `languages/enginescript-site-optimizer.pot` whenever translatable strings are added or changed |
52 | 65 |
|
53 | | -**Changelog Management:** |
54 | | -- Always update CHANGELOG.md and readme.txt when making code changes |
55 | | -- **Sync both changelogs:** CHANGELOG.md and readme.txt changelog section |
56 | | -- Use "Unreleased" section for ongoing changes |
| 66 | +## Documentation & Versioning |
57 | 67 |
|
58 | | -**Version Release Process (only when instructed):** |
| 68 | +**On every code change:** |
| 69 | +- Add an entry to the `Unreleased` section of `CHANGELOG.md` |
| 70 | +- Mirror the same entry in the changelog section of `readme.txt` |
| 71 | + |
| 72 | +**Version releases (only when explicitly instructed):** |
59 | 73 | - Follow semantic versioning (MAJOR.MINOR.PATCH) |
60 | | -- Update version in: plugin header, README.md, readme.txt, CHANGELOG.md, GEMINI.md, and `.pot` language files, constants section, package.json, and composer.json |
61 | | -- Move "Unreleased" changes to new version section in both changelogs |
62 | | -- **Never auto-update versions** - wait for explicit instruction |
63 | | - |
64 | | -**Code Documentation:** |
65 | | -- Use PHPDoc with `@param`, `@return`, `@since` tags |
66 | | -- Write clear function/class descriptions |
67 | | -- Document security considerations and hooks used |
68 | | - |
69 | | -**Internationalization (i18n):** |
70 | | -- Update `.pot` language files when adding or modifying translatable strings |
71 | | -- Always use the correct text domain when dealing with translation functions |
72 | | -- Mark all user-facing strings with `__()`, `_e()`, `esc_html__()`, `esc_attr__()`, etc. |
73 | | - |
74 | | -## ⚡ Performance & Quality |
75 | | - |
76 | | -**Performance Optimization:** |
77 | | -- Use WordPress caching (`wp_cache_*()`, transients) |
78 | | -- Optimize database queries, avoid N+1 problems |
79 | | -- Proper asset enqueueing with `wp_enqueue_*()` functions |
80 | | -- Focus on correctness first, then optimize |
81 | | - |
82 | | -**Code Architecture:** |
83 | | -- Group by feature, not by type |
84 | | -- Use descriptive function/variable names |
85 | | -- Remove unused code automatically |
86 | | -- Follow feature-sliced design when applicable |
87 | | - |
88 | | -**Error Handling:** |
89 | | -- Use `WP_Error` for WordPress-specific errors |
90 | | -- Log errors without exposing sensitive data |
91 | | -- Handle edge cases gracefully |
92 | | -- Validate all function parameters |
93 | | - |
94 | | -## 🚀 Workflow & Automation |
95 | | - |
96 | | -**Task Execution:** |
97 | | -- Make changes directly to existing files (don't create duplicates) |
98 | | -- Proceed automatically unless action is destructive |
99 | | -- Auto-identify and fix bugs when possible |
100 | | -- Only ask confirmation for data loss/deletion scenarios |
101 | | - |
102 | | -**File Management:** |
103 | | -- Edit files in place (e.g., modify `admin.php` directly) |
104 | | -- Create new files only when truly necessary |
105 | | -- Avoid file duplication and unnecessary rewrites |
106 | | -- Maintain clean project structure |
107 | | - |
108 | | -**Communication:** |
109 | | -- Provide concise, actionable responses |
110 | | -- Use clear formatting for readability |
111 | | -- Never create change summaries as separate .md files |
112 | | -- Focus on specific changes made, not verbose explanations |
| 74 | +- Update version in: plugin file header, `ES_SITE_OPTIMIZER_VERSION` constant, `README.md`, `readme.txt`, `CHANGELOG.md`, `GEMINI.md`, `composer.json`, and `languages/enginescript-site-optimizer.pot` |
| 75 | +- Move all `Unreleased` entries to the new version section in both `CHANGELOG.md` and `readme.txt` |
| 76 | +- **Never auto-bump versions** — wait for an explicit instruction to do so |
| 77 | + |
| 78 | +## Workflow |
| 79 | + |
| 80 | +- Edit files in place — never create duplicate files or unnecessary new files |
| 81 | +- Proceed automatically on non-destructive changes; ask before deleting files or data |
| 82 | +- Auto-fix bugs and security issues when identified |
| 83 | +- Keep responses concise and focused on what changed — no summary `.md` files |
0 commit comments