From b3dde547b1b48632b7f429b380a974ae5ac16066 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:39:55 +0000 Subject: [PATCH 01/13] Add agents.md file --- AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 68 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..8a7ec6bf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# AGENTS.md + +This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. See @README.md for more details. + +## Tech Stack + +- WordPress +- PHP +- JavaScript +- HTML +- CSS + +See @CONTRIBUTING.md for more details on the tech stack and development setup. + +## Directory Structure + +- `src/`: Source code for the plugin, including the main JavaScript files and utilities. +- `assets/`: Assets for the plugin, e.g. screenshots for documentation. +- `includes/`: Includes for the plugin. This is where the main plugin code is located. +- `test/`: JavaScript Jest test setup for the plugin. +- `tests/`: PHP unit tests for the plugin. +- `vendor/`: Vendor files for the plugin, including PHP dependencies. + +## Commands + +```bash +# Install dependencies +npm install + +# Build the plugin +npm run build + +# Watch for changes and rebuild the plugin +npm run start + +# Run the test setup +npm run test:php:setup + +# Run the PHP unit tests +npm run test:php + +# Run the JavaScript unit tests +npm run test:unit + +# Run the linter +npm run lint:php +npm run lint:js +npm run lint:css +``` + +## Conventions to Follow + +- Use the WordPress coding standards. +- Use the WordPress block editor coding standards. + +## Common Pitfalls + +- Always keep in mind that anything in this plugin should eventually be migrated to the WordPress Editor (Gutenberg). +- This plugin can be run on sites with or without the Gutenberg plugin installed. + +## Documentation and Links + +- @README.md for the plugin README. +- @CONTRIBUTING.md for the plugin contributing guidelines. +- [Plugin Documentation](https://wordpress.org/plugins/create-block-theme/) +- [Plugin Repository](https://github.com/WordPress/create-block-theme) +- [Plugin Support](https://wordpress.org/support/plugin/create-block-theme/) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From b047277f45ed0d2d96c5d11db99cfe29db0c327d Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:42:41 +0000 Subject: [PATCH 02/13] Add PR instructions --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8a7ec6bf..f1b297fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,11 @@ npm run lint:css - Always keep in mind that anything in this plugin should eventually be migrated to the WordPress Editor (Gutenberg). - This plugin can be run on sites with or without the Gutenberg plugin installed. +## PR instructions + +- Ensure build passes. +- Fix all formatting and linting issues; these are enforced through CI in PRs. + ## Documentation and Links - @README.md for the plugin README. From b41339549ce6a9c514e1058a90fca0c0b6afc970 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:43:13 +0000 Subject: [PATCH 03/13] Fix spacing --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f1b297fa..5cfa5cc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,8 +60,8 @@ npm run lint:css ## PR instructions -- Ensure build passes. -- Fix all formatting and linting issues; these are enforced through CI in PRs. +- Ensure build passes. +- Fix all formatting and linting issues; these are enforced through CI in PRs. ## Documentation and Links From 84b16ae7bc26c75e64e953f59623eeef420b8a6c Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:44:36 +0000 Subject: [PATCH 04/13] Add composer script --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5cfa5cc8..09257e18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,9 +24,12 @@ See @CONTRIBUTING.md for more details on the tech stack and development setup. ## Commands ```bash -# Install dependencies +# Install Node dependencies npm install +# Install Composer dependencies +composer install + # Build the plugin npm run build From 2ba2bda1840c6135ecaf92ef7fd6f9c78a6fa66f Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:51:18 +0000 Subject: [PATCH 05/13] Exclude CLAUDE.md from linting --- .markdownlintignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 .markdownlintignore diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 00000000..ceb2b988 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1 @@ +CLAUDE.md From 3a91e93a09d2a39165c1be583e709a22354856a9 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 10:55:27 +0000 Subject: [PATCH 06/13] Add vendor and node_modules to lint ignore --- .markdownlintignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.markdownlintignore b/.markdownlintignore index ceb2b988..cc53a4fc 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1 +1,3 @@ CLAUDE.md +node_modules/ +vendor/ From 7d6e5014afb86a30b25729f45dea80fd1bfb7964 Mon Sep 17 00:00:00 2001 From: Sarah Norris <1645628+mikachan@users.noreply.github.com> Date: Mon, 23 Feb 2026 11:12:58 +0000 Subject: [PATCH 07/13] Update AGENTS.md Co-authored-by: Ben Dwyer --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 09257e18..b9ebd9e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ npm run lint:css ## Common Pitfalls -- Always keep in mind that anything in this plugin should eventually be migrated to the WordPress Editor (Gutenberg). +- Always keep in mind that anything in this plugin could be migrated to the WordPress Editor (Gutenberg). - This plugin can be run on sites with or without the Gutenberg plugin installed. ## PR instructions From b1c93acbbc9496c0801b996c09cfcd72fbaa787f Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 11:34:08 +0000 Subject: [PATCH 08/13] List plugin features --- AGENTS.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b9ebd9e9..ad9cbcb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,14 @@ # AGENTS.md -This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. See @README.md for more details. +This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. The main purpose of the plugin is to provide additional functionality on top of the existing theme features in the Editor. See @README.md for more details. + +The main features include: + +- Export the activated theme with all the user's changes made in the Editor. +- Create a new theme, blank theme, child theme, or style variation from the Editor. +- Option to add all images used in templates to the theme's `assets` folder. +- Option to ensure the block markup used in templates and patterns is export-ready. +- Option to make most strings used in templates and patterns translate-ready. ## Tech Stack From 86418d136cb185f488738701f2afac5704580570 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 11:43:04 +0000 Subject: [PATCH 09/13] Add more specific info --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ad9cbcb9..cf1bbf37 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,8 +23,11 @@ See @CONTRIBUTING.md for more details on the tech stack and development setup. ## Directory Structure - `src/`: Source code for the plugin, including the main JavaScript files and utilities. + - `plugin-sidebar.js`: Entry point for the Block Editor plugin sidebar (loads in the Site Editor only). + - `admin-landing-page.js`: Entry point for the React app under Appearance > Create Block Theme. - `assets/`: Assets for the plugin, e.g. screenshots for documentation. - `includes/`: Includes for the plugin. This is where the main plugin code is located. + - `includes/create-theme/`: All main PHP logic, organised as `CBT_`-prefixed static utility classes (e.g. `CBT_Theme_JSON`, `CBT_Theme_Templates`, `CBT_Theme_Fonts`). - `test/`: JavaScript Jest test setup for the plugin. - `tests/`: PHP unit tests for the plugin. - `vendor/`: Vendor files for the plugin, including PHP dependencies. @@ -68,6 +71,8 @@ npm run lint:css - Always keep in mind that anything in this plugin could be migrated to the WordPress Editor (Gutenberg). - This plugin can be run on sites with or without the Gutenberg plugin installed. +- The plugin UI is gated using `wp_is_block_theme()`, which means nothing will appear on non-block themes. +- PHP code that touches theme.json must check for the `IS_GUTENBERG_PLUGIN` constant and use `WP_Theme_JSON_Gutenberg` when available, falling back to core `WP_Theme_JSON`. ## PR instructions From d6ac5f6b2a6a98c57e4733dcc7e7a4bac4b54957 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 11:45:43 +0000 Subject: [PATCH 10/13] Fix linting errors --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cf1bbf37..4ef18a0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,11 +23,11 @@ See @CONTRIBUTING.md for more details on the tech stack and development setup. ## Directory Structure - `src/`: Source code for the plugin, including the main JavaScript files and utilities. - - `plugin-sidebar.js`: Entry point for the Block Editor plugin sidebar (loads in the Site Editor only). - - `admin-landing-page.js`: Entry point for the React app under Appearance > Create Block Theme. + - `plugin-sidebar.js`: Entry point for the Block Editor plugin sidebar (loads in the Site Editor only). + - `admin-landing-page.js`: Entry point for the React app under Appearance > Create Block Theme. - `assets/`: Assets for the plugin, e.g. screenshots for documentation. - `includes/`: Includes for the plugin. This is where the main plugin code is located. - - `includes/create-theme/`: All main PHP logic, organised as `CBT_`-prefixed static utility classes (e.g. `CBT_Theme_JSON`, `CBT_Theme_Templates`, `CBT_Theme_Fonts`). + - `includes/create-theme/`: All main PHP logic, organised as `CBT_`-prefixed static utility classes (e.g. `CBT_Theme_JSON`, `CBT_Theme_Templates`, `CBT_Theme_Fonts`). - `test/`: JavaScript Jest test setup for the plugin. - `tests/`: PHP unit tests for the plugin. - `vendor/`: Vendor files for the plugin, including PHP dependencies. From 91a287de0ae81689958e99d3c070443560b7b389 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Mon, 23 Feb 2026 12:31:04 +0000 Subject: [PATCH 11/13] Remove unnecessary @s --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4ef18a0f..c6f580e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. The main purpose of the plugin is to provide additional functionality on top of the existing theme features in the Editor. See @README.md for more details. +This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. The main purpose of the plugin is to provide additional functionality on top of the existing theme features in the Editor. See README.md for more details. The main features include: @@ -18,7 +18,7 @@ The main features include: - HTML - CSS -See @CONTRIBUTING.md for more details on the tech stack and development setup. +See CONTRIBUTING.md for more details on the tech stack and development setup. ## Directory Structure @@ -81,8 +81,8 @@ npm run lint:css ## Documentation and Links -- @README.md for the plugin README. -- @CONTRIBUTING.md for the plugin contributing guidelines. +- README.md for the plugin README. +- CONTRIBUTING.md for the plugin contributing guidelines. - [Plugin Documentation](https://wordpress.org/plugins/create-block-theme/) - [Plugin Repository](https://github.com/WordPress/create-block-theme) - [Plugin Support](https://wordpress.org/support/plugin/create-block-theme/) From 4701a525f13c1cdd020893fe14ffe9c107aaae90 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Tue, 24 Feb 2026 11:54:17 +0000 Subject: [PATCH 12/13] Add intro --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c6f580e8..d04ef036 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,9 @@ # AGENTS.md +This file provides guidance to AI coding agents working in this repository. + +## Repository Overview + This is a WordPress plugin that allows you to create block themes from within the WordPress Editor. The main purpose of the plugin is to provide additional functionality on top of the existing theme features in the Editor. See README.md for more details. The main features include: From 8c67993082a8cdbdf884cdeee75779052ba04cbd Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Tue, 24 Feb 2026 12:22:59 +0000 Subject: [PATCH 13/13] Add more info --- AGENTS.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d04ef036..b34ca672 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,8 @@ See CONTRIBUTING.md for more details on the tech stack and development setup. - `assets/`: Assets for the plugin, e.g. screenshots for documentation. - `includes/`: Includes for the plugin. This is where the main plugin code is located. - `includes/create-theme/`: All main PHP logic, organised as `CBT_`-prefixed static utility classes (e.g. `CBT_Theme_JSON`, `CBT_Theme_Templates`, `CBT_Theme_Fonts`). -- `test/`: JavaScript Jest test setup for the plugin. +- `src/test/`: JavaScript unit tests. +- `test/`: JavaScript Jest configuration. - `tests/`: PHP unit tests for the plugin. - `vendor/`: Vendor files for the plugin, including PHP dependencies. @@ -51,21 +52,25 @@ npm run build # Watch for changes and rebuild the plugin npm run start -# Run the test setup +# Run the PHP unit tests (requires Docker; test:php:setup must succeed first) npm run test:php:setup - -# Run the PHP unit tests npm run test:php # Run the JavaScript unit tests npm run test:unit -# Run the linter +# Run the linters npm run lint:php npm run lint:js npm run lint:css +npm run lint:md-docs + +# Format code +npm run format ``` +Before committing, run all linters and format. These are all enforced in CI. + ## Conventions to Follow - Use the WordPress coding standards.