Setup

Read @/knowledge/acf-blocks/conventions.md before proceeding.

Step 1 — Collect project info

Ask for all answers before proceeding:

• Theme name — human-readable, e.g. My Client Site
• Theme slug / Text Domain — kebab-case, e.g. my-client-site
• Author — developer or agency name
• WordPress path — absolute path to the WordPress installation root (needed to copy mu-plugins)

Step 2 — Confirm optional features

Default yes for all:

• Tailwind v4 — CSS build pipeline with per-developer CSS support
• TypeScript + tsup — JS bundler for entry files and block scripts

Step 3 — Check for existing files

If a file already exists, ask whether to overwrite or skip. Never silently overwrite.

Step 4 — Copy and configure boilerplate

Copy the entire boilerplate/theme/ directory to themes/{slug}/:

cp -r "$(claude plugin path wp-acf-blocks)/boilerplate/theme" themes/{slug}

Then replace all placeholders throughout the copied files:

Files containing placeholders: style.css, functions.php, package.json.

The scaffolded structure:

themes/{slug}/
├── style.css
├── index.php
├── functions.php           THEME_NAME constant, DEV_CSS_MAP stub, requires
├── blocks.json             { "blocks": [] }
├── inc/
│   ├── enqueue-assets.php
│   └── auto-include-components.php
├── helpers/
│   └── ui/
│       └── get-block-wrapper-attributes.php
├── blocks/
├── scripts/
│   └── tailwind.js
├── assets/
│   ├── js/
│   │   └── index.entry.ts
│   └── css/
│       └── index.css
├── acf-json/               empty dir tracked via .gitkeep; populated by ACF when saving field groups
├── tsup.config.ts
├── tsconfig.json
├── .gitignore
└── package.json

Step 5 — Install mu-plugins

Copy all three mu-plugins to the WordPress mu-plugins directory:

cp "$(claude plugin path wp-acf-blocks)/boilerplate/mu-plugins/wp-blocks-loader.php" {WP_PATH}/wp-content/mu-plugins/
cp "$(claude plugin path wp-acf-blocks)/boilerplate/mu-plugins/acf-local-json-router.php" {WP_PATH}/wp-content/mu-plugins/
cp "$(claude plugin path wp-acf-blocks)/boilerplate/mu-plugins/tailwind-theme-loader.php" {WP_PATH}/wp-content/mu-plugins/

What each does:

• wp-blocks-loader.php — reads blocks.json, registers each block via register_block_type(), adds a project block category in the Gutenberg inserter (label from THEME_NAME constant), fixes WP 6.3+ defer strategy so viewScript files load in footer
• acf-local-json-router.php — routes ACF field group saves to blocks/{slug}/fields.json (per-block) or acf-json/ (all other groups); required for the per-block fields.json workflow
• tailwind-theme-loader.php — enqueues Tailwind-built CSS on frontend and inside Gutenberg editor iframe; supports per-developer CSS files via DEV_CSS_MAP

Step 6 — If Tailwind selected

The boilerplate .gitignore already excludes .env.local and generated CSS files. For per-developer CSS, instruct each developer to create .env.local in the theme root:

TAILWIND_USER=theirlogin

Then map WP user IDs in functions.php:

define('DEV_CSS_MAP', [
    1 => 'alice',
    2 => 'bob',
]);

Step 7 — Install dependencies and build

cd themes/{slug}
pnpm install
pnpm build

Step 8 — Confirm completion

Print a summary of what was created and what was skipped. Next steps:

• Activate the theme in WordPress admin
• Confirm ACF plugin is active (required for block field groups)
• Use /wp-acf-blocks:plan-block to plan a block and create a GitHub issue
• Use /wp-acf-blocks:add-block to scaffold the first block