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.