@goldencomm/create-baseline 0.0.1 → 0.1.0

package/templates/wordpress/.claude/skills/wp-block-themes/SKILL.md

@@ -1,116 +0,0 @@
----
-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

@@ -1,37 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,16 +0,0 @@
-# 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

@@ -1,59 +0,0 @@
-# `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

@@ -1,117 +0,0 @@
-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

@@ -1,146 +0,0 @@
----
-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

@@ -1,24 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

@@ -1,15 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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.
-