Skip to content

Agent workflows

The agents/ folder of the repository holds the procedures we use to work on Steel scenes: tune a scene, debug an instability, validate a solver change, add an example, port a project from PhysX. Each is plain Markdown with exact commands, pass and fail criteria and the evidence to keep. Any coding agent can follow them, and so can a person; nothing in them depends on one agent product.

You want toWorkflowDone when
make one Steel scene stable or faster, or pick its presetTune a scenethe settings you ship pass shelf check, cover the whole task with zero dropped rows, and their frames look right.
find out why a Steel scene explodes, jitters, sinks, slips or overflowsDebug instabilitythe cause is named with evidence, the fix passes the scene's gates over the whole task, or the report says why no setting can fix it.
know whether a Newton or Steel change breaks or slows any exampleValidate a solver changeboth revisions were rendered and checked on the same examples, every grade change is explained, and speed changes on the flagged scenes are measured.
add a scene to the collection, or give an example a Steel presetAdd an exampleshelf check EXAMPLE --every reports works for every filled table, the example renders and looks right, and PRESETS.md is regenerated.
move a PhysX project to SteelPort from PhysXthe upgraded-PhysX gate and the Steel parity check pass or every difference is explained, randomized and performance comparisons are matched and free of capacity loss, and a fresh checkout runs both backends.
  1. Workflows 5

    agents/workflows/

    A goal: when to use it, inputs, steps in order, decision points, exit criteria, deliverables.

  2. Steps 11

    agents/steps/

    One procedure: inputs, exact commands, pass and fail criteria, outputs. Calls tools, never a workflow.

  3. Tools code

    examples/

    shelf list, play, bench, tune, check, trial, autotune, advise; the render audit. All the logic lives here.

A workflow puts steps in order and says what to do at each decision point; a step is one procedure you can run on its own; the tools hold all the logic, so a workflow never asks anyone to re-derive a rule in prose. Every README opens with three summary lines (Goal, Use when, Done when for a workflow; Does, Use in, Passes when for a step), and commands run from the repository root unless a step says cd examples. Every step is on the steps page.

  • AGENTS.md. The repository root’s AGENTS.md points at agents/README.md, the catalog with the table above. Coding agents that read AGENTS.md start there; examples/AGENTS.md has the rules for changing an example or a preset.
  • By name. Point an agent, or yourself, at a workflow’s README: “follow agents/workflows/tune-a-scene/README.md for crane_wrecking_ball”.
  • Adapters (optional). Some tools discover procedures in skill folders. python agents/make_adapters.py writes one pointer per workflow, .claude/skills/steel-<workflow>/SKILL.md, holding the workflow’s summary as front matter and one link to its README. The README stays the only copy of the procedure; --check fails when a pointer is stale, so never edit one by hand.
  • The tools. From examples/: uv run python -m shelf trial runs one example’s whole episode with Steel and lists what is wrong in fix order, shelf autotune repeats trials until no fix is left and then keeps cheaper settings that stay healthy, shelf advise re-reads a recorded trial, and scripts/render_audit/ renders and grades examples with their Steel presets.

    Terminal window
    cd examples
    uv run python -m shelf trial crane_wrecking_ball --out outputs/crane_t0
    uv run python -m shelf autotune crane_wrecking_ball --start defaults --out outputs/crane_tune
  • The guides. The Steel tuning guide in the repository, with the measurements behind each rule and a validation of shelf autotune against hand-tuned presets, and on this site Tuning, Troubleshooting and Porting from PhysX.

  • The examples’ own checks. shelf check is the acceptance for a preset; the advisor’s health and the render grades are screens in front of it.

To write a new workflow or step, see Add a workflow.