[Docs] Add comprehensive coding standards and linting improvements #3

ashleyshaw · 2025-09-25T05:57:34Z

Pull Request: Add Copilot Docs and Instruction Files

Description

This pull request introduces new documentation and Copilot instruction files to the repository. It includes agent guides, markdown standards, accessibility, performance, and security best practices, aiming to improve onboarding, code quality, and contributor guidance.

Related Issue: Fixes #[issue-number] (replace with actual issue number)

Type of Change

📝 Documentation update (content changes, new guidance)
✨ New feature (new instruction sets, agent personas, substantial content)

Quality Gate Checklist

Testing Instructions

Run npm run build and verify no unexpected diffs.
Check that new links and cross-references resolve correctly.
Review documentation for accessibility, security, and performance compliance.

Screenshots (if applicable)

N/A

Changelog Entry

Category: Added

Entry: Added Copilot agent documentation, markdown standards, and best practice instruction files for accessibility, performance, and security.

Additional Context

This update is part of ongoing efforts to improve contributor experience and code quality. No breaking changes are introduced.

By submitting this pull request, I confirm that my contribution abides by the repository governance and will be licensed under the GPL-3.0-only licence.

- Introduced JSON schema for wp-env configuration files. - Established accessibility guidelines based on WCAG 2.2 AA. - Documented alignment decisions and matrix for coding practices. - Outlined standards for block development and inline documentation. - Created checklists for accessibility, performance, PRs, releases, and security. - Compiled common standards for PHP, JS, CSS, HTML, and documentation. - Defined CSS standards including BEM naming and fluid typography. - Added examples for blocks, CSS, HTML, JS, and PHP. - Specified theme.json guidelines for token definitions and formatting. - Implemented tooling documentation for CI, EditorConfig, ESLint, PHPCS, Stylelint, and WooCommerce guidelines.

- Implemented `lint-agents.js` to validate AGENTS.md and AGENT.md files structure. - Created `migrate-copilot-extensions.js` to rename legacy asset extensions to new plural forms, with deprecation stubs for legacy files. - Added a backup for the YAML parser in `yaml-parser-backup.js`. - Updated `.prettierignore` to exclude additional files and directories from formatting. - Introduced a new Stylelint configuration in `.stylelintrc copy.json` and linked it in `stylelint.config.js`. - Configured Webpack with multiple entry points for CSS and JS files, utilizing `RemoveEmptyScriptsPlugin` to clean up empty scripts.

… focus and improve maintainability

…unctionalities, including accessibility review, lint fixing, block generation, and BEM refactoring. Update workspace settings for improved development experience.

- Removed stylelint configuration and related linting scripts from package.json. - Deleted webpack.config.js as it is no longer needed. - Added a new WordPress documentation specialist agent for inline documentation. - Introduced an interactive chat mode for generating and reviewing WordPress documentation. - Created comprehensive instructions for WordPress inline documentation standards. - Added a prompt for generating WordPress-compliant inline documentation for PHP and JavaScript. - Updated package.json to remove stylelint dependencies and adjust linting scripts accordingly.

… clarity

coderabbitai · 2025-09-25T05:57:43Z

Important

Review skipped

More than 25% of the files skipped due to max files limit. The review is being skipped to prevent a low-quality review.

101 files out of 300 files are above the max files limit of 100. Please upgrade to Pro plan to get higher limits.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Warning

`.coderabbit.yml` has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Validation error: Invalid enum value. Expected 'chill' | 'assertive', received 'balanced' at "reviews.profile"

⚙️ Configuration instructions

Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch add-docs-copilot-files

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

ashleyshaw

Hi Lightspeed team,

Please review the newly added documentation and Copilot instruction files in this branch. These updates include agent guides, markdown standards, and best practices for accessibility, performance, and security.

Kindly check each file for accuracy, clarity, and compliance with our coding standards. Pay special attention to accessibility, security, and WordPress-specific guidance. Feedback and suggestions for improvement are welcome.

Thank you!
Ash

Copilot

Pull Request Overview

This pull request adds comprehensive coding standards and linting improvements for WordPress development, introducing new Copilot documentation assets and instruction files to improve onboarding, code quality, and contributor guidance. The changes focus on establishing consistent documentation standards, AI-assisted development workflows, and quality gates for WordPress block themes and plugins.

Key changes include:

Addition of WordPress inline documentation Copilot assets following official coding standards
Enhanced VS Code configuration with proper file associations for plural extensions
Repository cleanup removing unnecessary build tool configurations

Reviewed Changes

Copilot reviewed 206 out of 741 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`docs-unified/ai-copilot/prompts/*.md`	New WordPress-specific prompts for block patterns, Gutenberg blocks, theme.json configuration, and accessibility auditing
`.github/prompts/*.prompts.md`	WordPress inline documentation generator and various development prompts
`.vscode/settings.json`	Enhanced file associations for plural extensions and improved MCP server configuration
`.github/scripts/*.js`	Updated build scripts with support for new file extensions and improved collection validation
Configuration files	Cleanup of unnecessary build tools and enhanced linting configurations

Comments suppressed due to low confidence (1)

docs-unified/ai-copilot/prompts/accessibility-expert.chatmode.md:1

This concluding statement excellently demonstrates the people-first language and inclusive design principles outlined in the accessibility coding guidelines. This is a good example of how to frame accessibility work positively and comprehensively.

---

Copilot · 2025-09-25T11:36:57Z

docs-unified/ai-copilot/prompts/pr-description.md

+# Prompt — PR Description
+
+Template for strong PRs.


This file lacks frontmatter metadata required by the coding guidelines. According to CodingGuidelineID 1000000, prompt files should include markdown front matter with fields like mode, description, model, and tools. Add proper YAML frontmatter to make this file compliant with the established standards.

Copilot · 2025-09-25T11:36:57Z

docs-unified/ai-copilot/prompts/playwright-tests.md

+# Prompt: Playwright e2e scenarios
+
+Happy path + edge case; stable selectors; deterministic.


Missing required frontmatter metadata. According to the coding guidelines, prompt files should include YAML frontmatter with at least a description field and mode field specified as either 'agent' or 'ask'. Add proper frontmatter to comply with the prompt file guide standards.

Copilot · 2025-09-25T11:36:58Z

docs-unified/ai-copilot/prompts/performance-coach-agent.md

+# Agent — Performance Coach
+
+Checklist for Core Web Vitals.


This agent file lacks the required frontmatter structure. Per CodingGuidelineID 1000000, agent files should include markdown front matter with a description field that is not empty and wrapped in single quotes. The current content is too minimal for an agent specification.

Copilot · 2025-09-25T11:36:58Z

docs-unified/ai-copilot/prompts/plan.chatmode.md

@@ -0,0 +1,20 @@
+---
+mode: 'agent'
+name: 'Scrumban Project Planner'


The name field in the frontmatter is not part of the standard schema according to the coding guidelines. Chat mode files should focus on description, mode, model, and tools fields. Consider removing the name field or clarifying its purpose if it's intentionally extended beyond the standard.

Suggested change

name: 'Scrumban Project Planner'

Copilot · 2025-09-25T11:36:58Z

docs-unified/ai-copilot/prompts/javascript-react.instructions.md

+---
+applyTo: "**/*.{js,jsx,ts,tsx}"
+description: "JavaScript and React development standards for WordPress Gutenberg blocks and modern WordPress development"
+license: "GPL-3.0-or-later"


The instruction file includes a license field in the frontmatter, but according to CodingGuidelineID 1000000, instruction files should focus on applyTo and description fields. While the license information is valuable, consider whether it belongs in the coding guidelines or should be documented separately to maintain frontmatter consistency.

Suggested change

license: "GPL-3.0-or-later"

Copilot · 2025-09-25T11:36:59Z

.github/scripts/validate-collections.js

 		if(!item.path||typeof item.path!=="string") return `Item ${i+1} must have a path string`;
 		if(!item.kind||typeof item.kind!=="string") return `Item ${i+1} must have a kind string`;
-		if(!['prompt','instruction','chat-mode'].includes(item.kind)) return `Item ${i+1} kind must be one of: prompt, instruction, chat-mode`;
+		if(!['prompt','instruction','chat-mode','agent'].includes(item.kind)) return `Item ${i+1} kind must be one of: prompt, instruction, chat-mode, agent`;


The validation logic for file extensions is duplicated and complex. Consider extracting the extension validation logic into a separate function to improve maintainability and reduce code duplication across lines 50-53.

Copilot · 2025-09-25T11:36:59Z

.github/scripts/update-readme.js

 		}
 		inFM = false; fmDone = false;
-		if (/(\.prompt|\.chatmode|\.instructions)\.md$/.test(filePath)) {
+		if (CURRENT_EXT_PATTERN.test(filePath) || LEGACY_EXT_PATTERN.test(filePath) || AGENT_EXT_PATTERN.test(filePath)) {


The file extension pattern matching is becoming complex with multiple patterns. Consider consolidating these patterns into a single comprehensive regex or creating a helper function to determine if a file matches any of the supported extensions.

ashleyshaw added 7 commits September 25, 2025 00:38

Remove non-WordPress relevant files from the repository to streamline…

966555e

… focus and improve maintainability

Remove deprecated prompt files and add new prompt files for various f…

3f8ddec

…unctionalities, including accessibility review, lint fixing, block generation, and BEM refactoring. Update workspace settings for improved development experience.

Update configuration files for improved consistency and documentation…

091dcbe

… clarity

Add funding configuration for GitHub Sponsors

1e49d35

ashleyshaw added [Priority] Important [Status] Ready labels Sep 25, 2025

ashleyshaw self-assigned this Sep 25, 2025

ashleyshaw added the [Type] Documentation Improvements or additions to documentation label Sep 25, 2025

ashleyshaw assigned Copilot Sep 25, 2025

ashleyshaw requested review from brandonmarshal, josearmandoabreu, Justinabes007, krugazul, serenvdmerwe, tibiii and ZaredRogers September 25, 2025 05:57

ashleyshaw commented Sep 25, 2025

View reviewed changes

serenvdmerwe requested a review from Copilot September 25, 2025 11:34

Copilot AI reviewed Sep 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Docs] Add comprehensive coding standards and linting improvements #3

[Docs] Add comprehensive coding standards and linting improvements #3

ashleyshaw commented Sep 25, 2025

Uh oh!

coderabbitai bot commented Sep 25, 2025

Review skipped

`.coderabbit.yml` has a parsing error

Uh oh!

ashleyshaw left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Copilot AI Sep 25, 2025

Uh oh!

Uh oh!

		# Prompt: Playwright e2e scenarios

		Happy path + edge case; stable selectors; deterministic.

[Docs] Add comprehensive coding standards and linting improvements #3

Are you sure you want to change the base?

[Docs] Add comprehensive coding standards and linting improvements #3

Conversation

ashleyshaw commented Sep 25, 2025

Pull Request: Add Copilot Docs and Instruction Files

Description

Type of Change

Quality Gate Checklist

Testing Instructions

Screenshots (if applicable)

Changelog Entry

Additional Context

Uh oh!

coderabbitai bot commented Sep 25, 2025

Review skipped

.coderabbit.yml has a parsing error

Uh oh!

ashleyshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

`.coderabbit.yml` has a parsing error