.coderabbit.yml

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

# Branch-type-specific review context is maintained externally in docs/BRANCHING_STRATEGY.md
# section 5.3 ("Branch-Type Review Context"), which maps branch types to review focus areas.
# CodeRabbit reviews are guided by this reference table for targeted, actionable feedback.

reviews:
  # === Review Workflow Settings ===
  request_changes_workflow: true # Require workflow for requesting changes
  high_level_summary: true # Provide high-level summary in reviews
  poem: false # Disable poem output in reviews
  review_status: true # Show review status in output
  collapse_walkthrough: true # Collapse walkthroughs by default

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

  # === Auto Review Settings ===
  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - "main"
      - "develop"
      - "feature/*"
      - "fix/*"
      - "update/*"

  # === Path Priority System (CRITICAL: DO NOT SKIP) ===
  # This system ensures deterministic path pattern matching with explicit priority/specificity ordering.
  # When a file matches multiple patterns, the pattern with the HIGHEST priority number applies.
  #
  # Priority Scale (1-100):
  # - 90-100: EXACT paths (specific files, exact directory structures)
  #   Example: "agents/agent.md" or "agents/*.agent.js"
  #   Use for: Critical files requiring precise guidance, agent-specific rules
  #
  # - 70-89: SPECIFIC directories (technology-specific folders with clear purpose)
  #   Example: "agents/**", "**/.github/workflows/*.yml", "**/e2e/**"
  #   Use for: Infrastructure, testing, automation with specialized requirements
  #
  # - 50-69: TYPE-in-DIR patterns (language/type-specific patterns in broader directories)
  #   Example: "**/*.{js,ts}", "**/scripts/**/*.sh", "**/*.md"
  #   Use for: Language-specific guidance, test files, documentation
  #
  # - 1-49: GENERAL patterns (broad file types, fallback guidance)
  #   Example: "**/*", "docs/**", "src/**"
  #   Use for: Catch-all rules, generic guidance, project-wide standards
  #
  # Priority Resolution Algorithm:
  # 1. Match file path against all patterns
  # 2. Select pattern(s) with highest priority score
  # 3. If tie, use first-defined pattern (order-dependent fallback)
  # 4. Apply instructions from selected pattern
  #
  # Example: File "agents/labeling.agent.js"
  # - Matches: "agents/**.agent.js" (priority 95), "**/*.js" (priority 60)
  # - Selected: "agents/**.agent.js" (higher priority)
  # - Outcome: Agent-specific JS guidance applied, not generic JS guidance
  #
  # === Path-Specific Review Instructions ===
  # Organized by priority (descending): critical infrastructure → automation → language-specific → general
  path_instructions:
    # === PRIORITY 95: AGENT IMPLEMENTATION FILES (Exact agent-type patterns) ===
    # Agent implementations require strict code quality, testing, and documentation standards
    - path: "agents/*.agent.js"
      instructions: |
        Review all JavaScript agent files:
          - Must start with a valid shebang and detailed header (purpose, usage, author, date).
          - Require comprehensive JSDoc for all functions/classes.
          - Must have a corresponding Jest test file with:
            - Coverage for all agent capabilities and error paths.
            - Mocks for external dependencies.
            - Tests for edge cases and failure scenarios.
            - Linting and type-checking enabled.
          - Ensure agent is referenced in the agent index and spec.

    - path: "agents/*.agent.sh"
      instructions: |
        Review all shell agent files:
          - Must start with a valid shebang and detailed header (purpose, usage, author, date).
          - Require inline comments for all functions/logic.
          - Must have a corresponding Bats test file with:
            - Tests for all script functions and error conditions.
            - Checks for POSIX compliance and portability.
            - Usage of shellcheck for linting.
          - Ensure agent is referenced in the agent index and spec.

    - path: "agents/*.agent.py"
      instructions: |
        Review all Python agent files:
          - Must start with a valid shebang and detailed header (purpose, usage, author, date).
          - Require docstrings for all classes/functions.
          - Must have a corresponding pytest file with:
            - Coverage for all agent logic, including error handling.
            - Use of fixtures/mocks for isolation.
            - Tests for both success and failure cases.
            - Type hints and linting (e.g., mypy, flake8).
          - Ensure agent is referenced in the agent index and spec.

    # === PRIORITY 93: AGENT SPECIFICATION FILES (Exact agent documentation) ===
    # Agent specs and indexes define architecture and capabilities
    - path: "agents/*.agent.md"
      instructions: |
        Review all agent specification files:
          - Each agent spec must include: purpose, inputs/outputs, dependencies, configuration, security, error handling, and logging practices.
          - Reference to related implementation and test files.
          - Example usage and troubleshooting tips.
          - Ensure the spec is up to date and referenced from the agent index.

    - path: "agents/AGENTS.md"
      instructions: |
        Review the main agents index file:
          - Ensure this file lists and describes all agent specs, implementations, and test files in agents/.
          - Confirm each agent is listed with language, description, and test coverage status.
          - Validate cross-references to related workflows, prompts, and documentation.
          - Ensure the file is up to date and easy to navigate.

    - path: "agents/agent.md"
      instructions: |
        Review the agent architecture and integration file:
          - Ensure this file documents agent architecture, capabilities, and integration points.
          - Validate that all agent files (*.agent.js, *.agent.py, *.agent.sh) are referenced and described.
          - Confirm agent lifecycle, error handling, and security practices are documented.
          - Require a section on agent test strategy (unit, integration, workflow).
          - Ensure YAML files are referenced in agent indexes or documentation.
          - Validate header of *.sh, *.js, *.py files start with a shebang.
          - Confirm agent documentation is clear and up-to-date.

    # === PRIORITY 90: AGENT & PROMPT DIRECTORIES (Broad agent infrastructure) ===
    - path: ".github/prompts/**"
      instructions: |
        Review all CodeRabbit and agent prompt files:
          - Ensure prompts are clearly structured, role-focused, and actionable.
          - Verify all instructions are technology-agnostic (no framework/language specifics).
          - Confirm prompts reference authoritative sources (CLAUDE.md, AGENTS.md, standards docs).
          - Check that examples provided are universal and applicable across diverse project types.
          - Validate consistency of terminology and tone across related prompt files.

    - path: "agents/**"
      instructions: |
        Review all agent files (fallback for agent-specific paths):
          - Verify code quality, testing coverage, and error handling patterns.
          - Ensure agent specifications document purpose, inputs, outputs, dependencies, and error conditions.
          - Confirm agent implementations follow coding standards: documentation, linting, type safety.
          - Check that test files exist and cover both success and failure scenarios.
          - Validate cross-references between specs, implementations, and test files are up-to-date.

    # === PRIORITY 88: CRITICAL CONFIGURATION FILES (Custom instructions) ===
    - path: ".github/custom-instructions.md"
      instructions: |
        Review custom-instructions.md:
          - Ensure the file is easy to navigate and up to date with org standards.
          - Ensure the file is a dynamic index of all major Copilot files and instructions.
          - Validate YAML frontmatter for completeness and accuracy.
          - Confirm references to prompts.md, agent.md, AGENTS.md, and all **/.github/instructions/*.instructions.md files.
          - Check for up-to-date cross-references and clear documentation of Copilot usage.

    # === PRIORITY 85: WORKFLOW & TEMPLATE FILES (Critical automation) ===
    - path: "**/.github/workflows/*.yml"
      instructions: |
        Review .github workflows for CI/CD:
          - Check for use of reusable workflow templates and matrix strategies.
          - Validate secrets and environment variables are handled securely.
          - Ensure jobs have clear names and steps are well-commented.
          - Ensure workflows enforce linting, testing, and release policies.
          - Validate required status checks for merges.
          - Check for proper branch and path filters.
          - Confirm workflows are documented, maintainable, and DRY.
          - Check for agent capabilities, tool integration, and test coverage.
          - Ensure agent files reference org-wide standards and indexes.
          - Ensure workflows run markdownlint, test jobs, and security checks as required.

    - path: "**/.github/ISSUE_TEMPLATE/*.md"
      instructions: |
        Review all issue template files:
          - Ensure valid markdown syntax, logical structure, and clear, actionable instructions for users.
          - Validate YAML frontmatter for required fields (title, description, labels, etc.) and template metadata.
          - Check for usage examples, guidance for contributors, and context for when to use each template.
          - Ensure templates are discoverable from documentation, indexes, or contributing guides.
          - Confirm that templates are up to date with current project processes and reference related documentation where relevant.
          - Ensure accessibility (e.g., clear headings, no ambiguous language).

    - path: "**/.github/PULL_REQUEST_TEMPLATE/*.md"
      instructions: |
        Review all pull request template files:
          - Ensure valid markdown syntax, logical structure, and clear, actionable instructions for contributors.
          - Validate YAML frontmatter for required fields and template metadata.
          - Check for usage examples, guidance for contributors, and context for when to use each template.
          - Ensure templates are discoverable from documentation, indexes, or contributing guides.
          - Confirm that templates are up to date with current project processes and reference related documentation where relevant.
          - Ensure accessibility (e.g., clear headings, no ambiguous language).

    - path: "**/.github/DISCUSSION_TEMPLATE/*.yml"
      instructions: |
        Review all discussion template YAML files:
          - Ensure valid YAML syntax, logical structure, and clear, actionable instructions for users.
          - Validate YAML frontmatter for required fields and template metadata.
          - Check for clear instructions on how to use the discussion template and what information is required from the user.
          - Ensure the file is referenced from documentation, indexes, or contributing guides.
          - Confirm that templates are up to date with current project processes and reference related documentation where relevant.
          - Ensure accessibility (e.g., clear field names, no ambiguous language).

    - path: "**/.github/SAVED_REPLIES.md"
      instructions: |
        Review the saved replies index file:
          - Ensure the file links dynamically to all saved replies or lists all available saved reply files.
          - Validate YAML frontmatter and update date/version fields.
          - Check for clarity, brevity, and usefulness of reply summaries and instructions.
          - Ensure the file provides guidance on how to use saved replies and when to use each one.
          - Confirm that replies are referenced from the index and are up to date with current project processes.

    - path: "**/.github/SAVED_REPLIES/**/*.md"
      instructions: |
        Review all saved replies:
          - Ensure all saved replies are valid *.md files, make sense for the project, and are actionable.
          - Validate YAML frontmatter and update date/version fields.
          - Check for clarity, brevity, and usefulness of each reply.
          - Ensure replies are referenced from the saved replies index and are up to date with current project processes.

    # === PRIORITY 80: TEST FILES (Critical quality gates) ===
    - path: "**/e2e/*.{ts,js}"
      instructions: |
        Review Jest tests for agents and blocks:
          - Ensure tests cover accessibility and Full Site Editing (FSE) functionality.
          - Check for reliable, non-flaky tests and clear assertions.
          - Confirm test coverage for critical user flows and edge cases.
          - Validate use of test fixtures, mocks, and snapshot testing where appropriate.

    - path: "**/tests/*.*"
      instructions: |
        Review all test files:
          - Ensure valid syntax, logical structure, and clear instructions for users.
          - All test files must:
            - Start with a valid shebang (if applicable).
            - Contain a detailed header (purpose, author, date, related files).
            - Use clear, descriptive test names and logical structure.
            - Include both positive and negative test cases.
            - Reference the agent or feature under test.
            - Be discoverable from the main agent/test index.
            - Be linted and pass all style checks.
          - Ensure all tests have comprehensive inline documentation.

    # === PRIORITY 75: PROMPT DOCUMENTATION (Prompt conventions & files) ===
    - path: "**/.github/prompts/prompts.md"
      instructions: |
        Review the prompts index file:
          - 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 prompt files are concise and actionable.
          - Ensure each file is a valid prompt with correct YAML frontmatter.
          - Confirm the file is referenced in the prompts index.
          - Validate structure, naming, and documentation.

    # === PRIORITY 65: LANGUAGE/BUILD CONFIGURATION (Package managers) ===
    - path: "**/package.json"
      instructions: |
        Review package.json files:
          - Ensure dependencies are appropriate for project type.
          - Check for security vulnerabilities and outdated packages.
          - Ensure scripts are documented and have clear, descriptive names.
          - Check for presence of postinstall, prepublish, and prepare scripts if needed.
          - Validate repository, bugs, and homepage fields for open source projects.
          - Validate semantic versioning and proper version pinning.
          - Confirm devDependencies vs dependencies separation.
          - Check for unnecessary or duplicate dependencies.
          - Ensure scripts follow org standards (lint, test, build, format, env, etc.).
          - Confirm presence of npm scripts for linting, formatting, testing, and CI.
          - Validate package metadata (name, version, description, author, license).

    - path: "**/composer.json"
      instructions: |
        Review composer.json files:
          - Confirm scripts section is present and used for automation where appropriate.
          - Ensure stability flags (minimum-stability, prefer-stable) are set as needed.
          - Check for extra section for project metadata if relevant.
          - Ensure PHP dependencies are compatible and up-to-date.
          - Check for security best practices in package selection.
          - Verify autoloading configuration and PSR standards compliance.
          - Ensure compatibility with coding standards tools (PHPCS, PHPStan).
          - Check for appropriate development dependencies and version constraints.
          - Validate package metadata (name, description, type, license, authors).

    # === PRIORITY 60: LANGUAGE-SPECIFIC SOURCE CODE (JS/TS, Shell scripts) ===
    - path: "**/*.{js,ts}"
      instructions: |
        Review JavaScript/TypeScript source code:
          - Ensure code is linted and follows project style guides.
          - Validate module syntax is consistent and appropriate for the project.
          - Check for dead code, unused variables, and clear function naming.
          - Verify code enhances functionality without unnecessary complexity.
          - Validate accessibility and performance optimizations.
          - Ensure DOM and runtime compatibility with project targets.
          - Check for code comments, modularity, and maintainability.
          - 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 for automation:
          - Check for POSIX compliance and portability.
          - Validate use of comments and usage/help output in scripts.
          - Ensure functions are modular, reusable, and well-documented.
          - Validate error handling, input validation, and exit codes.
          - Confirm scripts are tested and used consistently across the project.
          - Check for code style, maintainability, and security best practices.
          - Ensure use of `set -euo pipefail` and shebang at the top.

    # === PRIORITY 75: WORKFLOW & PLUGIN DOCUMENTATION (Agentic workflows and plugins) ===
    - path: "workflows/*.md"
      instructions: |
        Review agentic workflow documentation:
          - Ensure workflow structure is clear: phases defined, agent task descriptions explicit.
          - Verify validation scenarios are comprehensive for end-to-end testing.
          - Check that agent capabilities are documented with usage examples.
          - Validate error handling and recovery guidance is present.
          - Ensure UK English terminology and consistency across all workflow descriptions.

    - path: "plugins/*/SKILL.md"
      instructions: |
        Review plugin skill documentation:
          - Ensure plugin purpose, usage, and configuration options are clearly documented.
          - Check for usability guidelines that make the skill accessible to end-users.
          - Verify skill metadata (versioning, dependencies, compatibility) is complete.
          - Validate that code examples and integration scenarios are provided.
          - Ensure accessibility guidelines are followed throughout the documentation.

    # === PRIORITY 95: SPECKIT DOCUMENTATION (Specification and planning files) ===
    - path: ".specify/spec.md"
      instructions: |
        Review specification document quality:
          - Verify specification completeness: user stories, requirements, success criteria all clearly defined.
          - Check that functional requirements (FR-###) and success criteria (SC-###) are testable and measurable.
          - Ensure acceptance scenarios are explicit and independent.
          - Validate that edge cases and constraints are documented.
          - Confirm no implementation details leak into the specification.
          - Check for UK English terminology, WCAG 2.2 AA accessibility, and technology-agnostic guidance.

    - path: ".specify/plan.md"
      instructions: |
        Review implementation plan quality:
          - Verify planning rigor: architecture decisions documented, technical constraints clear.
          - Check that phases are logically structured with clear dependencies.
          - Ensure phase decomposition breaks work into manageable, parallel-friendly chunks.
          - Validate that decision rationale explains trade-offs and risks.
          - Confirm technical context (stack, scope, constraints) is comprehensive.
          - Verify cross-repository applicability is considered for organisation-wide features.

    - path: ".specify/tasks.md"
      instructions: |
        Review task specification quality:
          - Verify task specificity: each task has clear description, file paths, acceptance criteria.
          - Check that parallel markers [P] are accurate and dependencies are identified.
          - Ensure phase organization is logical with clear checkpoints.
          - Validate that task descriptions are actionable and unambiguous.
          - Confirm task interdependencies are documented correctly.
          - Check that task IDs are sequential and unique (T###).

    # === PRIORITY 45: GENERAL DOCUMENTATION (Fallback for all docs) ===
    - path: "**/docs/*.*/*.md"
      instructions: |
        Review all documentation files:
          - Ensure markdown is linted and formatted according to project style guides.
          - Flag illogical folder structures, file naming, or misplaced content.
          - Flag inconsistent naming, unclear section headings, or missing frontmatter.
          - Confirm that documentation is up to date, accurate, and references related files or processes.
          - Ensure accessibility (e.g., heading hierarchy, alt text for images, no ambiguous language).

    # 10. Python Files & Scripts
    - path: "**/*.py"
      instructions: |
        Review Python source and script files:
          - Ensure code follows PEP 8 style guide and project conventions.
          - Check for proper docstrings and inline comments for complex logic.
          - Validate type hints and run mypy/pytype checks.
          - Verify imports are organized and unused imports removed.
          - Check for security best practices (input validation, no hardcoded secrets).
          - Ensure error handling is comprehensive and meaningful.
          - Validate test coverage and pytest compliance.
          - Check for logging and debugging output (avoid print statements in production).

    - path: "**/requirements.txt"
      instructions: |
        Review Python dependency manifest:
          - Ensure pinned versions for reproducible installs.
          - Check for security vulnerabilities in dependencies.
          - Validate package naming and version constraints.
          - Ensure only necessary packages are listed (no unused dependencies).
          - For production, prefer using requirements files over setup.py alone.

    - path: "**/setup.py"
      instructions: |
        Review Python package setup file:
          - Validate package metadata (name, version, description, author, license).
          - Ensure dependencies are declared correctly and versions are appropriate.
          - Check for proper entry points and script registration.
          - Validate classifiers for Python version compatibility.
          - Ensure setup is compatible with modern setuptools and pip standards.

    - path: "**/pyproject.toml"
      instructions: |
        Review Python project configuration:
          - Validate build system and tool configuration (poetry, setuptools, flit).
          - Check project metadata completeness and accuracy.
          - Ensure dependency specifications are correct and consistent.
          - Validate tool configurations (black, flake8, mypy, pytest, etc.).
          - Confirm Python version compatibility and constraints.

    # 11. Configuration Files
    - path: "**/*.toml"
      instructions: |
        Review TOML configuration files:
          - Ensure valid TOML syntax and formatting.
          - Check for consistency with project standards.
          - Validate all required sections are present and correct.
          - Ensure configuration keys match expected schema.
          - Check for security implications (no hardcoded secrets).

    - path: "**/*.yaml"
      instructions: |
        Review YAML configuration files:
          - Ensure valid YAML syntax with proper indentation and structure.
          - Check for consistency with project standards and conventions.
          - Validate required fields and proper nesting.
          - Ensure configuration matches application expectations.
          - Check for security implications (no secrets or sensitive data).

    - path: "**/*.xml"
      instructions: |
        Review XML configuration and data files:
          - Ensure valid XML syntax and well-formed structure.
          - Validate against any defined DTD or schema.
          - Check for proper namespace declarations if used.
          - Ensure special characters are properly escaped.
          - Check for clarity and maintainability of structure.

    # 12. Stylesheets
    - path: "**/*.css"
      instructions: |
        Review CSS stylesheets:
          - Ensure code is linted and follows project style guides (Prettier/Stylelint).
          - Check for proper CSS organization and modularity.
          - Validate browser compatibility and vendor prefixes.
          - Ensure performance optimizations (minimal specificity, no unused styles).
          - Check for accessibility (sufficient color contrast, focus states).
          - Validate CSS custom properties (variables) are well-documented.
          - Ensure dark mode and theme support where applicable.

    - path: "**/*.scss"
      instructions: |
        Review SCSS stylesheets:
          - Ensure valid SCSS syntax and proper nesting.
          - Check for Sass best practices (mixins, variables, functions).
          - Validate proper use of extends, mixins, and variables.
          - Ensure compilation output produces valid CSS.
          - Check for performance optimizations and unnecessary nesting.
          - Validate accessibility and responsive design practices.
          - Ensure color contrast and theme support.

    - path: "**/*.sass"
      instructions: |
        Review Sass stylesheets:
          - Ensure valid Sass syntax without parentheses/semicolons.
          - Check for proper variable and mixin usage.
          - Validate indentation and nesting structure.
          - Ensure compilation produces clean, performant CSS.
          - Check accessibility and browser compatibility.

    # 13. JavaScript Module Variants
    - path: "**/*.mjs"
      instructions: |
        Review module files (.mjs):
          - Ensure code is linted and follows project style guides.
          - Validate module syntax is correct and consistent.
          - Check for compatibility with target environments (Node.js, browsers).
          - Ensure consistent module resolution and import paths.
          - Verify no conflicting module patterns within the file.
          - Check for proper asynchronous operation handling and error handling.

    - path: "**/*.cjs"
      instructions: |
        Review module files (.cjs):
          - Ensure code is linted and follows project style guides.
          - Validate module syntax is correct and consistent with project patterns.
          - Check for compatibility with target Node.js versions.
          - Ensure consistent module patterns across codebase.
          - Verify module patterns are unified (not conflicting with other module variants).
          - Check for proper error handling and security practices.

    # 14. Component & Template Files
    - path: "**/*.astro"
      instructions: |
        Review component template files (.astro):
          - Ensure valid syntax and component structure.
          - Check for proper prop typing and validation.
          - Validate accessibility of rendered HTML output.
          - Ensure performance optimizations are applied.
          - Check for proper component and layout usage and reusability.
          - Validate client-side interactivity patterns.
          - Check for SEO best practices (metadata, structured data).

    - path: "**/*.mdx"
      instructions: |
        Review MDX files (Markdown with component integration):
          - Ensure valid markdown syntax and component usage.
          - Check for proper component imports and configuration.
          - Validate accessibility of interactive components.
          - Ensure consistent formatting with project markdown style.
          - Check for frontmatter completeness and accuracy.
          - Validate code blocks and syntax highlighting.
          - Check for clarity and usefulness for intended audience.

    - path: "**/*.html"
      instructions: |
        Review HTML files:
          - Ensure valid HTML5 syntax and semantic markup.
          - Check for accessibility (ARIA labels, alt text, heading hierarchy).
          - Validate proper meta tags and SEO optimization.
          - Ensure responsive design and mobile compatibility.
          - Check for security (no XSS vulnerabilities, proper escaping).
          - Validate proper use of forms, inputs, and validation.
          - Check for performance optimization (defer scripts, lazy load images).

    # 15. Data & Structured Files
    - path: "**/*.csv"
      instructions: |
        Review CSV data files:
          - Ensure proper CSV formatting and escaping.
          - Validate consistent column structure and headers.
          - Check for data integrity and validity.
          - Ensure no sensitive or private data is committed.
          - Validate character encoding (UTF-8 preferred).
          - Check for proper line endings and formatting.

    - path: "**/*.json"
      instructions: |
        Review JSON data and configuration files:
          - Ensure valid JSON syntax (no trailing commas, proper quoting).
          - Check for consistency with JSON Schema if defined.
          - Validate all required fields are present and correct.
          - Ensure proper formatting and indentation.
          - Check for security (no hardcoded secrets or credentials).
          - Validate performance impact (avoid very large JSON files).
          - Ensure compatibility with schema versioning if versioned.

    # 16. Other Configuration & Meta Files
    - path: "**/.editorconfig"
      instructions: |
        Review EditorConfig files:
          - Ensure valid EditorConfig syntax and format.
          - Check for consistency with project style guides.
          - Validate supported file extensions are covered.
          - Ensure indent style and size match project standards.
          - Check for end-of-line and charset consistency.

    - path: "**/.env*"
      instructions: |
        Review environment files (DO NOT COMMIT):
          - ⚠️ WARNING: .env files should NEVER be committed to version control.
          - Check that sensitive data is properly excluded via .gitignore.
          - Document required environment variables in example files (.env.example).
          - Ensure .env files are listed in .gitignore with patterns.
          - Validate example file includes all required variables with safe defaults.

    - path: "**/.gitignore"
      instructions: |
        Review .gitignore files:
          - Ensure all generated, temporary, and sensitive files are ignored.
          - Check for unnecessary broad patterns that exclude needed files.
          - Validate project-specific ignore rules are present.
          - Check for consistency across similar project types.
          - Ensure node_modules, build artifacts, and .env files are ignored.

    - path: "**/Makefile"
      instructions: |
        Review Makefile automation:
          - Ensure proper Makefile syntax and valid targets.
          - Check for clear target names and descriptions.
          - Validate recipes use tabs (not spaces) for indentation.
          - Ensure .PHONY declarations for non-file targets.
          - Check for proper error handling and exit codes.
          - Validate scripts are portable across Unix-like systems.
          - Ensure documentation of available targets.

# === GitHub Labels Reference ===
# This section documents the canonical labeling system for all PRs and issues.
# Labels are automatically applied by the labeling workflow based on branch patterns and file changes.
# See .github/labeler.yml for the complete mapping rules.

# Status Labels (applied automatically on PR creation)
# - status:needs-review: Assigned to PRs from feature, fix, docs, chore, and other development branches
# - status:approved: Applied when PR receives required approvals
# - status:in-progress: Applied to actively-being-worked PRs
# - status:blocked: Applied when PR has unresolved merge conflicts or CI failures
# - status:ready-to-merge: Applied when PR is green, approved, and ready for merge

# Type Labels (determined by branch prefix)
# - type:feature: PRs from 'feat/*' branches (new features and enhancements)
# - type:bug: PRs from 'fix/*' or 'hotfix/*' branches (bug fixes)
# - type:documentation: PRs from 'docs/*' branches (documentation updates)
# - type:chore: PRs from 'chore/*', 'build/*', or 'ci/*' branches (maintenance and tooling)
# - type:refactor: PRs from 'refactor/*' branches (code refactoring without feature changes)
# - type:test: PRs from 'test/*' branches (test additions and improvements)
# - type:performance: PRs from 'perf/*' branches (performance optimisations)
# - type:design: PRs from 'design/*' branches (design system and UI updates)
# - type:a11y: PRs from 'a11y/*' branches (accessibility improvements per WCAG 2.2 AA)
# - type:qa: PRs from 'qa/*' branches (quality assurance and testing)

# Priority Labels (determined by branch prefix)
# - priority:critical: Assigned to hotfix branches (high-urgency fixes)
# - priority:normal: Assigned to standard feature, fix, docs, and chore branches
# - priority:low: Assigned to non-urgent maintenance and documentation PRs

# Area/Component Labels (determined by changed file paths)
# - area:block-editor: Changes to WordPress block editor code (src/blocks/**, src/block-editor/**, block.json)
# - area:theme: Changes to WordPress theme (theme.json, templates/**, patterns/**, parts/**, theme/**)
# - area:ci: Changes to CI/CD and GitHub Actions (.github/workflows/**, .github/actions/**, ci/**)
# - area:documentation: Changes to markdown and docs (**.md, docs/**, README.md)
# - area:tests: Changes to test files (tests/**, **.test.*, **.spec.*, __tests/**)
# - area:scripts: Changes to shell scripts (scripts/**, **.sh, **.bash)
# - area:assets: Changes to assets and images (assets/**, images/**, **.png, **.jpg, **.svg)
# - area:woocommerce: Changes to WooCommerce integration (woocommerce/**, woocommerce*.css/php/js)
# - area:feature: Changes to feature-related code

# Language Labels (determined by changed file types)
# - lang:php: PRs modifying PHP files (**.php, composer.json, phpunit.xml)
# - lang:js: PRs modifying JavaScript/TypeScript (**.js, **.jsx, **.ts, **.tsx, package.json, tsconfig.json)
# - lang:css: PRs modifying stylesheets (**.css, **.scss, **.sass, **.less)

# Release and Changelog Labels (managed by labeling agent)
# - meta:changelog-required: Applied when PR modifies user-facing code and requires a changelog entry
# - meta:skip-changelog: Applied to internal-only PRs that do not require changelog entries
# - release:major, release:minor, release:patch: Version impact for release automation

# === Pull Request Description Template Standards ===
# All PRs must follow the standard template structure defined in .github/PULL_REQUEST_TEMPLATE/.
# Required sections:
# 1. Linked Issues: List related issues using closes/fixes/relates to syntax (e.g., "Closes #123")
# 2. Changelog: Document user-facing changes using Keep a Changelog format
#    - Categories: Added, Changed, Fixed, Removed
#    - Format: User-facing notes only; internal-only PRs use skip-changelog label
# 3. Checklist (Global DoD / PR): Verification that AC, tests, accessibility, docs, security, and reviews are complete
#    - All items must be checked off (no unchecked items)
#    - At least one item must be explicitly checked to validate completion

# PR Template Selection (by branch type):
# - feat/* branches: Use 'Feature PR' template (.github/PULL_REQUEST_TEMPLATE/pr_feature.md)
# - fix/* branches: Use 'Bug Fix PR' template (.github/PULL_REQUEST_TEMPLATE/pr_bug.md)
# - docs/* branches: Use 'Documentation PR' template (.github/PULL_REQUEST_TEMPLATE/pr_docs.md)
# - chore/* branches: Use 'Chore PR' template (.github/PULL_REQUEST_TEMPLATE/pr_chore.md)
# - refactor/* branches: Use 'Refactor PR' template (.github/PULL_REQUEST_TEMPLATE/pr_refactor.md)
# - ci/* branches: Use 'CI/CD PR' template (.github/PULL_REQUEST_TEMPLATE/pr_ci.md)
# - release/* branches: Use 'Release PR' template (.github/PULL_REQUEST_TEMPLATE/pr_release.md)
# - hotfix/* branches: Use 'Hotfix PR' template (.github/PULL_REQUEST_TEMPLATE/pr_hotfix.md)
# - perf/* branches: Use 'Performance PR' template (.github/PULL_REQUEST_TEMPLATE/pr_feature.md)
# - *.deps branches: Use 'Dependency Update PR' template (.github/PULL_REQUEST_TEMPLATE/pr_dep_update.md)

# PR Validation Rules:
# - All required sections must be completed (no placeholder comments left)
# - Changelog section must contain at least one user-facing entry OR skip-changelog label applied
# - Checklist must have ALL items checked (validation regex requires no unchecked boxes and at least one checked)
# - Linked issues must use proper GitHub syntax (Closes #, Fixes #, Relates to #)
# - CI must be green (all required status checks passing)
# - Code review approvals must be obtained before merge
# - No merge conflicts or unresolved review threads

# === Issue Description Template Standards ===
# All new issues must be created using one of the defined templates in .github/ISSUE_TEMPLATE/.
# Required sections vary by issue type but generally include:
# 1. Description/Summary: Clear, concise statement of the issue or request
# 2. Acceptance Criteria (if applicable): What success looks like
# 3. Steps to Reproduce (for bugs): Step-by-step instructions
# 4. Expected vs Actual Behaviour (for bugs): Comparison of expected vs actual outcome
# 5. Context/Environment: Relevant system, browser, WordPress, or PHP versions
# 6. Additional Context: Screenshots, code snippets, logs, or related references

# Issue Template Selection (by type):
# - Bug: Use '🐛 Bug report' template (.github/ISSUE_TEMPLATE/02-bug.md)
#   - Labels: status:needs-triage, priority:normal, area:core
#   - Sections: Description, Reproduce Steps, Expected Behaviour, Screenshots, Environment, Device/Browser, Additional Context
#   - Validation: DoR (Definition of Ready) and DoD (Definition of Done) checklists
# - Feature Request: Use '✨ Feature request' template (.github/ISSUE_TEMPLATE/03-feature.md)
#   - Labels: status:needs-triage, priority:normal, area:feature
#   - Sections: Description, Problem Statement, Proposed Solution, Acceptance Criteria, Additional Context
# - Task: Use '📝 Task' template (.github/ISSUE_TEMPLATE/01-task.md)
#   - Labels: status:needs-triage, priority:normal, type:task
#   - Sections: Description, Acceptance Criteria, Definition of Done
# - Epic: Use '🎯 Epic' template (.github/ISSUE_TEMPLATE/05-epic.md)
#   - Labels: status:needs-triage, priority:normal, type:epic
#   - Sections: Vision, Goals, Acceptance Criteria, Related Issues
# - Documentation: Use '📚 Documentation' template (.github/ISSUE_TEMPLATE/20-documentation.md)
#   - Labels: status:needs-triage, priority:normal, area:documentation
#   - Sections: Title, Description, Target Audience, Content Outline, Acceptance Criteria
# - Accessibility (a11y): Use '♿ Accessibility' template (.github/ISSUE_TEMPLATE/14-a11y.md)
#   - Labels: status:needs-triage, priority:normal, type:a11y
#   - Sections: Description, WCAG Criteria, Current Behaviour, Expected Behaviour, Acceptance Criteria
# - Performance: Use '⚡ Performance' template (.github/ISSUE_TEMPLATE/12-performance.md)
#   - Labels: status:needs-triage, priority:normal, type:performance
#   - Sections: Description, Current Metrics, Target Metrics, Acceptance Criteria
# - Security: Use '🔒 Security' template (.github/ISSUE_TEMPLATE/15-security.md)
#   - Labels: status:needs-triage, priority:critical, type:security
#   - Sections: Vulnerability Description, Impact Assessment, Reproduction Steps, Remediation, Acceptance Criteria
# - Code Review: Use '👀 Code Review' template (.github/ISSUE_TEMPLATE/23-code-review.md)
#   - Labels: status:needs-review, type:review
#   - Sections: Code Location, Review Focus, Acceptance Criteria
# - Testing/Coverage: Use '🧪 Testing Coverage' template (.github/ISSUE_TEMPLATE/12-testing-coverage.md)
#   - Labels: status:needs-triage, priority:normal, type:test
#   - Sections: Coverage Gap Description, Test Scenarios, Acceptance Criteria
# - Maintenance: Use '🔧 Maintenance' template (.github/ISSUE_TEMPLATE/19-maintenance.md)
#   - Labels: status:needs-triage, priority:normal, type:maintenance
#   - Sections: Description, Current State, Desired State, Acceptance Criteria
# - Build/CI: Use '🏗️ Build/CI' template (.github/ISSUE_TEMPLATE/10-build-ci.md)
#   - Labels: status:needs-triage, priority:normal, area:ci
#   - Sections: Description, Error Output, Steps to Reproduce, Acceptance Criteria
# - Refactoring: Use '♻️ Code Refactor' template (.github/ISSUE_TEMPLATE/09-code-refactor.md)
#   - Labels: status:needs-triage, priority:normal, type:refactor
#   - Sections: Current Implementation, Refactoring Goals, Acceptance Criteria, Risk Assessment

# Issue Validation Rules:
# - Issue type must be selected (determines template and labels)
# - All required template sections must be filled (no placeholder comments)
# - Labels must include: one status label (needs-triage), one type label, and optionally area labels
# - Title must be descriptive and follow naming conventions (e.g., "[Bug]", "[Feature]", "[Docs]")
# - Description must be clear and actionable
# - Acceptance Criteria must be specific and measurable
# - Environment/context details provided for bugs and performance issues

# === Label Automation Workflow ===
# The CI/CD pipeline automatically applies labels based on:
# 1. Branch naming patterns (status:needs-review, type:* labels)
# 2. Changed file paths (area:* and lang:* labels)
# 3. PR description content (meta:changelog-required vs meta:skip-changelog)
# 4. Issue type selection (status:needs-triage, type:*, area:* labels)
#
# Manual label adjustments may be made by maintainers during triage or review.
# Labels are used for:
# - Automation routing (workflow triggers, notifications)
# - Release categorisation (changelog generation, version bumping)
# - Project board organisation and filtering
# - Metrics and reporting (contribution types, area focus)

early_access: true