wp-bootstrap

WordPress Project Bootstrapper

One command to wire a WordPress project (single plugin, block theme, or monorepo with multiple packages) into the full wp-agent-kit system: local Playground dev, WP Engine deploy environments, Composer-managed PHP deps, CI gate, and git hooks.

When to use

• Setting up a new WordPress plugin, theme, or block theme from scratch.
• Onboarding an existing codebase to use the full agent toolkit.
• Wiring up a monorepo (multiple plugins/themes + JS packages in one repo) — like the wp-agent-os pattern: wpaos/ + wpaos-blocks/ + wpaos-theme/ + JS packages.
• Adding Composer (WPackagist + optional SatisPress) to a WordPress project.
• Configuring WP Engine dev/staging/production + GitHub Actions CI/CD.

What gets set up

Component	What	Where
Agent kit	Skills, agents, instructions	.agents/skills/ + .github/
PHP tooling	PHPCS + PHPStan + Pest	composer.json + phpcs.xml.dist + phpstan.neon.dist
JS tooling	Biome (lint+format)	biome.json
Git hooks	Pre-push gate	.githooks/pre-push
One-command setup	tools/setup.sh	tools/setup.sh
WP-CLI aliases	Local path + WPE SSH	wp-cli.yml
Playground	Multi-mount interactive + headless verify	tools/playground/
WP Engine CI/CD	Branch-gated deploy workflows	.github/workflows/
Plugin packaging	Build + zip for upload	tools/package-wp.sh
Composer	WPackagist + optional SatisPress	composer.json + auth.json
Config	Monorepo layout declaration	wp-bootstrap.config.json

---

Procedure

1) Probe the repository (always first)

Run the structure detector. It identifies WP packages, JS workspaces, existing tooling, WP Engine remotes, GitHub CLI status, existing secrets, and branch protection.

node {baseDir}/scripts/detect-structure.mjs --pretty

Key fields in the output:

Field	What it tells you
isMonorepo	Multiple WP packages or JS workspaces
wpPackages[]	Plugin/theme dirs, slugs, versions
wpRoot	Where WP core lives (null = Playground-only)
wpeRemotes[]	Existing WP Engine git remotes
php.hasPhpcs	PHPCS already configured
js.hasBiome	Biome already configured
playground.hasPlayground	Playground scripts/blueprints already exist
hasAgentKit	wp-agent-kit already installed
github.ghInstalled	gh CLI available
github.authenticated	gh auth status passes
github.existingSecrets[]	GitHub Actions secrets already set
github.missingSecrets[]	Required WPE secrets not yet set
github.branchProtection	Protection status per branch

For JSON output (useful in scripts/CI):

node {baseDir}/scripts/detect-structure.mjs

Read: references/monorepo-patterns.md to match the detected structure to a known pattern.

---

2) Ask what the probe couldn't determine

If any of these are unknown after the probe, ask the user before proceeding:

Question	When to ask
WP Engine install slugs (prod/staging/dev)?	wpeRemotes is empty
WP root path (or Playground-only)?	wpRoot is null AND WP packages found
Build command for generated packages?	Has generated *-blocks or *-theme packages
SatisPress URL + API key?	User has premium plugins to manage
Package manager preference?	packageManager is null
Deploy strategy for monorepo?	Multiple WP packages + no WPE remotes
Is gh CLI installed and authenticated?	Check github.ghInstalled and github.authenticated

---

3) Install the agent kit

wp-agent-kit install . --platform github

Or for Pi:

wp-agent-kit install . --platform pi

This installs .agents/skills/, .github/agents/, .github/instructions/, and AGENTS.md.

---

4) Set up PHP tooling

If php.hasComposer is false or php.hasPhpcs is false:

# Create root composer.json (dev tooling — not shipped)
# See references/composer-setup.md for the full template
composer init --no-interaction
composer require --dev squizlabs/php_codesniffer wp-coding-standards/wpcs \
  phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer \
  szepeviktor/phpstan-wordpress

# Register WordPress standards
composer run register-standards

For plugin-level tests (Pest), in each plugin directory:

cd <plugin-dir>
composer require --dev pestphp/pest

Read: references/composer-setup.md for phpcs.xml.dist and phpstan.neon.dist templates.

---

5) Set up Composer repositories

WPackagist (free, for wordpress.org plugins/themes):

composer config repositories.wpackagist composer https://wpackagist.org
composer require composer/installers

SatisPress (optional, for premium plugins):

composer config repositories.satispress composer https://<your-satispress-site>/satispress/
composer config http-basic.<your-satispress-site> <API_KEY> satispress

Read: references/composer-setup.md for auth.json and full setup.

---

6) Set up JS tooling (Biome)

If js.hasBiome is false:

npm install --save-dev @biomejs/biome
npx biome init

Update biome.json to match project style. Reference: wp-agent-os uses:

• indentStyle: "space", indentWidth: 2 (for monorepos with JS packages)
• indentStyle: "tab" (for TS/JS-only projects like wp-agent-kit itself)
• Excludes: wpaos-blocks/, wpaos-theme/ (generated), dist/, vendor/

---

7) Set up git hooks

Create .githooks/pre-push (no Husky dependency — works in all setups):

mkdir -p .githooks
# See ci-gate.md in wp-wpengine skill for the full template
cat > .githooks/pre-push << 'HOOK'
#!/usr/bin/env bash
set -uo pipefail
root="$(git rev-parse --show-toplevel)"
cd "$root"
bash .agents/skills/wp-bootstrap/scripts/ci-gate.sh || exit 1
HOOK
chmod +x .githooks/pre-push

# Activate
git config core.hooksPath .githooks

Or run the bootstrap script which handles all of this:

bash {baseDir}/scripts/bootstrap.sh

---

8) Create wp-cli.yml

# wp-cli.yml — WP-CLI targeting. Commit to repo.

# Local (if WP is in this repo)
# path: ./web     # Bedrock style
# path: .         # WP at root

@production:
  ssh: <install>@<install>.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>

@staging:
  ssh: <install>stg@<install>stg.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>stg

@development:
  ssh: <install>dev@<install>dev.ssh.wpengine.net
  path: /home/wpe-user/sites/<install>dev

---

9) Set up WordPress Playground

Start interactive Playground with all local plugins/themes mounted:

bash {baseDir}/scripts/playground-start.sh

Run headless verification (no browser):

bash {baseDir}/scripts/playground-verify.sh

Package plugins for upload to live sites:

bash {baseDir}/scripts/package-wp.sh

Read: references/monorepo-patterns.md for multi-mount configurations.

---

10) Set up GitHub repo with gh CLI

If github.ghInstalled is true, use the GitHub setup script to:

• Verify authentication and repo access
• Check which required secrets are already set
• Set missing secrets interactively (SSH key, known hosts, WPE install slugs, API credentials)
• Configure branch protection for main, staging, and develop

# Check-only first (no changes)
bash {baseDir}/scripts/setup-github.sh --check-only

# Set missing secrets interactively
bash {baseDir}/scripts/setup-github.sh --set-secrets

# Configure branch protection
bash {baseDir}/scripts/setup-github.sh --set-protection

# Do everything at once
bash {baseDir}/scripts/setup-github.sh --set-all

# Pass WPE slugs to skip those prompts
bash {baseDir}/scripts/setup-github.sh --set-all \
  --wpe-prod=mysite --wpe-staging=mysitestg --wpe-dev=mysitedev

The script handles WPE_SSH_KNOWN_HOSTS automatically via ssh-keyscan, and reads WPE_SSH_KEY from ~/.ssh/wpengine_ed25519 if present (or from 1Password via op read).

If gh is not installed: brew install gh (macOS) or see https://cli.github.com. After install: gh auth login.

---

11) Set up WP Engine GitHub Actions CI/CD

Read the wp-wpengine skill:

• references/ci-gate.md — CI gate with PHP + JS parallel jobs, no-verify policy
• references/github-actions-deploy.md — deploy workflows for dev/staging/production

Required GitHub Secrets:

WPE_SSH_KEY              — private key for WP Engine SSH
WPE_SSH_KNOWN_HOSTS      — output of ssh-keyscan for git.wpengine.com
WPE_PROD_INSTALL         — production install slug
WPE_PROD_GIT_URL         — exact URL from WPE portal (git_push page)
WPE_STAGING_INSTALL / WPE_STAGING_GIT_URL
WPE_DEV_INSTALL / WPE_DEV_GIT_URL
WPE_API_USER / WPE_API_PASSWORD  — for pre-deploy DB backups

---

Agent scripts

Script	Purpose	Usage
scripts/detect-structure.mjs	Probe repo structure + GitHub status → JSON	node {baseDir}/scripts/detect-structure.mjs [--pretty]
scripts/bootstrap.sh	One-command setup (hooks + PHP + JS deps)	bash {baseDir}/scripts/bootstrap.sh
scripts/setup-github.sh	Check/set GitHub secrets + branch protection via gh	bash {baseDir}/scripts/setup-github.sh [--set-all]
scripts/package-wp.sh	Build + zip WP plugins/themes	bash {baseDir}/scripts/package-wp.sh [--dry-run]
scripts/playground-start.sh	Start interactive Playground	bash {baseDir}/scripts/playground-start.sh
scripts/playground-verify.sh	Headless WP verification	bash {baseDir}/scripts/playground-verify.sh

---

References

• references/monorepo-patterns.md — WordPress monorepo structure patterns
• references/composer-setup.md — Composer, WPackagist, SatisPress setup
• wp-wpengine skill → references/ci-gate.md — PHP + JS CI gates, no-verify policy
• wp-wpengine skill → references/github-actions-deploy.md — deploy workflows
• wp-playground skill — Playground CLI, blueprints, PHPUnit, Playwright E2E
• wp-phpstan skill — PHPStan configuration for WordPress