Implement GitHub Agentic workflows

[don-petry]

Implement the existing GitHub agent workflows that are defined here:

https://github.com/github/gh-aw

And consider how to further adapt and extend for our organizations needs.

https://github.github.com/gh-aw/

https://github.github.com/gh-aw/setup/creating-workflows/

[don-petry]

@claude - review, refine and ideate this. Then, create an implementation plan that follows tdd and other best practices.

[don-petry]

Review, Refinement & Ideation

What gh-aw brings vs. what we already have

Our existing .github-private infrastructure is already sophisticated — dev-lead.yml and pr-review.yml are complex, multi-step YAML files backed by shell scripts. gh-aw doesn't replace those patterns; it gives us a better authoring surface for the next layer of automation:

Current approach	gh-aw approach
YAML + bash scripts (~200–400 lines)	Markdown with natural-language instructions (~30–60 lines)
Ad-hoc security (PATs, manual scoping)	5-layer security built-in (read-only, sandboxed, threat-scanned)
Compiled by hand	gh aw compile validates and generates .lock.yml
Hard to iterate	AI-assisted authoring in minutes

Recommendation: Don't migrate dev-lead or pr-review — they're too tightly integrated. Instead, use gh-aw for new workflows going forward.

---

Refinements to the idea

1. Use Claude as the engine — we already have CLAUDE_CODE_OAUTH_TOKEN configured. No new secrets needed.
2. Centralize in .github-private — keep the same pattern we use today: workflows live here, deployed org-wide.
3. Staged-first policy — all new gh-aw workflows launch with output: staged (human-reviewable artifacts) before going live. This is our safety valve.
4. Avoid the billing-buggy versions — README flags 0.68.4–0.71.3 as broken. Pin via gh extension upgrade aw and lock the version in CI.

---

Ideation — workflows worth building

Ordered by value / effort:

Priority	Workflow	Trigger	Safe Output
P0	Issue Triage	issues: opened	labels, comment
P0	CI Failure Analyst	check_run: completed (failure)	PR comment with root cause
P1	Stale Manager	schedule (weekly)	close/comment on stale items
P1	Release Notes Generator	push to main	PR with CHANGELOG update
P2	Documentation Health	schedule (weekly)	issue with staleness report
P2	Dependency Advisory	pull_request on dep files	PR comment with risk assessment
P3	Cross-repo Standards Sync	schedule (monthly)	PRs to all repos with standard updates
P3	ContentTwin Content Audit	schedule (daily)	issue in ContentTwin with content health

---

Implementation Plan

TDD methodology for gh-aw

gh-aw workflows are tested at three levels:

1. Scenario specs — written before the workflow markdown. Each spec defines trigger inputs, expected safe-outputs, and edge cases.
2. Compile validation — gh aw compile runs in CI on every PR touching .github/workflows/*.md.
3. Staged smoke tests — every new workflow runs in output: staged mode against a canary trigger before flipping live.

---

Phase 0 — Foundation (Day 1)

Goal: gh-aw is installed, initialized, and CI validates compiled workflows.

• Install the gh-aw extension in the CI environment:

  curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
  gh aw version

• Run gh aw init in .github-private — generates the dispatcher agent at .github/agents/agentic-workflows.agent.md and configures MCP server integration.
• Add a CI job to lint.yml that compiles all *.md workflows and fails on error:

  - name: Compile agentic workflows
    run: |
      gh extension install github/gh-aw
      gh aw compile

• Write tests/aw/README.md documenting the test convention (scenario specs + staged runs).
• Configure engine to use Claude (CLAUDE_CODE_OAUTH_TOKEN already in secrets).

Test gate: gh aw compile succeeds with zero workflows (baseline).

---

Phase 1 — Issue Triage Workflow (Days 2–3)

Goal: New issues are auto-labeled and triaged within 60 seconds of being opened.

TDD cycle

1. Write scenario spec first — tests/aw/issue-triage/scenarios.md:

   • Input: issue titled "Login button is broken" with no labels → Expected: labels bug, needs-triage; comment asking for repro steps
   • Input: issue titled "Add dark mode support" → Expected: label enhancement; comment acknowledging feature request
   • Edge: issue already has 2+ labels → workflow is a no-op

2. Write workflow — .github/workflows/issue-triage.md

3. Compile: gh aw compile → produces issue-triage.lock.yml

4. Staged test: gh aw run issue-triage --staged against a test issue; verify output artifact matches scenario spec

5. Go live: remove output: staged, merge PR

Test gate: Staged run output reviewed and signed off before merge.

---

Phase 2 — CI Failure Analyst (Days 4–5)

Goal: When a CI check fails on a PR, the bot posts a root-cause diagnosis within 2 minutes.

Scenario spec (tests/aw/ci-failure-analyst/scenarios.md):

• Input: check_run completed with failure → Expected: PR comment with failed step name, likely root cause, suggested fix, log link
• Edge: non-test check (lint, deploy) → diagnose but note the check type
• Edge: bot comment already exists → update it, don't duplicate

Note: Complements dev-lead — gh-aw handles analysis/commenting; dev-lead retains write authority for actual fixes.

---

Phase 3 — Stale Manager & Release Notes (Days 6–8)

Same TDD cycle for each:

• Stale Manager: specs define age thresholds (issues > 60 days, PRs > 30 days), expected comment text, and close conditions. Runs weekly on schedule.
• Release Notes Generator: spec defines expected CHANGELOG format given a set of merged PR titles/labels. Triggered on push to main.

---

Phase 4 — Cross-org Deployment (Day 9)

Decision point: after Phase 3 — if workflows are stable, package them as a shared agentic workflow and reference from other repos. If still iterating, keep centralized in .github-private using the existing org dispatch pattern.

---

Phase 5 — Remaining Workflows (Days 10+)

Documentation Health, Dependency Advisory, Cross-repo Standards Sync, ContentTwin Content Audit — each follows the same TDD cycle, prioritized by pain points.

---

Definition of Done (per workflow)

• Scenario spec written and reviewed before workflow markdown exists
• gh aw compile passes in CI
• Staged mode run reviewed; output matches spec
• Live mode tested on non-critical trigger
• Behavior documented in docs/aw/<workflow-name>.md

---

Files this creates in .github-private

.github/
  agents/
    agentic-workflows.agent.md    ← gh aw init generates this
  workflows/
    issue-triage.md               ← source (authoritative)
    issue-triage.lock.yml         ← compiled artifact (committed)
    ci-failure-analyst.md
    ci-failure-analyst.lock.yml
    stale-manager.md
    stale-manager.lock.yml
    release-notes.md
    release-notes.lock.yml
tests/
  aw/
    README.md
    issue-triage/scenarios.md
    ci-failure-analyst/scenarios.md
    stale-manager/scenarios.md
docs/
  aw/
    issue-triage.md
    ci-failure-analyst.md

Ready to kick off Phase 0 whenever you want to start.

[don-petry]

Architectural Analysis: Deployment Strategy & Shim Integration

Building on the implementation plan above — two questions came up in design review that affect how Phase 0 lands and how gh-aw sits alongside the existing workflow infrastructure.

---

1. Cross-repo deployment: is "deploy once org-wide" supported?

No — and the architecture to understand is the package model.

gh-aw is per-repo by design: gh aw init configures one repo, and compiled .lock.yml files + Actions runners live in that repo's .github/workflows/. There is no org-level install.

What IS supported is centralizing workflow definitions in .github-private (our source of truth) while each consuming repo handles its own execution:

# .github-private package structure
workflows/
  triage.md
  ci-failure-analyst.md
aw.yml          ← manifest listing installable workflows

Consuming repos run:

gh aw init                              # one-time per repo
gh aw add petry-projects/.github-private  # pulls workflow definitions in
gh aw compile                           # compiles to .lock.yml

This mirrors what deploy-standard-workflows.sh already does for the YAML stubs — same conceptual model, different mechanism.

Update propagation gap: unlike the reusable-workflow shim pattern (where logic updates are instant), gh-aw package updates require each consuming repo to re-run gh aw add + gh aw compile. Mitigation: add a maintenance workflow that automates this on a schedule or via workflow_dispatch, analogous to the existing deploy script.

---

2. How does gh-aw sit alongside the existing shim approach?

After reviewing the actual workflow structure in .github and .github-private, the two systems are complementary rather than competing:

Workflow type	Right tool	Why
agent-shield, auto-rebase, dependabot-*, dependency-audit	Keep as reusable shims	Deterministic YAML logic; update-propagation is instant via the reusable; no compile step; no tooling dependency
dev-lead, pr-review, feature-ideation, compliance-auditor	gh-aw long-term target	These are fundamentally "check out prompts, pipe through AI engine" — exactly the pattern gh-aw standardizes and hardens with injection sanitization, tool allow-listing, and strict: true compile-time validation
New agentic workflows (triage, CI analyst, stale manager, etc.)	gh-aw	Start here from day one

The existing plan's call to not migrate dev-lead / pr-review immediately is the right short-term call — they're deeply integrated. But the long-term target for those workflows is gh-aw, not indefinite maintenance of the hand-rolled bash+prompt architecture.

---

Revised Phase 0 checklist

Adding to the existing Phase 0 (Foundation) items:

• Run gh aw init in .github-private and commit the generated scaffolding
• Create aw.yml package manifest in .github-private root
• Add workflows/ directory alongside .github/workflows/ for installable package definitions
• Add a workflow_dispatch-triggered maintenance workflow that re-runs gh aw add + gh aw compile across consuming repos (parallels deploy-standard-workflows.sh)
• Document the two-system boundary in standards/agent-standards.md: shims for deterministic, gh-aw for agentic