Agent, docs and instructions file clean up

Author: ashleyshaw

.github/agents/labeling.agent.md

@@ -205,4 +205,4 @@ Maps issue template types to labels:
 - [labeling.agent.js](../../scripts/agents/labeling.agent.js) - Main implementation
 - [Labeling Documentation](../../docs/LABELING.md) - Complete labeling system docs
 - [Label Strategy](../../docs/LABEL_STRATEGY.md) - Label philosophy and best practices
-- [Coding Standards](../.github/instructions/coding-standards.instructions.md) - Development guidelines
+- [Coding Standards](../instructions/coding-standards.instructions.md) - Development guidelines

.github/agents/planner.agent.md

@@ -315,7 +315,7 @@ Comprehensive planning agent supporting three complementary modes:
 
 ## Reference Documentation
 
-- [Spec-Driven Workflow](.github/instructions/spec-driven-workflow.instructions.md)
-- [Architecture Guide](docs/ARCHITECTURE.md)
-- [Contributing Guidelines](CONTRIBUTING.md)
-- [Coding Standards](.github/instructions/coding-standards.instructions.md)
+- [Spec-Driven Workflow](../instructions/spec-driven-workflow.instructions.md)
+- [Architecture Guide](../../docs/ARCHITECTURE.md)
+- [Contributing Guidelines](../../CONTRIBUTING.md)
+- [Coding Standards](../instructions/coding-standards.instructions.md)

.github/agents/reporting.agent.md

@@ -123,6 +123,7 @@ First, what category does this report belong to?
 - issue-metrics (GitHub issue analytics, trends)
 - labeling (label automation, sync logs)
 - linting (ESLint, code quality reports)
+- mermaid (diagram coverage, accessibility checks, rendering/contrast audits)
 - meta (documentation metadata: badges, references, footers)
 - metrics (general metrics, weekly summaries)
 - optimisation (performance optimisation, token reduction)

.github/agents/reviewer.agent.md

@@ -0,0 +1,134 @@
+---
+name: "Reviewer"
+description: "Automated PR review agent that posts review summaries, CI status checks, and actionable recommendations for pull requests."
+file_type: "agent"
+version: "v1.0"
+created_date: "2025-12-10"
+last_updated: "2025-12-10"
+author: "LightSpeed Team"
+maintainer: "Ash Shaw"
+category: "automation"
+status: "active"
+visibility: "public"
+tags: ["pr-review", "automation", "ci", "quality-gate", "pull-requests"]
+language: "en"
+references:
+  - path: "../../scripts/agents/reviewer.agent.js"
+    description: "Main implementation script"
+  - path: "../workflows/reviewer.yml"
+    description: "GitHub Actions workflow"
+  - path: "../instructions/pull-requests.instructions.md"
+    description: "PR standards and guidelines"
+  - path: "../instructions/coding-standards.instructions.md"
+    description: "Coding standards reference"
+owners: ["lightspeedwp/maintainers"]
+---
+
+# Reviewer Agent
+
+## Purpose
+
+Automatically review pull requests and post comprehensive summaries including CI status, file analysis, changelog presence, and actionable recommendations to help maintainers make informed merge decisions.
+
+## Responsibilities
+
+- **CI Status Monitoring**: Check and report combined CI/CD pipeline status
+- **File Analysis**: Review changed files and identify potential issues
+- **Changelog Validation**: Verify changelog entries are present when required
+- **Review Summary**: Post structured comment with all findings
+- **Quality Gates**: Flag PRs that don't meet quality standards
+
+## Workflow Integration
+
+Triggered by the `.github/workflows/reviewer.yml` workflow on:
+
+- Pull request opened
+- Pull request synchronized (new commits pushed)
+- Pull request ready for review
+
+## Implementation
+
+**Script**: `scripts/agents/reviewer.agent.js`
+
+### Key Functions
+
+1. **run()** - Main orchestrator
+   - Fetches PR context
+   - Checks CI/CD status
+   - Analyses changed files
+   - Posts review summary comment
+
+2. **CI Status Check**
+   - Queries GitHub combined status API
+   - Reports: success, pending, failure, error, or unknown
+
+3. **File Analysis**
+   - Lists changed files
+   - Identifies file types
+   - Flags high-risk changes
+
+4. **Changelog Validation**
+   - Checks for CHANGELOG.md updates
+   - Can be required or optional (configurable)
+
+### Review Summary Format
+
+```markdown
+## 🤖 Automated Review Summary
+
+### CI/CD Status
+✅ All checks passing
+⏳ Checks pending
+❌ Some checks failed
+
+### Changed Files
+- `file1.js` - Modified
+- `file2.md` - Added
+- `file3.test.js` - Modified
+
+### Changelog
+✅ Changelog updated
+⚠️ No changelog entry found
+
+### Recommendations
+- Review test coverage
+- Update documentation
+- Consider adding migration notes
+```
+
+## Configuration
+
+The workflow accepts these inputs:
+
+- `github-token`: GitHub token for API access (required)
+- `require-changelog`: Whether to enforce changelog entries (default: `false`)
+
+## Best Practices
+
+1. **Review Automation**: This agent assists reviewers but doesn't replace human code review
+2. **CI Integration**: Always wait for CI to complete before merging
+3. **Changelog**: Update CHANGELOG.md for user-facing changes
+4. **Quick Feedback**: Agent provides instant feedback to PR authors
+
+## Error Handling
+
+- Gracefully handles missing PR context
+- Reports API errors without failing the workflow
+- Provides dry-run mode for testing
+
+## Related Agents
+
+- [Testing Agent](./testing.agent.md) - Runs test suites
+- [Linting Agent](./linting.agent.md) - Code quality checks
+- [Labeling Agent](./labeling.agent.md) - PR label automation
+- [Release Agent](./release.agent.md) - Release preparation
+
+## Reference Documentation
+
+- [Pull Request Process](../instructions/pull-requests.instructions.md)
+- [Coding Standards](../instructions/coding-standards.instructions.md)
+- [GitHub Actions Workflows](../../docs/WORKFLOWS.md)
+
+---
+
+*Reviewer Agent - Automated PR quality gates and review assistance*

.github/agents/testing.agent.md

@@ -29,14 +29,10 @@ tags:
   ]
 language: "en"
 references:
-  - path: ".github/agents/testing.agent.js"
-    description: "Implementation script"
   - path: ".github/workflows/testing.yml"
-    description: "GitHub Actions testing workflow"
-  - path: ".github/instructions/testing.instructions.md"
-    description: "Master testing standards index"
-  - path: ".github/instructions/tests.instructions.md"
-    description: "Test framework standards"
+    description: "GitHub Actions testing workflow (uses npm scripts)"
+  - path: "package.json"
+    description: "Test scripts configuration (npm run check, npm run test, npm run lint:all)"
   - path: ".github/instructions/coding-standards.instructions.md"
     description: "Unified coding standards"
 owners: ["lightspeedwp/maintainers"]
@@ -50,6 +46,8 @@ metadata:
 
 Automate test execution, coverage reporting, and quality validation across all testing frameworks used in LightSpeed projects.
 
+**Implementation Note:** This agent uses npm scripts defined in `package.json` rather than a dedicated `.agent.js` script file. The workflow executes `npm run check` which orchestrates linting and testing via package.json scripts.
+
 ## Responsibilities
 
 - Execute unit tests using Jest for JavaScript/TypeScript

.github/custom-instructions.md

@@ -16,7 +16,7 @@ The files are organised under the `.github/` directory:
 - [`AGENTS.md`](../AGENTS.md): Global AI rules applicable to all projects. Defines language, security, accessibility, modularity, and review requirements. Reference this file for central guidance on frontmatter schemas ([schemas/frontmatter.schema.json](../schemas/frontmatter.schema.json))
 - [`agents/agent.md`](./agents/agent.md): Main agent index. Links all agent specs, stubs, and explains local/dry-run usage. Reference this for agent implementation and testing.
 - [`instructions/`](./instructions/): Modular `.instructions.md` files scoped by language, file type, or topic. Each file includes YAML frontmatter describing its scope, mission, guidelines, checklists, and references. See below for a full index.
-  - **[file-output-organization.instructions.md](./instructions/file-output-organization.instructions.md)**: **CRITICAL** - Defines where Copilot/agents should create reports, task files, and project artifacts. Always follow these rules to prevent file organization drift.
+  - **[file-organisation.instructions.md](./instructions/file-organisation.instructions.md)**: **CRITICAL** - Defines where Copilot/agents should create reports, task files, and project artefacts. Always follow these rules to prevent file organisation drift.
 - [`prompts/prompts.md`](./prompts/prompts.md): Master prompt index and guidance. Reference this for prompt authoring conventions and to locate all available prompts.
 - [`prompts/`](./prompts/): Reusable `.prompt.md` files for Copilot Chat and GitHub Actions. Each prompt describes a specific task (e.g. audit docs, fix lint, author JSON schema, generate workflow, increase test coverage). See below for a full index.
 - [`reports/`](./reports/): Generated reports, analysis outputs, and audit files. All Copilot/agent reports must be created here, not in docs/ or repository root.
@@ -119,4 +119,9 @@ Use comprehensive inline documentation following WordPress standards (see [codin
 - Update as standards evolve or new best practices emerge
 - Document significant changes in commit messages
 
+## Community Health Assets (Shared vs Repository-Scoped)
+
+- **Shared across the organisation:** discussion templates (`.github/DISCUSSION_TEMPLATE/`), saved replies (`.github/SAVED_REPLIES/`), issue templates (`.github/ISSUE_TEMPLATE/`), pull request templates (branch-specific) (`.github/PULL_REQUEST_TEMPLATE/`), default PR template (`.github/PULL_REQUEST_TEMPLATE.md`).
+- **Repository-scoped only:** issue types (`.github/issue-types.yml`) and labels (`.github/labels.yml`) are defined per repository and are **not** shared organisation-wide.
+
 For more details, see the README files in the `instructions` and `prompts` folders.