Commit aa80a452abd for woocommerce
commit aa80a452abdc1812174a27cce2eccd9002145644
Author: James Kemp <me@jckemp.com>
Date: Fri May 22 15:15:23 2026 +0100
Update WooCommerce agent PR and environment skills (#65261)
* Update draft PR skill to preserve template comments
* Add WooCommerce local environment skill
diff --git a/.ai/skills/woocommerce-git-draft-pr/SKILL.md b/.ai/skills/woocommerce-git-draft-pr/SKILL.md
index 1eaa4f66979..17aad7e56e1 100644
--- a/.ai/skills/woocommerce-git-draft-pr/SKILL.md
+++ b/.ai/skills/woocommerce-git-draft-pr/SKILL.md
@@ -42,7 +42,7 @@ Extract issue/PR refs from commits and branch name:
### 3. Generate PR Title + Body
-Use the PR template from the dynamic context above.
+Use the PR template from the dynamic context above. Preserve HTML comments from the template in every retained section; several comments are automation markers or test fixtures for milestone, changelog, and other GitHub checks.
**Title** (under 70 chars, verb-first — the repo convention):
@@ -70,10 +70,10 @@ Use the full template:
- **Screenshots**: Remove section if no UI changes. For UI changes, use Chrome DevTools MCP to capture screenshots if available; otherwise remind user to add them before marking ready.
- **Testing instructions**: Concrete numbered steps with expected outcomes derived from the diff. Each step must be actionable — don't reference links that won't exist yet.
- **Testing done**: Fill with what's verifiable from the session (commits, test runs, lint runs). If nothing is verifiable, write "Author to fill in before marking ready."
-- **Milestone**: Check auto-assign `[x]` if plugin-affecting.
-- **Changelog**: If changelogs already in diff → "does not require" (created manually). Otherwise → "Automatically create" `[x]` with Significance, Type, and a user-facing Message.
+- **Milestone**: Check auto-assign `[x]` if plugin-affecting. Keep the surrounding template comments, including `<!-- milestone-target-selection -->` and `<!-- /milestone-target-selection -->`.
+- **Changelog**: If changelogs already in diff → "does not require" (created manually). Otherwise → "Automatically create" `[x]` with Significance, Type, and a user-facing Message. Keep the template comments in this section, including inline comments after headings such as `#### Message <!-- Add a changelog message here -->`.
-Strip all HTML comments (`<!-- -->`) and unfilled placeholder lines (e.g., `Closes # .`, `Bug introduced in PR # .`) from output.
+Do not strip HTML comments (`<!-- -->`) from retained template sections. They support PR automation and GitHub tests. Remove only unfilled placeholder lines that are actual visible placeholders (e.g., `Closes # .`, `Bug introduced in PR # .`).
### 4. Preview
@@ -95,5 +95,5 @@ Output the PR URL. If UI changes need screenshots, remind the user.
- No Co-Authored-By lines or self-attribution
- Never commit code — pushing is fine
-- Preserve the PR template section headings exactly (for plugin-affecting PRs)
+- Preserve the PR template section headings and HTML comments exactly in retained sections (for plugin-affecting PRs)
- Changelog checkboxes must match CI automation format
diff --git a/.ai/skills/woocommerce-local-env/SKILL.md b/.ai/skills/woocommerce-local-env/SKILL.md
new file mode 100644
index 00000000000..15413c616ba
--- /dev/null
+++ b/.ai/skills/woocommerce-local-env/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: woocommerce-local-env
+description: Set up, start, stop, restart, verify, and troubleshoot the WooCommerce Core local development environment with wp-env and asset build watchers. Use when Codex is asked to run WooCommerce locally, prepare wp-env, watch WooCommerce builds, choose between full and targeted build/watch commands, diagnose localhost:8888, or explain local environment setup commands.
+---
+
+# WooCommerce Local Environment
+
+## Overview
+
+Use this skill to get WooCommerce Core running locally without re-reading `plugins/woocommerce/README.md` and `.wp-env.json`.
+
+Prefer short root scripts when present. Fall back to filtered package commands if the aliases are not available.
+
+## Process Ownership
+
+Use this ownership model when deciding whether to run a command or tell the user what to run:
+
+- Run setup checks, dependency installs, one-shot builds, and `wp-env` start/stop commands from the agent when useful for the task. These commands should complete and return control.
+- Treat `watch:*` commands as user-owned long-running processes. Tell the user to run the relevant watcher in a separate terminal unless a short, temporary watcher session is explicitly needed for active verification.
+- Reuse an already-running environment when possible.
+- Stop or clean up any agent-owned long-running session before finishing.
+
+## Quick Commands
+
+Run these from the repository root:
+
+```bash
+# Start the wp-env development environment at http://localhost:8888/.
+pnpm wc:env
+
+# Stop or restart wp-env.
+pnpm wc:env:stop
+pnpm wc:env:restart
+
+# Watch all WooCommerce Core build outputs.
+pnpm wc:watch
+
+# Watch targeted build outputs.
+pnpm wc:watch:admin
+pnpm wc:watch:blocks
+pnpm wc:watch:classic-assets
+
+# Build all or targeted outputs once.
+pnpm wc:build
+pnpm wc:build:admin
+pnpm wc:build:blocks
+pnpm wc:build:classic-assets
+```
+
+`pnpm wc:env:restart` destroys and recreates the wp-env containers, so use it only when a clean restart is intended.
+
+Fallback commands from the WooCommerce package:
+
+```bash
+pnpm --filter='@woocommerce/plugin-woocommerce' env:dev
+pnpm --filter='@woocommerce/plugin-woocommerce' env:stop
+pnpm --filter='@woocommerce/plugin-woocommerce' env:restart
+pnpm --filter='@woocommerce/plugin-woocommerce' build
+pnpm --filter='@woocommerce/plugin-woocommerce' watch:build
+pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:admin
+pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:blocks
+pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:classic-assets
+```
+
+From `plugins/woocommerce/`, run the package scripts directly, for example `pnpm env:dev` or `pnpm watch:build`.
+
+## Setup Workflow
+
+1. Check prerequisites when setup fails or when the user asks for first-time setup:
+
+ ```bash
+ node --version
+ pnpm --version
+ php --version
+ composer --version
+ docker --version
+ docker info
+ ```
+
+2. Install dependencies from the repository root only when dependencies are missing or stale:
+
+ ```bash
+ pnpm install
+ ```
+
+3. Start the environment:
+
+ ```bash
+ pnpm wc:env
+ ```
+
+4. Tell the user to start a watcher in a separate terminal if frontend or asset changes need live rebuilds:
+
+ ```bash
+ pnpm wc:watch
+ ```
+
+Recommend targeted watchers for focused work to reduce noise and startup time:
+
+- Admin client: `pnpm wc:watch:admin`
+- Blocks client: `pnpm wc:watch:blocks`
+- Classic assets: `pnpm wc:watch:classic-assets`
+
+## Environment Details
+
+- Development URL: `http://localhost:8888/`
+- Test environment port: `8086`
+- wp-env config: `plugins/woocommerce/.wp-env.json`
+- wp-env PHP version: `8.1`
+- WooCommerce package: `@woocommerce/plugin-woocommerce`
+- Source README: `plugins/woocommerce/README.md`
+
+## Verification
+
+After starting `wp-env`, verify the site responds:
+
+```bash
+curl -I http://localhost:8888/
+```
+
+For browser-based verification, open `http://localhost:8888/` with the Browser plugin when the user asks to inspect or test the local site.
+
+## Troubleshooting
+
+- If `docker info` fails, ask the user to start Docker Desktop and retry.
+- If `pnpm wc:env` fails after dependency changes, run `pnpm install`, then retry.
+- If `wp-env` containers look stale, run `pnpm wc:env:restart` only after confirming a destructive environment reset is acceptable.
+- If assets do not update, confirm the relevant watcher is running and use a targeted watcher for the changed area.
+- If the user only needs PHP unit tests, prefer the test commands from `woocommerce-dev-cycle`; do not start a full browser workflow unless needed.
diff --git a/AGENTS.md b/AGENTS.md
index dbd94519134..c2436fcfd24 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,7 @@ The `.ai/skills/` directory contains procedural HOW-TO instructions:
- **`woocommerce-backend-dev`** - Backend PHP conventions and unit tests. **Invoke before writing any PHP test files.**
- **`woocommerce-dev-cycle`** - Testing and linting workflows (PHP, JS, markdown)
+- **`woocommerce-local-env`** - Local environment setup, wp-env commands, and WooCommerce build watchers
- **`woocommerce-copy-guidelines`** - UI text standards (sentence case rules)
- **`woocommerce-code-review`** - Code review standards and critical violations to flag
- **`woocommerce-markdown`** - Markdown writing and editing guidelines
diff --git a/package.json b/package.json
index c19df4848ce..d6eed867e97 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,18 @@
"postinstall": "husky",
"run-canonical-extensions-tests": "bash bin/run-canonical-extensions-tests.sh",
"sync-dependencies": "pnpm exec syncpack -- fix-mismatches",
- "utils": "./tools/monorepo-utils/bin/run"
+ "utils": "./tools/monorepo-utils/bin/run",
+ "wc:build": "pnpm --filter='@woocommerce/plugin-woocommerce' build",
+ "wc:build:admin": "pnpm --filter='@woocommerce/plugin-woocommerce' build:admin",
+ "wc:build:blocks": "pnpm --filter='@woocommerce/plugin-woocommerce' build:blocks",
+ "wc:build:classic-assets": "pnpm --filter='@woocommerce/plugin-woocommerce' build:classic-assets",
+ "wc:env": "pnpm --filter='@woocommerce/plugin-woocommerce' env:dev",
+ "wc:env:restart": "pnpm --filter='@woocommerce/plugin-woocommerce' env:restart",
+ "wc:env:stop": "pnpm --filter='@woocommerce/plugin-woocommerce' env:stop",
+ "wc:watch": "pnpm --filter='@woocommerce/plugin-woocommerce' watch:build",
+ "wc:watch:admin": "pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:admin",
+ "wc:watch:blocks": "pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:blocks",
+ "wc:watch:classic-assets": "pnpm --filter='@woocommerce/plugin-woocommerce' watch:build:classic-assets"
},
"devDependencies": {
"@babel/preset-env": "7.25.7",