Skip to content

Feature/content guidelines#359

Merged
dkotter merged 66 commits intoWordPress:developfrom
saarnilauri:feature/content-guidelines
Apr 22, 2026
Merged

Feature/content guidelines#359
dkotter merged 66 commits intoWordPress:developfrom
saarnilauri:feature/content-guidelines

Conversation

@saarnilauri
Copy link
Copy Markdown
Contributor

@saarnilauri saarnilauri commented Apr 1, 2026

What?

Closes #322

Adds Content Guidelines integration to the AI plugin, allowing all AI abilities to respect site-wide editorial standards defined via Gutenberg's wp_content_guideline custom post type (introduced in Gutenberg 22.7+).

Why?

When sites define content guidelines (tone, style, image standards, etc.), AI-generated content should follow them. Without this integration, AI abilities operate without awareness of the site's editorial standards, producing output that may not align with the site's voice and style.

How?

New Content_Guidelines service (includes/Services/Content_Guidelines.php):

  • Singleton that fetches and caches guidelines from the wp_content_guideline CPT
  • Supports four categories: site, copy, images, additional, plus per-block guidelines
  • Formats guidelines as XML-tagged strings (<content-guidelines>) for prompt injection
  • Truncates per-category content to 2000 chars (filterable via wpai_max_guideline_length)
  • Can be disabled via the wpai_use_content_guidelines filter
  • Gracefully returns empty/null when the CPT isn't registered

Abstract ability opt-in pattern (includes/Abstracts/Abstract_Ability.php):

  • New guideline_categories() method — subclasses override to declare which categories they use
  • New get_content_guidelines_for_prompt() helper fetches and formats guidelines for the declared categories
  • get_system_instruction() auto-appends a guidelines-awareness paragraph when categories are declared

Per-ability wiring — each ability declares relevant categories and injects guidelines into its prompt:

Ability Categories
Title Generation site, copy
Excerpt Generation site, copy
Summarization site, copy
Alt Text Generation site, images
Image Generation site, images
Image Prompt Generation site, images
Review Notes site, copy, additional

Review Notes also gains a new guidelines review type that flags content violating the editorial standards.

Helper functions in includes/helpers.php:

  • get_content_guidelines() — retrieve guidelines (optionally filtered by category)
  • format_content_guidelines_for_prompt() — format guidelines for prompt injection

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code (Opus 4.6 and Sonnet 4.6)
Used for: Initial planning and code implementation; finalization of implementation and tests were reviewed and edited by me.

Testing Instructions

  1. Start the local environment: npm run test:e2e:env:start
  2. Run the full test suite:
    • npm run test:php — runs unit/integration tests including Content_Guidelines_Test and Abstract_Ability_Guidelines_Test
    • npm run test:e2e — runs e2e tests including content-guidelines.spec.js
  3. Manual testing (without Gutenberg 22.7+): Open any post, use title generation, excerpt generation, or any other AI ability — verify they work normally without errors (graceful degradation when the wp_content_guideline CPT doesn't exist).
  4. Manual testing (with Gutenberg 22.7+): If the Content Guidelines feature is available, create a content guideline post with site/copy/images categories, then verify AI-generated content reflects those guidelines in the prompt (inspect via debug logging or network requests).
Open WordPress Playground Preview

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 1, 2026

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jeffpaul <[email protected]>
Co-authored-by: saarnilauri <[email protected]>
Co-authored-by: dkotter <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: justlevine <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 1, 2026

Codecov Report

❌ Patch coverage is 93.57143% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.72%. Comparing base (ae75c40) to head (8a6137a).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines Patch % Lines
includes/Abilities/Image/Generate_Image.php 57.14% 3 Missing ⚠️
includes/Abilities/Review_Notes/Review_Notes.php 40.00% 3 Missing ⚠️
includes/Services/Guidelines.php 96.70% 3 Missing ⚠️
Additional details and impacted files
@@              Coverage Diff              @@
##             develop     #359      +/-   ##
=============================================
+ Coverage      66.90%   67.72%   +0.81%     
- Complexity       907      959      +52     
=============================================
  Files             59       60       +1     
  Lines           4699     4836     +137     
=============================================
+ Hits            3144     3275     +131     
- Misses          1555     1561       +6     
Flag Coverage Δ
unit 67.72% <93.57%> (+0.81%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@saarnilauri saarnilauri marked this pull request as draft April 1, 2026 10:14
@saarnilauri saarnilauri marked this pull request as draft April 1, 2026 10:14
@jeffpaul
Copy link
Copy Markdown
Member

@saarnilauri let us know when this is ready again for review/testing, thanks!

@saarnilauri
Copy link
Copy Markdown
Contributor Author

I have updated the post type to match the new slug but keep the legacy slug for < 23.0

While the current code works, we need to watch the Gutenberg release process and adjust support as needed.

The support for the guideline taxonomy is now baked in.

  1. Currently doesn't work for me. Doing some quick debugging, it appears the Content Guidelines post type stores in a draft state so our query doesn't work. Not sure if there's something I need to do to get those published or if this is expected

Gutenberg's REST controller saves new guideline posts as 'draft' by default. Our query only matched 'publish', silently returning no guidelines for the common case. Now accept both statuses (matching Gutenberg's own get_guidelines_post() behavior) and order by date so the most recent guideline wins when multiple posts exist.

  1. We've added a few new Abilities since this was opened and we should look to add guidelines support to those: Content Classification and Meta Descriptions

These new abilities have now guidelines injected to them.

So, everything is ready for your review.

The not yet implemented PR WordPress/gutenberg#77230 in the Gutenberg, requires a larger refactoring and we need to keep tracking it's progress. It might be better to create a new issue related to it.

@saarnilauri saarnilauri requested a review from dkotter April 17, 2026 07:37
Copy link
Copy Markdown
Collaborator

@dkotter dkotter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested and works well for me now. Left one comment about maybe waiting until Gutenberg 23.0 comes out before merging this, so we can just make that the minimum version we support. But otherwise this looks good to go, thanks for all the work here!

Comment thread includes/Services/Guidelines.php Outdated
jeffpaul
jeffpaul previously approved these changes Apr 21, 2026
Copy link
Copy Markdown
Member

@jeffpaul jeffpaul left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested copy and images guidelines and title generation and featured image generation resulted as expected.

@justlevine
Copy link
Copy Markdown
Contributor

maybe waiting until Gutenberg 23.0 comes out before merging this, so we can just make that the minimum version we support. But otherwise this looks good to go

Just passing by and saw this. Are we picking up a new dependency in the form of the Gutenberg plugin or is there some availability checking that I'd see if I actually pulled this PR down to review more deeply?

@dkotter
Copy link
Copy Markdown
Collaborator

dkotter commented Apr 21, 2026

maybe waiting until Gutenberg 23.0 comes out before merging this, so we can just make that the minimum version we support. But otherwise this looks good to go

Just passing by and saw this. Are we picking up a new dependency in the form of the Gutenberg plugin or is there some availability checking that I'd see if I actually pulled this PR down to review more deeply?

It is the latter. We are not including Gutenberg as a dependency within the plugin. This is a progressive enhancement that only runs if the right version of Gutenberg is installed and if the Guidelines experiment is turned on.

@saarnilauri
Copy link
Copy Markdown
Contributor Author

Ready for the review

@jeffpaul jeffpaul requested a review from dkotter April 22, 2026 16:10
Copy link
Copy Markdown
Collaborator

@dkotter dkotter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good now. Looks like the meta keys they use were also updated in the latest version of Gutenberg so I had to push a fix for those (going from _content_guidelines to just _guidelines. Also had some flaky E2E tests not related to this PR I fixed up.

Thanks for all the work here @saarnilauri!

@dkotter dkotter merged commit 4c9699f into WordPress:develop Apr 22, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Integrate Content Guidelines into generation and refinement workflows

5 participants