migrate-brizy-to-gutenberg

Migrate Brizy to Gutenberg

Full-site migration from Brizy Builder to the WordPress block editor (Gutenberg). Audits every Brizy-built page, maps components to their Gutenberg block equivalents, builds a migration plan for approval, and executes page-by-page conversion into native block markup — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Brizy to Gutenberg, switching from Brizy to blocks, converting Brizy pages to the block editor, or moving away from Brizy to native WordPress.

What This Skill Does

Brizy uses a proprietary content format with its own component system, storing data in brizy_post_uid and related custom meta fields. Gutenberg uses a flat block structure in post_content with HTML comment delimiters. The migration requires extracting Brizy's custom format, identifying each component type, and translating it to equivalent core Gutenberg blocks.

This skill reads every Brizy page, extracts the builder content, translates each component to its Gutenberg block equivalent, and writes the result to duplicate pages in native block markup — giving you a complete parallel version of your site to review before going live.

Handles:

• Section → Group block mapping
• Row/Column → Columns/Column block mapping
• Text components → Paragraph/Heading blocks
• Image components → Image block
• Button components → Buttons/Button block
• Video components → Video/Embed block
• Icon components → basic equivalents
• Spacer/Divider → Spacer/Separator blocks
• Map component → basic embed fallback
• Form elements → flagged for manual handling (Contact Form 7 or similar)
• Custom HTML/embed content

What This Skill Does NOT Do

• Migrate Brizy's global styling system — must be recreated in theme settings or Global Styles
• Convert Brizy popup designs — Gutenberg has no native popup system
• Replicate Brizy's built-in form submissions — a separate form plugin is needed
• Migrate Brizy Cloud templates or synced content
• Convert Brizy Pro dynamic content features — flagged for manual handling
• Preserve Brizy's hover effects and animations — Gutenberg has limited animation support
• Guarantee pixel-perfect visual parity — different rendering approaches

Requirements

• Respira for WordPress plugin installed and connected
• MCP connection active (desktop or WebMCP)
• Brizy Builder active on the source site
• Read access to scan Brizy content
• Write access to create duplicates with Gutenberg content

Trigger Phrase

• "migrate brizy to gutenberg"

Alternative Triggers

• "convert brizy to blocks"
• "switch from brizy to gutenberg"
• "move brizy to block editor"
• "replace brizy with gutenberg"
• "brizy to wordpress blocks"
• "migrate brizy to native wordpress"

Builder Technical Context

Source: Brizy

• Content stored in post_meta key brizy_post_uid and Brizy's custom format
• Proprietary component structure with sections, rows, columns, and elements
• Read via wordpress_extract_builder_content with builder=brizy
• Components: sections, rows, columns, text, image, button, video, icon, spacer, map, form, embed, etc.

Target: Gutenberg (Block Editor)

• Content stored in post_content as HTML with block comment delimiters
• Format: <!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->
• Write via standard WordPress content tools (wordpress_update_page / wordpress_update_post)
• Core blocks: paragraph, heading, image, buttons, columns, group, html, video, separator, spacer, embed, etc.

Execution Workflow

Phase 1: Pre-Migration Audit

1. Verify Respira + MCP connection via wordpress_get_site_context. If unavailable, stop and show setup guidance.
2. Detect Brizy presence via wordpress_get_builder_info or wordpress_list_plugins.
3. Inventory all Brizy-built content:
4. wordpress_list_pages and wordpress_list_posts — identify all content
5. wordpress_find_builder_targets with builder=brizy — find Brizy-managed pages
6. For each Brizy page, extract content:
7. wordpress_extract_builder_content with builder=brizy
8. Catalog: component types used, nesting depth, popups, forms, dynamic content usage
9. Produce an Audit Report:
10. Total pages/posts using Brizy
11. Component type frequency (how many sections, text blocks, images, etc.)
12. Complexity flags (popups, forms, dynamic content, Brizy Pro features)
13. Estimated migration difficulty per page (simple / moderate / complex)

Phase 2: Migration Plan

Present a structured migration plan:

## Brizy → Gutenberg Migration Plan

### Site Overview
- Total Brizy pages: X
- Simple pages (direct mapping): X
- Moderate pages (some manual review needed): X
- Complex pages (significant manual work): X

### Component Mapping
| Brizy Component | Gutenberg Block | Notes |
|---|---|---|
| Section | Group | Container mapping |
| Row / Columns | Columns / Column | Layout structure |
| Text | Paragraph / Heading | Content parsed into blocks |
| Image | Image | Direct mapping |
| Button | Buttons > Button | Wrapped in container |
| ... | ... | ... |

### Migration Order
1. [Page Title] — Simple — estimated 2 min
2. [Page Title] — Moderate — estimated 5 min
...

### Items Requiring Manual Attention
- [Page X] — Brizy popup (no Gutenberg equivalent)
- [Page Y] — Brizy form (needs form plugin replacement)
- Global styles — must be configured in theme settings

Then ask:

Here's the migration plan. Would you like me to:

1. Migrate all pages (creates duplicates for review)

2. Migrate only simple pages first

3. Migrate specific pages you choose

4. Just keep this as a reference — no changes

Wait for explicit confirmation before proceeding.

Phase 3: Page-by-Page Migration

For each approved page:

1. Extract Brizy content via wordpress_extract_builder_content with builder=brizy
2. Map each Brizy component to Gutenberg blocks:
3. Sections → <!-- wp:group --> blocks
4. Rows/Columns → <!-- wp:columns --> with <!-- wp:column --> children
5. Text → Parse into <!-- wp:paragraph --> and <!-- wp:heading --> blocks
6. Image → <!-- wp:image --> with src, alt, caption
7. Button → <!-- wp:buttons --> wrapper with <!-- wp:button --> child
8. Video → <!-- wp:video --> or <!-- wp:embed --> block
9. Spacer → <!-- wp:spacer --> block
10. Custom HTML → <!-- wp:html --> block
11. Preserve text content, image URLs, link targets
12. Flag unmappable components with <!-- wp:paragraph --><p>[MIGRATION NOTE: ...]</p><!-- /wp:paragraph -->
13. Assemble the complete Gutenberg block markup
14. Create a duplicate via wordpress_create_page_duplicate or wordpress_create_post_duplicate
15. Update the duplicate's post_content with the Gutenberg markup via wordpress_update_page or wordpress_update_post
16. Log the migration result (success, warnings, manual review items)

Phase 4: Post-Migration Verification

1. Summarize all migrated pages with status:
2. Clean migrations (no issues)
3. Migrations with warnings (flagged items needing review)
4. Failed migrations (if any)
5. List all manual review items:
6. Popups that need a separate popup plugin solution
7. Forms that need a WordPress form plugin (Contact Form 7, WPForms, etc.)
8. Dynamic content that needs reconnecting
9. Brizy Pro features that have no Gutenberg equivalent
10. Provide review instructions:
11. Where to find duplicates in WordPress admin
12. How to preview pages in the block editor
13. How to delete duplicates if not wanted

Safety Model

• Read-only analysis first — full Brizy content audit before any changes
• Explicit user confirmation before creating any duplicates
• Duplicate-first only — never modifies live/published Brizy content
• Never auto-publishes duplicates
• Provides rollback guidance (delete duplicates if not wanted)
• Preserves all original Brizy content untouched

Honest Disclaimer

This skill converts Brizy p