v1.0.3 — DataForm settings-page reference

A forward-looking option for admin settings pages, plus a green-gate fix.

Added

• DataForm reference (.claude/references/DATAFORM.md) — @wordpress/dataviews' DataForm / DataViews is the direction WordPress core is taking for admin UI, so the kit now offers it alongside the PHP Settings API, with a decision table for which to reach for. Covers the @wordpress/dataviews/wp import path required under wp-scripts, registering the plugin's one option as a REST-exposed schema (show_in_rest + additionalProperties => false), enqueuing via the generated index.asset.php, mounting the React app, and the fields / form config shape.
• It deliberately supplies the security layer the upstream WordPress.org tutorial omits: double capability gating, schema-as-validation, a sanitize_callback for defense in depth, and why the REST nonce authenticates but does not authorise.
• @wordpress/dataviews added to the constitution's default npm dependencies, flagged pre-1.0 (import from /wp, pin the version, re-check on upgrade).

Fixed

• Quality gate is green again — the v1.0.2 autoloader closure's $class parameter tripped a newer WPCS reserved-keyword sniff; renamed to $fqcn. No behaviour change.

Full changelog: https://github.com/pluginslab/wp-agentic-kit/blob/main/CHANGELOG.md

v1.0.0 — Structurally complete

wp-agentic-kit v1.0.0

The first release that is structurally complete. Companion to the talk "A Nova Era do WordPress: De Developer a Arquiteto com Engenharia Agêntica" at WordCamp Portugal 2026, useful well beyond it.

---

Why this kit exists

Senior WordPress developers don't need to write boilerplate anymore. What we still need to do is design the system that writes it.

That system is what this kit is. It's the harness, the conventions, the safety nets, and the workflows that make an AI coding agent (Claude Code, Cursor, Codex, whatever) act like a careful junior on your team instead of a confident autocomplete with no sense of taste.

The shape of the system comes from Anthropic's AI Fluency Framework, the four D's of working productively with AI. The kit makes each one concrete, with files you can read, edit, and steal:

D (English / Portuguese)	What it means	Where it lives in the kit
Delegation / Delegação	Hand structured work to the agent	.claude/skills/ interview-driven workflows that scaffold a plugin or add a feature
Description / Descrição	Tell the agent what's allowed and what we're building	CLAUDE.md, AGENTS.md, .claude/plans/, .claude/references/
Discernment / Discernimento	Get an independent read before signing off	.claude/agents/ read-only sub-agents that audit plans and code
Diligence / Diligência	Make the safety nets non-negotiable	.claude/hooks/ + scripts/quality.sh + tests/

If you watch the talk and then come here, the kit is the talk's argument turned into something you can run in one command.

---

How to start

No clone required. The CLI publishes to npm, so npx fetches it on first use:

npx create-wp-ai-plugin my-plugin

Or the equivalent npm create form:

npm create wp-ai-plugin my-plugin

Pin a specific release with --ref:

npx create-wp-ai-plugin my-plugin --ref v1.0.0

The CLI asks for the plugin name, an optional vendor prefix, a one-sentence description, an author, and your minimum WordPress and PHP versions. Then it:

• Fetches the kit from GitHub at the requested ref
• Derives slug, namespace, constant prefix, and function prefix from your inputs
• Runs find-and-replace across every text file so the example identifiers become yours
• Renames slug-named files (pl-example.php becomes my-plugin.php)
• Pulls WordPress/agent-skills into .claude/skills/ for the per-API expertise (blocks, REST, themes, Playground, and more)
• Runs composer install and npm install
• Initialises a fresh git repo with a scaffold tag

Open the new directory in your coding agent and you're ready to delegate.

---

What's different about this approach

Four concrete things the kit gives the agent to lean on, instead of asking you to re-explain on every prompt:

• A short list of allowed functions. Each project has a constitution.md that names exactly which sanitize and escape functions are allowed. Short, specific, and the agent can't pick a wrong one.

• A written plan before any code. Every feature starts with a spec and a step-by-step plan with file paths. For meaningful features the plan ships as its own PR you review on GitHub before the agent writes anything. For small fixes the plan still gets written, but the agent just proceeds.

• Safety nets that always run. Hooks check lint, security, and progress on every edit and every commit. The agent can't skip them.

• A second opinion before merge. Two read-only sub-agents audit the plan and the code. They flag issues but can't fix anything themselves, which is the whole point.

There are nine chapters of walkthrough docs (docs/) if you want the longer version.

---

What's actually inside

A new plugin scaffolded with v1.0.0 lands with:

my-plugin/
├── CLAUDE.md, AGENTS.md         # what the agent reads on every session
├── README.md
├── .claude/
│   ├── settings.json            # permissions + 4 hooks registered
│   ├── skills/
│   │   ├── wordpress-scaffold/  # once-per-plugin bootstrap workflow
│   │   ├── wordpress-feature/   # per-feature workflow with planning + freeze
│   │   └── wp-* (×15)           # pulled fresh from WordPress/agent-skills
│   ├── plans/
│   │   ├── constitution.md      # project allowlists + defaults
│   │   ├── features/            # per-feature spec/plan/progress
│   │   └── archive/             # shipped features, long-term memory
│   ├── agents/
│   │   ├── plan-reviewer.md
│   │   └── security-reviewer.md
│   ├── hooks/                   # pre-commit, post-edit, user-prompt-submit, stop, session-start
│   ├── commands/                # /plan-freeze, /audit-plan, /ship-feature
│   └── references/              # SECURITY.md, BLOCKS.md, PLANNING.md
├── .mcp.json + mcp/             # 5 WP-flavored MCP servers
├── scripts/                     # quality.sh, open-plan-pr.sh
├── tests/                       # hook test suite (56 cases) + PHPUnit fixture
├── my-plugin.php                # real bootstrap, real REST endpoint
├── includes/api/                # REST controller base + one example endpoint
└── composer.json, package.json, phpcs.xml.dist, readme.txt, uninstall.php

Everything that ships is a worked example, not a placeholder. The example REST endpoint is a real endpoint with a real PHPUnit fixture. The example plan files reference real code.

The nine-chapter walkthrough lives in the kit repo at pluginslab/wp-agentic-kit/docs, not inside each scaffolded plugin (would be noise per-project).

---

What this kit is not

• It is not a code generator. It is a system for delegating to a code generator. If you want a CLI that emits a finished plugin, you want something else.
• It is not a replacement for taste. The hooks catch lint and quality regressions. They do not catch "this feature is the wrong feature." You still review the spec, the plan, and the diff.
• It is not WordPress-specific in spirit. The WP-flavored skills, MCPs, and security rules are; the four-D structure is portable. If you build for another platform, fork it and rewrite the WP pieces.

---

Try it, then read it

The five-minute path:

1. npx create-wp-ai-plugin my-plugin
2. cd my-plugin && code .
3. Open .claude/plans/features/001-example-hello-rest/ and read the spec, plan, findings, progress in that order.
4. Then read the matching code at includes/api/class-rest-hello.php and tests/phpunit/test-rest-hello.php.

The half-hour path:

5. Read docs/ chapters 1 through 3 in order. Chapter 3 (planning) is the new heart of the kit.
6. Open Claude Code (or your agent of choice) in the new project and tell it: "Use the wordpress-feature skill to add a Gutenberg block called order-status that fetches the status from a new REST endpoint." Watch the planning layer do its thing.

---

Prerequisites

• Node 18+ and npm
• PHP 8.2+ and composer
• git on $PATH
• A coding agent (the kit targets Claude Code but AGENTS.md makes it work with Codex, Cursor, Gemini CLI, Copilot, Windsurf)
• gh CLI if you want the plan-freeze flow to open PRs automatically; otherwise push the plan/NNN-slug branch and open the PR by hand

---

License

MIT. Take it, fork it, ship faster.

---

Technical addendum (for contributors and the curious)

What changed since v0.1.0

See CHANGELOG.md for the full surface. Highlights:

• Skill split. wordpress-development retired, replaced by wordpress-scaffold (greenfield) and wordpress-feature (per-PR loop with planning + conditional freeze).
• Planning layer. .claude/plans/ with constitution + per-feature spec/plan/progress (+ optional findings). The UserPromptSubmit hook reads the active plan on every turn, the load-bearing defense against agent drift.
• Sub-agents. Added plan-reviewer alongside the existing security-reviewer. Both are read-only by design.
• Hooks. Added UserPromptSubmit, Stop, and SessionStart to the existing pre-commit and post-edit pair.
• Slash commands. Added /plan-freeze, /audit-plan, /ship-feature for muscle-memory access to common operations.
• Test suite. 56 bash-based hook tests, integrated into scripts/quality.sh. The kit tests itself.
• Constitution split. Two binding levels: strict for security-relevant choices, default for dependencies. Avoids the "agent asks permission for trivia" failure mode while keeping the "no missing escapes" guarantee.
• Conditional plan-freeze. A typo fix and a new REST endpoint no longer go through the same PR ceremony. The checkbox-driven Freeze assessment makes the call explicit.
• SKILL.md trim. Both skill prompts down from ~180 lines to 54 each. Trusts the model more, deduplicates against .claude/references/.
• Worked example. 001-example-hello-rest ships with real code, real tests, real plan artifacts.
• CLI rename fix. Scaffolded plugins now correctly rename pl-example.php to {slug}.php.

Verification

git clone https://github.com/pluginslab/wp-agentic-kit
cd wp-agentic-kit
./tests/run.sh         # 56/56 pass

The hook test suite runs against the four shell hooks with isolated sandboxes per case. No network, no Docker, plain bash.

Roadmap (loose)

v1.0 is structurally complete; future work is depth, not surface.

• More worked examples (a settings page, a block, a CLI command, each with its own plan/spec/code)
• CI workflow that runs tests/run.sh on PRs
• Adapters for non-GitHub hosts (GitLab, Bitbucket, local)
• Temp...

v0.1.0 — first public release

First public release of wp-agentic-kit — a starter kit for building WordPress plugins with agentic engineering. The harness, the skills, the MCP servers, and the hooks Marcel uses every day, packaged so you can install once and start delegating implementation.

Companion to the talk "A Nova Era do WordPress: De Developer a Arquiteto com Engenharia Agêntica" at WordCamp Portugal 2026.

Quick start

npm create wp-ai-plugin my-cool-plugin
# or
npx create-wp-ai-plugin my-cool-plugin

Requires Node 18+, PHP 8.2+, composer, and git on $PATH.

What this version ships

• Node CLI scaffolder (create-wp-ai-plugin on npm) — interactive prompts (plugin name, vendor prefix, description, author, minimum WordPress + PHP versions), then fetches the kit, applies the identity, runs composer install and npm install foregrounded with spinners, and tags the initial commit scaffold so git reset --hard scaffold always works.
• CLAUDE.md / AGENTS.md templates that tell agents how WordPress projects work — security rules, naming conventions, file layout, mandatory checks.
• .claude/settings.json with a curated permission allowlist for WordPress dev (wp-cli, composer, php, npm, git, gh, phpcs, phpunit, phpstan, the kit's MCP servers).
• .mcp.json wiring five project-scoped MCP servers: wp-devdocs, wp-blockmarkup, wp-playground, chrome-devtools, github.
• .claude/skills/ — the kit's own interview-driven wordpress-development scaffolder plus the full WordPress/agent-skills library (15 skills covering blocks, themes, REST, abilities, performance, PHPStan, Playground, WP-CLI, and more) pulled fresh from trunk at scaffold time.
• .claude/agents/security-reviewer.md — read-only sub-agent that audits PHP/JS against the project's SECURITY checklist. Tool-restricted to Read / Grep / Glob / Bash so it physically can't edit code.
• Hooks
  • post-edit.sh — payload-aware lint of just the file the agent edited (phpcs / eslint / stylelint). Non-blocking.
  • pre-commit.sh — filters git commit* and delegates to scripts/quality.sh. Blocking.
  • scripts/quality.sh — single source of truth for the quality suite, gated on tool existence. Usable from Claude Code hooks, .git/hooks/pre-commit, and CI.
• Plugin baseline that makes the gate real from commit one:
  • composer.json (WPCS, PHPCompatibility-WP, PHPUnit, phpunit-polyfills)
  • phpcs.xml.dist (WordPress + PHPCompatibilityWP rules, version configs templated to your choices)
  • package.json (@wordpress/scripts only — pulls eslint, stylelint, webpack, jest, prettier transitively)
  • .eslintrc.json / .stylelintrc.json extending the WP configs so plain ./node_modules/.bin/eslint and stylelint work without arguments.
• Eight-chapter walkthrough in docs/ — CLAUDE.md, skills, MCP servers, sub-agents, hooks, permissions, end-to-end.

Pin a release

npm create wp-ai-plugin my-cool-plugin -- --ref v0.1.0

License

MIT.