wordpress-agent-kit 0.4.0 → 0.6.0

package/.agents/skills/wp-wpengine/scripts/ci-gate.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ci-gate.sh — run the full CI gate locally before pushing.
+#
+# Mirrors what GitHub Actions ci-gate.yml runs. Use this before any push
+# to a branch that triggers a WP Engine deploy.
+#
+# Usage:
+#   bash scripts/ci-gate.sh              # run both gates
+#   bash scripts/ci-gate.sh --php-only   # PHP gate only
+#   bash scripts/ci-gate.sh --js-only    # JS/TS gate only
+#
+# Exit code: 0 = all passed, 1 = at least one check failed.
+
+set -uo pipefail
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+
+PHP_ONLY=false
+JS_ONLY=false
+for arg in "$@"; do
+  [[ "$arg" == "--php-only" ]] && PHP_ONLY=true
+  [[ "$arg" == "--js-only" ]] && JS_ONLY=true
+done
+
+PASS=0
+FAIL=0
+
+run() {
+  local label="$1"; shift
+  echo "▶ $label"
+  if "$@" 2>&1; then
+    echo "  ✓ $label"
+    ((PASS++))
+  else
+    echo "  ✗ FAILED: $label"
+    ((FAIL++))
+    return 1
+  fi
+}
+
+# ── PHP gate ──────────────────────────────────────────────────────────────────
+if ! $JS_ONLY; then
+  echo ""
+  echo "── PHP gate ──────────────────────────────────────────────────────────"
+  if command -v composer >/dev/null 2>&1 && [ -f composer.json ]; then
+    if [ ! -d vendor ]; then
+      echo "▶ composer install"
+      composer install --no-interaction --quiet
+    fi
+
+    run "php -l (all tracked PHP files)" \
+      bash -c 'git ls-files "*.php" | xargs -P4 php -l > /dev/null'
+
+    if [ -x vendor/bin/phpcs ]; then
+      run "phpcs (WordPress coding standards)" composer run phpcs
+    else
+      echo "  ⚠  phpcs not found — run: composer install"
+    fi
+
+    if [ -x vendor/bin/phpstan ]; then
+      run "phpstan (static analysis)" composer run phpstan
+    else
+      echo "  ⚠  phpstan not found — run: composer install"
+    fi
+  else
+    echo "  ⚠  composer not available or no composer.json — skipping PHP gate"
+  fi
+fi
+
+# ── JS/TS gate ────────────────────────────────────────────────────────────────
+if ! $PHP_ONLY; then
+  echo ""
+  echo "── JS/TS gate ────────────────────────────────────────────────────────"
+  if [ -f package.json ]; then
+    if [ ! -d node_modules ]; then
+      echo "▶ npm install"
+      npm install --silent
+    fi
+
+    if [ -x node_modules/.bin/biome ]; then
+      run "biome check (lint + format)" npx biome check .
+    else
+      echo "  ⚠  biome not installed — run: npm install"
+    fi
+
+    if npm run typecheck --if-present 2>/dev/null; then
+      ((PASS++))
+    elif command -v tsc >/dev/null 2>&1 || [ -x node_modules/.bin/tsc ]; then
+      run "tsc --noEmit (type check)" npx tsc --noEmit
+    fi
+
+    if npm run test --if-present 2>/dev/null; then
+      ((PASS++))
+    fi
+
+    if npm run build --if-present 2>/dev/null; then
+      ((PASS++))
+    fi
+  else
+    echo "  ⚠  No package.json — skipping JS/TS gate"
+  fi
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "── CI Gate Result ────────────────────────────────────────────────────"
+echo "  Passed : $PASS"
+echo "  Failed : $FAIL"
+echo ""
+
+if [[ "$FAIL" -eq 0 ]]; then
+  echo "✅ Gate green — safe to push."
+  exit 0
+else
+  echo "❌ Gate failed — fix the issues above before pushing."
+  echo "   --no-verify is not a valid workaround; CI will catch the same failures."
+  exit 1
+fi

package/.agents/skills/wp-wpengine/scripts/wpe-check.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# wpe-check.sh — verify SSH connectivity to all configured WP Engine environments.
+#
+# Reads installs from wp-cli.yml @aliases (ssh: field) or from WPE_INSTALLS env var.
+# Useful after first-time machine setup or when debugging SSH issues.
+#
+# Usage:
+#   bash scripts/wpe-check.sh
+#   WPE_INSTALLS="mysite mysitestg mysitedev" bash scripts/wpe-check.sh
+#
+# Exit code: 0 = all connected, 1 = at least one failed.
+
+set -uo pipefail
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+
+SSH_OPTS="-o BatchMode=yes -o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new"
+
+# ── Discover installs from wp-cli.yml @aliases ────────────────────────────────
+declare -A ALIAS_MAP   # install → alias label
+CURRENT_ALIAS=""
+
+if [ -f wp-cli.yml ]; then
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^@([a-zA-Z0-9_-]+): ]]; then
+      CURRENT_ALIAS="${BASH_REMATCH[1]}"
+    elif [[ "$line" =~ ^[[:space:]]+ssh:[[:space:]]+([^@[:space:]]+)@[^[:space:]]+ && -n "$CURRENT_ALIAS" ]]; then
+      INSTALL="${BASH_REMATCH[1]}"
+      ALIAS_MAP["$INSTALL"]="@${CURRENT_ALIAS}"
+      CURRENT_ALIAS=""
+    fi
+  done < wp-cli.yml
+fi
+
+# Fallback: WPE_INSTALLS env var
+if [ "${#ALIAS_MAP[@]}" -eq 0 ] && [ -n "${WPE_INSTALLS:-}" ]; then
+  for slug in $WPE_INSTALLS; do
+    ALIAS_MAP["$slug"]="$slug"
+  done
+fi
+
+if [ "${#ALIAS_MAP[@]}" -eq 0 ]; then
+  echo "No WP Engine installs found."
+  echo ""
+  echo "Options:"
+  echo "  1. Add @aliases with 'ssh: <install>@<install>.ssh.wpengine.net' to wp-cli.yml"
+  echo "  2. Set WPE_INSTALLS='slug1 slug2 slug3' environment variable"
+  exit 1
+fi
+
+echo ""
+echo "── WP Engine SSH connectivity ────────────────────────────────────────"
+printf "  %-25s %-15s %-12s %s\n" "Install" "Alias" "Status" "WP version"
+echo "  ─────────────────────────────────────────────────────────────────"
+
+PASS=0
+FAIL=0
+
+for INSTALL in "${!ALIAS_MAP[@]}"; do
+  ALIAS="${ALIAS_MAP[$INSTALL]}"
+  SSH_HOST="${INSTALL}.ssh.wpengine.net"
+
+  WP_VERSION=$(ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" \
+    wp core version --skip-plugins --skip-themes 2>/dev/null || echo "")
+
+  if [ -n "$WP_VERSION" ]; then
+    printf "  %-25s %-15s %-12s %s\n" "$INSTALL" "$ALIAS" "✓ connected" "$WP_VERSION"
+    ((PASS++))
+  else
+    printf "  %-25s %-15s %-12s %s\n" "$INSTALL" "$ALIAS" "✗ FAILED" "—"
+    ((FAIL++))
+  fi
+done
+
+echo ""
+echo "  $PASS connected  |  $FAIL failed"
+
+if [[ "$FAIL" -gt 0 ]]; then
+  echo ""
+  echo "Troubleshooting:"
+  echo "  • Confirm key exists:  ls -la ~/.ssh/wpengine_ed25519"
+  echo "  • Confirm permissions: chmod 600 ~/.ssh/wpengine_ed25519"
+  echo "  • Trust the host:      ssh-keyscan -H ssh.wpengine.net >> ~/.ssh/known_hosts"
+  echo "  • Check portal:        https://my.wpengine.com/ssh_keys"
+  echo "  • Verify git access:   ssh git@git.wpengine.com info"
+fi
+
+echo ""
+[[ "$FAIL" -eq 0 ]] && exit 0 || exit 1

package/.agents/skills/wp-wpengine/scripts/wpe-preflight.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# wpe-preflight.sh — pre-deploy sanity checks for a WP Engine environment.
+#
+# Verifies SSH access, WP-CLI, site URL consistency, HTTP health, and
+# active plugin count before any deploy touches production or staging.
+#
+# Usage:
+#   INSTALL=mysite bash scripts/wpe-preflight.sh [staging|production]
+#   WPE_INSTALL=mysite bash scripts/wpe-preflight.sh production
+#
+# Exit code: 0 = all checks passed (safe to deploy), 1 = at least one failed.
+
+set -uo pipefail
+
+ENV="${1:-production}"
+INSTALL="${WPE_INSTALL:-${INSTALL:-}}"
+
+if [ -z "$INSTALL" ]; then
+  echo "❌ Usage: INSTALL=<slug> bash scripts/wpe-preflight.sh [staging|production]"
+  echo "   The install slug is the WP Engine environment name (e.g., 'mysite', 'mysitestg')."
+  exit 1
+fi
+
+SSH_HOST="${INSTALL}.ssh.wpengine.net"
+SSH_OPTS="-o BatchMode=yes -o ConnectTimeout=15 -o StrictHostKeyChecking=accept-new"
+WP="ssh $SSH_OPTS ${INSTALL}@${SSH_HOST} wp"
+
+PASS=0
+FAIL=0
+
+check() {
+  local label="$1"; shift
+  printf "  %-50s" "$label"
+  local output
+  if output=$("$@" 2>&1); then
+    echo "✓  $output"
+    ((PASS++))
+  else
+    echo "✗  FAILED"
+    echo "     $output" >&2
+    ((FAIL++))
+  fi
+}
+
+echo ""
+echo "── WP Engine preflight: ${INSTALL} (${ENV}) ─────────────────────"
+echo ""
+
+# ── SSH ───────────────────────────────────────────────────────────────────────
+echo "SSH"
+check "SSH gateway reachable" \
+  ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" echo "connected"
+
+check "WP-CLI available" \
+  $WP --info --skip-plugins --skip-themes
+
+# ── WordPress ─────────────────────────────────────────────────────────────────
+echo ""
+echo "WordPress"
+check "WP core version" \
+  $WP core version --skip-plugins --skip-themes
+
+check "siteurl option readable" \
+  $WP option get siteurl --skip-plugins --skip-themes
+
+check "Active plugins present (count > 0)" \
+  bash -c "COUNT=\$(${WP} plugin list --status=active --format=count --skip-plugins --skip-themes 2>&1); echo \"\$COUNT active\"; [[ \"\$COUNT\" -gt 0 ]]"
+
+check "No pending DB upgrades" \
+  $WP core update-db --dry-run --skip-plugins --skip-themes
+
+# ── HTTP health ───────────────────────────────────────────────────────────────
+echo ""
+echo "HTTP health"
+SITE_URL=$(ssh $SSH_OPTS "${INSTALL}@${SSH_HOST}" \
+  wp option get home --skip-plugins --skip-themes 2>/dev/null || echo "")
+
+if [ -n "$SITE_URL" ]; then
+  check "Homepage returns 2xx/3xx" \
+    bash -c "STATUS=\$(curl -s -o /dev/null -w '%{http_code}' -L --max-time 15 '${SITE_URL}'); echo \"HTTP \$STATUS\"; [[ \"\$STATUS\" -ge 200 && \"\$STATUS\" -lt 400 ]]"
+
+  check "No PHP errors in homepage body" \
+    bash -c "BODY=\$(curl -sL --max-time 15 '${SITE_URL}'); echo \"\${#BODY} chars\"; ! echo \"\$BODY\" | grep -qi 'fatal error\|parse error\|warning: '"
+
+  check "wp-json REST API responds" \
+    bash -c "STATUS=\$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 '${SITE_URL}/wp-json/wp/v2/'); echo \"HTTP \$STATUS\"; [[ \"\$STATUS\" -ge 200 && \"\$STATUS\" -lt 400 ]]"
+else
+  echo "  ⚠  Could not retrieve site URL — skipping HTTP checks"
+fi
+
+# ── Result ────────────────────────────────────────────────────────────────────
+echo ""
+echo "── Preflight result ──────────────────────────────────────────────────"
+echo "  Passed : $PASS"
+echo "  Failed : $FAIL"
+echo ""
+
+if [[ "$FAIL" -eq 0 ]]; then
+  echo "✅ All checks passed — safe to deploy to ${ENV}."
+  exit 0
+else
+  echo "❌ Preflight failed — resolve the issues above before deploying to ${ENV}."
+  exit 1
+fi

package/.github/agents/wp-architect.agent.md

@@ -14,8 +14,7 @@ When a task is assigned, you must retrieve information in this sequence:
 
 1.  **Local Project Instructions**: Read `.github/instructions/wordpress-workflow.instructions.md` to understand the specific prefix, folder structure, and dev workflow for this repo.
 
-2.  **Agent Skills**: Consult the `.github/skills/` directory.
-
+2.  **Agent Skills**: Consult the `.agents/skills/` directory.
     - Reference `wp-project-triage` to confirm if you are in a Plugin or Theme context.
     - Reference `wp-block-development` for any Gutenberg/React tasks.
     - Reference `wp-playground` to provide testable blueprints for your code.

package/.github/copilot-instructions.md

@@ -1,2 +1,2 @@
 @workspace /AGENTS.md
-@workspace / .github/instructions/wordpress-workflow.instructions.md
+@workspace / .github/instructions/wordpress-workflow.instructions.md

package/.github/instructions/wordpress-workflow.instructions.md

@@ -1,10 +1,10 @@
 \# WordPress Agent Skills Workflow
 
-This repo uses a local, filesystem-based set of WordPress agent skills under `.github/skills/`. Follow these procedures for every interaction.
+This repo uses a local, filesystem-based set of WordPress agent skills under `.agents/skills/`. Follow these procedures for every interaction.
 
 \## 1. Skill Discovery & Activation
 
-\- \*\*Always start by scanning \`.github/skills/\`\*\* to see which specialized modules are active.
+\- \*\*Always start by scanning \`.agents/skills/\`\*\* to see which specialized modules are active.
 
 \- If the user asks for a Block, explicitly activate the \`wp-block-development\` skill.
 
@@ -38,4 +38,4 @@ Before finalizing a response:
 
 2\. Check if a [WordPress.org Plugin Handbook]\(https://developer.wordpress.org) rule supersedes a generic community pattern.
 
-3\. State which skill was used (e.g., \*"Applied patterns from wp-block-development"\*).
+3\. State which skill was used (e.g., \*"Applied patterns from wp-block-development"\*).

package/AGENTS.md

@@ -1,8 +1,9 @@
 # Project: WordPress Agent Kit (CLI)
 
-This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent configuration for WordPress projects. It helps developers quickly set up `AGENTS.md` and `.github` skills/instructions in their repositories.
+This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent configuration for WordPress projects. It helps developers quickly set up `AGENTS.md` and `.agents/skills/` in their repositories.
 
 ## Tech Stack
+
 - **Language**: TypeScript (Node.js)
 - **Framework**: Commander.js
 - **Prompting**: `@clack/prompts`
@@ -11,20 +12,24 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Lint/Format**: Biome + ESLint
 
 ## Architecture
+
 - **Entry Point**: `src/cli.ts`
 - **Commands**: `src/commands/*.ts` (e.g., `install`, `setup`, `sync-skills`, `playground`, `upgrade`)
 - **Core Logic**: `src/lib/*.ts` (e.g., `installer.ts` for file copying, `triage-mapper.ts` for project detection, `api.ts` for programmatic API)
 - **Utilities**: `src/utils/*.ts` (e.g., `paths.ts`, `run.ts`, `output.ts`, `exit-codes.ts`)
-- **Assets**: 
+- **Assets**:
   - `AGENTS.template.md`: The template file copied to user projects.
-  - `.github/`: The source of skills (14 WordPress skills), instructions, agents, and prompts copied to user projects.
-  - `vendor/wp-agent-skills/`: Submodule containing upstream skills.
+  - `.github/`: Platform-specific agents, instructions, and prompts (copied to target platform dir).
+  - `.agents/skills/`: Universal skills directory (AgentSkills.io convention), copied to target `.agents/skills/`.
+  - `skills-custom/`: Custom skills that survive upstream syncs, merged into `.agents/skills/` on install.
 
 ## Package Exports
+
 - `wordpress-agent-kit` → CLI entry (`dist/cli.js`)
 - `wordpress-agent-kit/api` → Programmatic API (`dist/lib/api.js`)
 
 ## Development Workflow
+
 - **Run locally**: `npm run dev` (uses `tsx src/cli.ts`)
 - **Build**: `npm run build` (outputs to `dist/`)
 - **TypeCheck**: `npm run check` (no-emit type checking)
@@ -34,29 +39,36 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Pre-commit**: Husky runs lint:check + test:run
 
 ## Key Commands
-- `install`: Copies `.github` and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`.
+
+- `install`: Copies `.agents/skills/` (universal convention), platform agents/instructions, and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`. Merges custom skills from `skills-custom/`.
 - `setup`: Interactive wizard that detects project type and configures the kit. Supports `--auto`, `--project-type`, `--tech-stack`, `--yes`.
-- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.github/skills`. Supports `--json`, `--dry-run`.
+- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.agents/skills/` (canonical, AgentSkills.io convention), merging custom skills from `skills-custom/`. Supports `--json`, `--dry-run`.
+- `clean-skills`: Detects and removes orphaned skills that are no longer part of the kit. Supports `--dry-run`, `--remove`, `--json`.
 - `playground`: Launches a local WordPress Playground instance using a blueprint.
 - `upgrade`: Checks for and applies newer versions. Supports `--check-only`, `--force`, `--json`.
 
 ## Agent-Friendly Features (v0.3.0+)
+
 - `--json`: Structured JSON output with success/data/error/time fields
 - `--dry-run`: Preview mode showing what would happen without making changes
 - `--ndjson`: Newline-delimited JSON for streaming long operations
 - `--quiet`: Suppress non-essential output
 - **Semantic exit codes**: 0=OK, 2=Invalid Args, 3=Not Found, 4=Permission Denied, 5=Already Exists, 6=Git Error, 7=Network Error, 8=Validation Error, 130=Cancelled
-- **Programmatic API**: `import { installKitApi, syncSkillsApi, runTriageApi, configureAgentsMdApi } from 'wordpress-agent-kit/api'`
+- **Programmatic API**: `import { installKitApi, syncSkillsApi, runTriageApi, configureAgentsMdApi, cleanSkillsApi } from 'wordpress-agent-kit/api'`
 
 ## Notes for Agents
+
 - When modifying commands, ensure you update the corresponding JSDoc comments.
 - The `src/lib/installer.ts` file is critical as it handles the file copying logic.
 - The `src/lib/triage-mapper.ts` file contains logic for mapping project detection results to configuration options.
 - The `src/lib/api.ts` file exposes the programmatic API — all changes to command logic should flow through to the API.
-- The `vendor` directory is gitignored and populated via submodule or script.
-- The `.github/skills/` directory contains 14 WordPress skills following the AgentSkills.io spec.
+- The `vendor` directory is gitignored and populated via submodule or script. Upstream skills sync to `.github/skills/` (sync buffer) then copy to `.agents/skills/` (canonical).
+- The `.agents/skills/` directory contains 18 WordPress skills (17 upstream + 1 custom `wp-wpengine`) following the AgentSkills.io spec. Skills are installed to `.agents/skills/` (universal convention) instead of platform-specific directories.
 - CI runs on every push: lint, typecheck, test, build. No publish workflow (manual npm publish only).
 
 ## Pi Extension (Package)
+
 - `pi.extensions`: `./extensions/wp-agent-kit` — registers WordPress agent tools
-- `pi.skills`: `./.github/skills` — 14 WordPress skills discoverable by Pi
+- `pi.skills`: `./.agents/skills` — 18 WordPress skills discoverable by Pi (17 upstream + `wp-wpengine` custom from `skills-custom/`). Uses AgentSkills.io convention.
+- Tools: `wp_triage`, `wp_install_kit`, `wp_sync_skills`, `wp_upgrade`, `wp_clean_skills`
+- Commands: `/wp-triage`, `/wp-install`, `/wp-sync-skills`, `/wp-upgrade`, `/wp-clean-skills`

package/AGENTS.template.md

@@ -6,23 +6,33 @@ This repository is WordPress-centric (plugin, theme, block theme, or site). Agen
 
 - **Core Agent**: `.github/agents/wp-architect.agent.md` — the primary agent persona
 - **Workflow Instructions**: `.github/instructions/wordpress-workflow.instructions.md` — project-specific conventions
-- **Skills**: `.github/skills/` — specialized agent skills for WordPress development
+- **Skills**: `.agents/skills/` — specialized agent skills for WordPress development
 
 ## Project Discovery (Required Before Changes)
 
 1. **Run project triage** to classify the codebase:
+
    ```bash
-   node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
+   node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
    ```
+
    This outputs a JSON report with project kind, signals, and tooling.
 
 2. **Route to the right skill**:
-   - If routing is unclear, consult `.github/skills/wordpress-router/references/decision-tree.md`
+   - If routing is unclear, consult `.agents/skills/wordpress-router/references/decision-tree.md`
    - For plugins: `wp-plugin-development`
    - For block themes: `wp-block-themes`
    - For Gutenberg blocks: `wp-block-development`
    - For REST API work: `wp-rest-api`
+   - For Interactivity API: `wp-interactivity-api`
+   - For Abilities API: `wp-abilities-api` / `wp-abilities-audit` / `wp-abilities-verify`
    - For WP-CLI operations: `wp-wpcli-and-ops`
+   - For Playground testing (PHPUnit, E2E, CI): `wp-playground`
+   - For Performance profiling: `wp-performance`
+   - For PHPStan static analysis: `wp-phpstan`
+   - For WP Engine hosting: `wp-wpengine` (optional, requires env vars)
+   - For Design System components: `wpds`
+   - For plugin directory submission: `wp-plugin-directory-guidelines`
 
 3. **Update repo-specific guidance** based on triage results:
    - Confirm the project prefix (functions, classes, constants)
@@ -43,13 +53,13 @@ This repository is WordPress-centric (plugin, theme, block theme, or site). Agen
 
 <!-- Populated by project triage — do not remove -->
 
-| Purpose | Command |
-|---------|---------|
-| Build | <!-- e.g., npm run build --> |
-| Lint (PHP) | <!-- e.g., composer lint --> |
-| Lint (JS/CSS) | <!-- e.g., npm run lint --> |
-| Test | <!-- e.g., npm test, composer test --> |
-| Dev server | <!-- e.g., npm start --> |
+| Purpose       | Command                                |
+| ------------- | -------------------------------------- |
+| Build         | <!-- e.g., npm run build -->           |
+| Lint (PHP)    | <!-- e.g., composer lint -->           |
+| Lint (JS/CSS) | <!-- e.g., npm run lint -->            |
+| Test          | <!-- e.g., npm test, composer test --> |
+| Dev server    | <!-- e.g., npm start -->               |
 
 ## Code Conventions