Commit 1d1be6ca10c for woocommerce
commit 1d1be6ca10c712788d546a7d67bc778b2e6b0b9d
Author: Vlad Olaru <vlad.olaru@automattic.com>
Date: Thu Mar 26 11:50:48 2026 +0200
Restructure CLAUDE.md into tool-agnostic AGENTS.md (#63867)
* refactor: move AI agent docs from CLAUDE.md to AGENTS.md
CLAUDE.md now uses the @AGENTS.md include directive to reference the
agent documentation. This separates AI agent instructions into a
dedicated file (AGENTS.md) that multiple AI tools can consume
(Claude Code, Cursor, Copilot, Codex) while keeping CLAUDE.md as the
entry point for Claude Code specifically.
* chore: add .claude/docs subdirectories to .gitignore
Add .claude/docs/plans/, .claude/docs/analysis/, and
.claude/docs/research/ to .gitignore. These directories contain
session-specific working documents generated by AI agents that
should not be committed.
* Revise AGENTS.md for consistent directory paths
diff --git a/.gitignore b/.gitignore
index 762e7bd57a5..39990e39913 100644
--- a/.gitignore
+++ b/.gitignore
@@ -113,6 +113,9 @@ changes.json
# Claude related files
**/.claude/**/*.local.*
+.claude/docs/plans/
+.claude/docs/analysis/
+.claude/docs/research/
CLAUDE.local.md
# Cursor related files
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..3fe2db8c15a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,208 @@
+# WooCommerce Monorepo - AI Agents Documentation
+
+## Project Overview
+
+WooCommerce is a WordPress e-commerce plugin organized as a monorepo with:
+
+- **Backend**: PHP in `plugins/woocommerce/` (PSR-4, WordPress standards)
+- **Admin Client**: React/TypeScript in `plugins/woocommerce/client/admin/`
+- **Payment Settings**: Specialized React/TypeScript module in `plugins/woocommerce/client/admin/client/settings-payments/`
+
+## Navigation Guide
+
+### Which Documentation to Use?
+
+**Use this doc when:**
+
+- Getting oriented in the project
+- Understanding overall architecture
+- Finding the right documentation or skill
+
+## Available Skills
+
+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-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
+- **`woocommerce-git`** - Guidelines for git and GitHub operations
+- **`woocommerce-email-editor`** - Email editor development setup and Mailpit configuration
+
+**CRITICAL:** After reading a skill, check if a personal skill override file exists at
+`~/.ai/skills/{skill-name}-personal/SKILL.md` and apply it too. For example, for the
+`woocommerce-backend-dev` skill, check for `~/.ai/skills/woocommerce-backend-dev-personal/SKILL.md`.
+**Personal override skills take precedence over project-level skills in case of conflict**.
+
+## Project Architecture
+
+### Directory Structure
+
+```text
+plugins/woocommerce/
+├── src/ # Modern PHP code (PSR-4, DI container)
+│ ├── Internal/ # Internal classes (default location)
+│ └── [Public classes] # Public API classes
+├── includes/ # Legacy WordPress code
+│ └── class-woocommerce.php # Main plugin class
+├── tests/php/ # PHPUnit tests
+│ ├── includes/ # Tests for legacy code
+│ └── src/ # Tests for modern code
+└── client/ # Frontend applications
+ └── admin/ # Admin React app
+```
+
+### Key Architectural Concepts
+
+**Modern vs Legacy Code:**
+
+- `plugins/woocommerce/src/` - Modern PHP with dependency injection, PSR-4 autoloading
+- `plugins/woocommerce/includes/` - Legacy WordPress patterns, modify only when necessary
+
+**Namespace:**
+
+- Root namespace: `Automattic\WooCommerce`
+- Internal classes: `Automattic\WooCommerce\Internal\*`
+
+**Dependency Injection:**
+
+- Classes in `plugins/woocommerce/src/` use DI container (`$container->get()`)
+- Dependencies injected via `init()` method
+
+**Version Management:**
+
+- Current version in `plugins/woocommerce/includes/class-woocommerce.php` → `$version` property
+- Used for `@since` annotations (remove `-dev` suffix)
+- When changing template files (PHP files used to display UI on the front-end) the version in their header should be updated to the current version, without the `-dev` suffix.
+
+## Development Workflow
+
+1. Make code changes
+2. Run relevant tests (see `woocommerce-dev-cycle` skill)
+3. Run linting (see `woocommerce-dev-cycle` skill)
+4. Run PHPStan for PHP changes (see below)
+5. Commit only after tests pass and all checks are clean
+6. Create changelog entries for each affected package
+7. Create PR only after changelog entries exist
+
+### Pre-commit Checks
+
+**Before committing PHP changes**, run these checks to avoid CI failures:
+
+```sh
+# Lint changed PHP files
+pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes
+
+# Run PHPStan on modified files (from plugins/woocommerce directory)
+composer exec -- phpstan analyse path/to/modified/File.php --memory-limit=2G
+```
+
+PHPStan failures often indicate the need to update the baseline file (`phpstan-baseline.neon`). If your fix resolves a previously baselined error, remove the corresponding entry from the baseline.
+
+### Pre-push Checks
+
+**Before pushing**, run the branch-level lint to catch issues across all commits on the branch (e.g. alignment warnings that per-file linting misses):
+
+```sh
+pnpm --filter=@woocommerce/plugin-woocommerce lint:changes:branch
+```
+
+This compares the full branch diff against trunk and runs `phpcs-changed` on it. Fix any warnings before pushing.
+
+**NEVER create a PR without changelog entries.** Each package modified in the monorepo requires its own changelog entry. Run for each affected package:
+
+```sh
+pnpm --filter=<project> changelog add
+```
+
+Example for WooCommerce Core:
+
+```sh
+pnpm --filter=@woocommerce/plugin-woocommerce changelog add
+```
+
+This command prompts for the change type and description. Run it once per affected package before creating any PR.
+
+### Pull Request Template
+
+When creating PRs, **always use the template** from `.github/PULL_REQUEST_TEMPLATE.md`. Key sections:
+
+- **Submission Review Guidelines**: Checkboxes confirming adherence to contributing guidelines
+- **Changes proposed in this Pull Request**: Description of changes and link to bug-introducing PR if applicable
+- **Screenshots or screen recordings**: UI changes screenshots (can be removed if not applicable)
+- **How to test the changes in this Pull Request**: Step-by-step testing instructions
+- **Testing that has already taken place**: What testing you've done
+- **Milestone**: Check the box to auto-assign milestone, or manually set to the first available milestone that is not in the past (unless otherwise specified)
+- **Changelog entry**: Note if changelog was created manually or check box to auto-create
+
+For bug fixes, always reference the PR that introduced the bug using: `Bug introduced in PR #XXXXX.`
+
+## Testing Environment
+
+- PHP tests run in Docker via `wp-env`
+- WordPress and WooCommerce auto-installed
+- Uses PHPUnit 9.6.24 with PHP 8.1
+
+For detailed test commands, see `woocommerce-dev-cycle` skill.
+
+## Known Constraints
+
+- `includes/` directory changes should be minimal (legacy code)
+- All new backend code goes in `plugins/woocommerce/src/Internal/` by default
+- Never create standalone functions (always use class methods)
+- Tests require Docker environment
+
+## Interactivity API Stores
+
+All WooCommerce Interactivity API stores are **private by design**:
+
+- Stores use `lock: true` indicating they are not intended for extension
+- Removing or changing store state/selectors is **not a breaking change**
+- No backwards compatibility is required for store internals
+- If a store needs to be extensible in the future, it will be split into private (internal) and public (API) stores
+- General stores (namespace `woocommerce`) may become public eventually, but currently all are locked
+
+Reference: [WordPress Interactivity API - Private Stores](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference#private-stores)
+
+## Quick Reference
+
+### Most Common Commands
+
+```sh
+# Run specific test class
+pnpm test:php:env -- --filter TestClassName
+
+# Lint changed files
+pnpm lint:php:changes
+
+# Fix linting issues
+pnpm lint:php:fix -- path/to/file.php
+```
+
+For complete command reference and workflows, see `woocommerce-dev-cycle` skill.
+
+## Monorepo Context
+
+This is part of the WooCommerce monorepo:
+
+- Multiple packages managed with pnpm workspaces
+- Root-level scripts coordinate across packages
+- Some dependencies shared across packages
+
+## Historical Context
+
+**Why two code styles?** The `plugins/woocommerce/includes/` directory predates modern PHP practices. New code uses PSR-4 and dependency injection in `plugins/woocommerce/src/`.
+
+**Why DI container?** Improves testability and maintainability compared to legacy global state patterns.
+
+## Automated Code Reviews
+
+For code review standards and critical violations to flag, use the **`woocommerce-code-review` skill**.
+
+## Notes for AI Agents
+
+- This doc provides context; skills provide procedures
+- When in doubt about HOW to do something, check the skills
+- When in doubt about WHAT something is or WHERE it fits, check this doc
+- Skills are invoked automatically when relevant to the task
diff --git a/CLAUDE.md b/CLAUDE.md
index 2bb69d3d30c..43c994c2d36 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,213 +1 @@
-# WooCommerce Monorepo - Claude Documentation
-
-## Project Overview
-
-WooCommerce is a WordPress e-commerce plugin organized as a monorepo with:
-
-- **Backend**: PHP in `plugins/woocommerce/` (PSR-4, WordPress standards)
-- **Admin Client**: React/TypeScript in `client/admin/`
-- **Payment Settings**: Specialized module in `client/admin/client/settings-payments/`
-
-## Navigation Guide
-
-### Which Documentation to Use?
-
-**Use this doc when:**
-
-- Getting oriented in the project
-- Understanding overall architecture
-- Finding the right documentation or skill
-
-**Use other CLAUDE.md files when:**
-
-- React/TypeScript development → `client/admin/CLAUDE.md`
-- Payment gateway UI → `client/admin/client/settings-payments/CLAUDE.md`
-
-## Available Skills
-
-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-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
-- **`woocommerce-git`** - Guidelines for git and GitHub operations
-- **`woocommerce-email-editor`** - Email editor development setup and Mailpit configuration
-
-**CRITICAL:** After reading a skill, check if a personal skill override file exists at
-`~/.ai/skills/{skill-name}-personal/SKILL.md` and apply it too. For example, for the
-`woocommerce-backend-dev` skill, check for `~/.ai/skills/woocommerce-backend-dev-personal/SKILL.md`.
-**Personal override skills take precedence over project-level skills in case of conflict**.
-
-## Project Architecture
-
-### Directory Structure
-
-```text
-plugins/woocommerce/
-├── src/ # Modern PHP code (PSR-4, DI container)
-│ ├── Internal/ # Internal classes (default location)
-│ └── [Public classes] # Public API classes
-├── includes/ # Legacy WordPress code
-│ └── class-woocommerce.php # Main plugin class
-├── tests/php/ # PHPUnit tests
-│ ├── includes/ # Tests for legacy code
-│ └── src/ # Tests for modern code
-└── client/ # Frontend applications
- └── admin/ # Admin React app
-```
-
-### Key Architectural Concepts
-
-**Modern vs Legacy Code:**
-
-- `src/` - Modern PHP with dependency injection, PSR-4 autoloading
-- `includes/` - Legacy WordPress patterns, modify only when necessary
-
-**Namespace:**
-
-- Root namespace: `Automattic\WooCommerce`
-- Internal classes: `Automattic\WooCommerce\Internal\*`
-
-**Dependency Injection:**
-
-- Classes in `src/` use DI container (`$container->get()`)
-- Dependencies injected via `init()` method
-
-**Version Management:**
-
-- Current version in `includes/class-woocommerce.php` → `$version` property
-- Used for `@since` annotations (remove `-dev` suffix)
-- When changing template files (PHP files used to display UI on the front-end) the version in their header should be updated to the current version, without the `-dev` suffix.
-
-## Development Workflow
-
-1. Make code changes
-2. Run relevant tests (see `woocommerce-dev-cycle` skill)
-3. Run linting (see `woocommerce-dev-cycle` skill)
-4. Run PHPStan for PHP changes (see below)
-5. Commit only after tests pass and all checks are clean
-6. Create changelog entries for each affected package
-7. Create PR only after changelog entries exist
-
-### Pre-commit Checks
-
-**Before committing PHP changes**, run these checks to avoid CI failures:
-
-```sh
-# Lint changed PHP files
-pnpm --filter=@woocommerce/plugin-woocommerce lint:php:changes
-
-# Run PHPStan on modified files (from plugins/woocommerce directory)
-composer exec -- phpstan analyse path/to/modified/File.php --memory-limit=2G
-```
-
-PHPStan failures often indicate the need to update the baseline file (`phpstan-baseline.neon`). If your fix resolves a previously baselined error, remove the corresponding entry from the baseline.
-
-### Pre-push Checks
-
-**Before pushing**, run the branch-level lint to catch issues across all commits on the branch (e.g. alignment warnings that per-file linting misses):
-
-```sh
-pnpm --filter=@woocommerce/plugin-woocommerce lint:changes:branch
-```
-
-This compares the full branch diff against trunk and runs `phpcs-changed` on it. Fix any warnings before pushing.
-
-**NEVER create a PR without changelog entries.** Each package modified in the monorepo requires its own changelog entry. Run for each affected package:
-
-```sh
-pnpm --filter=<project> changelog add
-```
-
-Example for WooCommerce Core:
-
-```sh
-pnpm --filter=@woocommerce/plugin-woocommerce changelog add
-```
-
-This command prompts for the change type and description. Run it once per affected package before creating any PR.
-
-### Pull Request Template
-
-When creating PRs, **always use the template** from `.github/PULL_REQUEST_TEMPLATE.md`. Key sections:
-
-- **Submission Review Guidelines**: Checkboxes confirming adherence to contributing guidelines
-- **Changes proposed in this Pull Request**: Description of changes and link to bug-introducing PR if applicable
-- **Screenshots or screen recordings**: UI changes screenshots (can be removed if not applicable)
-- **How to test the changes in this Pull Request**: Step-by-step testing instructions
-- **Testing that has already taken place**: What testing you've done
-- **Milestone**: Check the box to auto-assign milestone, or manually set to the first available milestone that is not in the past (unless otherwise specified)
-- **Changelog entry**: Note if changelog was created manually or check box to auto-create
-
-For bug fixes, always reference the PR that introduced the bug using: `Bug introduced in PR #XXXXX.`
-
-## Testing Environment
-
-- PHP tests run in Docker via `wp-env`
-- WordPress and WooCommerce auto-installed
-- Uses PHPUnit 9.6.24 with PHP 8.1
-
-For detailed test commands, see `woocommerce-dev-cycle` skill.
-
-## Known Constraints
-
-- `includes/` directory changes should be minimal (legacy code)
-- All new backend code goes in `src/Internal/` by default
-- Never create standalone functions (always use class methods)
-- Tests require Docker environment
-
-## Interactivity API Stores
-
-All WooCommerce Interactivity API stores are **private by design**:
-
-- Stores use `lock: true` indicating they are not intended for extension
-- Removing or changing store state/selectors is **not a breaking change**
-- No backwards compatibility is required for store internals
-- If a store needs to be extensible in the future, it will be split into private (internal) and public (API) stores
-- General stores (namespace `woocommerce`) may become public eventually, but currently all are locked
-
-Reference: [WordPress Interactivity API - Private Stores](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference#private-stores)
-
-## Quick Reference
-
-### Most Common Commands
-
-```sh
-# Run specific test class
-pnpm test:php:env -- --filter TestClassName
-
-# Lint changed files
-pnpm lint:php:changes
-
-# Fix linting issues
-pnpm lint:php:fix -- path/to/file.php
-```
-
-For complete command reference and workflows, see `woocommerce-dev-cycle` skill.
-
-## Monorepo Context
-
-This is part of the WooCommerce monorepo:
-
-- Multiple packages managed with pnpm workspaces
-- Root-level scripts coordinate across packages
-- Some dependencies shared across packages
-
-## Historical Context
-
-**Why two code styles?** The `includes/` directory predates modern PHP practices. New code uses PSR-4 and dependency injection in `src/`.
-
-**Why DI container?** Improves testability and maintainability compared to legacy global state patterns.
-
-## Automated Code Reviews
-
-For code review standards and critical violations to flag, use the **`woocommerce-code-review` skill**.
-
-## Notes for Claude
-
-- This doc provides context; skills provide procedures
-- When in doubt about HOW to do something, check the skills
-- When in doubt about WHAT something is or WHERE it fits, check this doc
-- Skills are invoked automatically when relevant to the task
+@AGENTS.md