Add workflow catalog and CONTRIBUTING agentic workflow section (#8587)#8599
Merged
Conversation
Adds .github/workflows/README.md cataloging every regular and agentic workflow in the repo (28 agentic + 10 regular + 7 shared components), grouped by purpose, and links to gh-aw conventions. Also extends CONTRIBUTING.md with a short "Agentic Workflows" section that points contributors to the catalog and restates the non-negotiable rules: the .md is the source of truth, lock files are regenerated by `gh aw compile`, and strict mode is mandatory. Addresses Task 3 from #8587. Tasks 1, 2, 4, and 5 from that issue were assessed and intentionally skipped: - Task 1 (workflow testing infra): gh aw compile --strict already validates; a separate test/workflows framework is over-engineered. - Task 2 (observability shared component): gh-aw generates the .lock.yml from the .md; a shared "observability" import wouldn't inject summaries into generated jobs. - Task 4 (version:/changelog: frontmatter): not valid gh-aw fields; would fail strict-mode validation. Workflows are versioned via git. - Task 5 (error-handling shared component): gh-aw already provides AWF sandbox + safe-outputs; markdown "pattern docs" don't change runtime behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds contributor-facing documentation for the repository’s GitHub Actions ecosystem, with a focus on agentic workflows authored via gh aw.
Changes:
- Adds a workflow catalog at
.github/workflows/README.md(agentic workflows, regular workflows, shared components, and conventions). - Adds an “Agentic Workflows” section to
CONTRIBUTING.mdlinking to the catalog and restating key rules (source-of-truth.md, regenerate.lock.yml, strict mode, don’t edit generated artifacts).
Show a summary per file
| File | Description |
|---|---|
CONTRIBUTING.md |
Adds contributor guidance for working with agentic workflows and points to the new catalog. |
.github/workflows/README.md |
Introduces a central workflow catalog and conventions/quick-start commands for gh aw. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 3
Copilot review noted that .github/workflows/package.json, requirements.txt, and go.mod do not currently exist in the repo. Reworded the three mentions to make clear those manifests are only emitted by `gh aw compile` for workflows that need them, so the guidance stays accurate whether or not they're present. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Evangelink
commented
May 26, 2026
Member
Author
Evangelink
left a comment
Evangelink
left a comment
There was a problem hiding this comment.
✅ 21/21 dimensions clean — no findings.
This documentation-only PR adds a comprehensive workflow catalog to .github/workflows/README.md and updates CONTRIBUTING.md with agentic workflow guidelines.
Verified:
- ✅ All 28 agentic workflow filenames match filesystem
- ✅ All 10 regular workflow filenames match filesystem
- ✅ All 7 shared component filenames match filesystem
- ✅ Counts are accurate (28 agentic, 10 regular, 7 shared)
- ✅ File references use correct relative paths
- ✅ Organization is logical and scannable
- ✅ Scope is focused and appropriate
- ✅ markdownlint correctly excludes
.github/workflows/(agentic sources have non-standard frontmatter)
The catalog provides excellent discoverability for the repository's extensive workflow ecosystem.
Generated by Expert Code Review (on open) for issue #8599 · ● 1M
Evangelink
added a commit
that referenced
this pull request
May 26, 2026
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Evangelink
force-pushed
the
dev/amauryleve/workflow-catalog
branch
from
8682672 to
6834f63
Compare
YuliiaKovalova
approved these changes
May 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #8587 (partial — see assessment below).
What's in this PR
.github/workflows/README.md, a single source of truth that catalogs:*.md➝*.lock.yml), grouped by purpose (review, build/test diagnostics, continuous quality improvers, issue/PR housekeeping)*.ymlworkflowsshared/*.mdreusable components and who imports themCONTRIBUTING.mdthat points at the new catalog and restates the non-negotiable rules (.mdis the source of truth, lock files are regenerated bygh aw compile, strict mode is mandatory, never hand-edit lock files / generated manifests).Assessment of #8587's 5 tasks
The originating issue is an auto-generated report from
repository-quality-improverproposing 5 tasks. I reviewed each before implementing:test/workflows/)gh aw compile --strictalready validates frontmatter, action pinning, network policy, and safe-output usage. A separate test framework would duplicate this and require committing extra tooling..lock.ymlfrom the.md; adding animports:for a "patterns" doc doesn't inject `` writes into generated jobs. GitHub Actions already provides per-run logs.version:/changelog:frontmatter)error-handling.mdcomponentsafe-outputs:for structured error handling; a markdown "patterns" doc imported by every workflow doesn't change runtime behavior.PR strategy
I went with a single PR because Task 3 is the only task I judged worth doing, and it's small enough not to warrant splitting (one new doc + one section in CONTRIBUTING).
Validation
CONTRIBUTING.mdlints clean against the repo's.markdownlint-cli2.jsoncconfig..github/workflows/README.mdis excluded from CI markdownlint (the directory is excluded for the agentic workflow.mdsources, which have non-standard frontmatter), but I verified it passes the same rules locally.