PR: Release 1.0.0 #4
Conversation
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
Note
|
| Cohort / File(s) | Summary |
|---|---|
Agent Specifications ,.github/agents/a11y.agent.md, .github/agents/agent.md, .github/agents/generate-plugin.agent.md, .github/agents/release-scaffold.agent.md, .github/agents/release.agent.md, .github/agents/reporting.agent.md, .github/agents/task-planner.agent.md, .github/agents/task-researcher.agent.md |
Rewrote and expanded agent specs with detailed role/scope sections, input/output specifications, safety guardrails, and structured formatting. Added new agent entries (WP Block Build, Development Assistant) to central index. Updated implementation references and metadata fields. |
Instruction Documentation Standardization .github/instructions/... (26 files) |
Standardized frontmatter across all instruction files: converted version/last_updated to numeric format with camelCase lastUpdated, reorganized References sections to end of files as Markdown links, added new External resources sections, updated relative paths and scopes. |
Central Documentation & Indexing .github/custom-instructions.md, .github/instructions/_index.instructions.md |
Added unified "Instruction File Index" with categorized file listing. Updated file count from 19 to 22 and reorganized References sections with repository-relative links. |
Plugin Configuration Schema .github/schemas/plugin-config.schema.json |
Added 13 new top-level schema properties: short_description, contributors, docs/support/github/donate URLs, update_uri, copyright fields, block_category, block_supports, release_date, upgrade_notice. |
Variable Registry & Scanning scripts/mustache-variables-registry.json, scripts/scan-mustache-variables.js |
Reorganized variable registry with expanded metrics (549→701 files, 142→100 unique variables). Introduced new categories (core_identity, custom_post_type, taxonomy, blocks). Updated scan script to validate against plugin-config.json, adjusted directory scans and categorization logic. |
Agent Prompts & Utilities .github/prompts/agent-spec-auditor.prompt.md, .github/prompts/generate-plugin.prompt.md |
Added new agent auditor prompt with audit workflow and checklist. Expanded generate-plugin prompt with Step 1/2 repository context and config file detection, wizard selection, and updated output directory references. |
Main Documentation docs/AGENTS-OVERVIEW.md, docs/AGENT_CREATION.md, docs/GENERATE-PLUGIN.md, AGENTS.md |
Removed AGENTS-OVERVIEW.md. Added comprehensive AGENT_CREATION.md with governance, workflows, and diagrams. Expanded GENERATE-PLUGIN.md with quick-start guide, component details, operational modes, post-generation workflows. Added Agent Index entry to AGENTS.md. |
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~25 minutes
- High file count (~40+ files modified) with broad scope across agents, instructions, schemas, and scripts
- Repetitive patterns in instruction file standardization reduce per-file review complexity
- Schema additions are straightforward property declarations without breaking changes
- Variable registry reorganization requires careful validation that all references remain consistent across configuration, schema, and scanning logic
- Key areas requiring attention:
- Verify all variable registry keys are correctly mapped in scan script categorization logic
- Confirm References links in instruction files resolve correctly with new relative paths
- Validate agent spec metadata (version, tools, references) follows new template consistently
- Check that plugin-config schema changes align with generate-plugin prompt and variable registry updates
Pre-merge checks and finishing touches
❌ Failed checks (1 inconclusive)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Title check | ❓ Inconclusive | The PR title 'PR: Release 1.0.0' is too vague and generic. While it mentions a version number, it does not clearly describe the substantive changes in this large changeset affecting agent specs, instructions, schemas, and documentation. | Use a more descriptive title that summarizes the primary focus of changes, such as 'Establish agent specification framework and standardize documentation metadata' or 'Standardize agent specs, instruction metadata, and add new agent/schema definitions'. |
✅ Passed checks (2 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Docstring Coverage | ✅ Passed | Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. |
✨ Finishing touches
- 📝 Generate docstrings
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Post copyable unit tests in a comment
- Commit unit tests in branch
main
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.
Comment @coderabbitai help to get the list of available commands and usage tips.
Summary of ChangesHello @ashleyshaw, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces significant enhancements to the repository's internal tooling and documentation. It establishes a standardized framework for AI agent specifications, streamlines the plugin generation process with clearer modes and expanded configuration options, and refines the organization and referencing of instruction files. The addition of a new governance document for agent creation aims to ensure consistency, safety, and maintainability in future development, ultimately improving overall workflow efficiency and clarity for contributors. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant and well-executed refactoring, standardizing agent specifications, instruction documents, and prompts. It also pivots the project from a theme scaffold to a more complex multi-block plugin scaffold. The changes are comprehensive and greatly improve clarity, consistency, and functionality across the repository's automation and documentation. I've found one critical issue with a generated JSON file that needs to be addressed.
| @@ -1,1885 +1,1438 @@ | |||
| 🔍 Scanning repository for mustache variables... | |||
There was a problem hiding this comment.
This line makes the file invalid JSON, which will cause parsing errors for any tool that consumes this file. Please ensure that only valid JSON content is present in this file.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (13)
.github/instructions/wpcs-css.instructions.md (1)
123-183: Fix broken CSS comment examples (/&042; ... &042;/). Those sequences won’t paste as valid CSS; replace with real/* ... */comments in the examples so the guidance is copy/paste correct..github/instructions/wpcs-php.instructions.md (1)
18-24: Resolve indentation contradictions (tabs vs 4 spaces). This file currently instructs both “tabs” and “4 spaces, no tabs”. Pick one canonical rule (and align examples) to avoid devs fighting PHPCS/formatter defaults.Also applies to: 66-74, 372-376
.github/instructions/wpcs-html.instructions.md (1)
77-83: Fix malformed/incorrect doc content (related_links blob, self-closing example, stray “.n”).
- Convert Line 79 into a proper Markdown list under a heading (or move it into “External resources”).
- The “compact but incorrect” self-closing example currently matches the “correct” one—update the incorrect sample.
- Remove the trailing “.n” in Credits.
Also applies to: 164-177, 261-264
.github/agents/reporting.agent.md (2)
1-15:last_updatedis in the future; fix for traceability.This file says
last_updated: 2025-12-15, but today is 2025-12-12. Use an actual update date (or omit until updated).
19-43: Add explicit safety guardrails/confirmation rules given destructive tools.The spec allows
delete_file,write_file, andrun_in_terminal, but doesn’t state constraints like:
- require explicit user confirmation before deletion/moves/overwrites
- default to dry-run / proposal output
- rollback strategy (backup/restore) for
.github/reports/At minimum, add a “Safety Guardrails” section or embed rules in “Core Responsibilities”.
.github/instructions/wpcs-javascript.instructions.md (1)
88-93: Use consistent heading levels (avoid a second H1).
# Performance & Security(Line 88) should likely be## Performance & Securityto keep a single H1 per document..github/instructions/patterns-and-templates.instructions.md (2)
540-560: Add a language to the file-tree code fence.Use
textfor thepatterns/tree block:-``` +```text patterns/ ...--- `691-695`: **Normalize horizontal rule style.** Line 693 uses `----`; suggest `---` for consistency. </blockquote></details> <details> <summary>docs/GENERATE-PLUGIN.md (5)</summary><blockquote> `684-711`: **Post-generation section still references `output-plugin/` (conflicts with `generated-plugins/<slug>/`).** Earlier sections standardize on `generated-plugins/<slug>/`, but here it instructs `cd output-plugin/` and shows an expected structure rooted at `tour-operator/` without stating where it lives. Suggested update: ```diff -```bash -cd output-plugin/ -tree -L 2 -``` +```bash +cd generated-plugins/tour-operator/ +tree -L 2 +```
480-683: Fix duplicated/incorrect “Generation Methods” ordering and mixed CLI/agent text.The section repeats “Method 3/4” and mixes agent examples inside a bash fence (Line 653+). Recommend restructuring to a single list:
- Method 1: Template Mode (
--in-place)- Method 2: Generator Mode (default)
- Method 3: AI-Assisted (prompt)
- Method 4: Agent-based
- Method 5: CLI (direct args)
Also fix the invalid fence:
-```bashbash +```bash
292-293: Fix broken relative link fromdocs/to.github/paths.This link is missing a
../prefix for a docs file:
See [Generator Instructions](.github/instructions/generate-plugin.instructions.md)Suggested:
-See [Generator Instructions](.github/instructions/generate-plugin.instructions.md) +See [Generator Instructions](../.github/instructions/generate-plugin.instructions.md)
369-401: Add language to the “Output Location” fence (MD040) and keep fences consistent.-``` +```text multi-block-plugin-scaffold/ ...--- `684-692`: **Replace `output-plugin/` with `generated-plugins/` in documentation examples and commands.** The codebase uses `generated-plugins/` as the primary output directory (defined in `scripts/generate-plugin.js` and documented throughout), but docs/GENERATE-PLUGIN.md inconsistently references the legacy `output-plugin/` directory at lines 689 and 1089. Update both occurrences to use `generated-plugins/` to align with the actual implementation and primary documentation references elsewhere. Line 871 (error message context) may also need review to ensure consistency. </blockquote></details> </blockquote></details>🧹 Nitpick comments (4)
.github/instructions/blocks-development.instructions.md (1)
1-25: Consolidate references into the end “## References” section (avoid drift). Right now this file has both frontmatterreferences:and an end-of-doc## References. Unless something explicitly consumes the YAMLreferences:field, consider removing it and relying on the end section to align with the repo-wide “References at end as Markdown links” pattern.Also applies to: 810-826
.github/agents/task-researcher.agent.md (1)
36-41: Consider reducing “You do not…” repetition for readability.Three consecutive sentences start with “You do…”, which reads a bit mechanical. (LanguageTool note on Line 38–40.) A single bullet list would scan better.
.github/agents/reporting.agent.md (1)
354-356: Keep agent spec tone professional (avoid emoji in canonical docs).Line 356 ends with “📊”. Consider dropping it for consistency with other governance/spec docs.
.github/agents/task-planner.agent.md (1)
71-76: Add language identifiers to fenced code blocks.Multiple fenced code blocks throughout this file are missing language identifiers. Per markdown best practices and the markdownlint warnings, these should include a language specifier.
For file path examples, use:
```text .github/projects/active/YYYYMMDD-task-description-plan.md ```For code blocks showing directory structure or paths, consider using
text,plaintext, orbashas appropriate.Apply this pattern to all fenced code blocks at lines: 71, 85, 137, 159, 180, 244, and 255.
Also applies to: 85-89, 137-142, 159-163, 180-184, 244-248, 255-262
📜 Review details
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (49)
.github/agents/a11y.agent.md(1 hunks).github/agents/agent.md(1 hunks).github/agents/generate-plugin.agent.md(1 hunks).github/agents/release-scaffold.agent.md(1 hunks).github/agents/release.agent.md(1 hunks).github/agents/reporting.agent.md(2 hunks).github/agents/task-planner.agent.md(1 hunks).github/agents/task-researcher.agent.md(1 hunks).github/custom-instructions.md(1 hunks).github/instructions/_index.instructions.md(4 hunks).github/instructions/a11y.instructions.md(2 hunks).github/instructions/agent-spec.instructions.md(4 hunks).github/instructions/block-json.instructions.md(2 hunks).github/instructions/blocks-development.instructions.md(3 hunks).github/instructions/folder-structure.instructions.md(2 hunks).github/instructions/generate-plugin.instructions.md(2 hunks).github/instructions/i18n.instructions.md(2 hunks).github/instructions/instructions.instructions.md(2 hunks).github/instructions/javascript-react-development.instructions.md(2 hunks).github/instructions/markdown.instructions.md(2 hunks).github/instructions/patterns-and-templates.instructions.md(3 hunks).github/instructions/readme.instructions.md(2 hunks).github/instructions/release-scaffold.instructions.md(2 hunks).github/instructions/release.instructions.md(2 hunks).github/instructions/reporting.instructions.md(2 hunks).github/instructions/scaffold-extensions.instructions.md(2 hunks).github/instructions/scf-fields.instructions.md(2 hunks).github/instructions/schema-files.instructions.md(2 hunks).github/instructions/security.instructions.md(2 hunks).github/instructions/task-planner.instructions.md(2 hunks).github/instructions/task-researcher.instructions.md(2 hunks).github/instructions/temp-files.instructions.md(2 hunks).github/instructions/testing-e2e.instructions.md(2 hunks).github/instructions/wpcs-accessibility.instructions.md(2 hunks).github/instructions/wpcs-css.instructions.md(2 hunks).github/instructions/wpcs-html.instructions.md(3 hunks).github/instructions/wpcs-javascript.instructions.md(2 hunks).github/instructions/wpcs-js-docs.instructions.md(2 hunks).github/instructions/wpcs-php-docs.instructions.md(3 hunks).github/instructions/wpcs-php.instructions.md(2 hunks).github/prompts/agent-spec-auditor.prompt.md(1 hunks).github/prompts/generate-plugin.prompt.md(5 hunks).github/schemas/plugin-config.schema.json(1 hunks)AGENTS.md(1 hunks)docs/AGENTS-OVERVIEW.md(0 hunks)docs/AGENT_CREATION.md(1 hunks)docs/GENERATE-PLUGIN.md(3 hunks)scripts/mustache-variables-registry.json(1 hunks)scripts/scan-mustache-variables.js(7 hunks)💤 Files with no reviewable changes (1)
- docs/AGENTS-OVERVIEW.md
🧰 Additional context used
📓 Path-based instructions (24)
.github/instructions/**
📄 CodeRabbit inference engine (.github/instructions/folder-structure.instructions.md)
Place AI/Copilot instruction files in the
.github/instructions/directoryFiles:
.github/instructions/markdown.instructions.md.github/instructions/wpcs-html.instructions.md.github/instructions/task-planner.instructions.md.github/instructions/temp-files.instructions.md.github/instructions/reporting.instructions.md.github/instructions/schema-files.instructions.md.github/instructions/a11y.instructions.md.github/instructions/testing-e2e.instructions.md.github/instructions/i18n.instructions.md.github/instructions/wpcs-javascript.instructions.md.github/instructions/generate-plugin.instructions.md.github/instructions/instructions.instructions.md.github/instructions/release-scaffold.instructions.md.github/instructions/patterns-and-templates.instructions.md.github/instructions/wpcs-php.instructions.md.github/instructions/task-researcher.instructions.md.github/instructions/wpcs-js-docs.instructions.md.github/instructions/folder-structure.instructions.md.github/instructions/wpcs-css.instructions.md.github/instructions/wpcs-accessibility.instructions.md.github/instructions/wpcs-php-docs.instructions.md.github/instructions/_index.instructions.md.github/instructions/javascript-react-development.instructions.md.github/instructions/release.instructions.md.github/instructions/blocks-development.instructions.md.github/instructions/scf-fields.instructions.md.github/instructions/scaffold-extensions.instructions.md.github/instructions/block-json.instructions.md.github/instructions/readme.instructions.md.github/instructions/security.instructions.md.github/instructions/agent-spec.instructions.md**/*.{js,jsx,ts,tsx,md}
📄 CodeRabbit inference engine (.github/instructions/a11y.instructions.md)
When suggesting accessibility implementations, include reasoning or references to standards (WCAG, platform guidelines); state uncertainty clearly if it exists
Files:
AGENTS.mdscripts/scan-mustache-variables.jsdocs/AGENT_CREATION.mddocs/GENERATE-PLUGIN.md**/*.{php,md}
📄 CodeRabbit inference engine (.github/instructions/block-plugin.instructions.md)
Document all classes with docblocks explaining their purpose and keep everything clearly marked as example/placeholder/scaffold in comments and README files to avoid production assumptions
Files:
AGENTS.mddocs/AGENT_CREATION.mddocs/GENERATE-PLUGIN.md.github/agents/**/*.{md,js}
📄 CodeRabbit inference engine (.github/instructions/folder-structure.instructions.md)
Place AI agent specs and implementations in the
.github/agents/directory with naming convention{agent-name}.agent.md(spec) and{agent-name}.agent.js(implementation)Files:
.github/agents/release-scaffold.agent.md.github/agents/a11y.agent.md.github/agents/agent.md.github/agents/task-researcher.agent.md.github/agents/release.agent.md.github/agents/task-planner.agent.md.github/agents/reporting.agent.md.github/agents/generate-plugin.agent.md.github/agents/**/*.{js,py,ts,tsx,jsx,php,md}
📄 CodeRabbit inference engine (AGENTS.md)
All agent implementations and specs must be located in
.github/agents/directory with both a code file (.js,.py, etc.) and a spec (.md) following the templateFiles:
.github/agents/release-scaffold.agent.md.github/agents/a11y.agent.md.github/agents/agent.md.github/agents/task-researcher.agent.md.github/agents/release.agent.md.github/agents/task-planner.agent.md.github/agents/reporting.agent.md.github/agents/generate-plugin.agent.md.github/prompts/**
📄 CodeRabbit inference engine (.github/instructions/folder-structure.instructions.md)
Place AI prompt templates in the
.github/prompts/directoryFiles:
.github/prompts/agent-spec-auditor.prompt.md.github/prompts/generate-plugin.prompt.md**/*.{php,js,jsx,json,html,scss,css}
📄 CodeRabbit inference engine (.github/instructions/generate-plugin.instructions.md)
Always use
{{variable}}format with double curly braces for mustache template placeholders; never use${variable},%variable%,CONSTANT_NAME, or other alternative formatsFiles:
scripts/scan-mustache-variables.jsscripts/mustache-variables-registry.json**/*.{php,js,jsx,scss,css}
📄 CodeRabbit inference engine (.github/instructions/generate-plugin.instructions.md)
All classes, functions, constants, and CSS selectors must use namespace prefixes derived from the plugin namespace variable
Files:
scripts/scan-mustache-variables.js**/*.{js,jsx}
📄 CodeRabbit inference engine (.github/instructions/generate-plugin.instructions.md)
**/*.{js,jsx}: JavaScript block registration must use the namespace variable in block name format (e.g.,registerBlockType( '{{namespace}}/block-name' ))
JavaScript components must use namespace-prefixed CSS class names (e.g.,className="{{namespace}}-block-name")
JavaScript i18n function calls must include the textdomain variable (e.g.,__( 'Translatable string', '{{textdomain}}' ))Files:
scripts/scan-mustache-variables.js**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.github/instructions/a11y.instructions.md)
**/*.{js,jsx,ts,tsx}: Use semantic HTML elements (headings, lists, landmarks) instead of excessive<div>usage in block output and editor components
Ensure keyboard support with proper Tab/Shift+Tab order, visible focus indicators, and Escape key for closing dialogs in block controls and output
Use ARIA attributes only when necessary and do not override native HTML semantics in block components
Provide meaningfulalttext for images through block controls and support captions/transcripts for media blocks
Associate form labels with inputs properly, include required field indicators witharia-required=true, and provide error messages witharia-liveand programmatic focus management
Provide meaningful block titles, descriptions, andblock.jsonkeywords for editor accessibility
Test RTL (right-to-left) layout support and never concatenate translatable strings; use proper i18n function calls
Provide clear labels for all block controls, use appropriate control types (TextControl, SelectControl, etc.), and include help text for complex controls
Use IconButton components with aria-labels, group related controls logically, and provide tooltips for icon-only buttons in block toolbar
Organize inspector controls within PanelBody with clear section headings, help text, and ensure all controls are keyboard accessible
Manage focus on dynamic content changes, provide loading states with ARIA live regions, and ensure error messages are announced to assistive technologies
Use button element for buttons with visible focus indicators, ensure keyboard accessibility with clear hover/focus states, and test with keyboard-only navigation
Use fieldset and legend for form control groups, provide required field indicators, and ensure inline validation feedback is announced witharia-invalid=true
Provide alt text input controls for image blocks, include guidance for writing effective alt text, and support decorative image option withalt=""
Support captions and transcripts for v...Files:
scripts/scan-mustache-variables.js**/*.{js,jsx,ts,tsx,scss,sass,css}
📄 CodeRabbit inference engine (.github/instructions/block-plugin-development.instructions.md)
Use
@wordpress/scripts, Vite, or Webpack for JS/JSX (React) transpilation and bundling, SCSS/SASS to CSS compilation, and asset optimisationFiles:
scripts/scan-mustache-variables.js**/*.{js,jsx,ts,tsx,php}
📄 CodeRabbit inference engine (.github/instructions/block-plugin-development.instructions.md)
Ensure keyboard navigation and screen reader support in block controls and output
Files:
scripts/scan-mustache-variables.js**/*.{js,jsx,ts,tsx,css,scss,sass}
📄 CodeRabbit inference engine (.github/instructions/block-plugin-development.instructions.md)
Minimise JS/CSS bundle size and avoid unnecessary dependencies
Files:
scripts/scan-mustache-variables.jsscripts/**/*.js
📄 CodeRabbit inference engine (.github/instructions/folder-structure.instructions.md)
Place Node.js build and utility scripts in the
scripts/directory, not inbin/Files:
scripts/scan-mustache-variables.js**/*.{php,js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.github/instructions/i18n.instructions.md)
**/*.{php,js,jsx,ts,tsx}: Wrap all user-facing strings with translation functions in WordPress development
Provide translator comments for ambiguous strings in WordPress translations
Avoid concatenation in translatable strings; use placeholders insteadFiles:
scripts/scan-mustache-variables.js**/*.{js,ts,sh}
📄 CodeRabbit inference engine (.github/instructions/reporting.instructions.md)
When generating reports via scripts or automation, log execution to
logs/{source}-{type}-{timestamp}.logwith log levels: ERROR for critical findings, WARN for issues requiring attention, INFO for general progress, DEBUG for detailed analysis dataFiles:
scripts/scan-mustache-variables.js**/*.{js,ts}
📄 CodeRabbit inference engine (.github/instructions/reporting.instructions.md)
Temporary artifacts generated during report analysis MUST be stored in
tmp/reports/{report-type}/{report-date}/and cleaned up after report finalization by removing the directory withfs.rmSync(tmpDir, { recursive: true, force: true })or equivalentFiles:
scripts/scan-mustache-variables.js**/*.{js,jsx,ts,tsx,mjs,cjs}
📄 CodeRabbit inference engine (.github/instructions/wpcs-javascript.instructions.md)
**/*.{js,jsx,ts,tsx,mjs,cjs}: Use 2-space indentation (not tabs) for JavaScript files in block plugins and WordPress development
Use single quotation marks for string declarations in JavaScript
Use semicolons at the end of all statements; do not rely on Automatic Semicolon Insertion (ASI)
Preferconstandletovervarand always use strict equality (===/!==)
UselowerCamelCasefor variable and function names; useUpperCamelCasefor class and component names
UseUPPER_SNAKE_CASEfor constant values that are never intended to be reassigned or mutated
Document exported functions, classes, and modules using JSDoc with@paramand@returnstags; include@sincefor new APIs and@deprecatedwhere applicable
Use ESLint with the WordPress ruleset or LightSpeed's custom config and fix all lint errors before committing
Format code with Prettier following ESLint rules
Escape user-generated content when injecting into the DOM using functions likeescapeHtml()andsanitizeUrl()
Internationalize user-facing strings using WordPress i18n APIs (e.g.,wp.i18n.__,_n,sprintf)
Avoid polluting the global scope; wrap scripts in modules or IIFEs
Avoid complex nested callbacks; favor promises or async/await for asynchronous code
If/else/for/while/try blocks should always use braces and always go on multiple lines
Lines should usually be no longer than 80 characters, and should not exceed 100 characters (counting tabs as 4 spaces). Long lines generally indicate unreadable or disorganized code
Use spaces liberally throughout code; unary operators (++,--) must not have space next to operand; commas and semicolons must not have preceding space; colons after property names must not have preceding space
The?and:in a ternary conditional must have space on both sides
Negation operator!should have a following space
No filler spaces in empty constructs (e.g.,{},[],fn())
No whitespace at the end of line or on blank lines
There should be a n...Files:
scripts/scan-mustache-variables.js**/*.{js,mjs,cjs}
📄 CodeRabbit inference engine (.github/instructions/wpcs-javascript.instructions.md)
Name files using
lowercase-hyphenated.jsfor modules andUpperCamelCase.jsxfor React componentsFiles:
scripts/scan-mustache-variables.js**/*.{js,jsx,mjs,cjs}
📄 CodeRabbit inference engine (.github/instructions/wpcs-js-docs.instructions.md)
**/*.{js,jsx,mjs,cjs}: Begin each JSDoc block with a summary describing the purpose of the function or class, using third-person singular verbs.
Use@paramtags for each argument with its type and description. Describe optional parameters and default values using JSDoc@paramsyntax (e.g.,[var],[var=default]).
Use@returnsto describe the return type and meaning. For async functions, specify the resolved value.
Include@exampleblocks to demonstrate typical usage when helpful for functions and classes.
Document events, filters and deprecations using@fires,@deprecatedand related JSDoc tags.
Use@since x.x.x(3-digit version format, e.g.,@since 3.6.0) to document when a function, class, or member was added or significantly changed.
Use@deprecated x.x.x(3-digit format) to mark deprecated functions and classes, providing the version deprecated and the function/class to use instead.
Use@access(private, protected, public) to document access levels. Private members are intended for internal use only and will not appear in the code reference.
For class constructors, use@classand@augmentsto document parent classes, and@mixesto list mixins.
Use@memberofto specify the namespace that contains a function if JSDoc cannot resolve it automatically.
Use@staticto mark static methods on class constructors.
Use@seeto reference functions or classes that the documented item relies on, and@linkto provide URLs for more information.
Use@firesto document events fired by functions or constructors. For class-specific events, include the class name (e.g.,@fires className#eventName).
Use@listensto document events a function listens for, with event namespace prefix and class name where applicable (e.g.,@listens event:eventName,@listens className~event:eventName).
Use@yieldwith description to document values expected to be yielded from generator functions.
For Backbone classes, use@lendsbefore the Object conta...Files:
scripts/scan-mustache-variables.jsdocs/**/*.md
📄 CodeRabbit inference engine (.github/instructions/folder-structure.instructions.md)
docs/**/*.md: Place documentation files in thedocs/directory with naming conventionUPPERCASE.mdorlowercase.mdand required frontmatter
All markdown documentation files must include frontmatter with: title, description, category, type, audience, and date (YYYY-MM-DD format)Files:
docs/AGENT_CREATION.mddocs/GENERATE-PLUGIN.md**/*.json
📄 CodeRabbit inference engine (.github/instructions/generate-plugin.instructions.md)
ACF/SCF JSON field group files must use namespace-prefixed keys and names (e.g.,
key: "group_{{namespace}}_details",name: "{{namespace}}_subtitle")Include accessible block metadata in
block.jsonwith clear titles, descriptions, and keywords for editor discoverabilityFiles:
scripts/mustache-variables-registry.json**/*.{php,json}
📄 CodeRabbit inference engine (.github/instructions/scf-fields.instructions.md)
Always prefix field keys with your plugin/theme slug to ensure uniqueness
Files:
scripts/mustache-variables-registry.json**/*.{php,html,json}
📄 CodeRabbit inference engine (.github/instructions/block-plugin.instructions.md)
Ensure all plugin class files use mustache-style placeholders like
{{namespace}},{{slug}},{{textdomain}},{{name}}and do not hard-code values to keep the scaffold reusableFiles:
scripts/mustache-variables-registry.json🪛 Biome (2.1.2)
scripts/mustache-variables-registry.json
[error] 1-1: unexpected character
🔍(parse)
[error] 1-1: String values must be double quoted.
(parse)
[error] 1-1: String values must be double quoted.
(parse)
[error] 1-1: String values must be double quoted.
(parse)
[error] 1-1: String values must be double quoted.
(parse)
[error] 1-1: String values must be double quoted.
(parse)
[error] 1-1: unexpected character
.(parse)
[error] 1-1: unexpected character
.(parse)
[error] 1-2: unexpected character
.(parse)
🪛 LanguageTool
AGENTS.md
[uncategorized] ~72-~72: The official name of this software platform is spelled with a capital “H”.
Context: ...andards | | Agent Index | [.github/agents/agent.md](.github/agents/agent.m...(GITHUB)
[uncategorized] ~72-~72: The official name of this software platform is spelled with a capital “H”.
Context: ...dex** | .github/agents/agent.md | Main index of all av...(GITHUB)
.github/agents/release-scaffold.agent.md
[uncategorized] ~91-~91: The official name of this software platform is spelled with a capital “H”.
Context: ... capture and store readiness reports in.github/reports/validation/. ```markdown ## R...(GITHUB)
[style] ~328-~328: Consider using a different verb for a more formal wording.
Context: ...io 3: Post-Fix Validation User: "I fixed the issues. Check again." Agent: ...(FIX_RESOLVE)
.github/agents/task-researcher.agent.md
[style] ~39-~39: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... plan tasks. You do not write code. You only produce *evidence-based research...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~258-~258: The official name of this content management system is spelled with a capital “P”.
Context: ...find blocks, metadata, registration * wordpress_docs → fetch authoritative references...(WORDPRESS)
.github/instructions/i18n.instructions.md
[uncategorized] ~59-~59: Do not mix variants of the same word (‘internationalization’ and ‘internationalisation’) within a single text.
Context: ...adding strings. ## References - docs/INTERNATIONALIZATION.md...(EN_WORD_COHERENCY)
.github/instructions/release-scaffold.instructions.md
[uncategorized] ~60-~60: The official name of this software platform is spelled with a capital “H”.
Context: ...re production tags. ## References - .github/workflows - [docs/RELEA...(GITHUB)
.github/agents/task-planner.agent.md
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...Validation Before planning: 1. Search.github/projects/research/for: ``` YYYYMMDD...(GITHUB)
[uncategorized] ~109-~109: The official name of this content management system is spelled with a capital “P”.
Context: ...ndards - Gutenberg handbook - developer.wordpress.org block API - block bindings specific...(WORDPRESS)
[style] ~250-~250: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... MUST NOT reveal file contents in chat. You MUST provide short status-only summarie...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
.github/instructions/patterns-and-templates.instructions.md
[uncategorized] ~30-~30: The official name of this software platform is spelled with a capital “H”.
Context: .... They should not be applied to thelightspeedwp/.githubcommunity health repository, as that r...(GITHUB)
.github/prompts/agent-spec-auditor.prompt.md
[uncategorized] ~3-~3: The official name of this software platform is spelled with a capital “H”.
Context: ...rove** existing agent specifications in.github/agents/so they align with LightSpeed’...(GITHUB)
[uncategorized] ~19-~19: The official name of this software platform is spelled with a capital “H”.
Context: ...it and improve: * All files matching.github/agents/*.agent.mdin this repo. Treat...(GITHUB)
[style] ~54-~54: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...- ## 2. Non-destructive editing rules (very important) When editing any existing.agent.md...(EN_WEAK_ADJECTIVE)
[uncategorized] ~129-~129: The official name of this software platform is spelled with a capital “H”.
Context: ...he instructions & template** * Skim `.github/instructions/agent-spec.instructions.md...(GITHUB)
[uncategorized] ~130-~130: The official name of this software platform is spelled with a capital “H”.
Context: .../agent-spec.instructions.md. * Skim.github/agents/template.agent.md`. * Do this...(GITHUB)
[style] ~254-~254: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...versioning/release branches, etc.). * Add escalation rules, for example: * “...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/AGENT_CREATION.md
[uncategorized] ~282-~282: The official name of this software platform is spelled with a capital “H”.
Context: ...ifying multi-repo workflows (belongs in.github) - CI/CD orchestration changes (organi...(GITHUB)
docs/GENERATE-PLUGIN.md
[uncategorized] ~98-~98: The official name of this software platform is spelled with a capital “H”.
Context: ... "type": "number" } ] } ``` See `.github/schemas/examples/plugin-config.example....(GITHUB)
.github/prompts/generate-plugin.prompt.md
[uncategorized] ~40-~40: The official name of this software platform is spelled with a capital “H”.
Context: ... will validate it** against the schema (.github/schemas/plugin-config.schema.json) 3. ...(GITHUB)
[style] ~46-~46: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...** - If YES → I'll ask which values you want to change - If NO → I'll generate using yo...(REP_WANT_TO_VB)
.github/instructions/blocks-development.instructions.md
[uncategorized] ~31-~31: The official name of this software platform is spelled with a capital “H”.
Context: .... They should not be applied to thelightspeedwp/.githubcommunity health repository, as that r...(GITHUB)
.github/instructions/block-json.instructions.md
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: .... They should not be applied to thelightspeedwp/.githubcommunity health repository, as that r...(GITHUB)
.github/instructions/security.instructions.md
[uncategorized] ~387-~387: Do not mix variants of the same word (‘sanitization’ and ‘sanitisation’) within a single text.
Context: ...gins/security/data-validation/) - [Data Sanitization](https://developer.wordpress.org/plugin...(EN_WORD_COHERENCY)
.github/instructions/agent-spec.instructions.md
[uncategorized] ~18-~18: The official name of this software platform is spelled with a capital “H”.
Context: ...nglish. ## General Rules - Start from.github/agents/template.agent.md; replace all ...(GITHUB)
[uncategorized] ~74-~74: The official name of this software platform is spelled with a capital “H”.
Context: ...ces - AGENTS.md - [.github/agents/template.agent.md](../agents/tem...(GITHUB)
🪛 markdownlint-cli2 (0.18.1)
.github/agents/release-scaffold.agent.md
64-64: Link fragments should be valid
(MD051, link-fragments)
72-72: Link fragments should be valid
(MD051, link-fragments)
189-189: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
203-203: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
213-213: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
.github/agents/task-researcher.agent.md
235-235: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
245-245: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
.github/agents/task-planner.agent.md
71-71: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
85-85: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
137-137: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
159-159: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
180-180: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
244-244: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
255-255: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/AGENT_CREATION.md
19-19: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
171-171: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3(MD001, heading-increment)
docs/GENERATE-PLUGIN.md
393-393: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
.github/prompts/generate-plugin.prompt.md
124-124: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (65)
.github/instructions/release-scaffold.instructions.md (2)
4-5: YAML frontmatter formatting improvements are appropriate.The changes align with standard YAML practices: numeric version (1.0) and camelCase key naming (lastUpdated) improve consistency and tooling compatibility.
60-62: All reference links are accessible and correctly formatted.Verified that the relative path conversions resolve as intended:
../workflows/→.github/workflows/✓../../docs/RELEASE_PROCESS.md→docs/RELEASE_PROCESS.md✓./instructions.instructions.mdexists in.github/instructions/✓.github/instructions/i18n.instructions.md (1)
5-6: Frontmatter standardization looks good.The version format change (string to numeric) and lastUpdated key rename (snake_case to camelCase) align with the PR's standardization goals across instruction files. These changes are consistent with the broader pattern applied in the pull request.
.github/prompts/generate-plugin.prompt.md (1)
436-438: Related Resources links are valid. All three referenced files exist at their expected paths in the.github/directory, so no action is needed..github/instructions/release.instructions.md (2)
4-6: Frontmatter standardization looks good.The metadata updates (numeric version, camelCase lastUpdated) align with the broader PR pattern and improve consistency across instruction files.
61-63: References relocated to consolidated section.Migration to Markdown links at document end improves navigation and maintains consistency with other instruction files in this PR.
.github/instructions/folder-structure.instructions.md (3)
5-6: Frontmatter additions follow PR-wide standardization.Version and lastUpdated fields now consistent with other instruction documents.
199-204: Agent file placement guidance aligns with coding guidelines.The specification in lines 199–204 correctly documents agent naming convention (
{agent-name}.agent.mdfor specs,{agent-name}.agent.jsfor implementations) and placement in.github/agents/.
576-582: References section properly restructured.Markdown links are correctly formatted with repository-relative paths and relocate to document end consistently with other files.
.github/agents/generate-plugin.agent.md (1)
1-520: Agent specification structure is comprehensive and well-documented.The discovery stages, conversation flow examples, validation rules, and dependencies are clearly laid out. Once the implementation path issue (line 523) is resolved, this specification will serve as a strong guide for the plugin generation workflow.
.github/instructions/generate-plugin.instructions.md (2)
5-6: Frontmatter standardization applied consistently.Version and lastUpdated fields follow PR-wide pattern.
570-575: References section properly formatted with Markdown links.However, line 573 references
./agents/scaffold-generator.agent.md, while the PR shows.github/agents/generate-plugin.agent.md. Verify that the referenced agent file exists at the correct path and that naming is consistent across the codebase..github/instructions/markdown.instructions.md (2)
4-5: Frontmatter standardization applied.Version and lastUpdated fields updated consistently.
258-262: References properly relocated to end section.Markdown link formatting and repository-relative paths are correct.
.github/instructions/readme.instructions.md (2)
4-5: Frontmatter metadata standardized.Version and lastUpdated now consistent with other instruction files.
98-103: References section properly restructured with Markdown links.Links are well-formatted and use correct repository-relative paths.
.github/instructions/wpcs-accessibility.instructions.md (2)
5-6: Frontmatter field renamed and version format normalized.Field
last_updated→lastUpdatedand version format"v1.0"→1.0align with PR-wide standardization goals.
170-172: References converted to Markdown links with correct relative paths.Links are properly formatted for same-directory instruction file references.
.github/instructions/scaffold-extensions.instructions.md (2)
4-5: Frontmatter standardization applied consistently.Version and lastUpdated fields now uniform across instruction files.
417-419: References section added with appropriate Markdown links.Links correctly point to generator documentation, configuration registry, and related instructions.
.github/custom-instructions.md (1)
84-132: Instruction File Index provides valuable documentation discoverability.The new master index with categorized instruction files is a solid addition that improves navigation and accessibility of project standards. The table format is consistent and well-organized across the five categories.
.github/agents/release.agent.md (1)
15-19: Agent metadata properly declares tools and governance references.The addition of explicit tools and references to the Release Agent spec improves discoverability and clarifies permissions. This aligns with agent-spec.instructions.md guidance on frontmatter standardization.
.github/instructions/a11y.instructions.md (2)
5-6: Front-matter standardization improves metadata consistency.The change from string "v2.0" to numeric 2.0 and renaming last_updated to lastUpdated aligns with the PR's front-matter standardization across instruction files.
676-680: References relocation to end improves document structure.Moving references to a dedicated end-of-document section with Markdown links is consistent with the PR's broader documentation restructuring and improves discoverability.
.github/instructions/task-researcher.instructions.md (2)
4-5: Metadata standardization applied consistently.The changes to numeric version and addition of lastUpdated field align with the front-matter standardization pattern across the PR.
47-49: References properly formatted as Markdown links.The conversion to Markdown links with relative paths improves navigability and consistency across instruction files.
Please verify that the referenced instruction files (
instructions.instructions.mdand_index.instructions.md) exist in.github/instructions/..github/instructions/agent-spec.instructions.md (3)
4-5: Front-matter standardization applied to instruction template.Numeric version and lastUpdated field are now consistent with the broader PR standardization pattern.
18-18: Enhanced guidance on agent spec authorship and metadata discipline.The addition of changelog discipline guidance (line 35) and explicit references to lastUpdated field improvements clarify expectations for agent spec authors. Markdown links improve navigability.
Also applies to: 35-35, 69-69, 73-76
18-18: Capitalization hint from static analysis.The static analysis tool flagged that references to file paths containing "github" should use the capitalized form "GitHub". While these appear in comments/context rather than as semantic references, ensure consistency with project style guidelines if applicable.
Also applies to: 74-74
.github/agents/release-scaffold.agent.md (1)
24-404: Comprehensive agent specification with clear scope and constraints.The Release Scaffold Agent specification provides detailed role definition, validation phases, command interfaces, error handling, and example workflows. The structure aligns with agent-spec.instructions.md guidance and includes proper safety guardrails for non-destructive operations.
Please verify that a corresponding implementation file (e.g.,
scripts/release-scaffold.agent.js) exists in the repository, as agent specs should be paired with implementation files per coding guidelines..github/agents/agent.md (1)
36-47: New agent entries expand automation capabilities with clear documentation.The addition of WP Block Build Agent and Development Assistant Agent provides clear specifications and usage guidance. The entries maintain consistent formatting with the existing Scaffold Generator Agent and include proper references to detailed spec files.
AGENTS.md (1)
72-72: Agent Index reference improves central discoverability.The addition of Agent Index entry to the Cross-References table makes the main automation agents registry easily discoverable and provides a clear entry point for developers seeking available agents and their specifications.
.github/instructions/wpcs-css.instructions.md (1)
409-418: External resources + References placement looks consistent. End-of-doc references are repo-relative Markdown links and the external link is separated..github/instructions/wpcs-php.instructions.md (1)
984-999: External resources + References structure looks good. Keeping the WordPress standards link in “External resources” and internal docs in “References” is clear..github/instructions/wpcs-html.instructions.md (1)
104-111: Template Part Tips are a solid addition. Clear, actionable structure guidance for reusable parts..github/instructions/instructions.instructions.md (1)
23-31: References hygiene guidance is clear and enforceable. Explicit “References at end” + repo-relative Markdown links is easy to follow and review.Also applies to: 169-176, 177-190
.github/instructions/task-planner.instructions.md (1)
1-6: Metadata + end-of-doc References update looks consistent with the rest of the instruction set.Also applies to: 45-49
.github/instructions/schema-files.instructions.md (1)
1-9: applyTo expansion + References-at-end are both improvements. Clearer targeting for schema files and consistent repo-relative links.Also applies to: 483-491
.github/instructions/reporting.instructions.md (1)
5-6: Metadata standardization looks good (version/lastUpdated).
Matches the PR-wide frontmatter normalization..github/instructions/wpcs-php-docs.instructions.md (2)
5-6: Frontmatter normalization (lastUpdated + numeric version) is consistent.
Only question: confirmlastUpdated: 2025-10-19matches the intended meaning of that field (review date vs last content change).
942-960: References/external link additions look good.
Nice to include both the canonical WP DevHub page and the internal cross-links..github/instructions/scf-fields.instructions.md (2)
3-8: applyTo list + frontmatter metadata update is solid.
Makes targeting explicit for both PHP and SCF JSON.
936-948: External resources + internal References split is clear.
Links look appropriately scoped (SCF repo/docs + internal instruction entry points)..github/instructions/temp-files.instructions.md (2)
5-7: Frontmatter metadata addition is consistent with the new standard.
154-159: References are well-chosen (policy + enforcement + related guidance)..github/instructions/javascript-react-development.instructions.md (1)
5-6: Frontmatter update (numeric version + lastUpdated) aligns with the repo convention..github/instructions/testing-e2e.instructions.md (2)
6-8: Metadata addition is consistent and harmless.
138-140: Reference link formatting/paths look correct and consistent with other instruction docs..github/instructions/security.instructions.md (1)
6-8: Frontmatter normalization is good..github/instructions/block-json.instructions.md (1)
442-454: External resources + internal References separation looks good..github/instructions/wpcs-javascript.instructions.md (1)
6-8: Metadata changes look consistent with the new instruction format..github/prompts/agent-spec-auditor.prompt.md (1)
1-24: Solid, copy-pastable auditor workflow..github/instructions/patterns-and-templates.instructions.md (1)
30-31: Scope notice addition is clear and appropriately prominent..github/instructions/wpcs-js-docs.instructions.md (2)
559-568: All reference links in the file are valid and point to existing documentation files in the.github/instructions/directory.
1-8: Frontmatter is consistent with repository convention. ThelastUpdatedandversionkeys match the pattern used across all 30+ instruction files in.github/instructions/.No schema validation issues detected.
scripts/scan-mustache-variables.js (5)
12-12: Validation target correctly updated.The validation comment now references
plugin-config.jsoninstead oftheme-config.json, aligning with the plugin-focused approach of this PR.
19-31: Scan directories appropriately expanded.The addition of
inc,src,template-parts,patterns,scf-json, andtestsdirectories broadens the scope of mustache variable discovery to cover the full plugin structure.
34-48: Exclusion list expanded for generated artifacts.The updated exclusion list now covers generated plugins and various output directories (
generated-plugins,output-plugin,output,logs,.dry-run-backup), preventing pollution of the scan results with derived content.
124-196: Categorization logic comprehensively updated.The category mappings now include:
custom_post_typefor CPT-related variablestaxonomyfor taxonomy-related variablesblocksfor block-related variablescustom_fieldsfor SCF/ACF fieldsplugin_metadatafor plugin-specific metadataThis better reflects the expanded plugin generation capabilities.
417-431: Derived variable recognition updated.The
isDerivedVariablefunction now includes additional derived variables liketextdomain,copyright_year,copyright_holder, and taxonomy/name variations. This ensures these auto-generated values aren't incorrectly flagged as missing in validation..github/agents/a11y.agent.md (1)
1-122: Well-structured accessibility agent specification.The a11y agent spec follows the established template with:
- Comprehensive frontmatter metadata (title, version, owners, tools, references, guardrails)
- Clear role and scope definition
- Detailed capabilities and tool access
- Input/output specifications
- Safety guardrails and failure handling
- Test tasks for validation
- Observability requirements
This provides excellent guidance for implementing the accessibility agent.
.github/agents/task-planner.agent.md (1)
1-324: Comprehensive planning agent specification.The Block Plugin Planning Agent spec provides:
- Clear separation from implementation work (planning-only role)
- Mandatory research validation workflow
- Detailed planning output requirements (plan, details, implementation prompt files)
- Integration with the three-agent pipeline (Task Researcher → Planning → Implementation)
- Strong guardrails and risk assessment
This establishes excellent governance for the planning phase of block plugin development.
.github/schemas/plugin-config.schema.json (1)
528-653: Schema properties correctly defined with appropriate validation.The 13 new properties added to the plugin configuration schema are well-formed:
- short_description: Appropriately constrained to 150 chars for WordPress.org readme
- contributors: Correct pattern for WordPress.org usernames (
^[a-z0-9_-]+$)- URL fields (docs_url, support_url, github_url, donate_url, update_uri): All use
uriformat withhttps?://pattern; github_url correctly enforces GitHub domain- copyright_year: Pattern
^\d{4}(-\d{4})?$correctly allows single year or year range- copyright_holder: Simple string, appropriate for flexible naming
- block_category: Sensible default of "common" with examples
- block_supports: Well-structured nested boolean properties for align/color/spacing/typography with
truedefaults- release_date: Correct ISO date pattern
^\d{4}-\d{2}-\d{2}$- upgrade_notice: Appropriately constrained to 300 chars
These additions provide the metadata required for comprehensive plugin generation and WordPress.org distribution.
scripts/mustache-variables-registry.json (2)
1-2: Clarify intended format for registry file.This file contains a text header on line 1 (
🔍 Scanning repository for mustache variables...) followed by JSON, making it invalid JSON. The Biome parser correctly flags this as an error.If this file is generated output meant for human review only: The current format is acceptable for readability.
If this file is meant to be parsed by tools or committed to the repository: It should be pure JSON without the header text. Consider either:
- Removing lines 1-2 to make it valid JSON, or
- Restructuring as proper output with the scanning message sent to stderr instead of being included in the JSON output
Can you clarify whether this is:
- A committed artifact that should be valid JSON, or
- Generated output for human review that doesn't need to be valid JSON?
Based on the answer, we can determine if the format needs correction.
11-1437: Registry data reflects updated categorization correctly.The scanned variables show:
- 100 unique variables across 701 files
- New categories populated:
custom_post_type(21 vars),taxonomy(7 vars),blocks(4 vars)- Core identity variables properly identified:
slug,name,namespace,textdomain- URL category expanded with new fields:
license_uri,docs_url,support_url,github_url,update_uri,donate_url- Derived variable handling evident in the mappings
The data structure aligns with the categorization logic changes in
scan-mustache-variables.js.
| ## Implementation | ||
|
|
||
| This agent is implemented in [`scaffold-generator.agent.js`](./scaffold-generator.agent.js). | ||
| This agent is implemented in [`generate-plugin.agent.js`](../../scripts/generate-plugin.agent.js). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for the generate-plugin.agent.js file
fd -t f "generate-plugin.agent.js" .Repository: lightspeedwp/multi-block-plugin-scaffold
Length of output: 118
🏁 Script executed:
# Both files are in .github/agents/ directory, so the correct relative path should be:
# From .github/agents/generate-plugin.agent.md to .github/agents/generate-plugin.agent.js
# Since they're in the same directory, it should be just ./generate-plugin.agent.js
# Let's confirm the spec file exists and check its current reference
cat -n .github/agents/generate-plugin.agent.md | sed -n '520,525p'Repository: lightspeedwp/multi-block-plugin-scaffold
Length of output: 263
🏁 Script executed:
# Check if both files exist
echo "=== Checking .github/agents/generate-plugin.agent.js ==="
ls -la .github/agents/generate-plugin.agent.js 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"
echo ""
echo "=== Checking ./scripts/generate-plugin.agent.js ==="
ls -la ./scripts/generate-plugin.agent.js 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"
echo ""
echo "=== File comparison ==="
if [ -f .github/agents/generate-plugin.agent.js ] && [ -f ./scripts/generate-plugin.agent.js ]; then
echo "Both files exist. Comparing sizes:"
wc -l .github/agents/generate-plugin.agent.js ./scripts/generate-plugin.agent.js
fiRepository: lightspeedwp/multi-block-plugin-scaffold
Length of output: 319
Move implementation file to correct directory per coding guidelines.
The implementation file is currently at ./scripts/generate-plugin.agent.js, but per the coding guidelines, agent implementations must be located in .github/agents/ with the naming convention {agent-name}.agent.js. Move the file to .github/agents/generate-plugin.agent.js and update the reference on line 523 from ../../scripts/generate-plugin.agent.js to ./generate-plugin.agent.js.
🤖 Prompt for AI Agents
.github/agents/generate-plugin.agent.md around line 523: the implementation path
points to ../../scripts/generate-plugin.agent.js but per guidelines the agent
implementation must live under .github/agents with the filename
generate-plugin.agent.js; move the file from ./scripts/generate-plugin.agent.js
to .github/agents/generate-plugin.agent.js and update the reference on line 523
to ./generate-plugin.agent.js (ensure git moves the file to preserve history and
update any other references/imports if present).
| --- | ||
| name: "Release Agent" | ||
| description: "Automated release preparation and validation for the WordPress block theme scaffold" | ||
| target: "github-copilot" | ||
| version: "v1.0" | ||
| last_updated: "2025-12-15" | ||
| author: "LightSpeedWP" | ||
| maintainer: "Ash Shaw" | ||
| file_type: "agent" | ||
| category: "release-management" | ||
| status: "active" | ||
| visibility: "public" | ||
| tags: ["release", "automation", "validation", "wordpress", "block-theme"] | ||
| owners: ["lightspeedwp/maintainers"] | ||
| tools: ['search', 'edit', 'fetch'] | ||
| references: | ||
| - "../../AGENTS.md" | ||
| - "../instructions/agent-spec.instructions.md" | ||
| - "../instructions/coding-standards.instructions.md" | ||
| metadata: | ||
| guardrails: "Never skip validation steps. Always verify before making changes. Abort if critical checks fail. Log all actions for audit." | ||
| --- |
There was a problem hiding this comment.
Front-matter uses non-standard field name.
Line 6 uses last_updated instead of lastUpdated. The PR standardizes on camelCase lastUpdated across all agent specs (see agent-spec.instructions.md line 35, other instruction files). This should be corrected to maintain consistency.
Apply this diff to standardize the front-matter:
- last_updated: "2025-12-15"
+ lastUpdated: "2025-12-15"Based on coding guidelines and PR objectives for standardization...
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| name: "Release Agent" | |
| description: "Automated release preparation and validation for the WordPress block theme scaffold" | |
| target: "github-copilot" | |
| version: "v1.0" | |
| last_updated: "2025-12-15" | |
| author: "LightSpeedWP" | |
| maintainer: "Ash Shaw" | |
| file_type: "agent" | |
| category: "release-management" | |
| status: "active" | |
| visibility: "public" | |
| tags: ["release", "automation", "validation", "wordpress", "block-theme"] | |
| owners: ["lightspeedwp/maintainers"] | |
| tools: ['search', 'edit', 'fetch'] | |
| references: | |
| - "../../AGENTS.md" | |
| - "../instructions/agent-spec.instructions.md" | |
| - "../instructions/coding-standards.instructions.md" | |
| metadata: | |
| guardrails: "Never skip validation steps. Always verify before making changes. Abort if critical checks fail. Log all actions for audit." | |
| --- | |
| --- | |
| name: "Release Agent" | |
| description: "Automated release preparation and validation for the WordPress block theme scaffold" | |
| target: "github-copilot" | |
| version: "v1.0" | |
| lastUpdated: "2025-12-15" | |
| author: "LightSpeedWP" | |
| maintainer: "Ash Shaw" | |
| file_type: "agent" | |
| category: "release-management" | |
| status: "active" | |
| visibility: "public" | |
| tags: ["release", "automation", "validation", "wordpress", "block-theme"] | |
| owners: ["lightspeedwp/maintainers"] | |
| tools: ['search', 'edit', 'fetch'] | |
| references: | |
| - "../../AGENTS.md" | |
| - "../instructions/agent-spec.instructions.md" | |
| - "../instructions/coding-standards.instructions.md" | |
| metadata: | |
| guardrails: "Never skip validation steps. Always verify before making changes. Abort if critical checks fail. Log all actions for audit." | |
| --- |
🤖 Prompt for AI Agents
.github/agents/release-scaffold.agent.md lines 1 to 22: The front-matter uses a
non-standard snake_case field name `last_updated`; update this to the
standardized camelCase `lastUpdated` in the YAML front-matter to match
agent-spec.instructions.md and other agent specs, ensuring spacing and quoting
(if any) remain consistent and that references to this field elsewhere in the
file/repo are updated if present.
| ```text | ||
| .github/projects/research/ | ||
| ```` | ||
| Using naming pattern: | ||
| ```text | ||
| YYYYMMDD-task-description-research.md | ||
| ``` |
There was a problem hiding this comment.
Fix mismatched fenced code blocks (breaks Markdown rendering).
The Output Location & Format section opens with ```text but closes with ```` (Line 48–50). This will break the rest of the document formatting in many renderers.
Proposed fix:
-```text
-.github/projects/research/
-````
+```text
+.github/projects/research/
+```🤖 Prompt for AI Agents
.github/agents/task-researcher.agent.md around lines 48 to 56: the fenced code
block starts with ```text but is closed with four backticks (````), which breaks
Markdown rendering; replace the closing fence with three backticks (```) so the
block correctly opens and closes and verify the enclosed path line remains
`.github/projects/research/`.
| Write to: | ||
|
|
||
| ``` | ||
| .github/projects/research/YYYYMMDD-task-description-research.md | ||
| ``` | ||
|
|
||
| ### Step 7 — Provide Status Summary | ||
|
|
||
| Never output file contents. | ||
|
|
||
| Example: | ||
|
|
||
| ``` | ||
| Research: Created | ||
| Evidence Level: Complete | ||
| Ready for Planning Agent: Yes | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Add languages to fenced blocks to satisfy markdownlint (MD040).
The fences at Line 235–237 and Line 245–249 should declare a language (text is fine).
-```
+```text
.github/projects/research/YYYYMMDD-task-description-research.md...
- +text
Research: Created
Evidence Level: Complete
Ready for Planning Agent: Yes
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
235-235: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
245-245: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
.github/agents/task-researcher.agent.md around lines 233 to 250: the fenced code
blocks at lines 235–237 and 245–249 lack a language specifier which triggers
markdownlint MD040; update those opening fences to include a language (e.g.,
change ``` to ```text) for both blocks so the file passes linting while
preserving the existing block contents and formatting.
| **Last Updated:** 2025-12-10 | ||
| **Total Files:** 19 instruction files | ||
| **Total Files:** 22 instruction files | ||
|
|
There was a problem hiding this comment.
Fix instruction file count mismatch (22 vs 23). The “Total Files” line and the “File Statistics” table should match the actual list (currently numbered 1–23). Update the totals (and any “before/after” stats if they depend on that count).
Also applies to: 345-373
🤖 Prompt for AI Agents
In .github/instructions/_index.instructions.md around lines 44 to 46 (and also
update the related section at lines 345-373), the "Total Files" value (22) does
not match the actual instruction file count (23) and the File Statistics table;
update the "Total Files" number to 23 and adjust any dependent before/after
statistics in the table or elsewhere to reflect the correct total so both the
summary line and the table are consistent with the actual list.
| ## 0. Repository context | ||
|
|
||
| The relevant files in this repository are: | ||
|
|
||
| * Agent instructions (source of truth): | ||
|
|
||
| * `.github/instructions/agent-spec.instructions.md` | ||
| * Agent spec template: | ||
|
|
||
| * `.github/agents/template.agent.md` | ||
| * Agent specs to audit and improve: | ||
|
|
||
| * All files matching `.github/agents/*.agent.md` in this repo. | ||
|
|
||
| Treat the instructions file and template as the **authoritative standard** for structure and expectations. | ||
|
|
||
| If you don’t have the file content yet, first request or open it, then proceed with the audit. | ||
|
|
There was a problem hiding this comment.
Minor editorial: capitalize “GitHub” consistently.
LanguageTool flags a few instances where “GitHub” should be capitalized; worth fixing to keep docs clean.
Also applies to: 127-132
🧰 Tools
🪛 LanguageTool
[uncategorized] ~19-~19: The official name of this software platform is spelled with a capital “H”.
Context: ...it and improve: * All files matching .github/agents/*.agent.md in this repo. Treat...
(GITHUB)
🤖 Prompt for AI Agents
In .github/prompts/agent-spec-auditor.prompt.md around lines 7 to 24 (and also
check lines 127 to 132), several instances of “GitHub” are not capitalized
consistently; update those occurrences to “GitHub” (capital G and H) to match
the rest of the docs and the authoritative style, scanning the file for any
other lowercase “github” occurrences and fixing them while preserving
surrounding text and punctuation.
| ## 🧙 Interactive Wizard: Information Gathering | ||
|
|
||
| *(This section applies when using the Simple or Advanced Wizard)* | ||
|
|
||
| This scaffold requires detailed planning due to its complexity. I'll gather information in multiple stages to ensure your plugin is properly configured. |
There was a problem hiding this comment.
Replace emphasis-as-heading (markdownlint MD036).
Line 124 uses emphasis where a heading is expected; make it an actual heading for consistent structure/lint.
-*(This section applies when using the Simple or Advanced Wizard)*
+### Applies to Simple/Advanced Wizard
+
+This section applies when using the Simple or Advanced Wizard.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## 🧙 Interactive Wizard: Information Gathering | |
| *(This section applies when using the Simple or Advanced Wizard)* | |
| This scaffold requires detailed planning due to its complexity. I'll gather information in multiple stages to ensure your plugin is properly configured. | |
| ## 🧙 Interactive Wizard: Information Gathering | |
| ### Applies to Simple/Advanced Wizard | |
| This section applies when using the Simple or Advanced Wizard. | |
| This scaffold requires detailed planning due to its complexity. I'll gather information in multiple stages to ensure your plugin is properly configured. |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
124-124: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
.github/prompts/generate-plugin.prompt.md lines 122-126: the content uses
emphasis (italic) where a section heading is expected (markdownlint MD036).
Replace the emphasized line "(This section applies when using the Simple or
Advanced Wizard)" with an actual Markdown heading (e.g., "### This section
applies when using the Simple or Advanced Wizard" or an appropriate level) so
the structure is consistent with other headings and passes the lint rule.
| --- | ||
| title: "AGENT_CREATION Guide (Multi-Block Plugin Scaffold)" | ||
| description: "Governance and authoring workflow for creating AI agents within the Multi-Block Plugin Scaffold" | ||
| file_type: "governance" | ||
| version: "v1.0" | ||
| last_updated: "YYYY-MM-DD" | ||
| owners: ["LightSpeedWP Engineering"] | ||
| tags: ["multi-block-plugin", "agents", "governance", "spec-authoring"] | ||
| references: | ||
| - ".github/agents/template.agent.md" | ||
| - ".github/agents/generate-plugin.agent.md" | ||
| - ".github/agents/development-assistant.agent.md" | ||
| - "docs/AGENTS-OVERVIEW.md" | ||
| - "../schemas/frontmatter.schema.json" | ||
| --- |
There was a problem hiding this comment.
Docs frontmatter is missing required keys + has placeholder date.
Per docs/**/*.md guideline, you need title, description, category, type, audience, date and date must be YYYY-MM-DD. Also last_updated: "YYYY-MM-DD" is a placeholder.
Suggested update (use an actual date; PR created 2025-12-12):
---
title: "AGENT_CREATION Guide (Multi-Block Plugin Scaffold)"
description: "Governance and authoring workflow for creating AI agents within the Multi-Block Plugin Scaffold"
+category: "Governance"
+type: "Guide"
+audience: "Developers"
+date: 2025-12-12
file_type: "governance"
version: "v1.0"
-last_updated: "YYYY-MM-DD"
+last_updated: 2025-12-12
owners: ["LightSpeedWP Engineering"]
tags: ["multi-block-plugin", "agents", "governance", "spec-authoring"]
references:
- ".github/agents/template.agent.md"
- ".github/agents/generate-plugin.agent.md"
- ".github/agents/development-assistant.agent.md"
- "docs/AGENTS-OVERVIEW.md"
- "../schemas/frontmatter.schema.json"
---📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: "AGENT_CREATION Guide (Multi-Block Plugin Scaffold)" | |
| description: "Governance and authoring workflow for creating AI agents within the Multi-Block Plugin Scaffold" | |
| file_type: "governance" | |
| version: "v1.0" | |
| last_updated: "YYYY-MM-DD" | |
| owners: ["LightSpeedWP Engineering"] | |
| tags: ["multi-block-plugin", "agents", "governance", "spec-authoring"] | |
| references: | |
| - ".github/agents/template.agent.md" | |
| - ".github/agents/generate-plugin.agent.md" | |
| - ".github/agents/development-assistant.agent.md" | |
| - "docs/AGENTS-OVERVIEW.md" | |
| - "../schemas/frontmatter.schema.json" | |
| --- | |
| --- | |
| title: "AGENT_CREATION Guide (Multi-Block Plugin Scaffold)" | |
| description: "Governance and authoring workflow for creating AI agents within the Multi-Block Plugin Scaffold" | |
| category: "Governance" | |
| type: "Guide" | |
| audience: "Developers" | |
| date: 2025-12-12 | |
| file_type: "governance" | |
| version: "v1.0" | |
| last_updated: 2025-12-12 | |
| owners: ["LightSpeedWP Engineering"] | |
| tags: ["multi-block-plugin", "agents", "governance", "spec-authoring"] | |
| references: | |
| - ".github/agents/template.agent.md" | |
| - ".github/agents/generate-plugin.agent.md" | |
| - ".github/agents/development-assistant.agent.md" | |
| - "docs/AGENTS-OVERVIEW.md" | |
| - "../schemas/frontmatter.schema.json" | |
| --- |
🤖 Prompt for AI Agents
In docs/AGENT_CREATION.md lines 1 to 15, the frontmatter is missing required
keys and uses a placeholder date; add the required frontmatter keys title,
description, category, type, audience and date (use date: "2025-12-12" in
YYYY-MM-DD format), replace last_updated: "YYYY-MM-DD" with last_updated:
"2025-12-12" (or the actual last updated date), and ensure all dates follow
YYYY-MM-DD format and values are not placeholders.
| # AGENT_CREATION.md | ||
|
|
||
| **Human Governance for Creating New AI Agents in the Multi-Block Plugin Scaffold** | ||
|
|
||
| This document explains how humans plan, draft, evaluate, and publish new agent specifications for the **Multi-Block Plugin Scaffold**. |
There was a problem hiding this comment.
Avoid using bold text as a heading (MD036).
Line 19 is visually acting like a heading. Consider making it an ## heading instead of bold emphasis.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
19-19: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/AGENT_CREATION.md around lines 17 to 21, the line using bold text to act
like a heading (MD036) should be converted to a proper Markdown heading; replace
the bolded line with an appropriate heading level (e.g., prepend '## ' or '#' as
needed) so it renders and validates as a heading instead of emphasis, and ensure
surrounding whitespace/line breaks follow Markdown heading conventions.
| # 5. Writing Clear Multi-Block Behaviour | ||
|
|
||
| Because the scaffold generates entire WordPress plugins, agent responsibilities must be **precise and minimal**. | ||
|
|
||
| ### 5.1 Deterministic Behaviour | ||
|
|
||
| Examples: | ||
|
|
||
| - “If a CPT config is missing `label`, abort with error.” | ||
| - “If SCF field group fails schema validation, do not write the file.” | ||
|
|
||
| ### 5.2 Mustache & Template Rules | ||
|
|
There was a problem hiding this comment.
Fix heading level jump (MD001).
Line 171 is a ### directly under a # section context; make it ## (or add an intermediate ## heading).
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
171-171: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In docs/AGENT_CREATION.md around lines 167 to 179, there is a heading level
jump: a H3 ("### 5.1 Deterministic Behaviour") appears directly under the
top-level H1, triggering MD001; change that H3 to an H2 ("## 5.1 Deterministic
Behaviour") or insert an appropriate intermediate H2 before it so headings
descend hierarchically and the document passes linting.
…ains ## Critical Issues Fixed ### Issue #4: WordPress 6.5+ Block Rendering Standards - **block-json.instructions.md**: Enhanced dynamic block rendering documentation - Added "WordPress 6.5+ File-based Rendering (RECOMMENDED)" section - Positioned `"render": "file:./render.php"` as PRIMARY method - Documented automatic variables ($attributes, $content, $block) - Added proper mustache placeholder example with {{namespace}} and {{slug}} - Created "Legacy PHP Callback" section for pre-6.5 compatibility - Added Version Compatibility Matrix (6.5+, 6.0-6.4, <6.0) - Clarified scaffold standard: Always use file-based rendering ### Issue #5: Text Domain Standardization - **wpcs-php.instructions.md**: Standardized all text domain examples - Changed 'textdomain' to '{{textdomain}}' in all i18n examples (8 instances) - Changed 'lsx-theme' to '{{textdomain}}' in translation guidance (line 390) - Added explanatory note about placeholder vs production usage - Ensures AI agents copy correct mustache placeholders ## Changes Made ### block-json.instructions.md - Lines 305-367: Complete rewrite of "Render Callback" section - Added 3 subsections: Recommended, Legacy, Version Compatibility - Enhanced render.php example with proper @var annotations - Included WP_Block context usage example - Clear deprecation warning for render_callback approach ### wpcs-php.instructions.md - Lines 121-122: Updated wp_die() text domains - Lines 297-300: Updated core i18n function examples - Lines 307-308: Updated wp_localize_script() string examples - Line 390: Updated translation guidance with placeholder explanation - Line 295: Added note explaining {{textdomain}} placeholder convention ## Impact ### Before: - Unclear if file-based rendering or PHP callbacks were preferred - Text domain examples used inconsistent values ('textdomain', 'lsx-theme', 'plugin') - AI agents might copy wrong text domain into scaffold templates ### After: - Clear WordPress 6.5+ standard with file-based rendering as PRIMARY method - All examples consistently use '{{textdomain}}' placeholder - Explicit note explaining placeholder vs production usage - Version compatibility matrix guides decision-making ## Validation ✅ File-based rendering positioned as WordPress 6.5+ standard ✅ All text domain examples now use {{textdomain}} placeholder ✅ Backward compatibility documented for legacy WordPress versions ✅ Clear guidance prevents text domain mistakes in scaffold 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
name: "Pull Request"
about: "General changes, refactors, and maintenance"
title: "PR: {short summary}"
labels: ["status:needs-review"]
General Pull Request
Linked issues
Closes #
Changelog
Added
Changed
Fixed
Removed
Risk Assessment
Risk Level:
Potential Impact:
Mitigation Steps:
How to Test
Prerequisites
Test Steps
Expected Results
Edge Cases to Verify
Checklist (Global DoD / PR)
References
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.