.github -- AI Agent Guide

Status: Active | Last Updated: April 2026

Purpose

This directory holds GitHub-specific configuration: CI/CD workflows, issue/PR templates, Dependabot config, CODEOWNERS, Gemini AI command configs, and multi-agent infrastructure. This document tells AI agents what they need to know to operate safely within this directory.

Workflow YAML count: 37 files under .github/workflows/ (align with root README.md and docs/reference/inventory.md; refresh via uv run python scripts/doc_inventory.py).

Directory Contents

Agent-Specific Infrastructure

Jules AI Agent

Gemini CLI Agent

Dependabot

Safe Operations

• Read any file in .github/ to understand CI/CD structure and triggers
• Run yamllint .github/workflows/*.yml to validate YAML syntax
• Use gh run list --workflow=<name>.yml and gh run view to check status
• Use gh pr list and gh issue list to review open items
• Read CODEOWNERS to understand review assignment rules

Caution Required

• Workflow edits take effect immediately on the next trigger — test on a branch
• CODEOWNERS changes affect review requests for every future PR
• Never remove permissions: {} blocks — they enforce least-privilege tokens
• Never remove concurrency: blocks — they prevent duplicate workflow runs

Modifying Workflows — Checklist

1. Read the target workflow file fully before editing
2. Preserve all permissions: blocks (deny-all default + job-level grants)
3. Keep concurrency: groups intact
4. Pin action versions to a full commit SHA with a trailing comment naming the release, e.g. uses: actions/checkout@<40-char sha> # actions/checkout@vX.Y.Z (CUR-4, CUR-5)
5. Use uv (not pip/poetry) for Python dependency management
6. Test workflow changes on a feature branch before merging to main
7. Validate YAML: python3 -c "import yaml; yaml.safe_load(open('file.yml'))"

CI Quick Commands

# List recent CI runs
gh run list --workflow=ci.yml --limit=5

# Check auto-merge status
gh run list --workflow=auto-merge.yml --limit=3

# List agent PRs
gh pr list --label=jules --state=open

# List conflicting PRs
gh pr list --label=conflict --state=open

# View agent metrics (latest run)
gh run list --workflow=agent-metrics.yml --limit=1

# Trigger Jules batch dispatch
gh workflow run jules-dispatch.yml -f modules=all -f task_template=docstrings-mcp-tests

Operating Contracts

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.

Navigation

• PAI.md | SPEC.md
• Root AGENTS | Root PAI