@ai-kits/wp-ag-kit 1.0.0

package/skills/wp-rest-api/references/authentication.md

@@ -0,0 +1,18 @@
+# Authentication (summary)
+
+## Cookie authentication (in-dashboard / same-site)
+
+- Standard for wp-admin and theme/plugin JS.
+- Requires a REST nonce (`wp_rest`) sent as `X-WP-Nonce` header or `_wpnonce` param.
+- If the nonce is missing, the request is treated as unauthenticated even if cookies exist.
+
+## Application Passwords (external clients)
+
+- Available in WordPress 5.6+.
+- Use HTTPS + Basic Auth with the application password.
+- Recommended over the legacy Basic Auth plugin.
+
+## Auth plugins
+
+- OAuth 1.0a or JWT plugins are common for external apps.
+- Use only if required; follow plugin docs and security guidance.

package/skills/wp-rest-api/references/custom-content-types.md

@@ -0,0 +1,20 @@
+# Custom Content Types (summary)
+
+## Custom post types
+
+- Set `show_in_rest => true` in `register_post_type()` to expose in `wp/v2`.
+- Use `rest_base` to change the route slug.
+- Optionally set `rest_controller_class` (must extend `WP_REST_Controller`).
+
+## Custom taxonomies
+
+- Set `show_in_rest => true` in `register_taxonomy()`.
+- Use `rest_base` and optional `rest_controller_class` (default `WP_REST_Terms_Controller`).
+
+## Adding REST support to existing types
+
+- Use `register_post_type_args` or `register_taxonomy_args` filters to enable `show_in_rest` for types you do not control.
+
+## Discovery links for custom controllers
+
+- If you use a custom controller class, use `rest_route_for_post` or `rest_route_for_term` filters to map objects to routes.

package/skills/wp-rest-api/references/discovery-and-params.md

@@ -0,0 +1,20 @@
+# Discovery and Global Parameters (summary)
+
+## API discovery
+
+- REST API root is discovered via the `Link` header: `rel="https://api.w.org/"`.
+- HTML pages also include a `<link rel="https://api.w.org/" href="...">` element.
+- For non-pretty permalinks, use `?rest_route=/`.
+
+## Global parameters
+
+- `_fields` limits response fields (supports nested meta keys).
+- `_embed` includes linked resources in `_embedded`.
+- `_method` or `X-HTTP-Method-Override` allows POST to simulate PUT/DELETE.
+- `_envelope` puts headers/status in the response body.
+- `_jsonp` enables JSONP for legacy clients.
+
+## Pagination
+
+- Collections accept `page`, `per_page` (1-100), and `offset`.
+- Pagination headers: `X-WP-Total` and `X-WP-TotalPages`.

package/skills/wp-rest-api/references/responses-and-fields.md

@@ -0,0 +1,30 @@
+# Responses and Fields (summary)
+
+## Do not remove core fields
+
+- Removing or changing core fields breaks clients (including wp-admin).
+- Prefer adding new fields or using `_fields` to limit response size.
+
+## register_rest_field
+
+- Use for computed or custom fields.
+- Provide `get_callback`, optional `update_callback`, and `schema`.
+- Register on `rest_api_init`.
+
+## Raw vs rendered content
+
+- For posts, `content.rendered` reflects filters (plugins like ToC inject HTML).
+- Use `?context=edit` (authenticated) to access `content.raw`.
+- Combine with `_fields=content.raw` when you only need the editable body.
+
+## register_meta / register_post_meta / register_term_meta
+
+- Use when the data is stored as meta.
+- Set `show_in_rest => true` to expose under `.meta`.
+- For `object` or `array` types, provide a JSON schema in `show_in_rest.schema`.
+
+## Links and embedding
+
+- Add links with `WP_REST_Response::add_link( $rel, $href, $attrs )`.
+- Use `embeddable => true` to allow `_embed`.
+- Use IANA rels or a custom URI relation; CURIEs can be registered via `rest_response_link_curies`.

package/skills/wp-rest-api/references/routes-and-endpoints.md

@@ -0,0 +1,36 @@
+# Routes and Endpoints (summary)
+
+## Registering routes
+
+- Register routes on the `rest_api_init` hook with `register_rest_route( $namespace, $route, $args )`.
+- A **route** is the URL pattern; an **endpoint** is the method + callback bound to that route.
+- For non-pretty permalinks, the route is accessed via `?rest_route=/namespace/route`.
+
+## Namespacing
+
+- Always namespace routes (`vendor/v1`).
+- **Do not** use the `wp/*` namespace unless you are targeting core.
+
+## Methods
+
+- Use `WP_REST_Server::READABLE` (GET), `CREATABLE` (POST), `EDITABLE` (PUT/PATCH), `DELETABLE` (DELETE).
+- Multiple endpoints can share a route, one per method.
+
+## permission_callback (required)
+
+- Always provide `permission_callback`.
+- Public endpoints should use `__return_true`.
+- For restricted endpoints, use capability checks (`current_user_can`) or object-level authorization.
+- Missing `permission_callback` emits a `_doing_it_wrong` notice in modern WP.
+
+## Arguments
+
+- Register `args` to validate and sanitize inputs.
+- Use `type`, `required`, `default`, `validate_callback`, `sanitize_callback`.
+- Access params via the `WP_REST_Request` object, not `$_GET`/`$_POST`.
+
+## Return values
+
+- Return data via `rest_ensure_response()` or a `WP_REST_Response`.
+- Return `WP_Error` with a `status` in `data` for error responses.
+- Do not call `wp_send_json()` in REST callbacks.

package/skills/wp-rest-api/references/schema.md

@@ -0,0 +1,22 @@
+# Schema and Argument Validation (summary)
+
+## JSON Schema in WordPress
+
+- REST API uses JSON Schema (draft 4 subset) for resource and argument definitions.
+- Provide schema via `get_item_schema()` on controllers or `schema` callbacks on routes.
+- Schema enables discovery (`OPTIONS`) and validation.
+
+## Validation + sanitization
+
+- Use `rest_validate_value_from_schema( $value, $schema )` then `rest_sanitize_value_from_schema( $value, $schema )`.
+- If you override `sanitize_callback`, built-in schema validation will not run; use `rest_validate_request_arg` to keep it.
+- `WP_REST_Controller::get_endpoint_args_for_item_schema()` wires validation automatically.
+
+## Schema caching
+
+- Cache the generated schema on the controller instance (`$this->schema`) to avoid recomputation.
+
+## Formats and types
+
+- Common formats: `date-time`, `uri`, `email`, `ip`, `uuid`, `hex-color`.
+- For `array` and `object` types, you must define `items` or `properties` schemas.

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

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

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

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

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

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

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

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

package/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();

package/skills/wpds/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: wpds
+description: "Use when building UIs leveraging the WordPress Design System (WPDS) and its components, tokens, patterns, etc."
+compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 6.9+ (PHP 7.2.24+)."
+---
+
+# WordPress Design System (WPDS)
+
+## Prerequisites
+
+This skill works best with the **WPDS MCP server** installed. The MCP provides access to WordPress Design System documentation and resources, such as components and DS token lists.
+
+The following terms should be treated as synonyms:
+- "WordPress" and "WP";
+- "Design System" and "DS";
+- "WordPress Design System" and "WPDS".
+
+## When to use
+
+Use this skill when the user mentions:
+
+- building and/or reviewing any UI in a WordPress-related context (for example, Gutenberg, WooCommerce, WordPress.com, Jetpack, etc etc);
+- WordPress Design System, WPDS, Design System;
+- UI components, Design tokens, color primitives, spacing scales, typography variables and presets;
+- Specific component packages such as @wordpress/components or @wordpress/ui;
+
+## Rules
+
+### Use the WPDS MCP server to access WPDS-related documentation
+
+- Use the WPDS MCP server to retrieve the canonical, authoritative documentation:
+  - reference site (`wpds://pages`)
+  - list of available components (`wpds://components`) and specific component information (`wpds://components/:name`)
+  - list of available tokens (`wpds://design-tokens`)
+- DO NOT search the web for canonical documentation about the WordPress Design System. If asked by the user, push back and ask for confirmation, warning them that the MCP server is the best place to provide information
+
+### Required documentation
+
+Before working on any WPDS-related tasks, make sure you read relevant documentation on the reference site. This documentation should take the absolute precedence when evaluating the best course of action for any given tasks.
+
+### Boundaries
+
+- Skip non-UI related aspects of an answer (for example, fetching data from stores, or localizing strings of text).
+- Focus on building UI that adheres as much as possible to the WPDS best practices, uses the most fitting WPDS components/tokens/patterns.
+
+### Tech stack
+
+- Unless you are told otherwise (or gathered specific information from the local context of the request), assume the following tech stack: TypeScript, React, CSS.
+
+### Validation
+
+- If the local context in which a task is running provide lint scripts, use them to validate the proposed code output when possible.
+
+## Output
+
+- As a recap at the end of your response, provide a clear and concise explanation of what the solution does, and add context to why each decision was made.
+- Be explicit about the boundaries, ie. what was explicitly left out of the task because not relevant (eg non-ui related).
+- Provide working code snippets

package/workflows/create-block.md

@@ -0,0 +1,27 @@
+---
+description: Scaffold a new WordPress Gutenberg block using @wordpress/create-block.
+---
+
+# Create WordPress Block Workflow
+
+This workflow guides you through the process of scaffolding a high-quality, modern Gutenberg block.
+
+1. **Prerequisites**
+   - Ensure Node.js and npm are installed.
+   - Verify if the project already uses `@wordpress/scripts`.
+
+2. **Scaffold the Block**
+// turbo
+   - Run `npx @wordpress/create-block@latest` with the desired name and namespace.
+   - Use the `--interactive` flag if custom interactivity is needed.
+
+3. **Configure block.json**
+   - Update `apiVersion` to `3`.
+   - Set up `attributes`, `supports`, and `category`.
+
+4. **Initialize Build**
+// turbo
+   - Run `npm run start` to begin the development build.
+
+5. **Verify Registration**
+   - Check if the block is registered correctly in PHP using `register_block_type_from_metadata`.

package/workflows/wp-lint.md

@@ -0,0 +1,27 @@
+---
+description: Run WordPress-specific linting using @wordpress/scripts and PHPStan.
+---
+
+# WordPress Lint Workflow
+
+This workflow ensures your code follows WordPress Coding Standards (WPCS) and passes static analysis.
+
+1. **Check for Node dependencies**
+   - Check if `node_modules` and `@wordpress/scripts` are present.
+   - If not, advise running `npm install`.
+
+2. **Run JS/Block Linting**
+// turbo
+   - Run `npm run lint:js` or `npx wp-scripts lint-js`.
+
+3. **Run CSS Linting**
+// turbo
+   - Run `npm run lint:css` or `npx wp-scripts lint-style`.
+
+4. **Run PHP Static Analysis**
+// turbo
+   - Use `wp-phpstan` skill if configured.
+   - Run `vendor/bin/phpstan analyze`.
+
+5. **Report Results**
+   - Summarize findings and provide fix recommendations.