Section: The Developer Workspace

AI Coding Assistants (such as Cursor, VS Code Copilot, Windsurf, or Claude) can dramatically accelerate your theme development — but only if they have the proper context.

In this lesson, you will learn how to configure local AI coding assistants inside WP Rig and use our pre-packaged `.ai/` system to prevent model hallucinations.

The AI Challenge in WordPress

WordPress theme development historically relies on procedural scripts and global templates. When an AI assistant attempts to write code in a standard theme, it often: * Generates global namespace collisions. * Uses outdated or legacy PHP functions. * Writes custom CSS that overrides theme variables.

WP Rig v3 resolves this by incorporating an **AI-Native Framework**. By combining WP Rig’s strict PHP namespaces, OOP Components, and PSR-4 autoloading, AI agents can trace, read, and write code cleanly with near-zero errors!

Step-by-Step AI Agent Activation

To boot up and configure your local AI agent, run the following setup script inside the theme folder:

npm run ai:setup

This script scans your active project configurations and configures standard environment rules for your workspace (writing configurations for Cursor, Windsurf, Copilot, and Claude).

Navigating the `.ai/` Directory

WP Rig integrates a specialized directory to act as the “long-term memory” and command center for your AI assistant. Look under `./.ai/`:

.ai/
├── agent-state.md         # Tracks onboarding status (Pending vs. Completed)
├── developer-directions.md # Write your custom coding guidelines here
├── PROJECT_RULES.md       # Chronological log of custom architectural learnings
└── skills/                # Core technical tutorials for AI (CSS, PHP, Blocks)

1. `developer-directions.md`

2. `PROJECT_RULES.md`

3. Contract-First specs

The Quality Check Sweep

After your AI writes PHP, CSS, or JS, have it run:

npm run ai:check

This runs automated lints, PHPStan static checks, and Playwright tests. If any check fails, the AI can read the console logs and debug/heal its own code autonomously!

In our next section, we will see how to leverage WP Rig’s built-in generators to scaffold OOP PHP components and blocks!

With your theme active and fully scaffolded, you are ready to enter your daily development routine. In this lesson, we will explore starting the local dev server and how to navigate WP Rig’s source asset folders.

1. Start the Dev Server

Every time you sit down to develop, run this command in your terminal inside the theme directory:

npm run dev

This command: 1. Initiates asset compilers in **watch mode**. 2. Spins up a BrowserSync proxy server. 3. Automatically opens your default web browser to the proxy URL (e.g., `https://wprig.io/`). 4. Launches a live reload loop: CSS modifications are injected instantly into the DOM without refreshing; PHP/JS saves trigger automated browser reloads.

2. Navigating the Source Directories

WP Rig follows a strict **Source vs. Compiled Artifacts** pattern. You **MUST** edit files exclusively under source directories. Never edit files in the root `assets/` directory directly, as they are overwritten by compilers during builds!

Look inside `assets/`:

assets/
├── css/
│   ├── src/             <-- EDIT THESE FILES ONLY
│   │   ├── editor.css
│   │   ├── global.css
│   │   └── navigation.css
│   └── (compiled files) <-- NEVER EDIT THESE (Overwritten)
└── js/
    ├── src/             <-- EDIT THESE FILES ONLY
    │   ├── global.ts
    │   └── navigation.ts
    └── (compiled files) <-- NEVER EDIT THESE (Overwritten)

CSS Architecture & PostCSS

JavaScript Compilation

The Build Watch Cycle

Whenever you save a file in a `/src/` folder: 1. The compiler catches the save event in less than 50ms. 2. It parses syntax, processes imports, low-level bundles, and minifies the results. 3. BrowserSync injects the updated files directly into your active browser tabs instantly!

In our next lesson, we will explore setting up your local AI agent to accelerate your development inside this workspace!