@goldencomm/create-baseline 0.0.1

package/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/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/templates/wordpress/.claude/skills/wp-performance/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wp-performance
+description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
+---
+
+# WP Performance (backend-only)
+
+## When to use
+
+Use this skill when:
+
+- a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
+- you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
+- you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls
+
+This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.
+
+## Inputs required
+
+- Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
+- How to target the install:
+  - WP root `--path=<path>`
+  - (multisite/site targeting) `--url=<url>`
+- The performance symptom and scope:
+  - which URL/REST route/admin screen
+  - when it happens (always vs sporadic; logged-in vs logged-out)
+
+## Procedure
+
+### 0) Guardrails: measure first, avoid risky ops
+
+1. Confirm whether you may run write operations (plugin installs, config changes, cache flush).
+2. Pick a reproducible target (URL or REST route) and capture a baseline:
+   - TTFB/time with `curl` if possible
+   - WP-CLI profiling if available
+
+Read:
+- `references/measurement.md`
+
+### 1) Generate a backend-only performance report (deterministic)
+
+Run:
+
+- `node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]`
+
+This detects:
+
+- WP-CLI availability and core version
+- whether `wp doctor` / `wp profile` are available
+- autoloaded options size (if possible)
+- object-cache drop-in presence
+
+### 2) Fast wins: run diagnostics before deep profiling
+
+If you have WP-CLI access, prefer:
+
+- `wp doctor check`
+
+It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).
+
+Read:
+- `references/wp-cli-doctor.md`
+
+### 3) Deep profiling (no browser required)
+
+Preferred order:
+
+1. `wp profile stage` to see where time goes (bootstrap/main_query/template).
+2. `wp profile hook` (optionally with `--url=`) to find slow hooks/callbacks.
+3. `wp profile eval` for targeted code paths.
+
+Read:
+- `references/wp-cli-profile.md`
+
+### 4) Query Monitor (backend-only usage)
+
+Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and `_envelope` responses:
+
+- Authenticate (nonce or Application Password).
+- Request REST responses and inspect headers (`x-qm-*`) and/or the `qm` property when using `?_envelope`.
+
+Read:
+- `references/query-monitor-headless.md`
+
+### 5) Fix by category (choose the dominant bottleneck)
+
+Use the profile output to pick *one* primary bottleneck category:
+
+- **DB queries** → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
+  - `references/database.md`
+- **Autoloaded options** → identify the biggest autoloaded options and stop autoloading large blobs.
+  - `references/autoload-options.md`
+- **Object cache misses** → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
+  - `references/object-cache.md`
+- **Remote HTTP calls** → add timeouts, caching, batching; avoid calling remote APIs on every request.
+  - `references/http-api.md`
+- **Cron** → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
+  - `references/cron.md`
+
+### 6) Verify (repeat the same measurement)
+
+- Re-run the same `wp profile` / `wp doctor` / REST request.
+- Confirm the performance delta and that behavior is unchanged.
+- If the fix is risky, ship behind a feature flag or staged rollout when possible.
+
+## WordPress 6.9 performance improvements
+
+Be aware of these 6.9 changes when profiling:
+
+**On-demand CSS for classic themes:**
+- Classic themes now get on-demand CSS loading (previously only block themes had this).
+- Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
+- If you're profiling a classic theme, this should already be helping.
+
+**Block themes with no render-blocking resources:**
+- Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
+- Styles come from global styles (theme.json) and separate block styles, all inlined.
+- This significantly improves LCP (Largest Contentful Paint).
+
+**Inline CSS limit increased:**
+- The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.
+
+Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/
+
+## Verification
+
+- Baseline vs after numbers are captured (same environment, same URL/route).
+- `wp doctor check` is clean (or improved) when applicable.
+- No new PHP errors or warnings in logs.
+- No cache flush is required for correctness (cache flush should be last resort).
+
+## Failure modes / debugging
+
+- “No change” after code changes:
+  - you measured a different URL/site (`--url` mismatch), caches masked results, or opcode cache is stale
+- Profiling data is noisy:
+  - eliminate background tasks, test with warmed caches, run multiple samples
+- `SAVEQUERIES`/Query Monitor causes overhead:
+  - don’t run in production unless explicitly approved
+
+## Escalation
+
+- If this is production and you don’t have explicit approval, do not:
+  - install plugins, enable `SAVEQUERIES`, run load tests, or flush caches during traffic
+- If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

package/templates/wordpress/.claude/skills/wp-performance/references/autoload-options.md

@@ -0,0 +1,24 @@
+# Autoloaded options
+
+Autoloaded options are loaded on *every request*, so large autoload payloads can hurt performance site-wide.
+
+## Quick checks
+
+- Total autoload bytes:
+  - `wp option list --autoload=on --format=total_bytes`
+- Find biggest autoloaded options:
+  - `wp option list --autoload=on --fields=option_name,size_bytes | sort -n -k 2 | tail`
+
+Docs:
+
+- `wp option list`: https://wpcli.dev/docs/option/list
+- `wp doctor` includes an `autoload-options-size` check:
+  - https://make.wordpress.org/cli/handbook/doctor-default-checks/
+
+## Fix patterns
+
+- Stop autoloading large blobs:
+  - store large data in non-autoload options (autoload=off)
+  - move large computed data to transients/object cache
+- Remove stale options left behind by removed plugins/themes (careful: confirm usage before deleting).
+

package/templates/wordpress/.claude/skills/wp-performance/references/cron.md

@@ -0,0 +1,20 @@
+# WP-Cron performance
+
+Use this file when cron causes spikes or request-time slowness.
+
+Backend-only tools:
+
+- `wp cron test` (spawning health)
+- `wp cron event list`
+- `wp cron event run --due-now`
+
+Reference:
+
+- WP-CLI cron command package: https://github.com/wp-cli/cron-command
+
+Fix patterns:
+
+- De-duplicate scheduled events and reduce frequency where possible.
+- Ensure tasks are idempotent and short.
+- Move heavy work off-request; cron that runs on page load can hurt TTFB.
+

package/templates/wordpress/.claude/skills/wp-performance/references/database.md

@@ -0,0 +1,20 @@
+# Database / query performance
+
+Use this file when profiling points to DB time or high query counts.
+
+Common fixes:
+
+- Avoid N+1 query patterns (batch queries, prime caches, avoid per-row lookups).
+- Prefer `fields => 'ids'` when you only need IDs.
+- Avoid expensive meta queries where possible; consider indexing or schema changes.
+- Use object caching for repeated reads.
+
+Tools (backend-only):
+
+- Query Monitor (REST headers/envelope) for query lists and stack traces.
+- `wp db query` for targeted SQL/explain (be careful in prod).
+
+References:
+
+- Query Monitor plugin: https://wordpress.org/plugins/query-monitor/
+

package/templates/wordpress/.claude/skills/wp-performance/references/http-api.md

@@ -0,0 +1,15 @@
+# HTTP API (remote requests)
+
+Use this file when profiling shows slow external requests (`wp_remote_get`, etc.).
+
+Fix patterns:
+
+- Add timeouts and fail-fast behavior.
+- Cache responses where appropriate (transients/object cache).
+- Batch requests and avoid calling remote APIs on every page load.
+- Move heavy remote work to async (cron/queue) where possible.
+
+Tooling:
+
+- Query Monitor can report HTTP API calls (including timing) via REST envelope info.
+

package/templates/wordpress/.claude/skills/wp-performance/references/measurement.md

@@ -0,0 +1,21 @@
+# Measurement (profiling vs benchmarking)
+
+Backend-only measurement options:
+
+- **WP-CLI profiling** (`wp profile`): best for pinpointing slow hooks/stages without a browser.
+- **WP-CLI doctor** (`wp doctor`): best for quick diagnostics (autoload bloat, debug constants, updates).
+- **Query Monitor via REST**: use authenticated REST requests and inspect `x-qm-*` headers / `qm` envelope data.
+- **Server-Timing** (Performance Lab): inspect `Server-Timing` headers via `curl -I` (when enabled).
+- **APM/profilers**: New Relic, Datadog, Blackfire, Tideways, XHProf/Xdebug (requires server support).
+
+Best practices:
+
+- Always capture a baseline first.
+- Keep the test scenario fixed (same URL/route, same user state, same data).
+- Prefer multiple samples and medians over single runs.
+
+References:
+
+- Measuring performance handbook: https://make.wordpress.org/performance/handbook/measuring-performance/
+- Benchmarking with Server-Timing: https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+

package/templates/wordpress/.claude/skills/wp-performance/references/object-cache.md

@@ -0,0 +1,24 @@
+# Object caching
+
+Use this file when profiling indicates repeated queries or low cache hit rate.
+
+## Concepts
+
+- Default WP object cache is per-request memory only.
+- A persistent object cache “drop-in” (`wp-content/object-cache.php`) can persist cache across requests.
+
+WP-CLI cache commands:
+
+- https://wpcli.dev/docs/cache
+
+Guardrails:
+
+- `wp cache flush` can impact all sites in multisite and cause load spikes:
+  - https://wpcli.dev/docs/cache/flush
+
+## Fix patterns
+
+- Cache expensive computed results (transients or object cache) with explicit invalidation.
+- Avoid unbounded caches (set expirations or implement invalidation hooks).
+- If adding a persistent object cache, coordinate with infra (Redis/Memcached) and test cache flush behavior.
+