Does the front end need its own AGENTS.md?
Yes. Put a nested AGENTS.md in the frontend folder, generated from the Next.js template, so the agent applies React rules there and WordPress rules in the plugin.
WordPress used as a headless CMS, with content served over the REST API or WPGraphQL to a separate front end. The rules keep custom code in a plugin, apply WordPress security functions consistently, and protect the database.
# AGENTS.md
Project: headless-wp. WordPress as a headless CMS: custom plugin in PHP, content served over the REST API and WPGraphQL to a Next.js front end.
This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.
## Stack
- Languages: TypeScript, PHP
- Framework: WordPress
- Database: MySQL / MariaDB
- Hosting: Docker on your own servers
- Tests: PHPUnit
- Package manager: Composer
## Commands
Run these from the repository root.
- Install dependencies: `composer install`
- Run locally: `npx wp-env start`
- Run all tests: `npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit`
- Run one test file: `npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit --filter=test_name`
- Lint: `vendor/bin/phpcs`
- Type-check: `vendor/bin/phpstan analyse`
- Format: `vendor/bin/phpcbf`
## Project layout
- `wp-content/plugins/site-core/`: The custom plugin: post types, fields, REST routes
- `wp-content/themes/headless/`: A minimal theme (the site is rendered elsewhere)
- `frontend/`: The Next.js front end that reads the API
- `.wp-env.json`: Local WordPress environment config
## Code style
- Indent with tabs. Never spaces for indentation.
- Match the style and patterns of the surrounding code, even where you would personally choose differently.
- Never swallow an error. Handle it where you can act on it, or rethrow it with context about what failed.
- Commit messages follow Conventional Commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, with an imperative summary under 72 characters.
## Working rules
- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`, deleting cloud resources) without explicit approval.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
## Product constraints
- Validate all input at the boundary, use parameterized queries only, and treat every external payload as untrusted.
- Public pages must render their main content as HTML on the server, with a unique title, meta description and one h1.
## Project-specific notes
- All custom PHP goes in the `site-core` plugin; never edit WordPress core or third-party plugins.
- Follow the WordPress Coding Standards (tabs, Yoda conditions); `phpcs` must pass.
- Every custom REST route sets a real `permission_callback`; never `__return_true` for routes that write or expose private data.
- Sanitize input (`sanitize_text_field`, `absint`) and escape output (`esc_html`, `esc_url`, `wp_kses_post`).
- Use `$wpdb->prepare()` for every query with variables.
- Prefix all functions, hooks, options and post types with `site_core_` to avoid collisions.
- Never run `wp db reset`, `wp search-replace` or other database-wide WP-CLI commands without approval.
## Project phase
This project is in active development. Follow the patterns that already exist; consistency beats novelty.
# CLAUDE.md
@AGENTS.md
## Claude Code
- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
# GEMINI.md
@./AGENTS.md
## Gemini CLI
- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.
# Copilot instructions
Project: headless-wp. WordPress as a headless CMS: custom plugin in PHP, content served over the REST API and WPGraphQL to a Next.js front end.
The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.
## Stack
- Languages: TypeScript, PHP
- Framework: WordPress
- Database: MySQL / MariaDB
- Hosting: Docker on your own servers
- Tests: PHPUnit
- Package manager: Composer
## Commands
- Install dependencies: `composer install`
- Run locally: `npx wp-env start`
- Run all tests: `npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit`
- Run one test file: `npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit --filter=test_name`
- Lint: `vendor/bin/phpcs`
- Type-check: `vendor/bin/phpstan analyse`
- Format: `vendor/bin/phpcbf`
## Working rules
- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`, deleting cloud resources) without explicit approval.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---
# Project rules
The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.
Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.
Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).
These are the exact files the generator writes for this preset. Change any command or rule in the generator and download your own set.
The preset describes a WordPress as a headless CMS: custom plugin in PHP, content served over the REST API and WPGraphQL to a Next.js front end. Its AGENTS.md is 48 non-empty lines with 7 exact commands, 4 key directories, and 7 stack-specific rules on top of the shared working rules.
composer install, npx wp-env start, npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit, npx wp-env run tests-cli --env-cwd=wp-content/plugins/site-core vendor/bin/phpunit --filter=test_name, vendor/bin/phpcs, vendor/bin/phpstan analyse, vendor/bin/phpcbf.wp-content/plugins/site-core/, wp-content/themes/headless/, frontend/, .wp-env.json.Changes to WordPress core or a vendor plugin vanish on the next update, usually silently. Agents patch wherever the bug appears; the rule sends every change to the project plugin.
WordPress warns when a route omits it, and agents often satisfy the warning with __return_true, making a private endpoint public.
WordPress offers a function for each data type. Agents writing generic PHP skip them, which is the root of most plugin vulnerabilities.
search-replace across serialized data can corrupt a site in seconds, and backups are not always recent.
site-core plugin; never edit WordPress core or third-party plugins.phpcs must pass.permission_callback; never __return_true for routes that write or expose private data.sanitize_text_field, absint) and escape output (esc_html, esc_url, wp_kses_post).$wpdb->prepare() for every query with variables.site_core_ to avoid collisions.wp db reset, wp search-replace or other database-wide WP-CLI commands without approval.Want different commands or rules? Load this preset into the generator, change anything, and download your own set.
AGENTS.md is read directly by Codex, Cursor, Windsurf, Cline, Zed and Jules, and by GitHub Copilot's cloud agent, code review and CLI. Claude Code reads it through the generated CLAUDE.md, and Gemini CLI through GEMINI.md. See the compatibility table for details, last verified 2026-11-13.
All presets are on the stacks page.
Yes. Put a nested AGENTS.md in the frontend folder, generated from the Next.js template, so the agent applies React rules there and WordPress rules in the plugin.
Either works. The template mentions both; delete the one you do not use in the notes so the agent does not mix them.
The WordPress PHP coding standards require tabs for indentation, and phpcs enforces it.
Yes. Copy them into any project, commercial or not, without attribution. They are a starting point: adjust the commands and rules to match your repository.
You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.
F12, or Cmd+Option+I on a Mac, and select the Network tab.Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.