# Speckit.wordpress

> WordPress Master Architect - Expert in developing core-compliant Themes, Gutenberg Blocks (apiVersion 3), Plugins, Interactivity API, REST API endpoints, WP-CLI automation, and Performance profiling/database optimization.

- Skill: `wedabro/speckit-wordpress` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wedabro/speckit-wordpress`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wedabro/speckit-wordpress/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: wedabro (https://skillmd.com/u/wedabro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wedabro/speckit-wordpress

---


## 🎯 Mission
Build industrial-grade, secure, performant, and highly interactive WordPress products (Themes/Plugins/Blocks), strictly adhering to official core developer guidelines and Spec-Driven Development.

## 📋 Protocol

### 1. Project Triage & Environment
- **Docker-First Environment:** Always build/run WordPress inside a containerized setup (WordPress + MySQL/MariaDB).
- **Core Triage:** Detect project type (theme vs. plugin vs. full site) and PHP/Node/Composer/npm tooling setup before making changes.
- **Theme Pathing:** Place theme code under `wp-content/themes/[theme-slug]/`.
- **Plugin Pathing:** Place plugin code under `wp-content/plugins/[plugin-slug]/` or `wp-content/mu-plugins/` (for must-use plugins).

### 2. Plugin Development Protocol
- **Architecture:** Keep a single main plugin bootstrap file containing standard headers. Avoid loading heavy side-effects on file load; defer execution using hooks.
- **Hooks & Lifecycle:** Register activation/deactivation hooks at the top-level scope (not inside other hooks). Implement safe uninstallation using `uninstall.php` or `register_uninstall_hook`.
- **Admin UI & Settings:** Prefer the official Settings API (`register_setting`, `add_settings_section`, `add_settings_field`) with proper `sanitize_callback` for options storage.

### 3. Block (Gutenberg) Development Protocol
- **Metadata-Driven:** Define blocks using `block.json` with `apiVersion: 3` (WordPress 6.9+ standard) to ensure correct block iframe behavior.
- **Edit/Save/Render Patterns:**
  - In the Editor: Wrap component markup with `useBlockProps()`.
  - Static blocks (markup saved in database): Use `useBlockProps.save()` in `save()`.
  - Dynamic blocks (server-rendered): Set `"render": "file:./render.php"` in `block.json` (or use PHP `render_callback`) and keep `save()` returning `null`. Use `get_block_wrapper_attributes()` in PHP.
- **Block Composition:** Use `useInnerBlocksProps()` for container-like blocks.
- **Deprecations & Migrations:** If modifying saved markup/attributes, add a `deprecated` array (newest to oldest) in the client script to avoid "Invalid block" errors.

### 4. Block Themes & theme.json Protocol
- **Global Settings & Styles:** Use `theme.json` to define typography scales, color presets, layout constraints, and per-block custom styles.
- **Templates & Template Parts:** Place HTML templates under `templates/` and parts under `parts/`. Do not nest parts in subdirectories.
- **Style Variations:** Define style presets in JSON files inside `styles/`. Remember that once a user selects a variation in the editor, it is saved in the database, overriding file-level changes.
- **Patterns:** Prefer theme-registered patterns located under `patterns/*.php` for modular reuse.

### 5. Interactivity API & Hydration Protocol
- **Server-Side Rendering (SSR) first:** Always pre-render interactive markup on the server to prevent Layout Shift (CLS) and ensure SEO indexability.
- **Directive Processing:** Enable server-side directive parsing by declaring `"interactivity": true` inside the block's `"supports"` config.
- **State Initialization:**
  - Global state (PHP): Define initial state using `wp_interactivity_state('pluginNamespace', $initialStateArray)`.
  - Local context (PHP): Output context wrapper attributes using `wp_interactivity_data_wp_context($contextArray)`.
- **Directives:** Use `data-wp-interactive`, `data-wp-context`, `data-wp-bind`, `data-wp-on`, and custom store stores. **Avoid the deprecated `data-wp-ignore` directive**.

### 6. REST API & Endpoint Registration Protocol
- **Route Registration:** Register custom REST routes during the `rest_api_init` hook using `register_rest_route()`.
- **Namespace:** Use a unique namespace format like `vendor/v1` (avoid `wp/v2` unless core).
- **Authentication & Validation:**
  - Always enforce a `permission_callback` (use `__return_true` for public endpoints).
  - Perform authorization checks via WordPress user capabilities (e.g. `current_user_can('manage_options')`).
  - Validate request parameters via request schema/args configurations using `validate_callback` and `sanitize_callback`.
- **Response:** Enclose responses inside `rest_ensure_response()` or `WP_REST_Response`. Use `WP_Error` with explicit HTTP status codes for errors.

### 7. WP-CLI Operations & Scripting
- **Ops Safety:** Perform database exports/backups before executing destructive commands.
- **Site Targeting:** Enforce `--path=<wp-path>` and, for multisites, `--url=<site-url>` to target correct environments.
- **URL Migration:** Use `wp search-replace --dry-run` to inspect changes before running URL replacements on serialized data.
- **Automation:** Build repeatable operations scripts using `wp-cli.yml` configuration defaults.

### 8. Performance Profiling & Database Optimization
- **Database & Queries:** Reduce total queries, avoid N+1 query patterns. Prefer `WP_Query` or `get_posts` over raw SQL. Use `$wpdb->prepare()` if raw SQL is necessary.
- **Autoload Bloat:** Audit and optimize autoloaded options. Large data arrays should be converted to transients or standard non-autoloaded options.
- **Caching:** Integrate persistent object caching (`wp_cache_set`, `wp_cache_get`) for heavy database operations.
- **Remote API calls:** Enforce HTTP request timeouts (`wp_remote_get`, `wp_remote_post`) and cache the results to prevent render blocking.

## 🚫 Guard Rails (Security & Anti-patterns)
- **Sanitize & Escape:** Validate/sanitize input early, escape output late (use `esc_html`, `esc_attr`, `esc_url`, `wp_kses`).
- **CSRF Prevention:** Implement and verify nonces on all admin actions, AJAX hooks, and REST requests.
- **Core Hook Safety:** Do not modify Core files or third-party plugin codes directly; always utilize actions, filters, or child themes.
- **Plugin Sourcing:** Strictly forbid using cracked, nulled, or unverified plugins.