.coderabbit.yml

# yaml-language-server: $schema=https://docs.coderabbit.ai/schema/schema.v2.json

# CodeRabbit configuration for lightspeedwp/.github
# This repository contains GitHub governance files, agent specs, workflow
# automation, shared instructions, and community health files — not a typical
# application repo. Reviews should prioritise correctness, security, clarity,
# and maintainability over stylistic nitpicks.

language: "en-GB"
inheritance: true

chat:
  auto_reply: true

reviews:
  # === Review Behaviour ===
  profile: "chill" # Reduce noise; prefer high-signal comments only
  request_changes_workflow: true
  high_level_summary: true
  review_status: true
  review_details: true
  collapse_walkthrough: true
  poem: false

  # === Path Filters (Exclude from Review) ===
  path_filters:
    - "!build/**"
    - "!node_modules/**"
    - "!assets/css/*.map"
    - "!logs/**"
    - "!docs/drafts/**"
    - "!schema/**"
    - "!coverage/**"
    - "!.jest-skip/**"

  # === Path-Specific Review Instructions ===
  path_instructions:
    # 0. AI Assets (General)
    - path: ".github/prompts/**"
      instructions: |
        Prefer concise, actionable reviews. Respect documented style precedence. Link suggested fixes.

    - path: ".github/agents/**"
      instructions: |
        Review agent spec and implementation files:
          - Verify YAML frontmatter is complete (version, last_updated, owners, tags, file_type, status, domain, stability, permissions).
          - Confirm the spec includes: Purpose, Operating Modes or Workflow, Dependencies, Implementation Status, and Changelog sections.
          - Flag any `references:` frontmatter field — this is prohibited by CLAUDE.md.
          - For implementation files (.agent.js, .agent.sh, .agent.py): ensure shebang, header, and test coverage exist.

    # 1. Copilot & AI Files
    - path: ".github/custom-instructions.md"
      instructions: |
        Review custom-instructions.md:
          - Ensure the file is easy to navigate and up to date with org standards.
          - Validate YAML frontmatter for completeness and accuracy.
          - Confirm cross-references to prompts.md, agent.md, AGENTS.md, and instruction files.
          - Check for up-to-date cross-references and clear documentation of Copilot usage.

    - path: "**/.github/prompts/prompts.md"
      instructions: |
        - Ensure the file documents prompt conventions and usage patterns.
        - Ensure a dynamic index reference to all *.prompt.md files exists.
        - Validate YAML frontmatter and update date/version fields.
        - Confirm all prompt files are discoverable from this index.

    - path: "**/.github/prompts/*.md"
      instructions: |
        Review all prompt files:
          - Check for clear instructions, examples, and checklist sections.
          - Ensure each file has correct YAML frontmatter.
          - Confirm the file is referenced in the prompts index.
          - Validate structure, naming, and documentation.

    # 2. Instruction files
    - path: "instructions/**"
      instructions: |
        Review portable instruction files:
          - Verify frontmatter follows the canonical pattern (file_type, version, last_updated, owners, tags, status, domain, stability).
          - Flag any `references:` frontmatter field — prohibited by CLAUDE.md.
          - Confirm the file has: Overview, General Rules, Detailed Guidance, Examples, Validation, and Cross-References sections.
          - Check that language is UK English throughout.

    # 3. Project configuration and automation
    - path: "**/package.json"
      instructions: |
        Review package.json:
          - Check for security vulnerabilities and outdated packages.
          - Ensure scripts are documented with clear, descriptive names.
          - Validate semantic versioning and proper version pinning.
          - Confirm devDependencies vs dependencies separation.
          - Ensure scripts follow org standards (lint, test, build, format).

    - path: "**/composer.json"
      instructions: |
        Review composer.json for WordPress development:
          - Ensure PHP dependencies are WordPress-compatible and up-to-date.
          - Check for security best practices in package selection.
          - Verify autoloading configuration and PSR-4 compliance.
          - Ensure compatibility with WordPress coding standards tools (PHPCS, PHPStan).

    # 4. Source code and scripts
    - path: "**/*.{js,ts}"
      instructions: |
        Review JavaScript/TypeScript:
          - Ensure code is linted and follows project style guides.
          - Check for dead code, unused variables, and clear function naming.
          - Validate accessibility and performance optimisations.
          - Ensure tests are isolated and do not depend on external state.
          - Check for descriptive test names and clear test structure.

    - path: "**/scripts/**/*.sh"
      instructions: |
        Review shell scripts:
          - Check for POSIX compliance and portability.
          - Validate error handling, input validation, and exit codes.
          - Confirm `set -euo pipefail` and shebang are present.
          - Ensure functions are modular, reusable, and well-documented.
          - Check for shellcheck compliance and security best practices.

    # 5. Workflow and automation files
    - path: "**/.github/workflows/*.yml"
      instructions: |
        Review GitHub Actions workflows for this governance repo:
          - Security: check for least-privilege permissions (use `permissions:` at job level, default to read-only).
          - Secret handling: ensure secrets are passed via env vars, not interpolated directly into run: steps to prevent injection.
          - Action pinning: prefer SHA-pinned actions over mutable tags (e.g. `actions/checkout@v4` is acceptable; SHA pins are better).
          - No `pull_request_target` with untrusted code execution unless explicitly justified.
          - Avoid storing sensitive outputs as unmasked step outputs.
          - Check for reusable workflow patterns and matrix strategies where appropriate.
          - Validate `on:` triggers: ensure branch/path filters are present to avoid unnecessary runs.
          - Confirm workflows are documented, DRY, and maintainable.
          - Ensure agent-triggered workflows use `workflow_dispatch` with defined inputs.

    # 6. Agent and meta files
    - path: ".github/agents/AGENTS.md"
      instructions: |
        Review the main agents index file:
          - Ensure this file lists all agent specs, implementations, and test files.
          - Confirm each agent is listed with description and test coverage status.
          - Validate cross-references to related workflows, prompts, and documentation.

    - path: ".github/agents/*.agent.md"
      instructions: |
        Review all agent specification files:
          - Verify frontmatter completeness (version, last_updated, owners, tags, file_type, status, domain, stability, permissions).
          - Flag any `references:` frontmatter field — this is prohibited.
          - Each spec must include: Purpose, Workflow/Operating Modes, Dependencies, Implementation Status, Changelog.
          - Implementation Status must include a gap-analysis table (spec vs. runtime).
          - For paired workflow agents: confirm the matching .yml workflow file exists and is referenced.

    - path: ".github/agents/*.agent.js"
      instructions: |
        Review all JavaScript agent files:
          - Must start with a valid shebang and header (purpose, usage, author, date).
          - Require comprehensive JSDoc for all functions/classes.
          - Must have a corresponding Jest test file with coverage for all capabilities and error paths.

    - path: ".github/agents/*.agent.sh"
      instructions: |
        Review all shell agent files:
          - Must start with a valid shebang and header (purpose, usage, author, date).
          - Require inline comments for all functions/logic.
          - Must have a corresponding Bats test file.
          - Ensure agent is referenced in the agent index and spec.

    - path: ".github/agents/*.agent.py"
      instructions: |
        Review all Python agent files:
          - Must start with a valid shebang and header.
          - Require docstrings for all classes/functions.
          - Must have a corresponding pytest file with coverage.
          - Type hints and linting (mypy, flake8) required.

    # 7. Tests
    - path: "**/tests/*.*"
      instructions: |
        Review all test files:
          - All test files must have a header (purpose, author, date, related files).
          - Use clear, descriptive test names and logical structure.
          - Include both positive and negative test cases.
          - Be discoverable from the main agent/test index.
          - Pass all style checks and linting.

    # 8. Templates and saved replies
    - path: "**/.github/ISSUE_TEMPLATE/*.md"
      instructions: |
        Review issue template files:
          - Ensure valid markdown syntax, logical structure, and clear instructions.
          - Validate YAML frontmatter for required fields (title, description, labels).
          - Check for accessibility (clear headings, no ambiguous language).
          - Confirm templates reference related documentation.

    - path: "**/.github/PULL_REQUEST_TEMPLATE/*.md"
      instructions: |
        Review pull request template files:
          - Ensure valid markdown syntax and clear contributor instructions.
          - Validate YAML frontmatter and template metadata.
          - Confirm templates are up to date with current process.

    - path: "**/.github/DISCUSSION_TEMPLATE/*.yml"
      instructions: |
        Review discussion template YAML files:
          - Ensure valid YAML syntax and clear user instructions.
          - Validate required frontmatter fields.
          - Confirm accessibility (clear field names, no ambiguous language).

    - path: "**/.github/SAVED_REPLIES.md"
      instructions: |
        Review the saved replies index file:
          - Ensure the file links to all saved replies.
          - Validate YAML frontmatter and date/version fields.
          - Check for clarity, brevity, and usefulness of reply summaries.

    - path: "**/.github/SAVED_REPLIES/**/*.md"
      instructions: |
        Review all saved replies:
          - Ensure replies are valid, actionable markdown.
          - Validate YAML frontmatter and date/version fields.
          - Check replies are referenced from the index.

    # 9. Documentation
    - path: "**/docs/**/*.md"
      instructions: |
        Review documentation files:
          - Ensure markdown is linted and formatted per project style guides.
          - Flag illogical folder structures, file naming, or misplaced content.
          - Confirm documentation is up to date, accurate, and cross-referenced.
          - Ensure accessibility (heading hierarchy, alt text for images, UK English).

    # 10. Changelog
    - path: "CHANGELOG.md"
      instructions: |
        Review CHANGELOG.md:
          - Confirm entries follow Keep a Changelog 1.1.0 format.
          - Each entry under [Unreleased] must include a PR link and issue link.
          - Verify entries use the correct section headings (Added, Changed, Fixed, Deprecated, Removed, Security, Documentation, Performance).
          - Check UK English spelling throughout.
early_access: true