Agent Workflow Guide

Agent Workflow Guide#

VeOmni provides a skill-based workflow system that helps AI coding agents work on the project effectively. Skills follow the Agent Skills open standard and work with any compatible agent (Cursor, Claude Code, Codex, Junie, Goose, etc.).

Overview#

The workflow consists of three layers:

AGENTS.md                      <- Entry point: principles, skill dispatch, commit flow
.agents/skills/                <- Skills: step-by-step workflows for common tasks
.agents/knowledge/             <- Knowledge: constraints, architecture, dependency info
.cursor/rules/                 <- IDE rules: Cursor-specific coding conventions

When an agent opens the project, it reads AGENTS.md (or its symlink CLAUDE.md) to understand:

  • What constraints to follow before making any change

  • Which skill to use for the task at hand

  • How to commit (mandatory code review gate)

Quick Start#

For AI Agent Users#

If you are using Cursor or another AI coding tool on this project, the workflow activates automatically:

  1. The agent reads AGENTS.md on session start.

  2. For each task, the agent selects the appropriate skill from the dispatch table (or auto-discovers it via the description frontmatter).

  3. The agent reads the skill’s SKILL.md and follows its step-by-step instructions.

  4. Before committing, the agent runs the /veomni-review skill (a subagent code review).

You don’t need to do anything special — just describe your task in natural language. You can also invoke a specific skill with /skill-name in chat (e.g., /veomni-debug).

Examples#

What you say

Agent uses

“Add support for Llama 4”

/veomni-new-model

“Fix the OOM error in VLM training”

/veomni-debug

“Add a fused RoPE kernel”

/veomni-new-op

“Refactor the data collator”

/veomni-develop

“Update torch to 2.10”

/veomni-uv-update

Directory Structure#

.agents/skills/#

Each skill is a folder containing a SKILL.md file with YAML frontmatter (name and description):

.agents/skills/
├── veomni-develop/SKILL.md    # Feature development and refactoring
├── veomni-debug/SKILL.md      # Bug fix and debugging (quick path + full protocol)
├── veomni-review/SKILL.md     # Pre-commit code review (mandatory)
├── veomni-new-model/SKILL.md  # Add a new model to VeOmni
├── veomni-new-op/SKILL.md     # Add a new kernel/operator
└── veomni-uv-update/SKILL.md  # Dependency management with uv

The description field in frontmatter tells the agent when to apply the skill. Agents that support auto-discovery (Cursor, Claude Code) will offer the relevant skill automatically based on the task description.

.agents/knowledge/#

Domain knowledge that agents should read before making changes:

File

Content

constraints.md

22 hard constraints — violating any one causes bugs or crashes

architecture.md

Module map, trainer hierarchy, data flow, model loading flow, test mapping

uv.md

Dependency management architecture (uv, extras, lockfile, torch sources)

.cursor/rules/#

Cursor IDE rules (auto-applied when editing matching files):

  • no-section-divider-comments.mdc — no decorative # ---- banners in Python

  • skills-reusable-only.mdc — enforce Agent Skills standard format in .agents/skills/

Adding a New Skill#

  1. Create .agents/skills/<skill-name>/SKILL.md with YAML frontmatter:

---
name: skill-name
description: "When to use this skill. Trigger words and scenarios."
---

  1. Add the skill to the dispatch table in AGENTS.md.

  2. Add it to the Skill Index in .agents/skills/README.md.

  3. If the skill needs domain knowledge, add it to .agents/knowledge/.

  4. Optional: add scripts/, references/, or assets/ subdirectories.

See the Agent Skills specification for the full format.

Adding Domain Knowledge#

  1. Create or edit a .md file in .agents/knowledge/.

  2. Reference it from the Context Loading section in AGENTS.md.

  3. If the knowledge contains hard rules, add them to constraints.md.

Commit Flow#

The agent workflow enforces a structured commit flow:

Code Change -> /veomni-review (subagent) -> Verdict
                                             |
                                     safe -> commit
                              needs-attention -> fix, then commit
                                     risky -> report to user, wait

Additional gates:

  • make quality must pass (ruff check + format)

  • Commit messages must not mention AI/Claude

  • PR title must follow [{modules}] {type}: {description} format