name: 📝 Agent Instructions Audit

on:
  pull_request:
    types: [opened, ready_for_review, synchronize]
    paths-ignore:
      - "docs/**"
      - ".changeset/**"
      - ".server-changes/**"
      - "**/*.md"

concurrency:
  group: agent-instructions-audit-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  audit:
    # Set the ENABLE_CLAUDE_CODE repository variable to 'false' to turn off Claude
    # jobs; leave it unset (the default) to keep them enabled.
    if: >-
      vars.ENABLE_CLAUDE_CODE != 'false' &&
      github.event.pull_request.draft == false &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: warp-ubuntu-latest-x64-2x
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Run Claude Code
        id: claude
        uses: anthropics/claude-code-action@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1.0.157
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          use_sticky_comment: true
          allowed_bots: "devin-ai-integration[bot]"

          claude_args: |
            --max-turns 25
            --model claude-opus-4-8
            --allowedTools "Read,Glob,Grep,Bash(git diff:*)"

          prompt: |
            You are reviewing a PR to check whether any agent instruction files need updating.

            In this repo:
            - Root shared agent guidance lives in `AGENTS.md`.
            - Root `CLAUDE.md` is only a Claude Code adapter that imports `AGENTS.md`.
            - Subdirectories may still have scoped `CLAUDE.md` files.
            - `.claude/rules/` contains additional Claude Code guidance.

            ## Your task

            1. Run `git diff origin/main...HEAD --name-only` to see which files changed in this PR.
            2. For each changed directory, check the applicable instruction files: root `AGENTS.md`, any `CLAUDE.md` in that directory or a parent directory, and relevant `.claude/rules/` files.
            3. Determine if any instruction file should be updated based on the changes. Consider:
               - New files/directories that aren't covered by existing documentation
               - Changed architecture or patterns that contradict current agent guidance
               - New dependencies, services, or infrastructure that agents should know about
               - Renamed or moved files that are referenced in an instruction file
               - Changes to build commands, test patterns, or development workflows

            ## Response format

            If NO updates are needed, respond with exactly:
            ✅ Agent instruction files look current for this PR.

            If updates ARE needed, respond with a short list:
            📝 **Agent instruction updates suggested:**
            - `AGENTS.md`: [what should be added/changed]
            - `path/to/CLAUDE.md`: [what should be added/changed]
            - `.claude/rules/file.md`: [what should be added/changed]

            Keep suggestions specific and brief. Only flag things that would actually mislead agents in future sessions.
            Do NOT suggest updates for trivial changes (bug fixes, small refactors within existing patterns).
            Do NOT suggest creating new CLAUDE.md files - only updates to existing instruction files.