Veomni Develop
Developmentveomni-developVeomni Develop is an Agent Skill for development published in the ByteDance-Seed/VeOmni repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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'.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ByteDance-Seed/VeOmni/blob/HEAD/.agents/skills/veomni-develop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/veomni-develop, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 | All models ship a patchgen-generated v5 path under generated/; never import or call legacy modeling_<m>.py or apply_veomni_<m>_patch() (these no longer exist) |
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.autoregistration 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.distributedmodules 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.pyare coupled toDEFAULT_DATA_COLLATE_INFO— adding new tensor keys requires updating the collate info table. MainCollatorhas strict SP ordering (pad → slice → FA kwargs → slice position_ids) — reordering breaks SP correctness.position_ids == 0marks 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.
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