elastic / elastic/ai-github-actions
[product-manager-impersonator] Shared fragment inventory lint
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Feature Idea
**Summary:** Add a lightweight lint that keeps the shared `gh-aw-fragments` inventory aligned with actual fragment files and workflow imports.
## Why a Customer Would Want This
Maintainers who add or modify GitHub Agent Workflows need a reliable map of reusable fragments. Today the fragment catalog is manually maintained, so new contributors and agentic implementers can miss existing building blocks or leave stale architecture docs behind.
## Rough Implementation Sketch
- Add a small script such as `scripts/check-gh-aw-fragments.py` that scans `.github/workflows/gh-aw-fragments/*.md`.
- Parse workflow `imports:` entries in `.github/workflows/gh-aw-*.md` and compare them with the documented fragment table in `gh-agent-workflows/DEVELOPING.md`.
- Report undocumented fragments, documented-but-missing fragments, and optionally unused fragments.
- Wire the check into `make lint` next to the existing documentation/catalog checks.
## Why It Won't Be That Hard
This is a local file inventory check: no compiler or runtime behavior needs to change. The repository already has the pattern of Python-backed lint checks in `make lint`, and the relevant data lives in predictable Markdown files and frontmatter import lists.
## Evidence
- `gh-agent-workflows/DEVELOPING.md:82-105` documents a manual shared-fragment catalog.
- `gh-agent-workflows/DEVELOPING.md:143-148` tells maintainers to edit workflows, triggers, and fragments as part of the normal workflow-editing path.
- `Makefile:266-267` currently runs workflow/action lint plus `scripts/check-nav-catalog.py`, but there is no fragment inventory check in that lint path.
- The repository currently has 35 files under `.github/workflows/gh-aw-fragments/`, while only 19 are referenced in the `DEVELOPING.md` catalog. Missing catalog entries include `runtime-setup.md`, `network-ecosystems.md`, `pr-context.md`, and `safe-output-code-review.md`.
- `.github/workflows/gh-aw-pr-review.md:5-18` imports several undocumented fragments, including `runtime-setup.md`, `pr-context.md`, `safe-output-code-review.md`, and `network-ecosystems.md`.
Duplicate check: Existing product-manager findings cover workflow scaffolding, scoped compile, artifact parity, example-trigger linting, and docs input-table sync, but I found no open issue for a shared-fragment catalog/import inventory lint.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Product Manager Impersonator](https://github.com/elastic/ai-github-actions/actions/runs/28093749808)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Research direction
Start with the fragment catalog in gh-agent-workflows/DEVELOPING.md:82-105, the imports in .github/workflows/gh-aw-pr-review.md:5-18, and the existing lint wiring at Makefile:266-267. Compare the files under .github/workflows/gh-aw-fragments/ with documented and imported entries, then run make lint; done means the check reports discrepancies clearly and passes when the inventory is aligned.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, markdown, python
- Domain
- ci-cd, documentation, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100