385 lines
14 KiB
Markdown
385 lines
14 KiB
Markdown
# 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**
|