feat(phase-3): pre-commit hooks (Option B — GitHub Actions unavailable)

GitHub Actions cannot run on this private repo under the current org
plan. Adding pre-commit hooks as local enforcement until the repo goes
public or the org plan is upgraded.

- .githooks/pre-commit — runs on every `git commit` touching skills,
  evals, or schemas:
    1. scripts/validate_skills.py (frontmatter, line count, routing
       refs, forbidden URLs, index.json paths)
    2. evals.harness.validate_prompts (prompt YAML schema)
    3. mock Layer 1 eval (all 6 skills must pass)
    4. mock Layer 2 eval (all 6 skills must pass)
  Skips entirely if no relevant files are staged.
- scripts/install-hooks.sh — one-time setup: sets core.hooksPath to
  .githooks and marks the hook executable. Run after cloning.
- CONTRIBUTING.md — added install step to Quick start + note on
  automatic hook enforcement in PR checklist.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: george-bafaloukas-forgerock

.githooks/pre-commit

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Pre-commit hook: validate skill content + run mock evals.
+# Installed via: git config core.hooksPath .githooks
+# Or: scripts/install-hooks.sh
+#
+# Skips checks if no relevant files changed.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# Detect which files are staged
+STAGED=$(git diff --cached --name-only)
+
+SKILLS_CHANGED=$(echo "$STAGED" | grep -E \
+  "^plugins/ping-identity/skills/|^plugins/ping-identity/references/index\.json|^shared/schemas/|^scripts/validate_skills\.py" \
+  || true)
+
+EVALS_CHANGED=$(echo "$STAGED" | grep -E \
+  "^evals/|^plugins/ping-identity/skills/" \
+  || true)
+
+if [ -z "$SKILLS_CHANGED" ] && [ -z "$EVALS_CHANGED" ]; then
+  exit 0
+fi
+
+echo "🔍 Running pre-commit checks..."
+
+# ── 1. Skill content validator ──────────────────────────────────────────────
+if [ -n "$SKILLS_CHANGED" ]; then
+  echo "  → Validating skill content..."
+  if ! python3 scripts/validate_skills.py --root .; then
+    echo ""
+    echo "❌ Skill validation failed. Fix the errors above before committing."
+    exit 1
+  fi
+fi
+
+# ── 2. Prompt YAML schema validator ─────────────────────────────────────────
+if [ -n "$EVALS_CHANGED" ]; then
+  echo "  → Validating eval prompt sets..."
+  if ! python3 -m evals.harness.validate_prompts 2>&1 | grep -v "^SKIP"; then
+    echo ""
+    echo "❌ Eval prompt validation failed. Fix the errors above before committing."
+    exit 1
+  fi
+
+  echo "  → Running Layer 1 mock eval..."
+  if ! python3 -m evals.harness.run_eval --adapter mock --layer 1; then
+    echo ""
+    echo "❌ Layer 1 eval failed. All skills must pass before committing."
+    exit 1
+  fi
+
+  echo "  → Running Layer 2 mock eval..."
+  if ! python3 -m evals.harness.run_eval --adapter mock --layer 2; then
+    echo ""
+    echo "❌ Layer 2 eval failed. All skills must pass before committing."
+    exit 1
+  fi
+fi
+
+echo "✅ All pre-commit checks passed."

CONTRIBUTING.md

@@ -10,7 +10,10 @@ This repo ships the 6 umbrella skills for the Ping Identity agent skills package
 git clone https://github.com/pingidentity/agent-plugins.git
 cd agent-plugins
 
-# Validate everything
+# Install pre-commit hooks (run once after cloning)
+bash scripts/install-hooks.sh
+
+# Validate everything manually
 python3 scripts/validate_skills.py --root .
 
 # Run evals (mock, no API key needed)
@@ -28,7 +31,8 @@ All three commands must exit 0 before you open a PR.
 
 ## PR checklist
 
-Before opening a PR, confirm every item:
+The pre-commit hook (`bash scripts/install-hooks.sh`) runs the first four checks automatically on every `git commit`. Confirm all items before opening a PR:
+
 
 - [ ] `python3 scripts/validate_skills.py --root .` exits 0
 - [ ] `python3 -m evals.harness.validate_prompts` exits 0

scripts/install-hooks.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Install shared Git hooks for this repo.
+# Run once after cloning: bash scripts/install-hooks.sh
+set -euo pipefail
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+git -C "$REPO_ROOT" config core.hooksPath .githooks
+chmod +x "$REPO_ROOT/.githooks/pre-commit"
+echo "✅ Git hooks installed. Pre-commit checks will run on every commit."