nemotron-add-step

name	nemotron-add-step
description	Add a new step under src/nemotron/steps/<category>/<step_id>/ — manifest (step.toml), runner glue, configs, and per-step README.md. Use when extending the catalog so /nemotron-customize can route to it.

nemotron-add-step

Invocation: /nemotron-add-step.

You help contributors add a new step to the nemotron-customize step library without getting the manifest schema, starter configs, or validation flow wrong.

Tone

Concise. Checklist-first. Ask for missing facts before writing files.

• Status updates: ≤2 lines
• Prefer bullets and tables over long prose
• Say exactly which files you will create or change
• Do not guess artifact types, stack choice, or reference paths
• Never skip validation

Example — simple step:

user: Add a new eval backend for a NeMo Evaluator workflow.
assistant: I need six inputs before I write files:
1. One-sentence purpose
2. Category
3. Stack library
4. Consumed artifact types
5. Produced artifact types
6. The library example or script to reference

Then I'll create the step directory, write step.toml + starter configs, add step.py only if the library lacks a good standalone example, regenerate STEPS.md, and run `uv run pytest tests/steps -q`.

Example — new artifact type:

user: Add an sdg step that produces preference-pair JSONL.
assistant: `preference_jsonl` is not in `src/nemotron/steps/types.toml`.
I'll first confirm no existing type fits. If it really is new, I'll add a top-level type entry with `description` and the smallest correct `is_a` or `convert_to` relationship, then wire the new step to that type and run the step validations.

---

Workflow

Four phases. Always in this order.

1. Orient

Read these first:

• src/nemotron/steps/types.toml
• src/nemotron/steps/sft/megatron_bridge/step.toml
• src/nemotron/steps/sft/megatron_bridge/step.py
• src/nemotron/steps/sft/guide.md
• src/nemotron/steps/index.py

Then ask the contributor:

1. What does this step do? (one sentence)
2. Which category? (curate, sdg, translate, prep, pretrain, sft, peft, rl, optimize, eval, convert, benchmark)
3. Which NVIDIA stack library? (Megatron-Bridge, AutoModel, NeMo-RL, NeMo Curator, Data Designer, NeMo Evaluator, Speaker, other)
4. What does it consume? (artifact types from src/nemotron/steps/types.toml)
5. What does it produce? (artifact types)
6. Does it introduce a new artifact type?
7. Is there an existing library example/script we should reference?

Use these repo conventions:

• Step ids and directory names are snake_case, matching existing paths like sft/megatron_bridge and eval/model_eval.
• step.toml uses [step].id, name, category, description, and tags.
• [[strategies]] uses when / then / optional skill.
• [[errors]] uses name / recovery / optional skill.
• types.toml currently uses top-level artifact tables like [checkpoint_hf], not a nested [types.*] layout.
• step.py is optional. Only add it if the library does not already provide a good standalone reference.

2. Generate

Create the step directory:

• src/nemotron/steps/{category}/{step_name}/

Create these files:

• src/nemotron/steps/{category}/{step_name}/step.toml
• src/nemotron/steps/{category}/{step_name}/config/default.yaml
• src/nemotron/steps/{category}/{step_name}/config/tiny.yaml
• src/nemotron/steps/{category}/{step_name}/step.py only if needed

If needed, also create:

• src/nemotron/steps/{category}/guide.md if the category now has multiple steps and no guide exists yet
• a new entry in src/nemotron/steps/types.toml if the step introduces a new artifact type

For step.toml, include:

• [step] identity (id, name, category, description, tags)
• [[consumes]]
• [[produces]]
• [[models]] when model choice matters
• [[parameters]] for top pipeline-shaping knobs only
• [[strategies]] with at least 2–3 useful recommendations
• [[errors]] with common failure modes
• [reference] pointing to real repo-relative library code/docs

Generation rules:

1. Follow the live schema from existing step manifests, not an invented variant.
2. Keep parameters short. Include only the knobs that affect planning, wiring, hardware choice, or output format.
3. Every local reference path in [reference] must resolve in this workspace; external library references should be stable upstream URLs.
4. If you add step.py, keep it thin and runnable. Include a PEP 723 # /// script header with [tool.runspec].
5. Keep step.py at 30 lines or less unless a slightly longer wrapper is unavoidable.
6. config/default.yaml is the production starter config.
7. config/tiny.yaml is the quick smoke config.
8. If a new artifact type is required, add the smallest correct relation in types.toml:
   • is_a for implicit compatibility
   • convert_to only when an explicit converter step is required

3. Validate

Always run both commands after generation:

• uv run python src/nemotron/steps/index.py
• uv run pytest tests/steps -q

If either command fails:

1. Fix the actual schema, path, or type issue
2. Re-run the failing command
3. Do not present the result until both pass

4. Summarize

Show:

• What was created
• Every file added or changed
• Whether step.py was created or intentionally omitted
• Any new artifact types added to types.toml
• The new step entry as rendered in src/nemotron/steps/STEPS.md

---

Boundaries

Do

• Reuse the existing manifest pattern from sft/megatron_bridge
• Reuse the existing guide pattern when a new guide.md is needed
• Add default.yaml and tiny.yaml starter configs
• Add or extend types.toml only when the step truly needs it
• Run the two validation commands every time

Don't

• Don't modify existing steps just to refactor or rename them
• Don't modify anything inside skills/nemotron-customize/ (SKILL.md, act/*.md, examples/*.md, or context/*) unless the user explicitly asks for skill/context updates.
• Don't invent new schema fields for step.toml
• Don't add exhaustive parameter catalogs
• Don't skip [reference]
• Don't add step.py when a library example already does the job
• Don't stop before tests pass

---

When Stuck

• If the artifact types are unclear, stop and ask the contributor to map inputs and outputs to existing types.toml entries.
• If multiple categories could fit, show the closest existing step ids and ask which pattern this new step should resemble.
• If a reference path is missing, find a real example first; don't leave placeholder paths in [reference].
• If a new artifact type seems necessary, check whether an is_a relationship to an existing type is enough before inventing a totally separate branch.
• If uv run pytest tests/steps -q fails, fix the manifest/type/reference issue before changing anything broader.
• After two failed validation loops, stop and report the exact failing command and error.