From dc82525b50a8a806ed5d29e4e4b70f31c6540e0a Mon Sep 17 00:00:00 2001
From: Scott Converse <scott.converse@gmail.com>
Date: Mon, 2 Nov 2026 13:04:59 -0700
Subject: [PATCH] CI: skip the heavy jobs on docs-only changes

A new "changes" job lists the changed files. When every file is docs, the
other jobs skip. Skipped jobs report success, so required checks still pass.
Code, workflow, skill and prompt files still run the full CI.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cb4a038..a5485ed 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,7 +7,47 @@ on:
     branches: [main]
 
 jobs:
+  # Docs-only changes start no CI run (docs get push, merge and publish only).
+  changes:
+    name: Detect code changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      code: ${{ steps.diff.outputs.code }}
+    steps:
+      - id: diff
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT: ${{ github.event_name }}
+          PR: ${{ github.event.pull_request.number }}
+          BEFORE: ${{ github.event.before }}
+          SHA: ${{ github.sha }}
+        run: |
+          # code=false only when every changed file is docs. Anything unknown counts as code.
+          docs_re='(\.(md|mdx|rst|docx|pdf)$)|(^|/)(LICENSE|NOTICE)(\.[^/]*)?$|^docs/.*\.(png|jpe?g|svg|gif|webp|html|css)$'
+          keep_re='(^|/)SKILL\.md$|(^|/)(skills|agents|commands|prompts|references)/|^\.claude/'
+          files=""
+          if [ "$EVENT" = pull_request ] || [ "$EVENT" = pull_request_target ]; then
+            files=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/files" --paginate --jq '.[].filename') || files=""
+          elif [ "$EVENT" = push ] && [ -n "$BEFORE" ] && [ "$BEFORE" != 0000000000000000000000000000000000000000 ]; then
+            files=$(gh api "repos/$GITHUB_REPOSITORY/compare/$BEFORE...$SHA" --jq 'if (.files | length) >= 300 then empty else .files[].filename end') || files=""
+          fi
+          code=true
+          if [ -n "$files" ]; then
+            other=$(printf '%s\n' "$files" | grep -Ev "$docs_re" || true)
+            kept=$(printf '%s\n' "$files" | grep -E "$docs_re" | grep -E "$keep_re" || true)
+            if [ -z "$other" ] && [ -z "$kept" ]; then code=false; fi
+          fi
+          echo "Changed files:"; printf '%s\n' "$files" | head -50
+          echo "code=$code" | tee -a "$GITHUB_OUTPUT"
+
   tests:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository