wordpress-agent-kit 0.2.2 → 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/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-project-triage
 description: "Use when you need a deterministic inspection of a WordPress repository (plugin/theme/block theme/WP core/Gutenberg/full site) including tooling/tests/version hints, and a structured JSON report to guide workflows and guardrails."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

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/.github/skills/wp-rest-api/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wp-rest-api
 description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
 ---
 

package/.github/skills/wp-wpcli-and-ops/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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."
+license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
 ---
 

package/.github/skills/wpds/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: wpds
 description: "Use when building UIs leveraging the WordPress Design System (WPDS) and its components, tokens, patterns, etc."
+license: GPL-2.0-or-later
 compatibility: "Requires WPDS MCP server configured and running. Targets WordPress 6.9+ (PHP 7.2.24+)."
 ---
 

package/AGENTS.md

@@ -8,32 +8,55 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Prompting**: `@clack/prompts`
 - **Build**: `tsc` (TypeScript Compiler)
 - **Test**: `vitest`
+- **Lint/Format**: Biome + ESLint
 
 ## Architecture
 - **Entry Point**: `src/cli.ts`
-- **Commands**: `src/commands/*.ts` (e.g., `install`, `setup`, `sync-skills`, `playground`)
-- **Core Logic**: `src/lib/*.ts` (e.g., `installer.ts` for file copying, `triage-mapper.ts` for project detection)
-- **Utilities**: `src/utils/*.ts` (e.g., `paths.ts`, `run.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**: 
   - `AGENTS.template.md`: The template file copied to user projects.
-  - `.github/`: The source of skills and instructions 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.
 
+## 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)
 - **Test**: `npm test` (runs Vitest)
-- **Lint**: `npm run lint`
+- **Lint**: `npm run lint:check` (ESLint + Biome)
+- **Format**: `npm run format` (Prettier + Biome)
+- **Pre-commit**: Husky runs lint:check + test:run
 
 ## Key Commands
-- `install`: Copies `.github` and `AGENTS.md` template to a target directory.
-- `setup`: Interactive wizard that detects project type and configures the kit.
-- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.github/skills`.
+- `install`: Copies `.github` and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`.
+- `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`.
 - `playground`: Launches a local WordPress Playground instance using a blueprint.
-- `build-release`: Packages the CLI for release.
+- `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'`
 
 ## 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 `vendor` directory is gitignored and populated via submodule or script.
+- 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.
+- 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

package/AGENTS.template.md

@@ -1,31 +1,76 @@
 # Project: WordPress Codebase
 
-This repository is WordPress-centric (plugin, theme, or site). Agents should prioritize local skills and official WordPress standards.
+This repository is WordPress-centric (plugin, theme, block theme, or site). Agents should prioritize local skills and official WordPress standards.
 
 ## Onboarding
 
-- Core agent: `.github/agents/wp-architect.agent.md`
-- Workflow: `.github/instructions/wordpress-workflow.instructions.md`
-- Skills live in: `.github/skills/`
+- **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
 
-## Project Discovery (required before changes)
+## Project Discovery (Required Before Changes)
 
-1. Run project triage:
-   - `node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs`
-2. If routing is unclear, use the router decision tree:
-   - `.github/skills/wordpress-router/references/decision-tree.md`
-3. Update repo-specific guidance:
-   - Choose the project prefix based on existing code (functions/classes/constants).
-   - Confirm folder structure (single-file plugin vs `includes/`, blocks, theme, full site).
-   - Confirm target WordPress/PHP versions if relevant.
+1. **Run project triage** to classify the codebase:
+   ```bash
+   node .github/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`
+   - 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 WP-CLI operations: `wp-wpcli-and-ops`
+
+3. **Update repo-specific guidance** based on triage results:
+   - Confirm the project prefix (functions, classes, constants)
+   - Confirm the folder structure (single-file plugin, `includes/`, blocks, theme, full site)
+   - Confirm target WordPress and PHP versions
+
+## Architecture
+
+<!-- Populated by project triage — do not remove -->
+
+- **Project Type**: <!-- plugin | theme | block-theme | site | gutenberg -->
+- **PHP Version**: <!-- minimum PHP version -->
+- **WP Version**: <!-- minimum WordPress version -->
+- **Build Tool**: <!-- webpack | @wordpress/scripts | vite | none -->
+- **Test Framework**: <!-- PHPUnit | Jest | Cypress | none -->
+
+## Commands
+
+<!-- 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 --> |
+
+## Code Conventions
+
+<!-- Populated by project triage — do not remove -->
+
+- **Prefix**: <!-- e.g., myplugin_ for functions, MyPlugin\ for namespaces -->
+- **Indentation**: Tabs for PHP, <!-- 2 spaces for JS -->
+- **PHP Standards**: [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
+- **JS Standards**: <!-- WordPress JS standards -->
 
 ## Security Baseline
 
-- Sanitize input early, escape output late.
-- Use nonces for state-changing requests.
-- Enforce capabilities for privileged actions.
+- **Sanitize Early**: Validate and sanitize all user input (`sanitize_text_field`, `sanitize_email`, etc.)
+- **Escape Late**: Escape all output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- **Use Nonces**: All state-changing requests must include nonce verification (`wp_nonce_field`, `check_admin_referer`)
+- **Check Capabilities**: Privileged actions require capability checks (`current_user_can`)
+- **Validate AJAX/REST**: Use `permission_callback` for REST endpoints and capability checks for AJAX handlers
 
 ## Output Requirements
 
-- Prefer minimal, standards-compliant changes.
-- Follow existing conventions in the codebase.
+- Prefer minimal, standards-compliant changes over large rewrites
+- Follow existing conventions in the codebase (naming, patterns, architecture)
+- Cite which skill or handbook informed the solution
+- Cross-check against this file (`AGENTS.md`) before finalizing output