.github/workflows — AI Agent Guide

Status: Active | Last Updated: July 2026

Purpose

GitHub Actions workflow definitions for CI/CD, security, multi-agent infrastructure, documentation, benchmarks, PR automation, and repository maintenance. 37 workflows total.

Workflow Inventory

Core CI/CD

Agent & PR Infrastructure

Community & Release Automation

Documentation

Repository Health

Orchestration

Gemini AI

Critical Design Decisions

• Workflows declare a top-level permissions: block. 31 of 37 do today (12 of them permissions: {}); the 6 without one inherit the repository default and need a block.
• astral-sh/setup-uv is the standard for all UV installations, pinned by full commit SHA with the release named in a trailing comment.
• CI runs Ubuntu/Python 3.11 plus Windows/Python 3.11 on PRs. Main pushes run the full suite on Ubuntu and macOS across Python 3.11–3.14, plus the blocking Windows portability contract across Python 3.11–3.13.
• Ruff, ty, import layering, package build, dependency validation, and the primary test/coverage gates are authoritative. Optional PR commentary and benchmark/health reporting jobs remain informational.
• Documented coverage floor is 60% (fail_under in pyproject.toml). The Unix unit matrix and coverage-gate jobs pass --cov-fail-under=60 and fail on breach. The Windows portability matrix is a scoped platform contract, so it emits JUnit evidence without pretending to measure repository-wide coverage. release.yml uses --cov-fail-under=60. Default local uv run pytest omits --cov for speed.
• Jules PRs are exempt from stale closure (90d stale, 14d close)

AI Agent Guidelines

Safe to Read

• Any workflow file to understand triggers, jobs, and permissions
• yamllint output to check syntax before suggesting edits

Before Modifying Any Workflow

1. Read the full workflow file
2. Preserve all permissions: blocks
3. Keep the Windows portability paths explicit and use cross-platform commands (or declare shell: bash when Bash syntax is unavoidable)
4. Verify action versions don't change interface
5. Stage changes on a feature branch, not directly on main

Common Patterns

• uv sync --locked --group docs --all-extras --dev installs the locked test profile; the explicit docs group is required because documentation-hook tests import MkDocs.
• if: always() is limited to report/status jobs; required checks must preserve the underlying failure result and be enforced by their final status job.
• if: always() on summary jobs ensures they run after failures
• continue-on-error: true on lint/format steps for agent flexibility

Currency and supply chain

Account rules CUR-1..CUR-16 are authoritative for this repository; where this file and those rules disagree, the rules win.