WordPress (local-first)

Build and edit WordPress sites locally on WordPress Playground: site lifecycle, block themes and patterns, block-markup validation, design polish, and backup discipline. Deploying to WordPress.com is not yet supported by this skill — stay local or point the user to the WordPress.com UI.

Requirements: Node 18+ and a POSIX shell (macOS/Linux/WSL — native Windows is unsupported). Script paths below are relative to this skill directory; resolve them to absolute paths. Run scripts/playground.sh from the project directory (its state lives in ./workdir/.playground/).

Routing

Non-negotiable rules

1. Local WordPress = Playground via scripts/playground.sh (verbs: bootstrap | ensure | wp | front-page | status | stop). Docker is banned. Never hand-roll a MySQL/PHP stack, never wp-now.
2. Local sites you created are disposable; production is not. Before any destructive write to a user-designated production site, create and verify a backup manifest (references/backups-and-safety.md). If the user says to skip it, refuse — creating one takes ~30 seconds. File copies count as writes.
3. Block work isn't done until both gates pass. Per file, as you write/edit markup: auto-repair with fix-blocks.cjs (mechanical, no browser; fixes the recurring cover/border/order INVALID cases), then validate-blocks.cjs — both instant. Run the slow editor-gate.mjs (live editor) once per hand-back, at the very end, after every file is inner-loop-clean — not per file and not as a fix-discovery loop; it should pass first try. Do not hand-fix validity or open the editor to fix it; run the fixer. Invalid blocks render fine on the frontend and break only in the editor — screenshots can't catch them. (references/block-markup.md.)
4. Never edit WordPress core. wp search-replace always dry-runs first.
5. Leave the server running when you hand work back — the user needs it live to test. Do NOT run playground.sh stop just because development is "done"; stopping a site the user is about to try is a defect, not cleanup. Stop ONLY when the user asks, or when you must restart to change the mount set. Whenever you stop — and when you finish — give the user the one-line playground.sh ensure … command to bring the site back. (stop still asserts clean teardown and must print "stopped clean" on the occasions you do run it.)
6. End every rendered change by printing a clickable link the user can test. Print the live URL from the recorded port — http://127.0.0.1:$(cat workdir/.playground/server.port)/ — deep-linked to the part you changed: a section anchor (…/#<anchor>), a specific page (…/sample-page/), or the editor (…/wp-admin/) for editor-only work. Default to the home page for general or site-wide changes. Always resolve the real running port; never hardcode or assume one.
7. For new sites/redesigns, users choose from rendered HTML previews in a browser (references/design.md) — never from text directions, terminal option lists, or ASCII mockups. The number of previews scales to the brief: an open brief or material redesign gets the 4-direction gallery; a tightly-specified brief gets a single first-fold preview built to that brief (still shown and approved in the browser — not silently skipped). Build what the user asked for; previews confirm the execution, they don't reopen a decision the brief already made.
8. Build the LANDING PAGE first, then ask what else to build (references/design.md §5–§6). Run the build sequence — scaffold (scripts/scaffold-theme.sh — drops theme.json rigor, base CSS, motion runtime, content-loader) → site spec (site-spec.md) → recolor theme.json (themes-and-patterns.md) → page-frame CSS (layout-modes.md) → compose the home/front page only (aesthetics.md) → motion hooks (motion.md) — then hand back the live landing page and STOP. Do not pre-build the other pages, templates, CPTs, or forms, or generate the whole image library, on the assumption the user wants them — that's the slow path. Once the user has seen the landing page, ask which of the site-type-appropriate extras to build (§6). Scaffold first so rigor/motion can't be skipped; never hand-write theme.json/style.css boilerplate or hand-roll page creation / front-page wiring (content-loader.php does it).
9. Image handling needs an explicit choice — always ask, before design previews and any markup. Being logged in is not consent. Check workdir/.playground/images.json first (a recorded answer is the only thing that skips the question), then follow references/images-media.md: present four options, "generate real AI photos" always listed first, then plain placeholders (solid-color images + AI_IMAGE: markers, no login needed), provide their own photos, or imageless. The answer also decides what the design previews contain. Fall back to placeholders whenever the user isn't logged in or doesn't want to generate; respect a recorded answer across sessions; and never let generation failures or the choice block site creation.