Building Better Workflows with Claude and WordPress Studio

@AGENTS.md

## What This Repository Is
A WordPress 6.9.4 development environment using SQLite as the database backend, managed by [WordPress Studio](https://developer.wordpress.com/docs/developer-tools/studio/cli/). The active development focus is the `plugin-name` Gutenberg block plugin, which does things.
**Local URL:** https://SITESUBDOMAIN.wp.local/

## Environment Management (WordPress Studio)
The local server is managed by WordPress Studio. Key CLI commands:
```bash
studio site start           # Start the local site
studio site stop            # Stop the local site
studio site status          # Check if the site is running
studio wp <wp-cli-command>  # Run WP-CLI commands in the Studio context (no separate WP-CLI install needed)
```
Full CLI reference: https://developer.wordpress.com/docs/developer-tools/studio/cli/

## Plugin Development (plugin-name)
All plugin source lives in `wp-content/plugins/plugin-name/`. This directory has its own git repository.
@wp-content/plugins/plugin-name/CLAUDE.md

## Architecture
### Database
Uses SQLite instead of MySQL. The database file is at `wp-content/database/.ht.sqlite`. The SQLite Database Integration plugin (`wp-content/mu-plugins/sqlite-database-integration/`) provides the driver via the `wp-content/db.php` drop-in.
The system `sqlite3` binary is available and can be used to query the database directly when needed:
```bash
sqlite3 wp-content/database/.ht.sqlite "SELECT * FROM wp_options WHERE option_name = 'siteurl';"
```

## Architecture

## Build System
Uses `@wordpress/scripts` (wraps webpack + Babel). The `--blocks-manifest` flag auto-generates `build/blocks-manifest.php`.
```bash
npm run build       # Production build
npm run start       # Development watch mode
npm run lint:js     # JavaScript lint
npm run lint:css    # CSS/SCSS lint
npm run format      # Auto-format code
npm run plugin-zip  # Create distributable zip
```
> Always run a build before testing PHP-side block registration changes — the manifest is generated at build time.
## PHP Linting (WPCS / PHPCS)
PHP coding standards are enforced via [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards). Config is in `phpcs.xml.dist`.
```bash
composer install          # First time — installs PHPCS + WPCS into vendor/
composer lint:php         # Run PHPCS
composer lint:php:fix     # Run PHPCBF (auto-fix)
```

## Code Style
This project follows **WordPress Core coding standards** throughout, enforced by linting.
### PHP
- [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/): Yoda conditions, `array()` (not `[]`), tabs for indentation, spaces inside parentheses, `snake_case` for functions/variables, `PascalCase` for classes.
- Escape all output (`esc_html__()`, `esc_url()`, `esc_attr()`). Sanitize all input (`sanitize_text_field()`, `wp_unslash()`). Use `check_admin_referer()` for nonce verification before processing POST data.
- No direct database calls; use WordPress option and transient APIs.
### JavaScript / JSX
- [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/): tabs for indentation, spaces inside braces and parentheses, single quotes.
- Use `const`/`let`, never `var`.
- All user-visible strings must be wrapped in `__()` or `sprintf()` from `@wordpress/i18n`. `sprintf()` calls require a `/* translators: ... */` comment **inside the same JSX expression block** as the call (not on a separate line).
- Avoid flanking whitespace in translation strings — use `{ ' ' }` for explicit spaces between JSX nodes.
- `/* global SomeGlobal */` comments are required for browser globals not in the default ESLint environment (e.g. `MutationObserver`), and for WP-localized script globals (e.g. `bolPardot`).
### CSS / SCSS
- [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/): tabs for indentation, space before `{`, lowercase properties.
- Order pseudo-class selectors least-specific first: `&:disabled` before `&:focus` before `&:hover`.
- Avoid `input, textarea` combined rules when textarea needs additional properties — use separate blocks to satisfy `no-descending-specificity`.
- Use CSS custom property fallback chains: block-level `--bol-*` first, then `--global-palette*` (Kadence, if active), then `--wp--preset--*`, then a hardcoded default. Never rely on any single source being present.

## Debugging approach
- **Check actual output before speculating.** When diagnosing a frontend issue, make an HTTP request to the local site (`https://pardot.wp.local/`) and inspect the rendered HTML or loaded CSS first. This is faster and more reliable than reasoning about what the output might be.
- **Ask the user questions early.** If a problem has multiple possible causes, ask a targeted question rather than running through all hypotheses. The user can often point you straight to the answer.

## Before marking any task as done
1. Run **both** linters and fix any reported issues:
```bash
npm run lint:js && npm run lint:css
composer lint:php
```
2. If the task adds or changes user-visible behaviour, update the **Help tab** in `includes/class-bol-admin-page.php` (`render_help_tab()`).
3. Update **`CLAUDE.md`** and **`.github/copilot-instructions.md`** with any architectural changes.
4. If any translatable strings were added, changed, or removed (in PHP or JS), regenerate the POT file:
```bash
studio wp --path=/Users/georgestephanis/Studio/pardot i18n make-pot wp-content/plugins/big-orange-pardot wp-content/plugins/big-orange-pardot/languages/big-orange-pardot.pot --domain=big-orange-pardot
```