[Epic] wp-dev-tools — feed the coding agent live runtime data (Query Monitor telemetry + Core Web Vitals over MCP)

[Adi-ty]

Summary

Propose rtcamp/wp-dev-tools: an optional, dev-only package (chosen during scaffolding) that gives a coding agent — Claude Code or any MCP client — live runtime data it can't get from the code alone: what queries ran, what errored, what's slow, and which Core Web Vitals are poor and why. The agent already has the code and does the reasoning; dev-tools hands it the runtime truth, with the real file:line.

The proven seed already exists: the Query Monitor → telemetry → Abilities API → MCP module on rtcamp/wp-framework's feature/telemetry-abilities branch (PR rtCamp/wp-framework#45, idea #40) — the profile → fix → prove loop works today.

Planning/discussion issue. Nothing is built or moved yet; PR #45 stays as-is.

What goes where

Repo	Role
wp-dev-tools (new, require-dev, dev-only)	The package: Telemetry module, Core Web Vitals module, read-only diagnostic abilities, and the dev config it ships (.mcp.json, dev .wp-env.json keys).
wp-framework	Unchanged. dev-tools reuses its existing Registrable / Loader / AbstractModule contracts.
wp-tooling (this repo)	One opt-in scaffold: on init, offer "enable dev tools?"; if yes, add wp-dev-tools to require-dev and drop .mcp.json + the dev .wp-env.json keys.

How it reaches the coding agent (Abilities API → MCP)

Each diagnostic is an ability — a named function with an input/output JSON schema and a permission_callback — registered through the core Abilities API (wp_register_ability()). The only extra step to expose one is flagging meta.mcp.public = true.

1. The official WordPress/mcp-adapter plugin runs in the dev environment (installed via .wp-env.json).
2. It auto-exposes every ability marked meta.mcp.public = true as an MCP tool — no custom MCP server to write.
3. The project ships a .mcp.json; the coding agent connects over STDIO (through wp-env's CLI container) and sees the abilities as callable tools.

The loop in practice: the agent calls profile-url on a slow page → get-telemetry returns the duplicate queries with the real file:line → the agent opens that file and fixes it → compare-requests proves the query count dropped. Same shape for CWV: get-web-vitals returns "LCP element = hero image, blocked by 12 duplicate queries in inc/Hero.php:42."

What dev-tools ships

All abilities are read-only, hard-gated to local + dev-mode, and return host-translated file:line so the agent opens the exact source.

Telemetry (relocated from PR #45)

Built on Query Monitor: each request is captured, normalized, and kept in a small per-site ring buffer, then surfaced read-only through these abilities.

• list-requests — recent captures with headline metrics
• get-telemetry — full normalized request: DB queries (duplicate/slow + backtrace), PHP errors, HTTP calls, assets, timing/memory
• profile-url — fresh multi-sample capture of a same-site URL
• compare-requests — before/after deltas to prove a fix

Core Web Vitals (exposed via abilities)

• A tiny web-vitals (attribution build) snippet, enqueued behind the dev gate, beacons LCP / INP / CLS plus the offending element to a dev route and stores it on the matching telemetry record.
• get-web-vitals — returns the field metrics + attribution for a URL/request, correlated with the server telemetry (e.g. "LCP element = hero image; TTFB = 12 duplicate queries in inc/Hero.php:42").
• analyze-cwv (later) — lab data via PSI/Lighthouse for a URL (PSI key declared as a secret, never hardcoded).

More diagnostic abilities (as they prove useful)

• list-duplicate-queries / list-slow-queries — N+1s and >500ms queries with stacks
• check-autoload-bloat — oversized / orphaned autoload='yes' options + latency impact
• cron-health — overdue / duplicate scheduled events
• get-hooks-fired, get-http-calls, cache-stats, deprecation-notices — further read-only signals

Opt-in scaffold (this repo's piece)

wp-dev-tools owns a dev/tools scaffold (+ index.json); wp-tooling adds the repo to scaffolds/sources.json once. It's a feature{} (config_key: "dev-tools") that adds rtcamp/wp-dev-tools to require-dev (with the VCS repositories entry) and writes .mcp.json + the dev .wp-env.json keys. /init offers it; toggle later via wp-tooling features --enable/--disable dev-tools. The engine prints the install command rather than running it. A production (--no-dev) install simply won't have it.

Suggested build order

1. Stand up the wp-dev-tools repo and move the PR chore(deps): bump fast-uri from 3.1.2 to 3.1.4 #45 telemetry tree into it (re-namespaced); port its tests.
2. Add the Core Web Vitals module and the get-web-vitals ability, correlated onto telemetry records.
3. Add the dev/tools opt-in scaffold here in wp-tooling + the /init prompt.
4. Add the extra read-only diagnostic abilities as they prove useful; dogfood via features-plugin-skeleton and telemetry-test-plugin.

Open questions

• WP version floors (Abilities API 6.9 / AI Client 7.0) and which MCP Adapter version to pin in .wp-env.json.
• CWV lab/history source (PSI vs CrUX API).

---

References: rtCamp/wp-framework#45, rtCamp/wp-framework#40