Headless and WPGraphQL

When to use it

Build, debug or review decoupled WordPress with WPGraphQL: schema exposure, draft and preview access, authentication, query limits, Smart Cache and persisted queries, and webhook-driven frontend revalidation. Plain REST routes and ACF storage design belong to the sibling skills.

Boundaries and hand-offs

REST route design and permissions to wp-devkit-rest-api-development; ACF storage, keys and migrations to wp-devkit-acf-and-content-modeling; reachable XSS/authorization/SSRF defects to wp-devkit-security-review; slow queries and object cache tuning to wp-devkit-performance-review; pipeline and deploy mechanics to wp-devkit-ci-cd-and-release-engineering; Gutenberg block output to wp-devkit-block-development.

Ask Claude

With the plugin loaded, start a read-only review of a bounded target:

/wp-devkit:headless-review <target-path>

The short form /wp-devkit:headless requests a quick scan.

Ask Codex, ChatGPT or Antigravity

Name the installed skill and keep the request bounded. Replace the target with your files or journey.

$wp-devkit-headless-and-wpgraphql
Review the target without editing files.
Read the project instructions and the skill's engineering contract first.
Separate confirmed findings from candidates and state the evidence and checks you could not run.

What it covers

The agent loads only the reference that matches the task:

• caching-revalidation-and-webhooks.md : read for cache layers, Smart Cache, route mapping, webhook sender/receiver, Next.js revalidation.
• contract-testing-and-operations.md : read for schema snapshots, frontend coupling, WP front-end redirects, observability and rollout.
• preview-and-authentication.md : read for auth methods, preview flow, CORS and boundary tests.
• wpgraphql-schema-and-limits.md : read for exposure, registration, authorization model, query limits and resolver cost.

How a review runs

1. Follow one rendered route back to its query document, resolver and content model. Keep the schema names consumers already use.
2. Compare anonymous, low-privilege and preview-credential reads of published, draft, private, password-protected, scheduled and trashed content. A hidden frontend field does not protect an origin resolver.
3. Trace the preview path: link generation, secret/token validation, redirect target, credential location, asPreview use and cache partition.
4. Check endpoint settings (introspection, depth, batch limit, connection maximum, debug mode, endpoint restriction) against the exposure of the site. Measure the cost of a worst-case query on staging before calling it a risk.
5. For caching, name the freshness owner of each layer and the event that invalidates it; map content changes (publish, rename, unpublish, scheduled, term, menu) to affected routes.
6. Check webhook authentication (signature over raw body plus timestamp), replay handling, retries and visibility of failures.
7. Report the visibility and freshness boundary with the evidence gathered. Do not trigger rebuilds, purges or revalidation during review. Insufficient evidence is a valid outcome (no staging, no frontend access, unknown CDN behavior): state what is unverified and the check that settles it.

What you get back

Review: result and reviewed scope first. Each confirmed finding: severity per the contract, file:line, actor, trigger, reachable path, impact, confidence, minimal fix, regression test. Candidates and unverified items in a separate list.

Implementation: changed boundaries, schema or contract changes (additive or breaking), commands run with exit status, checks not run, residual risk, rollback.

Where to go next

Use review to fix for a bounded implementation and Doctor and reports for environment and evidence tooling.