@the-bearded-bear/claude-craft 9.2.0-next.32ff465 → 9.2.0-next.fa3e789

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/Dev/i18n/base/WordPress/checklists/new-feature.md +59 -0
  2. package/Dev/i18n/base/WordPress/checklists/pre-commit.md +125 -0
  3. package/Dev/i18n/base/WordPress/checks/all.md +257 -0
  4. package/Dev/i18n/base/WordPress/checks/architecture.md +157 -0
  5. package/Dev/i18n/base/WordPress/checks/code-quality.md +158 -0
  6. package/Dev/i18n/base/WordPress/checks/security.md +158 -0
  7. package/Dev/i18n/base/WordPress/checks/testing.md +157 -0
  8. package/Dev/i18n/base/WordPress/commands/check.md +28 -0
  9. package/Dev/i18n/base/WordPress/rules/00-project-context.md.template +169 -0
  10. package/Dev/i18n/base/WordPress/rules/02-architecture-wordpress.md +172 -0
  11. package/Dev/i18n/base/WordPress/rules/03-coding-standards.md +98 -0
  12. package/Dev/i18n/base/WordPress/rules/06-tooling.md +146 -0
  13. package/Dev/i18n/base/WordPress/rules/07-testing-wordpress.md +150 -0
  14. package/Dev/i18n/base/WordPress/rules/08-quality-tools.md +161 -0
  15. package/Dev/i18n/base/WordPress/rules/11-security-wordpress.md +174 -0
  16. package/Dev/i18n/base/WordPress/skills/woocommerce/REFERENCE.md +214 -0
  17. package/Dev/i18n/base/WordPress/skills/woocommerce/SKILL.md +40 -0
  18. package/Dev/i18n/base/WordPress/skills/woocommerce/checklist.md +66 -0
  19. package/Dev/i18n/base/WordPress/templates/block.md +235 -0
  20. package/Dev/i18n/base/WordPress/templates/plugin-bootstrap.md +215 -0
  21. package/Dev/i18n/base/WordPress/templates/rest-endpoint.md +246 -0
  22. package/Dev/i18n/de/WordPress/CLAUDE.md.template +100 -0
  23. package/Dev/i18n/de/WordPress/agents/wordpress-reviewer.md +348 -0
  24. package/Dev/i18n/de/WordPress/checks/all.md +242 -0
  25. package/Dev/i18n/de/WordPress/commands/check.md +28 -0
  26. package/Dev/i18n/en/WordPress/CLAUDE.md.template +100 -0
  27. package/Dev/i18n/en/WordPress/agents/wordpress-reviewer.md +348 -0
  28. package/Dev/i18n/en/WordPress/checks/all.md +241 -0
  29. package/Dev/i18n/en/WordPress/commands/check.md +28 -0
  30. package/Dev/i18n/es/WordPress/CLAUDE.md.template +100 -0
  31. package/Dev/i18n/es/WordPress/agents/wordpress-reviewer.md +348 -0
  32. package/Dev/i18n/es/WordPress/checks/all.md +241 -0
  33. package/Dev/i18n/es/WordPress/commands/check.md +28 -0
  34. package/Dev/i18n/fr/WordPress/CLAUDE.md.template +100 -0
  35. package/Dev/i18n/fr/WordPress/agents/wordpress-reviewer.md +348 -0
  36. package/Dev/i18n/fr/WordPress/checks/all.md +242 -0
  37. package/Dev/i18n/fr/WordPress/commands/check.md +28 -0
  38. package/Dev/i18n/pt/WordPress/CLAUDE.md.template +100 -0
  39. package/Dev/i18n/pt/WordPress/agents/wordpress-reviewer.md +348 -0
  40. package/Dev/i18n/pt/WordPress/checks/all.md +241 -0
  41. package/Dev/i18n/pt/WordPress/commands/check.md +28 -0
  42. package/Dev/scripts/check-config.sh +1 -1
  43. package/Dev/scripts/install-from-config.sh +3 -0
  44. package/Dev/scripts/install-wordpress-rules.sh +153 -0
  45. package/Dev/stack-profiles/wordpress/permissions.txt +10 -0
  46. package/Dev/stack-profiles/wordpress/quality.md +4 -0
  47. package/Dev/stack-profiles/wordpress/stack.txt +2 -0
  48. package/README.md +5 -2
  49. package/bundles/cursor/.cursorrules +2 -1
  50. package/bundles/windsurf/.windsurfrules +2 -1
  51. package/cli/lib/tech-registry.js +10 -0
  52. package/package.json +1 -1
@@ -0,0 +1,59 @@
1
+ # New Feature Checklist - WordPress
2
+
3
+ Use this checklist when adding a feature to a plugin or block theme (a block, an admin screen, a REST endpoint, a WP-CLI command, a setting, a template). Apply the TDD cycle: write the failing test first, then the code.
4
+
5
+ ## 1. Analysis (before code)
6
+
7
+ - [ ] Goal, acceptance criteria and user roles that can use the feature are written down
8
+ - [ ] Assumptions stated: minimum WordPress and PHP versions, whether multisite is supported, expected data volume, front-end versus admin context
9
+ - [ ] Core already offers it? Check core APIs, blocks, block bindings, patterns and `theme.json` before writing custom code
10
+ - [ ] Extension points identified: which hooks the feature uses, and which prefixed actions and filters it exposes
11
+ - [ ] Risk assessed: touches data model, uploads, remote calls, capabilities, or front-end output
12
+ - [ ] Impact written down (files, migrations, uninstall changes) and validated if more than 5 files or any breaking change
13
+
14
+ ## 2. Design
15
+
16
+ - [ ] Domain logic planned as plain PHP classes (no WordPress calls); hook callbacks stay thin adapters
17
+ - [ ] Data storage chosen: option (array, `autoload` false), registered meta, custom post type/taxonomy, or custom table with `dbDelta()` and a version option
18
+ - [ ] Capability model defined: which capability gates each action; custom capabilities added on activation and removed on uninstall
19
+ - [ ] Namespace/prefix, text domain, script handles and REST namespace follow the project convention
20
+ - [ ] Performance considered: bounded queries (no `posts_per_page => -1`), `no_found_rows`, no meta_query on large tables, caching and invalidation plan
21
+ - [ ] Accessibility and i18n considered (labels, focus, translatable strings, RTL)
22
+
23
+ ## 3. Implementation (TDD)
24
+
25
+ - [ ] Failing tests written first (unit for domain, `WP_UnitTestCase` for hooks/REST/DB, Jest for blocks, Playwright for the main journey)
26
+ - [ ] Hooks registered in one `register()` method on the right hook (`init`, `rest_api_init`, `admin_init`, ...)
27
+ - [ ] REST route: `permission_callback`, `args` with validate and sanitize callbacks, schema, proper `WP_Error` statuses (see `templates/rest-endpoint.md`)
28
+ - [ ] Block: `block.json` apiVersion 3, `render.php` with late escaping, deprecations if markup changes, registration through the build manifest (see `templates/block.md`)
29
+ - [ ] Admin screen or setting: Settings API, capability on the menu entry, nonce on custom forms
30
+ - [ ] WP-CLI command: registered under `WP_CLI`, reuses the domain services, documents synopsis and examples
31
+ - [ ] Assets: enqueued only where needed with `*.asset.php` dependencies; no inline tags
32
+ - [ ] Strings translatable with the literal text domain; JS translations loaded with `wp_set_script_translations()`
33
+ - [ ] Capability check and nonce on every state change; input sanitized, output escaped; SQL prepared
34
+
35
+ ## 4. Quality
36
+
37
+ - [ ] `phpcs`, `phpstan`, `wp-scripts lint-js` clean
38
+ - [ ] Coverage >= 80%; authorization and sanitization paths covered, including denied cases
39
+ - [ ] Plugin Check has no new errors
40
+ - [ ] Tested on the minimum and the latest declared PHP and WordPress versions (and multisite if supported)
41
+ - [ ] Manual check in `wp-env` with `WP_DEBUG` on: no notices, warnings or deprecated calls
42
+
43
+ ## 5. Lifecycle
44
+
45
+ - [ ] Activation routine idempotent; deactivation unschedules cron events
46
+ - [ ] `uninstall.php` removes the feature's options, tables, cron events, roles and capabilities
47
+ - [ ] Upgrade routine handles existing installs (`db_version` comparison)
48
+ - [ ] Privacy exporter and eraser registered if personal data is stored
49
+
50
+ ## 6. Documentation and Delivery
51
+
52
+ - [ ] Hooks documented with docblocks (`@since`, `@param`); README / `readme.txt` updated
53
+ - [ ] CHANGELOG entry added; version bumped consistently if releasing
54
+ - [ ] Atomic Conventional Commits (`feat(rest): add reports endpoint`)
55
+ - [ ] Pull request lists the capability, nonce, escaping and SQL decisions for the reviewer
56
+
57
+ ## 7. If the project depends on WooCommerce
58
+
59
+ If the project depends on WooCommerce (plugin header `Requires Plugins: woocommerce`, `wc_*` calls, `before_woocommerce_init` hook), also apply `.claude/skills/woocommerce/checklist.md` (HPOS compatibility, CRUD usage, Store API and block checkout extensibility, payment and webhook security).
@@ -0,0 +1,125 @@
1
+ # Pre-Commit Checklist - WordPress
2
+
3
+ ## Quick Validation Before Each Commit
4
+
5
+ All commands run in Docker (`docker compose exec app ...`); suites that need WordPress loaded run in the `wp-env` containers (`npx wp-env run tests-cli ...`). Keep one script or `make ci` target that chains the steps below so the local gate equals the CI gate.
6
+
7
+ ### Code Quality (PHP)
8
+
9
+ - [ ] WordPress Coding Standards pass (`vendor/bin/phpcs`), auto-fix with `vendor/bin/phpcbf`
10
+ - [ ] PHPStan passes at the project level (`vendor/bin/phpstan analyse`), baseline not grown
11
+ - [ ] New `phpcs:ignore` comments name the sniff, are one line and carry a reason
12
+ - [ ] No `var_dump`, `print_r`, `error_log`, `die()` or commented-out code left behind
13
+ - [ ] Every new global has the project prefix or namespace; every new PHP file has `defined( 'ABSPATH' ) || exit;` when directly reachable
14
+ - [ ] Code does not use syntax newer than the declared `Requires PHP`
15
+ - [ ] Methods < 10 lines (limit 20), nesting <= 3, parameters <= 4
16
+
17
+ ### Code Quality (JavaScript / Blocks)
18
+
19
+ - [ ] `npx wp-scripts lint-js` and `lint-style` pass with zero warnings
20
+ - [ ] `npx wp-scripts format --check` passes
21
+ - [ ] `build/` regenerated (`npx wp-scripts build --blocks-manifest`) when block sources changed, if `build/` is committed
22
+ - [ ] Block markup changes include a `deprecated` entry and a fixture
23
+ - [ ] Strings use `__()` from `@wordpress/i18n` with the plugin text domain
24
+
25
+ ### Tests
26
+
27
+ - [ ] PHPUnit passes (`npx wp-env run tests-cli --env-cwd=wp-content/plugins/<slug> vendor/bin/phpunit`)
28
+ - [ ] Jest passes (`npx wp-scripts test-unit-js`)
29
+ - [ ] New behavior has tests written first (Red, Green, Refactor)
30
+ - [ ] New handlers and routes have denied-path tests (logged out, wrong role, bad nonce, invalid input)
31
+ - [ ] Bug fixes include a regression test that failed before the fix
32
+ - [ ] Coverage maintained at 80% or higher
33
+ - [ ] No `markTestSkipped`, `test.skip` or `test.only` added without a ticket
34
+
35
+ ### Security
36
+
37
+ - [ ] Every state-changing handler checks `current_user_can()` with a specific capability and verifies a nonce
38
+ - [ ] Every REST route has a `permission_callback`; writes never use `__return_true`
39
+ - [ ] Superglobals read with existence check, `wp_unslash()` and a sanitizer
40
+ - [ ] All output escaped late (`esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`)
41
+ - [ ] All SQL with variables uses `$wpdb->prepare()`
42
+ - [ ] No `unserialize()` on user data, no `eval`, no dynamic `include`
43
+ - [ ] No secrets, keys or `.env` staged
44
+ - [ ] `composer audit` and `npm audit --omit=dev --audit-level=moderate` pass
45
+
46
+ ### Internationalization and Assets
47
+
48
+ - [ ] New user-facing strings are translatable with a literal text domain
49
+ - [ ] Scripts and styles enqueued with `*.asset.php` dependencies and version; no inline tags
50
+ - [ ] `.pot` regenerated if strings changed (`wp i18n make-pot`) when the project commits it
51
+
52
+ ### Release Metadata
53
+
54
+ - [ ] Plugin header, `readme.txt` (`Stable tag`, `Tested up to`, `Requires at least`, `Requires PHP`) and `package.json` versions consistent when releasing
55
+ - [ ] Plugin Check has no errors on the built ZIP when releasing
56
+ - [ ] `uninstall.php` updated when new options, tables, cron events or roles are added
57
+
58
+ ### Documentation and Git
59
+
60
+ - [ ] README / readme.txt / docs updated when features, hooks or settings changed
61
+ - [ ] CHANGELOG updated if applicable
62
+ - [ ] Commit message follows Conventional Commits (`feat(blocks): add report block`)
63
+ - [ ] Commit is atomic; branch up to date with `main`
64
+ - [ ] No unrelated files staged (`git status`, `git diff --staged`)
65
+
66
+ ### If the project depends on WooCommerce
67
+
68
+ If the project depends on WooCommerce (plugin header `Requires Plugins: woocommerce`, `wc_*` calls, `before_woocommerce_init` hook), also apply `.claude/skills/woocommerce/checklist.md`.
69
+
70
+ ## Automated Validation
71
+
72
+ ### CI gate script
73
+
74
+ ```bash
75
+ #!/usr/bin/env bash
76
+ # scripts/ci.sh - same steps locally and in CI
77
+ set -euo pipefail
78
+
79
+ vendor/bin/phpcs
80
+ vendor/bin/phpstan analyse --memory-limit=1G
81
+ npx wp-scripts lint-js
82
+ npx wp-scripts lint-style
83
+ npx wp-scripts test-unit-js
84
+ npx wp-env start
85
+ npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit
86
+ composer audit
87
+ npm audit --omit=dev --audit-level=moderate
88
+ ```
89
+
90
+ ### Git pre-commit hook (Lefthook)
91
+
92
+ ```yaml
93
+ # lefthook.yml
94
+ pre-commit:
95
+ parallel: true
96
+ commands:
97
+ phpcs:
98
+ glob: "*.php"
99
+ run: docker compose exec -T app vendor/bin/phpcs {staged_files}
100
+ js:
101
+ glob: "*.{js,jsx,ts,tsx}"
102
+ run: docker compose exec -T app npx wp-scripts lint-js {staged_files}
103
+ pre-push:
104
+ commands:
105
+ phpstan:
106
+ run: docker compose exec -T app vendor/bin/phpstan analyse --memory-limit=1G
107
+ tests:
108
+ run: docker compose exec -T app sh -c 'npx wp-scripts test-unit-js && npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit'
109
+ ```
110
+
111
+ Hooks are requirements, CLAUDE.md is a suggestion.
112
+
113
+ ## Quick Commands
114
+
115
+ ```bash
116
+ docker compose exec app vendor/bin/phpcbf
117
+ docker compose exec app vendor/bin/phpcs
118
+ docker compose exec app vendor/bin/phpstan analyse
119
+ docker compose exec app npx wp-scripts lint-js --fix
120
+ docker compose exec app npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit
121
+ ```
122
+
123
+ ## Final Check
124
+
125
+ If any box is unchecked, do not commit. Fix first, then re-run `./scripts/ci.sh`.
@@ -0,0 +1,257 @@
1
+ # Check Complete WordPress Compliance
2
+
3
+ ## Arguments
4
+
5
+ $ARGUMENTS (optional: path to the plugin or theme to analyze)
6
+
7
+ ## Plan Mode
8
+
9
+ > Plan mode is activated automatically when the scope spans PHP, block JavaScript and theme configuration, or requires cross-cutting investigation.
10
+
11
+ ## MISSION
12
+
13
+ Perform a complete compliance audit of the WordPress plugin or block theme (WordPress 7.1 line; PHP 7.4 minimum, 8.3+ recommended) by orchestrating the 4 major checks: Architecture, Code Quality, Tests, and Security. Produce a consolidated report with an overall score out of 100 points. Out of scope: Bedrock, hosting and multi-environment deployment, generic PHP design (see the `php` stack), frontend frameworks outside the block editor.
14
+
15
+ ### Step 1: Audit Preparation
16
+
17
+ Prepare audit environment:
18
+ - [ ] Identify project path to audit
19
+ - [ ] Verify presence of configuration files (main plugin file header, `composer.json`, `package.json`, `.wp-env.json`, `.phpcs.xml.dist`, `phpstan.neon.dist`, `phpunit.xml.dist`, `readme.txt`, `theme.json`, `block.json`, `playwright.config.ts`)
20
+ - [ ] List main directories (`src/`, `includes/`, `build/`, `blocks/`, `templates/`, `parts/`, `patterns/`, `tests/`, `languages/`)
21
+ - [ ] Identify WordPress minimum and tested versions, PHP minimum, project type (plugin, block theme, both), block count, and whether WooCommerce is a dependency
22
+
23
+ ```bash
24
+ docker compose exec app sh -c 'head -40 *.php | grep -nE "Plugin Name|Version|Requires at least|Requires PHP|Requires Plugins|Text Domain"'
25
+ docker compose exec app cat .wp-env.json
26
+ docker compose exec app grep -nE '"(wordpress|php)"|"require(-dev)?"|szepeviktor|wp-coding-standards|phpunit-polyfills' composer.json
27
+ docker compose exec app grep -nE '@wordpress/(scripts|env|create-block|e2e-test-utils-playwright)|@playwright/test' package.json
28
+ ```
29
+
30
+ **Note**: If $ARGUMENTS provided, use it as project path, otherwise use current directory.
31
+
32
+ ### Step 2: Architecture Audit (25 points)
33
+
34
+ Execute architecture check: `/wordpress:check architecture` or follow `.claude/references/wordpress/checks/architecture.md`
35
+
36
+ **Evaluated Criteria**:
37
+ - Plugin/theme layout and bootstrap (5 pts)
38
+ - Hooks and separation of concerns (6 pts)
39
+ - Blocks, themes and the Interactivity API (5 pts)
40
+ - REST API, settings and data (4 pts)
41
+ - i18n, assets and compatibility (5 pts)
42
+
43
+ **Reference**: `.claude/references/wordpress/checks/architecture.md`
44
+
45
+ ### Step 3: Code Quality Audit (25 points)
46
+
47
+ Execute code quality check: `/wordpress:check code-quality` or follow `.claude/references/wordpress/checks/code-quality.md`
48
+
49
+ **Evaluated Criteria**:
50
+ - PHP standards (PHPCS WordPress) and static analysis (PHPStan with phpstan-wordpress) (7 pts)
51
+ - JavaScript and block editor code (`@wordpress/scripts`, ESLint) (5 pts)
52
+ - WordPress API usage and performance (queries, options, caching) (5 pts)
53
+ - KISS/DRY/YAGNI and complexity (3 pts)
54
+ - Error handling, documentation and release hygiene (Plugin Check, readme) (5 pts)
55
+
56
+ **Reference**: `.claude/references/wordpress/checks/code-quality.md`
57
+
58
+ ### Step 4: Testing Audit (25 points)
59
+
60
+ Execute testing check: `/wordpress:check testing` or follow `.claude/references/wordpress/checks/testing.md`
61
+
62
+ **Evaluated Criteria**:
63
+ - Code coverage, 80% minimum (5 pts)
64
+ - PHP integration and unit tests (`WP_UnitTestCase`, wp-env) (7 pts)
65
+ - JavaScript and block tests (4 pts)
66
+ - End-to-end tests (Playwright) (5 pts)
67
+ - Isolation, speed and structure (4 pts)
68
+
69
+ **Reference**: `.claude/references/wordpress/checks/testing.md`
70
+
71
+ ### Step 5: Security Audit (25 points)
72
+
73
+ Execute security check: `/wordpress:check security` or follow `.claude/references/wordpress/checks/security.md`
74
+
75
+ **Evaluated Criteria**:
76
+ - Authorization and nonces (7 pts)
77
+ - Sanitization and escaping (7 pts)
78
+ - Database and injection (4 pts)
79
+ - REST, AJAX and outbound requests (3 pts)
80
+ - Files, secrets and supply chain (4 pts)
81
+
82
+ **Reference**: `.claude/references/wordpress/checks/security.md`
83
+
84
+ ### Step 6: WooCommerce Extension (conditional, not scored here)
85
+
86
+ If the project depends on WooCommerce (plugin header `Requires Plugins: woocommerce`, `wc_*` calls, `before_woocommerce_init` hook), also apply `.claude/skills/woocommerce/checklist.md` and report its findings in a separate section after the scored report.
87
+
88
+ ### Step 7: Consolidation and Global Scoring
89
+
90
+ - [ ] Sum the 4 scores (max 100 points)
91
+ - [ ] Identify critical categories (<50%)
92
+ - [ ] List all critical cross-cutting issues
93
+ - [ ] Prioritize actions by impact/effort
94
+ - [ ] Produce final consolidated report
95
+
96
+ **Grading Scale**:
97
+ - 90-100: Excellent - Reference project
98
+ - 75-89: Very Good - Some minor improvements
99
+ - 60-74: Acceptable - Requires improvements
100
+ - 40-59: Insufficient - Major refactoring required
101
+ - 0-39: Critical - Complete overhaul necessary
102
+
103
+ ### Step 8: Recommendations and Action Plan
104
+
105
+ - [ ] Identify top 3 priority actions across all categories
106
+ - [ ] Estimate effort (Low/Medium/High) and impact (Low/Medium/High) for each
107
+ - [ ] Propose implementation order
108
+ - [ ] Suggest quick wins (high impact/effort ratio)
109
+
110
+ **Version health** (reported in the executive summary, not scored):
111
+ - WordPress 7.1 is the reference line; flag a `Tested up to` that lags the current release, and a `Requires at least` far below the APIs actually used.
112
+ - PHP: 7.4 is the WordPress minimum, 8.3+ is recommended; flag a plugin that raises its floor without updating `Requires PHP` and `composer.json`.
113
+ - Tooling references: `@wordpress/scripts` 37, `@wordpress/env` 12, WPCS 3.4, `szepeviktor/phpstan-wordpress` 2.0, `yoast/phpunit-polyfills` 4.0, Playwright 1.65; flag major versions behind.
114
+ - Report the release readiness: Plugin Check result, `readme.txt` consistency, translation readiness.
115
+
116
+ ## OUTPUT FORMAT
117
+
118
+ ```
119
+ WORDPRESS COMPLIANCE AUDIT - COMPLETE REPORT
120
+ ============================================
121
+
122
+ OVERALL SCORE: XX/100
123
+
124
+ COMPLIANCE LEVEL: [Excellent/Very Good/Acceptable/Insufficient/Critical]
125
+
126
+ WordPress: X.Y PHP: X.Y Type: [plugin/block theme/both] WooCommerce: [yes/no] E2E: [playwright/none]
127
+
128
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
129
+
130
+ SCORES BY CATEGORY:
131
+
132
+ ARCHITECTURE : XX/25 [██████████░░░░░░░░░░] XX%
133
+ CODE QUALITY : XX/25 [██████████░░░░░░░░░░] XX%
134
+ TESTS : XX/25 [██████████░░░░░░░░░░] XX%
135
+ SECURITY : XX/25 [██████████░░░░░░░░░░] XX%
136
+
137
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
138
+
139
+ OVERALL STRENGTHS:
140
+ 1. [Strength identified in multiple categories]
141
+ 2. [Other major strength]
142
+ 3. [Third strength]
143
+
144
+ OVERALL IMPROVEMENTS:
145
+ 1. [Cross-cutting improvement]
146
+ 2. [Other recommended improvement]
147
+ 3. [Third improvement]
148
+
149
+ CRITICAL ISSUES:
150
+ 1. [Critical issue #1 - affected category]
151
+ 2. [Critical issue #2 - affected category]
152
+ 3. [Critical issue #3 - affected category]
153
+
154
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
155
+
156
+ DETAILS BY CATEGORY:
157
+
158
+ ┌─────────────────────────────────────────────┐
159
+ │ ARCHITECTURE (XX/25) │
160
+ └─────────────────────────────────────────────┘
161
+
162
+ Sub-scores:
163
+ • Layout and bootstrap : XX/5
164
+ • Hooks and separation of concerns : XX/6
165
+ • Blocks, themes, Interactivity API : XX/5
166
+ • REST, settings and data : XX/4
167
+ • i18n, assets and compatibility : XX/5
168
+
169
+ Strengths:
170
+ - [Architecture strengths]
171
+
172
+ Issues:
173
+ - [Architecture issues]
174
+
175
+ [Similar sections for Code Quality, Tests, and Security...]
176
+
177
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
178
+
179
+ WOOCOMMERCE EXTENSION (only if applicable, not scored):
180
+ - [Findings from .claude/skills/woocommerce/checklist.md]
181
+
182
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
183
+
184
+ TOP 3 PRIORITY ACTIONS (ALL CATEGORIES):
185
+
186
+ 1. CRITICAL - [Action #1]
187
+ Category : [Architecture/Quality/Tests/Security]
188
+ Impact : [High/Medium/Low]
189
+ Effort : [High/Medium/Low]
190
+ Priority : IMMEDIATE
191
+
192
+ Detailed description:
193
+ [Explanation of problem and proposed solution]
194
+
195
+ Affected files:
196
+ - [file:line]
197
+
198
+ Correction example:
199
+ [Code or correction command]
200
+
201
+ 2. IMPORTANT - [Action #2]
202
+ [Same format...]
203
+
204
+ 3. RECOMMENDED - [Action #3]
205
+ [Same format...]
206
+
207
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
208
+
209
+ QUICK WINS (High Impact / Low Effort):
210
+
211
+ - [Quick win #1] - Category: [X] - Impact: [X] - Effort: [X]
212
+ - [Quick win #2] - Category: [X] - Impact: [X] - Effort: [X]
213
+ - [Quick win #3] - Category: [X] - Impact: [X] - Effort: [X]
214
+
215
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
216
+
217
+ RECOMMENDED ACTION PLAN:
218
+
219
+ WEEK 1 (Immediate):
220
+ - [ ] [Critical action #1]
221
+ - [ ] [Priority quick win]
222
+
223
+ WEEK 2-4 (Short term):
224
+ - [ ] [Important action #2]
225
+ - [ ] [Other quick wins]
226
+
227
+ MONTH 2-3 (Medium term):
228
+ - [ ] [Recommended action #3]
229
+ - [ ] [Progressive improvements]
230
+
231
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
232
+
233
+ EXECUTIVE SUMMARY:
234
+
235
+ [Summary paragraph on overall project state, major strengths,
236
+ major weaknesses, version health (WordPress, PHP, tooling),
237
+ release readiness (Plugin Check, readme, translations), and
238
+ recommended trajectory. Say whether the project is
239
+ production-ready, requires corrections, or needs refactoring.]
240
+
241
+ General Recommendation: [Production-ready / Minor corrections /
242
+ Major refactoring / Overhaul necessary]
243
+
244
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
245
+ ```
246
+
247
+ ## IMPORTANT NOTES
248
+
249
+ - This command orchestrates the 4 specialized audits
250
+ - Use Docker for all analysis tools (`docker compose exec app ...`, `npx wp-env run ...` for suites that need WordPress loaded)
251
+ - Provide concrete examples with file:line for each problem
252
+ - Prioritize actions based on Impact/Effort matrix
253
+ - Security problems are ALWAYS top priority; missing capability checks, injectable queries and unauthenticated write routes are release blockers
254
+ - Generic PHP concerns are delegated to the `php` stack; frontend frameworks outside the block editor to their own stacks
255
+ - Propose automatable corrections (CI workflow with PHPCS, PHPStan, Plugin Check, wp-env tests; pre-commit hooks)
256
+ - Report must be actionable, not just descriptive
257
+ - Adapt recommendations to project business context
@@ -0,0 +1,157 @@
1
+ # Check WordPress Architecture
2
+
3
+ ## Arguments
4
+
5
+ $ARGUMENTS (optional: path to the plugin or theme to analyze)
6
+
7
+ ## Plan Mode
8
+
9
+ > Plan mode is activated automatically when the scope spans several plugins/themes, or mixes PHP, block JavaScript and theme configuration.
10
+
11
+ ## MISSION
12
+
13
+ Audit the architecture of a WordPress plugin or block theme (WordPress 7.1 line; PHP 7.4 minimum, 8.3+ recommended). Stance: **extend core through its public APIs (hooks, blocks, REST, Settings API) and keep the plugin a thin wiring layer over plain, testable PHP classes**. Never modify core, never fork behavior that a filter can change. Out of scope: Bedrock, hosting and multi-environment deployment, generic PHP design (see the `php` stack), frontend frameworks outside the block editor.
14
+
15
+ All commands run in Docker (`docker compose exec app ...`, or `npx wp-env run cli ...` when WordPress itself must be loaded).
16
+
17
+ ### Step 1: Plugin / Theme Layout and Bootstrap (5 points)
18
+
19
+ ```bash
20
+ docker compose exec app ls
21
+ docker compose exec app sh -c 'head -40 *.php | grep -nE "Plugin Name|Version|Requires at least|Requires PHP|Requires Plugins|Text Domain|Domain Path|License"'
22
+ docker compose exec app grep -rnE "defined\( *'ABSPATH' *\)" --include=*.php . --exclude-dir=vendor --exclude-dir=node_modules
23
+ docker compose exec app ls uninstall.php composer.json readme.txt theme.json
24
+ ```
25
+
26
+ Checklist:
27
+ - [ ] Main plugin file has a complete header: `Plugin Name`, `Version`, `Requires at least`, `Requires PHP`, `Text Domain` matching the slug, `License`; `Requires Plugins` lists hard dependencies by slug
28
+ - [ ] The main file only bootstraps: constants, autoloader, activation/deactivation hooks, one `plugins_loaded` (or later) call that starts the plugin; no feature logic at file scope
29
+ - [ ] Every PHP file that can be requested directly starts with `defined( 'ABSPATH' ) || exit;` (files that only declare classes are still guarded)
30
+ - [ ] Unique prefix or namespace for every global (functions, constants, options, hooks, post types, REST namespaces, script handles); no generic names like `init_settings()`
31
+ - [ ] Composer PSR-4 autoload (or a single documented autoloader); no `require_once` chains scattered through the code
32
+ - [ ] Activation, deactivation and `uninstall.php` (or `register_uninstall_hook`) exist and are idempotent; uninstall removes options, custom tables and cron events the plugin created
33
+ - [ ] Block themes: `theme.json` (version 3), `style.css` header, `templates/`, `parts/`, `patterns/`; classic PHP templates only where justified
34
+
35
+ **Scoring**: 5 pts, minus 1 per violation (min 0).
36
+
37
+ ### Step 2: Hooks and Separation of Concerns (6 points)
38
+
39
+ ```bash
40
+ docker compose exec app grep -rnE "add_(action|filter)\(" --include=*.php . --exclude-dir=vendor --exclude-dir=node_modules
41
+ docker compose exec app grep -rnE "remove_(action|filter)\(" --include=*.php . --exclude-dir=vendor
42
+ docker compose exec app grep -rnE '\bglobal \$|\$GLOBALS' --include=*.php . --exclude-dir=vendor
43
+ docker compose exec app grep -rnE "add_(action|filter)\( *'[a-z_]+' *, *function" --include=*.php . --exclude-dir=vendor
44
+ ```
45
+
46
+ Checklist:
47
+ - [ ] Hooks are registered in one place per feature (a `register()` / `boot()` method), not inside constructors of value objects or at file scope
48
+ - [ ] Callbacks are class methods or named functions, so they can be removed with `remove_action()` and tested; anonymous closures only for hooks that never need removal
49
+ - [ ] Priorities are explicit when order matters and documented; `remove_*` calls run late enough (priority and hook) to find the callback
50
+ - [ ] Business logic lives in plain classes with injected dependencies (including `$wpdb`, clock, HTTP client); hook callbacks are thin adapters
51
+ - [ ] Heavy work does not run on every request: guard with `is_admin()`, `wp_doing_ajax()` or load classes lazily on the relevant hook (`admin_init`, `rest_api_init`, `init`)
52
+ - [ ] The plugin exposes its own extension points (`apply_filters()` / `do_action()`) with prefixed names for behavior that integrators may change, documented with a docblock
53
+ - [ ] Globals (`$post`, `$wp_query`) are read through functions (`get_post()`, `get_queried_object()`); any temporary global change is restored (`wp_reset_postdata()`)
54
+ - [ ] Custom post types, taxonomies and meta are registered on `init` with `show_in_rest` where the editor or REST needs them; rewrite rules are flushed only on activation/deactivation
55
+
56
+ **Scoring**: 6 pts. Deduct 1 per feature mixing business rules with hook plumbing, 1 per irremovable callback that integrators need, 1 per file-scope side effect, max -6.
57
+
58
+ ### Step 3: Blocks, Themes and the Interactivity API (5 points)
59
+
60
+ ```bash
61
+ docker compose exec app find . -name block.json -not -path "./node_modules/*" -not -path "./vendor/*"
62
+ docker compose exec app grep -rnE "wp_register_block_types_from_metadata_collection|register_block_type\(|blocks-manifest" --include=*.php . --exclude-dir=vendor
63
+ docker compose exec app grep -rnE "\"apiVersion\"|\"viewScriptModule\"|\"render\"|\"supports\"" --include=block.json . --exclude-dir=node_modules
64
+ docker compose exec app grep -nE '"version"|"[$]schema"' theme.json
65
+ ```
66
+
67
+ Checklist:
68
+ - [ ] Each block has a `block.json` with `apiVersion` 3, a namespaced `name`, `title`, `category`, `textdomain`, and declared `attributes`, `supports`, `editorScript` / `style` / `render` as needed
69
+ - [ ] Blocks are registered from metadata: `wp_register_block_types_from_metadata_collection()` with a `blocks-manifest.php` produced by `wp-scripts build-blocks-manifest`, or `register_block_type( __DIR__ . '/build/<block>' )` for a single block
70
+ - [ ] Dynamic blocks use `render.php` (or a `render_callback`) that escapes late and relies on `$attributes`, `$content`, `$block`; static markup is saved in JS only when it never changes server-side
71
+ - [ ] Block deprecations are provided when saved markup or attributes change
72
+ - [ ] Interactive front-end behavior uses the Interactivity API (`viewScriptModule`, `data-wp-interactive`, `data-wp-on--click`, a namespaced `store()`), not ad-hoc jQuery on the front end
73
+ - [ ] Block themes configure design in `theme.json` (settings, styles, `templateParts`, `customTemplates`) rather than custom CSS; patterns live in `patterns/` with a header (`Title`, `Slug`, `Categories`)
74
+ - [ ] Front-end assets are enqueued only where needed (block `style` / `viewScriptModule`, or conditional `wp_enqueue_scripts`) using the `*.asset.php` dependencies and version
75
+
76
+ **Scoring**: 5 pts (2 block metadata and registration, 1 dynamic rendering, 1 Interactivity API, 1 theme.json and patterns). Mark items N/A when the project has no blocks or no theme, and rescale.
77
+
78
+ ### Step 4: REST API, Settings and Data (4 points)
79
+
80
+ ```bash
81
+ docker compose exec app grep -rnE "register_rest_route|permission_callback|register_setting|add_settings_(section|field)|add_options_page|add_menu_page" --include=*.php . --exclude-dir=vendor
82
+ docker compose exec app grep -rnE "(get|update|add)_option\(|(get|set)_transient\(|wp_cache_(get|set)\(" --include=*.php . --exclude-dir=vendor
83
+ docker compose exec app grep -rnE 'dbDelta|[$]wpdb->(query|get_results|get_var|insert|update)' --include=*.php . --exclude-dir=vendor
84
+ ```
85
+
86
+ Checklist:
87
+ - [ ] Custom endpoints use `register_rest_route()` on `rest_api_init` with a vendor namespace and version (`vendor/v1`), a `permission_callback` on every route, and `args` with `type`, `required`, `sanitize_callback` and `validate_callback`
88
+ - [ ] Controllers extend `WP_REST_Controller` (or follow its schema conventions) and return `WP_REST_Response` / `WP_Error` with proper status codes
89
+ - [ ] Settings use `register_setting()` with `type`, `sanitize_callback`, `default`, and `show_in_rest` when needed; admin pages use the Settings API, not hand-rolled forms
90
+ - [ ] Options are namespaced, grouped (one array option per feature instead of many scalar options), and large or rarely read ones use `autoload` set to false
91
+ - [ ] Expensive computations use transients or the object cache (`wp_cache_*` with a group) with an explicit expiration and invalidation on change
92
+ - [ ] Custom tables are created with `dbDelta()` on activation, versioned (a `{prefix}_db_version` option) with upgrade routines, and always accessed through `$wpdb` with the table prefix
93
+ - [ ] WP-CLI commands (when present) register via `WP_CLI::add_command()` inside `if ( defined( 'WP_CLI' ) && WP_CLI )` and reuse the same service classes as hooks and REST
94
+
95
+ **Scoring**: 4 pts (1 per group: REST, settings, options and caching, custom tables / WP-CLI).
96
+
97
+ ### Step 5: Internationalization, Assets and Compatibility (5 points)
98
+
99
+ ```bash
100
+ docker compose exec app grep -rnE "load_plugin_textdomain|wp_set_script_translations|esc_html__|_x\(|_n\(" --include=*.php . --exclude-dir=vendor
101
+ docker compose exec app grep -rnE "wp_(register|enqueue)_(script|style)|\.asset\.php" --include=*.php . --exclude-dir=vendor
102
+ docker compose exec app grep -rnE "<script|<style|<link rel=.stylesheet" --include=*.php . --exclude-dir=vendor
103
+ docker compose exec app grep -rnE "wp_remote_(get|post)|file_get_contents\( *'http|curl_init" --include=*.php . --exclude-dir=vendor
104
+ ```
105
+
106
+ Checklist:
107
+ - [ ] All user-facing strings use `__()`, `_x()`, `_n()`, `esc_html__()` with a single literal text domain matching the plugin slug (no variables as domain or string); a `.pot` file is generated with `wp i18n make-pot`
108
+ - [ ] JavaScript strings use `@wordpress/i18n` and `wp_set_script_translations( $handle, $domain, $path )`; `Domain Path` header set when translations ship in the plugin
109
+ - [ ] Assets are registered/enqueued with `wp_enqueue_script/style` and the dependencies and version from `build/*.asset.php`; no inline `<script>` / `<style>` tags in templates (use `wp_add_inline_script` / `wp_add_inline_style`)
110
+ - [ ] Scripts load in the footer or with the `strategy` argument set to `defer` where possible; admin assets are limited to the relevant screen via the hook suffix
111
+ - [ ] Bundled libraries come from npm and are built, not copied minified without source; no remote CDN assets that leak visitor data
112
+ - [ ] Outbound HTTP uses the HTTP API (`wp_remote_get` / `wp_safe_remote_get`) with timeouts and error handling, never raw cURL
113
+ - [ ] Declared `Requires at least` / `Requires PHP` match the APIs actually used; deprecated functions are not called (check with Plugin Check and `WP_DEBUG` logs)
114
+ - [ ] Multisite: `switch_to_blog()` / `restore_current_blog()` are paired; network-wide data uses the network option variants
115
+
116
+ **Scoring**: 5 pts (2 i18n, 2 assets and HTTP, 1 compatibility declarations).
117
+
118
+ ### Step 6: WooCommerce Extension (conditional, not scored here)
119
+
120
+ If the project depends on WooCommerce (plugin header `Requires Plugins: woocommerce`, `wc_*` calls, `before_woocommerce_init` hook), also apply `.claude/skills/woocommerce/checklist.md` and report its findings in a separate section.
121
+
122
+ ## OUTPUT FORMAT
123
+
124
+ ```
125
+ WORDPRESS ARCHITECTURE AUDIT
126
+ ============================
127
+
128
+ SCORE: XX/25
129
+
130
+ WordPress: X.Y PHP: X.Y Type: [plugin/block theme/both] Blocks: N REST routes: N Hooks: N
131
+
132
+ SUB-SCORES:
133
+ Layout and bootstrap : XX/5
134
+ Hooks and separation of concerns : XX/6
135
+ Blocks, themes, Interactivity API : XX/5
136
+ REST, settings and data : XX/4
137
+ i18n, assets and compatibility : XX/5
138
+
139
+ STRENGTHS:
140
+ - [...]
141
+
142
+ ISSUES (by severity):
143
+ - CRITICAL: [file:line] [description] -> [fix]
144
+ - IMPORTANT: ...
145
+ - MINOR: ...
146
+
147
+ RECOMMENDATIONS:
148
+ 1. [Action] (effort: Low/Medium/High, impact: Low/Medium/High)
149
+ 2. ...
150
+ ```
151
+
152
+ ## IMPORTANT NOTES
153
+
154
+ - Findings must cite `file:line` and propose a concrete refactoring (for example "move the pricing rules out of the `save_post` callback into `Pricing\Calculator` so it can be unit-tested")
155
+ - Do not recommend a DI container, custom abstraction layers or service providers for a small plugin (YAGNI)
156
+ - Never edit WordPress core or third-party plugins in the audit; propose a hook or a filter instead
157
+ - Generic PHP design belongs to the `php` stack; hosting and deployment (Bedrock, multi-environment) are out of scope