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

package/skills/woocommerce/references/markdown-guide.md

@@ -0,0 +1,358 @@
+
+# WooCommerce Markdown Guidelines
+
+This skill provides guidance for creating and editing markdown files in the WooCommerce project.
+
+## Critical Rules
+
+1. **Always lint after changes** - Run `markdownlint --fix` then `markdownlint` to verify
+2. **Run from repository root** - Ensures `.markdownlint.json` config is loaded
+3. **Use UTF-8 encoding** - Especially for directory trees and special characters
+4. **Follow WooCommerce markdown standards** - See configuration rules below
+
+## WooCommerce Markdown Configuration
+
+The project uses markdownlint with these specific rules (from `.markdownlint.json`):
+
+### Enabled Rules
+
+- **MD003**: Heading style must be ATX (`# Heading` not `Heading\n===`)
+- **MD007**: Unordered list indentation must be 4 spaces
+- **MD013**: Line length limit disabled (set to 9999)
+- **MD024**: Multiple headings with same content allowed (only check siblings)
+- **MD031**: Fenced code blocks must be surrounded by blank lines
+- **MD032**: Lists must be surrounded by blank lines
+- **MD033**: HTML allowed for `<video>` elements only
+- **MD036**: Emphasis (bold/italic) should not be used as headings - use proper heading tags
+- **MD040**: Fenced code blocks should specify language
+- **MD047**: Files must end with a single newline
+
+### Disabled Rules
+
+- **no-hard-tabs**: Tabs are allowed
+- **whitespace**: Trailing whitespace rules disabled
+
+## Markdown Writing Guidelines
+
+### Headings
+
+```markdown
+# Main Title (H1) - Only one per file
+
+## Section (H2)
+
+### Subsection (H3)
+
+#### Minor Section (H4)
+```
+
+- Use ATX style (`#`) not underline style
+- One H1 per file (usually the title)
+- Maintain heading hierarchy (don't skip levels)
+
+### Lists
+
+**Unordered lists:**
+
+```markdown
+- Item one
+- Item two
+    - Nested item (4 spaces)
+    - Another nested item
+- Item three
+```
+
+**Ordered lists:**
+
+```markdown
+1. First item
+2. Second item
+3. Third item
+```
+
+**Important:**
+
+- Use 4 spaces for nested list items
+- Add blank line before and after lists
+- Use `-` for unordered lists (not `*` or `+`)
+
+### Code Blocks
+
+**Always specify the language:**
+
+````markdown
+```bash
+pnpm test:php:env
+```
+
+```php
+public function process_order( int $order_id ) {
+    // code here
+}
+```
+
+```javascript
+const result = calculateTotal(items);
+```
+````
+
+**Common language identifiers:**
+
+- `bash` - Shell commands
+- `php` - PHP code
+- `javascript` or `js` - JavaScript
+- `typescript` or `ts` - TypeScript
+- `json` - JSON data
+- `sql` - SQL queries
+- `markdown` or `md` - Markdown examples
+
+**Code block rules:**
+
+- Add blank line before the opening fence
+- Add blank line after the closing fence
+- Always specify language (never use plain ` ``` `)
+
+### Inline Code
+
+Use backticks for inline code:
+
+```markdown
+Use the `process_order()` method to handle orders.
+The `$order_id` parameter must be an integer.
+```
+
+### Links
+
+```markdown
+[Link text](https://example.com)
+
+[Internal link](../path/to/file.md)
+
+[Link with title](https://example.com "Optional title")
+```
+
+### Tables
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Value 1  | Value 2  | Value 3  |
+| Value 4  | Value 5  | Value 6  |
+```
+
+- Use pipes (`|`) for column separators
+- Header separator row required
+- Alignment optional (`:---`, `:---:`, `---:`)
+
+### Directory Trees
+
+**Always use UTF-8 box-drawing characters:**
+
+```markdown
+src/
+├── Internal/
+│   ├── Admin/
+│   │   └── Controller.php
+│   └── Utils/
+│       └── Helper.php
+└── External/
+    └── API.php
+```
+
+**Never use:**
+
+- ASCII art (`+--`, `|--`)
+- Spaces or tabs for tree structure
+- Control characters
+
+### Emphasis
+
+```markdown
+**Bold text** for strong emphasis
+*Italic text* for regular emphasis
+***Bold and italic*** for very strong emphasis
+```
+
+## Workflow for Editing Markdown
+
+1. **Make your changes** to the markdown file
+2. **Auto-fix linting issues:**
+
+   ```bash
+   markdownlint --fix path/to/file.md
+   ```
+
+3. **Check for remaining issues:**
+
+   ```bash
+   markdownlint path/to/file.md
+   ```
+
+4. **Manually fix** what remains (usually language specs for code blocks)
+5. **Verify clean** - No output means success
+6. **Commit changes**
+
+## Common Linting Errors and Fixes
+
+### MD007: List indentation
+
+**Problem:**
+
+```markdown
+- Item
+  - Nested (only 2 spaces)
+```
+
+**Fix:**
+
+```markdown
+- Item
+    - Nested (4 spaces)
+```
+
+### MD031: Code blocks need blank lines
+
+**Problem:**
+
+````markdown
+Some text
+```bash
+command
+```
+More text
+````
+
+**Fix:**
+
+````markdown
+Some text
+
+```bash
+command
+```
+
+More text
+````
+
+### MD032: Lists need blank lines
+
+**Problem:**
+
+````markdown
+Some text
+- List item
+````
+
+**Fix:**
+
+````markdown
+Some text
+
+- List item
+````
+
+### MD036: Emphasis as heading
+
+**Problem:**
+
+```markdown
+**Example: Using bold as a heading**
+
+Some content here
+```
+
+**Fix:**
+
+```markdown
+#### Example: Using a proper heading
+
+Some content here
+```
+
+### MD040: Code needs language
+
+**Problem:**
+
+````markdown
+```
+code here
+```
+````
+
+**Fix:**
+
+````markdown
+```bash
+code here
+```
+````
+
+## Special Cases
+
+### CLAUDE.md Files
+
+CLAUDE.md files are AI assistant documentation:
+
+- Must be well-formatted for optimal parsing by AI
+- Follow all markdownlint rules strictly
+- Use clear, hierarchical structure
+- Include table of contents for long files
+
+### README Files
+
+- Start with H1 title
+- Include brief description
+- Add installation/usage sections
+- Keep concise and scannable
+
+### Changelog Files
+
+- Follow Keep a Changelog format
+- Use consistent date formatting
+- Group changes by type (Added, Changed, Fixed, etc.)
+
+## Troubleshooting
+
+### File Shows as "data" Instead of Text
+
+**Problem:** File is corrupted with control characters
+
+**Fix:**
+
+```bash
+tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
+file file.md  # Verify shows "UTF-8 text"
+```
+
+### Linting Shows Unexpected Errors
+
+**Problem:** Not running from repository root
+
+**Fix:**
+
+```bash
+# Always run from root
+cd /path/to/woocommerce
+markdownlint path/to/file.md
+
+# NOT like this
+markdownlint /absolute/path/to/file.md
+```
+
+### Auto-fix Doesn't Work
+
+**Problem:** Some issues require manual intervention
+
+**Fix:**
+
+- Language specs for code blocks must be added manually
+- Long lines may need manual rewrapping
+- Some structural issues require content reorganization
+
+## Notes
+
+- Most markdown issues are auto-fixable with `markdownlint --fix`
+- Always run markdownlint from repository root
+- UTF-8 encoding is critical for special characters
+- CLAUDE.md files must pass linting for optimal AI parsing
+- See `woocommerce-dev-cycle` skill for markdown linting commands

package/skills/woocommerce/references/markdown-linting.md

@@ -0,0 +1,202 @@
+# Markdown Linting
+
+## Table of Contents
+
+- [Critical Rule](#critical-rule)
+- [Installation](#installation)
+- [Basic Commands](#basic-commands)
+- [Important: Always Run from Repository Root](#important-always-run-from-repository-root)
+- [Recommended Workflow](#recommended-workflow)
+- [Common Markdown Linting Issues](#common-markdown-linting-issues)
+- [Character Encoding in Markdown Files](#character-encoding-in-markdown-files)
+- [Examples](#examples)
+- [Notes](#notes)
+
+## Critical Rule
+
+**ALWAYS lint markdown files after changes.** They must pass markdownlint validation.
+
+## Installation
+
+If markdownlint is not available:
+
+```bash
+npm install -g markdownlint-cli
+```
+
+## Basic Commands
+
+```bash
+# Check markdown file (run from repo root)
+markdownlint plugins/woocommerce/CLAUDE.md
+
+# RECOMMENDED: Auto-fix issues first (handles most errors)
+markdownlint --fix plugins/woocommerce/CLAUDE.md
+
+# Check multiple files
+markdownlint packages/js/CLAUDE.md plugins/woocommerce/CLAUDE.md
+
+# Lint all CLAUDE.md files
+markdownlint packages/js/CLAUDE.md plugins/woocommerce/CLAUDE.md \
+  plugins/woocommerce/client/admin/CLAUDE.md
+```
+
+## Important: Always Run from Repository Root
+
+**CRITICAL:** Always run markdownlint from the repository root so the `.markdownlint.json` config file is loaded.
+
+Using absolute paths bypasses the config and may show incorrect errors.
+
+```bash
+# ✅ CORRECT - run from repo root
+cd /path/to/woocommerce
+markdownlint plugins/woocommerce/CLAUDE.md
+
+# ❌ WRONG - bypasses config
+markdownlint /absolute/path/to/plugins/woocommerce/CLAUDE.md
+```
+
+## Recommended Workflow
+
+1. Make markdown changes
+2. Run `markdownlint --fix path/to/file.md` (auto-fixes most issues)
+3. Check remaining: `markdownlint path/to/file.md`
+4. Manually fix what remains (language specs, long lines)
+5. Verify clean, then commit
+
+## Common Markdown Linting Issues
+
+| Code | Issue | Description | Fix |
+|------|-------|-------------|-----|
+| **MD007** | List indentation | Wrong indentation level | Use 4 spaces for nested items |
+| **MD013** | Line length limit | Line exceeds 80 chars | Break into multiple lines |
+| **MD031** | Code blocks need blank lines | Missing blank lines | Add blank above/below code blocks |
+| **MD032** | Lists need blank lines | Missing blank lines | Add blank before/after lists |
+| **MD036** | Emphasis as heading | Using bold instead of heading | Use `###` not bold |
+| **MD040** | Code needs language | Missing language spec | Add: \`\`\`bash, \`\`\`php, etc. |
+| **MD047** | Need trailing newline | File doesn't end with newline | File must end with newline |
+
+## Character Encoding in Markdown Files
+
+### Critical: Use Proper UTF-8 Characters
+
+**NEVER allow control characters or null bytes into markdown files.**
+
+### Directory Trees
+
+Use UTF-8 box-drawing characters, not spaces, tabs, or ASCII art:
+
+```markdown
+✅ CORRECT - UTF-8 box-drawing:
+.ai/skills/
+├── woocommerce-backend/
+│   ├── SKILL.md
+│   └── file-entities.md
+└── woocommerce-dev-cycle/
+    └── SKILL.md
+
+❌ WRONG - ASCII art or spaces:
+.ai/skills/
++-- woocommerce-backend/
+|   +-- SKILL.md
+    +-- file-entities.md
+```
+
+### Avoiding File Corruption
+
+**NEVER use Edit tool after `markdownlint --fix`** if the file contains directory trees.
+
+**Always check file encoding first:**
+
+```bash
+file path/to/file.md
+# Should show: "UTF-8 text" or "ASCII text"
+# NEVER: "data"
+```
+
+### Fixing Corrupted Files
+
+If a file becomes corrupted (shows as "data" instead of text):
+
+```bash
+# Remove control characters and null bytes
+tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
+
+# Verify encoding after fix
+file file.md
+```
+
+## Examples
+
+### Adding Language Specs to Code Blocks
+
+**Before:**
+
+````markdown
+```
+pnpm test:php:env
+```
+````
+
+**After:**
+
+````markdown
+```bash
+pnpm test:php:env
+```
+````
+
+Common language specs:
+
+- `bash` - Shell commands
+- `php` - PHP code
+- `javascript` or `js` - JavaScript
+- `typescript` or `ts` - TypeScript
+- `json` - JSON data
+- `markdown` or `md` - Markdown examples
+
+### Breaking Long Lines
+
+**Before:**
+
+```markdown
+This is a very long line that exceeds the 80 character limit and needs to be broken into multiple lines for better readability.
+```
+
+**After:**
+
+```markdown
+This is a very long line that exceeds the 80 character limit and needs to be
+broken into multiple lines for better readability.
+```
+
+### Blank Lines Around Code Blocks
+
+**Before:**
+
+````markdown
+Some text here
+```bash
+command here
+```
+More text
+````
+
+**After:**
+
+````markdown
+Some text here
+
+```bash
+command here
+```
+
+More text
+````
+
+## Notes
+
+- `markdownlint --fix` automatically handles most issues
+- CLAUDE.md files are AI assistant documentation and must be well-formatted for optimal parsing
+- Only a few issues require manual fixing (language specs, long lines)
+- Always verify encoding after edits to prevent corruption

package/skills/woocommerce/references/php-i18n-patterns.md

@@ -0,0 +1,83 @@
+# PHP i18n Patterns for WooCommerce
+
+This guide covers internationalization (i18n) standards for WooCommerce backend PHP development.
+
+## Core Functions
+
+### Basic Translation
+
+Always use the `woocommerce` text domain for WooCommerce-related strings.
+
+```php
+// Simple string
+__( 'Save changes', 'woocommerce' );
+
+// Echoed string
+_e( 'Order details', 'woocommerce' );
+```
+
+### Contextual Translation
+
+Use `_x` when a word has multiple meanings and needs context for translators.
+
+```php
+_x( 'Post', 'verb', 'woocommerce' );
+_x( 'Post', 'noun', 'woocommerce' );
+```
+
+### Pluralization
+
+```php
+printf(
+    _n( '%d item', '%d items', $count, 'woocommerce' ),
+    $count
+);
+```
+
+### Strings with Placeholders
+
+Use `printf` or `sprintf` with `__()`. **Never** use variables directly inside translation functions.
+
+```php
+// ✅ CORRECT
+printf(
+    /* translators: %s: customer name */
+    __( 'Hello %s', 'woocommerce' ),
+    $customer_name
+);
+
+// ❌ WRONG
+__( "Hello $customer_name", 'woocommerce' );
+```
+
+## Translator Comments
+
+Always provide context for placeholders. The comment must be immediately above the line with the translation function.
+
+```php
+/* translators: 1: product name 2: category name */
+$message = sprintf( __( '%1$s in %2$s', 'woocommerce' ), $product_name, $category_name );
+```
+
+## Brand Names
+
+Brand names like "WooCommerce" or "WooPayments" should often be treated as constants or placeholders if they are used frequently, but in many cases, they are kept in the string if they shouldn't be translated.
+
+```php
+sprintf(
+    /* translators: %s: product name */
+    __( 'Buy %s on WooCommerce', 'woocommerce' ),
+    $product_name
+);
+```
+
+## Best Practices
+
+1. **No HTML in strings**: Keep HTML outside of translatable strings when possible to avoid translation breakage.
+2. **Full Sentences**: Don't break sentences into multiple translation calls. Translators need the full context.
+3. **Escaping**: Always escape translated strings that are being output to the browser.
+   ```php
+   echo esc_html__( 'Text', 'woocommerce' );
+   echo esc_attr__( 'Title', 'woocommerce' );
+   ```
+4. **Text Domain**: Ensure you use the correct text domain. If building a plugin, use your plugin's text domain.