Interaction Principle

Minimize confirmations. The only user confirmation is for uncommitted changes (Step 1.3). Everything after that — drafting, writing file, pushing, creating PR — runs automatically. Tool-level permission prompts (file write, git push) serve as implicit confirmation; do not add extra "are you sure?" pauses on top.

Steps

Step 1: Pre-flight Checks

1. Identify current branch:

   git branch --show-current

   If on main — stop and ask the user to create a feature branch first.

2. Determine base branch: use main unless the user specifies otherwise.

3. Check for uncommitted changes (only confirmation point):

   git status
   git diff --stat

   If there are staged or unstaged changes, show a summary and ask the user:

   "There are uncommitted changes. Commit them before creating the PR?"

   • If yes: run make quality, stage relevant files (skip .env, credentials, large binaries), commit.
   • If no: proceed with what's already committed.
   • If make quality fails: stop and report errors.

4. Check for existing PR on this branch:

   gh pr view --json number,title,body 2>/dev/null

   Note the PR number if one exists.

5. Check commits ahead of base:

   git log origin/main..HEAD --oneline

   If the branch has no commits ahead of main, stop — nothing to open a PR for.

Step 2: Analyze Changes (automatic)

1. Collect the full diff against the base branch:

   git diff main...HEAD
   git log main..HEAD --oneline

2. Identify affected modules by mapping changed file paths to allowed module names:

   Path prefix	Module
   veomni/models/	model
   veomni/trainer/	trainer
   veomni/data/	data
   veomni/distributed/	dist
   veomni/parallel/	parallel
   veomni/ops/	ops
   veomni/checkpoint/	ckpt
   veomni/optim/	optim
   veomni/logging/	logging
   veomni/lora/	lora
   configs/	config
   docs/	docs
   tests/, .github/workflows/	ci
   docker/	docker
   tasks/	task
   veomni/omni/	omni
   .agents/	agent
   other / mixed	misc

   Allowed modules: misc, ci, config, docs, data, dist, omni, logging, model, optim, ckpt, release, task, perf, ops, parallel, docker, trainer, agent, lora

3. Determine change type:

   Type	When
   feat	New functionality or capability
   fix	Bug fix
   refactor	Same behavior, better structure
   chore	Maintenance, cleanup, config changes
   test	Test-only changes

Step 3: Generate Draft File and Push (automatic)

1. Draft PR title in [{modules}] {type}: {description} format:

   • Multiple modules separated by comma: [model, data] feat: ...
   • Description: concise, lowercase start, no period, under 60 chars
   • Breaking changes: prepend [BREAKING]
   • Must pass the regex in .github/workflows/check_pr_title.yml

2. Draft PR description following .github/PULL_REQUEST_TEMPLATE.md.

3. Write to .pr-drafts/ (already in .gitignore):

   mkdir -p .pr-drafts

   Filename convention:

   • Existing PR: .pr-drafts/<pr-number>.md (e.g. .pr-drafts/123.md)
   • New PR: .pr-drafts/<branch-name>.md — renamed to PR# after creation.

   File format — first line is the PR title, blank line, then the description body:

   [model] feat: add support for Qwen4
   
   ### What does this PR do?
   
   > Summary here.
   
   ### Checklist Before Starting
   
   - Search for relative PRs/issues and link here: ...
   - PR title follows `[{modules}] {type}: {description}` format
   
   ### Test
   
   > Test description here.
   
   ### API and Usage Example
   
   > N/A
   
   ### Design & Code Changes
   
   > - Change 1
   > - Change 2
   
   ### Checklist Before Submitting
   
   - [ ] Read the [Contribute Guide](https://github.com/ByteDance-Seed/VeOmni/blob/main/CONTRIBUTING.md)
   - [ ] Applied pre-commit checks
   - [ ] Added/updated documentation
   - [ ] Added tests to CI workflow (or explained why not feasible)

4. Tell the user the draft file path (so they know where to find it if they want to review later).

Step 4: Push and Create/Update PR (automatic, immediately after Step 3)

1. Push the branch:

   git push -u origin HEAD

2. Create or update:

   • New PR (use --body-file to avoid shell escaping issues):

     # Extract body from draft file (everything after the first blank line)
     tail -n +3 .pr-drafts/<branch-name>.md > /tmp/pr-body.md
     gh pr create --base <base-branch> --title "<title>" --body-file /tmp/pr-body.md

     After creation, rename the draft file from <branch-name>.md to <pr-number>.md.
   • Existing PR:

     tail -n +3 .pr-drafts/<pr-number>.md > /tmp/pr-body.md
     gh pr edit <pr-number> --title "<title>" --body-file /tmp/pr-body.md

3. Output the PR URL and the draft file path.

Common Pitfalls

• Title format is enforced by CI — a malformed title will block the PR. Always validate against the allowed modules and types listed above.
• Don't force-push unless the user explicitly asks.
• Check for sensitive files before committing — skip .env, credentials, large binaries and warn the user.