heraspec 0.1.2 → 0.1.4

package/dist/core/templates/skills/documents-skill.md

@@ -1,114 +1,76 @@
-# Skill: Documents (Cross-Cutting)
+# Skill: Documents (Cross-Cutting & Multi-Format)
 
 ## Purpose
 
-This skill is used to create documentation for both technical and end-user audiences. Ensures documentation is complete, clear, and easy to understand.
-
-## When to Use
-
-- When creating technical documentation
-- When writing user guides
-- When documenting APIs
-- When creating changelogs
-- When writing installation/setup guides
-
-## Step-by-Step Process
-
-### Step 1: Identify Document Type
-- Technical docs: For developers
-- User guide: For end-users
-- API docs: For API consumers
-- Changelog: For version releases
-
-### Step 2: Choose Appropriate Template
-- Technical: `templates/technical-doc-template.md`
-- User guide: `templates/user-guide-template.md`
-- API: `templates/api-doc-template.md`
-- Changelog: `templates/changelog-template.md`
-
-### Step 3: Gather Information
-- Features and functionality
-- Installation steps
-- Configuration options
-- Usage examples
-- Troubleshooting tips
-
-### Step 4: Write Documentation
-- Follow template structure
-- Use good examples as reference
-- Ensure code examples work
-- Include screenshots if needed
-
-### Step 5: Validate & Generate
-- Run script: `scripts/validate-docs.py`
-- Run script: `scripts/generate-docs.sh` (if available)
-- Review with good examples
-- Test with target audience
+This skill is used to create comprehensive documentation for both technical and end-user audiences. It supports parallel generation of Markdown files (for repository/GitHub) and interactive HTML files (for browser-based manuals).
+
+## Core Requirements
+
+### 1. Multi-Format Output
+Every documentation task should ideally generate three versions:
+- `doc-name.md`: Clean Markdown for version control.
+- `doc-name.html`: Interactive HTML with a modern split-panel layout for deep reading.
+- `documentation-landing-page.html`: A high-end, visual landing page to showcase features and provide entry points.
+
+### 2. HTML Layout (Premium Standard)
+- **Documentation Page**: Split-panel (Sidebar for Nav, Content for reading). Smooth scroll-spy included.
+- **Landing Page**: Full-screen Hero section, feature grids with hover effects, and clear Calls to Action (CTA).
+
+### 3. Visual Excellence
+- Use the `ui-ux` skill to determine the theme colors, typography gradients, and spacing.
+- The Landing Page must include scroll animations (fade-in, transform) to feel premium and alive.
+
+## Implementation Steps
+
+### Step 1: Define Content and Flow
+1. Outline the main technical content for the `.md` and `.html` docs.
+2. Identify the "Key Features" and "USP" (Unique Selling Points) for the Landing Page feature grid.
+
+### Step 2: Generate Markdown & Documentation HTML
+1. Populate `technical-doc-template.md` (or user guide).
+2. Populate `documentation.html` with navigation and sections.
+
+### Step 3: Integrate Landing Page
+1. Use `templates/documentation-landing-page.html`.
+2. **Hero Section**: Write a compelling headline and description.
+3. **Feature Grid**: Create cards for each major feature using `<div class="feature-card">`.
+4. **Integration**: Link the CTA buttons to `documentation.html`.
+5. Apply `landing-style.css` and `landing-script.js`.
 
 ## Required Input
 
 - **Document type**: Technical, user guide, API, changelog
 - **Target audience**: Developers, end-users, admins
-- **Features to document**: List of features to document
-- **Code examples**: Code samples to include
-- **Screenshots**: Images if needed
+- **Structural Outline**: List of headings and sub-headings
+- **Design Cues**: Colors and icons from `ui-ux` skill
 
 ## Expected Output
 
-- Complete documentation file
-- Proper formatting and structure
-- Working code examples
-- Clear instructions
-- Troubleshooting section
+- `file.md`: Complete documentation in Markdown.
+- `file.html`: Interactive split-panel HTML documentation.
+- `style.css`: Documentation styles.
+- `script.js`: Documentation interactivity.
 
 ## Tone & Rules
 
-### Writing Style
-- **Clear**: Write clearly, easy to understand
-- **Concise**: Brief, not verbose
-- **Actionable**: Can be followed
-- **Complete**: Complete necessary information
-
-### Technical Docs
-- Code examples must work
-- Include prerequisites
-- Explain "why" not just "what"
-- Link to related docs
-
-### User Guides
-- Step-by-step instructions
-- Screenshots for complex steps
-- Common issues and solutions
-- Plain language (avoid jargon)
-
-### Limitations
-- ❌ DO NOT skip prerequisites
-- ❌ DO NOT assume prior knowledge
-- ❌ DO NOT use untested code examples
-- ❌ DO NOT write too technical for user guides
-- ❌ DO NOT skip troubleshooting
+- **Consistent Content**: The content in MD and HTML MUST be identical in substance.
+- **No Inline Bloat**: Keep CSS and JS in separate files as provided in the templates.
+- **Interactive T.O.C**: Sidebar links MUST use smooth-scroll IDs.
 
 ## Available Templates
 
+- `templates/documentation.html` - Base HTML documentation layout
+- `templates/documentation-landing-page.html` - Premium Landing Page layout
+- `templates/style.css` - Premium styles for HTML documentation
+- `templates/landing-style.css` - Premium styles for Landing Page
+- `templates/script.js` - Interactive logic for HTML documentation
+- `templates/landing-script.js` - Interactive logic for Landing Page
 - `templates/technical-doc-template.md` - Technical documentation
 - `templates/user-guide-template.md` - User guide
 - `templates/api-doc-template.md` - API documentation
 - `templates/changelog-template.md` - Changelog template
 
-## Available Scripts
-
-- `scripts/generate-docs.sh` - Automatically generate docs from code
-- `scripts/validate-docs.py` - Validate format and completeness
-
-## Examples
-
-See `examples/` directory for reference:
-- `good-technical-doc.md` - Good technical doc example
-- `good-user-guide.md` - Good user guide example
-- `good-api-doc.md` - Good API doc example
-
 ## Links to Other Skills
 
-- **module-codebase**: Document module structure
-- **ui-ux**: Document UI components and design system
-- **content-optimization**: Optimize documentation for clarity
+- **ui-ux**: ESSENTIAL. Use this to determine the look and feel of the HTML documentation.
+- **content-optimization**: Use to ensure the text is clear and professional.

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);

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

@@ -0,0 +1,169 @@
+<?php
+/**
+ * Plugin Name:       {{plugin_name}}
+ * Description:       A high-quality WordPress plugin following WP.org standards.
+ * Version:           1.0.0
+ * Author:            Your Name
+ * Author URI:        https://example.com
+ * License:           GPL-2.0-or-later
+ * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain:       {{text_domain}}
+ * Domain Path:       /languages
+ *
+ * @package           {{namespace}}
+ */
+
+// If this file is called directly, abort.
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * The core plugin class.
+ */
+class {{namespace}}\Main {
+
+	/**
+	 * Instance of this class.
+	 *
+	 * @var object
+	 */
+	protected static $instance = null;
+
+	/**
+	 * Initialize the plugin.
+	 */
+	public function __construct() {
+		$this->define_constants();
+		$this->includes();
+		$this->init_hooks();
+	}
+
+	/**
+	 * Return an instance of this class.
+	 */
+	public static function get_instance() {
+		if ( null === self::$instance ) {
+			self::$instance = new self();
+		}
+		return self::$instance;
+	}
+
+	/**
+	 * Define constants.
+	 */
+	private function define_constants() {
+		define( '{{prefix|upper}}VERSION', '1.0.0' );
+		define( '{{prefix|upper}}PATH', plugin_dir_path( __FILE__ ) );
+		define( '{{prefix|upper}}URL', plugin_dir_url( __FILE__ ) );
+	}
+
+	/**
+	 * Include required files.
+	 */
+	private function includes() {
+		// Include admin classes, helpers, etc.
+	}
+
+	/**
+	 * Initialize hooks.
+	 */
+	private function init_hooks() {
+		add_action( 'admin_menu', [ $this, 'add_menu_pages' ] );
+		add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_admin_assets' ] );
+		
+		// Activation / Deactivation hooks
+		register_activation_hook( __FILE__, [ $this, 'activate' ] );
+		register_deactivation_hook( __FILE__, [ $this, 'deactivate' ] );
+	}
+
+	/**
+	 * Add Admin Menu Pages.
+	 */
+	public function add_menu_pages() {
+		add_menu_page(
+			__( '{{plugin_name}}', '{{text_domain}}' ),
+			__( '{{plugin_name}}', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}',
+			[ $this, 'render_dashboard_page' ],
+			'dashicons-admin-generic',
+			100
+		);
+
+		add_submenu_page(
+			'{{plugin_slug}}',
+			__( 'Dashboard', '{{text_domain}}' ),
+			__( 'Dashboard', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}',
+			[ $this, 'render_dashboard_page' ]
+		);
+
+		add_submenu_page(
+			'{{plugin_slug}}',
+			__( 'Settings', '{{text_domain}}' ),
+			__( 'Settings', '{{text_domain}}' ),
+			'manage_options',
+			'{{plugin_slug}}-settings',
+			[ $this, 'render_settings_page' ]
+		);
+	}
+
+	/**
+	 * Enqueue Admin Assets.
+	 */
+	public function enqueue_admin_assets( $hook ) {
+		// Only load on our plugin pages
+		if ( strpos( $hook, '{{plugin_slug}}' ) === false ) {
+			return;
+		}
+
+		wp_enqueue_style( '{{plugin_slug}}-admin', {{prefix|upper}}URL . 'assets/css/admin.css', [], {{prefix|upper}}VERSION );
+		wp_enqueue_script( '{{plugin_slug}}-admin', {{prefix|upper}}URL . 'assets/js/admin.js', [ 'jquery' ], {{prefix|upper}}VERSION, true );
+		
+		wp_localize_script( '{{plugin_slug}}-admin', '{{prefix}}params', [
+			'ajax_url' => admin_url( 'admin-ajax.php' ),
+			'nonce'    => wp_create_nonce( '{{prefix}}nonce' ),
+		]);
+	}
+
+	/**
+	 * Render Dashboard Page.
+	 */
+	public function render_dashboard_page() {
+		// Include template file
+		include {{prefix|upper}}PATH . 'templates/admin-dashboard.php';
+	}
+
+	/**
+	 * Render Settings Page.
+	 */
+	public function render_settings_page() {
+		// Include template file
+		include {{prefix|upper}}PATH . 'templates/admin-settings.php';
+	}
+
+	/**
+	 * Activation logic.
+	 */
+	public function activate() {
+		// Setup database tables, default options, etc.
+	}
+
+	/**
+	 * Deactivation logic.
+	 */
+	public function deactivate() {
+		// Clear scheduled tasks, etc.
+	}
+}
+
+/**
+ * Initialize the plugin.
+ */
+function {{prefix}}init() {
+	return {{namespace}}\Main::get_instance();
+}
+
+add_action( 'plugins_loaded', '{{prefix}}init' );

package/dist/core/templates/skills/wordpress-plugin-standard/templates/readme.txt

@@ -0,0 +1,41 @@
+=== {{plugin_name}} ===
+Contributors: yourname
+Tags: wordpress, plugin, standard
+Requires at least: 6.0
+Tested up to: 6.4
+Requires PHP: 7.4
+Stable tag: 1.0.0
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+
+{{plugin_name}} is a high-quality WordPress plugin built with HeraSpec.
+
+== Description ==
+
+Describe your plugin features here.
+
+== Installation ==
+
+1. Upload the plugin files to the `/wp-content/plugins/{{plugin_slug}}` directory.
+2. Activate the plugin through the 'Plugins' screen in WordPress.
+3. Go to {{plugin_name}} -> Settings to configure.
+
+== Frequently Asked Questions ==
+
+= Is this plugin free? =
+
+Yes!
+
+== Screenshots ==
+
+1. Dashboard view.
+
+== Changelog ==
+
+= 1.0.0 =
+* Initial release.
+
+== Upgrade Notice ==
+
+= 1.0.0 =
+* First version.

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

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Fired when the plugin is uninstalled.
+ *
+ * @package {{namespace}}
+ */
+
+// If uninstall not called from WordPress, then exit.
+if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
+	exit;
+}
+
+/**
+ * Clean up plugin data.
+ */
+delete_option( '{{prefix}}version' );
+delete_option( '{{prefix}}api_key' );
+
+// Delete custom tables if any...
+// global $wpdb;
+// $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}your_table_name" );

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

@@ -0,0 +1,80 @@
+# 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.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heraspec",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Universal spec-first development framework + CLI for all project types and AI tools",
   "keywords": [
     "heraspec",