WP Plugin Dev Toolkit User Manual v0.2.0

Start cleaner. Repair faster. Ship safer.

The WP Plugin Dev Toolkit is a collection of scripts, templates, checklists, prompt files, and flow files for WordPress plugin development. Drop it into any plugin project, brand new or inherited, to bring immediate structure to the work.

It covers four areas: scaffolding a new plugin with consistent naming and structure, diagnosing and repairing a plugin that has drifted, enforcing a security baseline before shipping, and debugging a local development environment. The default path is prompt-driven: bootstrap your agent with either a workspace instruction file or the generic starter file, tell it either Let's build a new WordPress plugin. or Let's examine this WordPress plugin., and let it route into the right toolkit workflow while it keeps human-readable records.

What is included

• examples/flows/ — Grouped new-build and pre-existing-plugin flow files for LLM-assisted work
• scripts/project/ — Build a plugin profile and inspect an existing plugin’s file structure
• scripts/debug/ — Test REST routes, tail container logs, and collect environment diagnostics
• templates/ — A plugin brief template, a work-log template, an examination-report template, and config snippets for controlled implementation
• prompts/ — Prompt files for scaffold, repair, and security review workflows
• docs/ — Security baseline, repair checklist, debug checklist, and LLM workflow guidance
• site/mu-plugins/ — A diagnostic helper for your local WordPress development environment

Install

The recommended path is to extract this toolkit inside the target plugin directory, rename the folder to _wp-plugin-dev-toolkit, bootstrap your agent with either .github/copilot-instructions.md or AGENT_STARTER.md, and start with one of two prompts: Let's build a new WordPress plugin. or Let's examine this WordPress plugin..

If you want the toolkit project assets copied into the plugin repo up front instead, jump to Alternate Installation at the bottom of this page.

In the default path, keep TOOLKIT_WORK_LOG.md up to date while the LLM works. For examination work, also keep PLUGIN_EXAMINATION_REPORT.md up to date.

Fresh Project Flow

Use this flow when starting a new WordPress plugin from scratch.

The preferred entry is the natural-language starter prompt Let's build a new WordPress plugin.. That should route the agent into the underlying build flow, create or update TOOLKIT_WORK_LOG.md, ask permission before installing toolkit files, and gather the missing brief information before code generation starts.

1. Start with Let's build a new WordPress plugin.
2. Approve the specific toolkit files the LLM says it needs to copy into the project.
3. Run the profile builder to establish naming and generate an inventory.
4. Fill out the plugin brief.
5. Use prompts/scaffold-plugin.prompt.md with your AI coding assistant to generate the initial plugin structure.
6. Review the generated code against docs/PLUGIN_SECURITY_BASELINE.md before keeping it.

Repair Flow

Use this flow when taking over an existing plugin that has structural problems, security gaps, or active errors.

The preferred entry is the natural-language starter prompt Let's examine this WordPress plugin.. That should route the agent into the underlying examination flow so it can inspect structure, gather diagnostics evidence, review security and compatibility risks, and maintain both TOOLKIT_WORK_LOG.md and a formal PLUGIN_EXAMINATION_REPORT.md.

1. Start with Let's examine this WordPress plugin.
2. Approve the specific toolkit files the LLM says it needs to copy into the project.
3. Run scripts/project/inspect-plugin-structure.ps1 to inventory what is present and flag obvious structural problems.
4. Read docs/PLUGIN_REPAIR_CHECKLIST.md for a point-by-point repair sequence.
5. Feed the inspection output and any real error logs into prompts/repair-project.prompt.md to direct repair work with your AI coding assistant.
6. Run prompts/security-review.prompt.md before calling the repair complete.

Example Flows

Use docs/example-flows.md only when you need to override routing or inspect the underlying flow library under examples/flows/README.md. The main user path should be the two starter prompts, not direct flow browsing.

Security Baseline

The toolkit includes docs/PLUGIN_SECURITY_BASELINE.md and prompts/security-review.prompt.md to make security a front-of-process concern rather than an afterthought. The checklist below covers the minimum requirements the baseline enforces. Read the full document for detailed rationale and implementation notes.

Admin

• Capability checks on all admin actions
• Nonce validation on forms and AJAX
• Sanitized input, escaped output

REST

• Explicit permission callbacks on every route
• Route argument sanitization
• No lazy public write routes

Database

• Prepared queries on all variable input
• Typed insert formats
• Deliberate schema changes only

Bootstrap

• Predictable, narrow include paths
• Small activation hooks
• Soft failure for optional modules when possible

Debugging Tools

Three scripts in scripts/debug/ are designed to answer basic runtime questions without digging through WordPress source or Docker logs manually. Run them from inside your plugin project directory after the toolkit is installed.

.\scripts\debug\test-wordpress-routes.ps1 -SiteUrl http://localhost:8080
.\scripts\debug\tail-wordpress-container-logs.ps1 -Tail 120
.\scripts\debug\collect-wordpress-diagnostics.ps1 -SiteUrl http://localhost:8080 -IncludeDocker

Use the query-string REST route while debugging if your pretty permalinks are not settled. A 401 is often more useful than a 404 because it proves the route exists.

Site Diagnostics

A must-use plugin (mu-plugin) is included at site/mu-plugins/wp-plugin-dev-diagnostics.php. Must-use plugins are installed in the wp-content/mu-plugins/ directory and load automatically on every WordPress request, no activation required.

When installed into your local development environment, this plugin:

• Logs fatal shutdowns, plugin activation and deactivation, and upgrade events to a local diagnostics file.
• Exposes an admin-only REST status route at /?rest_route=/plugin-dev-toolkit/v1/status to confirm the environment is wired correctly.

Alternate Installation

Use this only when you want the toolkit project assets copied into the plugin repo up front instead of letting the agent install the minimum needed files during the workflow.

.\scripts\install-toolkit.ps1 -TargetProjectDir C:\path\to\plugin
.\scripts\install-toolkit.ps1 -TargetProjectDir C:\path\to\plugin -WordPressContentDir C:\path\to\wordpress\wp-content

After installation, use either .github/copilot-instructions.md or AGENT_STARTER.md depending on what your coding agent supports. Create TOOLKIT_WORK_LOG.md before AI-assisted edits begin, and for examination work also create PLUGIN_EXAMINATION_REPORT.md.