From 0c8872cc4d9784d8eb2afddfdd8c0026b5d32857 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 20 Sep 2026 17:08:47 +0000 Subject: [PATCH] Point overlay /scaffold at Hugging Face AGENTS.md and library CI A new engineer on the fork should follow upstream AGENTS.md/.ai/ and invoke make style / make quality / check_dummies, not the old two-files-only recipe. Attach copies that overlay command; tests assert the attached scaffold keeps those library gates. Co-authored-by: ale93.moro --- docs/CURSOR_PROMPTS.md | 6 ++++-- docs/LIVE_DEMO.md | 31 +++++++++++++++++-------------- docs/TALK_TRACK.md | 14 +++++++------- overlay/OVERLAY.md | 38 +++++++++++++++++++++----------------- overlay/scaffold.md | 26 +++++++++++++++++++------- tests/test_tooling.py | 8 +++++++- tools/attach_library.py | 1 + 7 files changed, 76 insertions(+), 48 deletions(-) diff --git a/docs/CURSOR_PROMPTS.md b/docs/CURSOR_PROMPTS.md index 1e0f9b1..d7b2f36 100644 --- a/docs/CURSOR_PROMPTS.md +++ b/docs/CURSOR_PROMPTS.md @@ -167,6 +167,8 @@ the tooling. Keep it minimal; do not implement a real model. rules, different surface. Note the upstream-vs-customer split. One registry, many projections — not a capability per SDLC step. - **Fork PR hygiene:** draft, **base `main`**, `[fork demo — not for upstream]`. - Overlay-gate is the customer check-run. Overlay green does not mean Hugging - Face CI is green; do not delete their workflows. Math stays TODO. + Overlay-gate is the customer check-run; `make style` / `make quality` are the + library's. Jobs that need Hugging Face private runners or size labels may + still be red on this fork — hosting, not a reason to skip those commands. + Do not delete their workflows. Math stays TODO. - **Maintainability:** Prompt B — one edit propagates everywhere. diff --git a/docs/LIVE_DEMO.md b/docs/LIVE_DEMO.md index 6d3e772..298f1cd 100644 --- a/docs/LIVE_DEMO.md +++ b/docs/LIVE_DEMO.md @@ -12,7 +12,7 @@ Two ways to play the same journey after the kit beat: | Path | When | |------|------| -| **A. Cloud Agent on the fork** (`/scaffold scheduler HeunLite`) | Primary. Real `src/diffusers/schedulers/`. Two files the registry checks. | +| **A. Cloud Agent on the fork** (`/scaffold scheduler `) | Primary. Real `src/diffusers/schedulers/`. Overlay templates + library `make style` / `make quality`. | | **B. CLI twin in this kit** (`make demo-contribute KEEP=1`) | Rehearsal if the fork VM is slow. Stand-in tree only. | Do **not** run Path B first if you want Path A to create the files live. @@ -34,12 +34,12 @@ plan → ground → build → gate → test → review → CI clearance | 0. Pre-flight | you | `make doctor` **on the kit** | “Python3, PyYAML, Cursor files present.” | | 1. Plan | PM + engineer | `.github/ISSUE_TEMPLATE/contribution.md` | “Done is the same checklist CI will run.” | | 2. Catch-early | QA / engineer | gate on kit `examples/candidate_scheduler` | “8 blocking: moved import, missing mixin, `.cuda()`, no test. That’s a review round-trip. This is the overlay, not the library.” | -| 3. Ground | engineer | `ramp-kit/conventions/rules.yaml` + overlay templates | “Done is the gate. Templates already pass. I am not copying Euler/DDPM or writing docs.” | -| 4. Build | engineer | `/scaffold scheduler HeunLite` **on the fork** | “Two files. `TODO(engineer)` stays in `step()`.” | -| 5. Gate | engineer + CI | check the **new file only** | “0 blocking. Same script as the edit hook. Never `--all` on this library.” | -| 6. Test | engineer | unittest on the new test | “Signatures pass; behavioral tests skip without torch — expected.” | +| 3. Ground | engineer | `ramp-kit/conventions/rules.yaml` + overlay templates + root `AGENTS.md` | “Overlay registry plus the library's own agent guide. Templates already pass. I am not copying Euler/DDPM math.” | +| 4. Build | engineer | `/scaffold scheduler ` **on the fork** | “Template copy, public-API registration, `TODO(engineer)` stays in `step()`.” | +| 5. Gate | engineer + CI | file-scoped overlay gate **and** `make style` / `make quality` | “0 blocking on the new file. Library quality green. Never `--all` on this library.” | +| 6. Test | engineer | unittest on the new test | “Signatures pass; with torch, count/shape/dtype/determinism pass. Do not edit `step()` math.” | | 7. Review | QA | `projections/qa/review-checklist.md` | “Gate took the mechanical items. Humans judge the paper.” | -| 8. Clearance | DevOps | overlay gate green; HF Actions may be red | “Overlay clearance ≠ upstream CI. I don’t fake deploy, and I don’t disable their workflows.” | +| 8. Clearance | DevOps | overlay gate green **and** `check_code_quality` / `check_repository_consistency` | “Customer gate plus library quality. I don’t fake deploy, and I don’t disable their workflows.” | | 9. Maintain | platform | `make demo-maintain` on the **kit** (if time) | “One YAML edit. I’m gone; they still own it. Not a tool per SDLC step.” | --- @@ -57,20 +57,23 @@ Pre-flight (before they sit): on this kit, not in the paste. - Paste **Prompt A (fork)** from `docs/CURSOR_PROMPTS.md`. -Then type: +Then type (`HeunLite` / `EulerLite` already exist on fork `main` — pick an unused `$2`): ``` -/scaffold scheduler HeunLite +/scaffold scheduler ``` -The agent should only run: +The agent should copy overlay templates, register the class, then invoke: ```bash -python3 ramp-kit/tools/convention_check.py src/diffusers/schedulers/scheduling_heun_lite.py -python3 -m unittest tests.schedulers.test_scheduling_heun_lite -v +python3 ramp-kit/tools/convention_check.py src/diffusers/schedulers/scheduling_.py +python3 -m unittest tests.schedulers.test_scheduling_ -v +make style +make quality +python utils/check_copies.py && python utils/check_dummies.py && python utils/check_repo.py ``` -Point at the `TODO(engineer)` in `step`. Stop. +Point at the `TODO(engineer)` in `step`. Stop. Do not skip library `make quality`. You (not the engineer paste) may still show catch-early, GrokBot, and contract re-verify from the kit: @@ -136,7 +139,7 @@ Default `make demo-contribute` **creates, proves, and deletes** (safe to run in - **30–38** judgment (schedulers first, empty default MCP, no embeddings, no auto-fix, stop at CI) - **38–45** where it breaks + `make demo-maintain` on the kit if not already shown -If time is tight, skip maintain and skip Path A’s agent: run Path B with `KEEP=1` and still open the two files. +If time is tight, skip maintain and skip Path A’s agent: run Path B with `KEEP=1` and still open the scaffolded files. --- @@ -169,5 +172,5 @@ python3 -c "import json; print(json.load(open('../diffusers/.cursor/mcp.json'))) # expected: mcpServers.diffusers-docs stdio, no huggingface ``` -If a Cloud Agent is already on the fork, the boot install is that JSON. You do not re-run attach live unless `.cursor/` is missing. Overlay clearance is still the file-scoped gate, not Hugging Face Actions. +If a Cloud Agent is already on the fork, the boot install is that JSON. You do not re-run attach live unless `.cursor/` is missing. Clearance is the file-scoped overlay gate **plus** library `make style` / `make quality`. Inherited jobs that need Hugging Face runners or size labels may still be red on this personal fork; that is hosting, not a reason to skip `make quality`. diff --git a/docs/TALK_TRACK.md b/docs/TALK_TRACK.md index 4a506b1..c5cae9b 100644 --- a/docs/TALK_TRACK.md +++ b/docs/TALK_TRACK.md @@ -58,13 +58,13 @@ open on the fork until they have seen the registry and the gate. show how the YAML was verified (`set_timesteps`, not `set_num_inference_steps`). That is not the engineer's diff. Their checklist is `ramp-kit/conventions/rules.yaml` plus the overlay templates. -2. **Scaffold.** `/scaffold scheduler HeunLite` writes - `src/diffusers/schedulers/scheduling_heun_lite.py`. Open the - `TODO(engineer)` in `step`. "Two files the gate checks. Not a sampler." -3. **File-scoped gate only** — never `--all` on this library. 0 blocking on the - new file; behavioral tests skip without torch. -4. **PR this fork**, draft, **base `main`**, title `[fork demo — not for upstream]`. Overlay - clearance ≠ Hugging Face CI. We do **not** delete inherited workflow files. +2. **Scaffold.** `/scaffold scheduler ` copies overlay templates, + registers the class, and invokes `make style` / `make quality`. Open the + `TODO(engineer)` in `step`. "Not a sampler. Library quality before the PR." +3. **File-scoped overlay gate only** — never `--all` on this library. 0 blocking + on the new file. Then library `make quality` until green. +4. **PR this fork**, draft, **base `main`**, title `[fork demo — not for upstream]`. + Overlay gate plus library quality. We do **not** delete inherited workflow files. Do not run kit `KEEP=1` before the fork agent if you want those files to appear live on the fork. diff --git a/overlay/OVERLAY.md b/overlay/OVERLAY.md index 64e2a17..e1bfa6f 100644 --- a/overlay/OVERLAY.md +++ b/overlay/OVERLAY.md @@ -3,24 +3,33 @@ This checkout is a **fork of huggingface/diffusers**. The overlay lives in a separate repo: [alex-16moro/diffuser_agent](https://github.com/alex-16moro/diffuser_agent). -Cloud Agent install clones it to `ramp-kit/` (gitignored). Do not edit -upstream `AGENTS.md` / `.ai/` — those stay Hugging Face's. +Cloud Agent install clones it to `ramp-kit/` (gitignored). + +Root `AGENTS.md` and `.ai/` stay Hugging Face's agent guide. Do not overwrite +them. A new engineer's agent should follow that guide **and** this overlay so +generated code is library-CI aligned by default (`make style`, `make quality`, +copies/dummies) plus the customer file-scoped gate. PRs from this overlay are **fork-demo only, not for upstream**. Keep them draft -and titled `[fork demo — not for upstream]`. Overlay clearance is the customer -gate (`ramp-kit/tools/convention_check.py` on the new file). Upstream GitHub -Actions may go red; that is expected — we do not claim Hugging Face's CI. +and titled `[fork demo — not for upstream]`. Do not disable inherited GitHub +workflows. Jobs that need Hugging Face's private runners or size labels may +still be red on this personal fork; that is repo-hosting, not a reason to skip +`make quality`. ## Grounding (default path — no MCP) -The first contribution is what `ramp-kit/conventions/rules.yaml` checks: +The first contribution: 1. Copy `ramp-kit/templates/scheduler/scheduling_TEMPLATE.py` and - `ramp-kit/tests/_templates/scheduler_test.py`. -2. Run the file-scoped gate on the new scheduler file. Never `--all`. + `ramp-kit/tests/_templates/scheduler_test.py`. Replace every template token. + Keep `TODO(engineer)` in `step()`. +2. Register the class in `schedulers/__init__.py`, `diffusers/__init__.py`, and + dummy objects (`python utils/check_dummies.py --fix_and_overwrite`). +3. File-scoped overlay gate on the new file. Never `--all`. +4. Invoke the library's own tooling until exit 0: `make style`, `make quality`, + `python utils/check_copies.py && python utils/check_dummies.py && python utils/check_repo.py`. -Docs search and reading `scheduling_euler_discrete.py` / `scheduling_ddpm.py` -are how the *kit* verified the YAML. They are not part of the first PR. +Do not copy `ramp-kit/examples/candidate_scheduler/`. `.cursor/mcp.json` ships **stdio `diffusers-docs` only** (`python3 -u .cursor/mcp-diffusers-docs.py`). Do not enable Hub HTTP MCP (OAuth). Cloud @@ -35,13 +44,8 @@ Hub HTTP and extra servers stay in `.cursor/mcp.optional.json`. 1. On the **kit** first: catch-early on `examples/candidate_scheduler`, then `make demo-maintain` if you show maintainability. 2. Then launch on **this fork** (`alex-16moro/diffusers`), branch `main`. -3. Scaffold writes `src/diffusers/schedulers/scheduling_.py` here - (a new unused name if EulerLite/HeunLite already exist). Gate: - `python3 ramp-kit/tools/convention_check.py ` (never `--all`). - Register the class in `schedulers/__init__.py`, `diffusers/__init__.py`, and - dummy objects. Invoke `make style`, `make quality`, and - `python utils/check_copies.py && python utils/check_dummies.py && python utils/check_repo.py` - until they exit 0. +3. `/scaffold scheduler `. Follow `.cursor/commands/scaffold.md` + (copied from the overlay). Register + library CI until green. Never `--all`. 4. Open the PR **on this fork**, not on huggingface/diffusers, **draft, base `main`**, only after those library gates pass. diff --git a/overlay/scaffold.md b/overlay/scaffold.md index 1e0360f..110ce7f 100644 --- a/overlay/scaffold.md +++ b/overlay/scaffold.md @@ -3,24 +3,35 @@ Usage: `/scaffold ` This workspace is `huggingface/diffusers` (fork). Overlay kit is `ramp-kit/` -(cloned from alex-16moro/diffuser_agent). Do not overwrite `.ai/` or root `AGENTS.md`. +(cloned from alex-16moro/diffuser_agent). + +Root `AGENTS.md` and `.ai/` are Hugging Face's agent guide. **Read them. Do not +overwrite them.** They are how the library itself wants code to look (`make +style`, `make quality`, `# Copied from`, self-review). This overlay adds the +first-contribution recipe and a customer file-scoped gate. It does not replace +the library guide. + Do not disable or guard inherited GitHub workflows. `$1` = component (`scheduler`). `$2` = PascalCase name without suffix (`PNDMLite` → `PNDMLiteScheduler`, `scheduling_pndm_lite.py`). If `scheduling_.py` already exists, pick a new unused `$2`. -Copy the overlay templates. Do not start from library scheduler source and do -not search docs for this PR. Keep `TODO(engineer)` in `step()`. +Copy the overlay templates. Do not start from library scheduler source. Keep +`TODO(engineer)` in `step()`. -## 0. Ground in the registry +## 0. Ground in the registry **and** the library guide Read `ramp-kit/conventions/rules.yaml`. Blocking ids for this contribution: SCHED001, SCHED002, SCHED003, REPRO001, DEVICE001, DEPR001, MUT001, TEST001, TEST002. -The overlay templates already satisfy them. Stay inside `.cursorignore`. Do not -read or copy `ramp-kit/examples/candidate_scheduler/`. +Read root `AGENTS.md` (and `.ai/` only as that guide directs). The templates +already satisfy the overlay registry. Library CI (`make style` / `make quality` +/ copies / dummies) is also required before the PR. + +Stay inside `.cursorignore`. Do not read or copy +`ramp-kit/examples/candidate_scheduler/`. ## 1. Paths (library layout, not the kit stand-in) @@ -71,7 +82,8 @@ Fix every **blocking** finding. Stop at 0 blocking. Do not edit `step()` math. ## 6. Library CI — invoke until green, then open the PR -Iterate until all of these exit 0. Do not reimplement them: +These are the library's own checks from `AGENTS.md`. Iterate until all exit 0. +Do not reimplement them: ```bash make style diff --git a/tests/test_tooling.py b/tests/test_tooling.py index 270f4c4..697508a 100644 --- a/tests/test_tooling.py +++ b/tests/test_tooling.py @@ -697,8 +697,12 @@ def test_attach_writes_stdio_docs_mcp(self): scaffold = (fake / ".cursor" / "commands" / "scaffold.md").read_text() self.assertIn("rules.yaml", scaffold) self.assertIn("scheduling_TEMPLATE.py", scaffold) + self.assertIn("make quality", scaffold) + self.assertIn("check_dummies.py", scaffold) + self.assertIn("AGENTS.md", scaffold) self.assertNotIn("docs_mcp_server.py", scaffold) self.assertNotIn("Those files are the contract", scaffold) + self.assertNotIn("those two files only", scaffold) def test_attach_does_not_delete_inherited_workflows(self): with tempfile.TemporaryDirectory() as td: @@ -755,11 +759,13 @@ def test_overlay_scaffold_copies_templates_not_library_source(self): self.assertIn("rules.yaml", text) self.assertIn("scheduling_TEMPLATE.py", text) self.assertIn("make style", text) - self.assertIn("check_dummies.py", text) + self.assertIn("make quality", text) + self.assertIn("AGENTS.md", text) self.assertNotIn("Those files are the contract", text) self.assertNotIn("docs_mcp_server.py", text) self.assertNotIn("scheduling_euler_discrete.py", text) self.assertNotIn("convention_check.py --all", text) + self.assertNotIn("those two files only", text) class TestOverlayPrGate(unittest.TestCase): diff --git a/tools/attach_library.py b/tools/attach_library.py index 26ea6ed..8be2b88 100755 --- a/tools/attach_library.py +++ b/tools/attach_library.py @@ -91,6 +91,7 @@ def copy_overlay(target: Path) -> None: print(" Default MCP: stdio diffusers-docs (no Hub HTTP). Cloud dropdown: diffusers-docs-mcp") print(" Fork PRs: draft, title [fork demo — not for upstream]") print(" Overlay CI: .github/workflows/ramp-kit-overlay.yml (file-scoped, never --all)") + print(" Library CI: invoke make style / make quality / check_copies / check_dummies") print(" Do not overwrite upstream AGENTS.md / .ai/; do not delete HF workflows")