dart-model-upgrade

Use this skill to run the DART dart-model-upgrade workflow. The editable workflow source lives in .claude/commands/; this generated skill is its entrypoint for Codex and Muse.

Invocation

• Claude Code: /dart-model-upgrade <arguments>
• Codex: $dart-model-upgrade <arguments>
• Muse: /dart-model-upgrade <arguments>

Treat the text after the skill name, or the user's request when the skill is loaded on demand, as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Audit or update DART's AI infrastructure for: $ARGUMENTS

Objective

Use live primary guidance and representative DART tasks to decide what to preserve, update, remove, consolidate, or add. Prefer the smallest change that improves the target without weakening the branch's compatibility rules, safety, evidence, public paths, or cross-tool capability parity. The reusable intake, comparison, verification, and closeout core stays model-agnostic. This workflow is itself an audit surface: improve it when a target exposes a reusable gap, and replace stale target-specific guidance instead of accumulating one command or permanent branch per model family. Because DART is a 3D physics simulator, every target also demonstrates how well it investigates simulation state with text-first and Filament visual/debug evidence.

Required Reading

@AGENTS.md @docs/AGENTS.md @docs/README.md @docs/information-architecture.md @docs/ai/principles.md @docs/ai/README.md @docs/ai/components.md @docs/ai/sessions.md @docs/ai/workflows.md @docs/ai/verification.md @docs/ai/branch-profile.json @docs/onboarding/ai-tools.md @docs/onboarding/release-management.md @docs/dev_tasks/README.md

Workflow

1. Normalize target, mode, and authority. Preserve the named model, reasoning mode, tool version, branch, and audit-only or apply boundary. Record whether external mutations are approved. Do not substitute a model or pin the repository to the audit target. audit-only is read-only for tracked files and external state: do not edit, regenerate, create task state, run auto-fixing lint, commit, push, or mutate GitHub. apply permits scoped local implementation; external mutations still need approval.

2. Capture the release control. Before apply-mode edits, record git state, installed versions, pixi run ai-doctor --json, model/config references, prompt and instruction sizes, generated skill-metadata size, custom-agent inheritance, hooks, scenarios, durable context and project state, active plan/dev-task handoffs, and the branch-local dart-verify-sim/Filament/image-evaluation route. Run baseline read-only gates. Create docs/dev_tasks/<task>/ only when the apply task is genuinely multi-session; audit-only reports the proposed path without creating it.

3. Refresh primary guidance. Read current official model, prompting, migration, configuration, skills, agents, and hook guidance relevant to the target. Record URLs, retrieval date, and installed-version evidence. Separate reusable procedure from target-specific evidence and flag any assumption in this workflow that the target invalidates.

4. Classify every finding. Use these verdicts:

   • preserve — intentional and evidence-backed;
   • update — stale or incorrect guidance/configuration;
   • remove/consolidate — repeated detail costs context without changing behavior;
   • add — a missing trigger, contract, diagnostic, or gate has a distinct owner and representative failure it prevents.

   Inspect model/effort routing, project and custom-agent pins, this workflow and generated adapters, other prompts, AGENTS.md chains, descriptions, hooks, scenarios, tests, and docs/ai/branch-profile.json. Audit AI infrastructure as both tooling and durable project context: the north star, docs/ai/sessions.md, docs/plans/dashboard.md, active docs/dev_tasks/*/RESUME.md, and handbook/design/release owners routed into sessions. Check discovery, freshness, duplication, context cost, cross-session resume quality, and usefulness to humans as well as agents.

5. Design a controlled comparison. Keep model, prompt, configuration, reasoning effort, and optional agent features as separate variables. When access permits, compare the existing model/settings, the target with the same prompt and preserved effort, the target at one lower effort, then only the smallest justified prompt/config change. Test delegation or concurrency separately. If a behavioral runner is unavailable, report structural evidence without turning it into a model-quality claim.

   Every target runs one representative DART physics investigation through dart-verify-sim using the same scene and claim. Require a text correctness oracle, then corroborate it with an assessed Filament capture and only the needed DebugOverlay layers. Compare whether the model requests missing evidence, repairs poor views, chooses claim-tied views/layers, reconciles text/image disagreement, and says what the image does not prove. Images are never the sole correctness oracle. If rendering or native image review is unavailable, exercise the text path, record the exact limitation, and do not infer visual quality from tool availability.

6. Route by task shape. Derive routing for the target family from its refreshed official guidance, then record the result in the model-routing owner, docs/ai/README.md § "Updating Models And Coding Agents", which keeps one bounded entry per validated tool lane. Match capability tiers to task shape: the top tier for the hardest ambiguous work, the middle tier for everyday or read-heavy work, and the light tier for clear repeatable work. Deeper reasoning modes give one difficult task more time. Delegate by default under docs/ai/orchestration.md, honoring a per-task delegation=off opt-out. Route packets to the best available agent, keeping small tasks or a single hard workstream with one agent when proportionate; independent packets may run in parallel. An explicitly requested top-tier evaluation exercises that lane without becoming a project default. Do not carry one family's tier or reasoning-mode names into another family's guidance. Replace a stale per-family entry in the owner doc; do not clone the workflow or append an ever-growing model taxonomy.

7. Implement only in apply mode. Apply the smallest supported delta. Preserve C++17, the nanobind binder, dart::utils, Filament, and the other compatibility rules in the branch's AGENTS.md. The approved DART nanobind binder is permitted under python/dartpy/. Follow the branch profile for other surfaces, including the forbidden historical python/dartpy/nanobind path. Keep outcome, constraints, permissions, evidence, routing, and stopping conditions explicit. Edit .claude/ sources and run pixi run sync-ai-commands; never hand-edit generated adapters. Prefer progressive disclosure over loading every plan or task by default. Improve this source in the same apply change when evidence exposes a reusable gap, and remove superseded model-specific guidance.

8. Exercise trigger and failure boundaries. Cover direct, indirect, incomplete, non-trigger, and edge prompts. Include a negative case that retains its existing route plus failures for model pins, config aliases, generated parity, instruction discovery, approvals, unavailable graphics, rejected views, text/image disagreement, and a static geometry defect that visual-only inspection must not pass. Include a fresh-session case that finds current project state and the correct resume surface without hidden chat history. Audit-only assesses and reports missing cases without adding them.

9. Verify and review. Run focused checks, pixi run check-ai-infra, pixi run exercise-agent-scenarios, pixi run test-ai-infra, the relevant docs/AI gates in docs/ai/verification.md, and the representative Filament investigation. Treat the configured CMake File API result, expanded target-command trace, and CTest inventory from check-ai-infra as the effective test-graph proof. Require its controlled runner probes to execute a body under hostile ambient controls, reject a successful zero-body run, and propagate a deliberate failure. Confirm inactive tests use explicit reached predicates, the requested multi-config CTest branch executes without ambient GTest selectors or result-neutralizing properties, and pytest remains pinned to the trusted root configuration without conftest or explicit local plugin loading; source-marker matches alone are insufficient. Audit-only uses pixi run check-lint; only apply mode runs auto-fixing pixi run lint before a commit. Complete the principle audit and two clean role-separated reviews. Label unavailable behavioral, cross-tool, hosted, or downstream evidence.

10. Close out. Make the changelog decision in apply mode, promote durable guidance, and remove completing temporary task state. Pushes, PRs, comments, review triggers, CI reruns, and merges require explicit maintainer/user approval.

Output

• Target, mode, branch, installed versions, primary sources, and control state
• Preserve/update/remove/consolidate/add plus apply/adapt/omit verdicts for reference material
• Durable context, session-handoff, freshness, and context-cost findings
• Comparison matrix, limitations, prompt/config changes, and unchanged choices
• DART physics/Filament investigation, semantic visual review, artifacts, and failure-boundary results
• Gates, compatibility effects, principle audit, two reviews, and blockers
• In apply mode, the changelog decision and local/external completion state