Skip to content

Instantly share code, notes, and snippets.

@lukecav

lukecav/AGENTS.MD

Created September 15, 2025 21:07
Show Gist options
  • Save lukecav/88c12adfe901e6967958a28bd100c659 to your computer and use it in GitHub Desktop.
Save lukecav/88c12adfe901e6967958a28bd100c659 to your computer and use it in GitHub Desktop.
Download ZIP
AGENTS.MD — Codex Playbook for Building a WordPress Plugin
Raw
AGENTS.MD

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

plugin-name/
├─ plugin-name.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: , 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 <slug>. 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
/**
 * 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

# 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment