docs: bootstrap AGENTS.md + CLAUDE.md shim (BE-3582)

AGENTS.md

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

CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- Agent instructions live in AGENTS.md (the cross-agent standard). This is a Claude Code shim: Claude reads only CLAUDE.md, so the import below pulls AGENTS.md in. Don't add content here — edit AGENTS.md. -->
+@AGENTS.md