{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"wordpress","version":"0.1.0"},"spec":{"agents_md":"---\napplyTo: 'wp-content/plugins/**,wp-content/themes/**,**/*.php,**/*.inc,**/*.js,**/*.jsx,**/*.ts,**/*.tsx,**/*.css,**/*.scss,**/*.json'\ndescription: 'Coding, security, and testing rules for WordPress plugins and themes'\n---\n\n# WordPress Development — Copilot Instructions\n\n**Goal:** Generate WordPress code that is secure, performant, testable, and compliant with official WordPress practices. Prefer hooks, small functions, dependency injection (where sensible), and clear separation of concerns.\n\n## 1) Core Principles\n- Never modify WordPress core. Extend via **actions** and **filters**.\n- For plugins, always include a header and guard direct execution in entry PHP files.\n- Use unique prefixes or PHP namespaces to avoid global collisions.\n- Enqueue assets; never inline raw `\u003cscript\u003e`/`\u003cstyle\u003e` in PHP templates.\n- Make user‑facing strings translatable and load the correct text domain.\n\n### Minimal plugin header \u0026 guard\n```php\n\u003c?php\ndefined('ABSPATH') || exit;\n/**\n * Plugin Name: Awesome Feature\n * Description: Example plugin scaffold.\n * Version: 0.1.0\n * Author: Example\n * License: GPL-2.0-or-later\n * Text Domain: awesome-feature\n * Domain Path: /languages\n */\n```\n\n## 2) Coding Standards (PHP, JS, CSS, HTML)\n- Follow **WordPress Coding Standards (WPCS)** and write DocBlocks for public APIs.\n- PHP: Prefer strict comparisons (`===`, `!==`) where appropriate. Be consistent with array syntax and spacing as per WPCS.\n- JS: Match WordPress JS style; prefer `@wordpress/*` packages for block/editor code.\n- CSS: Use BEM‑like class naming when helpful; avoid over‑specific selectors.\n- PHP 7.4+ compatible patterns unless the project specifies higher. Avoid using features not supported by target WP/PHP versions.\n\n### Linting setup suggestions\n```xml\n\u003c!-- phpcs.xml --\u003e\n\u003c?xml version=\"1.0\"?\u003e\n\u003cruleset name=\"Project WPCS\"\u003e\n  \u003cdescription\u003eWordPress Coding Standards for this project.\u003c/description\u003e\n  \u003cfile\u003e./\u003c/file\u003e\n  \u003cexclude-pattern\u003evendor/*\u003c/exclude-pattern\u003e\n  \u003cexclude-pattern\u003enode_modules/*\u003c/exclude-pattern\u003e\n  \u003crule ref=\"WordPress\"/\u003e\n  \u003crule ref=\"WordPress-Docs\"/\u003e\n  \u003crule ref=\"WordPress-Extra\"/\u003e\n  \u003crule ref=\"PHPCompatibility\"/\u003e\n  \u003cconfig name=\"testVersion\" value=\"7.4-\"/\u003e\n\u003c/ruleset\u003e\n```\n\n```json\n// composer.json (snippet)\n{\n  \"require-dev\": {\n    \"dealerdirect/phpcodesniffer-composer-installer\": \"^1.0\",\n    \"wp-coding-standards/wpcs\": \"^3.0\",\n    \"phpcompatibility/php-compatibility\": \"^9.0\"\n  },\n  \"scripts\": {\n    \"lint:php\": \"phpcs -p\",\n    \"fix:php\": \"phpcbf -p\"\n  }\n}\n```\n\n```json\n// package.json (snippet)\n{\n  \"devDependencies\": {\n    \"@wordpress/eslint-plugin\": \"^x.y.z\"\n  },\n  \"scripts\": {\n    \"lint:js\": \"eslint .\"\n  }\n}\n```\n\n## 3) Security \u0026 Data Handling\n- **Escape on output, sanitize on input.**\n  - Escape: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()`.\n  - Sanitize: `sanitize_text_field()`, `sanitize_email()`, `sanitize_key()`, `absint()`, `intval()`.\n- **Capabilities \u0026 nonces** for forms, AJAX, REST:\n  - Add nonces with `wp_nonce_field()` and verify via `check_admin_referer()` / `wp_verify_nonce()`.\n  - Restrict mutations with `current_user_can( 'manage_options' /* or specific cap */ )`.\n- **Database:** always use `$wpdb-\u003eprepare()` with placeholders; never concatenate untrusted input.\n- **Uploads:** validate MIME/type and use `wp_handle_upload()`/`media_handle_upload()`.\n\n## 4) Internationalization (i18n)\n- Wrap user‑visible strings with translation functions using your text domain:\n  - `__( 'Text', 'awesome-feature' )`, `_x()`, `esc_html__()`.\n- Load translations with `load_plugin_textdomain()` or `load_theme_textdomain()`.\n- Keep a `.pot` in `/languages` and ensure consistent domain usage.\n\n## 5) Performance\n- Defer heavy logic to specific hooks; avoid expensive work on `init`/`wp_loaded` unless necessary.\n- Use transients or object caching for expensive queries; plan invalidation.\n- Enqueue only what you need and conditionally (front vs admin; specific screens/routes).\n- Prefer paginated/parameterized queries over unbounded loops.\n\n## 6) Admin UI \u0026 Settings\n- Use **Settings API** for options pages; provide `sanitize_callback` for each setting.\n- For tables, follow `WP_List_Table` patterns. For notices, use the admin notices API.\n- Avoid direct HTML echoing for complex UIs; prefer templates or small view helpers with escaping.\n\n## 7) REST API\n- Register with `register_rest_route()`; always set a `permission_callback`.\n- Validate/sanitize request args via the `args` schema.\n- Return `WP_REST_Response` or arrays/objects that map cleanly to JSON.\n\n## 8) Blocks \u0026 Editor (Gutenberg)\n- Use `block.json` + `register_block_type()`; rely on `@wordpress/*` packages.\n- Provide server render callbacks when needed (dynamic blocks).\n- E2E tests should cover: insert block → edit → save → front‑end render.\n\n## 9) Asset Loading\n```php\nadd_action('wp_enqueue_scripts', function () {\n  wp_enqueue_style(\n    'af-frontend',\n    plugins_url('assets/frontend.css', __FILE__),\n    [],\n    '0.1.0'\n  );\n\n  wp_enqueue_script(\n    'af-frontend',\n    plugins_url('assets/frontend.js', __FILE__),\n    [ 'wp-i18n', 'wp-element' ],\n    '0.1.0',\n    true\n  );\n});\n```\n- Use `wp_register_style/script` to register first if multiple components depend on the same assets.\n- For admin screens, hook into `admin_enqueue_scripts` and check screen IDs.\n\n## 10) Testing\n### PHP Unit/Integration\n- Use **WordPress test suite** with `PHPUnit` and `WP_UnitTestCase`.\n- Test: sanitization, capability checks, REST permissions, DB queries, hooks.\n- Prefer factories (`self::factory()-\u003epost-\u003ecreate()` etc.) to set up fixtures.\n\n```xml\n\u003c!-- phpunit.xml.dist (minimal) --\u003e\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cphpunit bootstrap=\"tests/bootstrap.php\" colors=\"true\"\u003e\n  \u003ctestsuites\u003e\n    \u003ctestsuite name=\"Plugin Test Suite\"\u003e\n      \u003cdirectory suffix=\"Test.php\"\u003etests/\u003c/directory\u003e\n    \u003c/testsuite\u003e\n  \u003c/testsuites\u003e\n\u003c/phpunit\u003e\n```\n\n```php\n// tests/bootstrap.php (minimal sketch)\n\u003c?php\n$_tests_dir = getenv('WP_TESTS_DIR') ?: '/tmp/wordpress-tests-lib';\nrequire_once $_tests_dir . '/includes/functions.php';\ntests_add_filter( 'muplugins_loaded', function () {\n  require dirname(__DIR__) . '/awesome-feature.php';\n} );\nrequire $_tests_dir . '/includes/bootstrap.php';\n```\n### E2E\n- Use Playwright (or Puppeteer) for editor/front‑end flows.\n- Cover basic user journeys and regressions (block insertion, settings save, front‑end render).\n\n## 11) Documentation \u0026 Commits\n- Keep `README.md` up to date: install, usage, capabilities, hooks/filters, and test instructions.\n- Use clear, imperative commit messages; reference issues/tickets and summarize impact.\n\n## 12) What Copilot Must Ensure (Checklist)\n- ✅ Unique prefixes/namespaces; no accidental globals.  \n- ✅ Nonce + capability checks for any write action (AJAX/REST/forms).  \n- ✅ Inputs sanitized; outputs escaped.  \n- ✅ User‑visible strings wrapped in i18n with correct text domain.  \n- ✅ Assets enqueued via APIs (no inline script/style).  \n- ✅ Tests added/updated for new behaviors.  \n- ✅ Code passes PHPCS (WPCS) and ESLint where applicable.  \n- ✅ Avoid direct DB concatenation; always prepare queries.\n","description":"Coding, security, and testing rules for WordPress plugins and themes","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/wordpress.instructions.md"},"manifest":{}},"content_hash":[121,67,214,237,248,72,73,81,237,96,199,159,113,112,81,126,19,243,163,251,93,149,170,5,170,36,58,124,230,132,38,207],"trust_level":"unsigned","yanked":false}