feat: add plugin scaffold generator with flavian-starter reference plugin

[PAMulligan]

Summary

Adds a token-substitution plugin generator that produces a PSR-4 autoloaded WordPress plugin in one command. Ships plugins/flavian-starter/ as the canonical scaffold output and parallel to themes/flavian-shop/. Closes #19.

bash scripts/scaffold-plugin.sh my-plugin \
  --name "My Plugin" \
  --description "What it does" \
  --author "Your Name"

Produces a runnable plugin with proper headers, activation hooks, a CPT, a taxonomy, a Settings API page, a server-rendered block, PHPUnit tests (Brain Monkey), and a WordPress-Extra PHPCS ruleset. Feature flags: --no-cpt, --no-taxonomy, --no-settings, --no-block, --minimal, --force, --dry-run.

What the scaffold produces

plugins/<slug>/
├── <slug>.php                  ← main file, headers, autoload
├── uninstall.php
├── composer.json               ← PSR-4 + dev deps
├── phpunit.xml.dist
├── .phpcs.xml.dist
├── README.md
├── src/
│   ├── Plugin.php              ← singleton; class_exists() guards per feature
│   ├── Activator.php           ← flush_rewrite_rules on activation
│   ├── Deactivator.php
│   ├── PostTypes/Event.php
│   ├── Taxonomies/EventCategory.php
│   ├── Admin/Settings.php      ← Settings API page
│   └── Blocks/FeaturedEvent.php
├── assets/
│   ├── css/admin.css, js/admin.js
│   └── blocks/featured-event/  ← block.json + index.js (no build step) + CSS
└── tests/
    ├── bootstrap.php           ← Brain Monkey
    ├── TestCase.php
    ├── PluginTest.php
    └── PostTypes/EventTest.php

Decisions locked in (from scoping)

#	Choice	Implementation
1	flavian-starter reference plugin	plugins/flavian-starter/
2	PSR-4 namespaces	Flavian\Plugins\<PluginClass>, autoload via composer
3	Include one-block example	src/Blocks/FeaturedEvent.php + assets/blocks/featured-event/ (server-rendered, no JS build step)
4	Silent on activation	Activator::activate() only calls flush_rewrite_rules() — no demo content
5	Extend plugin-developer only, no new agents	.claude/agents/plugin-developer.md updated; description + body now point at scaffold and reference plugin
6	CI matrix over plugins/flavian-*/ glob	discover job in plugin-validation.yml enumerates with find ... -name 'flavian-*' + jq; adding a new first-party plugin requires no workflow edit
7	Per-plugin composer.json	Each plugin has its own composer.json, phpunit.xml.dist, .phpcs.xml.dist, vendor/ — independently testable

CI

.github/workflows/plugin-validation.yml (new) runs on PRs touching plugins/flavian-*/, .claude/templates/plugin/, or the scaffold script:

1. scaffold-drift — regenerates flavian-starter from templates, git diff --exit-code. Catches template/reference drift in either direction.
2. discover — emits a matrix of every plugins/flavian-*/ directory.
3. phpunit — composer install + phpunit per plugin.
4. phpcs — composer install + phpcs (via cs2pr for inline PR annotations) per plugin.

Implementation notes worth knowing

• {{PLUGIN_NS_JSON}} token — composer.json's PSR-4 strings need \ per literal backslash in the namespace. The generator computes a JSON-encoded namespace and substitutes it separately from the PHP-source {{PLUGIN_NS}} token. Documented in .claude/templates/plugin/README.md.
• No JS build step for the block — assets/blocks/featured-event/index.js uses window.wp.blocks / wp.element / wp.blockEditor / wp.i18n runtime globals directly. The plugin is usable the instant composer install finishes; users who want JSX can add @wordpress/scripts themselves.
• class_exists() guards in Plugin::boot() — so users can rm -rf src/PostTypes/ after scaffolding without breaking the rest of the plugin. Same pattern in Activator.
• Idempotence verified locally — running the same scaffold command twice produces byte-identical output (confirmed with diff -r). The CI drift check depends on this.
• .gitignore carve-out — .claude/templates/ added to the existing unignore list; .claude/* defaults to ignored.

Test plan

• commitlint passes on this PR.
• plugin-validation / scaffold-drift passes — regenerated flavian-starter matches committed copy.
• plugin-validation / phpunit (flavian-starter) passes — Brain Monkey tests in tests/PluginTest.php and tests/PostTypes/EventTest.php run green after composer install.
• plugin-validation / phpcs (flavian-starter) passes — no WordPress-Extra violations in the scaffold output.
• Visual regression workflow (feat: integrate visual regression testing for theme changes #69) and the rest of CI unaffected (no theme files touched).
• Spot check: scaffold a throwaway plugin locally — bash scripts/scaffold-plugin.sh demo --author "Demo" --force produces a working plugins/demo/ that passes its own composer test.

🤖 Generated with Claude Code