| 1 |
# Repository Instructions |
| 2 |
|
| 3 |
Follow these rules for all changes in this WordPress plugin repository. |
| 4 |
|
| 5 |
## Core Rules |
| 6 |
|
| 7 |
- Stay close to WordPress core and Gutenberg standards. |
| 8 |
- Keep it simple. |
| 9 |
- Prefer existing Gutenberg elements, WordPress functions, official APIs, block metadata, block-editor components, and the WordPress Settings API. |
| 10 |
- Write as little custom code as possible. Less is more. |
| 11 |
- Avoid hacks, CSS tricks, hidden coupling, and one-off workarounds. |
| 12 |
- Avoid inline styles unless a user-selected value must be output dynamically and there is no cleaner standard path. |
| 13 |
- Keep layout and reusable presentation rules in SCSS/CSS, not in PHP strings. |
| 14 |
- Sanitize all dynamic PHP output with the appropriate WordPress escaping helpers. |
| 15 |
|
| 16 |
## Documentation Workflow |
| 17 |
|
| 18 |
- Update `readme.txt` only when changing plugin documentation. |
| 19 |
- Do not edit `README.md` by hand. It is generated automatically from `readme.txt` by the GitHub Actions workflow. |
| 20 |
- Keep `readme.txt` valid for WordPress.org first; the generated Markdown README is secondary. |
| 21 |
|
| 22 |
## Deployment Workflow |
| 23 |
|
| 24 |
- Read and understand the repository's GitHub Actions workflows before changing deployment behavior. |
| 25 |
- Check `.github/workflows/` to see which branch, tag, path, or manual triggers deploy plugin code, WordPress.org assets, generated documentation, or release artifacts. |
| 26 |
- Check `.distignore` before adding project-only files. Claude skills, local tooling, generated GitHub-only files, and development metadata must not be shipped to WordPress.org. |
| 27 |
- Keep deployment changes conservative and explicit. Do not add a new deployment path when an existing workflow already covers the job. |
| 28 |
|
| 29 |
## Block Workflow |
| 30 |
|
| 31 |
- Treat `src/block.json` as the source of truth for block attributes and asset registration. |
| 32 |
- Treat `src/edit.js` as editor configuration only. |
| 33 |
- For dynamic blocks, render frontend markup in the PHP render path, not in `save.js`. |
| 34 |
- When adding a new editor option, wire it through block attributes first, then implement the frontend effect in the existing PHP render path or registered frontend styles. |
| 35 |
- Rebuild generated files after source changes so `build/` stays in sync. |
| 36 |
|
| 37 |
## Styling Workflow |
| 38 |
|
| 39 |
- Prefer wrapper classes and registered block stylesheets over hard-coded CSS in PHP. |
| 40 |
- Reuse Gutenberg conventions such as palette-driven colors, `has-background`, and block wrapper attributes when they fit. |
| 41 |
- For optional styling features, expose explicit settings instead of baking in fixed presets unless the requirement is truly global. |
| 42 |
- For global styling behavior, add the option to the plugin settings page and store it via the existing options flow. |
| 43 |
|
| 44 |
## Settings Workflow |
| 45 |
|
| 46 |
- Add global options in the plugin's existing settings module. |
| 47 |
- Register options with `register_setting()`, render them with `add_settings_field()`, and keep labels/help text concise. |
| 48 |
- Respect existing filter overrides when the settings page already follows that pattern. |
| 49 |
- If a global option forces behavior, keep block-level UI simple and make the server-side precedence explicit. |
| 50 |
|
| 51 |
## Project Preferences |
| 52 |
|
| 53 |
- Prefer maintainable, standard-compliant solutions over fast shortcuts. |
| 54 |
- If a request appears to require a workaround, stop and look for the clean WordPress-native approach first. |
| 55 |
- If a compromise is unavoidable, state the tradeoff explicitly before implementing it. |
| 56 |
|
