wordpress-agent-kit 0.4.0 → 0.6.0

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 (153) hide show
  1. package/.agents/skills/wp-bootstrap/SKILL.md +314 -0
  2. package/.agents/skills/wp-bootstrap/references/composer-setup.md +275 -0
  3. package/.agents/skills/wp-bootstrap/references/monorepo-patterns.md +184 -0
  4. package/.agents/skills/wp-bootstrap/scripts/bootstrap.sh +151 -0
  5. package/.agents/skills/wp-bootstrap/scripts/detect-structure.mjs +466 -0
  6. package/.agents/skills/wp-bootstrap/scripts/package-wp.sh +173 -0
  7. package/.agents/skills/wp-bootstrap/scripts/playground-start.sh +148 -0
  8. package/.agents/skills/wp-bootstrap/scripts/playground-verify.sh +165 -0
  9. package/.agents/skills/wp-bootstrap/scripts/setup-github.sh +417 -0
  10. package/{.github → .agents}/skills/wp-wpcli-and-ops/SKILL.md +11 -9
  11. package/.agents/skills/wp-wpengine/SKILL.md +462 -0
  12. package/.agents/skills/wp-wpengine/references/ci-gate.md +469 -0
  13. package/.agents/skills/wp-wpengine/references/github-actions-deploy.md +743 -0
  14. package/.agents/skills/wp-wpengine/scripts/ci-gate.sh +118 -0
  15. package/.agents/skills/wp-wpengine/scripts/wpe-check.sh +89 -0
  16. package/.agents/skills/wp-wpengine/scripts/wpe-preflight.sh +104 -0
  17. package/.github/agents/wp-architect.agent.md +1 -2
  18. package/.github/copilot-instructions.md +1 -1
  19. package/.github/instructions/wordpress-workflow.instructions.md +3 -3
  20. package/AGENTS.md +22 -10
  21. package/AGENTS.template.md +20 -10
  22. package/README.md +89 -85
  23. package/dist/cli.js +7 -1
  24. package/dist/commands/bootstrap.js +105 -0
  25. package/dist/commands/clean-skills.js +64 -0
  26. package/dist/commands/setup.js +6 -2
  27. package/dist/commands/sync-skills.js +3 -0
  28. package/dist/lib/api.js +165 -5
  29. package/dist/lib/bootstrap.js +352 -0
  30. package/dist/lib/installer.js +166 -2
  31. package/extensions/wp-agent-kit/index.ts +325 -10
  32. package/package.json +10 -14
  33. package/skills-custom/wp-bootstrap/SKILL.md +314 -0
  34. package/skills-custom/wp-bootstrap/references/composer-setup.md +275 -0
  35. package/skills-custom/wp-bootstrap/references/monorepo-patterns.md +184 -0
  36. package/skills-custom/wp-bootstrap/scripts/bootstrap.sh +151 -0
  37. package/skills-custom/wp-bootstrap/scripts/detect-structure.mjs +466 -0
  38. package/skills-custom/wp-bootstrap/scripts/package-wp.sh +173 -0
  39. package/skills-custom/wp-bootstrap/scripts/playground-start.sh +148 -0
  40. package/skills-custom/wp-bootstrap/scripts/playground-verify.sh +165 -0
  41. package/skills-custom/wp-bootstrap/scripts/setup-github.sh +417 -0
  42. package/skills-custom/wp-wpengine/SKILL.md +362 -27
  43. package/skills-custom/wp-wpengine/references/ci-gate.md +469 -0
  44. package/skills-custom/wp-wpengine/references/github-actions-deploy.md +743 -0
  45. package/skills-custom/wp-wpengine/scripts/ci-gate.sh +118 -0
  46. package/skills-custom/wp-wpengine/scripts/wpe-check.sh +89 -0
  47. package/skills-custom/wp-wpengine/scripts/wpe-preflight.sh +104 -0
  48. package/.github/skills/wp-wpengine/SKILL.md +0 -127
  49. package/.github/workflows/ci.yml +0 -44
  50. package/.husky/pre-commit +0 -7
  51. package/CLI_REVIEW.md +0 -250
  52. package/biome.json +0 -39
  53. /package/{.github → .agents}/skills/blueprint/SKILL.md +0 -0
  54. /package/{.github → .agents}/skills/wordpress-router/SKILL.md +0 -0
  55. /package/{.github → .agents}/skills/wordpress-router/references/decision-tree.md +0 -0
  56. /package/{.github → .agents}/skills/wp-abilities-api/SKILL.md +0 -0
  57. /package/{.github → .agents}/skills/wp-abilities-api/references/delegate-helper-pattern.md +0 -0
  58. /package/{.github → .agents}/skills/wp-abilities-api/references/domain-vs-projection.md +0 -0
  59. /package/{.github → .agents}/skills/wp-abilities-api/references/error-code-vocabulary.md +0 -0
  60. /package/{.github → .agents}/skills/wp-abilities-api/references/grouping-heuristic.md +0 -0
  61. /package/{.github → .agents}/skills/wp-abilities-api/references/input-schema-gotchas.md +0 -0
  62. /package/{.github → .agents}/skills/wp-abilities-api/references/php-registration.md +0 -0
  63. /package/{.github → .agents}/skills/wp-abilities-api/references/plugin-family-patterns.md +0 -0
  64. /package/{.github → .agents}/skills/wp-abilities-api/references/rest-api.md +0 -0
  65. /package/{.github → .agents}/skills/wp-abilities-api/references/shared-core-service.md +0 -0
  66. /package/{.github → .agents}/skills/wp-abilities-audit/SKILL.md +0 -0
  67. /package/{.github → .agents}/skills/wp-abilities-audit/references/audit-schema.md +0 -0
  68. /package/{.github → .agents}/skills/wp-abilities-audit/references/capability-gate-tracing.md +0 -0
  69. /package/{.github → .agents}/skills/wp-abilities-audit/references/controller-enumeration.md +0 -0
  70. /package/{.github → .agents}/skills/wp-abilities-verify/SKILL.md +0 -0
  71. /package/{.github → .agents}/skills/wp-abilities-verify/references/annotation-correctness.md +0 -0
  72. /package/{.github → .agents}/skills/wp-abilities-verify/references/audit-schema-validation.md +0 -0
  73. /package/{.github → .agents}/skills/wp-abilities-verify/references/permission-roundtrip.md +0 -0
  74. /package/{.github → .agents}/skills/wp-abilities-verify/references/runtime-harness.md +0 -0
  75. /package/{.github → .agents}/skills/wp-abilities-verify/references/schema-lints.md +0 -0
  76. /package/{.github → .agents}/skills/wp-abilities-verify/references/static-enumeration.md +0 -0
  77. /package/{.github → .agents}/skills/wp-block-development/SKILL.md +0 -0
  78. /package/{.github → .agents}/skills/wp-block-development/references/attributes-and-serialization.md +0 -0
  79. /package/{.github → .agents}/skills/wp-block-development/references/block-json.md +0 -0
  80. /package/{.github → .agents}/skills/wp-block-development/references/creating-new-blocks.md +0 -0
  81. /package/{.github → .agents}/skills/wp-block-development/references/debugging.md +0 -0
  82. /package/{.github → .agents}/skills/wp-block-development/references/deprecations.md +0 -0
  83. /package/{.github → .agents}/skills/wp-block-development/references/dynamic-rendering.md +0 -0
  84. /package/{.github → .agents}/skills/wp-block-development/references/inner-blocks.md +0 -0
  85. /package/{.github → .agents}/skills/wp-block-development/references/registration.md +0 -0
  86. /package/{.github → .agents}/skills/wp-block-development/references/supports-and-wrappers.md +0 -0
  87. /package/{.github → .agents}/skills/wp-block-development/references/tooling-and-testing.md +0 -0
  88. /package/{.github → .agents}/skills/wp-block-development/scripts/list_blocks.mjs +0 -0
  89. /package/{.github → .agents}/skills/wp-block-themes/SKILL.md +0 -0
  90. /package/{.github → .agents}/skills/wp-block-themes/references/creating-new-block-theme.md +0 -0
  91. /package/{.github → .agents}/skills/wp-block-themes/references/debugging.md +0 -0
  92. /package/{.github → .agents}/skills/wp-block-themes/references/patterns.md +0 -0
  93. /package/{.github → .agents}/skills/wp-block-themes/references/style-variations.md +0 -0
  94. /package/{.github → .agents}/skills/wp-block-themes/references/templates-and-parts.md +0 -0
  95. /package/{.github → .agents}/skills/wp-block-themes/references/theme-json.md +0 -0
  96. /package/{.github → .agents}/skills/wp-block-themes/scripts/detect_block_themes.mjs +0 -0
  97. /package/{.github → .agents}/skills/wp-interactivity-api/SKILL.md +0 -0
  98. /package/{.github → .agents}/skills/wp-interactivity-api/references/debugging.md +0 -0
  99. /package/{.github → .agents}/skills/wp-interactivity-api/references/directives-quickref.md +0 -0
  100. /package/{.github → .agents}/skills/wp-interactivity-api/references/server-side-rendering.md +0 -0
  101. /package/{.github → .agents}/skills/wp-performance/SKILL.md +0 -0
  102. /package/{.github → .agents}/skills/wp-performance/references/autoload-options.md +0 -0
  103. /package/{.github → .agents}/skills/wp-performance/references/cron.md +0 -0
  104. /package/{.github → .agents}/skills/wp-performance/references/database.md +0 -0
  105. /package/{.github → .agents}/skills/wp-performance/references/http-api.md +0 -0
  106. /package/{.github → .agents}/skills/wp-performance/references/measurement.md +0 -0
  107. /package/{.github → .agents}/skills/wp-performance/references/object-cache.md +0 -0
  108. /package/{.github → .agents}/skills/wp-performance/references/query-monitor-headless.md +0 -0
  109. /package/{.github → .agents}/skills/wp-performance/references/server-timing.md +0 -0
  110. /package/{.github → .agents}/skills/wp-performance/references/wp-cli-doctor.md +0 -0
  111. /package/{.github → .agents}/skills/wp-performance/references/wp-cli-profile.md +0 -0
  112. /package/{.github → .agents}/skills/wp-performance/scripts/perf_inspect.mjs +0 -0
  113. /package/{.github → .agents}/skills/wp-phpstan/SKILL.md +0 -0
  114. /package/{.github → .agents}/skills/wp-phpstan/references/configuration.md +0 -0
  115. /package/{.github → .agents}/skills/wp-phpstan/references/third-party-classes.md +0 -0
  116. /package/{.github → .agents}/skills/wp-phpstan/references/wordpress-annotations.md +0 -0
  117. /package/{.github → .agents}/skills/wp-phpstan/scripts/phpstan_inspect.mjs +0 -0
  118. /package/{.github → .agents}/skills/wp-playground/SKILL.md +0 -0
  119. /package/{.github → .agents}/skills/wp-playground/references/blueprints.md +0 -0
  120. /package/{.github → .agents}/skills/wp-playground/references/cli-commands.md +0 -0
  121. /package/{.github → .agents}/skills/wp-playground/references/debugging.md +0 -0
  122. /package/{.github → .agents}/skills/wp-playground/references/e2e-playwright.md +0 -0
  123. /package/{.github → .agents}/skills/wp-plugin-development/SKILL.md +0 -0
  124. /package/{.github → .agents}/skills/wp-plugin-development/references/data-and-cron.md +0 -0
  125. /package/{.github → .agents}/skills/wp-plugin-development/references/debugging.md +0 -0
  126. /package/{.github → .agents}/skills/wp-plugin-development/references/lifecycle.md +0 -0
  127. /package/{.github → .agents}/skills/wp-plugin-development/references/security.md +0 -0
  128. /package/{.github → .agents}/skills/wp-plugin-development/references/settings-api.md +0 -0
  129. /package/{.github → .agents}/skills/wp-plugin-development/references/structure.md +0 -0
  130. /package/{.github → .agents}/skills/wp-plugin-development/scripts/detect_plugins.mjs +0 -0
  131. /package/{.github → .agents}/skills/wp-plugin-directory-guidelines/SKILL.md +0 -0
  132. /package/{.github → .agents}/skills/wp-plugin-directory-guidelines/references/gpl-compliance.md +0 -0
  133. /package/{.github → .agents}/skills/wp-plugin-directory-guidelines/references/guideline-review-checklist.md +0 -0
  134. /package/{.github → .agents}/skills/wp-plugin-directory-guidelines/references/naming-rules.md +0 -0
  135. /package/{.github → .agents}/skills/wp-project-triage/SKILL.md +0 -0
  136. /package/{.github → .agents}/skills/wp-project-triage/references/triage.schema.json +0 -0
  137. /package/{.github → .agents}/skills/wp-project-triage/scripts/detect_wp_project.mjs +0 -0
  138. /package/{.github → .agents}/skills/wp-rest-api/SKILL.md +0 -0
  139. /package/{.github → .agents}/skills/wp-rest-api/references/authentication.md +0 -0
  140. /package/{.github → .agents}/skills/wp-rest-api/references/custom-content-types.md +0 -0
  141. /package/{.github → .agents}/skills/wp-rest-api/references/discovery-and-params.md +0 -0
  142. /package/{.github → .agents}/skills/wp-rest-api/references/responses-and-fields.md +0 -0
  143. /package/{.github → .agents}/skills/wp-rest-api/references/routes-and-endpoints.md +0 -0
  144. /package/{.github → .agents}/skills/wp-rest-api/references/schema.md +0 -0
  145. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/automation.md +0 -0
  146. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/cron-and-cache.md +0 -0
  147. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/debugging.md +0 -0
  148. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/multisite.md +0 -0
  149. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/packages-and-updates.md +0 -0
  150. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/safety.md +0 -0
  151. /package/{.github → .agents}/skills/wp-wpcli-and-ops/references/search-replace.md +0 -0
  152. /package/{.github → .agents}/skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs +0 -0
  153. /package/{.github → .agents}/skills/wpds/SKILL.md +0 -0
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg?style=flat-square)](LICENSE)
4
4
  [![TypeScript](https://img.shields.io/badge/Written%20in-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
5
- [![Version](https://img.shields.io/badge/version-0.4.0-blue?style=flat-square)](package.json)
5
+ [![Version](https://img.shields.io/badge/version-0.6.0-blue?style=flat-square)](package.json)
6
6
  [![Node](https://img.shields.io/badge/node-%3E%3D20.18-green?style=flat-square)](package.json)
7
7
  [![CI](https://img.shields.io/badge/CI-passing-brightgreen?style=flat-square)](.github/workflows/ci.yml)
8
8
 
@@ -26,21 +26,17 @@ npx wp-agent-kit install /path/to/my-plugin --platform github
26
26
  npx wp-agent-kit setup /path/to/my-plugin --auto
27
27
 
28
28
  # 3. (Optional) Verify the triage report
29
- node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
29
+ node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
30
30
  ```
31
31
 
32
32
  **What gets installed:**
33
+
33
34
  ```
34
35
  my-plugin/
35
36
  ├── AGENTS.md # Project-specific agent instructions
36
37
  ├── AGENTS.template.md # Template reference for future updates
37
- ├── .github/
38
- ├── agents/
39
- │ │ └── wp-architect.agent.md # WordPress Architect agent persona
40
- │ ├── instructions/
41
- │ │ └── wordpress-workflow.instructions.md
42
- │ ├── prompts/
43
- │ └── skills/ # 17 WordPress skills + 1 optional
38
+ ├── .agents/
39
+ └── skills/ # 18 WordPress skills (AgentSkills.io convention)
44
40
  │ ├── wp-project-triage/ # Project detection
45
41
  │ ├── wp-plugin-development/ # Plugin architecture
46
42
  │ ├── wp-block-development/ # Gutenberg blocks
@@ -55,6 +51,12 @@ my-plugin/
55
51
  │ ├── wpds/ # Design system
56
52
  │ ├── wordpress-router/ # Repo classification
57
53
  │ └── wp-wpengine/ # (optional) WP Engine hosting + git push
54
+ ├── .github/
55
+ │ ├── agents/
56
+ │ │ └── wp-architect.agent.md # WordPress Architect agent persona
57
+ │ ├── instructions/
58
+ │ │ └── wordpress-workflow.instructions.md
59
+ │ └── prompts/
58
60
  └── .wp-agent-kit-manifest.github.json # Safe-update tracking
59
61
  ```
60
62
 
@@ -65,7 +67,7 @@ my-plugin/
65
67
  npx wp-agent-kit install /path/to/existing-plugin --platform github
66
68
 
67
69
  # 2. Run triage to detect your project's type, tech stack, and tooling
68
- node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
70
+ node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
69
71
 
70
72
  # 3. Configure based on detection (headless)
71
73
  npx wp-agent-kit setup /path/to/existing-plugin --auto
@@ -79,6 +81,7 @@ npx wp-agent-kit setup /path/to/existing-plugin \
79
81
  ```
80
82
 
81
83
  **Key behavior:**
84
+
82
85
  - Your existing `AGENTS.md` is **never overwritten** — only new sections are added
83
86
  - Triage inspects your codebase and returns structured JSON with project kind, signals, and tooling
84
87
  - Setup updates only the tooling/configuration sections of AGENTS.md
@@ -97,6 +100,7 @@ npx wp-agent-kit upgrade --force
97
100
  ```
98
101
 
99
102
  **Safe update behavior:**
103
+
100
104
  - Compares installed files against a manifest of original hashes
101
105
  - Files you haven't modified → automatically updated
102
106
  - Files you modified → **skipped** (preserved)
@@ -114,32 +118,32 @@ npx wp-agent-kit install --no-safe --force
114
118
 
115
119
  ### CLI Commands
116
120
 
117
- | Command | Purpose |
118
- |---------|---------|
119
- | `install [dir]` | Install kit into a project |
120
- | `setup [dir]` | Interactive or headless configuration |
121
+ | Command | Purpose |
122
+ | ------------------- | ---------------------------------------------- |
123
+ | `install [dir]` | Install kit into a project |
124
+ | `setup [dir]` | Interactive or headless configuration |
121
125
  | `sync-skills [ref]` | Pull latest skills from WordPress/agent-skills |
122
- | `upgrade [dir]` | Check or apply version upgrades |
123
- | `playground` | Launch local WordPress Playground |
126
+ | `upgrade [dir]` | Check or apply version upgrades |
127
+ | `playground` | Launch local WordPress Playground |
124
128
 
125
129
  ### Platform Flags
126
130
 
127
- | Platform | Flag | Target Directory |
128
- |----------|------|-----------------|
129
- | GitHub Copilot / VS Code | `--platform github` | `.github/` |
130
- | Cursor IDE | `--platform cursor` | `.cursor/` |
131
- | Claude Code | `--platform claude` | `.claude/` |
132
- | Pi Coding Agent | `--platform pi` | `.pi/agent/` |
133
- | Generic .agent | `--platform agent` | `.agent/` |
131
+ | Platform | Flag | Target Directory |
132
+ | ------------------------ | ------------------- | ---------------- |
133
+ | GitHub Copilot / VS Code | `--platform github` | `.github/` |
134
+ | Cursor IDE | `--platform cursor` | `.cursor/` |
135
+ | Claude Code | `--platform claude` | `.claude/` |
136
+ | Pi Coding Agent | `--platform pi` | `.pi/agent/` |
137
+ | Generic .agent | `--platform agent` | `.agent/` |
134
138
 
135
139
  ### Agent-Friendly Flags (All Commands)
136
140
 
137
- | Flag | Description |
138
- |------|-------------|
139
- | `--json` | Machine-readable JSON output |
140
- | `--dry-run` | Preview changes without applying |
141
- | `--ndjson` | Newline-delimited JSON for streaming |
142
- | `--quiet` | Suppress non-error output |
141
+ | Flag | Description |
142
+ | ----------- | ------------------------------------ |
143
+ | `--json` | Machine-readable JSON output |
144
+ | `--dry-run` | Preview changes without applying |
145
+ | `--ndjson` | Newline-delimited JSON for streaming |
146
+ | `--quiet` | Suppress non-error output |
143
147
 
144
148
  ---
145
149
 
@@ -153,21 +157,21 @@ pi install npm:wordpress-agent-kit
153
157
 
154
158
  ### Pi Tools (Callable by the Agent)
155
159
 
156
- | Tool | What it does |
157
- |------|-------------|
158
- | `wp_triage` | Detect WordPress project type, signals, and tooling |
160
+ | Tool | What it does |
161
+ | ---------------- | --------------------------------------------------- |
162
+ | `wp_triage` | Detect WordPress project type, signals, and tooling |
159
163
  | `wp_install_kit` | Install/update kit into a project (safe by default) |
160
- | `wp_sync_skills` | Sync skills from WordPress/agent-skills upstream |
161
- | `wp_upgrade` | Check and apply version upgrades |
164
+ | `wp_sync_skills` | Sync skills from WordPress/agent-skills upstream |
165
+ | `wp_upgrade` | Check and apply version upgrades |
162
166
 
163
167
  ### Pi Commands (Type `/` in Pi TUI)
164
168
 
165
- | Command | What it does |
166
- |---------|-------------|
167
- | `/wp-triage [dir]` | Run project detection, show in status bar |
168
- | `/wp-install [dir]` | Install kit into current project |
169
- | `/wp-sync-skills [ref]` | Sync skills from upstream |
170
- | `/wp-upgrade` | Show installed vs latest version |
169
+ | Command | What it does |
170
+ | ----------------------- | ----------------------------------------- |
171
+ | `/wp-triage [dir]` | Run project detection, show in status bar |
172
+ | `/wp-install [dir]` | Install kit into current project |
173
+ | `/wp-sync-skills [ref]` | Sync skills from upstream |
174
+ | `/wp-upgrade` | Show installed vs latest version |
171
175
 
172
176
  ---
173
177
 
@@ -177,24 +181,24 @@ Import directly into scripts, tests, or other tools:
177
181
 
178
182
  ```typescript
179
183
  import {
180
- installKitApi, // Install/update kit
181
- syncSkillsApi, // Sync skills from upstream
182
- runTriageApi, // Run project detection
183
- configureAgentsMdApi, // Configure AGENTS.md
184
- computeChanges, // Preview file changes (dry-run)
185
- isKitInstalled, // Check if kit is installed
186
- loadManifest, // Read install manifest
187
- updateKit, // Raw safe update
188
- ExitCode, // Semantic exit codes
184
+ installKitApi, // Install/update kit
185
+ syncSkillsApi, // Sync skills from upstream
186
+ runTriageApi, // Run project detection
187
+ configureAgentsMdApi, // Configure AGENTS.md
188
+ computeChanges, // Preview file changes (dry-run)
189
+ isKitInstalled, // Check if kit is installed
190
+ loadManifest, // Read install manifest
191
+ updateKit, // Raw safe update
192
+ ExitCode, // Semantic exit codes
189
193
  } from 'wordpress-agent-kit/api';
190
194
 
191
195
  // Install with safe update
192
196
  const result = await installKitApi({
193
197
  targetDir: '/path/to/my-plugin',
194
198
  platform: 'github',
195
- safe: true, // Use manifest-based diff
196
- backup: true, // Create backup before changes
197
- force: false, // Don't overwrite user mods
199
+ safe: true, // Use manifest-based diff
200
+ backup: true, // Create backup before changes
201
+ force: false, // Don't overwrite user mods
198
202
  });
199
203
 
200
204
  // Dry-run preview
@@ -212,44 +216,44 @@ console.log(triage.data.project.primary); // "plugin"
212
216
 
213
217
  ### Semantic Exit Codes
214
218
 
215
- | Code | Meaning |
216
- |------|---------|
217
- | 0 | Success |
218
- | 2 | Invalid arguments |
219
- | 3 | Not found |
220
- | 4 | Permission denied |
221
- | 5 | Already exists |
222
- | 6 | Git error |
223
- | 7 | Network error |
224
- | 8 | Validation failed |
225
- | 130 | Cancelled |
219
+ | Code | Meaning |
220
+ | ---- | ----------------- |
221
+ | 0 | Success |
222
+ | 2 | Invalid arguments |
223
+ | 3 | Not found |
224
+ | 4 | Permission denied |
225
+ | 5 | Already exists |
226
+ | 6 | Git error |
227
+ | 7 | Network error |
228
+ | 8 | Validation failed |
229
+ | 130 | Cancelled |
226
230
 
227
231
  ---
228
232
 
229
233
  ## Skills Reference
230
234
 
231
- All 17 skills follow the [AgentSkills.io](https://agentskills.io) specification. Skills in `skills-custom/` are project-specific (not from upstream) and survive `sync-skills`:
232
-
233
- | Skill | When to Use |
234
- |-------|------------|
235
- | `wp-project-triage` | Run deterministic project detection (type, tooling, versions) |
236
- | `wp-plugin-development` | Develop WordPress plugins (hooks, settings, security, release) |
237
- | `wp-block-development` | Develop Gutenberg blocks (block.json, attributes, rendering) |
238
- | `wp-block-themes` | Develop block themes (theme.json, templates, patterns, variations) |
239
- | `wp-rest-api` | Build, extend, or debug REST API endpoints/routes |
240
- | `wp-interactivity-api` | Build Interactive blocks with data-wp-* directives |
241
- | `wp-abilities-api` | Register and consume WordPress Abilities API |
242
- | `wp-abilities-audit` | Audit a plugin's REST surface for Abilities API opportunities |
243
- | `wp-abilities-verify` | Verify registered Abilities match their annotations |
244
- | `wp-performance` | Profile and optimize WordPress performance |
245
- | `wp-phpstan` | Configure and run PHPStan static analysis |
246
- | `wp-wpcli-and-ops` | WP-CLI commands, automation, multisite operations |
247
- | `wp-playground` | Test with disposable Playground instances; PHPUnit, Playwright E2E, CI |
248
- | `blueprint` | Write and edit WordPress Playground blueprint JSON |
249
- | `wpds` | Build UIs with the WordPress Design System |
250
- | `wp-plugin-directory-guidelines` | GPL compliance, naming, slug rules for WP.org submission |
251
- | `wordpress-router` | Route/classify repository type and select appropriate skills |
252
- | **`wp-wpengine`** *(optional, custom)* | **WP Engine git push, install/domain/cache/backup management via wpe-labs skills** |
235
+ All 18 skills follow the [AgentSkills.io](https://agentskills.io) specification. Skills in `skills-custom/` are project-specific (not from upstream) and survive `sync-skills`:
236
+
237
+ | Skill | When to Use |
238
+ | -------------------------------------- | ---------------------------------------------------------------------------------- |
239
+ | `wp-project-triage` | Run deterministic project detection (type, tooling, versions) |
240
+ | `wp-plugin-development` | Develop WordPress plugins (hooks, settings, security, release) |
241
+ | `wp-block-development` | Develop Gutenberg blocks (block.json, attributes, rendering) |
242
+ | `wp-block-themes` | Develop block themes (theme.json, templates, patterns, variations) |
243
+ | `wp-rest-api` | Build, extend, or debug REST API endpoints/routes |
244
+ | `wp-interactivity-api` | Build Interactive blocks with data-wp-\* directives |
245
+ | `wp-abilities-api` | Register and consume WordPress Abilities API |
246
+ | `wp-abilities-audit` | Audit a plugin's REST surface for Abilities API opportunities |
247
+ | `wp-abilities-verify` | Verify registered Abilities match their annotations |
248
+ | `wp-performance` | Profile and optimize WordPress performance |
249
+ | `wp-phpstan` | Configure and run PHPStan static analysis |
250
+ | `wp-wpcli-and-ops` | WP-CLI commands, automation, multisite operations |
251
+ | `wp-playground` | Test with disposable Playground instances; PHPUnit, Playwright E2E, CI |
252
+ | `blueprint` | Write and edit WordPress Playground blueprint JSON |
253
+ | `wpds` | Build UIs with the WordPress Design System |
254
+ | `wp-plugin-directory-guidelines` | GPL compliance, naming, slug rules for WP.org submission |
255
+ | `wordpress-router` | Route/classify repository type and select appropriate skills |
256
+ | **`wp-wpengine`** _(optional, custom)_ | **WP Engine git push, install/domain/cache/backup management via wpe-labs skills** |
253
257
 
254
258
  ---
255
259
 
package/dist/cli.js CHANGED
@@ -1,6 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { createRequire } from 'node:module';
3
3
  import { Command } from 'commander';
4
+ import { bootstrapCommand } from './commands/bootstrap.js';
5
+ import { cleanSkillsCommand } from './commands/clean-skills.js';
4
6
  import { installCommand } from './commands/install.js';
5
7
  import { runPlaygroundCommand } from './commands/run-playground.js';
6
8
  import { setupCommand } from './commands/setup.js';
@@ -25,6 +27,8 @@ program
25
27
  sortSubcommands: true,
26
28
  });
27
29
  // Add commands
30
+ program.addCommand(bootstrapCommand);
31
+ program.addCommand(cleanSkillsCommand);
28
32
  program.addCommand(installCommand);
29
33
  program.addCommand(setupCommand);
30
34
  program.addCommand(syncSkillsCommand);
@@ -52,9 +56,11 @@ Examples:
52
56
  $ wp-agent-kit install --platform github
53
57
  $ wp-agent-kit setup --auto --json
54
58
  $ wp-agent-kit sync-skills --ref trunk --ndjson
55
- $ wp-agent-kit install --platform pi --dry-run --json
59
+ $ wp-agent-kit clean-skills --dry-run --json
60
+ $ wp-agent-kit clean-skills --remove --platform github
56
61
  $ wp-agent-kit upgrade --check-only --json
57
62
 
63
+
58
64
  Programmatic API:
59
65
  import { installKit, syncSkills, runTriage } from 'wordpress-agent-kit/api';
60
66
 
@@ -0,0 +1,105 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ import { Command } from 'commander';
5
+ import { bootstrapApi } from '../lib/api.js';
6
+ import { OutputFormatter, createFormatter } from '../utils/output.js';
7
+ const __filename = fileURLToPath(import.meta.url);
8
+ const __dirname = path.dirname(__filename);
9
+ /**
10
+ * Bootstrap command — probe, configure, and wire up a WordPress project.
11
+ * Supports single plugins/themes and monorepos (multiple WP packages).
12
+ * Supports --detect-only, --auto (non-interactive), --dry-run, --json.
13
+ */
14
+ export const bootstrapCommand = new Command('bootstrap')
15
+ .description('Bootstrap a WordPress project: detect structure, install agent kit, scaffold tooling')
16
+ .argument('[dir]', 'Target directory (defaults to cwd)', process.cwd())
17
+ .option('--detect-only', 'Only run structure detection and output result', false)
18
+ .option('--auto', 'Non-interactive: use detected values without prompting', false)
19
+ .option('--platform <platform>', 'Agent kit platform (github, pi, cursor, claude)', 'github')
20
+ .option('--wp-root <path>', 'WordPress root path relative to repo root (overrides detection)')
21
+ .option('--wp-packages <dirs>', 'Comma-separated list of WP package dirs (overrides detection)')
22
+ .option('--package-manager <pm>', 'Package manager: npm, pnpm, yarn (overrides detection)')
23
+ .option('--wpe-prod <slug>', 'WP Engine production install slug')
24
+ .option('--wpe-staging <slug>', 'WP Engine staging install slug')
25
+ .option('--wpe-dev <slug>', 'WP Engine development install slug')
26
+ .option('--with-satispress <url>', 'Add SatisPress repository URL to composer.json')
27
+ .option('--with-wpackagist', 'Add WPackagist repository to composer.json', false)
28
+ .option('--skip-install', 'Skip running wp-agent-kit install after scaffolding', false)
29
+ .action(async (dir, options, command) => {
30
+ const globalOpts = command.parent?.opts() || {};
31
+ const targetDir = path.resolve(dir);
32
+ const formatter = createFormatter(globalOpts, 'bootstrap', '0.0.0');
33
+ if (!fs.existsSync(targetDir)) {
34
+ const result = formatter.fail({
35
+ code: 'NOT_FOUND',
36
+ message: `Directory does not exist: ${targetDir}`,
37
+ exitCode: 3,
38
+ });
39
+ process.exit(OutputFormatter.getExitCode(result));
40
+ }
41
+ // ── 1. Structure detection ───────────────────────────────────────────
42
+ if (!globalOpts.json && !globalOpts.quiet) {
43
+ console.log(`\n▶ Detecting project structure in ${targetDir}...`);
44
+ }
45
+ const result = await bootstrapApi({
46
+ targetDir,
47
+ platform: options.platform,
48
+ detectOnly: options.detectOnly,
49
+ auto: options.auto,
50
+ dryRun: globalOpts.dryRun ?? false,
51
+ wpRoot: options.wpRoot,
52
+ wpPackages: options.wpPackages?.split(',').map((s) => s.trim()),
53
+ packageManager: options.packageManager,
54
+ wpeEnvironments: {
55
+ production: options.wpeProd,
56
+ staging: options.wpeStaging,
57
+ development: options.wpeDev,
58
+ },
59
+ withSatispress: options.withSatispress,
60
+ withWpackagist: options.withWpackagist,
61
+ skipInstall: options.skipInstall,
62
+ });
63
+ if (globalOpts.json || globalOpts.quiet) {
64
+ process.exit(OutputFormatter.getExitCode(result));
65
+ }
66
+ if (!result.success) {
67
+ console.error(`\n✗ Bootstrap failed: ${result.error?.message}`);
68
+ process.exit(1);
69
+ }
70
+ const data = result.data;
71
+ if (data.detectOnly) {
72
+ // Pretty-print structure
73
+ const s = data.structure;
74
+ console.log('\n── Detected structure ──────────────────────────────────────');
75
+ console.log(` Monorepo: ${s.isMonorepo ? 'yes' : 'no'}`);
76
+ console.log(` Pkg mgr: ${s.packageManager ?? 'none'}`);
77
+ console.log(` WP root: ${s.wpRoot ?? 'none (Playground-only)'}`);
78
+ console.log(` WP packages: ${s.wpPackages.length}`);
79
+ for (const p of s.wpPackages) {
80
+ console.log(` ${p.type === 'plugin' ? '🔌' : '🎨'} ${p.name ?? p.path} (${p.path}) v${p.version ?? '?'}`);
81
+ }
82
+ console.log(` WPE remotes: ${s.wpeRemotes.length}`);
83
+ for (const r of s.wpeRemotes) {
84
+ console.log(` → ${r.name} (${r.install})`);
85
+ }
86
+ console.log(` PHP: PHPCS=${s.php.hasPhpcs} PHPStan=${s.php.hasPhpstan}`);
87
+ console.log(` JS: Biome=${s.js.hasBiome} Vitest=${s.js.hasVitest}`);
88
+ console.log(` Playground: ${s.playground.hasPlayground ? 'configured' : 'not configured'}`);
89
+ console.log(` Agent kit: ${s.hasAgentKit ? 'installed' : 'not installed'}`);
90
+ console.log('');
91
+ }
92
+ else {
93
+ console.log('\n── Bootstrap complete ──────────────────────────────────────');
94
+ for (const action of data.actions) {
95
+ console.log(` ${action}`);
96
+ }
97
+ console.log('\nNext steps:');
98
+ console.log(' 1. Run: bash tools/setup.sh (install dev deps + activate hooks)');
99
+ console.log(' 2. Run: bash tools/playground/run-playground.sh (start local WP)');
100
+ console.log(' 3. Review AGENTS.md and the generated wp-cli.yml');
101
+ console.log(' 4. Add WP Engine secrets to GitHub (see .agents/skills/wp-wpengine/SKILL.md)');
102
+ console.log('');
103
+ }
104
+ process.exit(0);
105
+ });
@@ -0,0 +1,64 @@
1
+ import { Command } from 'commander';
2
+ import { cleanSkillsApi } from '../lib/api.js';
3
+ import { OutputFormatter } from '../utils/output.js';
4
+ function isDryRunResult(result) {
5
+ return result.success && 'wouldExecute' in (result.data || {});
6
+ }
7
+ function isRegularResult(result) {
8
+ return result.success && !('wouldExecute' in (result.data || {}));
9
+ }
10
+ /**
11
+ * Command to detect and remove orphaned skills from an installation.
12
+ * Compares installed skills against the canonical set (upstream + custom).
13
+ */
14
+ export const cleanSkillsCommand = new Command('clean-skills')
15
+ .description('Detect and remove orphaned skills from a WordPress Agent Kit installation')
16
+ .argument('[dir]', 'Target directory', process.cwd())
17
+ .option('--platform <platform>', 'Platform to clean (github, cursor, claude, agent, pi)', 'pi')
18
+ .option('--dry-run', 'Preview changes without applying (default: true)', true)
19
+ .option('--remove', 'Actually remove orphaned skills (default: false — report only)', false)
20
+ .option('--json', 'Output as JSON')
21
+ .option('--quiet', 'Suppress non-essential output')
22
+ .action(async (dir, options) => {
23
+ const targetDir = dir || process.cwd();
24
+ const platform = options.platform || 'pi';
25
+ const result = await cleanSkillsApi({
26
+ targetDir,
27
+ platform,
28
+ dryRun: !options.remove, // dry-run unless --remove is specified
29
+ remove: options.remove,
30
+ });
31
+ if (options.json || options.quiet) {
32
+ process.exit(OutputFormatter.getExitCode(result));
33
+ }
34
+ if (isRegularResult(result)) {
35
+ const data = result.data;
36
+ if (data.orphanedSkills.length === 0) {
37
+ console.log('✓ No orphaned skills found. All skills match the canonical set.');
38
+ }
39
+ else if (data.dryRun) {
40
+ console.log(`Found ${data.orphanedSkills.length} orphaned skill(s):`);
41
+ for (const skill of data.orphanedSkills) {
42
+ console.log(` - ${skill}`);
43
+ }
44
+ console.log('\nRun with --remove to remove them.');
45
+ }
46
+ else {
47
+ console.log(`✓ Removed ${data.removedSkills.length} orphaned skill(s):`);
48
+ for (const skill of data.removedSkills) {
49
+ console.log(` - ${skill}`);
50
+ }
51
+ }
52
+ }
53
+ else if (isDryRunResult(result)) {
54
+ const data = result.data;
55
+ console.log(`Dry-run: ${data.summary.orphanedSkills.length} orphaned skill(s) would be removed:`);
56
+ for (const skill of data.summary.orphanedSkills) {
57
+ console.log(` - ${skill}`);
58
+ }
59
+ }
60
+ else {
61
+ console.error(`✗ Clean failed: ${result.error?.message}`);
62
+ }
63
+ process.exit(result.success ? 0 : 1);
64
+ });
@@ -111,8 +111,12 @@ export const setupCommand = new Command('setup')
111
111
  let detectedTech = [];
112
112
  let detectedPackageManager = 'npm/pnpm';
113
113
  const triageScriptPaths = [
114
+ // Canonical location (AgentSkills.io convention)
115
+ path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
116
+ // Legacy platform-specific location
114
117
  path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
115
- path.join(PACKAGE_ROOT, 'vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs'),
118
+ // Source repo
119
+ path.join(PACKAGE_ROOT, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
116
120
  ];
117
121
  const triageScriptPath = triageScriptPaths.find((p) => fs.existsSync(p));
118
122
  if (triageScriptPath) {
@@ -291,6 +295,6 @@ export const setupCommand = new Command('setup')
291
295
  console.log('\nNext steps:');
292
296
  console.log(` 1. Review ${path.join(targetDir, 'AGENTS.md')}`);
293
297
  console.log(` 2. Customize ${path.join(targetDir, platformFolder, 'prompts/')}`);
294
- console.log(` 3. Run triage: node ${path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs')}`);
298
+ console.log(` 3. Run triage: node ${path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs')}`);
295
299
  process.exit(0);
296
300
  });
@@ -30,6 +30,9 @@ export const syncSkillsCommand = new Command('sync-skills')
30
30
  const data = result.data;
31
31
  console.log(`✓ Synced ${data.skillsSynced} skills from WordPress/agent-skills@${ref}`);
32
32
  console.log(` Method: ${data.method}`);
33
+ if (data.customMerged > 0) {
34
+ console.log(` Custom skills merged: ${data.customMerged}`);
35
+ }
33
36
  console.log(` Duration: ${data.durationMs}ms`);
34
37
  }
35
38
  else if (isDryRunResult(result)) {