claude-wp-builder: Instructions file for Claude Code

CLAUDE.md

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

What this repo is

A Claude Code plugin, not an application. Almost everything here is markdown that instructs Claude at runtime — commands, agents and skills. There is no build step, no package manager, no runtime for the plugin itself. The only executable code shipped is:

• bin/*.sh — env setup / ffmpeg wrappers, invoked by commands
• skills/wp-polylang/scripts/*.php — run inside a real WordPress via wp eval-file
• starter-theme/** — PHP copied into user projects (never executed here)

Editing a "feature" therefore usually means editing prose contracts, and the tests assert on those contracts (grep for required tokens in the markdown), not on program behavior.

Testing

Each check is a standalone bash script that prints PASS or exits non-zero. No runner, no framework.

bash tests/checks/wp-yolo-gate.sh                    # one check
for f in tests/checks/*.sh; do bash "$f"; done       # all checks

tests/checks/wp-polylang-live.sh is the only test that touches a real site; it exits 0 with SKIP unless PLL_TEST_SITE points at a WordPress root with Polylang active (PLL_TEST_SRC/PLL_TEST_DST/PLL_TEST_THIRD override the languages; the third language is created and deleted by the suite and is guarded by a pre-existence probe).

There is no CI. Run the checks yourself before claiming a change works.

Architecture

Four layers, strictly ordered:

commands/*.md   user-facing slash commands — orchestration, argument parsing, step-by-step flow
   ↓ dispatches
agents/*.md     specialized subagents (wp-template, wp-css, wp-acf, wp-audit-*, wp-normalize…)
   ↓ reads
skills/*/SKILL.md   knowledge libraries — methodology, never actions. user-invocable: false
   ↓ produces
starter-theme/ + templates/   PHP theme scaffolds and env/plugin-profile configs copied per project

Key consequences when changing things: