|
| 1 | +# AGENTS.md — Comfy-Org/github-workflows |
| 2 | + |
| 3 | +Shared, versioned **reusable GitHub Actions workflows** for use across Comfy-Org |
| 4 | +repositories. This repo is **public** so any repo — public or private, inside or |
| 5 | +outside the org — can call these workflows. Each reusable workflow's logic |
| 6 | +(prompts, Python/shell scripts) lives *here* as the single source of truth; |
| 7 | +consumer repos carry only a thin caller that pins this repo by full commit SHA. |
| 8 | +There is no application to build or run — the deliverable is the workflows |
| 9 | +themselves plus the scripts that back them. |
| 10 | + |
| 11 | +## Commands |
| 12 | + |
| 13 | +Python is stdlib-only (no requirements file); CI uses **Python 3.12**. Run from |
| 14 | +the repo root. Each command mirrors a CI job (see `.github/workflows/test-*.yml`): |
| 15 | + |
| 16 | +```bash |
| 17 | +# cursor-review helper-script tests (extract-findings, post-review) |
| 18 | +python3 -m unittest discover -s .github/cursor-review/tests -p 'test_*.py' -v |
| 19 | + |
| 20 | +# agents-md-integrity checker tests |
| 21 | +python3 -m unittest discover -s .github/agents-md-integrity/tests -p 'test_*.py' -v |
| 22 | + |
| 23 | +# bump-callers shell tests + lint (gh is stubbed; no network) |
| 24 | +shellcheck -x .github/bump-callers/bump-callers.sh .github/bump-callers/tests/test_bump_callers.sh |
| 25 | +bash .github/bump-callers/tests/test_bump_callers.sh |
| 26 | + |
| 27 | +# run the AGENTS.md integrity checker against any repo tree |
| 28 | +python3 .github/agents-md-integrity/check_agents_md.py --root . |
| 29 | +``` |
| 30 | + |
| 31 | +There is no repo-wide formatter/linter config (no ruff/black/pyproject, |
| 32 | +no pre-commit). Shell is linted by `shellcheck` in CI; Python is guarded by the |
| 33 | +`unittest` suites above. Every test workflow is **path-filtered**, so a change |
| 34 | +that touches only the files under a given directory runs only that directory's |
| 35 | +tests — run the matching command above for whatever you touched. |
| 36 | + |
| 37 | +## Layout |
| 38 | + |
| 39 | +- `.github/workflows/` — the reusable workflows (`on: workflow_call`) plus this |
| 40 | + repo's own CI callers (`ci-*.yml`) and the `test-*.yml` script tests. |
| 41 | +- `.github/cursor-review/` — prompts + scripts behind `cursor-review.yml` |
| 42 | + (the multi-model review panel + judge). Single source of truth; loaded at run |
| 43 | + time, never copied into consumers. Tests in `tests/`. |
| 44 | +- `.github/agents-md-integrity/` — `check_agents_md.py`, the checker behind |
| 45 | + `agents-md-integrity.yml` (enforces this AGENTS.md standard). Tests in `tests/`. |
| 46 | +- `.github/bump-callers/` — `bump-callers.sh`, the ONE fleet-agnostic script |
| 47 | + that opens SHA-bump PRs in consumer repos when a reusable workflow changes. |
| 48 | + Tests in `tests/`. |
| 49 | +- `README.md` — the public workflow catalog: per-workflow purpose, the SHA-pin |
| 50 | + usage pattern, and the versioning policy. Keep its table in sync when you add |
| 51 | + a workflow. |
| 52 | + |
| 53 | +## Reusable workflow catalog (what each does) |
| 54 | + |
| 55 | +- `cursor-review.yml` — label-triggered multi-model PR review (4-lab × 2-type |
| 56 | + panel → judge → one PR review with severity badges). Advisory by default; |
| 57 | + `blocking: true` gates on unresolved findings. |
| 58 | +- `cursor-review-auto-label.yml` — translates PR assignment/open into the review |
| 59 | + label (via an app token, since a `GITHUB_TOKEN`-applied label won't fire runs). |
| 60 | +- `agents-md-integrity.yml` — enforces the AGENTS.md standard on the caller repo. |
| 61 | +- `assign-reviewers.yml` — expertise-aware, load-balanced reviewer requests. |
| 62 | +- `assign-prs-to-author.yml` — assigns unassigned open PRs to their author. |
| 63 | +- `detect-unreviewed-merge.yml` — SOC 2: flags PRs merged without approval. |
| 64 | +- `bump-cursor-review-callers.yml` / `bump-agents-md-callers.yml` — thin |
| 65 | + entrypoints over `bump-callers.sh` that fan SHA bumps out to consumers. |
| 66 | + |
| 67 | +## Conventions & gotchas |
| 68 | + |
| 69 | +- **Public repo — never leak private caller names.** Consumer repo lists live in |
| 70 | + repo **variables** (`CURSOR_REVIEW_CALLERS`, `AGENTS_MD_CALLERS`), never |
| 71 | + hardcoded in a workflow file or printed to run logs (logs are public). The |
| 72 | + bumper masks names it processes. Keep private repo paths/detail out of |
| 73 | + workflow files, commit messages, and PR text. |
| 74 | +- **Pin everything by full commit SHA**, with a trailing `# v1` comment — both |
| 75 | + the `uses:` in callers and every third-party action here. Bare `@v1` fails the |
| 76 | + pin-validation (`pinact`, `zizmor`) that consumer CI runs. See README "Usage". |
| 77 | +- **Scripts are the single source of truth**, loaded at run time from a pinned |
| 78 | + ref of THIS repo — never from the caller's checkout. That's what makes the |
| 79 | + reviewer/checker tamper-proof: a PR can't rewrite the logic judging it. The |
| 80 | + self-enrollment callers (`ci-cursor-review.yml`, `ci-detect-unreviewed-merge.yml`) |
| 81 | + deliberately pin a merged-main SHA instead of a local `./` path for the same |
| 82 | + reason — do not "simplify" them to a local path. |
| 83 | +- **One bumper, not two.** `bump-callers.sh` backs both fleets; the two |
| 84 | + `bump-*-callers.yml` files are thin per-fleet wrappers (they stay separate so a |
| 85 | + `cursor-review.yml` change doesn't spuriously bump agents-md callers). Do not |
| 86 | + fork the script — a forked copy is how other shared org machinery has drifted. |
| 87 | +- **New reusable workflow?** `on: workflow_call` + a header comment documenting |
| 88 | + inputs/secrets/triggers + a caller-pattern example, then update the README |
| 89 | + table (README "Adding a new reusable workflow"). Move the floating major tag |
| 90 | + after merge. |
| 91 | +- **Versioning:** semver-style major tags (`v1`, `v2`). Breaking changes bump the |
| 92 | + major; backwards-compatible changes move the existing tag in place |
| 93 | + (`git tag -f v1 <sha> && git push -f origin v1`). This tag force-move is the |
| 94 | + one sanctioned force-push — it is NOT license to force-push branches. |
| 95 | +- **Commit style:** Conventional Commits with a scope, e.g. |
| 96 | + `fix(cursor-review): …`, `ci(bump-callers): …`, `feat(assign-reviewers): …`. |
| 97 | + Append a `(BE-####)` Linear suffix when a ticket drives the change. Land via |
| 98 | + squash-merged PR. |
| 99 | +- **This AGENTS.md is itself gated** by the standard `agents-md-integrity.yml` |
| 100 | + enforces: keep it under 200 lines (aim ≤150), keep `CLAUDE.md` a bare |
| 101 | + `@AGENTS.md` shim (never a divergent copy), and never add a `.cursorrules`. |
| 102 | + |
| 103 | +## Deeper docs |
| 104 | + |
| 105 | +- [`README.md`](README.md) — public catalog, SHA-pin usage, versioning. |
| 106 | +- [`.github/cursor-review/README.md`](.github/cursor-review/README.md) — review panel internals + adoption. |
| 107 | +- [`.github/agents-md-integrity/README.md`](.github/agents-md-integrity/README.md) — the checker + its knobs. |
| 108 | +- [`.github/bump-callers/README.md`](.github/bump-callers/README.md) — the shared bumper + the two fleets. |
0 commit comments