Adopt GitHub Agentic Workflows for issue, PR, and documentation automation

[arnaudlh]

Summary

Introduce GitHub Agentic Workflows (gh-aw) to Azure/git-ape to automate repetitive maintainer tasks, keep documentation evergreen, and improve contributor experience — aligning with the repo's mission as a platform engineering framework for the agentic age.

Agentic workflows are authored in Markdown, compiled to hardened GitHub Actions via the gh aw CLI, and run with guardrails (sandboxed execution, scoped tokens, audit trails, output validation). They support multiple engines (Copilot, Claude, Codex).

Motivation

• Reduce maintainer toil on triage, review, and docs upkeep.
• Dogfood agentic patterns in a repo explicitly about the agentic age.
• Provide a reference implementation contributors can learn from.

Proposed workflows

🗂️ Issue management

• Issue Triage Agent — On issues.opened / reopened: classify, apply labels (bug, feature, docs, question), detect likely duplicates, request missing repro info, and post a welcome/next-steps comment.
• Stale Issue/PR Groomer — Weekly schedule: summarize aging items, ping assignees, and suggest closure for abandoned items (human-in-the-loop).

🔀 Pull Request management

• PR Review Agent (Shell-focused) — On pull_request.opened / synchronize: AI-assisted review tuned for Shell best practices (shellcheck-style issues, quoting, set -euo pipefail, error handling, portability).
• PR Describer / Summarizer — Auto-generate or enrich thin PR descriptions, suggest labels, and draft changelog entries from the diff.

📚 Documentation evergreen

• Docs Drift Detector — On push to main: detect when script behavior, CLI flags, or configuration diverge from README.md / docs and open a PR with proposed updates.
• README & Examples Refresh — Monthly schedule: validate that commands/snippets in README still run and refresh outdated examples.

🛠️ Repo maintenance

• CI Failure Triager — On workflow failure on main: analyze logs, identify root cause, open or update a tracking issue with a suggested fix.
• Weekly Repo Health Report — Scheduled digest issue summarizing new/closed issues, merged PRs, contributor activity, and flagged hotspots.

Implementation plan

1. Bootstrap
   • Install gh aw CLI locally for authoring/compiling.
   • Add .github/workflows/agentic/ directory for Markdown workflow sources.
   • Document local authoring flow in CONTRIBUTING.md.
2. Guardrails & secrets
   • Decide on engine(s): Copilot by default; allow opt-in to Claude/Codex.
   • Configure least-privilege GITHUB_TOKEN scopes per workflow.
   • Enable required-reviewer gates on any agent-opened PRs.
3. Rollout (phased)
   • Phase 1: Issue Triage + PR Describer (low-risk, read/label focused).
   • Phase 2: PR Review Agent + Docs Drift Detector.
   • Phase 3: CI Failure Triager, Stale Groomer, Health Report, README Refresh.
4. Observability
   • Enable workflow run summaries and agent audit logs.
   • Track metrics: time-to-triage, PR review latency, doc drift PRs merged.

Acceptance criteria

• gh aw bootstrapped and documented in CONTRIBUTING.md.
• At least Phase 1 workflows running on main.
• Each workflow has a short README describing intent, triggers, and how to disable.
• Maintainer opt-out path documented (labels like no-agent to skip automation).

References

• GitHub Agentic Workflows — Home
• GitHub Blog: Automate repository tasks with GitHub Agentic Workflows
• Getting Started guide (josh-ops)

Labels (suggested)

enhancement, automation, documentation, good first issue (for individual sub-tasks if broken out)