ai-workflows: Instructions file for Codex

ai-workflows

Reusable AI agent workflows for GitHub Actions. Consumer repos call these with thin ~10-20 line callers.

Architecture

This repo is the single source of truth for CI/CD automation workflows. Each workflow is a GitHub reusable workflow (on: workflow_call) that consumer repos invoke via uses: dryvist/ai-workflows/.github/workflows/<name>.yml@<40-hex-sha> # vX.Y.Z.

Directory Structure

.github/
  prompts/
    *.md                            # Prompt files (one per workflow)
  scripts/
    render-prompt.sh                # Shared: envsubst + GITHUB_OUTPUT
    best-practices/                 # Extracted JS scripts per workflow
    ci-fail-issue/
    ci-fix/
    dep-review/
    issue-backlog-sweep/
    issue-linker/
    issue-resolver/
    post-merge-docs-review/
    post-merge-tests/
    pr-agent/
    release-notes/
    review-thread-resolver/
    shared/
    verification/
  workflows/
    *.yml                           # Pure YAML workflow definitions (no embedded content)

Workflow Types

There are three families, and they do not share a credential contract:

1. Agentic workflows use the shared run-ai-agent adapter, which selects Claude or Codex from GH_ACTION_AI_AGENT and defaults to Claude. These are the workflows that edit a tree and open a pull request.
2. pr-agent.yml runs PR-Agent against the model router for PR-scoped review, code suggestions and descriptions. Its prompts live in the consumer repository's own .pr_agent.toml; see docs/pr-agent.md.
3. Router workflows (thread-triage, docs-drift, repo-hygiene-digest) make one chat completion with actions/ai-inference (a .prompt.yml beside the workflow's scripts holds the messages and, where the answer is JSON, the schema). They take LLM_ROUTER_BASE_URL and LLM_ROUTER_API_KEY — both secrets — and default to a self-hosted runner, because only such a runner reaches the router.

A router workflow that cannot reach the router FAILS, releasing the runner: the action's client retries a connection failure or 5xx twice and gives up, and the job is capped at ten minutes. CI never waits for a model beyond that; the router role's own fallback chain absorbs load. pr-agent picks the router key and role by repository visibility (LLM_ROUTER_OSS_API_KEY + oss_model on an open-source repo); every review still runs on the self-hosted pool against the router. Never restore a skip-and-succeed path: a green check that did no work is what these replaced.