feat: add reusable workflow that keeps AGENTS.md accurate in the PR that changed it

[FilipMasar]

Fixes apify/integrations-team#98

What

A new reusable workflow that keeps AGENTS.md accurate.

When a PR makes AGENTS.md wrong, a bot commits the fix to that PR's own branch and comments what it changed.

Why

We already have claude-md-maintenance.yml, which runs after merge and opens its own PR. Nobody merges those PRs, so the doc goes stale anyway. Fixing the doc in the PR that broke it means the change lands together with the code.

How it works

1. Someone opens or updates a PR.
2. A shell gate decides whether to run. It skips drafts, forks, bot commits, and PRs where the branch has already moved on. If the repo doesn't use the standard layout, the run fails and the error says how to fix it.
3. Claude reads what the PR changed and compares it against the current AGENTS.md. It edits the file only if the PR made something in it wrong — a renamed script, a removed dependency, a new top-level directory.
4. If the file changed, the bot commits it to the PR branch (signed) and posts a comment saying what it changed and why.
5. If nothing was wrong, it does nothing. Its reasoning still goes into the run summary, so a quiet run is not a silent one.

The agent only reads and writes files. Committing and commenting are ordinary steps after it finishes, so when something breaks it's clear which part did it.

How to use it

Nothing happens until a repo opts in — this is workflow_call only. Onboarding is two steps.

1. The layout. Two regular files in the repo root, neither a symlink.

AGENTS.md — the whole doc
CLAUDE.md — first line is a pointer to AGENTS.md

@AGENTS.md

2. The workflow file.

name: Keep AGENTS.md accurate

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: write
  pull-requests: write

jobs:
  update-agents-md:
    uses: apify/workflows/.github/workflows/agents-md-maintenance.yml@main
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.YOUR_ANTHROPIC_API_KEY }}

For our teams integration repos, both steps are in apify/integrations-team#113

Tested various scenarios in a throwaway repo https://github.com/apify/claude-md-lab

[apify-factory]

Looks good, nothing blocking.

[drobnikj]

The ticket https://github.com/apify/integrations-team/issues/98 described new flow differently with "human in loop step", where user approve by button or whatever that wants to update the files. Why you decide to do it this way?

Left some comments.

[drobnikj]

Suggestion: this posts a fresh comment per bot commit, so a PR that keeps changing shape accumulates one per push. Editing a single sticky comment instead would keep the thread readable.

[drobnikj]

Note: should it to create the file if does not exist?

[FilipMasar]

I was thinking about it but it creates many cases and handeling them would blow up this workflow unnecessarily I think. So I would just keep it simple and say that the correct layout is prerequisite (it is one of the gate in gate step)

[drobnikj]

Looks good, nothing blocking.

We need to update the PR reviewer he is currently too nice 😄

[JanHranicky]

The prompt looks good to me. Agree with Kuba comments, would preffer a human in the loop, that would approve the changes somehow.

Some PRs tend to change with a lot of pushes fixing review stuff etc. This action would trigger on every push right?

Would it make sense to have the action post a single comment and another action would watch the responds to that comment? This way a human could apply/decline the changes or re-request it the action run.

[FilipMasar]

The ticket apify/integrations-team#98 described new flow differently with "human in loop step", where user approve by button or whatever that wants to update the files. Why you decide to do it this way?

Yes, I deviated from the issue a bit and forgot to mention it in the PR description 😬

1. If we want button trigger, then we need to create a github app - github workflow can't do it natively. Feels like overkill to me for this.
2. Another trigger options are labels, special /slash comments, or checkbox checking in bot comment (I testing that one)
3. I didn't like any of those. The UX was 🤮
4. Then I was thinking developers should not really think about having to trigger it. It should watch the PR all the time and if there is something to update, update it
5. It runs on every push (to ready for review PR, if we use drafts it won't run). Do you think its going to be an issue? It doesn't post anything so it won't bother us if there weren't any changes. Which I don't expect them to be so many.
6. Also I made it so everytime it changes AGENTS.md and commits, it creates new comment. It doesn't edit the previous one. The reason for it is the history. I feel like its more transparent to see what it does.

I would just keep it and see how it works for us in real PRs. Then change anything that is bothering us. What do you think? @drobnikj @JanHranicky