@rolepod/wplab 1.2.1

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@rolepod/wplab",
+  "version": "1.2.1",
+  "description": "Novamira-class WordPress operations toolkit for AI coding agents — default-safe wp-cli + REST + scoped fs, opt-in companion for execute-php + runtime introspection. MIT, rolepod ecosystem.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wordpress",
+    "wp-cli",
+    "rolepod",
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "homepage": "https://github.com/nuttaruj/rolepod-wplab",
+  "bugs": "https://github.com/nuttaruj/rolepod-wplab/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nuttaruj/rolepod-wplab.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "nuttaruj",
+    "url": "https://github.com/nuttaruj"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "rolepod-wplab": "./dist/bin/rolepod-wplab.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin",
+    ".cursor-plugin",
+    ".codex-plugin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src tests/unit tests/smoke",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/unit/**/*.ts\" \"tests/smoke/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/unit/**/*.ts\" \"tests/smoke/**/*.ts\"",
+    "doctor": "node ./dist/bin/rolepod-wplab.js doctor",
+    "smoke": "node ./dist/bin/rolepod-wplab.js smoke",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "execa": "^9.0.0",
+    "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "dockerode": "^4.0.0",
+    "node-ssh": "^13.2.0"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^4.0.1",
+    "@types/node": "^20.14.0",
+    "oxlint": "^0.9.0",
+    "prettier": "^3.3.0",
+    "tsup": "^8.2.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/skills/wp-audit-security/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: wp-audit-security
+description: Audit a WordPress target against known vulnerabilities, outdated core/plugins/themes, weak users, file-permission issues, debug flags.
+---
+
+## When to use
+
+- Before deploying a WP site or merging WP-touching changes.
+- After installing a third-party plugin/theme.
+- On a regular cadence as a smoke check (CI cron job).
+- After a security advisory drops for a major WP plugin.
+
+## When NOT to use
+
+- For deep penetration testing. Use specialised tools (WPScan paid feed, Burp Suite, OWASP ZAP).
+- For runtime exploit testing — wplab audits config + version posture, not active vulnerabilities.
+
+## Inputs
+
+- `target_id` — connected WP target.
+- `report_format?` — `markdown` (default, human-readable) or `json` (machine-readable for CI).
+
+## Outputs
+
+- `run_id`
+- `wp_core_outdated` — boolean
+- `outdated_plugins[]` — `{ slug, current, latest }`
+- `outdated_themes[]` — same shape
+- `known_vulnerable_plugins[]` — `{ slug, version, advisory_url }` (CVE lookup via public source, cached locally)
+- `weak_admin_users[]` — `{ login, reason }` (e.g. user named "admin", easy-to-guess username)
+- `file_permission_issues[]` — `{ path, mode, recommended }`
+- `wp_debug_on` — boolean (WP_DEBUG=true is fine on dev, smell on prod)
+- `report_path` — markdown/json file on disk for the full report
+
+## Process
+
+1. Construct `rolepod_wp_audit_security` composite input.
+2. Call the tool — composite chains: wp core check-update, wp plugin status, wp theme status, wp user list with role filter, file stat on key paths, wp_debug detection, CVE feed lookup.
+3. Group findings by severity (CVE matches > outdated plugins > weak users > file perms > debug flags) and surface critical ones inline in the chat.
+4. Save full report to `./.rolepod-wplab/artifacts/<run_id>/audit-report.md` and reference path in reply.
+
+## If the tool is unavailable
+
+Same handling as other shipped skills.
+
+## Examples
+
+```
+User: "audit security"
+Lead → rolepod_wp_audit_security { target_id: "tgt_8585..." }
+Lead reply: "Found 2 critical, 3 medium issues:
+              CRITICAL: Bricks v1.8.5 has CVE-2024-XXXX (auth bypass) — upgrade to 1.9.0+
+              CRITICAL: User 'admin' exists with role administrator — rename
+              MEDIUM:   3 plugins outdated (akismet, hello, contact-form-7)
+              MEDIUM:   wp-config.php is world-readable (644 → 600)
+              MEDIUM:   WP_DEBUG enabled on production-matched siteurl
+              Full report: ./.rolepod-wplab/artifacts/wplab_2026.../audit-report.md"
+```

package/skills/wp-audit-woo/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: wp-audit-woo
+description: Audit WooCommerce config — products, settings, shipping zones, payment gateways. Read-only.
+---
+
+## When to use
+
+- Pre-launch checklist for a WooCommerce shop.
+- After installing/configuring a new payment or shipping plugin.
+- Before merging a WooCommerce-touching change.
+
+## When NOT to use
+
+- Deep transaction debugging (use WP debug + `/wp-introspect` for runtime state).
+- Non-WooCommerce site (tool returns `detected: false` quickly).
+
+## Inputs
+
+- `target_id`.
+- Optional: `include_recent_orders` — default 0 (privacy default).
+
+## Outputs
+
+- Findings consolidated from multiple `rolepod_wp_woo_read` calls per scope: settings_groups, shipping_zones, payment_gateways.
+
+## Process
+
+1. Detect WooCommerce active via `rolepod_wp_woo_read { scope: settings_groups }`.
+2. Loop scopes: shipping_zones, payment_gateways, settings_groups.
+3. Synthesize findings into a brief report. Highlight: zero shipping zones, no active payment gateway, tax not configured.
+
+## If the tool is unavailable
+
+WooCommerce not active on this target. Skip the audit.
+
+## Examples
+
+```
+User: "audit WooCommerce on staging"
+Lead → rolepod_wp_woo_read { target_id, scope: "settings_groups" }
+     → rolepod_wp_woo_read { target_id, scope: "shipping_zones" }
+     → rolepod_wp_woo_read { target_id, scope: "payment_gateways" }
+Lead reply: "✓ tax configured, ✓ 2 shipping zones, ⚠ only Stripe enabled (no fallback)"
+```

package/skills/wp-edit-elementor/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: wp-edit-elementor
+description: Read or modify Elementor page widget trees on a connected WP target via the Elementor adapter.
+---
+
+## When to use
+
+- User wants to inspect or modify an Elementor page structure programmatically (audit widgets, bulk-update settings, migrate between page builders).
+- Target has Elementor active.
+
+## When NOT to use
+
+- Page builder is not Elementor. Use Bricks adapter (`/wp-bricks-read`) or fall back to manual edit.
+- Manual editing in the Elementor admin is faster for one-off design changes.
+
+## Inputs
+
+- `target_id`, `page_id`.
+- For reads: `rolepod_wp_elementor_read { target_id, page_id }`.
+- For writes: `rolepod_wp_elementor_write { target_id, post_id, widget_tree, allow_destructive: true, confirm? }`.
+
+## Outputs
+
+- Read: `pages[] | page` (widget_tree array of nested elements).
+- Write: `bytes_written`, `backup_path` (pre-write backup of `_elementor_data` meta).
+
+## Process
+
+1. Detect Elementor active on target (adapter handshake — `detected` field).
+2. For writes: production guard fires unless `confirm: true`.
+3. Call adapter tool.
+4. Surface diff summary or read content.
+
+## If the tool is unavailable
+
+Either: Elementor not active on this target, OR write op needs companion v0.2 fs-write endpoint and companion not installed. Doctor will distinguish.
+
+## Examples
+
+```
+User: "list Elementor pages on staging.client.com"
+Lead → rolepod_wp_elementor_read { target_id: tgt_staging }
+       → pages: [{ id: 7, title: "Home" }, ...]
+```

package/skills/wp-execute-php/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: wp-execute-php
+description: Run a PHP payload inside the live WordPress request lifecycle via the companion plugin. Requires companion installed + ROLEPOD_WPLAB_PROFILE=power + target not production-matched + confirm:true.
+---
+
+## When to use
+
+- A debugging or introspection task that genuinely needs PHP runtime context (active hooks at call time, plugin-internal cache, transients tied to current request, code paths only reachable inside `init` / `wp_loaded` / `template_redirect`).
+- The user has installed `rolepod-wplab-companion`, set `ROLEPOD_WPLAB_PROFILE=power`, and target is not production-matched.
+
+## When NOT to use
+
+- Anything achievable via wp-cli or REST. Use `rolepod_wp_cli_run` / `rolepod_wp_rest_request` / a typed `wp_*` tool instead.
+- Anything that mutates content. Use typed CRUD tools (`rolepod_wp_post_update`, etc.) so the operation is replayable + audit-trailed via tool schema.
+- Anything on a production-matched target. Tool will refuse; do not retry with override (no override exists).
+- When companion is not installed. Skill fails with a clear "install companion" hint.
+
+## Requires companion?
+
+yes — `rolepod-wplab-companion` installed on target + `ROLEPOD_WPLAB_PROFILE=power` + target not production-matched.
+
+## Inputs
+
+- `target_id` — connected WP target.
+- `payload` — PHP source (no `<?php` tag). MUST pass AST screen: no `eval` / `system` / `shell_exec` / `exec` / `proc_open` / `popen` / `pcntl_*` / `dl` / backtick / dynamic include/require.
+- `timeout_ms?` — default 5000, max 30000.
+- `confirm: true` — REQUIRED literal. Surface the payload to the user before invoking.
+
+## Outputs
+
+- `ok`, `return_value`, `stdout`, `duration_ms`, `php_warnings[]`, `audit_id`.
+
+## Process
+
+1. Verify companion handshake + power profile + non-prod target. If any missing, abort with diagnostic — do not retry.
+2. Show payload to user, wait for explicit confirmation.
+3. Construct `rolepod_wp_execute_php` input with `confirm: true`.
+4. Call tool. Surface `audit_id` + result. Log entry on disk is permanent.
+
+## If the tool is unavailable
+
+Cause is one of:
+- Companion not installed → install from https://github.com/nuttaruj/rolepod-wplab-companion/releases
+- `power` profile not set → `export ROLEPOD_WPLAB_PROFILE=power` and restart MCP
+- Target is production-matched → intentional; no override exists. Use `/wp-scaffold-*` or wp-cli direct on production after manual review.
+
+Run `rolepod-wplab doctor` for a full diagnostic.
+
+## Examples
+
+```
+User: "debug why 'init' hook fires twice"
+Lead → verify companion handshake (rolepod_wp_health_check → companion_ok: true)
+Lead → show payload: "global $wp_filter; return count($wp_filter['init']->callbacks);"
+User confirms
+Lead → rolepod_wp_execute_php { target_id, payload, confirm: true }
+        → { return_value: 47, audit_id: "wplab_audit_4a2b1f" }
+Lead reply: "47 callbacks registered on init. Audit: wplab_audit_4a2b1f."
+```

package/skills/wp-health-check/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: wp-health-check
+description: Return a lightweight diagnostic of a WordPress target — versions, DB connectivity, REST reachability, active plugins/theme, companion presence, warnings.
+---
+
+## When to use
+
+- After installing rolepod-wplab to confirm a target connects.
+- Inside `check-work` workflow to provide WP-context evidence.
+- Before invoking other wplab tools to confirm the target is reachable.
+- After any wp-cli / REST change to verify nothing broke.
+
+## When NOT to use
+
+- For deep performance profiling. Use APM tools (New Relic, Query Monitor inside WP).
+- For security audits — use `/wp-audit-security` instead.
+
+## Inputs
+
+- `target_id` — connected WP target (from `rolepod_wp_connect_local` or `rolepod_wp_connect_rest`).
+
+## Outputs
+
+- `wp_version`, `php_version`, `db_ok`, `wp_cli_ok`, `rest_ok`, `companion_ok`, `site_url`, `warnings[]`.
+
+## Process
+
+1. Call `rolepod_wp_health_check { target_id }`.
+2. Surface any `warnings[]` prominently — they often indicate misconfig the user can fix in 1 minute.
+3. If `companion_ok=false` but the user wants power tools, hint at companion install.
+
+## If the tool is unavailable
+
+The rolepod-wplab MCP server is not registered or is not responding.
+
+- Confirm the plugin is installed: `claude plugin list | grep wplab` (or analogue for Cursor / Codex / Gemini).
+- Run `rolepod-wplab doctor` to diagnose.
+
+Do NOT attempt the work via wp-cli direct, Novamira, or any other backend.
+
+## Examples
+
+```
+User: "WP health"
+Lead → rolepod_wp_health_check { target_id: "tgt_8585f975d001" }
+Lead reply: "WP 6.6.2 / PHP 8.2.10
+              ✓ db_ok, wp_cli_ok, rest_ok
+              ✗ companion_ok=false (install companion for power tools)
+              warnings: REST check deferred to v0.1"
+```

package/skills/wp-introspect/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: wp-introspect
+description: Snapshot WordPress runtime context (hooks, transients, options, request state) via the companion endpoint. Read-only, no eval.
+---
+
+## When to use
+
+- Debugging "why isn't this hook firing?" / "what's in this transient right now?"
+- Auditing plugin behavior without modifying state.
+- Before invoking `/wp-execute-php` to verify the runtime is in the expected state.
+
+## When NOT to use
+
+- For data you can get from wp-cli (`wp option get`, `wp transient get`). Use those — faster, no companion required.
+- For mutation. Use a typed write tool instead.
+
+## Requires companion?
+
+yes — `rolepod-wplab-companion` installed on target.
+
+## Inputs
+
+- `target_id`.
+- `scope` — `hooks` | `transients` | `options_full` | `request_state`.
+- `include_values?` — only effective on non-prod targets (default false).
+
+## Outputs
+
+- `scope`, `report` (shape varies by scope).
+
+## Process
+
+1. Verify companion handshake.
+2. Call `rolepod_wp_introspect { target_id, scope }`.
+3. Surface key findings inline; if `report` is large, save to disk and reference path.
+
+## If the tool is unavailable
+
+Companion not installed; install from companion releases page. Same flow as `/wp-execute-php`.
+
+## Examples
+
+```
+User: "what hooks fire on init?"
+Lead → rolepod_wp_hook_state { target_id, hook: "init" }
+       → callbacks: [{ priority: 10, callback_identifier: "..." }, ...]
+Lead reply: "47 callbacks on init, top 5 by priority: ..."
+```

package/skills/wp-migrate-dryrun/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: wp-migrate-dryrun
+description: Compute a migration plan between two WP targets without applying any changes. Useful for diffing dev → staging → prod.
+---
+
+## When to use
+
+- Plan a migration between environments (e.g. staging → prod) without committing changes.
+- Pre-deploy diff to surface plugin version mismatches, missing options, role drift.
+- Sanity-check that two environments are aligned after a refactor.
+
+## When NOT to use
+
+- One-way data sync (use a dedicated migration plugin like WP Migrate / Duplicator for actual data transfer).
+- Tiny single-table copy (use `rolepod_wp_db_query` directly).
+
+## Inputs
+
+- `source_target_id` — connected source target.
+- `dest_target_id` — connected destination target.
+- `scope[]` — any of: `plugin_versions`, `options`, `users`, `posts`. Default: `[plugin_versions]`.
+
+## Outputs
+
+- `plan` — structured diff per scope.
+- `plan_path` — markdown/json artifact under `./.rolepod-wplab/artifacts/<run_id>/migration-plan.json`.
+
+## Process
+
+1. Verify both targets are connected (call `rolepod_wp_health_check` on each).
+2. Call `rolepod_wp_migrate_dryrun { source_target_id, dest_target_id, scope }`.
+3. Surface key diffs inline (e.g. "5 plugin version mismatches, 12 options only on source").
+4. Reference plan_path for full detail.
+
+## If the tool is unavailable
+
+Same handling as other shipped skills.
+
+## Examples
+
+```
+User: "diff dev vs staging"
+Lead → rolepod_wp_connect_local { path: "..." }   (already connected)
+Lead → rolepod_wp_connect_rest { url: "https://staging.client.com" }
+Lead → rolepod_wp_migrate_dryrun { source_target_id, dest_target_id, scope: ["plugin_versions","users"] }
+       → plan_path: "./.rolepod-wplab/artifacts/wplab_.../migration-plan.json"
+Lead reply: "Plugin diff: WooCommerce on dev 9.4, staging 9.2 — upgrade staging first. Users: 1 admin on dev not on staging."
+```

package/skills/wp-pair-setup/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: wp-pair-setup
+description: One-click WordPress pairing using a companion-issued pair_token. Trade the token for a real Application Password and open a Target without the user typing credentials.
+---
+
+## When to use
+
+- The user pastes a "rolepod-wplab one-click pair" prompt (generated by Tools → WPLab Setup on their WordPress site).
+- The user pastes a `pair_token` string that looks like `wplab_pair_<48 hex>` and asks you to connect.
+- After a fresh plugin install when the user says "connect to my site" and you have no stored credentials yet — ask them to open Tools → WPLab Setup → Generate setup prompt → paste the result here.
+
+## When NOT to use
+
+- The user already has stored credentials for the site (use `rolepod_wp_connect_rest` directly).
+- The user is on a CLI without the wplab plugin installed AND without a way to install it — fall back to manual setup via `rolepod-wplab init` (see `wp-health-check` for the manual path).
+- The token is older than 60 minutes or has been used once already — it WILL fail. Ask the user to generate a fresh one.
+
+## Inputs
+
+- `siteurl` — full https:// URL of the target WordPress site.
+- `pair_token` — single-use token matching `wplab_pair_[a-f0-9]{48}` issued by the companion.
+
+## Outputs
+
+- `target_id` — pass this to every subsequent `rolepod_wp_*` tool.
+- `siteurl`, `username`, `capabilities[]`, `companion_version`, `is_production`, `app_password_name`, `credential_stored`.
+
+## Process
+
+1. Call `rolepod_wp_pair { siteurl, pair_token }`.
+2. The MCP POSTs `/wp-json/wplab/v1/pair/redeem` to the companion (https-only, pair token is the auth). The companion atomically deletes the token (single-use), mints a WP Application Password under the issuing admin user (named `wplab-pair-<timestamp>`), and returns it.
+3. The MCP stores the credential in the local vault (OS keychain when available) so subsequent sessions reconnect without re-pairing.
+4. The MCP opens a `RestTarget` and registers it — `target_id` is returned.
+5. Immediately call `rolepod_wp_health_check { target_id }` to confirm `db_ok`, `rest_ok`, `companion_ok` are all true.
+6. Report back to the user: site connected, capabilities discovered, App Password name (so they can revoke it later from `profile.php` if needed).
+
+## Failure modes
+
+- `PAIR_REDEEM_INVALID` — token unknown / expired / already used. Ask the user to regenerate from Tools → WPLab Setup.
+- `PAIR_REDEEM_THROTTLED` — too many failed redeems from your IP in the last hour. Wait or use manual setup.
+- `PAIR_REDEEM_TIMEOUT` / `PAIR_REDEEM_NETWORK` — companion unreachable. Check `siteurl` typo + firewall + companion `endpoints_enabled` toggle.
+- `PAIR_REDEEM_USER_GONE` — admin who issued the token lost `manage_options` between issue and redeem (rare).
+- `PAIR_REDEEM_APP_PASSWORD_FAILED` — WP's `WP_Application_Passwords::create_new_application_password` rejected the create (very rare; check WP_DEBUG log).
+
+## Security notes (DO NOT skip)
+
+- `pair_token` is **App-Password-equivalent for 60 min**. Treat it as a secret.
+- Never echo the token in chat logs after redeem. After step 1 it is one-time consumed anyway.
+- The minted Application Password is stored locally only (vault). Never paste it into a chat or push to git.
+- The user can revoke at any time via `profile.php#application-passwords-section` — name pattern `wplab-pair-<timestamp>`.
+
+## If the tool is unavailable
+
+The rolepod-wplab MCP is not registered. The user must install the wplab CLI plugin first:
+
+- Claude Code: `/plugin install nuttaruj/rolepod-wplab`
+- Cursor / Codex / Gemini: add an MCP server entry → `npx -y @rolepod/wplab serve` (see the prompt from Tools → WPLab Setup for exact syntax per CLI).
+
+Do NOT attempt the pair via raw HTTP or curl from the user's machine. The MCP needs to receive the App Password so future sessions reconnect cleanly.
+
+## Example
+
+```
+User: [pastes pair prompt with token wplab_pair_a1b2c3...]
+
+Lead → rolepod_wp_pair {
+         siteurl: "https://walnutztudio.com",
+         pair_token: "wplab_pair_a1b2c3..."
+       }
+       → { target_id: "tgt_8585f975d001", username: "admin", capabilities: [...] }
+
+Lead → rolepod_wp_health_check { target_id: "tgt_8585f975d001" }
+       → db_ok:true, rest_ok:true, companion_ok:true
+
+Lead reply: "Paired ✓ walnutztudio.com (admin). Companion v1.2.0 — full power tools
+              available. App Password name: wplab-pair-20260526T000123 (revocable
+              from profile.php → Application Passwords)."
+```

package/skills/wp-scaffold-block/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: wp-scaffold-block
+description: Generate a Gutenberg block (PHP register + JS + CSS + block.json) into an existing WordPress plugin or theme on a connected target.
+---
+
+## When to use
+
+- User asks to create a new Gutenberg block.
+- A target WordPress install is connected.
+- A destination plugin slug or theme slug is identified.
+
+## When NOT to use
+
+- Editing an existing block. Use `rolepod_wp_file_write` directly with the specific file.
+- Creating a non-Gutenberg widget. Use `wp_scaffold_plugin` with `features: ['admin_page']` instead.
+- The destination plugin/theme doesn't exist yet. First run `/wp-scaffold-plugin` then come back.
+
+## Inputs
+
+- `target_id` — connected WP target.
+- `destination` — `{ plugin_slug: string }` or `{ theme_slug: string }`.
+- `block.slug` — namespaced, e.g. `my-team/testimonial`.
+- `block.title`, `block.description?`, `block.category?`, `block.icon?`.
+- `block.attributes?` — schema for block attributes.
+- `block.supports?` — Gutenberg `supports` object.
+- `render_strategy` — `dynamic` (PHP render callback) or `static` (save() output).
+- `scaffold_test?` — if true, also generate a Playwright Test scaffold for rolepod-uiproof to run.
+
+## Outputs
+
+- `run_id`, `files_written[]`, `files_modified[]`, `test_file?`, `next_steps[]`.
+
+## Process
+
+1. Confirm the destination plugin/theme exists on the target — call `rolepod_wp_cli_run { args: ['plugin', 'is-installed', '<slug>'] }` if plugin_slug given.
+2. Construct `rolepod_wp_scaffold_block` input from user intent (composite tool — lands v0.1+).
+3. Call the tool.
+4. Surface `next_steps[]` to the user — usually one of: activate parent plugin, rebuild block.json, run `wp cache flush`.
+
+## If the tool is unavailable
+
+The rolepod-wplab MCP server is not registered or is not responding. Run `rolepod-wplab doctor`.
+
+Do NOT attempt to hand-write block files via raw `rolepod_wp_file_write` — the composite handles asset registration, dependency tracking, and test scaffolding consistently.
+
+## Examples
+
+```
+User: "/wp-scaffold-block testimonial card into my-team plugin, dynamic render"
+Lead → rolepod_wp_scaffold_block {
+  target_id: "tgt_8585...",
+  destination: { plugin_slug: "my-team" },
+  block: { slug: "my-team/testimonial-card", title: "Testimonial Card", category: "design" },
+  render_strategy: "dynamic"
+}
+Lead reply: "Generated 4 files under wp-content/plugins/my-team/blocks/testimonial-card/
+              Next steps:
+                1. cd wp-content/plugins/my-team && npm run build
+                2. wp cache flush
+                3. Refresh editor — block appears in 'Design' category"
+```

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

@@ -0,0 +1,53 @@
+---
+name: wp-scaffold-plugin
+description: Bootstrap a new WordPress plugin skeleton with optional REST endpoint, admin page, Gutenberg block, or WP-CLI command on a connected target.
+---
+
+## When to use
+
+- Starting a brand new WP plugin.
+- A target WP install is connected.
+- User can name the plugin (slug + display name).
+
+## When NOT to use
+
+- Adding features to an existing plugin. Use `rolepod_wp_file_write` or `/wp-scaffold-block` instead.
+- Scaffolding a theme — use a theme generator (out of v0.1 scope; lands v0.2 as `/wp-scaffold-theme`).
+
+## Inputs
+
+- `target_id`.
+- `slug` — folder/textdomain slug, lowercase-with-dashes (e.g. `my-team-tools`).
+- `name` — human-readable plugin name (e.g. `My Team Tools`).
+- `description?` — one-sentence plugin description.
+- `author?` — author name + url.
+- `features[]?` — any of: `rest_endpoint`, `admin_page`, `gutenberg_block`, `cli_command`.
+
+## Outputs
+
+- `run_id`, `plugin_path`, `files_written[]`, `activate_command`.
+
+## Process
+
+1. Call `rolepod_wp_scaffold_plugin` with constructed input.
+2. Surface `activate_command` so user can run it via wp-cli (or wplab does it automatically when `allow_destructive=true`).
+3. Suggest follow-up: `/wp-health-check` to verify activation succeeded.
+
+## If the tool is unavailable
+
+Same handling as other shipped skills.
+
+## Examples
+
+```
+User: "/wp-scaffold-plugin my-team-tools with REST endpoint + admin page"
+Lead → rolepod_wp_scaffold_plugin {
+  target_id: "tgt_8585...",
+  slug: "my-team-tools",
+  name: "My Team Tools",
+  features: ["rest_endpoint", "admin_page"]
+}
+Lead reply: "Created wp-content/plugins/my-team-tools/ (7 files)
+              Activate: wp --path=... plugin activate my-team-tools
+              REST endpoint stub: /wp-json/my-team-tools/v1/ping"
+```

package/skills/wp-scaffold-theme/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wp-scaffold-theme
+description: Bootstrap a minimum-viable WordPress block-theme skeleton (style.css + theme.json + functions.php + templates) on a connected target.
+---
+
+## When to use
+
+- Starting a brand-new block-theme.
+- A target WP install is connected.
+- User can name the theme (slug + display name).
+
+## When NOT to use
+
+- Adding features to an existing theme. Use `rolepod_wp_file_write` for targeted edits.
+- Customizing an existing block theme via theme.json — use `wp_file_write` on theme.json directly.
+
+## Inputs
+
+- `target_id`, `slug`, `name`, `description?`, `author?`.
+- `allow_destructive: true` required (creates files on target).
+
+## Outputs
+
+- `theme_path`, `files_written[]`, `activate_command`.
+
+## Process
+
+1. Call `rolepod_wp_scaffold_theme` with constructed input.
+2. Surface `activate_command` so user can switch themes.
+3. Suggest follow-up: `/wp-health-check` to verify theme activates without errors.
+
+## If the tool is unavailable
+
+Same handling as other shipped skills.
+
+## Examples
+
+```
+User: "/wp-scaffold-theme my-team-blog"
+Lead → rolepod_wp_scaffold_theme { target_id, slug: "my-team-blog", name: "My Team Blog", allow_destructive: true }
+       → 6 files under wp-content/themes/my-team-blog/
+Lead reply: "Theme scaffolded. Activate: wp theme activate my-team-blog"
+```