Initialization turns an acquired starter theme into a named project: it sets the theme’s identity, applies your chosen capabilities, and cleans up starter-only files. It runs after you’ve acquired the starter and installed dependencies, and it does not install WordPress or implement new feature classes.
Run from the theme root: the directory containing package.json, composer.json, and bin/init.js. For a theme inside another repository, this is its wp-content/themes/<directory> directory; keep the parent repository’s tooling at the parent root. Have Composer 2, PHP 8.2+, Node/npm matching .nvmrc, and the dependencies installed. Follow the dependency installation steps when they are not installed. Confirm the working tree is clean before continuing:
git status --short
The command should produce no output. Init rewrites and removes starter files; use a clean checkout or a disposable copy so the pre-init state remains your recovery point.
| Entry point | Role |
|---|---|
| Clone / Composer acquisition | Place the starter in the intended theme directory using the supported repository workflow; see Getting Started. |
npm run init |
Run the theme’s identity and capability wizard. |
/init |
Guide dependency installation and the same init flow with confirmations; a feature brief can be handed to scaffold afterwards. |
/scaffold |
Implement a new feature after personalization. |
/setup |
Generic tooling bootstrap; it is not an acquisition or personalization path for this starter. |
Claude skills remain after cleanup. Copilot’s /init and /scaffold prompts ship in .github/prompts, which cleanup removes. Use the retained skill with an assistant that supports it, or the CLI, for subsequent work. The maintained AI entry points describe assistant-specific instructions.
Each stage hands off a concrete result to the next:
vendor/autoload.php and node_modules/@rtcamp/wp-tooling.The Getting Started guide verifies the clone route. If a parent project acquires the starter through its Composer/VCS workflow, continue from the same theme-root checkpoint after that workflow has placed the files.
.wp-scaffold.json; the setup confirmation defaults to No.Acme Blog, the namespace is rtCamp\Theme\Acme_Blog, package rtcamp/acme-blog, text domain acme-blog, function prefix acme_blog_, constant prefix ACME_BLOG, and CSS prefix acme-blog-. Version defaults to 1.0.0..wp-scaffold.json, regenerates the Composer autoloader, and removes the configured starter-only targets. There is no separate cleanup prompt. The wrapper then runs sync-ai after a successful change..git and its starter history; decline it when keeping that history or working inside another repository. Hook installation defaults to Yes after a new repository is initialized, and the initial commit is then created automatically. Non-interactive --yes skips optional Git setup.Examples are kept by default. HMR is on; Tailwind is off. See Included features for their purpose and source locations.
For a scripted, non-interactive first run — for example a feature-focused brief that doesn’t need any supplied example set:
npm run init -- --name="Acme Blog" --version=1.0.0 --yes --remove-examples
| Area | Result |
|---|---|
| Identity fields | Name, version, text domain, package, namespace, function prefix, constant prefix, and CSS prefix are derived and reviewed. |
| Affected files | style.css, functions.php, composer.json, package.json, and text or file basenames containing starter identity tokens are personalized. |
| Version | Written to style.css and package.json. |
| Examples | Kept groups remain. Removed groups delete their configured paths and registration regions; markers are removed in either case. See Included features. |
| Optional features | HMR updates .env.local; Tailwind adds its entry/config and declarations. |
| State | .wp-scaffold.json records identity and feature choices; do not hand-edit it. |
| Autoload | Setup regenerates Composer’s autoloader. |
| Cleanup | Before the wrapper’s final sync, the Copilot-specific .github files (copilot-instructions.md, prompts/, instructions/) and languages (including the starter POT file) are removed. Workflows, issue templates, the PR template, dependabot.yml, and release.yml stay untouched. |
| AI instructions | After a successful change, the wrapper runs sync-ai; in a standalone project with the framework installed, it refreshes the generated framework PHP instructions. It does not restore the removed prompts or theme-specific rules. |
| Retained files | Theme source, bin/, Claude skills, documentation, and test infrastructure remain; files belonging to removed example sets do not. |
Init does not generate a POT file. Run npm run pot separately when preparing translations (it runs WP-CLI inside wp-env, so start wp-env first); it recreates the language output. Review cleanup before treating the initialized project as your baseline.
After setup, review the generated state and the cleanup result before adding features:
npm run init -- --list (or --list --json) and confirm the retained example sets are present and the selected feature states match your choices.style.css, functions.php, composer.json, package.json, and .wp-scaffold.json for the resolved name, namespace, prefixes, version, and package metadata.git status and the diff. Confirm removed example paths are gone and that the output lists the .github/languages cleanup. Check the generated framework instruction file if sync-ai ran.Follow dependency instructions printed by init. Make a baseline commit after these checks so feature work has a known starting point.
Identity edits and optional feature toggles are repeatable manage-mode operations. Example removal is a one-time setup decision: its markers are consumed, so a later init run cannot restore a removed group or safely remove another group. Restore a clean starter copy to recover an example, or add new functionality through Scaffolding.
Later, bare npm run init opens management for identity and optional features. Useful commands from the theme root:
npm run init -- --list
npm run init -- --list --json
npm run init -- --enable=hmr --yes
npm run init -- --disable=hmr --yes
npm run init -- --features=hmr --yes
--features sets the entire enabled set; --enable and --disable change one feature without replacing the others. Do not combine these forms. Help and --list are read-only. For machine-readable JSON without npm’s banner, use node bin/init.js --list --json.
Example removal belongs to initial setup: --remove-examples=shortcode,patterns removes those groups, and --keep-examples keeps every group. Do not use --reinit to restore examples or remove more groups after their markers have been consumed. Review source and registration together when making a manual change.
npm run init -- --enable=tailwind --yes changes declarations and creates the entry/config files; npm installation is separate. See Tailwind for the theme integration and installation checks.| Symptom | Check and next action |
|---|---|
| Engine cannot load | Finish dependency installation from the theme root; confirm node_modules/@rtcamp/wp-tooling exists. |
| Command option rejected | Run npm run init -- --help; correct the command before retrying. |
| Partial setup or interrupted operation | Inspect the diff and state file before continuing. Restore your pre-init checkout/backup if necessary; do not blindly rerun destructive setup. |
| Feature enabled but dependency missing | Follow the package-install/update instruction; a declaration is not an installed package. |
| Retained example or capability is missing | Run npm run init -- --list and inspect the recorded selection and paths. If the group was removed, recover from a clean starter copy; manage mode cannot restore consumed markers. |
| Git step fails after personalization | Inspect the completed theme changes, configure Git, and finish repository setup manually. |
| Copilot prompts disappeared | This is cleanup behavior; see CLI or AI. |
Cleanup has a tracked implementation follow-up: retained starter instructions can still refer to AI files that cleanup removes. Keep that repair separate from this guide and follow the maintenance known gaps.
Generic engine behavior belongs upstream in wp-tooling; use the local help output for the options supported by your installed revision.