# Veomni Develop

> Veomni 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'.

- Skill name: `veomni-develop`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/ByteDance-Seed/VeOmni/blob/HEAD/.agents/skills/veomni-develop/SKILL.md
- Repository: ByteDance-Seed/VeOmni (2,088 GitHub stars when collected)

## SKILL.md

## 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):

1. **Baseline first**: run `pytest tests/` before any change, record results.
2. **One change per commit**: ONE structural change → update ALL callers → verify tests match baseline → commit.
3. **Never batch multiple refactoring steps into one commit.**
4. 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`.

## 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`

---

Source: https://www.openparable.com/skill/development/veomni-develop (OpenParable). Cite the canonical URL above.
