DeltaWP Toolkit User Manual

Start cleaner. Brief smarter. Ship safer.

The DeltaWP Toolkit is a reusable toolkit for creating and maintaining WordPress plugins with low-token LLM workflows. Drop it into any plugin project, brand new or inherited, to bring immediate structure to the work. The root instructions stay short, WordPress-specific depth is deferred into a skill and bundled scripts, and the workflow is designed to be easy to share, fork, and adapt.

It covers the full plugin development lifecycle: scaffolding a new plugin from a secure starter template, retrofitting an existing plugin with structured guidance, running baseline and delta briefings for efficient AI handoff, gathering context for wider codebase analysis, validating with syntax and standards checks, and packaging for distribution.

What is included

AGENTS.md — Always-on project guidance optimized for token efficiency and consistent plugin work
.github/skills/wordpress-plugin-toolkit/ — On-demand WordPress plugin procedures and reference material
template/ — A secure starter plugin with an admin settings page, shortcode example, assets, and uninstall routine
tools/ — PowerShell scripts for scaffolding, baseline briefing, delta briefing, context gathering, validation, and packaging

This toolkit replaces the WP Plugin Dev Toolkit. If you are migrating from the previous toolkit, the workflows are similar but the tooling has been expanded: the briefing system is new, the starter template is more complete, and Docker support is built into the check script rather than requiring separate configuration.

Install

The toolkit is designed to be used in two ways: as a source repository for scaffolding new plugins, or installed directly into an existing plugin project for retrofitting.

As a Scaffolding Source

Clone the toolkit repository and use it as the source for bootstrapping new plugin projects. The scaffold command copies the starter template and installs the toolkit files into the new plugin root.

pwsh -File ./tools/project-bootstrap.ps1 -Name "Example Plugin" -Destination "C:/path/to/project/wp-content/plugins"

As a Retrofit Into an Existing Plugin

Copy the agent guidance, skill bundle, and maintenance scripts into an existing plugin project.

pwsh -File ./tools/install-toolkit.ps1 -Destination "C:/path/to/existing-plugin"

Add -Force to refresh existing toolkit files and -IncludeQualityFiles to also copy .editorconfig and phpcs.xml.dist.

Treat the toolkit repository as the source of truth for the shared template and toolkit files. Prefer updating the generated plugin for plugin-specific work and only change template/ when you want future scaffolds to inherit the change.

Scaffold a New Plugin

Use this flow when starting a new WordPress plugin from scratch. The toolkit bootstraps a self-contained plugin repo from the secure starter template.

Clone or navigate to the DeltaWP Toolkit repository.

Run the bootstrap script with your plugin name and destination.

pwsh -File ./tools/project-bootstrap.ps1 -Name "Example Plugin" -Destination ./generated

The script creates the plugin from template/ and immediately installs AGENTS.md, the WordPress skill bundle, and the maintenance scripts into the new plugin root.
Run the baseline brief to generate a compact model-ready summary for your AI coding assistant.
```
pwsh -File ./tools/plugin-brief.ps1 -Path ./generated/example-plugin
```
Begin development with your AI coding assistant, using the brief as handoff context.

Before publishing, update the plugin metadata defaults in the scaffolded project. Choose a repository name, Composer package name, and license that match your public distribution target.

Retrofit an Existing Plugin

Use this flow when taking over an existing plugin that needs structure, guidance, and a repeatable AI workflow.

Install the toolkit into the existing plugin directory.

pwsh -File ./tools/install-toolkit.ps1 -Destination "C:/path/to/existing-plugin"

Run the baseline brief to understand what you’re working with.

pwsh -File ./tools/plugin-brief.ps1 -Path "C:/path/to/existing-plugin"

Review the brief output: it ranks likely edit targets, lists behavior touch points, and highlights review risks.
Make small, focused changes with your AI coding assistant.

After edits, run the delta brief to summarize only changed files.

pwsh -File ./tools/plugin-delta-brief.ps1 -Path "C:/path/to/existing-plugin"

Run the check script before committing.

pwsh -File ./tools/plugin-check.ps1 -Path "C:/path/to/existing-plugin"

For an existing plugin repo, install the toolkit into that repo instead of copying individual files by hand. The install script ensures all toolkit files land in the right places.

Briefing & Delta Briefing

The briefing system is the core of the low-token workflow. It generates compact, model-ready summaries that give your AI coding assistant exactly what it needs without burning context on irrelevant details.

Baseline Brief

The plugin-brief.ps1 script generates a compact handoff summary. It ranks likely edit targets, lists behavior touch points, and highlights review risks.

pwsh -File ./tools/plugin-brief.ps1 -Path ./generated/example-plugin
pwsh -File ./tools/plugin-brief.ps1 -Path ./generated/example-plugin -OutputPath ./generated/example-plugin/.ai/plugin-brief.md

Output formats: Markdown (default), text, or JSON. Use -OutputPath to write the brief to a file instead of stdout.

Delta Brief

The plugin-delta-brief.ps1 script is the cheap follow-up step. It summarizes only changed files from the current git working tree, or from an explicit -Files list when the plugin is not in git.

pwsh -File ./tools/plugin-delta-brief.ps1 -Path ./generated/example-plugin
pwsh -File ./tools/plugin-delta-brief.ps1 -Path ./generated/example-plugin -Files admin/class-example-plugin-admin.php,assets/css/admin.css
pwsh -File ./tools/plugin-delta-brief.ps1 -Path ./generated/example-plugin -OutputPath ./generated/example-plugin/.ai/plugin-delta-brief.md

Use the baseline brief for initial orientation. Use the delta brief for follow-up edits when only a few files have changed. This keeps token usage low across long development sessions.

Context Gathering

Use plugin-context.ps1 when you need a wider raw inventory after the brief has already narrowed the likely code path. This is for weaker models that need more explicit structure, or for situations where the brief alone isn’t enough context.

pwsh -File ./tools/plugin-context.ps1 -Path ./generated/example-plugin
pwsh -File ./tools/plugin-context.ps1 -Path ./generated/example-plugin -Format Json

The context script provides a full inventory of hooks, filters, shortcodes, REST routes, admin pages, and other touch points. Use it when the brief has identified the relevant area but the AI needs the full picture of that area to work effectively.

The context script is intentionally heavier than the brief. Use it only when the brief isn’t sufficient. The layered approach — brief first, context only when needed — keeps total token usage low.

Validation & Checks

The plugin-check.ps1 script runs syntax linting and standards checks against your plugin. When PHP is available locally, it runs PHP lint directly. When PHP is only available in a Docker container, it runs linting inside the container while the rest of the checks stay local.

Local PHP Available

pwsh -File ./tools/plugin-check.ps1 -Path ./generated/example-plugin

PHP in Docker Container

pwsh -File ./tools/plugin-check.ps1 -Path "C:/path/to/plugin" -DockerComposeService wordpress -ContainerPluginPath "/var/www/html/wp-content/plugins/example-plugin"

When vendor/bin/phpcs is available (via composer install with WordPress Coding Standards), the check script automatically runs PHPCS as well.

Run the check script before every commit. It catches syntax errors, standards violations, and structural problems early, before they reach your AI coding assistant’s context window.

Packaging

When your plugin is ready to ship, use plugin-build.ps1 to assemble a clean distribution archive.

pwsh -File ./tools/plugin-build.ps1 -Path ./generated/example-plugin -OutputDir ./dist

The build script creates a zip archive ready for upload to WordPress.org, a private repository, or direct distribution. It excludes development files, toolkit internals, and any configured ignore patterns.

Run the check script before packaging. The build step should be the final action after all validation passes.

Docker Workflows

When PHP is only available in your WordPress container, use the Docker parameters on the check script so syntax linting happens inside the container while the rest of the checks still run locally.

Example docker-compose.yml volume mapping:

services:
  wordpress:
    image: wordpress:php8.2-apache
    volumes:
      - ./plugins/example-plugin:/var/www/html/wp-content/plugins/example-plugin

With that mapping, the matching check command is:

pwsh -File ./tools/plugin-check.ps1 -Path "C:/path/to/plugin" -DockerComposeService wordpress -ContainerPluginPath "/var/www/html/wp-content/plugins/example-plugin"

All other scripts — briefing, context gathering, scaffolding, and packaging — run locally regardless of where PHP lives. Only the check script needs Docker parameters when local PHP is unavailable.

In Docker-based projects, keep using the same commands and only add the Docker parameters when local PHP is unavailable. The toolkit is designed to degrade gracefully.

Low-Token Strategy

The toolkit is designed around a layered approach to AI context management. Stronger models consume fewer tokens with the compact brief. Weaker models get more explicit structure from the full context inventory.

Typical Flow

Scaffold a plugin from the template, or retrofit an existing one.
Run the baseline brief to generate a compact model-ready summary.
After follow-up edits, run the delta brief to summarize only changed files.
Use the context script when you need a wider inventory of hooks and touch points.
Make small changes.
Run the check script.
Package the plugin when needed.

When to Use Each Layer

Baseline Brief

Initial orientation. Use when starting work on a plugin or handing off to a new AI session. Compact enough for strong models to work from directly.

Delta Brief

Follow-up edits. Use after making changes to keep the AI oriented on what’s different. Cheapest option for ongoing work.

Full Context

Deep analysis. Use when the brief has identified the right area but the AI needs the full picture. Heavier but more complete.

Skill Bundle

On-demand depth. WordPress-specific procedures that load only when the AI needs them. Stays out of context until invoked.

The key insight: don’t send everything at once. Start with the brief. Add context only when the brief isn’t enough. Load the skill bundle only when WordPress-specific depth is needed. This keeps token usage predictable and costs low across long development sessions.

DeltaWP Toolkit User Manual v1.0.0