Add pre-commit lockfile recompilation guard for workflow markdown changes

.githooks/pre-commit

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+mapfile -t staged_files < <(git diff --cached --name-only --diff-filter=ACMR)
+staged_workflow_md_files=()
+for staged_file in "${staged_files[@]}"; do
+	if [[ "$staged_file" =~ ^\.github/workflows/.*\.md$ ]]; then
+		staged_workflow_md_files+=("$staged_file")
+	fi
+done
+if [ "${#staged_workflow_md_files[@]}" -eq 0 ]; then
+	exit 0
+fi
+
+echo "Detected staged workflow markdown changes:"
+printf '%s\n' "${staged_workflow_md_files[@]}"
+echo "Running make recompile..."
+if ! make recompile; then
+	echo "Pre-commit hook failed while recompiling workflows."
+	echo "Fix the recompilation errors, then retry the commit."
+	exit 1
+fi
+
+changed_lock_files=()
+for workflow_md_file in "${staged_workflow_md_files[@]}"; do
+	lock_file="${workflow_md_file%.md}.lock.yml"
+	if [ -f "$lock_file" ] && ! git diff --quiet -- "$lock_file"; then
+		changed_lock_files+=("$lock_file")
+	fi
+done
+
+if [ "${#changed_lock_files[@]}" -gt 0 ]; then
+	echo "Workflow lock files are out of sync after recompilation."
+	echo "Stage the updated .lock.yml files and commit again."
+	printf '%s\n' "${changed_lock_files[@]}"
+	exit 1
+fi

CONTRIBUTING.md

@@ -22,6 +22,16 @@ The Dev Container installs all required dependencies and runs `make deps` automa
 
 If you encounter errors about Node.js or Go versions when running `make deps` or other build commands, this is a sign that you are not using the Dev Container. Please switch to a Dev Container or Codespace environment.
 
+### Install Git Pre-Commit Hooks
+
+After opening the repository locally, install the project git hooks once (including in Dev Containers/Codespaces):
+
+```bash
+make install-git-hooks
+```
+
+The pre-commit hook automatically runs `make recompile` when staged changes include workflow markdown files under `.github/workflows/*.md`. If recompilation updates any corresponding `.lock.yml` files, the commit is blocked until you stage those lock file updates.
+
 ## 🤖 How Development Works
 
 GitHub Agentic Workflows is developed by a core team using agentic development — primarily GitHub Copilot coding agent and local coding agents. This means:
@@ -489,6 +499,14 @@ Quick reference:
 - `make test` - Full test suite (~30s)
 - `make agent-finish` - Complete validation before committing
 
+### Workflow Editing Checklist
+
+When you edit files under `.github/workflows/*.md`:
+
+- [ ] Run `make recompile` (or rely on the installed pre-commit hook to run it for you)
+- [ ] Stage updated `.lock.yml` files generated by recompilation
+- [ ] Run `make agent-report-progress` before opening/updating a PR
+
 ### Compiling against a different actions repository
 
 When working on changes that span both `github/gh-aw` and `github/gh-aw-actions`, you can compile workflows against a fork or branch of the actions repository:

Makefile

@@ -691,6 +691,13 @@ sync-action-scripts:
 	@chmod +x actions/setup-cli/install.sh
 	@echo "✓ Action scripts synced successfully"
 
+.PHONY: install-git-hooks
+install-git-hooks:
+	@git config core.hooksPath .githooks
+	@test -f .githooks/pre-commit || { echo "Error: .githooks/pre-commit not found"; exit 1; }
+	@chmod +x .githooks/pre-commit
+	@echo "✓ Git hooks installed (core.hooksPath=.githooks)"
+
 # Recompile all workflow files
 .PHONY: recompile
 recompile: build
@@ -829,6 +836,7 @@ help:
 	@echo "  install          - Install binary locally"
 	@echo "  sync-action-pins - Sync actions-lock.json from .github/aw to pkg/actionpins/data and pkg/workflow/data (runs automatically during build)"
 	@echo "  sync-action-scripts - Sync install-gh-aw.sh to actions/setup-cli/install.sh (runs automatically during build)"
+	@echo "  install-git-hooks - Install repository git hooks (sets core.hooksPath=.githooks)"
 	@echo "  update           - Update GitHub Actions and workflows, sync action pins, and rebuild binary"
 	@echo "  fix              - Apply automatic codemod-style fixes to workflow files (depends on build)"
 	@echo "  recompile        - Recompile all workflow files (runs init, depends on build)"