WordPress AI Client - Coding Agent Guide

Project Overview

An AI client and API for WordPress to communicate with any generative AI models of various capabilities using a uniform API. Built on top of the PHP AI Client, it provides a WordPress-native Prompt Builder, an Admin Settings Screen for credentials, automatic credential wiring, a PSR-compliant HTTP client, and a client-side JavaScript API.

Commands & Scripts

```
composer lint
```
: Lints the PHP code (PHPCodeSniffer and PHPStan).
```
composer phpcs
```
: Runs PHPCodeSniffer on the PHP code.
```
composer phpstan
```
: Runs PHPStan on the PHP code.
```
npm run build
```
: Builds the JavaScript assets.
```
npm run format-js
```
: Formats the JavaScript code using Prettier.
```
npm run lint-js
```
: Lints the JavaScript code.
```
npm run lint-php
```
: Lints the PHP code using Composer inside the
```
wp-env
```
environment.
```
npm run test-php
```
: Runs PHPUnit tests with single site config inside the
```
wp-env
```
environment.
```
npm run test-php-multisite
```
: Runs PHPUnit tests with Multisite config inside the
```
wp-env
```
environment.

Note: In order to follow the WordPress code style in JavaScript, the project uses a WordPress-specific fork of Prettier (

wp-prettier

) under the hood.

Coding Standards & Compatibility Constraints

This project adheres to the WordPress Coding Standards with specific exceptions for PSR-4 autoloading (file names match class names). More details about coding and documentation standards are outlined in the

CONTRIBUTING.md

file. Any agent working on this project MUST read and follow the guidelines in that file before starting any work.

PHP Version: Code must be compatible with PHP 7.4.
Code Style: All code (PHP and JavaScript) must be compliant with the WordPress Coding Standards.
Type Hints: Use explicit type hints for parameters, return values, and properties where supported by PHP 7.4.

Core Principles

Uniform API: Provide a consistent interface for interacting with various AI providers.
WordPress Native: Integrate deeply with WordPress APIs (Abilities API, HTTP API, Settings API).
Security: Restrict access to powerful features (like arbitrary prompt generation via REST API) using capabilities (
```
prompt_ai
```
).
Standards Compliance: Adhere to PSR standards where applicable (e.g., HTTP Client) while maintaining WordPress compatibility.

Project Architecture Overview

The project consists of three main layers:

PHP SDK (
includes/
): The core logic, built on
```
wordpress/php-ai-client
```
. It handles prompt building, request execution, and response parsing. It also manages API credentials and integrates with WordPress core.
REST API (
includes/REST_API/
): Exposes the AI capabilities to the client-side. It handles authentication and validation.
JavaScript SDK (
src/
): A client-side library that mirrors the PHP Prompt Builder interface, communicating with the backend via the REST API.

Directory Structure

```
build/
```
: Compiled JavaScript and CSS assets.
```
includes/
```
: Main PHP source files (PSR-4 autoloaded).
- ```
API_Credentials/
```
  : Manages API keys and settings.
- ```
Builders/
```
  : Prompt builder implementations.
- ```
Capabilities/
```
  : Capability management.
- ```
HTTP/
```
  : HTTP client integrations.
- ```
REST_API/
```
  : REST API controllers.
```
src/
```
: Source TypeScript/JavaScript files.
```
tests/
```
: PHPUnit tests.
- ```
phpunit/
```
  : Test suite configuration and test files.
```
vendor/
```
: Composer dependencies.

Git Repo

The main branch for this project is called "trunk".

Agent Guidelines

DO: Read
```
CONTRIBUTING.md
```
before writing any code.
DO: Ensure all PHP code is compatible with PHP 7.4.
DO: Use
```
wp_enqueue_script( 'wp-ai-client' )
```
to load the JS SDK.
DO: Add unit tests for new PHP functionality in
```
tests/phpunit/tests/
```
.
DO: Run
```
npm run lint-php
```
and
```
npm run test-php
```
before submitting changes.
DON'T: Use PHP 8.0+ features (e.g., constructor property promotion, union types, match expressions, enums).
DON'T: Create new top-level directories without a strong reason.
DON'T: Hardcode API credentials.

Common Pitfalls

Ignoring the Fluent API: While the traditional API is available, the fluent API is the preferred way for implementers to use the client. Avoid writing complex, nested method calls when the fluent API provides a cleaner alternative.
Duplicating Interface Documentation: Manually writing PHPDoc descriptions for methods that implement an interface is a common pitfall. The
```
{@inheritDoc}
```
tag should be used instead to inherit the documentation from the interface.
Missing Capability Checks in REST: Exposing AI generation endpoints without proper capability checks. Always ensure
```
prompt_ai
```
capability is checked for privileged operations.

WordPress AI Client - Coding Agent Guide

Project Overview

Commands & Scripts

```
composer lint
```
: Lints the PHP code (PHPCodeSniffer and PHPStan).
```
composer phpcs
```
: Runs PHPCodeSniffer on the PHP code.
```
composer phpstan
```
: Runs PHPStan on the PHP code.
```
npm run build
```
: Builds the JavaScript assets.
```
npm run format-js
```
: Formats the JavaScript code using Prettier.
```
npm run lint-js
```
: Lints the JavaScript code.
```
npm run lint-php
```
: Lints the PHP code using Composer inside the
```
wp-env
```
environment.
```
npm run test-php
```
: Runs PHPUnit tests with single site config inside the
```
wp-env
```
environment.
```
npm run test-php-multisite
```
: Runs PHPUnit tests with Multisite config inside the
```
wp-env
```
environment.

Note: In order to follow the WordPress code style in JavaScript, the project uses a WordPress-specific fork of Prettier (

wp-prettier

) under the hood.

Coding Standards & Compatibility Constraints

CONTRIBUTING.md

file. Any agent working on this project MUST read and follow the guidelines in that file before starting any work.

PHP Version: Code must be compatible with PHP 7.4.
Code Style: All code (PHP and JavaScript) must be compliant with the WordPress Coding Standards.
Type Hints: Use explicit type hints for parameters, return values, and properties where supported by PHP 7.4.

Core Principles

Uniform API: Provide a consistent interface for interacting with various AI providers.
WordPress Native: Integrate deeply with WordPress APIs (Abilities API, HTTP API, Settings API).
Security: Restrict access to powerful features (like arbitrary prompt generation via REST API) using capabilities (
```
prompt_ai
```
).
Standards Compliance: Adhere to PSR standards where applicable (e.g., HTTP Client) while maintaining WordPress compatibility.

Project Architecture Overview

The project consists of three main layers:

PHP SDK (
includes/
): The core logic, built on
```
wordpress/php-ai-client
```
. It handles prompt building, request execution, and response parsing. It also manages API credentials and integrates with WordPress core.
REST API (
includes/REST_API/
): Exposes the AI capabilities to the client-side. It handles authentication and validation.
JavaScript SDK (
src/
): A client-side library that mirrors the PHP Prompt Builder interface, communicating with the backend via the REST API.

Directory Structure

```
build/
```
: Compiled JavaScript and CSS assets.
```
includes/
```
: Main PHP source files (PSR-4 autoloaded).
- ```
API_Credentials/
```
  : Manages API keys and settings.
- ```
Builders/
```
  : Prompt builder implementations.
- ```
Capabilities/
```
  : Capability management.
- ```
HTTP/
```
  : HTTP client integrations.
- ```
REST_API/
```
  : REST API controllers.
```
src/
```
: Source TypeScript/JavaScript files.
```
tests/
```
: PHPUnit tests.
- ```
phpunit/
```
  : Test suite configuration and test files.
```
vendor/
```
: Composer dependencies.

Git Repo

The main branch for this project is called "trunk".

Agent Guidelines

DO: Read
```
CONTRIBUTING.md
```
before writing any code.
DO: Ensure all PHP code is compatible with PHP 7.4.
DO: Use
```
wp_enqueue_script( 'wp-ai-client' )
```
to load the JS SDK.
DO: Add unit tests for new PHP functionality in
```
tests/phpunit/tests/
```
.
DO: Run
```
npm run lint-php
```
and
```
npm run test-php
```
before submitting changes.
DON'T: Use PHP 8.0+ features (e.g., constructor property promotion, union types, match expressions, enums).
DON'T: Create new top-level directories without a strong reason.
DON'T: Hardcode API credentials.

Common Pitfalls

Ignoring the Fluent API: While the traditional API is available, the fluent API is the preferred way for implementers to use the client. Avoid writing complex, nested method calls when the fluent API provides a cleaner alternative.
Duplicating Interface Documentation: Manually writing PHPDoc descriptions for methods that implement an interface is a common pitfall. The
```
{@inheritDoc}
```
tag should be used instead to inherit the documentation from the interface.
Missing Capability Checks in REST: Exposing AI generation endpoints without proper capability checks. Always ensure
```
prompt_ai
```
capability is checked for privileged operations.

WordPress AI Client - Coding Agent Guide

WordPress AI Client - Coding Agent Guide

Project Overview

Commands & Scripts

Coding Standards & Compatibility Constraints

Core Principles

Project Architecture Overview

Directory Structure

Git Repo

Agent Guidelines

Common Pitfalls

Related Skills

Markdown Converter

Nano Banana Pro

1password

WordPress AI Client - Coding Agent Guide

Project Overview

Commands & Scripts

Coding Standards & Compatibility Constraints

Core Principles

Project Architecture Overview

Directory Structure

Git Repo

Agent Guidelines

Common Pitfalls