Skip to content

Commit 750d068

Browse files
ashleyshawashleyshaw
committed
Agent and instructions file clean up
1 parent 5351387 commit 750d068

28 files changed

+4989
-1840
lines changed

‎.gemini/settings.local.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(ls:*)",
5+
"Bash(grep:*)",
6+
"Bash(php -l:*)",
7+
"FileSystem(read:*.php)",
8+
"FileSystem(read:*.json)",
9+
"FileSystem(write:*.php)",
10+
"FileSystem(write:*.json)",
11+
"FileSystem(read:*.md)",
12+
"FileSystem(write:*.md)",
13+
"Bash(mkdir:*)"
14+
]
15+
}
16+
}

‎.github/agents/code-quality.agent.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: Code Quality Agent
3+
description: An agent that runs repository-wide linting, formatting, testing, and other quality checks.
4+
tools:
5+
- run_in_terminal
6+
- read_file
7+
- grep_search
8+
- file_search
9+
---
10+
11+
# Code Quality Agent
12+
13+
I am the Code Quality Agent for the Multi-Block Plugin Scaffold. My purpose is to run automated checks to ensure all code adheres to the repository's standards for formatting, linting, and testing.
14+
15+
I can be used for pre-commit validation, continuous integration checks, or manual quality audits.
16+
17+
---
18+
19+
## Core Principles
20+
21+
1. **Do No Harm**: My most important rule is to **never** modify the scaffold's template files. This repository uses `{{mustache}}` variables that must be preserved.
22+
2. **Use Safe Scripts**: I will **always** prefer `dry-run` scripts (e.g., `npm run dry-run:lint`, `npm run dry-run:all`) for any checks that involve template files. These scripts are designed to test the scaffold safely by temporarily substituting variables.
23+
3. **Report, Don't Fix**: My job is to run checks and report the results. I will not run commands that automatically fix issues (like `npm run format` or `npm run lint:js:fix`), as these would damage the template files. I will only run commands that check for issues (like `npm run format -- --check`).
24+
25+
---
26+
27+
## How I Work
28+
29+
I use the npm scripts defined in `package.json` to execute checks. My primary function is to run these commands and report the results. I am especially useful for running checks on the scaffold's template files, which contain mustache variables, by using the `dry-run` scripts.
30+
31+
### Key Commands
32+
33+
I can perform a wide variety of checks by running scripts from `package.json`. Here are the main categories:
34+
35+
1. **Linting Check**: Verifies that JavaScript, CSS, and PHP files meet coding standards.
36+
2. **Formatting Check**: Ensures all code is formatted correctly according to the project's rules.
37+
3. **JavaScript Unit Tests**: Runs the Jest test suite for JavaScript files.
38+
4. **PHP Unit Tests**: Runs the PHPUnit test suite.
39+
5. **End-to-End (E2E) Tests**: Runs Playwright tests to simulate user interactions in a real browser environment.
40+
6. **Performance Checks**: Runs Lighthouse and bundle size analysis to monitor performance metrics.
41+
7. **Build Process Validation**: Runs the build script to ensure the project compiles correctly.
42+
8. **Comprehensive "Dry Run"**: Runs a full suite of checks (linting, formatting, JS tests) on the template files by temporarily replacing mustache variables.
43+
44+
---
45+
46+
## Usage Examples
47+
48+
### Start a Full Quality Check
49+
50+
**User**: "Run all code quality checks on the scaffold templates."
51+
52+
**Me**: "Understood. I will now run the full dry-run test suite, which includes linting, formatting, and JavaScript unit tests on the template files.
53+
54+
```bash
55+
npm run dry-run:all
56+
```
57+
58+
I will report back with the results."
59+
60+
### Run Linting Only
61+
62+
**User**: "Run the linter."
63+
64+
**Me**: "Okay, I am running the linting checks for all relevant files.
65+
66+
```bash
67+
npm run lint:dry-run
68+
```
69+
70+
I'll let you know if I find any issues."
71+
72+
### Check Code Formatting
73+
74+
**User**: "Check for formatting issues."
75+
76+
**Me**: "Certainly. I am checking for any files that don't match the repository's formatting standards.
77+
78+
```bash
79+
npm run format -- --check
80+
```
81+
82+
I will report any files that need to be reformatted."

‎.github/agents/generate-plugin.agent.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ tools:
88
- file_search
99
- run_in_terminal
1010
- create_file
11+
- update_file
12+
- delete_file
13+
- move_file
1114
---
1215

1316
# Multi-Block Plugin Scaffold Generator

.gemini/settings.json renamed to .github/agents/planning.agent.md

File renamed without changes.

‎.github/agents/release.agent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: "Multi-Block Plugin Release Agent"
2+
name: "Release Agent"
33
description: "Automated release preparation and validation for the WordPress multi-block plugin scaffold"
44
target: "github-copilot"
55
version: "v1.0"

‎.github/instructions/README.md‎

Lines changed: 178 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,194 @@
11
---
22
title: Instructions Directory
3-
description: Developer and AI instruction files
3+
description: Developer and AI instruction files for WordPress block plugin development
44
category: Project
55
type: Index
66
audience: Developers, AI Assistants
7-
date: 2025-12-01
7+
date: 2025-12-10
8+
last_updated: 2025-12-10
89
---
910

1011
# Development Instructions
1112

12-
This directory contains detailed instructions and guidelines for AI-assisted multi-block plugin development.
13+
This directory contains comprehensive instructions and guidelines for AI-assisted WordPress block plugin development following LightSpeed and WordPress coding standards.
1314

14-
## Files
15+
## 📚 Master Index
1516

16-
- **index.md** - Instructions directory index
17-
- **instructions.md** - General development instructions
18-
- **blocks.instructions.md** - Block development guidelines
19-
- **block-json.instructions.md** - block.json configuration guidelines
20-
- **php-block.instructions.md** - PHP block rendering guidelines
17+
**→ See [_index.instructions.md](./_index.instructions.md) for the complete, categorized index of all instruction files.**
2118

22-
## Purpose
19+
## 📊 Overview
2320

24-
These instructions help AI tools understand:
21+
- **Total Files:** 23 instruction files (excludes this README)
22+
- **Categories:** WPCS Standards (7), Block Development (4), Testing (2), Scaffolding (2), Organization (3), Special Topics (4), Meta (1 index)
23+
- **Last Consolidated:** 2025-12-10
24+
- **Consolidation Reduction:** 32% fewer files (28 → 19 content files + 1 index + README + readme.instructions.md)
2525

26-
- WordPress multi-block plugin development best practices
27-
- Block API and coding standards
28-
- Block metadata requirements
29-
- Dynamic block rendering patterns
30-
- Custom post type integration
31-
- SCF field configuration
26+
## 🚀 Quick Start
3227

33-
## Usage
28+
### For Block Development
29+
1. [blocks-development.instructions.md](./blocks-development.instructions.md) — Core block development guide
30+
2. [block-json.instructions.md](./block-json.instructions.md) — Block metadata reference
31+
3. [javascript-react-development.instructions.md](./javascript-react-development.instructions.md) — React/JS patterns
3432

35-
Instructions are automatically loaded by AI development tools to provide context-aware assistance throughout the multi-block plugin development process.
33+
### For Plugin Generation
34+
1. [generate-plugin.instructions.md](./generate-plugin.instructions.md) — Mustache template generator
35+
2. [scaffold-extensions.instructions.md](./scaffold-extensions.instructions.md) — Extending the scaffold
36+
37+
### For Coding Standards
38+
- All `wpcs-*.instructions.md` files — WordPress PHP, JavaScript, CSS, HTML, Accessibility, and Documentation standards
39+
40+
## 📂 File Categories
41+
42+
### WordPress Coding Standards (wpcs-*)
43+
7 protected files defining core WordPress standards:
44+
- `wpcs-php.instructions.md` — PHP standards
45+
- `wpcs-javascript.instructions.md` — JavaScript standards
46+
- `wpcs-css.instructions.md` — CSS/SCSS standards
47+
- `wpcs-html.instructions.md` — HTML standards
48+
- `wpcs-accessibility.instructions.md` — Accessibility (WCAG 2.2 AA)
49+
- `wpcs-php-docs.instructions.md` — PHP documentation (PHPDoc)
50+
- `wpcs-js-docs.instructions.md` — JavaScript documentation (JSDoc)
51+
52+
### Block Development
53+
4 files covering comprehensive block development:
54+
- `blocks-development.instructions.md` — **NEW** Main block development guide
55+
- `block-json.instructions.md` — Block metadata and configuration
56+
- `patterns-and-templates.instructions.md` — **NEW** Pattern and template development
57+
- `javascript-react-development.instructions.md` — **CONSOLIDATED** React/JS patterns
58+
59+
### Testing & Security
60+
- `testing-e2e.instructions.md` — **RENAMED** Playwright E2E testing
61+
- `security.instructions.md` — Security best practices
62+
63+
### Plugin Scaffolding
64+
- `generate-plugin.instructions.md` — Plugin generation with mustache templates
65+
- `scaffold-extensions.instructions.md` — **RENAMED** Scaffold extension patterns
66+
67+
### Project Organization
68+
- `folder-structure.instructions.md` — File organization standards
69+
- `schema-files.instructions.md` — Schema file structure
70+
- `temp-files.instructions.md` — Temporary file handling
71+
72+
### Special Topics
73+
- `a11y.instructions.md` — Accessibility for block plugins
74+
- `i18n.instructions.md` — Internationalization
75+
- `scf-fields.instructions.md` — Custom fields
76+
- `reporting.instructions.md` — Reporting standards
77+
78+
## 🔍 Finding Instructions
79+
80+
### By Task
81+
- **Creating a block?** → `blocks-development.instructions.md`
82+
- **Creating a pattern?** → `patterns-and-templates.instructions.md`
83+
- **Writing PHP?** → `wpcs-php.instructions.md`
84+
- **Writing JavaScript?** → `wpcs-javascript.instructions.md` + `javascript-react-development.instructions.md`
85+
- **Testing?** → `testing-e2e.instructions.md`
86+
- **Security?** → `security.instructions.md`
87+
- **Accessibility?** → `wpcs-accessibility.instructions.md` or `a11y.instructions.md`
88+
89+
### By File Type
90+
- `*.php` → `wpcs-php.instructions.md`, `wpcs-php-docs.instructions.md`
91+
- `*.js, *.jsx, *.ts, *.tsx` → `wpcs-javascript.instructions.md`, `javascript-react-development.instructions.md`, `wpcs-js-docs.instructions.md`
92+
- `*.css, *.scss` → `wpcs-css.instructions.md`
93+
- `*.html` → `wpcs-html.instructions.md`
94+
- `block.json` → `block-json.instructions.md`
95+
- `patterns/*.php` → `patterns-and-templates.instructions.md`
96+
97+
## 📈 Recent Changes (2025-12-10)
98+
99+
### Consolidation Complete ✅
100+
101+
**Files Consolidated (9 eliminated):**
102+
1. `block-plugin-development.instructions.md` → merged into `blocks-development.instructions.md`
103+
2. `blocks.instructions.md` → merged into `blocks-development.instructions.md`
104+
3. `patterns.instructions.md` → merged into `patterns-and-templates.instructions.md`
105+
4. `pattern-development.instructions.md` → merged into `patterns-and-templates.instructions.md`
106+
5. `javascript-react.instructions.md` → merged into `javascript-react-development.instructions.md`
107+
6. `js-react.instructions.md` → merged into `javascript-react-development.instructions.md`
108+
7. `playwright.instructions.md` → merged into `testing-e2e.instructions.md`
109+
8. `playwright-typescript.instructions.md` → renamed to `testing-e2e.instructions.md`
110+
9. `wp-security.instructions.md` → deleted (redundant)
111+
112+
**Files Renamed (1):**
113+
- `block-plugin.instructions.md` → `scaffold-extensions.instructions.md`
114+
115+
**New Files Created (4):**
116+
1. `blocks-development.instructions.md` — Comprehensive block development guide
117+
2. `patterns-and-templates.instructions.md` — Pattern and template guide
118+
3. `javascript-react-development.instructions.md` — Consolidated JS/React guide
119+
4. `_index.instructions.md` — Master index with navigation
120+
121+
### Impact
122+
- **32% file reduction** (28 → 19 content files)
123+
- **~14% size reduction** (~450KB → ~389KB)
124+
- **Zero duplicate content** (~80KB eliminated)
125+
- **Improved organization** with master index
126+
- **Clearer file purposes** with better naming
127+
128+
## 🎯 Purpose
129+
130+
These instructions help AI tools and developers understand:
131+
132+
- **WordPress block plugin development** — Modern patterns and best practices
133+
- **Block API standards** — Comprehensive block.json and component guidance
134+
- **WordPress Coding Standards** — PHP, JavaScript, CSS, HTML, and accessibility
135+
- **Plugin scaffolding** — Mustache templates and generator patterns
136+
- **Testing strategies** — E2E testing with Playwright
137+
- **Security practices** — Sanitization, escaping, nonces, and capability checks
138+
- **Documentation standards** — PHPDoc and JSDoc conventions
139+
- **Accessibility requirements** — WCAG 2.2 AA compliance
140+
141+
## 📖 Usage
142+
143+
### For AI Assistants
144+
Instructions are automatically loaded to provide context-aware assistance throughout the development process. The `applyTo` frontmatter field specifies which file patterns each instruction applies to.
145+
146+
### For Developers
147+
Reference these files when:
148+
- Starting new block development
149+
- Reviewing code for standards compliance
150+
- Implementing new features
151+
- Writing documentation
152+
- Setting up testing
153+
- Ensuring accessibility
154+
155+
## 🔗 Related Resources
156+
157+
### Internal
158+
- [.github/reports/instruction-consolidation-audit-2025-12-10.md](../reports/instruction-consolidation-audit-2025-12-10.md) — Consolidation audit report
159+
- [.github/projects/active/2025-12-10-instruction-consolidation.md](../projects/active/2025-12-10-instruction-consolidation.md) — Implementation tasks
160+
161+
### External
162+
- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
163+
- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
164+
- [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)
165+
166+
## ⚠️ Important Notes
167+
168+
- **Protected Files:** All `wpcs-*` files are protected and should not be deleted
169+
- **Flat Structure:** All files remain in one directory for easy discovery
170+
- **Version Control:** All changes are tracked in git history
171+
- **Cross-References:** Files reference each other — update links when renaming
172+
- **Scope:** Instructions are for WordPress block plugin repositories only
173+
174+
## 📝 Maintenance
175+
176+
### Adding New Instructions
177+
1. Check if topic fits in existing file
178+
2. Consider if new file is truly needed
179+
3. Update `_index.instructions.md` if creating new file
180+
4. Update this README
181+
182+
### Updating Instructions
183+
1. Make changes to instruction file(s)
184+
2. Update `last_updated` in frontmatter
185+
3. Update version number if significant changes
186+
4. Update cross-references if needed
187+
188+
### Reporting Issues
189+
- Create issue with file name and specific problem
190+
- Reference `_index.instructions.md` for context
191+
192+
---
193+
194+
**For complete navigation and detailed file descriptions, see [_index.instructions.md](./_index.instructions.md)**

0 commit comments

Comments
 (0)