CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude Code-integrated WordPress development template providing a clean, root-level WordPress content layout (themes/, plugins/, and mu-plugins/ live at the project root) with WordPress-specific development tools and scripts.

The template is designed for:

WordPress FSE (Full Site Editing) block theme development
Custom WordPress plugin development
WordPress security, performance, and accessibility auditing
Integration with Claude Code for WordPress development workflows
Automated design-to-WordPress pipelines (Figma · Canva · InDesign) via the flavian CLI and Claude Code

⚠️ CRITICAL: File Location Requirements

This project uses ROOT-LEVEL WordPress folders, NOT wp-content/ subfolders:

project-root/
├── themes/          ← Theme files go HERE (NOT wp-content/themes/)
├── plugins/         ← Plugin files go HERE (NOT wp-content/plugins/)
├── mu-plugins/      ← Must-use plugins go HERE (NOT wp-content/mu-plugins/)
└── .claude/         ← Claude Code configuration

Why root-level?

Cleaner development structure
Easier version control (no nested wp-content)
Testing copies files to WordPress wp-content/ for deployment
Development and testing environments separated

NEVER create files in wp-content/themes/ or wp-content/plugins/ during development.

When deploying to WordPress, files are copied from root folders to wp-content/ by deployment scripts.

WordPress Development Scripts

This template includes WordPress-specific automation scripts:

Security and Quality Tools

# Set up PHP CodeSniffer with WordPress standards
./scripts/wordpress/setup-phpcs.sh

# Check WordPress coding standards
./scripts/wordpress/check-coding-standards.sh

# Run security scan
./scripts/wordpress/security-scan.sh

# Check performance
./scripts/wordpress/check-performance.sh

Development Commands

WordPress Setup

# Download WordPress core files
wp core download

# Create wp-config.php
wp config create --dbname=dbname --dbuser=root --dbpass=password --dbhost=localhost

# Install WordPress
wp core install --url=example.com --title="Site Title" --admin_user=admin --admin_password=password --admin_email=admin@example.com

# Update WordPress core
wp core update

# Update all plugins
wp plugin update --all

# Update all themes
wp theme update --all

Theme Development

# Activate a theme
wp theme activate theme-name

# Generate theme starter files
wp scaffold _s theme-name --theme_name="Theme Name" --author="Author Name"

# Check theme for errors
wp theme verify theme-name

Plugin Development

# Activate a plugin
wp plugin activate plugin-name

# Deactivate a plugin
wp plugin deactivate plugin-name

# Generate plugin starter files
wp scaffold plugin plugin-name --plugin_name="Plugin Name"

# Run plugin tests (if PHPUnit is configured)
phpunit

Database Operations

# Export database
wp db export backup.sql

# Import database
wp db import backup.sql

# Search and replace in database
wp search-replace 'old-domain.com' 'new-domain.com'

# Reset database
wp db reset

Development Server

# Using PHP built-in server
php -S localhost:8000

# Using wp-cli server
wp server --host=localhost --port=8080

# Using Local by Flywheel, XAMPP, MAMP, or Docker
# Configure according to your local environment

WordPress File Structure

When developing, follow these conventions:

Theme Structure (Development - Root Level)

themes/theme-name/              ← ROOT-LEVEL (not wp-content/themes/)
├── style.css                   # Theme information and main styles
├── functions.php               # Theme functions and hooks
├── index.php                   # Main template file (classic themes)
├── theme.json                  # FSE theme configuration (REQUIRED for FSE)
├── templates/                  # FSE block templates
│   ├── index.html             # Main template
│   ├── front-page.html        # Homepage template
│   ├── single.html            # Single post template
│   ├── page.html              # Page template
│   └── 404.html               # 404 error template
├── parts/                      # FSE template parts
│   ├── header.html            # Header template part
│   ├── footer.html            # Footer template part
│   └── sidebar.html           # Sidebar template part
├── patterns/                   # Block patterns
├── assets/
│   ├── css/                   # Additional stylesheets
│   ├── js/                    # JavaScript files
│   └── images/                # Theme images
└── inc/                        # PHP includes

# Classic theme alternatives (if not using FSE):
# ├── header.php, footer.php, sidebar.php
# ├── single.php, page.php, archive.php
# └── template-parts/

Plugin Structure (Development - Root Level)

plugins/plugin-name/            ← ROOT-LEVEL (not wp-content/plugins/)
├── plugin-name.php            # Main plugin file with header
├── includes/                  # PHP includes
├── admin/                     # Admin-specific functionality
├── public/                    # Public-facing functionality
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
└── languages/                 # Translation files

Deployment Note: During testing/deployment, files from themes/ are copied to wp-content/themes/ and files from plugins/ are copied to wp-content/plugins/. See .claude/skills/figma-to-fse-autonomous-workflow/TESTING-GUIDE.md for deployment procedures.

WordPress Development Standards

PHP Coding Standards

Follow WordPress PHP Coding Standards
Use WordPress functions and APIs where available
Properly escape output: esc_html(), esc_url(), esc_attr()
Sanitize input: sanitize_text_field(), sanitize_email(), etc.
Use nonces for form submissions and AJAX requests

Database Interactions

Use $wpdb global for custom queries
Prepare SQL queries to prevent injection: $wpdb->prepare()
Use WordPress functions for common operations (get_posts, WP_Query, etc.)

Hooks and Filters

Use action hooks: add_action(), do_action()
Use filter hooks: add_filter(), apply_filters()
Follow WordPress hook naming conventions
Document custom hooks

JavaScript and CSS

Enqueue scripts and styles properly using wp_enqueue_script() and wp_enqueue_style()
Localize scripts for AJAX: wp_localize_script()
Use wp_register_script() for conditional loading

Security Best Practices

Validate and sanitize all user input
Escape all output
Use nonces for state-changing operations
Check user capabilities: current_user_can()
Keep WordPress, themes, and plugins updated

Testing

PHPUnit Testing

# Install PHPUnit
composer require --dev phpunit/phpunit

# Run tests
vendor/bin/phpunit

# Run specific test file
vendor/bin/phpunit tests/test-sample.php

WordPress Debugging

Add to wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );

Common WordPress Functions

Content Retrieval

get_posts() - Retrieve posts
WP_Query - Advanced post queries
get_pages() - Retrieve pages
get_categories() - Get categories
get_tags() - Get tags

Theme Functions

get_header(), get_footer(), get_sidebar()
get_template_part()
wp_head(), wp_footer()
the_loop(), have_posts(), the_post()

User and Permissions

is_user_logged_in()
current_user_can()
wp_get_current_user()
get_current_user_id()

Options and Settings

get_option(), update_option(), add_option()
get_theme_mod(), set_theme_mod()
get_site_option() (for multisite)

Claude Code Architecture & Configuration

Installed Plugins (6 Total)

This project uses a lean, WordPress-optimized plugin configuration with 6 plugins (5 user + 1 local):

episodic-memory - Conversation search and memory
commit-commands - Git workflow automation
github - GitHub integration (PRs, issues, repos)
php-lsp - PHP language server
superpowers - Advanced development workflows
ai-taskmaster - Task management (local)

Full documentation: .claude/PLUGINS-REFERENCE.md

Custom Agents (53 Total)

53 specialized agents spanning WordPress-focused development and generic cross-domain work (meta/ops, business, marketing/social, engineering). Key WordPress agents include frontend-developer, plugin-developer, test-writer-fixer, ui-designer, figma-fse-converter, canva-fse-converter, indesign-to-wordpress, security-audit-agent, deployment-agent, woocommerce-agent, headless-developer. Key generic agents include agent-expert, backend-architect, migration-specialist, content-creator, devops-automator. See the catalog for the full WordPress/generic breakdown.

Agents are invoked automatically based on task context.

Full catalog: .claude/CUSTOM-AGENTS-GUIDE.md

Agent Naming Conflicts

⚠️ Note: If you install additional Claude Code plugins beyond the bundled set, more than one may provide a similarly-named agent (for example, a code-reviewer).

Quick rule: When names collide, pick the agent most specific to your task — a PR-focused reviewer before merge, a plan-alignment reviewer for verifying work against a plan, or a general reviewer otherwise.

The bundled 6-plugin set (see .claude/PLUGINS-REFERENCE.md) does not itself ship duplicate agent names; this guidance applies only once you add plugins that do.

Full guide: See .claude/AGENT-NAMING-GUIDE.md

Custom WordPress Skills (12 Total)

12 WordPress-specific skills provide systematic workflows:

Pipeline orchestrators: figma-to-fse-autonomous-workflow, canva-to-fse-autonomous-workflow, indesign-conversion

Theme authoring: fse-block-theme-development, fse-pattern-first-architecture, block-pattern-creation

Quality & security: visual-qa-verification, wordpress-security-hardening, wordpress-testing-workflows

Operations: wordpress-internationalization, wordpress-hook-integration, wp-cli-workflows

Skills auto-trigger based on keywords (e.g., "FSE", "security review", "deploy").

Full catalog: .claude/skills/README.md

Development Workflow with Claude Code

1. Theme Development Cycle

# Start feature branch
git checkout -b feature/hero-block-pattern

# Develop with Claude Code
# - Use php-lsp for autocomplete
# - Use frontend-developer agent for UI work
# - Use test-writer-fixer for PHP tests

# Commit with structure
/commit
# Suggested: "feat: Add hero section block pattern"

# Create PR
/commit-push-pr
# Auto-generates PR with test plan

2. Code Quality Workflow

# Check coding standards (use root-level paths)
./scripts/wordpress/check-coding-standards.sh themes/my-theme

# Security scan (use root-level paths)
./scripts/wordpress/security-scan.sh themes/my-theme

# Performance check (use root-level paths)
./scripts/wordpress/check-performance.sh themes/my-theme

# Dependency vulnerability scan
./scripts/security-audit/scan-dependencies.sh .

# Generate security report with severity ratings
./scripts/security-audit/scan-dependencies.sh . 2>/dev/null | ./scripts/security-audit/generate-report.sh

# Auto-create issues for critical findings
./scripts/security-audit/scan-dependencies.sh . 2>/dev/null | ./scripts/security-audit/create-issues.sh

# Fix issues and commit
/commit

Note: Always use root-level paths (themes/, plugins/) for development scripts.

3. Using Custom Agents Agents are invoked automatically based on task context, or explicitly:

User: "Help me optimize theme performance"
Claude: [Uses performance-benchmarker agent]

User: "Build a hero block pattern"
Claude: [Uses frontend-developer agent]

User: "Write tests for my custom post type"
Claude: [Uses test-writer-fixer agent]

4. Figma-to-WordPress Automation Convert Figma designs to WordPress FSE themes automatically:

User: "Convert this Figma design to WordPress"
      [Provide Figma URL]

Claude: [Autonomous workflow 5-90 minutes]
        → Complete FSE theme with theme.json, templates, patterns
        → Images work immediately (pattern-first architecture)
        → Zero manual intervention

Result: themes/[theme-name]/ ready for WordPress

Features:

Wholesale design system extraction (colors, typography, spacing)
FSE template generation with WordPress blocks
PHP patterns for images (avoids broken src="" in HTML templates)
Automatic validation (security, standards, architecture)
100% theme.json token usage (no hardcoded values)

Documentation: docs/figma-to-wordpress/README.md

5. Canva-to-WordPress Automation Convert Canva HTML/CSS exports to WordPress FSE themes:

User: "Convert this Canva export to WordPress"
      [Provide path to Canva export directory]

Claude: [Autonomous workflow 5-30 minutes]
        → Parses CSS for design tokens (colors, fonts, spacing)
        → Converts HTML to WordPress block markup
        → Complete FSE theme with theme.json, templates, patterns
        → Zero manual intervention

Result: themes/[theme-name]/ ready for WordPress

Features:

CSS design token extraction (colors, typography, spacing)
HTML-to-block conversion (headings, paragraphs, images, sections)
Shared validation infrastructure with Figma pipeline
PHP patterns for images (pattern-first architecture)
100% theme.json token usage (no hardcoded values)

Documentation: docs/canva-to-wordpress/README.md

WordPress + Claude Code Best Practices

When Claude Code should:

✅ Follow WordPress coding standards automatically
✅ Use WordPress functions instead of raw PHP/MySQL
✅ Escape output with esc_html(), esc_url(), esc_attr()
✅ Sanitize input with sanitize_text_field(), etc.
✅ Use nonces for form submissions
✅ Check user capabilities with current_user_can()
✅ Enqueue scripts/styles with wp_enqueue_script()
✅ Use $wpdb->prepare() for custom queries
✅ Create structured git commits with /commit
✅ Use appropriate specialized agents for tasks

Security Reminders for Claude Code:

Never trust user input
Always escape output
Use nonces for state-changing operations
Verify user capabilities before sensitive operations
Keep WordPress, themes, and plugins updated

Architecture Notes

Plugin Philosophy:

Lean configuration (6 plugins total: 5 user + 1 local)
WordPress-specific focus (php-lsp, not 9+ language servers)
No redundant or duplicate plugins
All plugins serve WordPress development

Agent Philosophy:

53 custom agents available (WordPress-focused + generic cross-domain; see CUSTOM-AGENTS-GUIDE.md for the breakdown)
Agents invoked contextually by Claude Code
No action required - automatic selection

Documentation Structure:

CLAUDE.md (this file) - WordPress development guidance and quick reference
docs/QUICK-START.md - 5-minute getting started guide
docs/PREREQUISITES.md - Complete requirements checklist
docs/figma-to-wordpress/ - Figma-to-FSE automation documentation
- README.md - User guide and quick start
- IMPLEMENTATION.md - Technical implementation details
- EXAMPLES.md - FSE template syntax examples
docs/CLI-WIZARD.md - The flavian CLI and interactive setup wizard
docs/pipelines/indesign.md - InDesign (.idml/PDF) → FSE pipeline (CLI)
docs/GUI.md - Cross-platform desktop GUI (@flavian/gui)
docs/RELEASING.md - Release-please versioning and release flow
.claude/PLUGINS-REFERENCE.md - Plugin commands and detailed usage
.claude/CUSTOM-AGENTS-GUIDE.md - Complete agent catalog
.claude/AGENT-NAMING-GUIDE.md - Agent name disambiguation
.claude/skills/README.md - WordPress skills catalog
LOCAL-DEVELOPMENT.md - Docker setup for local WordPress
themes/ - Generated FSE themes go here

Troubleshooting:

docs/TROUBLESHOOTING.md - General troubleshooting guide
docs/docker-troubleshooting.md - Docker & container issues (incl. Apple Silicon / M-series)
docs/COMMON-FAILURES-FIXES.md - Figma-to-WordPress workflow issues
docs/MCP-TROUBLESHOOTING.md - MCP server debugging
docs/E2E-VALIDATION.md - End-to-end validation procedures

Quick Command Reference

WordPress Development:

wp core download              # Download WordPress
wp theme activate my-theme    # Activate theme
wp plugin list                # List plugins
wp db export backup.sql       # Backup database

Flavian CLI & setup wizard:

pnpm install                                          # install workspace deps (pnpm 9.x)
pnpm run init                                         # interactive setup wizard: writes .env, scaffolds a
                                                      # starter theme, optional WooCommerce, makes an initial commit
pnpm run init -- --yes --name=my-site --theme=blank   # non-interactive
node bin/flavian.mjs --help                            # the `flavian` CLI entry point

Full guide: docs/CLI-WIZARD.md.

Design-to-WordPress pipelines:

# InDesign (.idml preferred, or PDF) → FSE theme, via the CLI
node bin/flavian.mjs pipeline indesign <input> --output themes/<slug>
pnpm pipeline:ingest            # ingest stage (packages/pipeline)
pnpm pipeline:stage-assets      # asset-staging stage
# Figma / Canva conversions are driven through Claude Code — see docs/figma-to-wordpress/ and docs/canva-to-wordpress/

Full guide: docs/pipelines/indesign.md.

Desktop GUI (@flavian/gui):

pnpm gui:dev                   # run the cross-platform desktop GUI from source
pnpm gui:build                 # build the renderer
pnpm gui:package               # build a distributable installer

Full guide: docs/GUI.md.

Git Workflows (via commit-commands):

/commit                       # Structured commit
/commit-push-pr              # Commit + push + PR
/clean_gone                   # Clean merged branches

GitHub CLI Workflows:

gh pr create                  # Create pull request
gh pr list                    # List pull requests
gh issue create               # Create issue
gh repo view                  # View repository info
gh auth status                # Check authentication

Code Quality:

./scripts/wordpress/check-coding-standards.sh [path]
./scripts/wordpress/security-scan.sh [path]
./scripts/wordpress/check-performance.sh [path]

Agent Config Validation:

./scripts/validate-agent-configs.sh              # Validate all .claude/ configs
./scripts/validate-agent-configs-ci.sh            # CI dry-run (exits non-zero on error)

Security Audit:

./scripts/security-audit/scan-dependencies.sh [path]   # Scan dependencies for CVEs
./scripts/security-audit/generate-report.sh             # Generate vulnerability report (stdin)
./scripts/security-audit/create-issues.sh               # Create GitHub issues for critical findings (stdin)

Remote Deployment:

./scripts/remote-deployment/deploy.sh --env staging --dry-run            # Plan a deploy
./scripts/remote-deployment/deploy.sh --env staging                      # Deploy to staging
./scripts/remote-deployment/deploy.sh --env production --auto-rollback   # Production with safety net
./scripts/remote-deployment/pre-deploy-checks.sh --target all            # Run validation gate only
./scripts/remote-deployment/rollback.sh --env <env> --list               # List rollback targets
./scripts/remote-deployment/rollback.sh --env <env> --to <release-id>    # Roll back

Configs live in .claude/config/deployment/<env>.yml (gitignored). Templates: *.example.yml.

Multisite network (subdirectory mode):

# Convert the single-site install into a subdirectory network + sample sub-site
docker compose --profile multisite up multisite-installer

# Or run the script directly
./scripts/wordpress-install/setup-multisite.sh --network-title "My Network"

Mu-plugin: mu-plugins/flavian-multisite.php (no-op on single-site installs). Agent: wp-environment-manager § 8 covers site CRUD, super admins, and network activation. Full guide: docs/multisite/README.md.

Headless WordPress (decoupled frontends):

# One-shot install: WPGraphQL + CORS + preview secret
docker compose --profile headless up headless-installer

# Scaffold a Next.js 14 frontend under frontend/<slug>/
bash scripts/scaffold-frontend.sh my-app --name "My Site"

# Smoke test (boots WP, asserts REST/CORS/hardening/GraphQL/scaffold + no fatals)
pnpm test:headless-e2e

Mu-plugin: mu-plugins/flavian-headless.php (toggled by flavian_headless_mode option; gates REST CORS to the frontend allowlist). Frontend templates: .claude/templates/frontend/nextjs/. CI: .github/workflows/headless-e2e.yml. Full guide: docs/headless-wordpress/README.md.

WooCommerce (e-commerce scaffold):

# One-shot install via compose profile
docker compose --profile woocommerce up woocommerce-installer

# Or run the installer script directly against the running container
./scripts/wordpress-install/setup-woocommerce.sh                  # full install + sample products
./scripts/wordpress-install/setup-woocommerce.sh --no-sample      # install without sample data
./scripts/wordpress-install/setup-woocommerce.sh --currency GBP   # configure currency / country

Bundled WooCommerce-ready FSE theme: themes/flavian-shop/. Defaults configurable via .env: WC_INSTALL_SAMPLE_DATA, WC_DEFAULT_THEME, WC_DEFAULT_CURRENCY, WC_DEFAULT_COUNTRY.

Gutenberg custom block scaffolding:

# Slash command: /scaffold-block  (or pnpm run scaffold:block)
# Generates a self-contained, activatable block plugin under plugins/<name>/
# (no build step — runtime globals + index.asset.php deps).

# Static block (save() serializes markup)
bash scripts/scaffold-block.sh hero-card --namespace flavian \
  --attributes "heading:string:Welcome,centered:boolean:true"

# Dynamic block (server-rendered render.php)
bash scripts/scaffold-block.sh latest-events --namespace flavian \
  --attributes "count:number:3" --dynamic

# Full E2E smoke test (scaffold → activate → render; needs the Docker stack)
docker compose up -d wordpress db
bash scripts/smoke-block.sh            # or: pnpm run smoke:block

Inputs: block name (positional), --namespace, --attributes "name:type[:default]" (types: string, number, boolean, array, object), --dynamic. Outputs: block.json, index.js (edit+save), index.asset.php, styles, render.php (dynamic only), a PHPUnit stub, and phpunit.xml.dist. Full guide: docs/blocks/README.md. Tests: tests/unit/scaffold-block.bats.

Visual QA & Quality Scripts:

./scripts/visual-diff.js [actual] [expected]     # Pixel-level screenshot comparison
./scripts/check-responsive.sh [url]               # Responsive screenshots at all breakpoints
./scripts/check-dark-mode.sh [url]                # Dark mode visual verification
./scripts/check-dead-code.sh [--json]             # PHP dead code detection (Psalm/PHPStan)

PostToolUse Hooks (6 Total)

post-build-qa — Reminds to run full quality gate after theme validation
pre-commit-guard — Checks for hardcoded colors before commits
coverage-check — Reminds to review PHPUnit/Pest coverage output
dark-mode-reminder — Suggests dark mode verification after visual diff
bundle-guard — Warns if theme >5MB or plugin >10MB before commits
mutation-test — Suggests Infection PHP after all tests pass

Plugin Management:

/plugin list                  # List installed plugins
/plugin install <name>        # Install plugin
/plugin uninstall <name>      # Uninstall plugin

Last Updated: 2026-06-28 Architecture Status: ✅ Lean, WordPress-optimized configuration (6 plugins + 53 agents)

Uh oh!

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

⚠️ CRITICAL: File Location Requirements

WordPress Development Scripts

Security and Quality Tools

Development Commands

WordPress Setup

Theme Development

Plugin Development

Database Operations

Development Server

WordPress File Structure

Theme Structure (Development - Root Level)

Plugin Structure (Development - Root Level)

WordPress Development Standards

PHP Coding Standards

Database Interactions

Hooks and Filters

JavaScript and CSS

Security Best Practices

Testing

PHPUnit Testing

WordPress Debugging

Common WordPress Functions

Content Retrieval

Theme Functions

User and Permissions

Options and Settings

Claude Code Architecture & Configuration

Installed Plugins (6 Total)

Custom Agents (53 Total)

Agent Naming Conflicts

Custom WordPress Skills (12 Total)

Development Workflow with Claude Code

WordPress + Claude Code Best Practices

Architecture Notes

Quick Command Reference

PostToolUse Hooks (6 Total)