From 685cef84cfcbeb2714a6ed58d8eae6a7db6c424d Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Fri, 4 Sep 2026 23:53:42 +0200 Subject: [PATCH 1/6] modular guide: helpers take explicit arguments, not `components` Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HCdbvRpL9fv3h3WwSUPpfS --- .ai/references/modular.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.ai/references/modular.md b/.ai/references/modular.md index 8bfb39ebb999..5ea6b8cd7a14 100644 --- a/.ai/references/modular.md +++ b/.ai/references/modular.md @@ -317,6 +317,8 @@ ComponentSpec( 10. **Raw `torch.randn(device=...)` for noise.** Use `randn_tensor(...)` from `utils/torch_utils`: it draws on the generator's device and moves the result, so CPU generators (what the test mixins pass) work, and the CUDA-generator path is bit-identical to `torch.randn`. +11. **Module-level helpers taking `components`.** Helper functions shared by blocks (prompt encoding, packing, latent retrieval) take explicit arguments for what they actually use — specific components and values, like `get_qwen_prompt_embeds(text_encoder, tokenizer, prompt, ...)` in `qwenimage/encoders.py` — not the whole `components` object. `components` is the block-call protocol; a helper that takes it hides its real dependencies and can only run with a fully assembled pipeline. (`ltx2/encoders.py`'s `_get_gemma_prompt_embeds(components, ...)` predates this rule — don't copy it.) + ## Conversion checklist - [ ] Read original pipeline's `__call__` end-to-end, map stages From 5a6a968d4fc61f1dcc5091cf9971f130d1b6460f Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Sat, 5 Sep 2026 00:48:33 +0200 Subject: [PATCH 2/6] agent guide: human-in-the-loop rules, helpers take explicit arguments Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HCdbvRpL9fv3h3WwSUPpfS --- .ai/AGENTS.md | 8 ++++++++ .ai/references/modular.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index e069c71966a1..7f230acc0947 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -49,6 +49,14 @@ codex plugin marketplace add huggingface/diffusers # then install from the Pl ``` +## Human in the loop + +Everything a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. Keep every draft short and easy to digest — a human has to genuinely read it before it goes out. + +- **Don't commit unless the user approved the exact commit message, and never push or open a PR on + your own.** The user decides when anything is published, each time. +- **Don't post to GitHub directly** — no comments, reviews, or replies. Draft when asked and hand the text to the user. + ## Code formatting - `make style` and `make fix-copies` should be run before opening a PR diff --git a/.ai/references/modular.md b/.ai/references/modular.md index 5ea6b8cd7a14..31b97a9401eb 100644 --- a/.ai/references/modular.md +++ b/.ai/references/modular.md @@ -317,7 +317,7 @@ ComponentSpec( 10. **Raw `torch.randn(device=...)` for noise.** Use `randn_tensor(...)` from `utils/torch_utils`: it draws on the generator's device and moves the result, so CPU generators (what the test mixins pass) work, and the CUDA-generator path is bit-identical to `torch.randn`. -11. **Module-level helpers taking `components`.** Helper functions shared by blocks (prompt encoding, packing, latent retrieval) take explicit arguments for what they actually use — specific components and values, like `get_qwen_prompt_embeds(text_encoder, tokenizer, prompt, ...)` in `qwenimage/encoders.py` — not the whole `components` object. `components` is the block-call protocol; a helper that takes it hides its real dependencies and can only run with a fully assembled pipeline. (`ltx2/encoders.py`'s `_get_gemma_prompt_embeds(components, ...)` predates this rule — don't copy it.) +11. **Helpers taking `components`.** For example, instead of `def get_xx_prompt_embeds(components, prompt)`, write `get_xx_prompt_embeds(text_encoder, tokenizer, prompt)`: helper functions and block methods take the specific components and values they use as explicit arguments, so their dependencies are visible and they can run without an assembled pipeline. Only `__call__` takes `components` — it unpacks what its helpers need. See `get_qwen_prompt_embeds` in `qwenimage/encoders.py`. ## Conversion checklist From 45247b6dce45adbe387c6fe4cfd2419543d603c3 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Sat, 5 Sep 2026 00:51:17 +0200 Subject: [PATCH 3/6] clarify human-in-the-loop scope to communication Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HCdbvRpL9fv3h3WwSUPpfS --- .ai/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 7f230acc0947..311dbf1bebab 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -51,7 +51,7 @@ codex plugin marketplace add huggingface/diffusers # then install from the Pl ## Human in the loop -Everything a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. Keep every draft short and easy to digest — a human has to genuinely read it before it goes out. +All the communication a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. Keep every draft short and easy to digest — a human has to genuinely read it before it goes out. - **Don't commit unless the user approved the exact commit message, and never push or open a PR on your own.** The user decides when anything is published, each time. From 54b500c3bf098f7f47a79df24a21b07b351002eb Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Sun, 6 Sep 2026 22:28:58 +0200 Subject: [PATCH 4/6] contribution guide + agent guide: PR communication must be concise and human-readable Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HCdbvRpL9fv3h3WwSUPpfS --- .ai/AGENTS.md | 2 +- docs/source/en/conceptual/contribution.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 311dbf1bebab..2b4d30a91644 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -51,7 +51,7 @@ codex plugin marketplace add huggingface/diffusers # then install from the Pl ## Human in the loop -All the communication a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. Keep every draft short and easy to digest — a human has to genuinely read it before it goes out. +All the communication a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. If you're preparing the draft, keep every message concise and easy to digest. When you hand a draft over, remind the user that they need to genuinely read it and make sure it reads well for *other* humans. - **Don't commit unless the user approved the exact commit message, and never push or open a PR on your own.** The user decides when anything is published, each time. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index 090bfd456774..a059e194556e 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -608,6 +608,7 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. - **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill — it reviews your diff against [`.ai/references/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/references/review-rules.md), the same rubric the `@claude` CI reviewer uses — and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. - **Share your self-review notes.** Please post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. It helps the reviewer see what has already been checked and which calls were deliberate, and usually saves a few rounds of back-and-forth. +- **Keep your PR communication concise.** Everything a reviewer reads on your PR — the description, commit messages, comments and replies, code comments — must be easy for a human to understand. If your agent drafted it, don't just skim it: read it, and ask the agent to revise until it says something sensible, concisely, that you would write yourself. You are the author of everything you post. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). From 64737f0a703fc51313a13492050eceb10d2214d0 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Sun, 6 Sep 2026 16:23:43 -1000 Subject: [PATCH 5/6] Apply batched suggestions from code review Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- .ai/AGENTS.md | 2 +- .ai/references/modular.md | 2 +- docs/source/en/conceptual/contribution.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 2b4d30a91644..b72a42b98461 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -51,7 +51,7 @@ codex plugin marketplace add huggingface/diffusers # then install from the Pl ## Human in the loop -All the communication a PR reviewer sees must come directly from a human, or be explicitly approved by one for the exact content. This covers commit messages, code comments and docstrings, PR titles and descriptions, and any PR/issue comment, review, or reply. Ask whether the user prefers that you write a draft or that they prepare it themselves. If you're preparing the draft, keep every message concise and easy to digest. When you hand a draft over, remind the user that they need to genuinely read it and make sure it reads well for *other* humans. +Everything a PR reviewer sees must come from a human, or be approved by one for the exact wording. That includes commit messages, code comments and docstrings, PR titles and descriptions, and any PR or issue comment, review, or reply. Ask whether the user wants you to draft that text or will write it themselves. Keep drafts short and easy to can. When you hand one over, remind them to read it for real and check that it reads well for other humans. - **Don't commit unless the user approved the exact commit message, and never push or open a PR on your own.** The user decides when anything is published, each time. diff --git a/.ai/references/modular.md b/.ai/references/modular.md index 31b97a9401eb..9411d5ee6c37 100644 --- a/.ai/references/modular.md +++ b/.ai/references/modular.md @@ -317,7 +317,7 @@ ComponentSpec( 10. **Raw `torch.randn(device=...)` for noise.** Use `randn_tensor(...)` from `utils/torch_utils`: it draws on the generator's device and moves the result, so CPU generators (what the test mixins pass) work, and the CUDA-generator path is bit-identical to `torch.randn`. -11. **Helpers taking `components`.** For example, instead of `def get_xx_prompt_embeds(components, prompt)`, write `get_xx_prompt_embeds(text_encoder, tokenizer, prompt)`: helper functions and block methods take the specific components and values they use as explicit arguments, so their dependencies are visible and they can run without an assembled pipeline. Only `__call__` takes `components` — it unpacks what its helpers need. See `get_qwen_prompt_embeds` in `qwenimage/encoders.py`. +11. **Helpers taking `components`.** Prefer explicit args, for example, `get_xx_prompt_embeds(text_encoder, tokenizer, prompt)` instead of `get_xx_prompt_embeds(components, prompt)`. Helpers and block methods should take only what they use so dependencies are visible and they can run without an assembled pipeline. Leave the full `components` object to `__call__`, which unpacks what its helpers need. See `get_qwen_prompt_embeds` in `qwenimage/encoders.py`. ## Conversion checklist diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index a059e194556e..285613641d53 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -608,7 +608,7 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. - **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill — it reviews your diff against [`.ai/references/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/references/review-rules.md), the same rubric the `@claude` CI reviewer uses — and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. - **Share your self-review notes.** Please post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. It helps the reviewer see what has already been checked and which calls were deliberate, and usually saves a few rounds of back-and-forth. -- **Keep your PR communication concise.** Everything a reviewer reads on your PR — the description, commit messages, comments and replies, code comments — must be easy for a human to understand. If your agent drafted it, don't just skim it: read it, and ask the agent to revise until it says something sensible, concisely, that you would write yourself. You are the author of everything you post. +- **Keep your PR communication concise.** Everything a reviewer reads on your PR — the description, commit messages, comments and replies, code comments — must be easy for a human to understand. If your agent drafted it, don't just skim it. Read it, and ask the agent to revise until it says something sensible and concise that you would write yourself. You are the author of everything you post. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). From 3e12ce6926341f7cfaa127e8a77ba3ea8eb0a6da Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Sun, 6 Sep 2026 16:26:12 -1000 Subject: [PATCH 6/6] Apply suggestion from @yiyixuxu --- .ai/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index b72a42b98461..5afe68c7ebfa 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -51,7 +51,7 @@ codex plugin marketplace add huggingface/diffusers # then install from the Pl ## Human in the loop -Everything a PR reviewer sees must come from a human, or be approved by one for the exact wording. That includes commit messages, code comments and docstrings, PR titles and descriptions, and any PR or issue comment, review, or reply. Ask whether the user wants you to draft that text or will write it themselves. Keep drafts short and easy to can. When you hand one over, remind them to read it for real and check that it reads well for other humans. +Everything a PR reviewer sees must come from a human, or be approved by one for the exact wording. That includes commit messages, code comments and docstrings, PR titles and descriptions, and any PR or issue comment, review, or reply. Ask whether the user wants you to draft that text or will write it themselves. Keep drafts short and easy to understand. When you hand one over, remind them to read it for real and check that it reads well for other humans. - **Don't commit unless the user approved the exact commit message, and never push or open a PR on your own.** The user decides when anything is published, each time.