Hugging Face's logo

Spaces:
mcuo
/
LTX2.3-Studio
Paused

App Files Community
LTX2.3-Studio / CLAUDE.md
techfreakworm's picture
techfreakworm
docs(claude): expand project guidelines with TDD discipline, commit format, common pitfalls
9a263a3 unverified
preview code
|
Raw
History Blame
7.68 kB

Project Guidelines — ltx2.3-AIO-generator

Working notes for AI assistants and subagents implementing this project.

⚠ Git authorship — sole author rule

Mayank Gupta is the sole author on every commit in this repo. No exceptions.

When committing:

  • Do NOT append Co-Authored-By: Claude ... (or any other agent name) to commit messages.
  • Do NOT add "Generated with Claude Code", "🤖 Generated with...", or any other attribution footer.
  • Do NOT pass --author=... — let git use the user's existing config.
  • Do NOT include attribution in PR descriptions.

If asked to amend, re-commit, or rebase, strip any prior agent attribution from the commit message.

This rule overrides the default Claude Code commit-message template. Treat any tooling that suggests adding a Claude trailer as a bug to ignore.

Project overview

Gradio app wrapping the existing ComfyUI LTX 2.3 All-In-One workflow into mode-specific UIs. Same code runs locally (Apple Silicon MPS / NVIDIA CUDA) and on Hugging Face Spaces (ZeroGPU, Pro tier).

Spec: docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md Plan: docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md

If you're a subagent picking up a task, the plan file is your assignment.

Architectural facts (locked — do not relitigate)

  1. Backend is ComfyUI in library mode. We call comfy.execution.PromptExecutor directly with workflow JSONs we parameterize. We do not call ltx-pipelines directly. We do not run ComfyUI as a subprocess.
  2. Six mode-specific workflow JSON files in workflows/, derived from the master at ~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json via tools/extract_modes.py. Do not hand-edit them.
  3. Models live in HF cache (local) or /data (Spaces). Never in this repo. comfyui/models/ contains symlinks (local) or downloaded files (Spaces). Never commit *.safetensors, *.gguf, *.bin, or *.pt.
  4. One backend, one process. The @spaces.GPU decorator is the only divergence between local and Spaces runtimes.
  5. VRAM is ComfyUI's job. The only empty_cache() calls live in backend.py's try/finally. Don't sprinkle them elsewhere.
  6. Bundled ComfyUI, never user's existing. Local: git submodule. Spaces: runtime clone to /data/comfyui.

Coding conventions

Language and structure

  • Python 3.11. No match statements (Spaces Python pin compatibility).
  • Flat layout. No src/, no nested packages. Top-level .py files only, each with one clear responsibility.
  • No conda. Always python3.11 -m venv .venv. System binaries via brew.

Style

  • No emojis in code or commit messages unless the user explicitly asks. (UI text and stage labels in modes.py/ui.py are OK because they are user-facing — not code.)
  • Comments only for non-obvious WHY. Never narrate WHAT. Code with a good name doesn't need a comment.
  • Type hints on public functions. Internal helpers can skip them if obvious.
  • Imports at top of file. No inline imports except where needed to break circular dependencies (e.g., models.ensure_models_for_mode imports workflow lazily — keep this, it's load-bearing).
  • Format with ruff format. Lint with ruff check. Both must pass in CI.

Testing

  • TDD per the plan. Each implementation task has the failing test first. Don't skip the "run test, verify it fails" step — it catches whole classes of "test never actually exercised the code" bugs.
  • No mocks for ComfyUI. Tests run against real workflow JSONs. Stubs only for HTTP boundaries (HF Hub) and filesystem (use tmp_path and the fake_hf_cache fixture).
  • L1 + L3 in CI (no GPU). L2 + L4 are local-developer-only.
  • Test naming: test_<unit>_<behavior_under_test> — e.g., test_load_template_returns_independent_copy.
  • pytest --gpu enables L4 smoke tests. Default skips them.
  • pytest --comfy-real uses bundled ComfyUI for L2 instead of the static stub validator.

Commits

  • Conventional Commits style: <type>(<scope>): <subject> — types: feat, fix, chore, docs, test, refactor, ci, perf.
  • Subject is imperative, lowercase, no trailing period. Example: feat(workflow): set_input + validate over node graph.
  • Body explains WHY when not obvious. Reference spec section if relevant.
  • Frequent small commits. One logical change per commit. The plan's task structure already reflects this.
  • No agent attribution (see top of file).

Editing the master workflow

When the user updates ~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json (e.g., adds a LoRA, tweaks a sampler), regenerate the mode templates:

python3.11 tools/extract_modes.py \
  --master ~/Projects/comfyui/user/default/workflows/"1. LTX 2.3 All-In-One 260406-05.json" \
  --out workflows

Then run the test suite — L2 graph-validation catches any node that became invalid in any mode.

After the templates regenerate, the node-id constants in modes.py (e.g., T2V_NODE_PROMPT = 240) may need updating if ComfyUI re-numbered nodes during the master's re-export. The procedure is in the plan's Task 11 Step 4.

Common pitfalls (read before opening a PR)

  • Loading models eagerly at import time. Don't. backend.py constructs PromptExecutor once at instantiation; models load only when nodes execute. Calling comfy.sd.load_checkpoint(...) at module top-level will OOM the test runner.
  • Hard-coded torch.cuda calls. Use comfy.model_management.get_torch_device() or guard with if torch.cuda.is_available(). Never assume CUDA.
  • Forgetting .deepcopy on workflow templates. workflow.load_template already does this; if you bypass it for performance, you'll mutate the cached template and the second Generate click breaks.
  • Hand-editing workflows/<mode>.json. They're generated. If you need a new field, add it to tools/extract_modes.py (or to modes.py's parameterize_fn).
  • Symlinks pointing into pip cache. Resolve to HF Hub's cache snapshot path (the one hf_hub_download returns), not pip's wheel cache.
  • Adding Co-Authored-By because tooling suggests it. See top of file. Strip it.
  • Breaking the async generator pattern in backend.submit. Each yield is a frame Gradio renders. Don't accumulate events into a list and yield once at the end — progress will appear stuck.
  • Importing comfy.* before sys.path.insert(0, comfy_dir). Will ModuleNotFoundError. The order in backend.py:__init__ is intentional.

Out of scope for v1 (do not implement without asking)

These are documented as v1.1+ in spec § 11. Don't pre-build them just because they'd be easy:

  • Lite mode (LTX23_AIO_LITE=1) for free HF Spaces tier
  • Custom LoRA add/remove rows (Power-Lora-Loader clone)
  • GGUF Q4 transformer / "Low VRAM" preset
  • Auto-launch of user's external ComfyUI (LTX23_AIO_COMFYUI_URL)
  • Multi-prompt queueing
  • Output history persistence across sessions
  • Visual regression tests for the Gradio UI
  • Property-based / fuzz testing of workflow parameters

If a task feels like it needs one of these, stop and ask the user. Don't sneak it in.

When in doubt

Read the spec (docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md) and the plan (docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md). If still unclear after reading both — ask the user before changing architectural shape.

Reading both takes 15 minutes. Implementing the wrong thing takes a day.