wp-skills 1.0.0

package/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/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/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/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/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/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.
+

package/skills/wp-performance/references/query-monitor-headless.md

@@ -0,0 +1,38 @@
+# Query Monitor (headless / backend-only)
+
+Query Monitor is UI-first, but it can expose useful data to backend-only tooling.
+
+## What it can show
+
+Query Monitor can help debug:
+
+- DB queries (slow/dupes/errors), hooks/actions, HTTP API calls, PHP errors
+
+Plugin page:
+
+- https://wordpress.org/plugins/query-monitor/
+
+Configuration constants:
+
+- https://querymonitor.com/help/configuration-constants/
+
+## REST API requests (no browser needed)
+
+Query Monitor can add performance/error info to authenticated REST responses.
+
+Docs:
+
+- https://querymonitor.com/wordpress-debugging/rest-api-requests/
+
+High-level approach:
+
+1. Authenticate (nonce or Application Password).
+2. Make a REST request and inspect response headers like `x-qm-overview-*`.
+3. If you request an enveloped response (`?_envelope`), you can get a `qm` property with:
+   - DB queries details, cache stats, HTTP API request details, etc.
+
+## Guardrails
+
+- Query Monitor adds some overhead; don’t enable it in production without approval.
+- If it’s already installed by your platform (e.g. VIP), you may need to grant `view_query_monitor`.
+

package/skills/wp-performance/references/server-timing.md

@@ -0,0 +1,22 @@
+# Server-Timing (Performance Lab)
+
+Use this file when you can enable Server-Timing metrics and want backend-only inspection via HTTP headers.
+
+Performance Lab plugin:
+
+- https://wordpress.org/plugins/performance-lab/
+
+Benchmarking guidance:
+
+- https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+
+Backend-only approach:
+
+- Enable the relevant module/standalone plugin.
+- Request a URL and inspect the `Server-Timing` header:
+  - `curl -sS -D - https://example.test/ -o /dev/null | rg -i \"^server-timing:\"`
+
+Guardrails:
+
+- Don’t enable experimental modules in production without approval.
+

package/skills/wp-performance/references/wp-cli-doctor.md

@@ -0,0 +1,24 @@
+# WP-CLI doctor (`wp doctor`)
+
+Use this for quick “production readiness” checks.
+
+## Install (if missing)
+
+- `wp package install wp-cli/doctor-command`
+
+Docs:
+
+- Default checks: https://make.wordpress.org/cli/handbook/doctor-default-checks/
+- Customize checks: https://make.wordpress.org/cli/handbook/guides/doctor/doctor-customize-config/
+
+## Recommended usage
+
+- `wp doctor check`
+- `wp doctor list` (to see available checks)
+
+Especially relevant to performance:
+
+- `autoload-options-size` (autoloaded options threshold)
+- `constant-savequeries-falsy` / `constant-wp-debug-falsy` (avoid perf-costly debug flags in prod)
+- cron checks (count/duplicates)
+

package/skills/wp-performance/references/wp-cli-profile.md

@@ -0,0 +1,32 @@
+# WP-CLI profiling (`wp profile`)
+
+Use this when you need actionable profiling without a browser.
+
+## Install (if missing)
+
+`wp profile` comes from a WP-CLI package:
+
+- `wp package install wp-cli/profile-command`
+
+Docs:
+
+- https://wpcli.dev/docs/profile/stage
+- https://wpcli.dev/docs/profile/hook
+- https://wpcli.dev/docs/profile/eval
+
+## Recommended sequence
+
+1. Stage overview:
+   - `wp profile stage --fields=stage,time,cache_ratio [--url=<url>]`
+2. Hooks hotspot:
+   - `wp profile hook --spotlight [--url=<url>]`
+   - then drill into a specific hook:
+     - `wp profile hook init --spotlight [--url=<url>]`
+3. Targeted evaluation:
+   - `wp profile eval 'do_action(\"init\");' --hook=init`
+
+Tips:
+
+- Use `--url` to profile specific site/route behavior.
+- Use `--skip-plugins` / `--skip-themes` to isolate culprit components (careful: behavior changes).
+

package/skills/wp-performance/scripts/perf_inspect.mjs

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const TOOL_VERSION = "0.1.0";
+
+function parseArgs(argv) {
+  const args = { path: null, url: null, allowRoot: false };
+  for (const a of argv) {
+    if (a === "--allow-root") args.allowRoot = true;
+    if (a.startsWith("--path=")) args.path = a.slice("--path=".length);
+    if (a.startsWith("--url=")) args.url = a.slice("--url=".length);
+  }
+  return args;
+}
+
+function existsFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function runWp(cmdArgs, { pathArg, urlArg, allowRoot }) {
+  const args = [];
+  if (allowRoot) args.push("--allow-root");
+  if (pathArg) args.push(`--path=${pathArg}`);
+  if (urlArg) args.push(`--url=${urlArg}`);
+  args.push(...cmdArgs);
+
+  const out = spawnSync("wp", args, { encoding: "utf8" });
+  return {
+    ok: out.status === 0,
+    status: out.status,
+    error: out.error ? { message: out.error.message, code: out.error.code } : null,
+    stdout: (out.stdout || "").trim(),
+    stderr: (out.stderr || "").trim(),
+    args,
+  };
+}
+
+function canRun(report, result, noteIfNotOk) {
+  report._runs.push({ cmd: result.args.join(" "), ok: result.ok, status: result.status, error: result.error });
+  if (!result.ok && noteIfNotOk) report.notes.push(noteIfNotOk);
+  return result.ok;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const report = {
+    tool: { name: "perf_inspect", version: TOOL_VERSION },
+    target: { path: opts.path, url: opts.url },
+    wpCli: { available: false },
+    wp: {
+      isInstalled: null,
+      coreVersion: null,
+    },
+    commands: {
+      doctor: { available: false },
+      profile: { available: false },
+    },
+    perfSignals: {
+      autoloadTotalBytes: null,
+      hasObjectCacheDropin: null,
+      hasAdvancedCacheDropin: null,
+      hasQueryMonitorPlugin: null,
+      hasPerformanceLabPlugin: null,
+    },
+    notes: [],
+    _runs: [],
+  };
+
+  const info = runWp(["--info"], { pathArg: null, urlArg: null, allowRoot: opts.allowRoot });
+  report.wpCli.available = info.ok;
+  report.wpCli.info = info;
+  if (!info.ok) {
+    report.notes.push("WP-CLI not available on PATH. Run in the intended environment (container/ssh) or install WP-CLI.");
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  const isInstalled = runWp(["core", "is-installed"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.wp.isInstalled = isInstalled.ok;
+  canRun(report, isInstalled, "WordPress not detected at the given --path/--url (check wp-config.php and targeting).");
+  if (!isInstalled.ok) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  const coreVersion = runWp(["core", "version"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.wp.coreVersion = coreVersion.ok ? coreVersion.stdout : null;
+  canRun(report, coreVersion);
+
+  const doctorHelp = runWp(["doctor", "--help"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.commands.doctor.available = doctorHelp.ok;
+  canRun(report, doctorHelp);
+
+  const profileHelp = runWp(["profile", "--help"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.commands.profile.available = profileHelp.ok;
+  canRun(report, profileHelp);
+
+  const autoloadBytes = runWp(["option", "list", "--autoload=on", "--format=total_bytes"], {
+    pathArg: opts.path,
+    urlArg: opts.url,
+    allowRoot: opts.allowRoot,
+  });
+  if (autoloadBytes.ok && /^\d+$/.test(autoloadBytes.stdout)) {
+    report.perfSignals.autoloadTotalBytes = Number(autoloadBytes.stdout);
+  }
+  canRun(report, autoloadBytes);
+
+  if (opts.path) {
+    const wpContent = path.join(opts.path, "wp-content");
+    report.perfSignals.hasObjectCacheDropin = existsFile(path.join(wpContent, "object-cache.php"));
+    report.perfSignals.hasAdvancedCacheDropin = existsFile(path.join(wpContent, "advanced-cache.php"));
+    report.perfSignals.hasQueryMonitorPlugin = existsFile(path.join(wpContent, "plugins", "query-monitor", "query-monitor.php"));
+    report.perfSignals.hasPerformanceLabPlugin = existsFile(path.join(wpContent, "plugins", "performance-lab", "load.php"));
+  }
+
+  if (!report.commands.doctor.available) report.notes.push("Tip: install WP-CLI doctor: `wp package install wp-cli/doctor-command`.");
+  if (!report.commands.profile.available) report.notes.push("Tip: install WP-CLI profile: `wp package install wp-cli/profile-command`.");
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();
+

package/skills/wp-phpstan/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wp-phpstan
+description: "Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines, WordPress-specific typing, and handling third-party plugin classes."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires Composer-based PHPStan."
+---
+
+# WP PHPStan
+
+## When to use
+
+Use this skill when working on PHPStan in a WordPress codebase, for example:
+
+- setting up or updating `phpstan.neon` / `phpstan.neon.dist`
+- generating or updating `phpstan-baseline.neon`
+- fixing PHPStan errors via WordPress-friendly PHPDoc (REST requests, hooks, query results)
+- handling third-party plugin/theme classes safely (stubs/autoload/targeted ignores)
+
+## Inputs required
+
+- `wp-project-triage` output (run first if you haven't)
+- Whether adding/updating Composer dev dependencies is allowed (stubs).
+- Whether changing the baseline is allowed for this task.
+
+## Procedure
+
+### 0) Discover PHPStan entrypoints (deterministic)
+1. Inspect PHPStan setup (config, baseline, scripts):
+   - `node skills/wp-phpstan/scripts/phpstan_inspect.mjs`
+
+Prefer the repo’s existing `composer` script (e.g. `composer run phpstan`) when present.
+
+### 1) Ensure WordPress core stubs are loaded
+
+`szepeviktor/phpstan-wordpress` or `php-stubs/wordpress-stubs` are effectively required for most WordPress plugin/theme repos. Without it, expect a high volume of errors about unknown WordPress core functions.
+
+- Confirm the package is installed (see `composer.dependencies` in the inspect report).
+- Ensure the PHPStan config references the stubs (see `references/third-party-classes.md`).
+
+### 2) Ensure a sane `phpstan.neon` for WordPress projects
+
+- Keep `paths` focused on first-party code (plugin/theme directories).
+- Exclude generated and vendored code (`vendor/`, `node_modules/`, build artifacts, tests unless explicitly analyzed).
+- Keep `ignoreErrors` entries narrow and documented.
+
+See:
+- `references/configuration.md`
+
+### 3) Fix errors with WordPress-specific typing (preferred)
+
+Prefer correcting types over ignoring errors. Common WP patterns that need help:
+
+- REST endpoints: type request parameters using `WP_REST_Request<...>`
+- Hook callbacks: add accurate `@param` types for callback args
+- Database results and iterables: use array shapes or object shapes for query results
+- Action Scheduler: type `$args` array shapes for job callbacks
+
+See:
+- `references/wordpress-annotations.md`
+
+### 4) Handle third-party plugin/theme classes (only when needed)
+
+When integrating with plugins/themes not present in the analysis environment:
+
+- First, confirm the dependency is real (installed/required).
+- Prefer plugin-specific stubs already used in the repo (common examples: `php-stubs/woocommerce-stubs`, `php-stubs/acf-pro-stubs`).
+- If PHPStan still cannot resolve classes, add targeted `ignoreErrors` patterns for the specific vendor prefix.
+
+See:
+- `references/third-party-classes.md`
+
+### 5) Baseline management (use as a migration tool, not a trash bin)
+
+- Generate a baseline once for legacy code, then reduce it over time.
+- Do not “baseline” newly introduced errors.
+
+See:
+- `references/configuration.md`
+
+## Verification
+
+- Run PHPStan using the discovered command (`composer run ...` or `vendor/bin/phpstan analyse`).
+- Confirm the baseline file (if used) is included and didn’t grow unexpectedly.
+- Re-run after changing `ignoreErrors` to ensure patterns are not masking unrelated issues.
+
+## Failure modes / debugging
+
+- “Class not found”:
+  - confirm autoloading/stubs, or add a narrow ignore pattern
+- Huge error counts after enabling PHPStan:
+  - reduce `paths`, add `excludePaths`, start at a lower level, then ratchet up
+- Inconsistent types around hooks / REST params:
+  - add explicit PHPDoc (see references) rather than runtime guards
+
+## Escalation
+
+- If a type depends on a third-party plugin API you can’t confirm, ask for the dependency version or source before inventing types.
+- If fixing requires adding new Composer dependencies (stubs/extensions), confirm it with the user first.

package/skills/wp-phpstan/references/configuration.md

@@ -0,0 +1,52 @@
+# PHPStan configuration (WordPress)
+
+This reference documents a minimal, WordPress-friendly PHPStan setup and baseline workflow.
+
+## Minimal `phpstan.neon` template
+
+Use the repo’s existing layout. The example below is intentionally conservative and should be adapted to the project’s actual directories.
+
+```neon
+# Include the baseline only if the file exists.
+includes:
+    - phpstan-baseline.neon
+
+parameters:
+    level: 5
+    paths:
+        - src/
+        - includes/
+
+    excludePaths:
+        - vendor/
+        - vendor-prefixed/
+        - node_modules/
+        - tests/
+
+    ignoreErrors:
+        # Add targeted exceptions only when necessary.
+```
+
+Guidelines:
+
+- Prefer analyzing first-party code only.
+- Exclude anything generated or vendored.
+- Keep `ignoreErrors` patterns narrow and grouped by dependency.
+
+## Baseline workflow
+
+Baselines help you adopt PHPStan in legacy code without accepting new regressions.
+
+```bash
+# Generate a baseline (explicit filename)
+vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon
+
+# Update an existing baseline (defaults)
+vendor/bin/phpstan analyse --generate-baseline
+```
+
+Best practices:
+
+- Avoid adding new errors to the baseline; fix the new code instead.
+- Treat baseline changes like code changes: review in PRs.
+- Chip away at the baseline gradually (remove entries as you fix root causes).

package/skills/wp-phpstan/references/third-party-classes.md

@@ -0,0 +1,76 @@
+# Third-party classes and ignore patterns
+
+When PHPStan reports legitimate classes as missing (e.g. because WordPress or a plugin is not installed in the analysis environment), prefer fixing discovery first and only then add targeted ignores.
+
+## Before adding `ignoreErrors`
+
+- Confirm the dependency is real (installed/required in this environment).
+- Prefer stubs/extensions already used by the repo.
+- Prefer a narrow ignore for the vendor prefix over a broad ignore.
+
+## Recommended stub packages
+
+Stubs are useful when the analysis environment does not include WordPress (or a plugin API) but you still want real type checking (instead of blanket ignores).
+
+Common packages:
+
+```bash
+composer require --dev szepeviktor/phpstan-wordpress
+composer require --dev php-stubs/wordpress-stubs
+composer require --dev php-stubs/woocommerce-stubs
+composer require --dev php-stubs/acf-pro-stubs
+```
+
+When stubs are useful (and sometimes necessary):
+
+- Running PHPStan in a plugin/theme repo without a full WordPress checkout.
+- PHPStan reports unknown WordPress core functions (e.g. `add_action()`, `get_option()`).
+- Integrations with optional plugins (WooCommerce, ACF Pro) that are not installed during analysis.
+- You want method/property existence checks and accurate return types instead of `ignoreErrors`.
+
+Notes:
+
+- Prefer stubs that match the runtime versions; mismatches can cause false positives.
+- Adding Composer dependencies changes the repo; confirm it is acceptable for the task.
+
+## Ensure stubs are loaded
+
+Installing stubs is not enough if PHPStan does not scan them. Add stub paths in `phpstan.neon`.
+
+```neon
+parameters:
+    bootstrapFiles:
+        - %rootDir%/../../php-stubs/woocommerce-stubs/woocommerce-stubs.php
+    scanFiles:
+        - %rootDir%/../../php-stubs/wordpress-stubs/wordpress-stubs.php
+        - %rootDir%/../../php-stubs/acf-pro-stubs/acf-pro-stubs.php
+        - %rootDir%/../../woocommerce/action-scheduler/functions.php
+```
+
+## Targeted ignore patterns (examples)
+
+```neon
+parameters:
+    ignoreErrors:
+        # Admin Columns Pro
+        - '#.*(unknown class|invalid type|call to method .* on an unknown class) AC\\ListScreen.*#'
+
+        # Elementor
+        - '#.*(unknown class|invalid type|call to method .* on an unknown class) Elementor\\.*#'
+
+        # Yoast SEO
+        - '#.*(unknown class|invalid type|call to method .* on an unknown class) WPSEO_.*#'
+```
+
+Pattern creation rules:
+
+- Cover error variations: `unknown class`, `invalid type`, `call to method .* on an unknown class`.
+- Keep patterns specific enough to target only intended classes.
+- Add a short comment naming the plugin/theme.
+- Group related patterns for the same dependency.
+
+When to add exceptions:
+
+- Only for legitimate third-party dependencies your code integrates with.
+- Document each pattern with a comment.
+- Re-run PHPStan to ensure the ignore does not hide unrelated issues.