heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/wordpress/plugin-directory/skill.md

@@ -0,0 +1,396 @@
+# Skill: WordPress Plugin Directory Compliance Check
+
+This skill provides a systematic approach to review WordPress plugin source code against the [WordPress Plugin Directory Guidelines](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/).
+
+## Purpose
+
+To ensure a WordPress plugin fully complies with all 18 guidelines before submission to WordPress.org Plugin Directory, identifying issues and providing detailed recommendations for user approval before making changes.
+
+## Prerequisites
+
+1. **Identify Plugin Root**: The agent must identify the root directory of the WordPress plugin being reviewed.
+2. **Plugin Main File**: Locate the main plugin file (with `Plugin Name:` header).
+3. **Readme File**: Check for `readme.txt` or `README.md`.
+
+## Required Variables
+
+- `{{plugin_path}}`: Absolute path to the plugin root directory.
+- `{{plugin_slug}}`: The plugin's slug (folder name).
+
+## Process Flow
+
+### Step 1: Gather Plugin Information
+
+1. **Find Main Plugin File**:
+   ```bash
+   grep -l "Plugin Name:" {{plugin_path}}/*.php
+   ```
+
+2. **Read Plugin Headers**:
+   - Plugin Name
+   - Version
+   - Author
+   - License
+   - Text Domain
+
+3. **Scan File Structure**:
+   ```bash
+   find {{plugin_path}} -type f \( -name "*.php" -o -name "*.js" -o -name "*.css" \) | head -50
+   ```
+
+### Step 2: Review All 18 Guidelines
+
+Perform systematic checks on each guideline:
+
+---
+
+#### **Guideline 1: GPL Compatibility**
+> "Plugins must be compatible with the GNU General Public License"
+
+**Checks:**
+- [ ] Main plugin file has License header?
+- [ ] License is GPL-compatible? (GPLv2 or later recommended)
+- [ ] Third-party libraries have GPL-compatible licenses?
+- [ ] Images and fonts have clear licensing?
+
+**Commands:**
+```bash
+grep -r "License:" --include="*.php" {{plugin_path}}
+grep -r "@license" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 2: Developer Responsibility**
+> "Developers are responsible for the contents and actions of their plugins"
+
+**Checks:**
+- [ ] No code intentionally bypassing guidelines?
+- [ ] All files have confirmed licensing?
+- [ ] Third-party APIs comply with terms of use?
+
+---
+
+#### **Guideline 3: Stable Version Availability**
+> "A stable version of a plugin must be available from its WordPress Plugin Directory page"
+
+**Checks:**
+- [ ] Code on SVN/directory is the latest version?
+- [ ] Not distributing code via alternate methods without updating directory?
+
+---
+
+#### **Guideline 4: Human Readable Code**
+> "Code must be (mostly) human readable"
+
+**Checks:**
+- [ ] No obfuscated code (p,a,c,k,e,r, uglify mangle)?
+- [ ] No obscure variable names ($z12sdf813d)?
+- [ ] Source code or link to development location available in readme?
+- [ ] Build tools documented?
+
+**Commands:**
+```bash
+# Find eval() that may contain obfuscated code
+grep -r "eval(" --include="*.php" --include="*.js" {{plugin_path}}
+# Find strange variable names
+grep -rE "\$[a-z][0-9]{3,}" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 5: No Trialware**
+> "Trialware is not permitted"
+
+**Checks:**
+- [ ] No features locked behind payment?
+- [ ] No time-based trial limits?
+- [ ] No quota restrictions?
+- [ ] No sandbox-only API access?
+
+**Commands:**
+```bash
+grep -ri "trial" --include="*.php" {{plugin_path}}
+grep -ri "expired" --include="*.php" {{plugin_path}}
+grep -ri "license_key" --include="*.php" {{plugin_path}}
+grep -ri "is_pro" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 6: Software as a Service**
+> "Software as a Service is permitted"
+
+**Checks:**
+- [ ] Service provides real functionality, not just license validation?
+- [ ] Service documented in readme?
+- [ ] Link to Terms of Use provided?
+- [ ] Not just a storefront?
+
+---
+
+#### **Guideline 7: User Tracking Consent**
+> "Plugins may not track users without their consent"
+
+**Checks:**
+- [ ] No automatic data collection without consent?
+- [ ] Clear opt-in mechanism?
+- [ ] Privacy policy documented in readme?
+- [ ] Not misleading users to submit information?
+- [ ] Not offloading unrelated assets?
+- [ ] No undocumented external data usage?
+
+**Commands:**
+```bash
+# Find external requests
+grep -ri "wp_remote" --include="*.php" {{plugin_path}}
+grep -ri "curl_" --include="*.php" {{plugin_path}}
+grep -ri "file_get_contents.*http" --include="*.php" {{plugin_path}}
+# Find tracking
+grep -ri "analytics" --include="*.php" --include="*.js" {{plugin_path}}
+grep -ri "tracking" --include="*.php" --include="*.js" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 8: No External Executable Code**
+> "Plugins may not send executable code via third-party systems"
+
+**Checks:**
+- [ ] Not serving updates from external servers?
+- [ ] Not installing plugins/themes/add-ons from outside?
+- [ ] Not calling CDN for JS/CSS (except fonts)?
+- [ ] Not using third-party services to manage data lists?
+- [ ] Not using iframes in admin pages?
+
+**Commands:**
+```bash
+grep -ri "cdn" --include="*.php" --include="*.js" {{plugin_path}}
+grep -ri "<iframe" --include="*.php" {{plugin_path}}
+grep -ri "wp_remote_get.*\.js" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 9: Legal and Ethical Conduct**
+> "Developers and their plugins must not do anything illegal, dishonest, or morally offensive"
+
+**Checks:**
+- [ ] No keyword stuffing?
+- [ ] No fake reviews/sockpuppeting?
+- [ ] No copying others' plugins?
+- [ ] No automatic legal compliance claims?
+- [ ] No unauthorized server resource usage (botnet, crypto-mining)?
+
+---
+
+#### **Guideline 10: External Links and Credits**
+> "Plugins may not embed external links or credits on the public site without explicitly asking the user's permission"
+
+**Checks:**
+- [ ] "Powered By" links are optional and default OFF?
+- [ ] Users must opt-in to display credits?
+- [ ] Plugin doesn't require credit for functionality?
+
+**Commands:**
+```bash
+grep -ri "powered by" --include="*.php" {{plugin_path}}
+grep -ri "credit" --include="*.php" {{plugin_path}}
+grep -ri "footer_text" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 11: Admin Dashboard Experience**
+> "Plugins should not hijack the admin dashboard"
+
+**Checks:**
+- [ ] Upgrade prompts are limited and contextual?
+- [ ] Notices are dismissible?
+- [ ] Error messages have resolution guidance?
+- [ ] No excessive dashboard advertising?
+- [ ] No tracking in ads (related to Guideline 7)?
+
+**Commands:**
+```bash
+grep -ri "admin_notice" --include="*.php" {{plugin_path}}
+grep -ri "is-dismissible" --include="*.php" {{plugin_path}}
+grep -ri "upgrade" --include="*.php" {{plugin_path}}
+```
+
+---
+
+#### **Guideline 12: No Spam in Public Pages**
+> "Public facing pages on WordPress.org (readmes) must not spam"
+
+**Checks in readme.txt:**
+- [ ] No more than 5 tags?
+- [ ] No undisclosed affiliate links?
+- [ ] No keyword stuffing?
+- [ ] No competitor tags?
+- [ ] Links are direct, not redirected/cloaked?
+
+---
+
+#### **Guideline 13: WordPress Default Libraries**
+> "Plugins must use WordPress' default libraries"
+
+**Checks:**
+- [ ] Not including separate jQuery?
+- [ ] Not including libraries already in WordPress?
+- [ ] Using `wp_enqueue_script()` with standard handles?
+
+**WordPress Default Libraries:**
+- jQuery, jQuery UI
+- Backbone.js, Underscore.js
+- React, ReactDOM
+- Lodash
+- Moment.js
+- PHPMailer, PHPass
+
+**Commands:**
+```bash
+find {{plugin_path}} -name "jquery*.js" -o -name "jquery*.min.js"
+find {{plugin_path}} -name "underscore*.js" -o -name "backbone*.js"
+find {{plugin_path}} -name "react*.js" -o -name "moment*.js"
+```
+
+---
+
+#### **Guideline 14: Commit Frequency**
+> "Frequent commits to a plugin should be avoided"
+
+**Checks:**
+- [ ] SVN is release repository, not development?
+- [ ] Meaningful commit messages?
+- [ ] No rapid-fire minor commits?
+
+---
+
+#### **Guideline 15: Version Number Increment**
+> "Plugin version numbers must be incremented for each new release"
+
+**Checks:**
+- [ ] Version in main plugin file matches readme.txt?
+- [ ] Correct version format (semantic versioning recommended)?
+- [ ] SVN tag matches version number?
+
+**Commands:**
+```bash
+grep -r "Version:" --include="*.php" {{plugin_path}} | head -5
+grep -r "Stable tag:" {{plugin_path}}/readme.txt
+```
+
+---
+
+#### **Guideline 16: Complete Plugin Required**
+> "A complete plugin must be available at the time of submission"
+
+**Checks:**
+- [ ] Plugin is fully functional?
+- [ ] Not a placeholder/coming soon?
+- [ ] Not reserving name for future use?
+
+---
+
+#### **Guideline 17: Trademark and Copyright**
+> "Plugins must respect trademarks, copyrights, and project names"
+
+**Checks:**
+- [ ] Slug doesn't start with trademarked names (WordPress, WooCommerce, etc.) unless authorized?
+- [ ] Plugin name doesn't cause confusion with other products?
+- [ ] Original branding recommended?
+
+---
+
+#### **Guideline 18: Directory Maintenance Rights**
+> "We reserve the right to maintain the Plugin Directory to the best of our ability"
+
+**Notes:** WordPress.org has rights to:
+- Update guidelines at any time
+- Disable/remove plugins for unlisted reasons
+- Grant exceptions
+- Remove developer access
+- Modify plugins without consent for public safety
+
+---
+
+### Step 3: Generate Compliance Report
+
+Create a report using this format:
+
+```markdown
+# WordPress Plugin Directory Compliance Report
+
+## Plugin Information
+- **Name:** [Plugin Name]
+- **Version:** [Version]
+- **Path:** [Path]
+- **Review Time:** [Date/Time]
+
+## Summary
+- ✅ Passed: X/18 guidelines
+- ⚠️ Needs Review: X issues
+- ❌ Violations: X issues
+
+## Details by Guideline
+
+### ❌ Guideline X: [Guideline Name]
+**Issues Found:**
+- [Issue description]
+- **File:** [file path]
+- **Line:** [line number]
+
+**Suggested Fix:**
+\`\`\`php
+// Code suggestion
+\`\`\`
+
+### ⚠️ Guideline Y: [Guideline Name]
+**Needs Review:**
+- [Description]
+
+---
+
+## Recommended Actions
+1. [ ] [Action 1]
+2. [ ] [Action 2]
+...
+```
+
+### Step 4: User Confirmation
+
+**CRITICAL:** Before making ANY changes, the Agent MUST:
+
+1. Present the complete report to the user
+2. Clearly explain each issue with reference to the specific guideline number
+3. Wait for user confirmation on each action item
+4. Only proceed after receiving approval
+
+## Useful Commands
+
+```bash
+# Check plugin structure overview
+find {{plugin_path}} -type f \( -name "*.php" -o -name "*.js" -o -name "*.css" \) | head -50
+
+# Find all external URLs
+grep -rhoE "https?://[a-zA-Z0-9./?=_-]*" --include="*.php" {{plugin_path}} | sort -u
+
+# Check enqueued scripts
+grep -r "wp_enqueue_script\|wp_enqueue_style" --include="*.php" {{plugin_path}}
+
+# Find admin notices
+grep -r "add_action.*admin_notices" --include="*.php" {{plugin_path}}
+
+# Check AJAX handlers
+grep -r "wp_ajax_" --include="*.php" {{plugin_path}}
+
+# Find direct database queries
+grep -r "\$wpdb->" --include="*.php" {{plugin_path}}
+```
+
+## References
+
+- [WordPress Plugin Guidelines](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/)
+- [GPL Compatible Licenses](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses)
+- [Default Scripts in WordPress](https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-and-js-libraries-included-and-registered-by-wordpress)

package/dist/core/templates/skills/wordpress/plugin-standard/skill.md

@@ -0,0 +1,100 @@
+# Skill: WordPress Plugin Standard (WP.org Compliant)
+
+This skill guides the creation of a high-quality, secure, and WordPress.org compliant plugin. It focuses on adherence to the Plugin Check (PCP) requirements and provides a robust structure including admin interfaces.
+
+## Purpose
+Standardize WordPress plugin development to ensure acceptance into the official repository, maximize security, and promote maintainability through strict separation of concerns.
+
+## Required Variables
+- `{{plugin_name}}`: Human-readable name (e.g., My Awesome Plugin).
+- `{{plugin_slug}}`: Unique slug (e.g., my-awesome-plugin).
+- `{{namespace}}`: PHP Namespace (e.g., PolyXGO\MyPlugin).
+- `{{prefix}}`: Unique prefix for functions/variables (e.g., pxmp_).
+- `{{text_domain}}`: I18n text domain (usually same as plugin slug).
+
+## Core Requirements (WordPress.org & PCP)
+
+### 1. Security & Protection
+- **Direct Access**: Use `if ( ! defined( 'ABSPATH' ) ) exit;` at the top of every PHP file.
+- **Nonces**: Verify nonces for all form submissions and AJAX requests.
+- **Validation & Sanitization**: Sanitize all inputs (`sanitize_text_field`, `absint`, etc.) and validate data before processing.
+- **Escaping**: Escape all outputs strictly based on context (`esc_html`, `esc_attr`, `wp_kses`, etc.).
+- **Capabilities**: Explicitly check user capabilities (`current_user_can`) for all admin actions.
+
+### 2. Code Organization & Standards
+- **Naming**: Use the `{{prefix}}` for all global functions, variables, and constants.
+- **Namespace**: Use PSR-4 namespacing (`{{namespace}}`) to avoid class collisions.
+- **Separation of Concerns**: Keep CSS and JS in separate files. AVOID inline styles or scripts unless dynamically generated values are required (use `wp_localize_script` or `wp_add_inline_style` only when necessary).
+- **No Prohibited Constructs**: Never use `eval()`, `base64_decode()` for obfuscation, or short tags (`<?`).
+
+### 3. Required Components
+- **Main Plugin File**: Must contain the required header comment.
+- **`readme.txt`**: Standard WordPress.org format.
+- **Admin Interface**:
+  - A top-level or sub-menu item for the **Dashboard**.
+  - A dedicated **Settings** page for configuration.
+- **Uninstallation**: Provide an `uninstall.php` file to clean up data (options, tables) when the plugin is deleted.
+
+## Implementation Steps
+
+### Step 1: Initialize Main Structure
+1. Create the main plugin file `{{plugin_slug}}.php` with the correct header.
+2. Initialize the main class with a singleton or static instance.
+3. Hook into `plugins_loaded` to start the plugin logic.
+
+### Step 2: Register Admin Menu
+1. Hook into `admin_menu`.
+2. Add a menu page and a sub-page for Settings.
+3. Enqueue admin-specific assets (CSS/JS) only on plugin pages.
+
+### Step 3: Integrate UI/UX Skill
+When designing the Dashboard or Settings page:
+1. **Call Skill**: Use `(skill: ui-ux)` to define the design language.
+2. **Apply Styles**: Use the colors, typography, and spacing defined by the `ui-ux` skill result.
+3. Write styles in `assets/admin.css`.
+
+### Step 4: Handle Data Persistence
+1. Use the Options API (`get_option`, `update_option`) for settings.
+2. Ensure all data saved to the database is sanitized.
+3. Ensure all data retrieved from the database is escaped on output.
+
+## Standards and Rules
+
+### The Prefixing Rule
+Every global identifier MUST start with `{{prefix}}`.
+- ✅ `{{prefix}}get_settings()`
+- ❌ `get_settings()`
+
+### The "No Inline" Rule
+- CSS must be in `assets/css/admin.css`.
+- JS must be in `assets/js/admin.js`.
+- Use `wp_enqueue_style` and `wp_enqueue_script` correctly.
+
+### The "Smart Flush" Rule (Friendly URLs)
+If the plugin uses custom post types or custom permalink structures, you MUST implement a "Queue & Flush" mechanism to update rewrite rules automatically. **NEVER** call `flush_rewrite_rules()` on every page load or `init` hook directly without a condition.
+
+**Implementation Pattern:**
+1.  **Queue Flush**: When settings verify (e.g., via `update_option` hook), set a temporary flag.
+    ```php
+    add_action('update_option_{{prefix}}permalink_settings', function($old, $new) {
+        update_option('{{prefix}}flush_rewrite_flag', true);
+    }, 10, 2);
+    ```
+2.  **Execute Flush**: On the next `admin_init`, check and flush.
+    ```php
+    add_action('admin_init', function() {
+        if (get_option('{{prefix}}flush_rewrite_flag')) {
+            flush_rewrite_rules();
+            delete_option('{{prefix}}flush_rewrite_flag');
+        }
+    });
+    ```
+
+## Templates
+- [plugin-main.php](templates/plugin-main.php)
+- [admin-dashboard.php](templates/admin-dashboard.php)
+- [admin-settings.php](templates/admin-settings.php)
+- [readme.txt](templates/readme.txt)
+- [uninstall.php](templates/uninstall.php)
+- [assets/admin-css.css](templates/assets/admin-css.css)
+- [assets/admin-js.js](templates/assets/admin-js.js)

package/dist/core/templates/skills/wordpress/plugin-standard/templates/admin-dashboard.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Admin Dashboard Template
+ *
+ * @package {{namespace}}
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+?>
+
+<div class="wrap {{plugin_slug}}-dashboard">
+	<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
+	
+	<div class="welcome-panel">
+		<div class="welcome-panel-content">
+			<h2><?php esc_html_e( 'Welcome to {{plugin_name}}', '{{text_domain}}' ); ?></h2>
+			<p class="about-description"><?php esc_html_e( 'Thank you for using our plugin. This dashboard provides an overview of your activity.', '{{text_domain}}' ); ?></p>
+			
+			<div class="welcome-panel-column-container">
+				<div class="welcome-panel-column">
+					<h3><?php esc_html_e( 'Get Started', '{{text_domain}}' ); ?></h3>
+					<a class="button button-primary button-hero" href="<?php echo esc_url( admin_url( 'admin.php?page={{plugin_slug}}-settings' ) ); ?>"><?php esc_html_e( 'Configure Settings', '{{text_domain}}' ); ?></a>
+				</div>
+				<div class="welcome-panel-column">
+					<h3><?php esc_html_e( 'Next Steps', '{{text_domain}}' ); ?></h3>
+					<ul>
+						<li><a href="#" class="welcome-icon welcome-view-site"><?php esc_html_e( 'Check Features', '{{text_domain}}' ); ?></a></li>
+						<li><a href="#" class="welcome-icon welcome-edit-page"><?php esc_html_e( 'Documentation', '{{text_domain}}' ); ?></a></li>
+					</ul>
+				</div>
+			</div>
+		</div>
+	</div>
+
+	<div class="postbox-container">
+		<div class="postbox">
+			<div class="postbox-header">
+				<h2 class="hndle"><?php esc_html_e( 'Overview Stats', '{{text_domain}}' ); ?></h2>
+			</div>
+			<div class="inside">
+				<p><?php esc_html_e( 'Summary of your plugin usage will appear here.', '{{text_domain}}' ); ?></p>
+			</div>
+		</div>
+	</div>
+</div>

package/dist/core/templates/skills/wordpress/plugin-standard/templates/admin-settings.php

@@ -0,0 +1,60 @@
+<?php
+/**
+ * Admin Settings Template
+ *
+ * @package {{namespace}}
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+// Handle form submission
+if ( isset( $_POST['{{prefix}}save_settings'] ) ) {
+	
+	// Check nonce
+	if ( ! isset( $_POST['{{prefix}}settings_nonce'] ) || ! wp_verify_nonce( $_POST['{{prefix}}settings_nonce'], '{{prefix}}settings_action' ) ) {
+		wp_die( esc_html__( 'Security check failed.', '{{text_domain}}' ) );
+	}
+
+	// Check capabilities
+	if ( ! current_user_can( 'manage_options' ) ) {
+		wp_die( esc_html__( 'You do not have sufficient permissions to access this page.', '{{text_domain}}' ) );
+	}
+
+	// Save settings (example)
+	if ( isset( $_POST['{{prefix}}api_key'] ) ) {
+		update_option( '{{prefix}}api_key', sanitize_text_field( wp_unslash( $_POST['{{prefix}}api_key'] ) ) );
+	}
+
+	echo '<div class="updated"><p>' . esc_html__( 'Settings saved.', '{{text_domain}}' ) . '</p></div>';
+}
+
+$api_key = get_option( '{{prefix}}api_key', '' );
+?>
+
+<div class="wrap {{plugin_slug}}-settings">
+	<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
+
+	<form method="post" action="">
+		<?php wp_nonce_field( '{{prefix}}settings_action', '{{prefix}}settings_nonce' ); ?>
+		
+		<table class="form-table" role="presentation">
+			<tbody>
+				<tr>
+					<th scope="row">
+						<label for="{{prefix}}api_key"><?php esc_html_e( 'API Key', '{{text_domain}}' ); ?></label>
+					</th>
+					<td>
+						<input name="{{prefix}}api_key" type="text" id="{{prefix}}api_key" value="<?php echo esc_attr( $api_key ); ?>" class="regular-text">
+						<p class="description"><?php esc_html_e( 'Enter your API key here.', '{{text_domain}}' ); ?></p>
+					</td>
+				</tr>
+			</tbody>
+		</table>
+
+		<p class="submit">
+			<input type="submit" name="{{prefix}}save_settings" id="submit" class="button button-primary" value="<?php esc_attr_e( 'Save Changes', '{{text_domain}}' ); ?>">
+		</p>
+	</form>
+</div>

package/dist/core/templates/skills/wordpress/plugin-standard/templates/assets/admin-css.css

@@ -0,0 +1,22 @@
+/**
+ * Admin Styles for {{plugin_name}}
+ * 
+ * DESIGN SYSTEM:
+ * Use the ui-ux skill to define colors, fonts, and spacing.
+ * This file should contain layout and component-specific styles.
+ */
+
+.{{plugin_slug}}-dashboard .welcome-panel {
+    margin-top: 20px;
+    border: 1px solid #ccd0d4;
+    background: #fff;
+    padding: 20px;
+}
+
+.{{plugin_slug}}-dashboard .welcome-panel h2 {
+    margin-top: 0;
+}
+
+.{{plugin_slug}}-settings .form-table {
+    margin-top: 20px;
+}

package/dist/core/templates/skills/wordpress/plugin-standard/templates/assets/admin-js.js

@@ -0,0 +1,15 @@
+/**
+ * Admin JavaScript for {{plugin_name}}
+ */
+
+(function($) {
+    'use strict';
+
+    $(document).ready(function() {
+        console.log('{{plugin_name}} Admin Loaded');
+
+        // Example: Handle AJAX or UI interactions
+        // Use {{prefix}}params.ajax_url and {{prefix}}params.nonce
+    });
+
+})(jQuery);