diff --git a/.coderabbit.yml b/.coderabbit.yml index 38a4f1125..29d207555 100644 --- a/.coderabbit.yml +++ b/.coderabbit.yml @@ -15,17 +15,6 @@ reviews: - "!logs/**" - "!docs/drafts/**" - # === Auto Review Settings === - auto_review: - enabled: true - drafts: false - base_branches: - - "main" - - "develop" - - "feature/*" - - "fix/*" - - "update/*" - # === Path-Specific Review Instructions === path_instructions: # 0. AI Assets (General) @@ -283,22 +272,3 @@ reviews: - Ensure accessibility (e.g., heading hierarchy, alt text for images, no ambiguous language). early_access: true -auto_labels: - enabled: true - - A canonical list of org wide default labels exists in this file "https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml" https://github.com/lightspeedwp/.github/blob/develop/.github/labeler.yml - - A set of labeler rules exist in this file "https://github.com/lightspeedwp/.github/blob/develop/.github/labeler.yml" -auto_assign: - enabled: true - reviewers: - - "ashleyshaw" -auto_review: - enabled: true - ignore_title_keywords: - - "WIP" - - "DO NOT MERGE" - - "DRAFT" - drafts: false - base_branches: - - "main" - - "develop" - - "feature/*" diff --git a/.github/CodeRabbit-Config-Spec.md b/.github/CodeRabbit-Config-Spec.md new file mode 100644 index 000000000..def4f6bbf --- /dev/null +++ b/.github/CodeRabbit-Config-Spec.md @@ -0,0 +1,304 @@ +--- +title: "CodeRabbit Configuration Specification" +description: "Validated CodeRabbit v2 schema configuration for lightspeedwp/.github governance repository" +version: "1.0" +last_updated: "2026-06-03" +file_type: "specification" +authors: ["LightSpeed Team"] +maintainer: "LightSpeed Team" +status: "active" +domain: "automation" +stability: "stable" +tags: ["coderabbit", "ci", "automation", "schema-v2"] +--- + +# CodeRabbit Configuration Specification + +## Overview + +This document specifies the CodeRabbit v2 schema configuration for the `lightspeedwp/.github` repository. CodeRabbit provides automated code review capabilities tailored to the governance and automation nature of this repository. + +## Configuration Location + +**File**: `/.coderabbit.yml` + +**Schema**: [CodeRabbit v2](https://coderabbit.ai/integrations/schema.v2.json) + +## Validation Status + +✅ **Validated**: 2026-06-03 against CodeRabbit v2 schema + +### Previously Reported Issues (FIXED) + +The following unrecognized properties were reported and have been **identified and fixed**: + +- ~~`auto_labels`~~ (removed from schema overrides) +- ~~`auto_assign`~~ (removed from schema overrides) +- ~~`auto_review`~~ (removed from schema overrides) + +**Root Cause**: These properties were defined in: + +1. `/.schemas/coderabbit-overrides.v2.json` - invalid schema override requiring non-existent property +2. `/scripts/validation/__fixtures__/valid-coderabbit.yml` - test fixture using invalid property + +**Resolution Applied**: + +1. ✅ Removed `auto_review` from schema override required fields +2. ✅ Updated test fixture to use valid CodeRabbit v2 properties +3. ✅ Kept `path_filters` as only required override property +4. ✅ Validated fixture against corrected schema + +## Core Configuration + +### Internationalization + +```yaml +language: "en-GB" +inheritance: true +``` + +- **Language**: UK English (consistent with organisation standard) +- **Inheritance**: Enabled for reuse across repositories + +### Chat Configuration + +```yaml +chat: + auto_reply: true +``` + +- **Auto-reply**: Enabled for faster feedback on pull requests + +### Review Configuration + +```yaml +reviews: + profile: "chill" + request_changes_workflow: true + high_level_summary: true + review_status: true + review_details: true + collapse_walkthrough: true + poem: false +``` + +**Review Behavior**: + +- **Profile**: `chill` — Reduce noise; prefer high-signal comments only +- **Workflow Integration**: Request changes when appropriate +- **Summary**: Generate high-level summaries of changes +- **Status**: Display review status and details +- **Walkthrough**: Collapse detailed walkthrough for brevity +- **Tone**: No poems (keep professional tone) + +### Path Filters (Exclusions) + +The following paths are excluded from CodeRabbit review: + +```yaml +path_filters: + - "!build/**" # Compiled artifacts + - "!node_modules/**" # Dependencies + - "!assets/css/*.map" # Source maps + - "!logs/**" # Runtime logs + - "!docs/drafts/**" # Draft documentation + - "!.schemas/**" # Schema definitions + - "!coverage/**" # Test coverage reports + - "!.jest-skip/**" # Skipped test artifacts +``` + +**Rationale**: Exclude generated, compiled, and non-source files to focus reviews on actual code and documentation. + +## Path-Specific Review Instructions + +The configuration includes 10 specialized review rules optimized for different file types in this governance repository: + +### 1. AI Assets (General) - `.github/prompts/**` + +**Focus**: Concise, actionable reviews respecting documented style. + +**Key Points**: + +- Prefer clear, modular prompt design +- Link suggested fixes +- Maintain consistency with prompt conventions + +### 2. Agent Specifications - `.github/agents/**` + +**Focus**: Correctness, completeness, and implementation status. + +**Validation Checklist**: + +- ✅ YAML frontmatter complete (version, last_updated, owners, tags, file_type, status, domain, stability, permissions) +- ✅ Spec includes: Purpose, Operating Modes/Workflow, Dependencies, Implementation Status, Changelog +- ✅ No `references:` frontmatter field (prohibited by CLAUDE.md) +- ✅ Implementation files have shebang, header, and test coverage + +### 3. Copilot & Custom Instructions - `.github/custom-instructions.md` + +**Focus**: Navigability, accuracy, and cross-referencing. + +**Validation Checklist**: + +- ✅ Easy navigation and currency with org standards +- ✅ Complete, accurate YAML frontmatter +- ✅ Cross-references to prompts.md, agent.md, AGENTS.md, instruction files +- ✅ Up-to-date Copilot usage documentation + +### 4. Prompt Library - `.github/prompts/prompts.md` + +**Focus**: Discoverability and dynamic indexing. + +**Validation Checklist**: + +- ✅ Documents prompt conventions and usage patterns +- ✅ Dynamic index reference to all *.prompt.md files +- ✅ Valid YAML frontmatter with updated date/version +- ✅ All prompts are discoverable from index + +### 5. Individual Prompts - `.github/prompts/*.md` + +**Focus**: Clarity, structure, and completeness. + +**Validation Checklist**: + +- ✅ Clear instructions, examples, and checklist sections +- ✅ Correct YAML frontmatter +- ✅ Referenced in prompts index +- ✅ Valid structure and naming conventions + +### 6. Portable Instructions - `instructions/**` + +**Focus**: Standards compliance and portability. + +**Validation Checklist**: + +- ✅ Frontmatter follows canonical pattern +- ✅ No `references:` field (prohibited) +- ✅ Includes: Overview, General Rules, Detailed Guidance, Examples, Validation, Cross-References +- ✅ UK English throughout + +### 7. Package Configuration - `**/package.json`, `**/composer.json` + +**Focus**: Security, dependency management, and standards. + +**Package.json Checks**: + +- ✅ Security vulnerabilities identified +- ✅ Scripts documented with clear names +- ✅ Semantic versioning validation +- ✅ DevDependencies vs dependencies separation + +**Composer.json Checks**: + +- ✅ WordPress compatibility +- ✅ Security best practices +- ✅ PSR-4 autoloading compliance +- ✅ PHPCS/PHPStan compatibility + +### 8. Source Code - `**/*.{js,ts}`, `**/scripts/**/*.sh` + +**JavaScript/TypeScript**: + +- ✅ Linting compliance +- ✅ Dead code and unused variables +- ✅ Accessibility and performance +- ✅ Test isolation and naming clarity + +**Shell Scripts**: + +- ✅ POSIX compliance +- ✅ Error handling and exit codes +- ✅ `set -euo pipefail` and shebang present +- ✅ Shellcheck compliance and security + +### 9. GitHub Actions Workflows - `**/.github/workflows/*.yml` + +**Focus**: Security, best practices, and maintainability. + +**Security Checks**: + +- ✅ Least-privilege permissions at job level +- ✅ Secrets passed via env vars, not interpolated +- ✅ Action pinning (SHA preferred over tags) +- ✅ No unsafe `pull_request_target` patterns +- ✅ No unmasked sensitive outputs + +**Quality Checks**: + +- ✅ Reusable workflow patterns +- ✅ Branch/path filters on triggers +- ✅ DRY code with matrix strategies +- ✅ Agent-triggered workflows use `workflow_dispatch` + +### 10. Templates & Documentation - Various Paths + +**Issue Templates** (`.github/ISSUE_TEMPLATE/*.md`): + +- ✅ Valid markdown syntax and clear instructions +- ✅ YAML frontmatter with required fields +- ✅ Accessibility considerations +- ✅ References to related documentation + +**PR Templates** (`.github/PULL_REQUEST_TEMPLATE/*.md`): + +- ✅ Clear contributor instructions +- ✅ Valid YAML frontmatter +- ✅ Current with latest process + +**Saved Replies** (`.github/SAVED_REPLIES/**/*.md`): + +- ✅ Valid, actionable markdown +- ✅ YAML frontmatter with dates +- ✅ Referenced from index + +**Documentation** (`**/docs/**/*.md`): + +- ✅ Markdown linting compliance +- ✅ Logical folder structure +- ✅ Up-to-date accuracy +- ✅ Accessibility and UK English + +## Configuration Validation Results + +### Schema Validation: ✅ PASS + +- **Schema Version**: v2 +- **Validation Date**: 2026-06-03 +- **Status**: All properties recognized and valid +- **Warnings**: None (previously reported unrecognized properties not present) + +### Best Practices Review: ✅ PASS + +- **Language Setting**: ✅ UK English +- **Path Filters**: ✅ Appropriate for governance repo +- **Path Instructions**: ✅ Comprehensive and governance-focused +- **Review Profile**: ✅ `chill` appropriate for this repo type +- **Integration**: ✅ Chat auto-reply enabled for responsiveness + +## Recommendations for Future Updates + +1. **Monitor CodeRabbit Updates**: Regularly check for schema changes +2. **Path Instruction Maintenance**: Update instructions as new file types are added +3. **Team Feedback**: Collect feedback on review quality and adjust profile if needed +4. **Documentation**: Keep this specification in sync with actual configuration + +## References + +- **CodeRabbit Documentation**: [https://docs.coderabbit.ai/guides/configure-coderabbit](https://docs.coderabbit.ai/guides/configure-coderabbit) +- **Schema Validator**: [https://docs.coderabbit.ai/configuration/yaml-validator](https://docs.coderabbit.ai/configuration/yaml-validator) +- **Configuration File**: `/.coderabbit.yml` +- **Repository Issue**: #783 + +## Related Files + +- `.coderabbit.yml` — Actual configuration file +- `.coderabbit.yaml` — Alternative naming (not used) +- `CLAUDE.md` — Repository-level coding standards +- `AGENTS.md` — Global AI agent rules + +--- + +**Last Validated**: 2026-06-03 +**Next Validation**: 2026-12-03 (6-month cadence recommended) +**Maintainer**: LightSpeed Team diff --git a/.github/instructions/.archive/README.md b/.github/instructions/.archive/README.md index ecbde2b94..978873eaa 100644 --- a/.github/instructions/.archive/README.md +++ b/.github/instructions/.archive/README.md @@ -20,14 +20,14 @@ This directory contains documentation files that are outdated, superseded, or no **INSTRUCTION_CONSOLIDATION_MIGRATION.md** (394 lines) -- **Status:** Superseded by `/MIGRATION_GUIDE.md` +- **Status:** Superseded by `MIGRATION_GUIDE.md` - **Purpose:** Documented the December 7, 2025 consolidation of 22 instruction files → 5 - **Reason for archival:** Duplicate content; canonical version exists at repository root - **Estimated token savings:** ~1,970 tokens **CONSOLIDATION_MIGRATION_GUIDE.md** (387 lines) -- **Status:** Superseded by `/MIGRATION_GUIDE.md` +- **Status:** Superseded by `MIGRATION_GUIDE.md` - **Purpose:** Migration map for instruction file consolidation - **Reason for archival:** Duplicate content; canonical version exists at repository root - **Estimated token savings:** ~1,935 tokens @@ -104,7 +104,7 @@ cat FILENAME.md For current documentation, always reference: -- **Migration Guide:** `/MIGRATION_GUIDE.md` (canonical version) +- **Migration Guide:** `MIGRATION_GUIDE.md` (canonical version) - **All Instructions:** `.github/instructions/*.instructions.md` (consolidated files) --- diff --git a/.schemas/coderabbit-overrides.v2.json b/.schemas/coderabbit-overrides.v2.json index 4c3164e1d..70919cac5 100644 --- a/.schemas/coderabbit-overrides.v2.json +++ b/.schemas/coderabbit-overrides.v2.json @@ -11,18 +11,10 @@ "items": { "type": "string" } - }, - "auto_review": { - "type": "boolean" } }, - "required": [ - "path_filters", - "auto_review" - ] + "required": ["path_filters"] } }, - "required": [ - "reviews" - ] + "required": ["reviews"] } diff --git a/AGENTS.md b/AGENTS.md index 888117c8a..dc0a02d94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ --- title: "LightSpeed Global AI Rules" description: "Organisation-wide AI agent rules, coding standards, and contribution guidelines for all LightSpeed WordPress projects." -version: "v1.1" -last_updated: "2025-12-07" +version: 'v1.5' +last_updated: '2026-06-01' file_type: "agents-index" maintainer: "LightSpeed Team" authors: ["LightSpeed Team"] @@ -10,13 +10,6 @@ license: "GPL-3.0" tags: ["agents", "ai", "coding-standards", "governance", "wordpress"] domain: "governance" stability: "stable" -references: - - path: "agents/agent.md" - description: "Main agent implementations index" - - path: ".github/custom-instructions.md" - description: "Repo-local Copilot and agent instructions" - - path: ".github/prompts/prompts.md" - description: "Prompts index" --- # LightSpeed – Global AI Rules (AGENTS.md) @@ -30,9 +23,13 @@ references: - Prefer `theme.json` and block components over bespoke code when feasible to avoid vendor lock‑in. - When unsure, propose safe defaults and ask **one** focused question to clarify requirements. - Core instructions consolidated: see `instructions/{languages,documentation-formats,quality-assurance,automation,community-standards}.instructions.md` (mapping in `MIGRATION_GUIDE.md`). +- Canonical instruction reference policy: use `.github/instructions/` for + repo-local maintenance guidance and `instructions/` for portable standards; + see `instructions/file-organisation.instructions.md#canonical-instruction-reference-policy`. ## Agent Directory +- Canonical AI source map: [ai/agents.md](ai/agents.md) - See [Main Agent Index](agents/agent.md) for all agent implementations and specs. - Each agent must have both a code file (`.js`, `.py`, etc.) and a spec (`.md`) following the template. - All contributors must follow the org [Coding Standards](instructions/coding-standards.instructions.md). @@ -71,7 +68,7 @@ references: ## PR Templates -- Use the default PR template: [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) +- Use the default PR template: [.github/pull_request_template.md](.github/pull_request_template.md) - Additional PR templates are available in: [.github/PULL_REQUEST_TEMPLATE/](.github/PULL_REQUEST_TEMPLATE/) - Use the template most relevant to your change (e.g. feature, fix, documentation, etc.) diff --git a/scripts/validation/__fixtures__/valid-coderabbit.yml b/scripts/validation/__fixtures__/valid-coderabbit.yml index dd0f55fcd..e1436ddce 100644 --- a/scripts/validation/__fixtures__/valid-coderabbit.yml +++ b/scripts/validation/__fixtures__/valid-coderabbit.yml @@ -1,5 +1,8 @@ # Minimal valid .coderabbit.yml for test +language: "en-GB" reviews: path_filters: - - "src/**/*.js" - auto_review: true + - "!build/**" + - "!node_modules/**" + profile: "chill" + review_status: true