Skip to content

Commit 596506e

Browse files
ashleyshawashleyshaw
committed
Add block plugin automation agents and AI instructions
Introduces a comprehensive automation and documentation system for WordPress block plugin development. Adds the main build agent script and spec, workflow for build/lint/test, chat modes, prompt templates, and detailed custom instructions for AI/Copilot usage. Updates .gitignore and AGENTS.md for improved structure and cross-referencing. Also adds a generator script for single block plugins and updates dependencies in package.json for broader WordPress compatibility.
1 parent 081aae4 commit 596506e

16 files changed

+951
-130
lines changed

‎.coderabbit.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
$schema: https://coderabbit.ai/integrations/coderabbit-overrides.v2.json
2+
language: 'en'
3+
chat:
4+
auto_reply: true
5+
reviews:
6+
request_changes_workflow: true
7+
high_level_summary: true
8+
poem: false
9+
review_status: true
10+
collapse_walkthrough: true
11+
path_filters:
12+
- '!build/**'
13+
- '!node_modules/**'
14+
- '!assets/css/*.map'
15+
- '!logs/**'
16+
auto_review:
17+
enabled: true
18+
drafts: false
19+
base_branches:
20+
- 'main'
21+
- 'develop'
22+
- 'feature/*'
23+
- 'fix/*'
24+
- 'update/*'
25+
path_instructions:
26+
- path: '**/block.json'
27+
instructions: |
28+
Review block.json configuration for WordPress block plugins:
29+
- Ensure JSON syntax is valid and properly formatted
30+
- Verify block name, title, description, and category are present
31+
- Check for correct use of supports, attributes, and styles
32+
- Validate icon and keywords fields for discoverability
33+
- Confirm textdomain and namespace usage
34+
- Ensure block is registered for both frontend and editor
35+
- Check for accessibility compliance and ARIA attributes
36+
- Validate custom properties don't conflict with core block functionality
37+
- path: '**/src/{{slug}}/*.js'
38+
instructions: |
39+
Review JavaScript for WordPress block plugin:
40+
- Check for proper WordPress script enqueueing in block.json
41+
- Validate accessibility enhancements don't conflict with core features
42+
- Ensure performance optimization and avoid unnecessary dependencies
43+
- Check compatibility with WordPress script loading patterns
44+
- Verify proper event handling and DOM manipulation
45+
- Ensure scripts work with both frontend and editor interfaces
46+
- path: '**/src/{{slug}}/style.scss'
47+
instructions: |
48+
Review SCSS for WordPress block plugin:
49+
- Prefer block.json configuration over custom CSS when possible
50+
- Ensure SCSS enhances rather than replaces block.json settings
51+
- Check for proper use of CSS custom properties from block.json
52+
- Validate responsive design using consistent breakpoints
53+
- Ensure accessibility compliance in custom styles
54+
- Check for performance optimization (minimal CSS, efficient selectors)
55+
- Verify styles don't conflict with core WordPress block styles
56+
- Ensure proper CSS organization and maintainability
57+
- path: '**/src/{{slug}}/render.php'
58+
instructions: |
59+
Review render.php for WordPress block plugin:
60+
- Ensure server-side rendering follows WordPress block standards
61+
- Validate secure coding practices (sanitization, validation, escaping)
62+
- Check for proper use of block attributes and context
63+
- Ensure compatibility with latest WordPress version
64+
- Check for performance optimization in render functions
65+
- Ensure functions don't conflict with block editor functionality
66+
- path: '**/tests/*.{js,php}'
67+
instructions: |
68+
Review test files for WordPress block plugin:
69+
- Ensure valid syntax, logical structure, and clear instructions
70+
- Check for descriptive test names and clear test structure
71+
- Include both positive and negative test cases
72+
- Reference the block or feature under test
73+
- Be linted and pass all style checks
74+
- Ensure tests have comprehensive inline documentation

‎.github/agents/agent.md‎

Lines changed: 43 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,43 @@
1-
# Single Block WP Plugin — Primary Agent
2-
3-
- **Agent:**
4-
`wp-block-build-agent.js`
5-
- **Workflow:** `.github/workflows/block-build-and-e2e.yml`
6-
- **Purpose:**
7-
Automate a common, repeatable quality task for this repository type.
8-
- **Usage:**
9-
10-
- GitHub Actions: see the workflow file for triggers and env.
11-
- Local: `node
12-
.github/agents/wp-block-build-agent.js`
13-
- **Environment variables:**
14-
-
15-
`DRY_RUN` (default: `false`), `VERBOSE` (default: `false`)
16-
- Additional secrets per
17-
workflow (e.g. `GITHUB_TOKEN` for label ops).
18-
- **Maintenance:** Keep the agent
19-
aligned with repo tooling (linters, build, tests).
1+
# Block Plugin Scaffold: Main Agent Index
2+
3+
## Overview & Related Files
4+
5+
This file documents the primary automation agent(s) for this repository, their purpose, usage, and integration with workflows. Reference this file for agent specs, triggers, and environment variables.
6+
7+
**Related Files:**
8+
9+
- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and plugin instructions
10+
- [Chat Modes](../chatmodes/chatmodes.md) — context-specific Copilot prompts
11+
- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
12+
- [Global AI Rules (AGENTS.md)](../../AGENTS.md) — org-wide agent rules, coding standards, and cross-references
13+
- [WP Block Build Agent Spec](./wp-block-build.agent.md) — detailed build agent spec for single block plugin
14+
15+
---
16+
17+
## Primary Agent: wp-block-build.agent.js
18+
19+
- **Agent Script:** `.github/agents/wp-block-build.agent.js`
20+
- **Spec:** `.github/agents/wp-block-build.agent.md`
21+
- **Workflow:** `.github/workflows/block-plugin-build-and-e2e.yml`
22+
- **Purpose:** Automate build, lint, test, and validation for this block plugin using WordPress and org standards.
23+
24+
### Usage
25+
26+
- **GitHub Actions:** See the workflow file for triggers and environment variables
27+
- **Local:** `node .github/agents/wp-block-build.agent.js`
28+
29+
### Environment Variables
30+
31+
- `DRY_RUN` (default: `false`)
32+
- `VERBOSE` (default: `false`)
33+
- Additional secrets per workflow (e.g., `GITHUB_TOKEN` for label operations)
34+
35+
### Maintenance
36+
37+
- Keep the agent aligned with repo tooling (linters, build, tests)
38+
- Update documentation and scripts as workflows evolve
39+
- See [WP Block Build Agent Spec](./wp-block-build.agent.md) for detailed build process and requirements
40+
41+
---
42+
43+
For more information on agent usage, see [Custom Instructions](../custom-instructions.md), [Workflows](../../workflows/), and [Global AI Rules (AGENTS.md)](../../AGENTS.md).

‎.github/agents/wp-block-build.agent.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// wp-block-build.agent.js
2+
// Automation agent for single block plugin build, lint, and test lifecycle.
3+
// Usage: node .github/agents/wp-block-build.agent.js
4+
5+
const { execSync } = require('child_process');
6+
7+
function run(cmd) {
8+
console.log(`$ ${cmd}`);
9+
execSync(cmd, { stdio: 'inherit' });
10+
}
11+
12+
function main() {
13+
// 1. Install dependencies
14+
run('npm ci');
15+
16+
// 2. Lint
17+
run('npm run lint');
18+
19+
// 3. Build
20+
run('npm run build');
21+
22+
// 4. Test
23+
run('npm test');
24+
25+
// 5. Report success
26+
console.log('Block plugin build agent: All steps completed successfully.');
27+
}
28+
29+
if (require.main === module) {
30+
main();
31+
}

‎.github/agents/wp-block-build.agent.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# WP Block Build Agent Spec
2+
3+
This document defines the specification for the `wp-block-build.agent.js` automation agent, responsible for managing the build, lint, and test lifecycle of a single-block WordPress plugin. It is tightly integrated with the repository's workflows and follows the latest best practices from the official WordPress block development tutorial.
4+
5+
---
6+
7+
## Purpose
8+
9+
- Automate the build, lint, test, and validation process for a single-block plugin.
10+
- Ensure all code changes are validated against WordPress and org standards before merging or deployment.
11+
- Provide a consistent, reproducible build and test process for local and CI/CD environments.
12+
13+
---
14+
15+
## Key References
16+
17+
- [Main Agent Index](./agent.md)
18+
- [Global AI Rules (AGENTS.md)](../../AGENTS.md)
19+
- [WordPress Block Editor Tutorial](https://developer.wordpress.org/block-editor/getting-started/tutorial/)
20+
- [Block.json Reference](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/)
21+
22+
---
23+
24+
## Build Process Overview
25+
26+
1. **Install**: Ensure all required dependencies are installed (`npm ci`).
27+
2. **Lint**: Run all linters (JS, CSS, PHP) and fail on any errors.
28+
3. **Build**: Use `@wordpress/scripts` and custom webpack config to build assets.
29+
4. **Test**: Run all tests (Jest, Playwright, PHPunit, etc.).
30+
5. **Report**: Output a summary of all steps, errors, and next actions.
31+
32+
---
33+
34+
## Environment Variables
35+
36+
- `DRY_RUN`: If true, only print steps without executing them.
37+
- `VERBOSE`: If true, print detailed logs for each step.
38+
- `GITHUB_TOKEN`: For workflow and label operations (if needed).
39+
40+
---
41+
42+
## Maintenance & Best Practices
43+
44+
- Keep this spec in sync with the [WordPress Block Editor Tutorial](https://developer.wordpress.org/block-editor/getting-started/tutorial/) and org [AGENTS.md](../../AGENTS.md).
45+
- Update the agent and this spec as new best practices or requirements emerge.
46+
- Ensure all contributors are aware of this spec and reference it in PRs and workflow changes.
47+
48+
---
49+
50+
## Example Build Command
51+
52+
```sh
53+
node .github/agents/wp-block-build.agent.js --verbose
54+
```
55+
56+
---
57+
58+
## See Also
59+
60+
- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
61+
- [Block.json Reference](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/)
62+
- [Block Development Examples](https://github.com/WordPress/block-development-examples)

‎.github/chatmodes/chatmodes.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Block Plugin Scaffold: Chat Modes & AI Assistant
2+
3+
## Overview & Related Files
4+
5+
This repository supports multiple Copilot/AI chat modes for different block plugin development scenarios. Use the right mode for your task and reference related files for best results.
6+
7+
**Related Files:**
8+
9+
- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
10+
- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and plugin instructions
11+
- [Main Agent Index](../agents/agent.md) — agent specs and usage
12+
- [WP Block Build Agent Spec](../agents/wp-block-build.agent.md) — build agent spec for this scaffold
13+
- [WP Block Build Agent Script](../agents/wp-block-build.agent.js) — automation agent for build/lint/test
14+
- [Block Plugin Build Workflow](../../workflows/block-plugin-build-and-e2e.yml) — CI/CD workflow for this scaffold
15+
16+
---
17+
18+
## Chat Modes for Block Plugin Development
19+
20+
**Available Modes:**
21+
22+
- **Block Authoring Mode**: Block creation, markup, and registration
23+
- **block.json Editing Mode**: Schema, tokens, and validation for block.json and style variations
24+
- **PHP/JS/SCSS Expert Mode**: Advanced code, refactoring, and best practices
25+
- **Testing & QA Mode**: Playwright, Jest, PHPUnit, and accessibility testing
26+
27+
**How to Switch Modes:**
28+
29+
- Use the Copilot command palette or chat mode selector in your IDE
30+
- Reference this file for mode-specific quick commands and best practices
31+
32+
**Best Practices:**
33+
34+
- Always specify the context (file, feature, or problem) when starting a new chat
35+
- Use quick commands for common tasks (see below) and reference prompt templates for consistent output
36+
- Review all Copilot/AI suggestions for accuracy, security, and accessibility
37+
38+
---
39+
40+
# {{projectName}} Development Chat Mode
41+
42+
I'm your WordPress block plugin development assistant for **{{projectName}}**. I can help you with:
43+
44+
## What I Can Help With
45+
46+
### 🎨 Block Development
47+
48+
- Block creation and customization
49+
- Style variations and block.json configuration
50+
- Custom block styles and variations
51+
52+
### 🔧 Technical Support
53+
54+
- WordPress Block Editor (Gutenberg) integration
55+
- Build process and asset compilation
56+
- Testing and debugging
57+
58+
### 📝 Code Generation
59+
60+
- PHP functions following WordPress standards
61+
- JavaScript for block functionality
62+
- SCSS/CSS for styling
63+
- Block template HTML
64+
65+
### 🚀 Best Practices
66+
67+
- Performance optimization
68+
- Accessibility compliance
69+
- Security implementation
70+
- WordPress coding standards
71+
- For automation, always use the [WP Block Build Agent](../agents/wp-block-build.agent.js) and [workflow](../../workflows/block-plugin-build-and-e2e.yml) for build/lint/test/CI.
72+
73+
## How to Work With Me
74+
75+
### Quick Commands
76+
77+
- `help blocks` — Block authoring assistance
78+
- `help styles` — Styling and block.json
79+
- `help js` — JavaScript functionality
80+
- `help testing` — Testing strategies
81+
- `help build` — Build process help
82+
83+
### Example Requests
84+
85+
- "Create a testimonial block with call-to-action"
86+
- "Add dark mode style variation"
87+
- "Fix block alignment issues"
88+
- "Optimize plugin performance"
89+
90+
## Current Plugin Context
91+
92+
- **Plugin**: {{projectName}}
93+
- **Slug**: {{slug}}
94+
- **Version**: {{version}}
95+
- **Architecture**: WordPress Block Plugin
96+
- **Build**: Webpack + @wordpress/scripts
97+
- **Standards**: WordPress Coding Standards
98+
99+
## Quick Reference
100+
101+
**File Structure:**
102+
103+
```
104+
{{slug}}/
105+
├── src/
106+
│ ├── {{slug}}/
107+
│ │ ├── block.json
108+
│ │ ├── edit.js
109+
│ │ ├── save.js
110+
│ │ ├── index.js
111+
│ │ ├── render.php
112+
│ │ └── style.scss
113+
│ ├── scss/
114+
│ │ ├── editor.scss
115+
│ │ └── style.scss
116+
│ └── index.js
117+
├── bin/
118+
├── tests/
119+
├── .github/
120+
├── docs/
121+
├── {{slug}}.php
122+
├── package.json
123+
├── composer.json
124+
├── .wp-env.json
125+
└── CODEOWNERS
126+
```
127+
128+
**Common Patterns:**
129+
130+
- Testimonial blocks
131+
- Call-to-action blocks
132+
- Gallery blocks
133+
134+
**Available Hooks:**
135+
136+
- `{{slug}}_init` — Plugin/block setup
137+
- `{{slug}}_enqueue_assets` — Asset loading
138+
139+
---
140+
141+
## Let's Build Together
142+
143+
Just ask me what you'd like to work on, and I'll provide specific, actionable code and guidance for **{{projectName}}**.
144+
145+
**Examples:**
146+
147+
- "How do I add a new block?"
148+
- "Create a pricing table block"
149+
- "Help me style the testimonial block"
150+
- "Add animation to the call-to-action block"
151+
- "Optimize images for better performance"
152+
153+
I'm here to help you create an amazing WordPress block plugin! 🚀

0 commit comments

Comments
 (0)