Skip to content

Commit 634d391

Browse files
ashleyshawashleyshaw
committed
Add block theme automation agents and documentation
Introduces a comprehensive agent system for WordPress block theme development, including the main build agent script, agent specifications, chat modes, prompt templates, and detailed instructions for theme, PHP, testing, and JSON validation. Updates documentation to reference new agent and AI usage files, adds a workflow for build/lint/test automation, and enhances .gitignore for scaffold-specific needs. Also adds a theme generator script and updates package.json with relevant metadata and keywords.
1 parent 68ec056 commit 634d391

23 files changed

+1279
-214
lines changed

‎.coderabbit.yml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
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: "**/theme.json"
27+
instructions: |
28+
Review theme.json configuration for WordPress block themes:
29+
- Ensure JSON syntax is valid and properly formatted
30+
- Verify color palettes use named tokens consistently (primary, secondary, accent)
31+
- Check typography settings include complete font definitions with fluid clamp() values
32+
- Validate spacing scales are consistent and use rem units
33+
- Confirm layout settings define appropriate contentSize and wideSize values
34+
- Ensure all settings follow WordPress block theme standards
35+
- Check accessibility compliance with sufficient color contrast ratios (4.5:1 minimum)
36+
- Verify compatibility with Full Site Editing (FSE) features
37+
- Validate custom properties don't conflict with core block functionality
38+
- path: "**/patterns/*.php"
39+
instructions: |
40+
Review WordPress block patterns for FSE compatibility:
41+
- Ensure proper pattern registration using register_block_pattern() function
42+
- Verify pattern naming follows lsx/[category]-[name] convention
43+
- Check that patterns use theme.json variables exclusively for styling
44+
- Validate proper heading hierarchy and accessibility compliance
45+
- Ensure placeholder content is realistic and appropriate
46+
- Check patterns maintain design integrity with different content lengths
47+
- Verify patterns are responsive and work across all viewport sizes
48+
- Confirm patterns avoid inline styles and use block variations appropriately
49+
- Validate proper block nesting and semantic HTML structure
50+
- Test that patterns follow WordPress coding standards for PHP
51+
- path: "**/parts/*.html"
52+
instructions: |
53+
Review WordPress template parts for block theme compatibility:
54+
- Ensure template parts follow WordPress HTML template structure
55+
- Verify proper use of WordPress block markup
56+
- Check semantic HTML elements and proper heading hierarchy
57+
- Validate accessibility features (ARIA roles, alt attributes)
58+
- Ensure template parts use theme.json variables for styling
59+
- Check compatibility with Full Site Editing interface
60+
- Verify proper block structure and nesting
61+
- Validate responsive design across different screen sizes
62+
- path: "**/templates/*.html"
63+
instructions: |
64+
Review WordPress block templates for FSE:
65+
- Ensure templates follow WordPress block template structure
66+
- Verify proper template hierarchy and naming conventions
67+
- Check integration with template parts and patterns
68+
- Validate proper query loop implementation for dynamic content
69+
- Ensure templates maintain design consistency
70+
- Check accessibility compliance throughout templates
71+
- Verify responsive behavior and layout integrity
72+
- path: "**/functions.php"
73+
instructions: |
74+
Review functions.php for WordPress block theme:
75+
- Ensure theme setup follows WordPress block theme standards
76+
- Verify proper theme support declarations for FSE features
77+
- Check secure coding practices (sanitization, validation, escaping)
78+
- Validate proper hook usage and WordPress coding standards
79+
- Ensure compatibility with latest WordPress version
80+
- Check for performance optimization in theme functions
81+
- Verify proper asset enqueueing and dependency management
82+
- Ensure functions don't conflict with block editor functionality
83+
- path: "**/*.{css,scss}"
84+
instructions: |
85+
Review CSS/SCSS for WordPress block theme:
86+
- Prefer theme.json configuration over custom CSS when possible
87+
- Ensure CSS enhances rather than replaces theme.json settings
88+
- Check for proper use of CSS custom properties from theme.json
89+
- Validate responsive design using consistent breakpoints
90+
- Ensure accessibility compliance in custom styles
91+
- Check for performance optimization (minimal CSS, efficient selectors)
92+
- Verify styles don't conflict with core WordPress block styles
93+
- Ensure proper CSS organization and maintainability
94+
- path: "**/e2e/*.{ts,js}"
95+
instructions: |
96+
Review Playwright end-to-end tests for WordPress block theme:
97+
- Ensure tests cover accessibility validation across all pages
98+
- Verify tests check responsive design at multiple breakpoints
99+
- Check tests validate Full Site Editing functionality
100+
- Ensure tests cover block pattern and template part functionality
101+
- Verify proper test structure, setup, and teardown
102+
- Ensure tests are reliable and not flaky
103+
- path: "**/src/js/*.js"
104+
instructions: |
105+
Review JavaScript for WordPress block theme:
106+
- Check for proper WordPress script enqueueing in functions.php
107+
- Validate accessibility enhancements don't conflict with core features
108+
- Ensure performance optimization and avoid unnecessary dependencies
109+
- Check compatibility with WordPress script loading patterns
110+
- Verify proper event handling and DOM manipulation
111+
- Ensure scripts work with both frontend and editor interfaces

‎.github/agents/agent.md‎

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,54 @@
1-
# Single Block WP Plugin — Primary Agent
1+
## Overview & Related Files
22

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:**
3+
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.
4+
5+
**Related Files:**
6+
- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and theme instructions
7+
- [Chat Modes](../chatmodes/chatmodes.md) — context-specific Copilot prompts
8+
- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
9+
10+
---
11+
12+
## Primary Agent: block-theme-build.agent.js
13+
14+
- **Agent Script:** `.github/agents/block-theme-build.agent.js`
15+
- **Spec:** `.github/agents/block-theme-build.agent.md`
16+
- **Workflow:** `.github/workflows/block-theme-build-and-e2e.yml`
17+
- **Purpose:** Automate build, lint, test, and validation for this block theme using WordPress and org standards.
18+
19+
### Usage
20+
- **GitHub Actions:** See the workflow file for triggers and environment variables
21+
- **Local:** `node .github/agents/block-theme-build.agent.js`
22+
23+
### Environment Variables
24+
- `DRY_RUN` (default: `false`)
25+
- `VERBOSE` (default: `false`)
26+
- Additional secrets per workflow (e.g., `GITHUB_TOKEN` for label operations)
27+
28+
### Maintenance
29+
- Keep the agent aligned with repo tooling (linters, build, tests)
30+
- Update documentation and scripts as workflows evolve
31+
- See [Block Theme Build Agent Spec](./block-theme-build.agent.md) for detailed build process and requirements
932

10-
- GitHub Actions: see the workflow file for triggers and env.
11-
- Local: `node
12-
.github/agents/wp-block-build-agent.js`
33+
---
34+
35+
## Example: Agent Spec Template (for new agents)
36+
37+
Use the following as a template for documenting new agents:
38+
39+
---
40+
41+
- **Agent:** `agent-script.js`
42+
- **Workflow:** `.github/workflows/agent-workflow.yml`
43+
- **Purpose:** Automate a common, repeatable quality task for this repository type.
44+
- **Usage:**
45+
- GitHub Actions: see the workflow file for triggers and environment variables
46+
- Local: `node .github/agents/agent-script.js`
1347
- **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).
48+
- `DRY_RUN` (default: `false`), `VERBOSE` (default: `false`)
49+
- Additional secrets per workflow (e.g., `GITHUB_TOKEN` for label ops)
50+
- **Maintenance:** Keep the agent aligned with repo tooling (linters, build, tests)
51+
52+
---
53+
54+
For more information on agent usage, see [Custom Instructions](../custom-instructions.md) and [Workflows](../../workflows/).

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// block-theme-build.agent.js
2+
// Automation agent for WordPress block theme build, lint, and test lifecycle.
3+
// Usage: node .github/agents/block-theme-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 theme build agent: All steps completed successfully.');
27+
}
28+
29+
if (require.main === module) {
30+
main();
31+
}

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

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

‎.github/chatmodes/chatmodes.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Block Theme Scaffold: Chat Modes & AI Assistant
2+
3+
# Block Theme Scaffold: Chat Modes & AI Assistant
4+
5+
## Overview & Related Files
6+
7+
This repository supports multiple Copilot/AI chat modes for different block theme development scenarios. Use the right mode for your task and reference related files for best results.
8+
9+
**Related Files:**
10+
11+
- [Prompts](../prompts/prompts.md) — prompt templates for consistent output
12+
- [Custom Instructions](../custom-instructions.md) — main AI/Copilot and theme instructions
13+
- [Main Agent Index](../agents/agent.md) — agent specs and usage
14+
15+
---
16+
17+
## Chat Modes for Block Theme Development
18+
19+
**Available Modes:**
20+
21+
- **Pattern Authoring Mode**: Block pattern creation, markup, and registration
22+
- **Theme.json Editing Mode**: Schema, tokens, and validation for theme.json and style variations
23+
- **PHP/JS/SCSS Expert Mode**: Advanced code, refactoring, and best practices
24+
- **Testing & QA Mode**: Playwright, Jest, PHPUnit, and accessibility testing
25+
26+
**How to Switch Modes:**
27+
28+
- Use the Copilot command palette or chat mode selector in your IDE
29+
- Reference this file for mode-specific quick commands and best practices
30+
31+
## Example: {{theme_name}} Development Chat Mode Template
32+
33+
Use the following as a template for project-specific chat mode documentation:
34+
35+
---
36+
37+
I'm your WordPress block theme development assistant for **{{theme_name}}**. I can help you with:
38+
39+
**What I Can Help With:**
40+
41+
- Block pattern creation and customization
42+
- Template part development
43+
- Style variations and theme.json configuration
44+
- Custom block styles and variations
45+
- WordPress Block Editor (Gutenberg) integration
46+
- Full Site Editing (FSE) implementation
47+
- Build process and asset compilation
48+
- Testing and debugging
49+
- PHP functions following WordPress standards
50+
- JavaScript for theme functionality
51+
- SCSS/CSS for styling
52+
- Block template HTML
53+
- Performance optimization
54+
- Accessibility compliance
55+
- Security implementation
56+
- WordPress coding standards
57+
58+
**How to Work With Me:**
59+
60+
- `help patterns` — Block pattern assistance
61+
- `help templates` — Template development
62+
- `help styles` — Styling and theme.json
63+
- `help js` — JavaScript functionality
64+
- `help testing` — Testing strategies
65+
- `help build` — Build process help
66+
67+
**Example Requests:**
68+
69+
- "Create a hero pattern with call-to-action"
70+
- "Add dark mode style variation"
71+
- "Fix responsive navigation"
72+
- "Optimize theme performance"
73+
74+
**Current Theme Context:**
75+
76+
- **Theme**: {{theme_name}}
77+
- **Slug**: {{theme_slug}}
78+
- **Version**: {{version}}
79+
- **Architecture**: WordPress Block Theme with FSE
80+
- **Build**: Webpack + @wordpress/scripts
81+
- **Standards**: WordPress Coding Standards
82+
83+
**Quick Reference:**
84+
85+
```
86+
{{theme_slug}}/
87+
├── templates/ # Block templates (HTML)
88+
├── parts/ # Template parts
89+
├── patterns/ # Block patterns
90+
├── styles/ # Style variations
91+
├── src/ # Source files
92+
├── inc/ # PHP includes
93+
└── theme.json # Global configuration
94+
```
95+
96+
**Common Patterns:**
97+
98+
- Hero sections
99+
- Call-to-action blocks
100+
- Team member grids
101+
- Testimonial layouts
102+
- Gallery patterns
103+
104+
**Available Hooks:**
105+
106+
- `{{theme_slug}}_setup` — Theme setup
107+
- `{{theme_slug}}_enqueue_assets` — Asset loading
108+
- `{{theme_slug}}_customize_register` — Customizer options
109+
110+
---
111+
112+
## Let's Build Together
113+
114+
Just ask me what you'd like to work on, and I'll provide specific, actionable code and guidance for **{{theme_name}}**.
115+
116+
**Examples:**
117+
118+
- "How do I add a new block pattern?"
119+
- "Create a contact form template"
120+
- "Help me style the navigation menu"
121+
- "Add animation to the hero section"
122+
- "Optimize images for better performance"
123+
124+
I'm here to help you create an amazing WordPress block theme! 🚀
125+
**Examples:**
126+
127+
- "How do I add a new block pattern?"
128+
- "Create a contact form template"
129+
- "Help me style the navigation menu"
130+
- "Add animation to the hero section"
131+
- "Optimize images for better performance"
132+
133+
I'm here to help you create an amazing WordPress block theme! 🚀

0 commit comments

Comments
 (0)