Two-phase site building with a new skill to convert html blocks to core Gutenberg blocks

apps/cli/ai/plugin/skills/blockify/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: blockify
+description: Convert all core/html blocks in a WordPress site to native Gutenberg blocks. Run this after building a site (Phase 2) or on any existing site that uses custom HTML blocks.
+user-invokable: true
+---
+
+# Block Conversion (Blockify)
+
+Convert all `core/html` blocks in a site's pages, posts, and template parts to native Gutenberg blocks. The CSS stays untouched — the visual output must remain identical.
+
+**The goal is FAITHFUL CONVERSION.** Convert every `core/html` block that has a native block equivalent. Do not make editorial decisions about what to skip. Do not "improve" or simplify the structure. Reproduce the exact same content using native blocks.
+
+## How to Run
+
+### Step 1 — Read back all content
+
+Retrieve every piece of block content. You MUST read ALL of these before proceeding:
+- Page/post content: `wp_cli post list --post_type=page,post --fields=ID,post_title` then `wp_cli post get <id> --field=post_content` for each
+- Template part files: Read header.html, footer.html, and ALL other template part files from the theme's `parts/` directory
+
+Do NOT skip template parts — they often contain navigation, hero sections, or footer content that needs conversion.
+
+### Step 2 — Audit every core/html block
+
+Before planning the conversion, list every `core/html` block you found across all content. For each one, state:
+- Where it is (page/post name or template part file)
+- What HTML it contains (the wrapper tag and a brief summary)
+- What it will become: the specific native block(s), OR `core/html` (kept) with the reason
+
+Example:
+```
+1. Homepage hero wrapper: <section class="hero-section"> with heading, paragraph, buttons, image, scroll indicator
+   → core/group (tagName="section") with inner core/heading + core/paragraph + core/buttons + core/image + core/html (scroll indicator only)
+2. Homepage script tag: <script src="iconify">
+   → core/html (kept — script tag, no block equivalent)
+3. Header nav logo: <div class="logo"><a>Site Name</a></div>
+   → core/group with inner core/paragraph
+```
+
+This audit ensures nothing is silently skipped. Every `core/html` block must be accounted for.
+
+### Step 3 — Plan the conversion element-by-element (using audit from Step 2)
+
+**CRITICAL: Always decompose.** Never keep an entire section as `core/html` just because it contains some non-convertible sub-elements. Break the section apart: convert every convertible element to native blocks and isolate only the truly non-convertible elements as individual `core/html` blocks.
+
+For example, a hero section with a heading, paragraph, buttons, image, AND a scroll-indicator animation should become: `core/group` > `core/heading` + `core/paragraph` + `core/buttons` + `core/image` + `core/html` (scroll indicator only). Do NOT keep the entire hero as `core/html`.
+
+For each section of content, decide what converts to native blocks and what stays as `core/html`:
+
+| HTML | Gutenberg block |
+|------|----------------|
+| `<section>`, `<div>`, `<header>`, `<footer>`, `<aside>` | `core/group` with appropriate `tagName` |
+| `<h1>`–`<h6>` | `core/heading` with matching `level` |
+| `<p>` | `core/paragraph` |
+| `<a class="btn">` / CTA links | `core/buttons` + `core/button` |
+| CSS grid/flex layouts with `<div>` children | `core/columns` + `core/column` |
+| `<ul>` / `<ol>` | `core/list` + `core/list-item` |
+| `<img>` | `core/image` |
+| `<figure>` | `core/image` or `core/media-text` |
+| `<blockquote>` | `core/quote` |
+| `<table>` | `core/table` |
+| `<hr>` | `core/separator` |
+| Empty spacing `<div>` | `core/spacer` |
+
+Keep `core/html` ONLY for individual elements with no native block equivalent:
+- Inline SVGs (icons, illustrations, decorative graphics)
+- `<form>` elements and interactive inputs
+- `<canvas>`, `<iframe>`, `<video>`, `<audio>`
+- Animation/interaction markup (marquee, custom cursor, scroll-triggered elements)
+- Elements needing custom `data-*` attributes for JS interactivity
+- `<script>` tags — always extract into their own separate `core/html` block, never bundled with structural content
+
+**Things that are NOT valid reasons to keep an element as `core/html`:**
+- `id` attributes — `core/group` supports `anchor` for element IDs
+- Inline `<em>`, `<strong>`, `<br>`, `<a>` inside text — `core/heading` and `core/paragraph` support inline HTML
+- `loading="eager"` on images — drop the attribute rather than keeping the whole section as HTML
+- A single non-convertible child — decompose the section instead of skipping it entirely
+- Small text-containing `<div>` or `<span>` elements (eyebrow text, labels, captions, taglines) — convert to `core/paragraph` with the appropriate `className`
+- Decorative wrapper `<div>` elements — convert to `core/group` with `className`
+- **Section wrappers with background images, overlays, or gradients** — these are always `core/group` with `className`. All visual effects (background-image, overlays, pseudo-elements, gradients) are handled by CSS targeting the className, not by the block markup. There is no reason to keep a `<section>` or `<div>` wrapper as `core/html` because of its visual styling.
+
+**Be thorough.** Convert every single element that has a native block equivalent. Do not leave small or simple elements as `core/html` out of convenience. A `<div>` with text inside it is a `core/paragraph` or `core/group`, not a Custom HTML block.
+
+All CSS classes from the original design stay in style.css — the visual output must remain identical after conversion.
+
+### Step 4 — Write the converted content
+
+Rewrite the full content for each page/post and template part using native Gutenberg block markup. Use the block patterns below as reference. Update posts via `wp_cli post update` and template parts via Write/Edit.
+
+**IMPORTANT — CSS migration must be atomic replacements, not additions.** When converting elements to native blocks, the block markup changes the DOM structure (e.g., a bare `<a class="btn-gold">` becomes `<div class="wp-block-button btn-gold"><a class="wp-block-button__link wp-element-button">`). The Phase 1 CSS rules targeting the old selectors will now apply to the wrong elements, causing double borders, double backgrounds, and broken layouts.
+
+**The rule:** Every time you write a new block-scoped CSS rule, you MUST delete the Phase 1 rule it replaces. One rule out, one rule in. Never leave both.
+
+For example, when converting buttons:
+- **Delete** the Phase 1 rule: `.btn-gold { background: gold; border: 2px solid gold; padding: 1rem 2rem; }`
+- **Replace** with a block-scoped rule: `.wp-block-button.btn-gold .wp-block-button__link { background: gold; border: 2px solid gold; padding: 1rem 2rem; }`
+
+This applies to all converted elements, not just buttons. If a Phase 1 rule targeted a bare class that is now a `className` on a block wrapper, rewrite the rule to target the correct block DOM structure.
+
+## Block pattern reference
+
+### Section wrapper
+
+Replaces `<section>`, `<div>`, `<aside>`, `<header>`, `<footer>`:
+```
+<!-- wp:group {"tagName":"section","className":"hero-section","layout":{"type":"default"}} -->
+<section class="wp-block-group hero-section">
+  <!-- inner blocks go here -->
+</section>
+<!-- /wp:group -->
+```
+
+### Heading
+
+Replaces `<h1>`–`<h6>`:
+```
+<!-- wp:heading {"level":1,"className":"hero-title"} -->
+<h1 class="wp-block-heading hero-title">Your Title</h1>
+<!-- /wp:heading -->
+```
+
+### Paragraph
+
+Replaces `<p>`:
+```
+<!-- wp:paragraph {"className":"hero-subtitle"} -->
+<p class="hero-subtitle">Your text here.</p>
+<!-- /wp:paragraph -->
+```
+
+### Columns layout
+
+Replaces CSS grid/flex with `<div>` children:
+```
+<!-- wp:columns {"className":"features-grid"} -->
+<div class="wp-block-columns features-grid">
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+  <!-- wp:column -->
+  <div class="wp-block-column">
+    <!-- inner blocks -->
+  </div>
+  <!-- /wp:column -->
+</div>
+<!-- /wp:columns -->
+```
+
+### Image
+
+Replaces `<img>`:
+```
+<!-- wp:image {"className":"hero-image"} -->
+<figure class="wp-block-image hero-image"><img src="https://example.com/image.jpg" alt="Description"/></figure>
+<!-- /wp:image -->
+```
+
+### Buttons
+
+Replaces `<a class="btn">`:
+```
+<!-- wp:buttons {"className":"hero-cta"} -->
+<div class="wp-block-buttons hero-cta">
+  <!-- wp:button {"className":"primary-btn"} -->
+  <div class="wp-block-button primary-btn"><a class="wp-block-button__link wp-element-button" href="#">Get Started</a></div>
+  <!-- /wp:button -->
+</div>
+<!-- /wp:buttons -->
+```
+
+**CRITICAL — Where button CSS goes.** A `core/button` renders two stacked elements: the `.wp-block-button` wrapper and the `.wp-block-button__link` anchor inside. ALL visual paint (background, border, padding, color, font, hover, transitions, shadow, border-radius) MUST target `.wp-block-button.<className> .wp-block-button__link`. The `.wp-block-button` wrapper carries ZERO paint — give it only layout properties (margin, flex alignment) if any. Putting paint on the wrapper creates the classic "button inside a button" double-background/double-border effect.
+
+For example, when migrating `.btn-gold { background: gold; border: 2px solid gold; padding: 1rem 2rem; color: black; }`:
+
+- **Correct** (all paint on the inner link):
+  ```css
+  .wp-block-button.btn-gold .wp-block-button__link {
+    background: gold;
+    border: 2px solid gold;
+    padding: 1rem 2rem;
+    color: black;
+  }
+  ```
+- **Wrong** (paint on the wrapper — produces the double-layer effect):
+  ```css
+  .wp-block-button.btn-gold {
+    background: gold;
+    border: 2px solid gold;
+    padding: 1rem 2rem;
+  }
+  ```
+
+### List
+
+Replaces `<ul>` / `<ol>`:
+```
+<!-- wp:list {"className":"feature-list"} -->
+<ul class="feature-list">
+  <!-- wp:list-item -->
+  <li>First item</li>
+  <!-- /wp:list-item -->
+  <!-- wp:list-item -->
+  <li>Second item</li>
+  <!-- /wp:list-item -->
+</ul>
+<!-- /wp:list -->
+```
+
+### Separator
+
+Replaces `<hr>`:
+```
+<!-- wp:separator {"className":"section-divider"} -->
+<hr class="wp-block-separator section-divider"/>
+<!-- /wp:separator -->
+```
+
+## Nesting blocks
+
+Sections are built by nesting blocks inside `core/group`. All visual styling (grid layouts, spacing, colors, backgrounds, animations) goes in `style.css` targeting the `className`. The block structure is for editability; the CSS is for aesthetics.
+
+## Additional rules
+
+- Never use `core/html` to wrap text content, headings, layout sections, or lists.
+- No decorative HTML comments (e.g. `<!-- Hero Section -->`, `<!-- Features -->`). Only block delimiter comments are allowed.
+- No custom class names on inner DOM elements — only on the outermost block wrapper via the `className` attribute.
+- No inline `style` or `style` block attributes for styling. Use `className` + `style.css` instead.
+- Use `core/spacer` for empty spacing divs, not `core/group`.
+- No emojis anywhere in generated content.
+- Adding `data-*` attributes does NOT make a block acceptable — use `className` on `core/group` blocks instead.

apps/cli/ai/system-prompt.ts

@@ -114,9 +114,10 @@ Then continue with:
 1. **Get site details**: Use site_info to get the site path, URL, and credentials.
 2. **Plan the design**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing.
 3. **Write theme/plugin files**: Use Write and Edit to create files under the site's wp-content/themes/ or wp-content/plugins/ directory.
-4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` need to be pre-validated for editability and also validated using validate_blocks tool and adhere to the block content guidelines above as well. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
-5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again.
-6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations.
+4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` needs to adhere to the block content guidelines above. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
+5. **Convert HTML blocks to native Gutenberg blocks (MANDATORY)**: Invoke the \`blockify\` skill via the Skill tool. This step is required on every site build — your initial content is HTML, and \`blockify\` converts it to native Gutenberg blocks for WordPress editability. Do not proceed to step 6 until \`blockify\` has run. When you build your todo list, this step MUST appear as its own item; do not collapse it into validation or screenshots.
+6. **Final block validation**: Run \`validate_blocks\` on all converted content as a final safety guard. If any blocks are invalid, fix the markup and re-run until everything passes.
+7. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations. **Cap this step at 2 screenshot → fix cycles.** If an issue persists after 2 attempts, trust your CSS source over the screenshot and move on — thumbnails frequently misrepresent grid/flex layouts as "stacked". During this step, do NOT: add \`!important\` to fight injected styles; write forensic PHP scripts or run \`wp_cli eval\` to inspect \`the_content\`/rendered markup; read or grep WordPress core block CSS files. If your class-scoped CSS looks correct, trust it.
 
 ## Available Studio Tools (prefixed with mcp__studio__)
 
@@ -131,7 +132,7 @@ Then continue with:
 - preview_update: Update an existing hosted WordPress.com preview from a local site; this can take a few minutes, so tell the user to wait
 - preview_delete: Delete a hosted WordPress.com preview by hostname
 - wp_cli: Run WP-CLI commands on a running site
-- validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call after every file write/edit that contains block content.
+- validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call at the end of the workflow as a final safety guard after the \`blockify\` skill has converted content.
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - audit_performance: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
 

apps/cli/ai/tools.ts

@@ -539,7 +539,8 @@ const runWpCliTool = tool(
 const validateBlocksTool = tool(
 	'validate_blocks',
 	"Validates WordPress block content by running each block through its save() function in the site's block editor (real browser). " +
-		'The site must be running. Returns per-block validation results with expected HTML for invalid blocks.',
+		'Catches invalid attributes, malformed nesting, and markup mismatches. ' +
+		'The site must be running. Returns per-block validation results.',
 	{
 		nameOrPath: z
 			.string()
@@ -571,6 +572,7 @@ const validateBlocksTool = tool(
 
 			const site = await resolveSite( args.nameOrPath );
 			const siteUrl = getSiteUrl( site );
+
 			const report = await validateBlocks( blockContent, siteUrl );
 
 			if ( report.error ) {