AI-Assisted Development in WP Rig

WP Rig is built to be developed with AI agents, not just by humans. Every feature ships with machine-readable context, every scaffold emits agent documentation, and the toolchain verifies agent work the same way it verifies human work. This post maps the agentic surface of the framework: what exists, where it lives, and how the pieces connect.

Agent onboarding (ai:setup)

A new agent session starts with a state check, not exploration — that’s the token-saving protocol:

  • .ai/agent-state.md records whether onboarding is complete; a completed state means the agent proceeds directly to your task.
  • npm run ai:setup configures the workspace for a specific agent: it copies the core instructions into the agent’s own rules file (GEMINI.md, CLAUDE.md, .cursorrules, and friends — 12 generated configs, all gitignored) and downloads the headless Playwright Chromium build so visual tools work immediately.
  • Generated configs stay synchronized with a compressed master guidelines file (~3.2KB, 55%+ smaller than verbose instructions) so background token cost stays low.

Project memory: rules, directions, skills

  • .ai/developer-directions.md — your house rules: aesthetic preferences, constraints, do/don’t. Agents must follow it.
  • .ai/PROJECT_RULES.md — a self-learning memory. Agents fill in the discovered theme configuration and design system on first contact; future sessions read it instead of re-deriving.
  • .ai/skills/ — 25+ specialized playbooks (architecture, styles, e2e-testing, bake-sync, component-registry, theme-review, …). Components added from the registry link their own SPEC.md/SKILL.md here automatically.

The documentation MCP server

npm run mcp starts a Model Context Protocol server that gives connected agents direct access to WP Rig’s documentation — so an agent can query the framework docs instead of guessing or burning context on file exploration. Point your MCP-capable tool at the server and the docs become tools.

Verification: screenshots and measurement

Agents that change UI must verify their work. WP Rig standardizes a two-tier, measurement-first loop (documented in the styles skill):

  • Tier 1 — semantic measurement (cheap): npm run inspect -- --url "/page" --selector ".el1, .el2" returns exact bounding boxes and computed styles. Batch viewports, no screenshots.
  • Tier 2 — aesthetic verification (fallback): screenshots only when geometry can’t express the issue: npm run inspect -- --selector ".el" --screenshot, or regression baselines via npm run test:e2e:screenshot.
  • Baseline/after comparisons use Playwright’s snapshot diffing — agents iterate against evidence, not vibes.

Quality gates apply to agents too

npm run ai:check is the single exit criterion: full e2e matrix, block and pattern linting, CSS and JS linting. Agents follow the same contract-first discipline as humans — a SPEC.md in .ai/plans/ before implementation, clarifying questions before code. The WP Rig Tools toolbar closes the loop interactively: its AI Selector generates structured remediation prompts from any element on the page.

Registry components are agent-ready by construction

Every registry component ships SPEC.md (technical contract) and SKILL.md (implementation recipes). When you rig:add a component, those files link into .ai/skills/ — the agent that adds the feature is the same agent that can read how to use it. The Open Component Registry post covers the lifecycle.

Environment detection

PHP-side, WP Rig uses ergebnis/agent-detector to detect AI agent environments, letting the framework (and audit tooling) adapt logging and behavior when work is being done by an agent rather than a human.

WP Rig Tools: The Developer Toolbar (human-in-the-loop inspection), Testing in WP Rig (the verification gates), and The Open Component Registry (agent-ready components).