| name | veomni-develop |
| description | VeOmni-specific checklist for feature development and refactoring. Covers impact analysis across modalities, trainer hierarchy, data pipeline, and distributed code. Use before implementing any non-trivial change. For model-specific or ops-specific work, use veomni-new-model or veomni-new-op instead. Trigger: 'add feature', 'implement', 'refactor', 'reorganize', 'new capability'. |
Impact Analysis
Before implementing, check which areas your change affects:
| Area | What to check | Why it matters |
|---|
veomni/trainer/ | All trainer subclasses (TextTrainer, VLMTrainer, DitTrainer, RL trainers) | Changing BaseTrainer method signatures breaks all subclasses |
veomni/data/data_collator.py | All modalities (text, VLM, DiT) | Collators are tightly coupled to model-specific preprocessing |
veomni/distributed/ | FSDP2 + ExtraParallel/MoE/SP paths | Shared distributed code is used by many downstream modalities |
veomni/models/auto.py, loader.py | Model registry, import-time side effects | MODELING_REGISTRY is populated at import time; moving registrations breaks loading |
configs/ | YAML config keys | Renaming config keys breaks existing training configs silently |
veomni/models/transformers/*/ | __init__.py registration entry points | Every transformers-family LLM/VLM/Omni model ships a patchgen-generated path under generated/; never import or call legacy modeling_<m>.py or apply_veomni_<m>_patch() (these no longer exist). The non-transformers-architecture models (flux, movqgan, wan) have no generated/ and patch through device_patch.py or direct modeling — check the directory before assuming |
Refactoring Safety Rules
When restructuring code (same behavior, better structure):
- Baseline first: run
pytest tests/ before any change, record results.
- One change per commit: ONE structural change → update ALL callers → verify tests match baseline → commit.
- Never batch multiple refactoring steps into one commit.
- Check baseline again at the end — results must be identical.
Common Traps
veomni.models.auto registration depends on import-time side effects — moving registrations into functions or delaying them breaks model loading.- Renaming config keys silently breaks existing YAML configs in
configs/ — grep all YAML files first.
veomni.distributed modules feed into ExtraParallel/MoE/SP — touching shared code may affect every modality, so run the cross-cutting parallel tests.- Data collators in
veomni/data/data_collator.py are coupled to DEFAULT_DATA_COLLATE_INFO — adding new tensor keys requires updating the collate info table.
MainCollator has strict SP ordering (pad → slice → FA kwargs → slice position_ids) — reordering breaks SP correctness.position_ids == 0 marks segment boundaries for FA varlen — any transform that produces position_ids must preserve this convention.
Documentation
Before committing, check if the change requires documentation updates:
- New/changed API → update or create docs in
docs/.
- New/changed config fields → update config examples in
configs/ and relevant docs.
- Architecture change → update
.agents/knowledge/architecture.md.
- New constraint discovered → add to
.agents/knowledge/constraints.md.
Tests
Follow .agents/knowledge/testing.md. In short: extend an existing
CI-enumerated test before creating a new file. If you do create one, check its
path against the table there and wire it into the workflow that owns that path
— the directory-level entries (tests/data/, tests/checkpoints/, tests/ops/ on GPU,
tests/parallel/context_parallel/ on GPU) need no line, e2e paths belong to
{gpu,npu}_e2e_test.yml, and everything else is invisible to CI until it is
listed. A pure refactor with existing coverage does not need a new test — say
so in the PR instead of adding one.
When to Use Other Skills
- New model →
/veomni-new-model
- New op/kernel →
/veomni-new-op
- Bug fix or debugging →
/veomni-debug
- Dependency update →
/veomni-uv-update
