initial

.agents/skills/wp-wpcli-and-ops/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: wp-wpcli-and-ops
+description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
+---
+
+# WP-CLI and Ops
+
+## When to use
+
+Use this skill when the task involves WordPress operational work via WP-CLI, including:
+
+- `wp search-replace` (URL changes, domain migrations, protocol switch)
+- DB export/import, resets, and inspections (`wp db *`)
+- plugin/theme install/activate/update, language packs
+- cron event listing/running
+- cache/rewrite flushing
+- multisite operations (`wp site *`, `--url`, `--network`)
+- building repeatable scripts (`wp-cli.yml`, shell scripts, CI jobs)
+
+## Inputs required
+
+- Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
+- How to target the correct site root:
+  - `--path=<wordpress-root>` and (multisite) `--url=<site-url>`
+- Whether this is multisite and whether commands should run network-wide.
+- Any constraints (no downtime, no DB writes, maintenance window).
+
+## Procedure
+
+### 0) Guardrails: confirm environment and blast radius
+
+WP-CLI commands can be destructive. Before running anything that writes:
+
+1. Confirm environment (dev/staging/prod).
+2. Confirm targeting (path/url) so you don’t hit the wrong site.
+3. Make a backup when performing risky operations.
+
+Read:
+- `references/safety.md`
+
+### 1) Inspect WP-CLI and site targeting (deterministic)
+
+Run the inspector:
+
+- `node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]`
+
+If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.
+
+### 2) Choose the right workflow
+
+#### A) Safe URL/domain migration (`search-replace`)
+
+Follow a safe sequence:
+
+1. `wp db export` (backup)
+2. `wp search-replace --dry-run` (review impact)
+3. Run the real replace with appropriate flags
+4. Flush caches/rewrite if needed
+
+Read:
+- `references/search-replace.md`
+
+#### B) Plugin/theme operations
+
+Use `wp plugin *` / `wp theme *` and confirm you’re acting on the intended site (and network) first.
+
+Read:
+- `references/packages-and-updates.md`
+
+#### C) Cron and queues
+
+Inspect cron state and run individual events for debugging rather than “run everything blindly”.
+
+Read:
+- `references/cron-and-cache.md`
+
+#### D) Multisite operations
+
+Multisite changes can affect many sites. Always decide whether you’re operating:
+
+- on a single site (`--url=`), or
+- network-wide (`--network` / iterating sites)
+
+Read:
+- `references/multisite.md`
+
+### 3) Automation patterns (scripts + wp-cli.yml)
+
+For repeatable ops, prefer:
+
+- `wp-cli.yml` for defaults (path/url, PHP memory limits)
+- shell scripts that log commands and stop on error
+- CI jobs that run read-only checks by default
+
+Read:
+- `references/automation.md`
+
+## Verification
+
+- Re-run `wpcli_inspect` after changes that could affect targeting or config.
+- Confirm intended side effects:
+  - correct URLs updated
+  - plugins/themes in expected state
+  - cron/caches flushed where needed
+- If there’s a health check endpoint or smoke test suite, run it after ops changes.
+
+## Failure modes / debugging
+
+- “Error: This does not seem to be a WordPress installation.”
+  - wrong `--path`, wrong container, or missing `wp-config.php`
+- Multisite commands affecting the wrong site
+  - missing `--url` or wrong URL
+- Search-replace causes unexpected serialization issues
+  - wrong flags or changing serialized data unsafely
+
+See:
+- `references/debugging.md`
+
+## Escalation
+
+- If you cannot confirm environment safety, do not run write operations.
+- If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.

.agents/skills/wp-wpcli-and-ops/references/automation.md

@@ -0,0 +1,30 @@
+# Automation with WP-CLI
+
+Use this file when turning an ops sequence into a repeatable script or CI job.
+
+## `wp-cli.yml`
+
+If the repo uses `wp-cli.yml`, use it to standardize:
+
+- `path:` (WordPress root)
+- `url:` (default site)
+- PHP settings (memory limits)
+
+## Shell scripting
+
+Guardrails for scripts:
+
+- `set -euo pipefail`
+- print commands before running them
+- make destructive operations require an explicit flag (e.g. `--apply`)
+
+## CI jobs
+
+Prefer CI jobs that are read-only by default:
+
+- `wp core version`
+- `wp plugin list`
+- `wp theme list`
+
+Only enable write operations in dedicated deploy/maintenance workflows.
+

.agents/skills/wp-wpcli-and-ops/references/cron-and-cache.md

@@ -0,0 +1,23 @@
+# Cron, caches, and rewrites
+
+Use this file when debugging background jobs or “changes not visible”.
+
+## Cron
+
+- List scheduled events:
+  - `wp cron event list`
+- Run a specific event now:
+  - `wp cron event run <hook>`
+
+## Cache + rewrite
+
+- Flush object cache:
+  - `wp cache flush`
+- Flush rewrite rules:
+  - `wp rewrite flush`
+
+## Guardrails
+
+- Don’t “run all cron events” on production without understanding impact.
+- Cache flush can cause load spikes; coordinate if needed.
+

.agents/skills/wp-wpcli-and-ops/references/debugging.md

@@ -0,0 +1,17 @@
+# Debugging WP-CLI
+
+## WP not found / wrong WP root
+
+- Run `wp --info`.
+- Provide `--path=<wordpress-root>` if WP is not in the current directory.
+- Confirm `wp-config.php` exists in the expected root.
+
+## HTTP/URL targeting issues
+
+- On multisite, include `--url=<site-url>` for site-specific actions.
+
+## Permission/file ownership issues
+
+- If running in containers, ensure you’re using the same user/volume mapping as the app.
+- Avoid `--allow-root` unless you understand the environment and have no alternative.
+

.agents/skills/wp-wpcli-and-ops/references/multisite.md

@@ -0,0 +1,22 @@
+# Multisite targeting
+
+Use this file any time you might be operating on multisite.
+
+## Key flags
+
+- `--url=<site-url>` targets a specific site/blog context.
+- `--network` applies to the network where supported.
+
+## Common commands
+
+- List sites:
+  - `wp site list`
+- Get site options for a specific site:
+  - `wp option get siteurl --url=<site-url>`
+
+## Guardrails
+
+- Always include `--url` when you mean “one site” in a multisite install.
+- If you need to run something across sites, prefer scripting:
+  - list sites → iterate → run a safe per-site command.
+

.agents/skills/wp-wpcli-and-ops/references/packages-and-updates.md

@@ -0,0 +1,22 @@
+# Plugin/theme operations
+
+Use this file for installs, activation, updates, and listing state.
+
+## Common commands
+
+- Plugins:
+  - `wp plugin list`
+  - `wp plugin status <slug>`
+  - `wp plugin activate <slug>`
+  - `wp plugin deactivate <slug>`
+  - `wp plugin update --all`
+- Themes:
+  - `wp theme list`
+  - `wp theme activate <slug>`
+  - `wp theme update --all`
+
+## Guardrails
+
+- On production, avoid `update --all` without a maintenance window.
+- On multisite, plugin activation may be per-site or network-wide; confirm intent.
+

.agents/skills/wp-wpcli-and-ops/references/safety.md

@@ -0,0 +1,30 @@
+# Safety rules (WP-CLI)
+
+Use this file before running any write operations.
+
+## Golden rules
+
+- Assume production is **unsafe** unless explicitly confirmed.
+- Always confirm targeting:
+  - `--path` (WordPress root)
+  - `--url` (multisite / specific site targeting)
+- Prefer a backup (`wp db export`) before risky operations.
+- Prefer `--dry-run` where available (especially `search-replace`).
+
+## High-risk commands (require explicit confirmation)
+
+- `wp db reset`
+- `wp db import` (overwrites data)
+- `wp search-replace` (can affect serialized data and URLs)
+- bulk deletes (`wp post delete --force --all`, `wp user delete --reassign`, etc.)
+- plugin/theme mass updates on production
+
+## Logging
+
+For ops scripts, log:
+
+- date/time
+- environment (dev/staging/prod)
+- exact WP-CLI commands
+- exit codes
+

.agents/skills/wp-wpcli-and-ops/references/search-replace.md

@@ -0,0 +1,40 @@
+# Safe `wp search-replace`
+
+Use this file when migrating domains, switching http→https, or changing paths.
+
+## Recommended workflow
+
+1. Backup:
+   - `wp db export`
+2. Dry run:
+   - `wp search-replace OLD NEW --dry-run`
+3. Run for real (carefully choose scope):
+   - consider `--all-tables-with-prefix` if you need to include non-core tables with the WP prefix
+4. Flush:
+   - `wp cache flush`
+   - `wp rewrite flush`
+
+## Multisite notes
+
+For multisite, decide whether you’re replacing:
+
+- a single site (`--url=...`), or
+- across the network (`--network` or iterating `wp site list`).
+
+Read:
+- `references/multisite.md`
+
+## Common flags
+
+- `--dry-run`
+- `--precise` (slower but can be safer in complex cases)
+- `--skip-columns=...` (avoid touching large/binary columns)
+- `--report-changed-only`
+
+## Serialization caution
+
+WP-CLI search-replace is designed to handle PHP serialized data, but you must still:
+
+- avoid replacing within binary/blob columns
+- validate results with application smoke tests
+

.agents/skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs

@@ -0,0 +1,90 @@
+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 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 main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  const info = runWp(["--info"], { pathArg: null, urlArg: null, allowRoot: opts.allowRoot });
+  const report = {
+    tool: { name: "wpcli_inspect", version: TOOL_VERSION },
+    wpCli: {
+      available: info.ok,
+      info,
+    },
+    wordpress: {
+      path: opts.path,
+      url: opts.url,
+      isInstalled: null,
+      coreVersion: null,
+      isMultisite: null,
+      siteurl: null,
+      home: null,
+    },
+    notes: [],
+  };
+
+  if (!info.ok) {
+    report.notes.push("WP-CLI not available on PATH. Install WP-CLI or run inside the intended container/environment.");
+    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.wordpress.isInstalled = isInstalled.ok;
+
+  if (!isInstalled.ok) {
+    report.notes.push("WordPress not detected at the given path/url. Check --path/--url (multisite) and that wp-config.php is present.");
+    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.wordpress.coreVersion = coreVersion.ok ? coreVersion.stdout : null;
+
+  const isMultisite = runWp(["core", "is-installed", "--network"], {
+    pathArg: opts.path,
+    urlArg: opts.url,
+    allowRoot: opts.allowRoot,
+  });
+  // If network check passes, we can assume multisite. If it fails, it might still be multisite depending on context.
+  report.wordpress.isMultisite = isMultisite.ok;
+
+  const siteurl = runWp(["option", "get", "siteurl"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.wordpress.siteurl = siteurl.ok ? siteurl.stdout : null;
+
+  const home = runWp(["option", "get", "home"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
+  report.wordpress.home = home.ok ? home.stdout : null;
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main();