From 0dd9d54d390c4fd1498a10100a4c50caa4c43f54 Mon Sep 17 00:00:00 2001
From: mrjf <mrjf@github.com>
Date: Wed, 27 May 2026 09:14:22 -0700
Subject: [PATCH 1/2] ci: check gh-aw workflow locks

---
 .github/workflows/gh-aw-lock-check.yml | 47 ++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 .github/workflows/gh-aw-lock-check.yml

diff --git a/.github/workflows/gh-aw-lock-check.yml b/.github/workflows/gh-aw-lock-check.yml
new file mode 100644
index 00000000..f54262d7
--- /dev/null
+++ b/.github/workflows/gh-aw-lock-check.yml
@@ -0,0 +1,47 @@
+name: gh-aw lock check
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/*.md"
+      - ".github/workflows/**/*.md"
+      - ".github/workflows/*.lock.yml"
+      - ".github/workflows/**/*.lock.yml"
+      - ".github/workflows/gh-aw-lock-check.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/*.md"
+      - ".github/workflows/**/*.md"
+      - ".github/workflows/*.lock.yml"
+      - ".github/workflows/**/*.lock.yml"
+      - ".github/workflows/gh-aw-lock-check.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify gh-aw locks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install gh-aw
+        uses: github/gh-aw-actions/setup-cli@d3abfe96a194bce3a523ed2093ddedd5704cdf62 # v0.74.4
+        with:
+          version: v0.74.4
+
+      - name: Verify compiled workflows are current
+        run: |
+          gh aw compile --no-check-update
+
+          if [ -n "$(git status --porcelain -- .github/workflows)" ]; then
+            echo "::error::gh-aw generated workflow files are stale. Run 'gh aw compile' and commit the result."
+            git status --short -- .github/workflows
+            git diff -- .github/workflows
+            exit 1
+          fi

From 3f59af71777837902a1895e76f14d6b8563926fd Mon Sep 17 00:00:00 2001
From: mrjf <mrjf@github.com>
Date: Wed, 27 May 2026 09:18:20 -0700
Subject: [PATCH 2/2] docs: add gh-aw guidance for agents

---
 AGENTS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..b5828f2b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,12 @@
+# AGENTS.md
+
+## Agentic Workflow Sources
+
+When changing GitHub Agentic Workflow source files under
+`.github/workflows/`, run `gh aw compile` before committing and
+include the regenerated `.lock.yml` files in the same change.
+
+This applies to workflow markdown files such as `.github/workflows/*.md`
+and shared workflow markdown such as `.github/workflows/shared/*.md`.
+The `gh-aw lock check` CI job runs the same compile step and fails if
+the generated workflow files are stale.