boilerplate-update（样板更新）

Boilerplate Update Skill

Update WordPress plugins to the latest plugin-boilerplate features.

User Confirmation Rules

ASK for confirmation before:

• Replacing or significantly restructuring files (Loader.php, main plugin class)
• Changing build tools or asset pipeline
• Modifying CI/CD workflows
• Adding new architectural patterns (Abilities API, Blocks)
• Deleting resources belonging to plugin features

Proceed without confirmation for:

• Updating dependency versions
• Adding/renaming scripts with equivalent functionality
• Syncing QA config files
• Copying.opencode commands and.agents/skills

Identity Replacement Script

Use scripts/boilerplate-replace.php (bundled with this skill) for deterministic placeholder replacement. This avoids manual AI search-and-replace across copied upstream files.

Determine the target plugin identity

Before running the script, read these sources from the target plugin to determine the three required parameters:

• plugin-name — Plugin Name: header in the main plugin PHP file (the root .php file containing @wordpress-plugin headers)
• plugin-text-domain — Text Domain: header in the same file
• plugin-namespace — the PSR-4 namespace mapped to src/ in composer.json (autoload.psr-4), or the namespace declaration in src/*.php files

Apply replacements on the cloned boilerplate

Run the script against the cloned boilerplate directory so every file in the reference copy already carries the target plugin's identity before you compare or copy anything:

php tmp/boilerplate-ref/.agents/skills/boilerplate-update/scripts/boilerplate-replace.php \
  --path tmp/boilerplate-ref \
  --plugin-name "My Awesome Plugin" \
  --plugin-namespace "My_Awesome_Plugin" \
  --plugin-text-domain "my-awesome-plugin" \
  --cleanup-setup

This does three things in one pass:

1. Replaces all boilerplate placeholders (demo-plugin, Demo_Plugin, etc.)
2. Strips all BOILERPLATE-DOCS marker sections
3. Removes setup-only artifacts (setup.php, src/Cli/Setup.php, composer autoload/hook entries)

After this step every diff between tmp/boilerplate-ref/ and the target plugin shows only real upstream changes -- no placeholder noise and no setup-only files.

Rename an already-customised plugin

The script also supports renaming a plugin that has already been set up (i.e. the boilerplate defaults have already been replaced). Pass the current identity as --source-plugin-* options and the desired new identity as the regular --plugin-* options:

php boilerplate-replace.php \
  --path /path/to/plugin \
  --source-plugin-name "My Awesome Plugin" \
  --source-plugin-namespace "My_Awesome_Plugin" \
  --source-plugin-text-domain "my-awesome-plugin" \
  --plugin-name "Better Plugin" \
  --plugin-namespace "Better_Plugin" \
  --plugin-text-domain "better-plugin"

When --source-plugin-* options are omitted, the script falls back to the boilerplate defaults (Demo Plugin / Demo_Plugin / demo-plugin), which is the correct behaviour for a fresh clone.

Workflow

1. Clone fresh boilerplate for comparison: git clone --depth 1 https://github.com/JUVOJustin/wordpress-plugin-boilerplate.git./tmp/boilerplate-ref
2. Determine target plugin identity (see above).
3. Run the replacement script on tmp/boilerplate-ref with --cleanup-setup (see above).
4. Use one subtask/subagent per key area. Delegate comparison using diff against tmp/boilerplate-ref/.
5. Present findings to user, categorized by confirmation requirement.
6. Apply changes incrementally.
7. Cleanup: rm -rf tmp/boilerplate-ref

Documentation Reference

The boilerplate includes detailed docs at tmp/boilerplate-ref/docs/:

Read these docs for implementation details. This skill only provides high-level guidance.

Key Areas to Compare

1. PHP (composer.json & QA)

Compare: diff composer.json tmp/boilerplate-ref/composer.json

See docs for details: i18n.mdx, bundeling.mdx

Key items:

• wp-cli/i18n-command - Translation extraction/compilation
• Scripts: i18n:extract, i18n:compile, phpstan, phpcs, phpcbf
• Strauss config in extra.strauss for namespace prefixing
• QA config files: phpcs.xml, phpstan.neon

2. JS & Bundling (package.json, webpack.config.js)

Compare:

• diff package.json tmp/boilerplate-ref/package.json
• diff webpack.config.js tmp/boilerplate-ref/webpack.config.js

See docs for details: bundeling.mdx, wp-env.mdx, create-blocks.mdx

Key items:

• @wordpress/scripts - Bundling, linting, formatting
• @wordpress/env - Containerized WordPress for dev/CI
• Scripts: start, build (with --blocks-manifest), lint:*, format, create-block, env:*
• QA config: .eslintrc

3. GitHub Actions (.github/workflows/)

Compare: diff -r.github/workflows tmp/boilerplate-ref/.github/workflows

• setup.yml - Reusable workflow with dependency caching
• test-analyse.yml - PHPStan, PHPCS, JS linting on push
• deploy.yml - Release automation, translation compilation via wp-env

4. Loader.php

Compare: diff src/Loader.php tmp/boilerplate-ref/src/Loader.php

New methods:

• add_shortcode($tag, $component, $callback)
• add_cli($name, $instance, $args)
• add_ability($ability_class) - Categories auto-register

5. Main Plugin Class

Compare: diff src/*.php tmp/boilerplate-ref/src/Demo_Plugin.php

New patterns:

• enqueue_entrypoint($entry) - See tmp/boilerplate-ref/docs/bundeling.mdx
• register_blocks() - See tmp/boilerplate-ref/docs/create-blocks.mdx

6. i18n Workflow

Scripts: i18n:extract (creates.pot, updates.po) and i18n:compile (generates.mo,.json,.php)

See tmp/boilerplate-ref/docs/i18n.mdx for workflow, caveats, and AI command.

7. Abilities API (WordPress 6.9+)

See tmp/boilerplate-ref/docs/abilities.mdx for interface reference and examples.

Key pattern: $this->loader->add_ability(Abilities\My_Ability::class)

8. Agent Configuration

Compare:

• diff -r.opencode/command tmp/boilerplate-ref/.opencode/command
• diff -r.agents/skills tmp/boilerplate-ref/.agents/skills

See tmp/boilerplate-ref/docs/work-with-ai.mdx for AI integration details.

Sync strategy:

• Add new items from upstream
• Update existing (ask user if diff is significant)
• Ask user before removing local-only items
• Adapt text domain and paths after copying
• Remove redundant skills/commands if upstream now includes them or they are possibly renamed

9. File Control files

Compare:

• diff.distignore tmp/boilerplate-ref/.distignore
• diff.gitignore tmp/boilerplate-ref/.gitignore

Verification

1. Ran composer install && npm install after changes
2. Ran npm run build after changes
3. Ran composer phpstan && composer phpcs after changes
4. Ran npm run lint:js && npm run lint:style after changes
5. Test plugin functionality