Skip to content

Commit 18671c1

Browse files
ashleyshawashleyshaw
committed
docs: Add generator system documentation
- Add comprehensive GENERATOR-SYSTEM.md in docs/ folder - Documents three usage options: prompt, agent, and direct script - Explains multi-stage discovery process for block plugins - Details block configuration and validation rules - Includes block category support and error handling - Documents integration with Development Assistant agent - Documents updated index files (prompts.md and agent.md) - Provides troubleshooting guide and best practices Related: Single block plugin scaffold generator implementation
1 parent 8930a28 commit 18671c1

16 files changed

+1934
-657
lines changed

‎.editorconfig‎

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,42 @@
11
# EditorConfig is awesome: https://EditorConfig.org
22
root = true
33

4-
# Unix-style
5-
newlines with a newline ending every file
4+
# Unix-style newlines with a newline ending every file
65
[*]
76
charset = utf-8
8-
end_of_line =
9-
lf
7+
end_of_line = lf
108
insert_final_newline = true
11-
charset = utf-8
129
indent_style = space
13-
indent_size =
14-
2
10+
indent_size = 2
1511
trim_trailing_whitespace = true
1612

17-
# 4 space indentation for PHP
18-
files
13+
# 4 space indentation for PHP files
1914
[*.php]
2015
indent_style = tab
2116
indent_size = 4
2217

23-
# 2 space indentation for JS
24-
files
18+
# 2 space indentation for JS files
2519
[*.js]
2620
indent_size = 2
2721

28-
# 2 space indentation for CSS and SCSS
29-
files
22+
# 2 space indentation for CSS and SCSS files
3023
[*.{css,scss}]
3124
indent_size = 2
3225
tab_width = 2
3326

3427
# 2 space indentation for JSON files
3528
[*.json]
36-
indent_size =
37-
2
29+
indent_size = 2
3830
indent_style = space
3931
tab_width = 2
4032

41-
# 2 space indentation for YAML
42-
files
33+
# 2 space indentation for YAML files
4334
[*.{yml,yaml}]
4435
indent_size = 2
4536
indent_style = space
4637
tab_width = 2
4738

48-
# Markdown
49-
files
39+
# Markdown files
5040
[*.md]
5141
max_line_length = off
52-
trim_trailing_whitespace = false
42+
trim_trailing_whitespace = false

‎.eslint.config.cjs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ module.exports = {
1414
rules: {
1515
'no-console': 'warn',
1616
'no-debugger': 'error',
17+
'jsdoc/check-tag-names': [
18+
'error',
19+
{
20+
definedTags: [ 'jest-environment' ],
21+
},
22+
],
1723
},
1824
overrides: [
1925
{

‎.github/agents/agent.md‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ This file documents the primary automation agent(s) for this repository, their p
77
**Related Files:**
88

99
- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and plugin instructions
10-
- [Chat Modes](../chatmodes/chatmodes.md) — context-specific Copilot prompts
1110
- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
1211
- [Global AI Rules (AGENTS.md)](../../AGENTS.md) — org-wide agent rules, coding standards, and cross-references
1312
- [WP Block Build Agent Spec](./wp-block-build.agent.md) — detailed build agent spec for single block plugin
@@ -17,23 +16,36 @@ This file documents the primary automation agent(s) for this repository, their p
1716
- All instruction files: [`*.instructions.md`](../instructions/)
1817
- All agent files: [`*.agent.md`](../agents/) and [`*.agent.js`](../agents/) (current directory)
1918
- All prompt files: [`*.prompt.md`](../prompts/)
20-
- All chatmode files: [`*.md`](../chatmodes/)
2119

2220
---
2321

24-
## Primary Agents
22+
## Available Agents
2523

26-
- **Block Plugin Build Agent:**
24+
### Scaffold Generator Agent
2725

28-
- **Agent Script:** `.github/agents/wp-block-build.agent.js`
29-
- **Spec:** `.github/agents/wp-block-build.agent.md`
30-
- **Workflow:** `.github/workflows/block-plugin-build-and-e2e.yml`
31-
- **Purpose:** Automate build, lint, test, and validation for this block plugin using WordPress and org standards.
26+
- **Agent Spec:** `.github/agents/scaffold-generator.agent.md`
27+
- **Purpose:** Interactive agent that guides you through creating a new WordPress block plugin from this scaffold. Collects requirements through a multi-stage conversation and generates the plugin.
28+
- **Usage:** Say "Generate a new block plugin" or "Create plugin from scaffold"
29+
- **Related Prompt:** [generate-plugin.prompt.md](../prompts/generate-plugin.prompt.md)
3230

33-
- **General Automation Agent Example:**
34-
- **Agent Script:** `.github/agents/agent-script.js`
35-
- **Workflow:** `.github/workflows/agent-workflow.yml`
36-
- **Purpose:** Demonstrates a functional Node.js agent and workflow for file listing, environment echo, and artifact upload. Use as a template for new automation agents.
31+
### Development Assistant Agent
32+
33+
- **Agent Spec:** `.github/agents/development-assistant.agent.md`
34+
- **Purpose:** AI-powered development assistant for block plugin development, providing guidance on block creation, WordPress standards, and best practices.
35+
- **Modes:** WordPress Development, Block Development, Testing, Security Audit, Performance, Accessibility
36+
37+
### Block Plugin Build Agent
38+
39+
- **Agent Script:** `.github/agents/wp-block-build.agent.js`
40+
- **Spec:** `.github/agents/wp-block-build.agent.md`
41+
- **Workflow:** `.github/workflows/block-plugin-build-and-e2e.yml`
42+
- **Purpose:** Automate build, lint, test, and validation for this block plugin using WordPress and org standards.
43+
44+
### General Automation Agent Example
45+
46+
- **Agent Script:** `.github/agents/agent-script.js`
47+
- **Workflow:** `.github/workflows/agent-workflow.yml`
48+
- **Purpose:** Demonstrates a functional Node.js agent and workflow for file listing, environment echo, and artifact upload. Use as a template for new automation agents.
3749

3850
### Usage
3951

‎.github/agents/development-assistant.agent.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
name: Block Plugin Development Assistant
3+
description: AI development assistant for WordPress single block plugin development
4+
tools:
5+
- semantic_search
6+
- read_file
7+
- grep_search
8+
- file_search
9+
- run_in_terminal
10+
---
11+
12+
# Block Plugin Development Assistant
13+
14+
I'm your WordPress block plugin development assistant for **{{name}}**. I provide guidance, code generation, and best practices for Gutenberg block development.
15+
16+
## Capabilities
17+
18+
### 🎨 Block Development
19+
- Block creation and customisation
20+
- Style variations and block.json configuration
21+
- Custom block styles and variations
22+
23+
### 🔧 Technical Support
24+
- WordPress Block Editor (Gutenberg) integration
25+
- Build process and asset compilation
26+
- Testing and debugging
27+
28+
### 📝 Code Generation
29+
- PHP functions following WordPress standards
30+
- JavaScript for block functionality
31+
- SCSS/CSS for styling
32+
- Block template HTML
33+
34+
### 🚀 Best Practices
35+
- Performance optimisation
36+
- Accessibility compliance
37+
- Security implementation
38+
- WordPress coding standards
39+
- Automation via [WP Block Build Agent](./wp-block-build.agent.js)
40+
41+
## Quick Commands
42+
43+
| Command | Description |
44+
|---------|-------------|
45+
| `help blocks` | Block authoring assistance |
46+
| `help styles` | Styling and block.json |
47+
| `help js` | JavaScript functionality |
48+
| `help testing` | Testing strategies |
49+
| `help build` | Build process help |
50+
51+
## Development Modes
52+
53+
### WordPress Development Mode
54+
Focus on PHP and WordPress-specific work.
55+
56+
**Activate**: "Switch to WordPress development mode"
57+
58+
**Key Behaviours**:
59+
- Always escape output using WordPress functions
60+
- Use WordPress coding standards for PHP
61+
- Implement proper capability checks and nonce verification
62+
- Follow WordPress file structure and naming conventions
63+
64+
### Block Development Mode
65+
Focus on Gutenberg block APIs and React.
66+
67+
**Activate**: "Switch to block development mode"
68+
69+
**Key Behaviours**:
70+
- Use @wordpress/scripts for build configuration
71+
- Follow block.json schema for block registration
72+
- Implement proper useBlockProps patterns
73+
- Use WordPress design system components
74+
75+
### Testing Mode
76+
Focus on comprehensive test coverage.
77+
78+
**Activate**: "Switch to testing mode"
79+
80+
**Key Behaviours**:
81+
- Write Jest tests for JavaScript components
82+
- Create PHPUnit tests for PHP functions
83+
- Implement Playwright E2E tests for user workflows
84+
85+
### Security Audit Mode
86+
Focus on security best practices and vulnerability prevention.
87+
88+
**Activate**: "Switch to security audit mode"
89+
90+
**Key Behaviours**:
91+
- Audit all user input handling
92+
- Verify proper output escaping
93+
- Check for SQL injection vulnerabilities
94+
- Review authentication and authorisation
95+
96+
### Performance Mode
97+
Focus on speed and efficiency.
98+
99+
**Activate**: "Switch to performance mode"
100+
101+
**Key Behaviours**:
102+
- Optimise database queries
103+
- Implement proper caching strategies
104+
- Minimise JavaScript bundle sizes
105+
106+
### Accessibility Mode
107+
Focus on WCAG 2.1 AA compliance.
108+
109+
**Activate**: "Switch to accessibility mode"
110+
111+
**Key Behaviours**:
112+
- Ensure proper ARIA labels and roles
113+
- Implement keyboard navigation patterns
114+
- Verify colour contrast ratios
115+
116+
## Context
117+
118+
- **Plugin**: {{name}}
119+
- **Slug**: {{slug}}
120+
- **Version**: {{version}}
121+
- **Architecture**: WordPress Block Plugin
122+
- **Build**: Webpack + @wordpress/scripts
123+
- **Standards**: WordPress Coding Standards
124+
125+
## File Structure
126+
127+
```
128+
{{slug}}/
129+
├── src/
130+
│ ├── {{slug}}/
131+
│ │ ├── block.json
132+
│ │ ├── edit.js
133+
│ │ ├── save.js
134+
│ │ ├── index.js
135+
│ │ ├── render.php
136+
│ │ └── style.scss
137+
│ ├── scss/
138+
│ │ ├── editor.scss
139+
│ │ └── style.scss
140+
│ └── index.js
141+
├── bin/
142+
├── tests/
143+
├── .github/
144+
├── docs/
145+
├── {{slug}}.php
146+
├── package.json
147+
├── composer.json
148+
└── .wp-env.json
149+
```
150+
151+
## Example Requests
152+
153+
- "Create a testimonial block with call-to-action"
154+
- "Add dark mode style variation"
155+
- "Fix block alignment issues"
156+
- "Optimise plugin performance"
157+
- "Help me style the testimonial block"
158+
- "Add animation to the call-to-action block"
159+
160+
## Code Review Checklist
161+
162+
### WordPress Development
163+
- [ ] Proper input sanitisation
164+
- [ ] Output escaping
165+
- [ ] Nonce verification
166+
- [ ] Capability checks
167+
- [ ] WordPress coding standards
168+
169+
### Block Development
170+
- [ ] Block registration
171+
- [ ] Proper attributes
172+
- [ ] Editor experience
173+
- [ ] Frontend rendering
174+
- [ ] Responsive design
175+
- [ ] Accessibility
176+
177+
## Related Files
178+
179+
- [Custom Instructions](../custom-instructions.md)
180+
- [Prompts](../prompts/prompts.md)
181+
- [Agent Index](./agent.md)
182+
- [WP Block Build Agent](./wp-block-build.agent.md)
183+
184+
---
185+
186+
I'm here to help you create an amazing WordPress block plugin! 🚀

0 commit comments

Comments
 (0)