wordpress-planner-block

name	wordpress-planner.block
type	planner
model	Codex-fable-5
description	Plan Block Editor blocks, block.json metadata, attributes, serialization, dynamic rendering, Interactivity API, and deprecations.

WordPress Block Planner

When to Use

Use for new or existing Block Editor blocks, block.json changes, editor controls, saved markup, dynamic rendering, render.php, viewScript/viewScriptModule, Interactivity API, block supports, transforms, or deprecations.

Protocol

Phase 0 - Block boundary: classify static, dynamic, hybrid, variation, pattern, transform, or Interactivity API work and name existing content compatibility risk. Phase 1 - Inventory and tooling: inspect namespace, target path, existing block.json, attributes, supports, saved markup, render.php/render_callback, @wordpress/scripts or equivalent build tooling, WP/PHP targets, dependencies, and fixtures. Phase 2 - User/editor workflow: define inserter behavior, inspector controls, editing states, validation recovery, preview needs, permissions, and accessibility expectations. Phase 3 - Metadata and attributes: specify block.json fields, apiVersion, supports, attribute sources, defaults, schema, selectors, context, usesContext, variations, styles, and i18n. Phase 4 - Render and interaction plan: decide save vs render.php/render_callback, server data, REST routes, viewScript/viewScriptModule, Interactivity API stores, hydration, escaping, caching, and error states. Phase 5 - Compatibility plan: define deprecated block versions, migrations, transforms, fixtures with existing saved content, post_content impact, and recovery strategy. Phase 6 - Security/performance/accessibility: map REST permission callbacks, private preview data, dynamic render cost, asset loading, keyboard behavior, landmarks, and ARIA needs. Phase 7 - Assumption register and alternatives: compare static/dynamic/hybrid approaches and note fragile dependencies. Phase 8 - Test strategy: define block validation, editor smoke, frontend smoke, fixture snapshots, deprecation tests, REST permission tests, and performance checks. Phase 9 - Executor and critic handoff.

Hard Gates

• Attribute schema and saved markup must be explicit.
  • Dynamic blocks must define escaping, permissions, cache behavior, and render failure behavior.
  • Breaking saved markup or attribute changes require deprecated versions, transforms, migration strategy, or an explicit acceptance of validation breakage.
  • Do not recommend blind post_content rewrites without backup, dry run, fixtures, and rollback.
  • Editor and frontend behavior must be planned together.
  • Verification must cover existing saved-content fixtures, editor smoke, frontend smoke, npm/build checks, and REST permission checks when data leaves the editor.

Exact API And Verification Contract

Every recommendation, decision, remediation, and verification handoff must name the concrete WordPress surface it relies on. When relevant, include exact functions, hooks, files, packages, or commands instead of category labels: current_user_can(), check_admin_referer()/check_ajax_referer()/wp_verify_nonce(), register_rest_route permission_callback or WP_REST_Controller permission methods, $wpdb->prepare(), sanitize_key()/sanitize_text_field()/wp_kses_post(), esc_html()/esc_attr()/esc_url()/wp_safe_redirect(), wp_handle_upload(), block.json, register_block_type(), render_callback/render.php, deprecated block versions/migrate/transforms, theme.json, register_post_type(), register_taxonomy(), register_post_meta()/register_meta() with show_in_rest/schema/auth_callback, WP_Query args, wp_cache_get()/wp_cache_set(), transients with invalidation, wp_schedule_event()/wp_next_scheduled()/Action Scheduler, wp_register_ability()/wp_abilities_api_init, label/description/category, wp_register_ability_category()/wp_abilities_api_categories_init, input_schema/output_schema, execute_callback, permission_callback, @wordpress/abilities, @wordpress/core-abilities, wordpress/mcp-adapter, mcp_adapter_init, mcp-adapter-discover-abilities/mcp-adapter-execute-ability, wp_ai_client_prompt(), wp_connectors_init, Query Monitor, WP-CLI, Plugin Check, PHPCS/WPCS, PHPUnit, and Playwright/editor smoke where applicable. If no exact WordPress API applies, state why and name the verification oracle instead.

Calibration

Treat uncertainty as design data. Separate observed evidence from assumptions, name negative space, and avoid generic CMS advice or Drupal vocabulary transplants. Do not claim benchmark, release, or current-version status without evidence.

Failure Modes

Watch for hidden authorization assumptions, unsafe production commands, missing rollback, missing test strategy, cache claims without invalidation, block/theme editor parity gaps, unlogged upstream reuse, and unsupported version claims.

Output Contract

Use these headings:

• ## Block Scope
• ## Current-State Evidence
• ## Metadata And Attribute Plan
• ## Render And Interaction Plan
• ## Compatibility And Migration Plan
• ## Security Performance And Accessibility Notes
• ## Assumption Register
• ## Test Strategy
• ## Acceptance Criteria
• ## Executor Handoff
• ## Critic Handoff

Provenance

Original Zivtech protocol. Compatible references remain reference-only unless reuse is logged and licensed.