# AGENTS.md — Codex Playbook for Building a WordPress Plugin

> A precise, no-nonsense blueprint for orchestrating autonomous and semi-autonomous coding agents to plan, scaffold, implement, test, and ship a production‑grade WordPress plugin.

---

## 0) Purpose & Scope

This document defines the **agents**, **tools**, **workflows**, **constraints**, and **acceptance criteria** for using an agentic coding system ("Codex") to create and maintain a WordPress plugin. It is optimized for **real, shippable code**, not demos.

Outcomes:

* A production‑ready WordPress plugin following WP Coding Standards.
* Clean, testable PHP, JS (React) admin UI, i18n, security hardening, and CI.
* Repeatable pipelines from idea → release (with versioning & changelog).

---

## 1) High-Level Task Graph

1. **Discovery & Planning**
   Requirements intake → constraints → feature list → milestones → risk register.
2. **Scaffolding**
   Repo init → plugin headers → file structure → build tooling.
3. **Implementation**
   Core PHP features → admin screens (React) → REST endpoints → WP‑CLI.
4. **Quality & Hardening**
   PHPCS/WPCS → unit/integration tests → e2e (Playwright) → security checks.
5. **Docs & Demos**
   README, inline docs, usage guide, screenshots/GIFs, sample data.
6. **Release**
   Semantic versioning → tagged release → changelog → release assets.
7. **Maintenance**
   Issue triage → patch releases → perf audits → dependency updates.

---

## 2) Agents & Ownership

### A. PlannerAgent (Lead)

* **Goal:** Convert business requirements into a concrete implementation plan.
* **Inputs:** Product brief, constraints, compatibility targets.
* **Outputs:** `PLAN.md` with MVP scope, milestones, risks, success metrics.
* **Key checks:** Feasibility, risk mitigation, timeline, test strategy alignment.

### B. ScaffolderAgent

* **Goal:** Create plugin skeleton and development toolchain.
* **Outputs:**

  * `plugin-name/plugin-name.php` with proper headers
  * `src/` (PHP), `includes/`, `assets/`, `admin/`, `languages/`
  * `composer.json`, `package.json`, `webpack.config.js` or `vite.config.ts`
  * `phpcs.xml`, `.editorconfig`, `.gitattributes`, `.gitignore`
  * `README.md`, `CHANGELOG.md`, `LICENSE`
* **Standards:** PSR-4 autoloading, WPCS ruleset, PHPCS baseline if needed.

### C. BackendAgent (PHP)

* **Goal:** Implement core plugin features with hooks, filters, REST, cron, WP‑CLI.
* **Constraints:**

  * **Security first:** Nonces, `current_user_can`, prepared SQL, sanitize/escape.
  * **Compatibility:** PHP 7.4–8.3, WP 6.1+, multisite-safe where relevant.
* **Artifacts:** `src/` classes, `includes/`, `uninstall.php`, activation/deactivation hooks.

### D. FrontendAgent (Admin UI)

* **Goal:** Build admin screens with React + WP Scripts (or Vite w/ WP deps externals).
* **Artifacts:** `admin/` React app, enqueue via `wp_enqueue_script/style`, settings pages, components, forms with wp.data/wc.data if Woo, and REST integration.

### E. APIGatewayAgent (REST & Webhooks)

* **Goal:** Define REST routes, permissions callbacks, and (optionally) webhooks.
* **Checks:** Nonces or auth tokens, caps mapping, rate limiting where applicable.

### F. CLIAgent (WP‑CLI)

* **Goal:** Add WP‑CLI commands for power users & CI automation.
* **Artifacts:** `src/CLI/Commands.php` with subcommands, argument validation, exit codes.

### G. TestAgent (QA)

* **Goal:** Unit, integration (WP core bootstrap), e2e (Playwright) with headless Chromium.
* **Artifacts:** `tests/phpunit.xml`, `tests/`, GitHub Actions CI templates.

### H. SecPerfAgent (Security & Performance)

* **Goal:** Threat modeling, perf budgets, db/indexing strategy, cache headers.
* **Checks:** Nonce coverage, XSS/CSRF/SQLi audit, escaping map, memory/time profiles.

### I. DocsAgent

* **Goal:** Build crisp docs: README, usage, configuration, troubleshooting, examples.

### J. ReleaseAgent

* **Goal:** Version bump, changelog, Git tag, GitHub Release, packaged zip artifact.

---

## 3) Repository Structure

```
logo-soup/
├─ logo-soup.php                 # Main plugin file (headers + bootstrap)
├─ composer.json                   # PSR-4 autoload, dev tools
├─ package.json                    # Build scripts, lint, test
├─ vite.config.ts | webpack.config.js
├─ phpcs.xml                       # WPCS rules
├─ phpstan.neon                    # Static analysis (level 6–max)
├─ .editorconfig / .gitattributes / .gitignore
├─ README.md / CHANGELOG.md / LICENSE / CONTRIBUTING.md
├─ src/                            # PHP business logic (PSR-4)
│  ├─ Admin/                       # Settings pages, controllers
│  ├─ REST/                        # Endpoints & permissions
│  ├─ CLI/                         # WP-CLI commands
│  ├─ Cron/                        # Scheduled events
│  └─ Infrastructure/              # Services, DI container, logger
├─ includes/                       # Legacy-style helpers (thin shims only)
├─ admin/                          # React app (built → dist)
│  ├─ src/                         # TS/JS, components
│  └─ dist/                        # Built assets (git-ignored)
├─ assets/                         # CSS, images, icons
├─ languages/                      # .pot and translations
├─ tests/
│  ├─ phpunit.xml.dist             # Bootstrapped with WP test suite
│  ├─ php/                         # Unit/integration tests
│  └─ e2e/                         # Playwright tests
└─ uninstall.php                   # Hard removal of options/data when required
```

---

## 4) Coding Standards & Quality Gates

* **PHP:** PHPCS with **WordPress Coding Standards** (`wpcs`), PHPStan level ≥ 6.
* **JS/TS:** ESLint (airbnb/base), TypeScript strict mode where used, Prettier.
* **Commits:** Conventional Commits.
* **Branches:** `main` (stable), `develop`, feature branches → PRs.
* **CI Required Checks:** lint, static analysis, unit/integration tests, e2e (smoke), `composer validate`. No merge to `main` without green.

---

## 5) Security Model

* Enforce **capability checks** on every privileged action. Prefer granular custom caps.
* **Nonces** on all state‑changing forms/requests; **verify before mutate**.
* Always **sanitize input** (`sanitize_text_field`, `sanitize_key`, `absint`, custom) and **escape output** (`esc_html`, `esc_attr`, `wp_kses`).
* **DB access:** `wpdb->prepare`, avoid dynamic table names; consider custom tables with schema migrations when needed.
* **Files:** Validate MIME types/size, use WP Filesystem API.
* **Settings:** Use `register_setting` with `sanitize_callback`.
* **Secrets:** Never commit secrets; use environment variables or WP constants via `.env` with `vlucas/phpdotenv` (optional).

---

## 6) Build & Tooling

**Composer dev deps (suggested):**

* `dealerdirect/phpcodesniffer-composer-installer`
* `squizlabs/php_codesniffer`
* `wp-coding-standards/wpcs`
* `phpstan/phpstan`
* `phpunit/phpunit`

**NPM dev deps (suggested):**

* `@wordpress/scripts` *or* `vite` + `@wordpress/dependency-extraction-webpack-plugin` equivalent via externals
* `typescript`, `eslint`, `prettier`, `playwright`

**Makefile (optional) targets:**

```
make setup       # composer install, npm install
make build       # build admin assets
make lint        # phpcs, eslint, phpstan
make test        # phpunit, e2e (smoke)
make zip         # generate distributable zip under ./dist
```

---

## 7) CI/CD (GitHub Actions templates)

* **php.yml:** matrix {php: \[7.4, 8.0, 8.1, 8.2, 8.3]}, run phpcs, phpstan, phpunit.
* **js.yml:** node LTS, run eslint, typecheck, build.
* **e2e.yml:** spin WP (wp-env/docker), run Playwright smoke on admin.
* **release.yml:** on tag `v*`, bump version in headers, generate zip, create release, attach artifact.

---

## 8) Implementation Checklists

### 8.1 Plugin Bootstrap

* [ ] Header with `Plugin Name`, `Version`, `Requires at least`, `Requires PHP`, `Text Domain`.
* [ ] Autoloader (Composer) + safe early exit if direct access.
* [ ] Activation/Deactivation hooks; network‑aware.
* [ ] Service container bootstrap (optional) for loose coupling.

### 8.2 Admin UI

* [ ] Single‑page admin screen registered via `add_menu_page`/`add_submenu_page`.
* [ ] Nonce embedded into page for REST mutations.
* [ ] `wp_enqueue_script` with dependencies (`wp-element`, `wp-components`, etc.).
* [ ] Accessible components, keyboard navigation, focus styles.

### 8.3 REST API

* [ ] `register_rest_route` with namespaced routes and `permission_callback`.
* [ ] Input validation and output normalization.
* [ ] Pagination and error shapes consistent.

### 8.4 Data Layer

* [ ] Options API with schema, or custom tables via dbDelta + migrations.
* [ ] Caching using transients or object cache; set TTLs.
* [ ] Background tasks via Action Scheduler or WP Cron when needed.

### 8.5 Internationalization (i18n)

* [ ] Load text domain, generate `.pot`.
* [ ] Wrap strings with translation functions, no string concatenation with HTML.

### 8.6 Uninstall

* [ ] `uninstall.php` handles irreversible deletion when user opts-in.

---

## 9) Prompts & Guardrails for Agents

**General guardrails** (apply to all agents):

* Prefer stable, framework‑agnostic PHP for plugin core; keep vendor size small.
* Follow WPCS; do not bypass lints without justification.
* Avoid over‑engineering; MVP first, extensibility second.
* Provide diffs/patches or exact file paths in outputs.
* Every change must include: rationale → code → tests → docs.

**Prompt scaffolds**:

* **PlannerAgent:**

  * *"Given this brief: `project-brief.md`, enumerate functional/non‑functional requirements, risks, milestones, metrics, and a phased MVP plan. Output `PLAN.md` with tables and a Gantt‑style milestone list."*

* **ScaffolderAgent:**

  * *"Generate a WordPress plugin skeleton named `logo-soup`. Include Composer (PSR‑4), Vite (or @wordpress/scripts), PHPCS (WPCS), PHPStan. Produce file tree and initial file contents. No placeholder TODOs—write minimal viable code."*

* **BackendAgent:**

  * *"Implement feature `<feature>` behind capability `<cap>`. Add actions/filters, sanitize/validate, and unit tests. Return diff with file paths. Include acceptance tests for edge cases."*

* **FrontendAgent:**

  * *"Create admin view `<view>` with React, using WP components. Implement controlled inputs, form validation, REST calls with nonce, and optimistic updates. Provide Playwright tests."*

* **APIGatewayAgent:**

  * *"Define REST endpoint `<method> /<ns>/<route>` with schema, permission callback respecting `<cap>`. Include unit tests for auth and validation failures."*

* **CLIAgent:**

  * *"Add WP‑CLI command `wp <ns> <cmd>` with flags `<flags>`. Validate args, handle errors gracefully, and return exit codes. Provide usage examples."*

* **TestAgent:**

  * *"Write PHPUnit tests for `<class>` with edge cases. Bootstrap WP test suite. Add Playwright test for `<user flow>`. Ensure CI green."*

* **ReleaseAgent:**

  * *"Prepare release `<version>`. Update plugin header + `readme.txt` stable tag, generate changelog (Conventional Commits), build zip, create Git tag and GitHub Release with assets."*

---

## 10) Acceptance Criteria (Definition of Done)

* ✅ Linting: PHPCS (WPCS) and ESLint pass with 0 errors.
* ✅ Tests: PHP unit/integration ≥ 80% critical path coverage; e2e smoke green.
* ✅ Security: Nonces, caps, sanitization/escaping verified; no direct SQL without prepare.
* ✅ Docs: README with install/usage, configuration, screenshots/GIFs; CHANGELOG.
* ✅ Release: Tagged semantic version; distributable zip attached to release.
* ✅ Performance: First meaningful paint in admin ≤ 2s on mid hardware; queries indexed.
* ✅ Accessibility: Admin UI meets WCAG AA basics (labels, contrast, keyboard nav).

---

## 11) Example: Minimal Plugin Header & Bootstrap

```php
<?php
/**
 * Plugin Name: Example Plugin
 * Description: Minimal bootstrap showing headers, autoloading, and safety guards.
 * Version: 0.1.0
 * Requires at least: 6.1
 * Requires PHP: 7.4
 * Author: Your Org
 * License: GPL-2.0-or-later
 * Text Domain: example-plugin
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

// Composer autoload (if present).
$autoload = __DIR__ . '/vendor/autoload.php';
if ( file_exists( $autoload ) ) {
	require_once $autoload;
}

// Bootstrap.
add_action( 'plugins_loaded', static function () {
	// Initialize services, hooks, etc.
} );
```

---

## 12) Local Dev Environments

* **wp-env (official):** Zero-config local WP; good for e2e.
* **Docker Compose:** MySQL + WP + phpMyAdmin; seed data via WP‑CLI.
* **Valet/Local/Lando:** Developer preference; ensure parity with CI PHP versions.

---

## 13) Release Engineering

* **Versioning:** `MAJOR.MINOR.PATCH`, align PHP headers and `readme.txt` `Stable tag`.
* **Dist:** Production build, vendor‑prefixed if shipping SDKs, no dev files.
* **SVN (wp.org) optional:** Mirror release using `svn cp` into `/tags/<version>`.

---

## 14) Risk Register (starter)

| Risk                 | Impact | Likelihood | Mitigation                                 |
| -------------------- | ------ | ---------- | ------------------------------------------ |
| WP Core API changes  | Medium | Low        | Pin compatibility, test on latest beta     |
| PHP 7.4 deprecations | Medium | Medium     | Polyfills, conditionals, CI matrix         |
| Admin UI bloat       | Medium | Medium     | Perf budgets, code splitting, audit        |
| Security regressions | High   | Low        | Threat model, security checklist, CI gates |

---

## 15) Contribution Guide (short)

* Fork + feature branch; keep PRs < 500 lines when possible.
* Add/adjust tests and docs with any functional change.
* Keep public API stable; mark internal APIs with `@internal`.
* Link issues to PRs; include before/after screenshots for UI.

---

## 16) Quickstart Commands

```bash
# 1) Setup
git init && git commit --allow-empty -m "chore: repo init"
composer install
npm install

# 2) Develop
npm run dev   # or: npm run start

# 3) Lint & test
composer phpcs
composer phpstan
npm run lint
npm run test

# 4) Build & package
npm run build
make zip  # or custom script to produce ./dist/plugin-name-vX.Y.Z.zip
```

---

**End of AGENTS.md**