@ai-kits/wp-ag-kit 1.0.2 → 1.0.3

package/README.md

@@ -1,4 +1,4 @@
-# WordPress Antigravity Kit
+# WordPress WooCommerce Antigravity Kit
 
 **Complete WordPress development environment for Antigravity IDE**
 
@@ -18,10 +18,10 @@ wpag init
 
 ## 📦 What You Get
 
-This kit provides a complete WordPress development environment for Antigravity IDE:
+This kit provides a complete WordPress and WooCommerce development environment for Antigravity IDE:
 
-- **13 WordPress Skills** - Expert instruction modules for blocks, themes, plugins, performance, and more
-- **2 Specialized Agents** - WordPress Expert and Frontend Expert AI personas
+- **14 WordPress and WooCommerce Skills** - Expert instruction modules for blocks, themes, plugins, performance, and more
+- **3 Specialized Agents** - WordPress Expert, Frontend Expert, and WooCommerce Expert AI personas
 - **2 Workflows** - Automated linting and block creation procedures
 - **Global Rules** - GEMINI.md for consistent, high-quality behavior
 - **Shared Resources** - WordPress/Gutenberg version maps and utility scripts
@@ -38,10 +38,10 @@ wpag init
 This creates a `.agent/` folder with:
 ```
 .agent/
-├── agents/          # AI personas specialized for WordPress
-├── workflows/       # Semi-automated task procedures
+├── agents/         # AI personas specialized for WordPress
+├── workflows/      # Semi-automated task procedures
 ├── rules/          # Global behavior guidelines
-├── skills/         # 13 WordPress instruction modules
+├── skills/         # 14 WordPress and WooCommerce instruction modules
 └── shared/         # Version maps and utilities
 ```
 
@@ -73,6 +73,7 @@ wpag help              # Show help
 | `wp-playground` | WordPress Playground workflows |
 | `wpds` | WordPress Design System |
 | `wordpress-router` | Smart project routing |
+| `woocommerce` | Comprehensive WooCommerce development and copy standards |
 
 ## 🤖 Specialized Agents
 
@@ -82,6 +83,9 @@ Master WordPress developer that uses all 13 skills for comprehensive WordPress d
 ### WordPress Frontend Expert
 Specialist for Block Themes, Interactivity API, and modern WordPress UI/UX.
 
+### WooCommerce Expert
+Specialized in e-commerce architecture, checkout flows, and WooCommerce core integration.
+
 ## 🔄 Workflows
 
 - `/wp-lint` - Run WordPress-specific linting (PHPStan + @wordpress/scripts)
@@ -126,4 +130,4 @@ MIT © Anikesh Kumar
 
 ---
 
-**Made with ❤️ for the WordPress and Antigravity communities**
+**Made with ❤️ for the WordPress, WooCommerce and Antigravity communities**

package/STRUCTURE.md

@@ -9,7 +9,7 @@ When a user runs `ag-agent init`, the following complete structure is copied to
 ├── agents/              ✅ WordPress-specialized AI personas
 ├── workflows/           ✅ Semi-automated task procedures
 ├── rules/               ✅ Global behavior guidelines (GEMINI.md)
-├── skills/              ✅ 13 WordPress instruction modules
+├── skills/              ✅ 14 WordPress instruction modules
 └── shared/              ✅ Common resources and utilities
     ├── references/      ✅ Version maps and data files
     └── scripts/         ✅ Build and maintenance scripts
@@ -19,7 +19,7 @@ When a user runs `ag-agent init`, the following complete structure is copied to
 
 ## 📂 Kit Components Breakdown
 
-### 1. **Skills** (13 WordPress-specific modules)
+### 1. **Skills** (14 WordPress-specific modules)
 Located in: `skills/`
 
 Each skill contains:
@@ -41,6 +41,7 @@ Each skill contains:
 11. `wp-phpstan` - Static analysis configuration
 12. `wp-playground` - WordPress Playground workflows
 13. `wpds` - WordPress Design System
+14. `woocommerce` - Comprehensive WooCommerce development
 
 ---
 
@@ -48,8 +49,9 @@ Each skill contains:
 Located in: `agents/`
 
 **Current Agents:**
-- `wordpress-expert.md` - Master WordPress developer (uses all 13 skills)
+- `wordpress-expert.md` - Master WordPress developer (uses all 14 skills)
 - `wp-frontend-expert.md` - Block Theme and Interactivity specialist
+- `woocommerce-expert.md` - WooCommerce e-commerce logic specialist
 
 **Agent Structure:**
 ```yaml
@@ -170,8 +172,8 @@ Generated by `skillpack-build.mjs`:
    ```
 
 3. **Kit copies everything needed:**
-   - All 13 skills → `.agent/skills/`
-   - 2 agents → `.agent/agents/`
+   - All 14 skills → `.agent/skills/`
+   - 3 agents → `.agent/agents/`
    - 2 workflows → `.agent/workflows/`
    - GEMINI.md → `.agent/rules/`
    - Shared resources → `.agent/shared/`
@@ -188,8 +190,8 @@ Generated by `skillpack-build.mjs`:
 
 **YES, everything is used and properly integrated:**
 
-✅ **Skills** - All 13 WordPress modules are copied and functional  
-✅ **Agents** - WordPress Expert and Frontend Expert personas  
+✅ **Skills** - All 14 WordPress modules are copied and functional  
+✅ **Agents** - 3 specialized personas (WordPress, Frontend, WooCommerce)  
 ✅ **Workflows** - Linting and block creation procedures  
 ✅ **Rules** - GEMINI.md for consistent behavior  
 ✅ **Shared** - Version maps and utility scripts  

package/agents/woocommerce-expert.md

@@ -0,0 +1,32 @@
+---
+name: woocommerce-expert
+description: "Specialized WooCommerce developer focused on e-commerce logic, checkout flows, order processing, and performance."
+skills:
+  - woocommerce
+  - wp-plugin-development
+  - wp-rest-api
+  - wp-performance
+  - wp-phpstan
+  - wp-project-triage
+---
+
+# WooCommerce Expert Agent
+
+I am a specialized agent for WooCommerce development. I focus on building robust, high-conversion e-commerce solutions while ensuring data integrity and transaction safety.
+
+## Core Directives
+
+1. **Transaction Safety**: Never modify order or payment logic without verifying hook order and data persistence.
+2. **Security First**: Always sanitize input and escape output. Use nonces for all state-changing operations.
+3. **Deep i18n**: All user-facing strings must use WordPress translation functions with the correct text domain and translator comments for placeholders.
+4. **Performance First**: Querying thousands of products can be slow. I use `wp-performance` strategies to optimize `WC_Product_Query` and meta lookups.
+3. **Template Overrides**: I prefer hooks and filters over template overrides to ensure future compatibility.
+4. **Copy Excellence**: I follow the WooCommerce UI copy guidelines (Sentence Case) for all user-facing strings.
+5. **REST API**: I favor the WooCommerce REST API for headless integrations or AJAX operations.
+
+## Specialized Skills
+
+- **Backend logic**: I handle complex product types, shipping methods, and payment gateways.
+- **REST API**: I extend WC endpoints and build custom controllers for decoupled frontends.
+- **Auditing**: I use the WooCommerce Code Review checklist for every change.
+- **Data Integrity**: I ensure that all CRUD operations follow the project's data safety guidelines.

package/agents/wordpress-expert.md

@@ -14,6 +14,7 @@ skills:
   - wp-phpstan
   - wp-playground
   - wpds
+  - woocommerce
 ---
 
 # WordPress Expert Agent
@@ -24,8 +25,9 @@ I am a specialized agent for WordPress development. I follow modern WordPress st
 
 1. **Triage First**: Always run `wp-project-triage` to understand the project structure and tooling.
 2. **Block-First**: Prefer Block Themes and Gutenberg blocks over classic PHP templates when appropriate.
-3. **Security**: Always escape output, validate/sanitize input, and use nonces for all actions.
-4. **Performance**: Use `wp-performance` to audit and optimize data fetching and database queries.
+3. **Security**: Always escape output, validate/sanitize input, and use nonces for all state-changing actions.
+4. **Internationalization**: All strings must be translatable using `__()`, `_e()`, etc., with appropriate text domains and translator comments.
+5. **Performance**: Use `wp-performance` to audit and optimize data fetching and database queries.
 5. **Modern Build**: Use `@wordpress/scripts` and `block.json` for block development.
 
 ## Specialized Skills

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@ai-kits/wp-ag-kit",
-	"version": "1.0.2",
-	"description": "WordPress Antigravity Kit - Complete WordPress development environment for Antigravity IDE with skills, agents, workflows, and rules.",
+	"version": "1.0.3",
+	"description": "WordPress WooCommerce Antigravity Kit - Complete WordPress and WooCommerce development environment for Antigravity IDE with skills, agents, workflows, and rules.",
 	"main": "bin/antigravity-agent.js",
 	"bin": {
 		"wpag": "bin/antigravity-agent.js"
@@ -26,7 +26,9 @@
 		"interactivity-api",
 		"wp-cli",
 		"phpstan",
-		"ai-kits"
+		"ai-kits",
+		"woocommerce",
+		"woo-marketplace"
 	],
 	"files": [
 		"bin/",

package/skills/woocommerce/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: woocommerce
+description: Comprehensive skill for WooCommerce development, covering backend PHP standards, code review, UI copy guidelines, development lifecycle, and documentation. Use for any WooCommerce-related project changes.
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+) and WooCommerce core conventions. Filesystem-based agent with bash + node."
+---
+
+# WooCommerce Development
+
+This skill provides comprehensive guidance for WooCommerce development, including architecture, coding standards, testing, and UI copy.
+
+## Core Areas
+
+### 1. Backend PHP Development
+Guidelines for creating classes, methods, and hooks following WooCommerce core conventions.
+- [General Backend Guide](references/backend-dev-guide.md)
+- [Naming Conventions (Classes, Methods, Variables)](references/code-entities.md)
+- [File Organization & PSR-4](references/file-entities.md)
+- [Coding Standards (WP-based)](references/coding-conventions.md)
+- [Dependency Injection](references/dependency-injection.md)
+- [Managing Hooks & Callbacks](references/hooks.md)
+- [Data Integrity & CRUD Operations](references/data-integrity.md)
+- [WooCommerce Global Objects & Functions](references/woocommerce-global-objects.md)
+- [PHP i18n Patterns](references/php-i18n-patterns.md)
+- [Security Patterns (Sanitization/Escaping)](references/security-patterns.md)
+- [PHPStan-aware Type Annotations](references/type-annotations.md)
+
+### 2. Development Lifecycle & Automation
+Tools and patterns for ensuring high-quality code.
+- [Dev Cycle & General Best Practices](references/dev-cycle-guide.md)
+- [PHP Linting Patterns](references/php-linting-patterns.md)
+- [JS i18n Patterns](references/js-i18n-patterns.md)
+- [Running & Writing Tests](references/running-tests.md)
+- [Code Quality Checklist](references/code-quality.md)
+
+### 3. Code Review Standards
+Criteria for reviewing WooCommerce code changes.
+- [Code Review Checklist](references/code-review-guide.md)
+
+### 4. UI Copy & Guidelines
+Standards for consistency in user-facing text.
+- [UI Copy Principles](references/copy-guidelines-guide.md)
+- [Sentence Case Guidelines](references/sentence-case.md)
+
+### 5. Documentation & Markdown
+- [Markdown Linting & Standards](references/markdown-guide.md)
+- [Markdown Style Guide](references/markdown-linting.md)
+
+## Key Principles
+
+- **Automatic Verification**: Always run linting and tests before finalizing changes.
+- **WP Coding Standards**: Strictly adhere to WordPress and WooCommerce specific coding standards.
+- **Data Safety**: Validate state and permissions before performing destructive operations.
+- **Consistency**: Follow existing naming and structural patterns in the codebase.
+- **Documentation**: Provide appropriate `@since` and `@testdox` annotations.

package/skills/woocommerce/references/backend-dev-guide.md

@@ -0,0 +1,44 @@
+
+# WooCommerce Backend Development
+
+This skill provides guidance for developing WooCommerce backend PHP code according to project standards and conventions.
+
+## When to Use This Skill
+
+**ALWAYS invoke this skill before:**
+
+- Writing new PHP unit tests (`*Test.php` files)
+- Creating new PHP classes
+- Modifying existing backend PHP code
+- Adding hooks or filters
+
+## Instructions
+
+Follow WooCommerce project conventions when adding or modifying backend PHP code:
+
+1. **Creating new code structures**: See [file-entities.md](file-entities.md) for conventions on creating classes and organizing files (but for new unit test files see [unit-tests.md](unit-tests.md)).
+2. **Naming conventions**: See [code-entities.md](code-entities.md) for naming methods, variables, and parameters
+3. **Coding style**: See [coding-conventions.md](coding-conventions.md) for general coding standards and best practices
+4. **Type annotations**: See [type-annotations.md](type-annotations.md) for PHPStan-aware PHPDoc annotations
+5. **Working with hooks**: See [hooks.md](hooks.md) for hook callback conventions and documentation
+6. **Dependency injection**: See [dependency-injection.md](dependency-injection.md) for DI container usage
+7. **Data integrity**: See [data-integrity.md](data-integrity.md) for ensuring data integrity when performing CRUD operations
+8. **Writing tests**: See [unit-tests.md](unit-tests.md) for unit testing conventions
+
+## Key Principles
+
+- Always follow WordPress Coding Standards
+- Use class methods instead of standalone functions
+- Place new internal classes in `src/Internal/` by default
+- Use PSR-4 autoloading with `Automattic\WooCommerce` namespace
+- Write comprehensive unit tests for new functionality
+- Run linting and tests before committing changes
+
+## Version Information
+
+To determine the next WooCommerce version number for `@since` annotations:
+
+- Read the `$version` property in `includes/class-woocommerce.php` **on the trunk branch**
+- Remove the `-dev` suffix if present
+- Example: If trunk shows `10.4.0-dev`, use `@since 10.4.0`
+- Note: When reviewing PRs against trunk, the version in trunk is correct even if it seems "future" relative to released versions

package/skills/woocommerce/references/code-entities.md

@@ -0,0 +1,186 @@
+# Creating Code Entities (Methods, Variables, Parameters)
+
+## Table of Contents
+
+- [Naming Conventions](#naming-conventions)
+- [Method Visibility](#method-visibility)
+- [Static Methods](#static-methods)
+- [Docblock Requirements](#docblock-requirements)
+    - [Public, Protected Methods, and Hooks](#public-protected-methods-and-hooks)
+    - [Private Methods and Internal Callbacks](#private-methods-and-internal-callbacks)
+    - [@internal Annotation Placement](#internal-annotation-placement)
+- [Hook Docblocks](#hook-docblocks)
+
+## Naming Conventions
+
+Use snake_case for methods, variables, and hooks (not camelCase or PascalCase).
+
+**Examples:**
+
+```php
+// Correct
+public function calculate_order_total() { }
+private $order_items;
+```
+
+## Method Visibility
+
+New class methods should be `private` by default.
+
+**Use `protected`** only if it's clear the method will be used in derived classes.
+
+**Use `public`** only if the method will be called from outside the class.
+
+**Examples:**
+
+```php
+class OrderProcessor {
+    // Default: private for internal helpers
+    private function validate_items( array $items ) { }
+
+    // Protected: for use in child classes
+    protected function get_tax_rate( string $country ) { }
+
+    // Public: external API
+    public function process_order( int $order_id ) { }
+}
+```
+
+## Static Methods
+
+Pure methods (output depends only on inputs, no external dependencies) must be `static`.
+
+**Examples of pure methods (should be static):**
+
+```php
+// Mathematical calculations
+public static function calculate_percentage( float $amount, float $percent ) {
+    return $amount * ( $percent / 100 );
+}
+
+// String manipulations
+public static function format_product_sku( string $sku ) {
+    return strtoupper( trim( $sku ) );
+}
+
+// Data transformations
+public static function normalize_address( array $address ) {
+    return array_map( 'trim', $address );
+}
+```
+
+**Examples of non-pure methods (should NOT be static):**
+
+```php
+// Depends on database
+public function get_order_total( int $order_id ) { }
+
+// Depends on system time
+public function is_order_recent( int $order_id ) { }
+
+// Uses object state
+public function calculate_with_tax( float $amount ) {
+    return $amount * $this->tax_rate;
+}
+```
+
+**Exception:** Non-pure methods should not be `static` unless there's a specific architectural reason (e.g., singleton pattern, factory methods).
+
+## Docblock Requirements
+
+Add concise docblocks to all hooks and methods. One line is ideal.
+
+### Public, Protected Methods, and Hooks
+
+Must include a `@since` annotation with the next WooCommerce version number.
+
+The `@since` annotation must be:
+
+- The last line in the docblock
+- Preceded by a blank comment line
+- Use the version from `includes/class-woocommerce.php` on trunk, removing the `-dev` suffix
+  (e.g., if trunk shows `10.4.0-dev`, use `@since 10.4.0`)
+
+**Good - Concise:**
+
+```php
+/**
+ * Process the order and update status.
+ *
+ * @param int $order_id The order ID.
+ * @return bool True if successful.
+ *
+ * @since 9.5.0
+ */
+public function process_order( int $order_id ) { }
+
+/**
+ * Fires after an order is processed.
+ *
+ * @param int $order_id The order ID.
+ *
+ * @since 9.5.0
+ */
+do_action( 'woocommerce_order_processed', $order_id );
+```
+
+**Avoid - Over-explained:**
+
+```php
+/**
+ * This method processes the order by validating the order data,
+ * checking inventory levels, processing payment, and then updating
+ * the order status to reflect the successful processing.
+ *
+ * @param int $order_id The unique identifier for the order that needs to be processed.
+ * @return bool Returns true if the order was processed successfully, false otherwise.
+ *
+ * @since 9.5.0
+ */
+```
+
+For hooks, aim for a single descriptive line whenever possible.
+
+### Private Methods and Internal Callbacks
+
+Do NOT require a `@since` annotation if they are:
+
+- Private methods
+- Internal callbacks (marked with `@internal`)
+
+**Example:**
+
+```php
+/**
+ * Internal helper to validate order items.
+ *
+ * @param array $items The items to validate.
+ * @return bool
+ */
+private function validate_items( array $items ) { }
+```
+
+### @internal Annotation Placement
+
+When an `@internal` annotation is added, it must be:
+
+- Placed after the method description
+- Placed before the arguments list
+- Have a blank comment line before and after
+
+**Example:**
+
+```php
+/**
+ * Handle the woocommerce_init hook.
+ *
+ * @internal
+ *
+ * @param array $args Hook arguments.
+ */
+public function handle_woocommerce_init( array $args ) { }
+```
+
+## Hook Docblocks
+
+For information about documenting hooks (including adding docblocks to existing hooks), see [hooks.md](hooks.md).