@ai-kits/wp-ag-kit 1.0.0

package/skills/wp-phpstan/scripts/phpstan_inspect.mjs

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TOOL_VERSION = "0.1.0";
+
+/**
+ * Reads and parses JSON from a file path.
+ *
+ * Returns null when parsing fails so the caller can provide user-facing
+ * guidance without crashing.
+ *
+ * @param {string} filePath Absolute path to a JSON file.
+ * @returns {any|null} Parsed JSON object.
+ */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads a UTF-8 text file.
+ *
+ * Returns null when reading fails so callers can surface missing configs
+ * without crashing.
+ *
+ * @param {string} filePath Absolute path to a text file.
+ * @returns {string|null} File contents.
+ */
+function readTextSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks whether a path exists and is a regular file.
+ *
+ * @param {string} filePath Absolute or relative file path.
+ * @returns {boolean} True when the path exists and is a file.
+ */
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalizes Composer script entries into a flat list of commands.
+ *
+ * Composer allows scripts to be strings or arrays. This helper provides a
+ * consistent format for analysis.
+ *
+ * @param {unknown} value Composer script value.
+ * @returns {string[]} Command list.
+ */
+function normalizeComposerScript(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((x) => typeof x === "string");
+  return [];
+}
+
+/**
+ * Detects which Composer scripts invoke PHPStan.
+ *
+ * This helps the agent prefer the repo's own invocation (memory limits,
+ * config, bootstrap files) instead of guessing.
+ *
+ * @param {Record<string, unknown>} scripts Composer scripts block.
+ * @returns {Array<{name: string, commands: string[]}>} Matching script entries.
+ */
+function findPhpstanScripts(scripts) {
+  if (!scripts || typeof scripts !== "object") return [];
+
+  const matches = [];
+
+  for (const [name, raw] of Object.entries(scripts)) {
+    const commands = normalizeComposerScript(raw);
+
+    const invokesPhpstan = commands.some((cmd) => {
+      if (typeof cmd !== "string") return false;
+      return cmd.includes("phpstan") || cmd.includes("vendor/bin/phpstan");
+    });
+
+    if (!invokesPhpstan) continue;
+
+    matches.push({ name, commands });
+  }
+
+  return matches;
+}
+
+/**
+ * Chooses a recommended command for running PHPStan in the current repo.
+ *
+ * The intent is to prefer an existing Composer script (often has correct
+ * config, bootstrap, and memory limits), falling back to vendor binaries.
+ *
+ * @param {Array<{name: string, commands: string[]}>} phpstanScripts Matching Composer scripts.
+ * @param {{binaryRelPath: string|null, configRelPath: string|null}} fallbackInfo Fallback discovery.
+ * @returns {{command: string|null, rationale: string}} Suggested command and why.
+ */
+function suggestCommand(phpstanScripts, fallbackInfo) {
+  const preferred = phpstanScripts.find((s) => s.name === "phpstan");
+  if (preferred) {
+    return {
+      command: `composer run ${preferred.name}`,
+      rationale: "Uses the repo's Composer script (preferred for consistent config).",
+    };
+  }
+
+  if (phpstanScripts.length > 0) {
+    return {
+      command: `composer run ${phpstanScripts[0].name}`,
+      rationale: "Uses the repo's Composer script that invokes PHPStan.",
+    };
+  }
+
+  if (!fallbackInfo.binaryRelPath) {
+    return {
+      command: null,
+      rationale: "No PHPStan binary detected under vendor/bin and no Composer script found.",
+    };
+  }
+
+  const configArg = fallbackInfo.configRelPath ? ` -c ${fallbackInfo.configRelPath}` : "";
+
+  return {
+    command: `${fallbackInfo.binaryRelPath} analyse${configArg}`,
+    rationale: "Falls back to vendor/bin/phpstan with an explicit config when needed.",
+  };
+}
+
+/**
+ * Extracts lightweight hints from a phpstan.neon config.
+ *
+ * This does not parse NEON. It only checks for common directive tokens so the
+ * agent can quickly see whether scan directives are in use.
+ *
+ * @param {string} configText Raw phpstan config contents.
+ * @returns {{mentionsScanDirectories: boolean, mentionsScanFiles: boolean}} Hints.
+ */
+function buildConfigHints(configText) {
+  const t = configText.toLowerCase();
+
+  return {
+    mentionsScanDirectories: t.includes("scandirectories"),
+    mentionsScanFiles: t.includes("scanfiles"),
+  };
+}
+
+/**
+ * Extracts stub-like package references from a PHPStan config.
+ *
+ * The PHPStan config usually references stubs via vendor paths (for example,
+ * "vendor/php-stubs/wordpress-stubs"), so this helper focuses on composer-style
+ * "vendor/package" tokens containing "stubs".
+ *
+ * @param {string} configText Raw phpstan config contents.
+ * @returns {string[]} Unique, lowercased composer-style package references.
+ */
+function extractStubPackageReferences(configText) {
+  const matches = configText
+    .toLowerCase()
+    .match(/\b[a-z0-9_.-]+\/[a-z0-9_.-]*stubs[a-z0-9_.-]*\b/g);
+
+  if (!matches) return [];
+
+  return [...new Set(matches)].sort();
+}
+
+/**
+ * Builds a JSON report describing the current repository's PHPStan setup.
+ *
+ * @returns {object} A stable, machine-readable inspection report.
+ */
+function buildReport() {
+  const repoRoot = process.cwd();
+
+  const composerPath = path.join(repoRoot, "composer.json");
+  const composer = isFile(composerPath) ? readJsonSafe(composerPath) : null;
+
+  const phpstanConfigFiles = ["phpstan.neon", "phpstan.neon.dist"].filter((f) =>
+    isFile(path.join(repoRoot, f))
+  );
+  const phpstanBaselineFiles = ["phpstan-baseline.neon", "phpstan-baseline.neon.dist"].filter((f) =>
+    isFile(path.join(repoRoot, f))
+  );
+
+  let configRelPath = null;
+  if (phpstanConfigFiles.includes("phpstan.neon")) configRelPath = "phpstan.neon";
+  else if (phpstanConfigFiles.includes("phpstan.neon.dist")) configRelPath = "phpstan.neon.dist";
+
+  const configAbsPath = configRelPath ? path.join(repoRoot, configRelPath) : null;
+  const configText = configAbsPath ? readTextSafe(configAbsPath) : null;
+
+  const binaryRelPath = isFile(path.join(repoRoot, "vendor", "bin", "phpstan")) ? "vendor/bin/phpstan" : null;
+
+  const composerScripts = composer?.scripts && typeof composer.scripts === "object" ? composer.scripts : null;
+  const phpstanScripts = composerScripts ? findPhpstanScripts(composerScripts) : [];
+
+  const composerDependencies = [
+    ...Object.keys(composer?.require ?? {}),
+    ...Object.keys(composer?.["require-dev"] ?? {}),
+  ].sort();
+  const referencedDependencies = configText ? extractStubPackageReferences(configText) : [];
+
+  const configHints = configText ? buildConfigHints(configText) : null;
+
+  const suggested = suggestCommand(phpstanScripts, {
+    binaryRelPath,
+    configRelPath: configRelPath === "phpstan.neon" ? null : configRelPath,
+  });
+
+  const notes = [];
+
+  if (!composer) notes.push("No composer.json found; PHPStan is usually installed via Composer.");
+  if (phpstanConfigFiles.length === 0) notes.push("No phpstan.neon or phpstan.neon.dist found at repo root.");
+  if (!binaryRelPath && phpstanScripts.length === 0) notes.push("No PHPStan entrypoint detected (Composer script or vendor/bin/phpstan).");
+
+
+
+  return {
+    tool: { name: "phpstan_inspect", version: TOOL_VERSION },
+    repoRoot,
+    composer: {
+      exists: Boolean(composer),
+      path: isFile(composerPath) ? "composer.json" : null,
+      phpstanScripts,
+      dependencies: composerDependencies,
+    },
+    phpstan: {
+      configFiles: phpstanConfigFiles,
+      baselineFiles: phpstanBaselineFiles,
+      config: {
+        primary: configRelPath,
+        hints: configHints,
+        referencedDependencies,
+      },
+      binary: {
+        vendorBin: binaryRelPath,
+      },
+    },
+    suggested,
+    notes,
+  };
+}
+
+/**
+ * CLI entrypoint for printing the inspection report.
+ */
+function main() {
+  const report = buildReport();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();

package/skills/wp-playground/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wp-playground
+description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
+---
+
+# WordPress Playground
+
+## When to use
+
+- Spin up a disposable WordPress to test a plugin/theme without full stack setup.
+- Run or iterate on Playground Blueprints (JSON) locally.
+- Build a reproducible snapshot of a site for sharing or CI.
+- Switch WP/PHP versions quickly to reproduce issues.
+- Debug plugin/theme code with Xdebug in an isolated Playground.
+
+## Inputs required
+
+- Host machine readiness: Node.js ≥ 20.18, `npm`/`npx` available.
+- Project path to mount (`--auto-mount` or explicit mount mapping).
+- Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
+- Blueprint location/URL if running a blueprint.
+- Port preference if 9400 conflicts.
+- Whether Xdebug is needed.
+
+## Procedure
+
+### 0) Guardrails
+
+- Playground instances are ephemeral and SQLite-backed; **never** point at production data.
+- Confirm Node ≥ 20.18 (`node -v`) before running CLI.
+- If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.
+
+### 1) Quick local spin-up (auto-mount)
+
+```bash
+cd <plugin-or-theme-root>
+npx @wp-playground/cli@latest server --auto-mount
+```
+- Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
+- Add `--wp=<version>` / `--php=<version>` as needed.
+- For classic full installs already present, add `--skip-wordpress-setup` and mount the whole tree.
+
+### 2) Manual mounts or multiple mounts
+
+- Use `--mount=/host/path:/vfs/path` (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
+- Mount before install with `--mount-before-install` for bootstrapping installer flows.
+- Reference: `references/cli-commands.md`
+
+### 3) Run a Blueprint (no server needed)
+
+```bash
+npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
+```
+- Use for scripted setup/CI validation. Supports remote URLs and local files.
+- Allow bundled assets in local blueprints with `--blueprint-may-read-adjacent-files` when required.
+- See `references/blueprints.md` for structure and common flags.
+
+### 4) Build a snapshot for sharing
+
+```bash
+npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
+```
+- Produces a ZIP you can load in Playground or attach to bug reports.
+
+### 5) Debugging with Xdebug
+
+- Start with `--xdebug` (or `--enable-xdebug` depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
+- Combine with `--auto-mount` for plugin/theme debugging.
+- Checklist: `references/debugging.md`
+
+### 6) Version switching
+
+- Use `--wp=` to pin WP (e.g., 6.9.0) and `--php=` to test compatibility.
+- If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.
+
+### 7) Browser-only workflows (no CLI)
+
+- Launch quick previews with URL fragments or query params:
+  - Fragment: `https://playground.wordpress.net/#<base64-or-json-blueprint>`
+  - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
+- Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
+
+## Verification
+
+- Verify mounted code is active (plugin listed/active; theme selected).
+- For blueprints/snapshots, re-run with `--verbosity=debug` to confirm steps executed.
+- Run targeted smoke (e.g., `wp plugin list` inside Playground shell via browser terminal if exposed) or UI click-path.
+
+## Failure modes / debugging
+
+- **CLI exits complaining about Node**: upgrade to ≥ 20.18.
+- **Mount not applied**: check path, use absolute path, add `--verbosity=debug`.
+- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files`.
+- **Port already used**: `--port=<free-port>`.
+- **Slow/locked UI**: disable `--experimental-multi-worker` if enabled; or enable it to improve throughput on CPU-bound runs.
+
+## Escalation
+
+- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
+- For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/

package/skills/wp-playground/references/blueprints.md

@@ -0,0 +1,36 @@
+## Blueprint quick reference
+
+Blueprints are JSON recipes that describe how Playground should set up WordPress.
+
+### Minimal example
+
+```json
+{
+  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
+  "steps": [
+    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
+    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
+  ]
+}
+```
+
+### Common steps (non-exhaustive)
+
+- `setSiteUrl`, `setHomeUrl`
+- `installTheme`, `installPlugin` (ZIP URLs or local paths when allowed)
+- `activateTheme`, `activatePlugin`
+- `runPHP` (inline PHP)
+- `applyPatches` (filesystem patch)
+- `writeFile` (create/update files)
+- `importFile` (XML/WXR)
+- `wpConfigConstants` (define constants)
+- `preferredVersions` (pick WP/PHP; matches CLI `--wp` / `--php`)
+- `blueprintSteps` that include `extraLibraries` (e.g., Jetpack) and `features.networking` when browser networking is required
+
+### Tips
+
+- Use `--blueprint-may-read-adjacent-files` when the blueprint needs local files (e.g., custom plugin ZIP) during `run-blueprint` or `build-snapshot`.
+- For iterative authoring, keep blueprints small and compose via separate files.
+- Validate against the published schema URL above to catch typos.
+- For Gutenberg/nightly testing, set `--wp=<version>` to align with target WP.
+- To share quickly, encode the blueprint as base64 in the Playground URL fragment or host the JSON/ZIP and pass `?blueprint-url=…`.

package/skills/wp-playground/references/cli-commands.md

@@ -0,0 +1,39 @@
+## Playground CLI command cheatsheet
+
+> Requires Node.js 20.18+ and npm/npx.
+> Latest version: 3.0.20 (November 2025)
+
+### What's new in 2025
+
+- **PHP 8.3 is now the default** (since July 2025).
+- **New PHP extensions**: ImageMagick, SOAP, and AVIF GD support.
+- **OpCache enabled**: 42% faster response times (185ms → 108ms average).
+- **Multi-worker default**: `--experimental-multi-worker` now defaults to CPU count minus one.
+
+### Install / run server
+
+- `npx @wp-playground/cli@latest server [--port=9400] [--auto-mount] [--wp=<ver>] [--php=<ver>] [--verbosity=debug] [--blueprint=<url-or-path>]`
+- Mounts:
+  - `--auto-mount` (detect plugin/theme in CWD)
+  - `--mount=/abs/host:/vfs/path` (repeatable)
+  - `--mount-before-install` (apply mounts before WP install)
+
+### Run a blueprint
+
+- `npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> [--blueprint-may-read-adjacent-files] [--wp=<ver>] [--php=<ver>] [--verbosity=debug]`
+- Use for scripted setup; no persistent server.
+
+### Build a snapshot
+
+- `npx @wp-playground/cli@latest build-snapshot --blueprint=<file-or-url> --outfile=./site.zip [--verbosity=debug]`
+- Produces a sharable ZIP usable by Playground UI or other CLI commands.
+
+### Debugging flags
+
+- `--xdebug` / `--enable-xdebug` (depends on release) to start Xdebug listener.
+- `--experimental-multi-worker` to speed multi-step blueprints; disable if unstable.
+
+### Version control
+
+- `--wp=<version>` to pick WordPress version (defaults to latest).
+- `--php=<version>` to pick PHP version (defaults to 8.3 since July 2025).

package/skills/wp-playground/references/debugging.md

@@ -0,0 +1,16 @@
+## Debugging WordPress Playground
+
+- Start CLI with Xdebug: `server --auto-mount --xdebug` (or `--enable-xdebug` depending on release). The CLI prints host/port and IDE key to configure your debugger.
+- If breakpoints are not hit, confirm:
+  - IDE listens on the port shown by CLI.
+  - Path mappings include the mounted VFS path used by Playground.
+- For slow or stuck runs:
+  - Add `--verbosity=debug` to see step-level logs.
+  - Disable `--experimental-multi-worker` if it was enabled.
+- For mount issues:
+  - Prefer absolute paths in `--mount`.
+  - Use `--mount-before-install` when installer steps need files present early.
+- To inspect runtime state:
+  - Open the Playground browser console; the Service Worker logs network/FS events.
+  - Use the “Terminal” tab (if available) to run WP-CLI inside the instance.
+

package/skills/wp-plugin-development/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: wp-plugin-development
+description: "Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Plugin Development
+
+## When to use
+
+Use this skill for plugin work such as:
+
+- creating or refactoring plugin structure (bootstrap, includes, namespaces/classes)
+- adding hooks/actions/filters
+- activation/deactivation/uninstall behavior and migrations
+- adding settings pages / options / admin UI (Settings API)
+- security fixes (nonces, capabilities, sanitization/escaping, SQL safety)
+- packaging a release (build artifacts, readme, assets)
+
+## Inputs required
+
+- Repo root + target plugin(s) (path to plugin main file if known).
+- Where this plugin runs: single site vs multisite; WP.com conventions if applicable.
+- Target WordPress + PHP versions (affects available APIs and placeholder support in `$wpdb->prepare()`).
+
+## Procedure
+
+### 0) Triage and locate plugin entrypoints
+
+1. Run triage:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Detect plugin headers (deterministic scan):
+   - `node skills/wp-plugin-development/scripts/detect_plugins.mjs`
+
+If this is a full site repo, pick the specific plugin under `wp-content/plugins/` or `mu-plugins/` before changing code.
+
+### 1) Follow a predictable architecture
+
+Guidelines:
+
+- Keep a single bootstrap (main plugin file with header).
+- Avoid heavy side effects at file load time; load on hooks.
+- Prefer a dedicated loader/class to register hooks.
+- Keep admin-only code behind `is_admin()` (or admin hooks) to reduce frontend overhead.
+
+See:
+- `references/structure.md`
+
+### 2) Hooks and lifecycle (activation/deactivation/uninstall)
+
+Activation hooks are fragile; follow guardrails:
+
+- register activation/deactivation hooks at top-level, not inside other hooks
+- flush rewrite rules only when needed and only after registering CPTs/rules
+- uninstall should be explicit and safe (`uninstall.php` or `register_uninstall_hook`)
+
+See:
+- `references/lifecycle.md`
+
+### 3) Settings and admin UI (Settings API)
+
+Prefer Settings API for options:
+
+- `register_setting()`, `add_settings_section()`, `add_settings_field()`
+- sanitize via `sanitize_callback`
+
+See:
+- `references/settings-api.md`
+
+### 4) Security baseline (always)
+
+Before shipping:
+
+- Validate/sanitize input early; escape output late.
+- Use nonces to prevent CSRF *and* capability checks for authorization.
+- Avoid directly trusting `$_POST` / `$_GET`; use `wp_unslash()` and specific keys.
+- Use `$wpdb->prepare()` for SQL; avoid building SQL with string concatenation.
+
+See:
+- `references/security.md`
+
+### 5) Data storage, cron, migrations (if needed)
+
+- Prefer options for small config; custom tables only if necessary.
+- For cron tasks, ensure idempotency and provide manual run paths (WP-CLI or admin).
+- For schema changes, write upgrade routines and store schema version.
+
+See:
+- `references/data-and-cron.md`
+
+## Verification
+
+- Plugin activates with no fatals/notices.
+- Settings save and read correctly (capability + nonce enforced).
+- Uninstall removes intended data (and nothing else).
+- Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets.
+
+## Failure modes / debugging
+
+- Activation hook not firing:
+  - hook registered incorrectly (not in main file scope), wrong main file path, or plugin is network-activated
+- Settings not saving:
+  - settings not registered, wrong option group, missing capability, nonce failure
+- Security regressions:
+  - nonce present but missing capability checks; or sanitized input not escaped on output
+
+See:
+- `references/debugging.md`
+
+## Escalation
+
+For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.

package/skills/wp-plugin-development/references/data-and-cron.md

@@ -0,0 +1,19 @@
+# Data storage, cron, and upgrades
+
+Use this file when adding persistent storage, background jobs, or upgrade routines.
+
+## Data storage
+
+- Prefer Options API for small config/state.
+- Use custom tables only when needed; store schema version and provide upgrade paths.
+
+## Cron
+
+- Ensure tasks are idempotent (may run late or multiple times).
+- Provide a manual trigger path for debugging (WP-CLI or admin-only action).
+
+## Database safety note
+
+If using `$wpdb->prepare()`, avoid building queries with concatenated user input.
+Recent WordPress versions support identifier placeholders (`%i`) but you must not assume it exists without checking capabilities or target versions.
+

package/skills/wp-plugin-development/references/debugging.md

@@ -0,0 +1,19 @@
+# Debugging quick routes
+
+## Plugin doesn’t load / fatal errors
+
+- Confirm correct plugin main file and header.
+- Check PHP error logs and `WP_DEBUG_LOG`.
+- If the repo is a site repo, confirm you edited the correct plugin under `wp-content/plugins/`.
+
+## Activation hook surprises
+
+- Hooks must be registered at top-level.
+- Activation runs in a special context; avoid assuming other hooks already ran.
+
+## Settings not saving
+
+- Confirm `register_setting()` is called.
+- Confirm the option group matches the form.
+- Confirm capability checks and nonces.
+

package/skills/wp-plugin-development/references/lifecycle.md

@@ -0,0 +1,33 @@
+# Activation, deactivation, uninstall
+
+Use this file for lifecycle changes and data cleanup.
+
+## Activation / deactivation hooks
+
+- `register_activation_hook( __FILE__, 'callback' )`
+- `register_deactivation_hook( __FILE__, 'callback' )`
+
+Guardrails:
+
+- These hooks must be registered at top-level (not inside other hooks).
+- If you flush rewrite rules, ensure rules are registered first (often via a shared function called both on `init` and activation).
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/activation-deactivation-hooks/
+
+## Uninstall
+
+Preferred approaches:
+
+- `uninstall.php` (runs only on uninstall)
+- `register_uninstall_hook()`
+
+Guardrails:
+
+- Check `WP_UNINSTALL_PLUGIN` before running destructive cleanup.
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/
+

package/skills/wp-plugin-development/references/security.md

@@ -0,0 +1,29 @@
+# Security guardrails (plugin work)
+
+Use this file when making security fixes or when handling any input/output.
+
+## Nonces + permissions
+
+- Nonces help prevent CSRF, not authorization.
+- Always pair nonces with capability checks (`current_user_can()` or a more specific capability).
+
+Upstream reference:
+
+- https://developer.wordpress.org/apis/security/nonces/
+
+## Sanitization and escaping
+
+Golden rule:
+
+- sanitize/validate on input, escape on output.
+
+Practical rules:
+
+- never process the entire `$_POST` / `$_GET` array; read explicit keys
+- use `wp_unslash()` before sanitizing when needed
+- use prepared statements for SQL; avoid interpolating user input into queries
+
+Common review guidance:
+
+- https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
+