@ai-kits/wp-ag-kit 1.0.0

package/skills/wp-block-themes/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: wp-block-themes
+description: "Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Block Themes
+
+## When to use
+
+Use this skill for block theme work such as:
+
+- editing `theme.json` (presets, settings, styles, per-block styles)
+- adding or changing templates (`templates/*.html`) and template parts (`parts/*.html`)
+- adding patterns (`patterns/*.php`) and controlling what appears in the inserter
+- adding style variations (`styles/*.json`)
+- debugging “styles not applying” / “editor doesn’t reflect theme.json”
+
+## Inputs required
+
+- Repo root and which theme is targeted (theme directory if multiple exist).
+- Target WordPress version range (theme.json version and features vary by core version).
+- Where the issue manifests: Site Editor, post editor, frontend, or all.
+
+## Procedure
+
+### 0) Triage and locate block theme roots
+
+1. Run triage:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Detect theme roots + key folders:
+   - `node skills/wp-block-themes/scripts/detect_block_themes.mjs`
+
+If multiple themes exist, pick one and scope all changes to that theme root.
+
+### 1) Create a new block theme (if needed)
+
+If you are creating a new block theme from scratch (or converting a classic theme):
+
+- Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
+- Be explicit about the minimum supported WordPress version because `theme.json` schema versions differ.
+
+Read:
+- `references/creating-new-block-theme.md`
+
+After creating the theme root, re-run `detect_block_themes` and continue below.
+
+### 2) Confirm theme type and override expectations
+
+- Block theme indicators:
+  - `theme.json` present
+  - `templates/` and/or `parts/` present
+- Remember the style hierarchy:
+  - core defaults → theme.json → child theme → user customizations
+  - user customizations can make theme.json edits appear “ignored”
+
+Read:
+- `references/debugging.md` (style hierarchy + fastest checks)
+
+### 3) Make `theme.json` changes safely
+
+Decide whether you are changing:
+
+- **settings** (what the UI allows): presets, typography scale, colors, layout, spacing
+- **styles** (how it looks by default): CSS-like rules for elements/blocks
+
+Read:
+- `references/theme-json.md`
+
+### 4) Templates and template parts
+
+- Templates live under `templates/` and are HTML.
+- Template parts live under `parts/` and must not be nested in subdirectories.
+
+Read:
+- `references/templates-and-parts.md`
+
+### 5) Patterns
+
+Prefer filesystem patterns under `patterns/` when you want theme-owned patterns.
+
+Read:
+- `references/patterns.md`
+
+### 6) Style variations
+
+Style variations are JSON files under `styles/`. Note: once a user picks a style variation, that selection is stored in the DB, so changing the file may not “update what the user sees” automatically.
+
+Read:
+- `references/style-variations.md`
+
+## Verification
+
+- Site Editor reflects changes where expected (Styles UI, templates, patterns).
+- Frontend renders with expected styles.
+- If styles aren’t changing, confirm whether user customizations override theme defaults.
+- Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).
+
+## Failure modes / debugging
+
+Start with:
+
+- `references/debugging.md`
+
+Common issues:
+
+- wrong theme root (editing an inactive theme)
+- user customizations override your defaults
+- invalid `theme.json` shape/typos prevent application
+- templates/parts in wrong folders (or nested parts)
+
+## Escalation
+
+If upstream behavior is unclear, consult canonical docs:
+
+- Theme Handbook and Block Editor Handbook for `theme.json`, templates, patterns, and style variations.

package/skills/wp-block-themes/references/creating-new-block-theme.md

@@ -0,0 +1,37 @@
+# Creating a new block theme
+
+Use this file when you need to create a new block theme or convert a theme to block theme structure.
+
+## Two practical starting points
+
+1. **Export from a WP environment**
+   - Use the official “Create Block Theme” plugin to generate/export a theme from the Site Editor.
+   - This tends to produce a structure aligned with current WordPress behavior.
+
+2. **Create the minimal filesystem structure**
+   - Create a theme folder with:
+     - `style.css` (theme header)
+     - `theme.json` (global settings/styles)
+     - `templates/index.html` (minimum viable template)
+     - `parts/header.html` and `parts/footer.html` (recommended)
+
+## References
+
+- Create Block Theme plugin:
+  - https://wordpress.org/plugins/create-block-theme/
+- Block theme structure:
+  - https://developer.wordpress.org/themes/block-themes/theme-structure/
+- Required templates:
+  - https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/
+
+## theme.json version choice (compatibility)
+
+`theme.json` has schema versions. Pick the highest version that matches your minimum supported WordPress version.
+
+References:
+
+- Theme Handbook introduction:
+  - https://developer.wordpress.org/themes/global-settings-and-styles/introduction-to-theme-json/
+- Theme.json version 3 dev note:
+  - https://make.wordpress.org/core/2024/06/19/theme-json-version-3/
+

package/skills/wp-block-themes/references/debugging.md

@@ -0,0 +1,24 @@
+# Debugging block theme issues
+
+## Styles not applying
+
+Fast checks:
+
+1. Confirm you edited the active theme (Site Editor → theme).
+2. Check if user customizations exist (they override theme defaults).
+3. Validate `theme.json` structure (typos can prevent styles from applying).
+
+Remember the hierarchy:
+
+- core defaults → theme.json → child theme → user customizations
+
+## Templates/parts not showing
+
+- Ensure files are in the correct folders (`templates/`, `parts/`).
+- Template parts must not be nested in subdirectories.
+
+## Style variations not updating
+
+- If a user already selected the variation, the selection is stored in the DB.
+- Test with a fresh site/user or reset customizations when appropriate.
+

package/skills/wp-block-themes/references/patterns.md

@@ -0,0 +1,18 @@
+# Patterns (filesystem patterns)
+
+Use this file when adding patterns that should be available in the inserter.
+
+## Filesystem patterns
+
+- Put patterns in `patterns/*.php`.
+- Patterns are registered automatically by WordPress core based on file headers.
+
+Upstream reference:
+
+- https://developer.wordpress.org/themes/patterns/
+
+## Practical guardrails
+
+- Keep pattern markup stable; changing block names inside patterns can break older content in subtle ways.
+- If a pattern should not be inserted directly by users, mark it as non-inserter / internal-only (per upstream header conventions).
+

package/skills/wp-block-themes/references/style-variations.md

@@ -0,0 +1,14 @@
+# Style variations (`styles/*.json`)
+
+Use this file when adding or debugging style variations.
+
+Key points:
+
+- Style variations are JSON files in `styles/`.
+- Users can pick a style variation in the UI.
+- Once selected, the choice is stored in the DB (so “changing the JSON file” may not update what a user already selected).
+
+Upstream reference:
+
+- https://developer.wordpress.org/themes/global-settings-and-styles/style-variations/
+

package/skills/wp-block-themes/references/templates-and-parts.md

@@ -0,0 +1,16 @@
+# Templates and template parts
+
+Use this file when creating or editing HTML templates/parts.
+
+## Key folders
+
+- `templates/` for templates.
+- `parts/` for template parts.
+
+Template parts must not be nested in subdirectories.
+
+Upstream references:
+
+- Templates + parts overview: https://developer.wordpress.org/themes/block-themes/theme-structure/
+- Template parts details: https://developer.wordpress.org/themes/block-themes/template-parts/
+

package/skills/wp-block-themes/references/theme-json.md

@@ -0,0 +1,59 @@
+# `theme.json` guidance
+
+Use this file when changing global settings/styles or per-block styling.
+
+## High-level structure
+
+Common top-level keys:
+
+- `version`
+- `settings` (what the UI exposes / allows)
+- `styles` (default appearance)
+- `customTemplates` and `templateParts` (optional, to describe templates and parts)
+
+Upstream references:
+
+- Theme Handbook: https://developer.wordpress.org/themes/global-settings-and-styles/
+- Block Editor Handbook (often more current): https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/
+- Theme JSON living reference: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/
+- Theme JSON version 3 (dev note): https://make.wordpress.org/core/2024/06/19/theme-json-version-3/
+
+## Practical guardrails
+
+- Prefer presets when you want editor-visible controls (colors, font sizes, spacing).
+- Prefer `styles` when you want consistent defaults without requiring user choice.
+- Be careful with specificity: user global styles override theme defaults.
+
+## WordPress 6.9 additions
+
+**Form element styling:**
+- Style text inputs and selects via `styles.elements` (e.g., `styles.elements.input`, `styles.elements.select`).
+- Supports border, color, outline, shadow, and spacing properties.
+- Note: Focus state styling is not yet available in 6.9.
+
+**Border radius presets:**
+- Define presets in `settings.border.radiusSizes` for visual selection in the border radius control.
+- Users can still enter custom values.
+
+```json
+{
+  "settings": {
+    "border": {
+      "radiusSizes": [
+        { "name": "Small", "slug": "small", "size": "4px" },
+        { "name": "Medium", "slug": "medium", "size": "8px" },
+        { "name": "Large", "slug": "large", "size": "16px" }
+      ]
+    }
+  }
+}
+```
+
+**Button pseudo-classes:**
+- Style Button block hover and focus states directly in theme.json.
+- No longer requires custom CSS for simple button state styling.
+
+References:
+
+- Border radius presets: https://make.wordpress.org/core/2025/11/12/theme-json-border-radius-presets-support-in-wordpress-6-9/
+- Form element styling: https://developer.wordpress.org/news/2025/11/how-wordpress-6-9-gives-forms-a-theme-json-makeover/

package/skills/wp-block-themes/scripts/detect_block_themes.mjs

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+]);
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function existsDir(p) {
+  const st = statSafe(p);
+  return Boolean(st && st.isDirectory());
+}
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function findFilesRecursive(repoRoot, predicate, { maxFiles = 6000, maxDepth = 10 } = {}) {
+  const results = [];
+  const queue = [{ dir: repoRoot, depth: 0 }];
+  let visited = 0;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const ent of entries) {
+      const fullPath = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (DEFAULT_IGNORES.has(ent.name)) continue;
+        queue.push({ dir: fullPath, depth: depth + 1 });
+        continue;
+      }
+      if (!ent.isFile()) continue;
+
+      visited += 1;
+      if (visited > maxFiles) return { results, truncated: true };
+      if (predicate(fullPath)) results.push(fullPath);
+    }
+  }
+
+  return { results, truncated: false };
+}
+
+function summarizeTheme(repoRoot, themeJsonPath) {
+  const json = readJsonSafe(themeJsonPath);
+  const rel = path.relative(repoRoot, themeJsonPath);
+  const rootDir = path.dirname(rel);
+
+  const templatesDir = path.join(repoRoot, rootDir, "templates");
+  const partsDir = path.join(repoRoot, rootDir, "parts");
+  const patternsDir = path.join(repoRoot, rootDir, "patterns");
+  const stylesDir = path.join(repoRoot, rootDir, "styles");
+
+  const hasTemplates = existsDir(templatesDir);
+  const hasParts = existsDir(partsDir);
+
+  return {
+    themeRoot: rootDir,
+    themeJson: rel,
+    version: typeof json?.version === "number" ? json.version : null,
+    hasTemplates,
+    hasParts,
+    hasPatterns: existsDir(patternsDir),
+    hasStyles: existsDir(stylesDir),
+    isBlockTheme: hasTemplates || hasParts,
+  };
+}
+
+function main() {
+  const repoRoot = process.cwd();
+
+  const { results: themeJsonFiles, truncated } = findFilesRecursive(repoRoot, (p) => path.basename(p) === "theme.json", {
+    maxFiles: 8000,
+    maxDepth: 12,
+  });
+
+  const themes = themeJsonFiles.map((p) => summarizeTheme(repoRoot, p));
+
+  const report = {
+    tool: { name: "detect_block_themes", version: "0.1.0" },
+    repoRoot,
+    truncated,
+    count: themes.length,
+    themes,
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();
+

package/skills/wp-interactivity-api/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: wp-interactivity-api
+description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Interactivity API
+
+## When to use
+
+Use this skill when the user mentions:
+
+- Interactivity API, `@wordpress/interactivity`,
+- `data-wp-interactive`, `data-wp-on--*`, `data-wp-bind--*`, `data-wp-context`,
+- block `viewScriptModule` / module-based view scripts,
+- hydration issues or “directives don’t fire”.
+
+## Inputs required
+
+- Repo root + triage output (`wp-project-triage`).
+- Which block/theme/plugin surfaces are affected (frontend, editor, both).
+- Any constraints: WP version, whether modules are supported in the build.
+
+## Procedure
+
+### 1) Detect existing usage + integration style
+
+Search for:
+
+- `data-wp-interactive`
+- `@wordpress/interactivity`
+- `viewScriptModule`
+
+Decide:
+
+- Is this a block providing interactivity via `block.json` view script module?
+- Is this theme-level interactivity?
+- Is this plugin-side “enhance existing markup” usage?
+
+If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:
+
+- `@wordpress/create-block-interactive-template` (via `@wordpress/create-block`)
+
+### 2) Identify the store(s)
+
+Locate store definitions and confirm:
+
+- state shape,
+- actions (mutations),
+- callbacks/event handlers used by `data-wp-on--*`.
+
+### 3) Server-side rendering (best practice)
+
+**Pre-render HTML on the server** before outputting to ensure:
+
+- Correct initial state in the HTML before JavaScript loads (no layout shift).
+- SEO benefits and faster perceived load time.
+- Seamless hydration when the client-side JavaScript takes over.
+
+#### Enable server directive processing
+
+For components using `block.json`, add `supports.interactivity`:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+For themes/plugins without `block.json`, use `wp_interactivity_process_directives()` to process directives.
+
+#### Initialize state/context in PHP
+
+Use `wp_interactivity_state()` to define initial global state:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'hasItems' => true,
+));
+```
+
+For local context, use `wp_interactivity_data_wp_context()`:
+
+```php
+<?php
+$context = array( 'isOpen' => false );
+?>
+<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
+  ...
+</div>
+```
+
+#### Define derived state in PHP
+
+When derived state affects initial HTML rendering, replicate the logic in PHP:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana' ),
+  'hasItems' => function() {
+    $state = wp_interactivity_state();
+    return count( $state['items'] ) > 0;
+  }
+));
+```
+
+This ensures directives like `data-wp-bind--hidden="!state.hasItems"` render correctly on first load.
+
+For detailed examples and patterns, see `references/server-side-rendering.md`.
+
+### 4) Implement or change directives safely
+
+When touching markup directives:
+
+- keep directive usage minimal and scoped,
+- prefer stable data attributes that map clearly to store state,
+- ensure server-rendered markup + client hydration align.
+
+**WordPress 6.9 changes:**
+
+- **`data-wp-ignore` is deprecated** and will be removed in future versions. It broke context inheritance and caused issues with client-side navigation. Avoid using it.
+- **Unique directive IDs**: Multiple directives of the same type can now exist on one element using the `---` separator (e.g., `data-wp-on--click---plugin-a="..."` and `data-wp-on--click---plugin-b="..."`).
+- **New TypeScript types**: `AsyncAction<ReturnType>` and `TypeYield<T>` help with async action typing.
+
+For quick directive reminders, see `references/directives-quickref.md`.
+
+### 5) Build/tooling alignment
+
+Verify the repo supports the required module build path:
+
+- if it uses `@wordpress/scripts`, prefer its conventions.
+- if it uses custom bundling, confirm module output is supported.
+
+### 6) Debug common failure modes
+
+If “nothing happens” on interaction:
+
+- confirm the `viewScriptModule` is enqueued/loaded,
+- confirm the DOM element has `data-wp-interactive`,
+- confirm the store namespace matches the directive’s value,
+- confirm there are no JS errors before hydration.
+
+See `references/debugging.md`.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesInteractivityApi: true` after your change (if applicable).
+- Manual smoke test: directive triggers and state updates as expected.
+- If tests exist: add/extend Playwright E2E around the interaction path.
+
+## Failure modes / debugging
+
+- Directives present but inert:
+  - view script not loading, wrong module entrypoint, or missing `data-wp-interactive`.
+- Hydration mismatch / flicker:
+  - server markup differs from client expectations; simplify or align initial state.
+  - derived state not defined in PHP: use `wp_interactivity_state()` with closures.
+- Initial content missing or wrong:
+  - `supports.interactivity` not set in `block.json` (for blocks).
+  - `wp_interactivity_process_directives()` not called (for themes/plugins).
+  - state/context not initialized in PHP before render.
+- Layout shift on load:
+  - derived state like `state.hasItems` missing on server, causing `hidden` attribute to be absent.
+- Performance regressions:
+  - overly broad interactive roots; scope interactivity to smaller subtrees.
+- Client-side navigation issues (WordPress 6.9):
+  - `getServerState()` and `getServerContext()` now reset between page transitions—ensure your code doesn't assume stale values persist.
+  - Router regions now support `attachTo` for rendering overlays (modals, pop-ups) dynamically.
+
+## Escalation
+
+- If repo build constraints are unclear, ask: "Is this using `@wordpress/scripts` or a custom bundler (webpack/vite)?"
+- Consult:
+  - `references/server-side-rendering.md`
+  - `references/directives-quickref.md`
+  - `references/debugging.md`

package/skills/wp-interactivity-api/references/debugging.md

@@ -0,0 +1,29 @@
+# Debugging checklist
+
+1. Confirm the interactive root exists in the rendered HTML (`data-wp-interactive`).
+2. Confirm the view script module is loaded (network + source maps).
+3. Confirm store namespace matches what markup expects.
+4. Check console for errors before any interaction.
+5. Reduce scope:
+   - temporarily remove directives to isolate which directive/store path breaks.
+6. If hydration mismatch occurs:
+   - ensure initial state/context matches server markup.
+
+## WordPress 6.9 specific issues
+
+**State not persisting across navigation:**
+- `getServerState()` and `getServerContext()` now reset between client-side page transitions.
+- If you relied on stale values persisting, refactor to use the store's reactive state instead.
+
+**Multiple plugins conflicting on same element:**
+- Use unique directive IDs with the `---` separator to avoid attribute collisions.
+- Example: `data-wp-on--click---my-plugin="actions.handle"`
+
+**`data-wp-ignore` not working:**
+- This directive is deprecated in 6.9 and will be removed. It caused context inheritance and navigation bugs.
+- Find an alternative approach (conditional rendering, separate interactive regions).
+
+**Router regions / overlays not rendering:**
+- WordPress 6.9 adds `attachTo` property for router regions to render overlays anywhere on the page.
+- Ensure nested router regions are properly structured.
+

package/skills/wp-interactivity-api/references/directives-quickref.md

@@ -0,0 +1,30 @@
+# Directives quick reference (high level)
+
+Common directives to recognize in markup:
+
+- `data-wp-interactive`: declares an interactive region (and often a store namespace).
+- `data-wp-context`: provides server-rendered context/state.
+- `data-wp-on--event`: attaches event handlers (e.g. `click`, `submit`).
+- `data-wp-on-async--event`: async event handlers (preferred for most actions).
+- `data-wp-bind--attr`: binds DOM attributes to state.
+- `data-wp-class--name`: toggles CSS classes based on state.
+
+Use these as search anchors when triaging bugs.
+
+## Unique directive IDs (WordPress 6.9+)
+
+HTML doesn't allow duplicate attributes. To attach multiple handlers of the same type from different plugins, use the `---` separator:
+
+```html
+<button
+  data-wp-on--click---plugin-a="actions.handleA"
+  data-wp-on--click---plugin-b="actions.handleB"
+>
+```
+
+Both handlers will fire. The ID after `---` must be unique per element.
+
+## Deprecated directive
+
+- **`data-wp-ignore`**: Deprecated in WordPress 6.9. It was intended to prevent hydration of a region but broke context inheritance and client-side navigation. Will be removed in future versions. Avoid using it.
+