wordpress-agent-kit 0.3.0 → 0.3.2

package/.github/skills/wp-plugin-directory-guidelines/references/naming-rules.md

@@ -0,0 +1,121 @@
+## Plugin Naming Rules (Guideline 17 + Plugin Check Namer)
+
+Sources: [Plugin Header Requirements](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/#header-fields) · [Detailed Plugin Guidelines §17](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/) · Plugin Check `Plugin_Header_Fields_Check`, `Trademarks_Check`, and AI Namer prompts.
+
+### Technical Name Requirements
+
+| Rule | Details | Error Code |
+|------|---------|------------|
+| Must not use placeholder names | `"Plugin Name"` or `"My Basics Plugin"` are rejected | `plugin_header_invalid_plugin_name` |
+| Minimum 5 alphanumeric characters | Name must contain at least 5 latin letters (a–Z) or digits | `plugin_header_unsupported_plugin_name` (new plugins only) |
+| Name must exist in readme | `=== Plugin Name ===` header required and must be valid | `invalid_plugin_name` / `empty_plugin_name` |
+| Name must match across files | Readme and plugin header name must match (case/entity-decoded) | `mismatched_plugin_name` (warning) |
+
+**Slug rules:** lowercase, hyphens only, max 50 characters, derived from display name.
+
+### Naming Quality Rules (AI Namer)
+
+**1. No generic names**
+Names must be specific enough to distinguish the plugin from ~60,000 others.
+- Rejected: "Shipping", "Ecommerce Tracker", "SEO Plugin"
+- Accepted: "ShipGlex Shipping", "Shipping Tracker for UPS"
+- Exception: invented/original terms are allowed if placed at the **beginning** of the name
+
+**2. Name must relate to plugin function**
+The display name must correlate with what the plugin actually does. Exception: original invented terms.
+
+**3. No keyword stuffing**
+Unnaturally repeating keywords in the name for SEO purposes is not allowed.
+
+**4. No names too similar to existing plugins**
+Checked against the WordPress.org Plugin Directory. If similar, suggest a distinctive term (author name, brand, or crafted term) at the beginning.
+
+**5. Trademark/project name usage rules**
+Trademarks and project names are allowed **only** after connectors like `for`, `with`, `using`, or `and`:
+- ✅ `"My Plugin for WooCommerce"` — trademark after "for", no affiliation implied
+- ✅ `"Pricing Rates for WooCommerce"` — OK
+- ❌ `"WooCommerce Pricing Rates"` — starts with trademark, implies affiliation
+- ❌ `"Nicedev Paypal for WooCommerce"` — PayPal is not after a no-affiliation structure; correct form: `"Nicedev Payment Gateway with PayPal for WooCommerce"`
+- ❌ `"PricingPress"` — portmanteau using `-Press` (WordPress trademark)
+- Check for portmanteaus: names blending a trademark (e.g., `-Press`, `Woo-`) are not allowed
+
+**6. Banned and discouraged terms**
+
+Banned/discouraged terms cannot appear **anywhere** in the name — not even after `for`/`with`.
+
+#### Banned Terms (hard block)
+
+| Term | Reason |
+|------|--------|
+| Facebook, FB, fbook, Whatsapp, WA, Instagram, Insta, Gram, INS, Threads, Oculus | Meta legal request: no use in name, slug, or banners |
+| WordPress, wordpess, wpress | WordPress trademark; redundant in the WP.org directory |
+| WP (as standalone/redundant, e.g., "for WP") | Same as WordPress — redundant in context |
+| Trustpilot | Direct request from trademark holder |
+| Binance Pay | Direct request from trademark holder |
+
+#### Discouraged Terms (must be removed)
+
+| Term | Reason |
+|------|--------|
+| plugin (when redundant, e.g., "SEO Plugin") | Redundant; forbidden as first word |
+| best, #1, First, Perfect, The most | Superlatives / unverifiable comparative claims |
+| free (when redundant, e.g., "(free)") | All directory plugins are free — redundant |
+| WP, W P (at beginning or end, referring to WordPress) | WordPress abbreviation — redundant |
+| Gutenberg, gberg, guten, berg | Creates confusion; block editor is the current name |
+
+### Trademark Slug List (static check — `Trademarks_Check`)
+
+The following slugs are statically blocked. Terms ending in `-` cannot **begin** a slug; terms without `-` cannot appear **anywhere** in the slug. `woocommerce` (no dash) is allowed only as `for-woocommerce`, `with-woocommerce`, `using-woocommerce`, or `and-woocommerce`.
+
+```
+adobe-, adsense-, advanced-custom-fields-, adwords-, akismet-,
+all-in-one-wp-migration, amazon-, android-, apple-, applenews-, applepay-,
+aws-, azon-, bbpress-, bing-, booking-com, bootstrap-, buddypress-,
+chatgpt-, chat-gpt-, cloudflare-, contact-form-7-, cpanel-, disqus-, divi-,
+dropbox-, easy-digital-downloads-, elementor-, envato-,
+fbook, facebook, fb-, fb-messenger, fedex-, feedburner, firefox-,
+fontawesome-, font-awesome-, ganalytics-, gberg, github-, givewp-, google-,
+googlebot-, googles-, gravity-form-, gravity-forms-, gravityforms-, gtmetrix-,
+gutenberg, guten-, hubspot-, ig-, insta-, instagram, internet-explorer-,
+ios-, jetpack-, macintosh-, macos-, mailchimp-, microsoft-,
+ninja-forms-, oculus, onlyfans-, only-fans-, opera-, paddle-, paypal-,
+pinterest-, plugin, skype-, stripe-, tiktok-, tik-tok-, trustpilot,
+twitch-, twitter-, tweet, ups-, usps-, vvhatsapp, vvcommerce, vva-, vvoo,
+wa-, webpush-vn, wh4tsapps, whatsapp, whats-app, watson, windows-,
+wocommerce, woocom-, woocommerce, woocomerce, woo-commerce, woo-, wo-,
+wordpress, wordpess, wpress, wp, wc, wp-mail-smtp-, yandex-, yahoo-,
+yoast, youtube-, you-tube-
+```
+
+**Portmanteaus also blocked:** any slug starting with `woo` (case-insensitive) — e.g., `woopress`, `wooland`.
+
+### Naming Examples
+
+| Plugin Name | Verdict | Reason |
+|-------------|---------|--------|
+| `Shipping` | ❌ | Too generic |
+| `Ecommerce Tracker` | ❌ | Too generic, no context |
+| `Shipping Tracker for UPS` | ✅ | Descriptive + context |
+| `ShipGlex Shipping` | ✅ | Invented term at beginning |
+| `WooCommerce Pricing Rates` | ❌ | Starts with trademark |
+| `Pricing Rates for WooCommerce` | ✅ | Trademark after "for" |
+| `PricingPress` | ❌ | `-Press` portmanteau |
+| `PRT Text editor for WP` | ❌ | WP is banned/redundant; correct: `PRT Text editor` |
+| `Nicedev Paypal for WooCommerce` | ❌ | PayPal not after no-affiliation structure |
+| `Nicedev Payment Gateway with PayPal for WooCommerce` | ✅ | Correct structure |
+| `Best SEO Plugin for WordPress` | ❌ | Superlative + banned terms |
+| `My Free Slider` | ❌ | "free" is redundant/discouraged |
+
+### Naming Review Checklist (pre-submission)
+
+- [ ] Name is not a placeholder (`Plugin Name`, `My Basics Plugin`)
+- [ ] Name has at least 5 alphanumeric characters
+- [ ] Name matches between plugin header and readme
+- [ ] Name is specific — not too generic for 60,000+ plugins
+- [ ] Name relates to what the plugin actually does
+- [ ] No keyword stuffing
+- [ ] No banned terms anywhere (Meta brands, WordPress/WP redundant, Trustpilot, Binance Pay)
+- [ ] No discouraged terms (Plugin, Best/#1, Free, Gutenberg, standalone WP)
+- [ ] Trademarks/project names only appear after `for`/`with`/`using`/`and`
+- [ ] No portmanteaus using WordPress or WooCommerce trademarks
+- [ ] Slug is lowercase, hyphens only, max 50 chars, no blocked terms

package/.github/skills/wp-project-triage/scripts/detect_wp_project.mjs

@@ -124,7 +124,8 @@ function findFilesRecursive(repoRoot, predicate, { maxFiles = 6000, maxDepth = 8
 function detectPluginHeaderFromPhpFile(filePath) {
   const contents = readFileSafe(filePath, 128 * 1024);
   if (!contents) return null;
-  const headerMatch = contents.match(/^\s*Plugin Name:\s*(.+)\s*$/im);
+  // Allow leading whitespace and asterisks common in block comments
+  const headerMatch = contents.match(/^[ \\t*]*Plugin Name:\s*(.+)\s*$/im);
   if (!headerMatch) return null;
   return headerMatch[1].trim();
 }
@@ -132,7 +133,8 @@ function detectPluginHeaderFromPhpFile(filePath) {
 function detectThemeHeaderFromStyleCss(filePath) {
   const contents = readFileSafe(filePath, 128 * 1024);
   if (!contents) return null;
-  const headerMatch = contents.match(/^\s*Theme Name:\s*(.+)\s*$/im);
+  // Allow leading whitespace and asterisks common in block comments
+  const headerMatch = contents.match(/^[ \\t*]*Theme Name:\s*(.+)\s*$/im);
   if (!headerMatch) return null;
   return headerMatch[1].trim();
 }
@@ -397,6 +399,13 @@ function main() {
     maxDepth: 8,
   });
 
+  const restApiScan = scanForTokens(repoRoot, {
+    tokens: ["register_rest_route", "register_rest_field", "WP_REST_Controller"],
+    exts: [".php"],
+    maxFiles: 2500,
+    maxDepth: 8,
+  });
+
   const wpCliConfigBasenames = new Set([
     "wp-cli.yml",
     "wp-cli.yaml",
@@ -439,6 +448,7 @@ function main() {
 
   const usesInteractivityApi = pkgHasInteractivity || Object.keys(interactivityScan.matches).length > 0;
   const usesAbilitiesApi = pkgHasAbilities || Object.keys(abilitiesScan.matches).length > 0;
+  const usesRestApi = Object.keys(restApiScan.matches).length > 0;
   const usesInnerBlocks = Object.keys(innerBlocksScan.matches).length > 0;
   const usesWpCli = composerHasWpCli || wpCliConfigFiles.length > 0 || Object.keys(wpCliTokenScan.matches).length > 0;
 
@@ -476,6 +486,10 @@ function main() {
   );
 
   const hasPhpUnit = phpunitXml.length > 0 || Boolean(composerJson?.requireDev?.phpunit || composerJson?.["require-dev"]?.phpunit);
+  
+  const hasPhpStan = existsFile(path.join(repoRoot, "phpstan.neon")) || 
+                     existsFile(path.join(repoRoot, "phpstan.neon.dist")) || 
+                     Boolean(composerJson?.requireDev?.["phpstan/phpstan"] || composerJson?.["require-dev"]?.["phpstan/phpstan"]);
 
   const signals = {
     paths: {
@@ -496,8 +510,7 @@ function main() {
     isBlockPlugin,
     isBlockTheme,
     usesInteractivityApi,
-    usesAbilitiesApi,
-    usesInnerBlocks,
+    usesAbilitiesApi,    usesRestApi,    usesInnerBlocks,
     usesWpCli,
     performanceHints: {
       wpConfig: config.source,
@@ -523,6 +536,10 @@ function main() {
       matches: abilitiesScan.matches,
       scanTruncated: abilitiesScan.truncated,
     },
+    restApiHints: {
+      matches: restApiScan.matches,
+      scanTruncated: restApiScan.truncated,
+    },
     innerBlocksHints: {
       matches: innerBlocksScan.matches,
       scanTruncated: innerBlocksScan.truncated,
@@ -552,6 +569,7 @@ function main() {
     php: {
       hasComposerJson: existsFile(path.join(repoRoot, "composer.json")),
       hasVendorDir: existsDir(path.join(repoRoot, "vendor")),
+      hasPhpStan,
       phpunitXml,
     },
     node: {

package/README.md

@@ -2,7 +2,7 @@
 
 [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/Written%20in-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Version](https://img.shields.io/badge/version-0.3.0-blue?style=flat-square)](package.json)
+[![Version](https://img.shields.io/badge/version-0.3.2-blue?style=flat-square)](package.json)
 [![Node](https://img.shields.io/badge/node-%3E%3D20.18-green?style=flat-square)](package.json)
 [![CI](https://img.shields.io/badge/CI-passing-brightgreen?style=flat-square)](.github/workflows/ci.yml)
 
@@ -40,7 +40,7 @@ my-plugin/
 │   ├── instructions/
 │   │   └── wordpress-workflow.instructions.md
 │   ├── prompts/
-│   └── skills/                      # 13 WordPress skills
+│   └── skills/                      # 17 WordPress skills
 │       ├── wp-project-triage/       # Project detection
 │       ├── wp-plugin-development/   # Plugin architecture
 │       ├── wp-block-development/    # Gutenberg blocks
@@ -231,7 +231,6 @@ All 13 skills follow the [AgentSkills.io](https://agentskills.io) specification:
 
 | Skill | When to Use |
 |-------|------------|
-| `wordpress-router` | Classify a WordPress repo and route to the right workflow |
 | `wp-project-triage` | Run deterministic project detection (type, tooling, versions) |
 | `wp-plugin-development` | Develop WordPress plugins (hooks, settings, security, release) |
 | `wp-block-development` | Develop Gutenberg blocks (block.json, attributes, rendering) |
@@ -239,11 +238,15 @@ All 13 skills follow the [AgentSkills.io](https://agentskills.io) specification:
 | `wp-rest-api` | Build, extend, or debug REST API endpoints/routes |
 | `wp-interactivity-api` | Build Interactive blocks with data-wp-* directives |
 | `wp-abilities-api` | Register and consume WordPress Abilities API |
+| `wp-abilities-audit` | Audit a plugin's REST surface for Abilities API opportunities |
+| `wp-abilities-verify` | Verify registered Abilities match their annotations |
 | `wp-performance` | Profile and optimize WordPress performance |
 | `wp-phpstan` | Configure and run PHPStan static analysis |
 | `wp-wpcli-and-ops` | WP-CLI commands, automation, multisite operations |
 | `wp-playground` | Test in disposable WordPress Playground instances |
+| `blueprint` | Write and edit WordPress Playground blueprint JSON |
 | `wpds` | Build UIs with the WordPress Design System |
+| `wp-plugin-directory-guidelines` | GPL compliance, naming, slug rules for WP.org submission |
 
 ---
 

package/dist/lib/api.js

@@ -25,7 +25,7 @@ export async function installKitApi(options) {
             installKit(targetDir, platform, { force, safe, backup });
             return { success: true };
         });
-        const filesCreated = getInstalledFiles(targetDir, platform);
+        const filesCreated = getInstalledSummary(targetDir, platform);
         const durationMs = Date.now() - startTime;
         return formatter.success({
             targetDir,
@@ -473,38 +473,49 @@ function getPlatformFolder(platform) {
     return folders[platform];
 }
 /**
- * Get list of files that would be/are installed.
+ * Get summary of installed files grouped by directory.
  */
-function getInstalledFiles(targetDir, platform) {
+function getInstalledSummary(targetDir, platform) {
     const platformFolder = getPlatformFolder(platform);
-    const files = [];
+    const summary = [];
     const targetPlatform = path.join(targetDir, platformFolder);
     if (fs.existsSync(targetPlatform)) {
-        function walk(dir, prefix = '') {
-            const entries = fs.readdirSync(dir);
-            for (const entry of entries) {
-                const fullPath = path.join(dir, entry);
-                const relPath = path.join(prefix, entry);
-                const stat = fs.statSync(fullPath);
-                if (stat.isDirectory()) {
-                    walk(fullPath, relPath);
-                }
-                else {
-                    files.push(path.join(platformFolder, relPath));
+        // Walk top-level entries for clean summary
+        const topEntries = fs.readdirSync(targetPlatform);
+        for (const entry of topEntries) {
+            const fullPath = path.join(targetPlatform, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                let totalFiles = 0;
+                let totalDirs = 0;
+                function countAll(dir) {
+                    const items = fs.readdirSync(dir);
+                    for (const item of items) {
+                        const itemPath = path.join(dir, item);
+                        const s = fs.statSync(itemPath);
+                        if (s.isDirectory()) {
+                            totalDirs++;
+                            countAll(itemPath);
+                        }
+                        else {
+                            totalFiles++;
+                        }
+                    }
                 }
+                countAll(fullPath);
+                summary.push(`${platformFolder}/${entry}/ (${totalDirs + 1} dirs, ${totalFiles} files)`);
             }
         }
-        walk(targetPlatform);
     }
     const agentsPath = path.join(targetDir, 'AGENTS.md');
     if (fs.existsSync(agentsPath)) {
-        files.push('AGENTS.md');
+        summary.push('AGENTS.md');
     }
     const agentsTemplatePath = path.join(targetDir, 'AGENTS.template.md');
     if (fs.existsSync(agentsTemplatePath)) {
-        files.push('AGENTS.template.md');
+        summary.push('AGENTS.template.md');
     }
-    return files;
+    return summary;
 }
 export { ExitCode } from '../utils/exit-codes.js';
 export { OutputFormatter, createFormatter, parseOutputFormat } from '../utils/output.js';

package/dist/lib/installer.js

@@ -45,7 +45,6 @@ function isKitAlreadyInstalled(targetDir, platform) {
  */
 function fullInstall(targetDir, platform, _force) {
     const platformFolder = PLATFORM_FOLDERS[platform];
-    console.log(`Installing WordPress Agent Kit (${platform}) into: ${targetDir}`);
     if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
@@ -117,7 +116,6 @@ function fullInstall(targetDir, platform, _force) {
  * Safe update install using the updater module.
  */
 function safeUpdateInstall(targetDir, platform, options) {
-    console.log(`Updating WordPress Agent Kit (${platform}) in: ${targetDir}`);
     const updateOptions = {
         targetDir,
         platform,