dart-analyze

Use this skill in Codex to run the DART dart-analyze workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-analyze <arguments>
• Codex: $dart-analyze <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Analyze repository evidence without editing: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/workflows.md @docs/ai/verification.md @docs/onboarding/ai-tools.md

Workflow

1. Restate the question and the read-only boundary. Do not edit files, stage changes, or perform GitHub, CI, branch, or review-thread mutations.
2. Inspect local state enough to avoid misreading user work:

   git status --short --branch
   git diff --stat
   

3. Build an evidence set from repository files, tests, docs, generated artifacts, and command output. Load task-specific docs from AGENTS.md when the question names a subsystem.
4. Separate direct evidence from inference and unknowns. Do not present an inference as a fact, and do not turn a read-only answer into an implementation plan.
5. Rank explanations, risks, or options by confidence when multiple readings are plausible. Use concrete file and line references for material claims.
6. If current external documentation or standards are needed for correctness, gather source-backed evidence and label date/version context explicitly.
7. Stop when the synthesis answers the question with enough evidence, or report the exact proof source that is unavailable.

Output

Report:

• the question answered and the scope inspected;
• ranked synthesis with confidence;
• evidence, inference, and unknowns as separate sections;
• any discriminating read-only probe that would reduce remaining uncertainty;
• confirmation that no local edits or external mutations were performed.

DART 7 Architecture

Load this skill when working on the DART 7 simulation World, on solvers/physics domains/compute backends, or whenever a task needs the big-picture map of how DART 7 is generalized for multi-physics, multi-solver, and multi-backend simulation.

The design in one sentence

The World owns topology, time, and a configured set of solvers; each solver advances the dynamics of the entities in its physics domain, and couplers mediate interactions between domains — with parallelizable work expressed as compute-graph nodes that any backend executor runs. Users configure method families and policies, never solver registries, component storage, or execution backends.

Why three axes of choice

• Research, apples-to-apples. A new paper's algorithm should be reproducible and benchmarkable inside DART against baselines on shared foundations, not in a fork. New methods enter through DART-owned solver families.
• End-user choice. Users pick the solver method and (internally) backend that fit their accuracy/speed/platform needs.
• Auto-configuration. Defaults are selected from scene content so the easy path stays trivial; the backend seam is designed for later platform/scene-scale awareness without changing the public API.

Design vs current state (read both)

docs/readthedocs/architecture.md is the single-page map of the design and the options at each seam, with honest status markers. docs/design/dart7_architecture_assessment.md is the verified record of where the implementation still diverges from that design (no internal solver contract yet, conceptual-only Model/State split, executor seam unused by dynamics stages, missing apples-to-apples substrate) and owns the standing rule: new solver families enter only through docs/plans/solver-family-intake.md, including contract conformance and machine-recorded solver identity in all benchmark evidence. PLAN-091 retired the first living hardening packet plan; current follow-up work routes through docs/plans/dashboard.md, the intake checklist, and the durable owner docs named in the assessment. Do not write new code that copies a pattern the assessment still lists as a verified finding.

Key owner documents

The architecture page's Source-of-truth map is the single owner of the full topic → owner-doc mapping (solver, API, extension, compute, differentiable, clean-break, north-star). The docs an agent most often needs inline:

Public-facade rules (do not violate)

• Do not expose Solver, Coupler, PhysicsDomain, ECS storage, component types, executor/backend types, or solver registries as public API.
• Select behavior by documented method-family names and policy value objects.
• Backend names (CUDA, Taskflow, SIMD ISA) may appear in build flags, diagnostics, and benchmarks — never in public types, namespaces, or required configuration.
• Keep the easy path (World + addRigidBody/addMultibody + step) free of solver vocabulary.
• Fallbacks must never silently substitute algorithms: validate capabilities at finalize or record the substitution in diagnostics.

Verification

Use docs/ai/verification.md to select the docs-only or code gate set for the change. Implementation work that realizes parts of this architecture also follows the gates in docs/design/simulation_solver_architecture.md, the solver-family intake checklist, and any active owner plan named in docs/plans/dashboard.md.

dart-audit-agent-compliance

Use this skill in Codex to run the DART dart-audit-agent-compliance workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-audit-agent-compliance <arguments>
• Codex: $dart-audit-agent-compliance <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Audit agent compliance issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/verification.md @docs/ai/components.md @docs/onboarding/ai-tools.md @docs/onboarding/contributing.md

Incident Inputs

• Rule violated: $1
• Where documented: $2
• Actual behavior: $3
• Expected behavior: $4

Treat missing positional values as details to infer from the user request or ask about before editing.

Workflow

1. Locate the exact existing rule and confirm it is still correct.
2. Diagnose why it was missed:
   • buried in prose
   • wrong file for the task type
   • weak emphasis
   • duplicated or conflicting guidance
   • not referenced from relevant commands or skills
3. Prefer restructuring existing docs over adding duplicate content.
4. Improve visibility with one or more focused changes:
   • move the rule to a loaded file
   • make it scannable with a checklist or mandatory marker
   • consolidate duplicate guidance
   • add cross-references from relevant commands or skills
5. Run the principle audit from docs/ai/principles.md and use docs/ai/verification.md to map audit results to evidence.
6. Run the relevant gate set from docs/ai/verification.md. For AI workflow changes, that includes generated adapter sync/checks, docs policy, spell, Markdown checks, and pixi run lint.

Output

• Root cause for the missed rule
• Files changed and why
• Which audit items were proven by automation vs manual inspection
• Confidence level that the recurrence risk is reduced

dart-backport-pr

Use this skill in Codex to run the DART dart-backport-pr workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-backport-pr <arguments>
• Codex: $dart-backport-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Backport PR or commits: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/release-management.md @docs/onboarding/changelog.md

Workflow

For a source change involving model/scene structure, physics behavior, or GUI output, use the target branch's dart-verify-sim workflow to preserve the text oracle and assessed visual evidence. Document a visual exception when the target branch cannot render the claim.

1. Verify the source PR or commit is merged to main:

   gh pr view <SOURCE_PR> --json state,mergedAt,baseRefName,mergeCommit
   

2. Check whether an equivalent change already exists on the release branch:

   git fetch origin <RELEASE_BRANCH> main
   git cherry -v --abbrev=40 origin/<RELEASE_BRANCH> origin/main | grep <COMMIT_HASH>
   

3. For AI-infra or workflow-doc backports, compare the release branch capability inventory and adapter directories against main. If the release branch has a smaller workflow surface, adapt to the release branch instead of importing main-only workflows.
4. Create a release branch from the release target:

   git checkout -B backport/<SOURCE_PR>-to-<RELEASE_BRANCH> origin/<RELEASE_BRANCH>
   

5. Cherry-pick with provenance: git cherry-pick -x <COMMIT_HASH>.
6. Resolve conflicts minimally; stop and ask if conflicts are broad or change behavior.
7. Run the dart-changelog routine for the release-target decision before opening the backport PR.
8. Run pixi run lint and the smallest relevant release-branch checks.
9. Ask for explicit maintainer/user approval before pushing or opening the PR. After approval, open the PR against the release branch with milestone matching that release branch and use the PR template.

Output

• Backport PR URL
• Source PR/commit
• Conflicts resolved, if any
• Changelog decision
• Checks run and CI status

dart-benchmark-packet

Use this skill in Codex to run the DART dart-benchmark-packet workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-benchmark-packet <arguments>
• Codex: $dart-benchmark-packet <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Author or refresh a benchmark evidence packet: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/profiling.md

Also read the owning plan file named by the packet (for example docs/plans/<NNN>-<slug>.md) and its packet convention.

Workflow

1. Identify the owning plan and its packet convention: the packet checker (for example pixi run check-avbd-packets) and the packet generator (for example scripts/write_*_packet.py) that the plan names.
2. Build the benchmark target and run the benchmark that feeds the packet, following docs/onboarding/profiling.md for a stable measurement setup.
3. Run the packet writer to record the machine-generated evidence packet with its provenance and resolved configuration.
4. Validate the packet with the plan's packet checker; treat a failing checker as incomplete evidence and fix the packet, not the checker.
5. Prepare the owning plan's row or link update that task-specific gates require, but leave editing the plan file to the plan's own workflow — this command prepares and validates the packet. This is a local task; do not push or open PRs without explicit maintainer/user approval.

Output

• Owning plan, packet ID, and the checker/generator used
• Benchmark command run and the measurement setup
• Packet file written and checker result
• Whether the packet is new or refreshed, and any remaining gap

dart-branch-cleanup

Use this skill in Codex to run the DART dart-branch-cleanup workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-branch-cleanup <arguments>
• Codex: $dart-branch-cleanup <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Analyze or clean branches: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md

Modes

• analyze: inspect only, no deletions
• action: prepare follow-up, or delete only after ownership/safety are clear and the maintainer/user gives explicit approval for each local or remote branch deletion

Default to analyze if the requested mode is ambiguous.

Workflow

1. git fetch --all --no-prune
2. List stale remote-tracking refs without deleting them:

   git remote prune origin --dry-run
   

   If origin uses SSH and port 22 is unavailable, keep the check read-only and use a temporary HTTPS rewrite instead of changing repository config:

   git -c url.https://github.com/.insteadOf=git@github.com: \
     fetch --all --no-prune
   git -c url.https://github.com/.insteadOf=git@github.com: \
     remote prune origin --dry-run
   

   To confirm that a remote PR branch was deleted without updating refs, query GitHub directly over HTTPS:

   git ls-remote --heads https://github.com/dartsim/dart.git <BRANCH>
   

3. Determine target branch, usually origin/main.
4. For each branch:

   git rev-list --left-right --count <TARGET>...<BRANCH>
   git log --oneline <TARGET>..<BRANCH>
   git diff --stat <TARGET>..<BRANCH>
   git cherry -v <TARGET> <BRANCH>
   

5. Before any explicitly approved local branch deletion, check whether the branch is checked out by a linked worktree:

   git worktree list --porcelain
   git -C <WORKTREE> status --short --branch
   

   Dirty linked worktrees must not be removed, detached, or reset during branch cleanup. Only after explicit maintainer/user approval, switch that worktree to a preservation branch at the same commit to free the obsolete branch name before deleting the merged branch.
6. The command git branch --merged may not prove ancestry for PR branches that landed through a squash or merge commit. Use the merged PR state plus an empty tree diff or equivalent git cherry -v output as the deletion signal; if the history relationship is unclear, keep the branch.
7. Classify recommendations only; deleting a candidate requires explicit maintainer/user approval:
   • ahead=0: safe deletion candidate
   • equivalent commits already landed: deletion candidate
   • no-PR branch whose fix may already be solved differently on the target: confirm supersession with a focused A/B or content check before deciding; superseded is a deletion candidate, otherwise keep or open a follow-up
   • small, current, useful diff: keep or rebase into PR
   • large or unclear diff: document follow-up before action
8. Ask for explicit maintainer/user approval before pruning refs or deleting any local or remote branch, even when ownership, branch purpose, and remote impact look clear.

Output

• Branch summary with ahead/behind count and last commit date
• Useful commits or risks
• Recommendation: delete, keep, rebase, or needs follow-up
• Actions taken after explicit maintainer/user approval, if action mode was explicitly requested

DART Build System

Load this skill when working with DART's build system.

Quick Commands

pixi run config       # Configure CMake
pixi run build        # Build
pixi run test         # Run tests
pixi run test-all     # Full validation (lint + build + tests)
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run lint         # Format code

Full Documentation

For complete build instructions, read: docs/onboarding/building.md

For build system internals (CMake, dependencies): docs/onboarding/build-system.md

Common Issues

CUDA Notes

• On Linux hosts with visible NVIDIA GPUs, the CUDA Pixi config auto-detects compute capabilities for DART_CUDA_ARCHITECTURES; set DART_CUDA_ARCHITECTURES=<arch> only when overriding that detected list.
• If CUDA runtime tests fail with unsupported PTX/toolchain errors, verify the generated CUDA flags include the local GPU architecture before assuming a kernel bug.

Pixi Lockfiles

• Do not edit pixi.lock by hand. Change dependency constraints in pixi.toml, then run a Pixi command such as pixi install to let Pixi regenerate the lockfile.
• If pixi.lock changes format or has broad solver churn, keep the generated output and call it out in the PR rather than attempting to splice lockfile entries manually.

Filament GUI Visual Checks

• For Filament GUI, scene, or simulation rendering changes, load dart-verify-sim. Pair a text correctness oracle with agent-capture, view assessment, and claim-relevant engine debug layers; inspect the artifact and sidecar instead of relying only on command success.
• If the user explicitly asks for pixi run ex dartsim, also run that exact entry point and terminate it after confirming the GUI binary launches.

Key Files

• pixi.toml - Package management
• CMakeLists.txt - Build configuration
• cmake/ - CMake modules

dart-changelog

Use this skill in Codex to run the DART dart-changelog workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-changelog <arguments>
• Codex: $dart-changelog <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Maintain DART changelog entries: $ARGUMENTS

Purpose

dart-changelog is the reusable changelog decision and writing routine. It is usually invoked by other DART workflows when they reach a changelog decision, not directly by users.

Use it to decide whether CHANGELOG.md needs an entry, draft an entry at the right level of detail, add a PR link after publication, or audit a release section for missing or over-detailed entries. Keep style, placement, evidence, and release-note density aligned with docs/onboarding/changelog.md.

Required Reading

@AGENTS.md @docs/onboarding/changelog.md @docs/onboarding/release-roadmap.md @docs/onboarding/release-management.md

Modes

Interpret $ARGUMENTS as one of these modes when present:

• decide: determine whether the current change needs a changelog entry and record the reason for the PR checklist/body when no entry is needed.
• draft: write or revise the entry before a PR number exists.
• finalize: add the PR link or adjust the entry after a PR exists, keeping the follow-up local until explicit maintainer/user approval permits a push.
• audit: scan a release section or PR set for missing, duplicate, over-detailed, misplaced, or stale entries.
• release-audit: alias for audit when the caller is finalizing a release section through dart-release-packaging.

If no mode is given, infer the smallest mode that satisfies the caller's need.

Output Contract

Every run must leave the caller with a concise, pasteable decision note. Use this shape in the response, PR body draft, or handoff text:

Changelog decision:

- Mode: decide | draft | finalize | audit | release-audit
- Base evidence: <base ref or PR/release inspected>
- Scope evidence: <diff, PR, issue, or release section inspected>
- Decision: entry required | no entry required | entry deferred | audit only
- Target section: <release/category, or N/A>
- Entry text: <final or draft bullet, or N/A>
- PR-body note: <exact no-entry reason or follow-up, or N/A>
- Follow-up: <PR link, maintainer approval, release audit, or none>

For no entry required, the PR-body note must name the evidence-backed reason rather than just saying "not needed." For entry deferred, say exactly what is missing, usually the PR number or release target. For finalize, confirm the entry still matches nearby CHANGELOG.md style after adding the PR link.

Workflow

1. Inspect the change and target:

   git status --short --branch
   git diff --stat
   git diff --cached --stat
   BASE_REF="$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || true)"
   # If the caller or arguments name a release branch before PR creation, set
   # BASE_REF to that branch before falling back to automatic inference.
   if [ -z "$BASE_REF" ]; then
     CURRENT_BRANCH="$(git branch --show-current)"
     UPSTREAM_REF="$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || true)"
     for REF in "$CURRENT_BRANCH" "${UPSTREAM_REF#origin/}"; do
       case "$REF" in
         main|release-*) BASE_REF="$REF"; break ;;
       esac
     done
   fi
   BASE_REF="${BASE_REF:-main}"
   git fetch origin "$BASE_REF"
   git diff --stat "origin/$BASE_REF...HEAD"
   gh pr diff --name-only 2>/dev/null || true
   gh pr list --head "$(git branch --show-current)"
   

   Use the base comparison or PR diff even when the worktree is clean. If a PR, issue, release, or target branch is named, inspect that live object before writing and prefer its base over the main fallback.
2. Read docs/onboarding/changelog.md and the relevant CHANGELOG.md release section. Compare nearby bullets before drafting so wording, section choice, and level of detail match the current file.
3. Decide whether an entry is required using the guide:
   • user-visible API, behavior, packaging, CI, docs workflow, AI-infra, simulation correctness, release, or migration impact usually needs an entry;
   • typo-only, formatting-only, generated-only, and tiny internal refactors usually do not.
4. Record the decision with the Output Contract before modifying CHANGELOG.md or telling a caller to skip it. The decision must cite the diff, PR, issue, release section, or target branch that was inspected.
5. When writing, start with the reader-visible outcome, not the implementation chore. Use one concise bullet, combine closely related changes, avoid author credits, and avoid one-bullet-per-PR diary style.
6. Place the entry under the target branch's release section and nearest existing category. Do not create a new category for one PR unless the release shape genuinely needs it.
7. Add the best evidence link:
   • if a PR number exists, use ([#1234](https://github.com/dartsim/dart/pull/1234));
   • if no PR number exists yet, draft without the link and leave the follow-up local until explicit approval permits another push or PR update.
8. For release audits, consolidate noisy implementation ledgers, confirm breaking/removal/deprecation bullets name a migration or support lane, and preserve human-readable release notes over exhaustive history.
9. Validate with the gate appropriate to the caller. For changelog-only edits, run the docs-only checks from docs/ai/verification.md; before any commit, run pixi run lint.

Caller Contract

Other workflows should call this routine whenever they touch behavior or docs that may need release notes. The caller keeps ownership of the overall task, validation, PR body, and approval boundary; dart-changelog owns the changelog decision, wording, placement, evidence-link hygiene, and the pasteable decision note that lets Claude, Codex, OpenCode, and manual contributors record the same outcome.

Output

Report:

• the changelog decision note in the Output Contract shape above;
• the drafted or finalized entry text and its CHANGELOG.md placement;
• gates run (pixi run lint, docs-only checks) and their results;
• any follow-up left local pending explicit maintainer/user approval.

DART CI/CD Troubleshooting

Load this skill when debugging CI failures or working with GitHub Actions.

When the failing claim depends on model/scene structure, physics behavior, or GUI/rendering output, also load dart-verify-sim and reproduce it with a text oracle plus assessed visual evidence. Document a visual exception when that renderer is unavailable or not applicable in the failing environment.

Quick Commands

# Monitor PR checks
gh pr checks <PR_NUMBER>
gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast

# View run details
gh run list --branch <BRANCH> -e pull_request -L 20
gh run watch <RUN_ID> --interval 30
gh run view <RUN_ID> --json status,conclusion,url

# Debug failures
gh run view <RUN_ID> --job <JOB_ID> --log-failed
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'

# Rerun failed jobs only after explicit maintainer/user approval
gh run rerun <RUN_ID> --failed
gh run rerun <RUN_ID> --job <DATABASE_ID>

Full Documentation

For complete CI/CD guide: docs/onboarding/ci-cd.md

Common Failure Modes

Workflow Architecture

CUDA Runner Policy

The project has a trusted ubuntu-latest-gpu runner for same-repository CUDA runtime validation, but it must never run untrusted fork-PR code. Consequences:

• Same-repository PRs, protected branch pushes, and manual dispatches use the GPU runner and run pixi run --locked -e cuda test-cuda.
• Fork PRs use a GitHub-hosted fallback and compile CUDA targets without running GPU-only steps.
• Local CUDA validation is pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime; local Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES.
• pixi run check-phase5-cuda-workflow enforces the trusted-event GPU guard and fork-PR hosted fallback in ci_cuda.yml.

Fast Iteration Loop

1. Identify failing step from job logs
2. Reproduce locally with same build toggles
3. Fix the smallest failing test
4. Push only after explicit maintainer/user approval, then monitor: gh run watch <RUN_ID>

Caching And Timing

Use the cache policy, current timing guidance, and investigation steps in docs/onboarding/ci-cd.md. Treat observed job duration and cache diagnostics from the affected run as the current evidence; do not copy mutable timing or hit-rate estimates into this skill.

dart-close-issue

Use this skill in Codex to run the DART dart-close-issue workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-close-issue <arguments>
• Codex: $dart-close-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Close or prepare closing message for issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md

Workflow

1. Inspect the issue: gh issue view <ISSUE_NUMBER> --comments.
2. Verify the stated resolution:
   • fixed by merged PR
   • already fixed on main
   • no longer reproducible
   • out of scope or needs a different tracker
3. Draft a concise closing message:
   • thank the reporter
   • state the concrete resolution
   • link the fixing PR or relevant docs when available
4. Only post and close if the user explicitly requested action and explicit maintainer/user approval has been given:

   gh issue comment <ISSUE_NUMBER> --body "<message>"
   gh issue close <ISSUE_NUMBER>
   

Output

• Closing message
• Whether it was posted
• Whether the issue was closed

DART Contribution Workflow

Load this skill when contributing code to DART.

Full Documentation

For complete guide: docs/onboarding/contributing.md

For code style: docs/onboarding/code-style.md

Branch Naming

• feature/<topic> - New features
• fix/<topic> - Bug fixes
• refactor/<topic> - Refactoring
• docs/<topic> - Documentation

PR Workflow

# Features, docs, and non-bugfix refactors start from main
git checkout -b <type>/<topic> origin/main

# Bug fixes that apply to the current release line start from the active DART 6 LTS branch
DART6_LTS_BRANCH=$(git branch -r --list 'origin/release-6.*' | sed 's|.*/||' | sort -V | tail -1)
git checkout -b "fix/<topic>-${DART6_LTS_BRANCH#release-}" "origin/$DART6_LTS_BRANCH"

# Make changes, then
pixi run lint
pixi run test-all
# On Linux hosts with a visible NVIDIA CUDA runtime
pixi run -e cuda test-all

# After explicit maintainer/user approval, push and create PR
git push -u origin HEAD
gh pr create --draft --base <target-branch> --milestone "<milestone>"

Use --base main --milestone "DART 7.0" for main PRs and the branch-matching DART 6.x patch milestone for active DART 6 LTS PRs.

Rule of thumb: run pixi run lint before committing so auto-fixes are included.

Use .github/PULL_REQUEST_TEMPLATE.md and keep DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first as the reviewer skim target. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then put the fuller why in Motivation / Problem rather than moving Motivation above Summary.

Write PR descriptions for a user or downstream maintainer who is not already familiar with the implementation. Lead Summary and Motivation with what changes for them, what stays compatible, how they opt in or migrate, and why the evidence matters; keep implementation mechanics in Changes unless they explain user-visible risk.

When a PR has meaningful user-facing API, workflow, behavior, or performance impact, add a concise Before / After section. Cover only relevant dimensions, phrase rows as user-visible before/after outcomes, and for performance claims name the baseline explicitly: CPU path, parent commit, main, or prior implementation, plus workload, metric, and important limitations.

Use plain descriptive commit messages and PR titles. Do not prefix them with agent tags such as [codex], [claude], or [opencode].

For already-published PRs, keep history inspectable with additive commits. If the PR branch needs the latest target branch, use explicit maintainer/user approval to update that published branch by merging the target branch and pushing normally. Do not rebase published PR branches by default because that invalidates existing CI runs and makes PR review/comment history harder to follow. Rebase or force-push only when the maintainer explicitly requests it.

Milestones (Required)

Always set a milestone when creating PRs after explicit maintainer/user approval:

# After explicit maintainer/user approval, set milestone on existing PR
gh pr edit <PR#> --milestone "DART 7.0"

# List available milestones
gh api repos/dartsim/dart/milestones --jq '.[] | .title'

CRITICAL: Bug Fix Dual-PR

Bug fixes require PRs to BOTH release lines:

1. Active DART 6 LTS release-6.* branch - Current DART 6 maintenance line
2. main - Next release

Steps:

1. Fix on the active DART 6 LTS branch first
2. Cherry-pick to main
3. After explicit maintainer/user approval, create separate PRs for each

CHANGELOG (After Approved PR Exists)

Use the dart-changelog routine with docs/onboarding/changelog.md as the source of truth. After the approved PR exists, check if CHANGELOG.md needs updating:

Format: - Reader-visible outcome. ([#PR](https://github.com/dartsim/dart/pull/PR))

Keep entries concise. If details need more than a few wrapped lines, move the details to the owner doc, plan, or migration note and link that document. Do not add one bullet per PR when several PRs ship one reader-visible outcome; merge them into one human-readable release-note entry.

# Example entry in CHANGELOG.md under appropriate section:
- Added AI-native documentation with AGENTS.md and module-specific guides. ([#2446](https://github.com/dartsim/dart/pull/2446))

Code Review

• Address all feedback
• Keep changes minimal
• Update tests if behavior changed
• Run full validation, then ask for explicit maintainer/user approval before pushing fixes

CI Loop

gh run watch <RUN_ID> --interval 30

Fix failures until green.

dart-deps

Use this skill in Codex to run the DART dart-deps workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-deps <arguments>
• Codex: $dart-deps <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Triage and shepherd dependency and bot PRs: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md

Scope

Handle automated dependency and maintenance PRs: Dependabot GitHub Action version bumps and the scheduled lockfile PRs opened by update_lockfiles.yml. Default to read-only triage; merging any bot PR is an explicit approval gate.

Workflow

1. List open bot PRs:

   gh pr list --repo dartsim/dart --state open \
     --search "author:app/dependabot OR author:app/github-actions" \
     --json number,title,headRefName,author
   

2. For each PR, review the diff (gh pr diff <PR_NUMBER>):
   • Action bumps: confirm the new ref is a pinned commit SHA and sanity-check the upstream changelog for the bumped version.
   • Lockfile PRs: confirm the regenerated lockfile provenance matches the workflow that produced it and that no unrelated content changed.
3. Confirm CI is green for the PR head: gh pr checks <PR_NUMBER>.
4. Merge a reviewed, CI-green bot PR only after explicit maintainer/user approval, using the current head SHA and the repository merge method.
5. Batch-report every triaged PR with its recommendation and status.

Output

• Table of open bot PRs with kind (action bump or lockfile), CI state, and recommendation
• Diff-review notes per PR
• Which PRs were merged after explicit approval and which remain pending

dart-docs-update

Use this skill in Codex to run the DART dart-docs-update workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-docs-update <arguments>
• Codex: $dart-docs-update <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Update documentation: $ARGUMENTS

Required Reading

@AGENTS.md @docs/README.md @docs/AGENTS.md @docs/information-architecture.md @docs/ai/principles.md @docs/ai/verification.md @docs/onboarding/ai-tools.md @docs/onboarding/changelog.md

Workflow

1. Create a branch from the target branch: git checkout -b docs/<topic> origin/main
2. Edit docs and AI workflow sources only:
   • Regular docs: docs/**, README.md, AGENTS.md, CONTRIBUTING.md, and CHANGELOG.md when dart-changelog requires a release-note entry
   • AI source files: .claude/commands/**, .claude/skills/**
3. For AI workflow changes, run pixi run sync-ai-commands; do not hand-edit generated .opencode/ or .codex/ files
4. Classify new or moved docs by lifecycle first, then audience, then topic, using docs/information-architecture.md. For AI docs, keep always-loaded entrypoints compact: improve owner placement or pointers instead of duplicating procedures.
5. Update indexes and cross-references that point to changed docs
6. Use docs/ai/verification.md to select the docs-only or AI docs/adapters gate set, then run pixi run lint before committing
7. Invoke the dart-changelog routine for the CHANGELOG.md decision and any required entry.
8. Ask for explicit maintainer/user approval before pushing or opening the PR. After approval, use .github/PULL_REQUEST_TEMPLATE.md and the proper milestone.

Output

• Docs and AI workflow sources changed
• Sync and verification commands run
• Changelog decision
• PR readiness, noting any external mutation that was explicitly approved

dart-downstream-fix

Use this skill in Codex to run the DART dart-downstream-fix workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-downstream-fix <arguments>
• Codex: $dart-downstream-fix <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix downstream-reported DART issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md

When To Use

Use for downstream issues in gz-physics, Gazebo, or gz-sim that trace back to DART behavior: crashes, assertions, NaN/Inf propagation, missing validation, or DART performance regressions.

Workflow

If the downstream symptom depends on scene/model structure, simulation, collision/contact, or GUI output, route through dart-verify-sim: establish a text oracle, add assessed claim-tied visual evidence, or document a visual exception when rendering is unavailable or not applicable.

1. Read the downstream issue, logs, stack traces, and reproduction steps.
2. Identify the DART API, component, and invalid usage pattern involved.
3. Search for related validation and recovery patterns in DART.
4. Plan the smallest fix and the regression test location.
5. Decide whether the bug applies to the active release line. For applicable bug fixes, implement on the active DART 6 LTS branch first, then cherry-pick or reapply to main for DART 7:
   • branch: fix/<downstream-project>-<issue-number>-<brief-description>-6-lts
   • add a regression test that reproduces the downstream symptom
   • keep the fix minimal; no unrelated refactors
6. Run pixi run lint and relevant tests; use pixi run test-all when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime.
7. Ask for explicit maintainer/user approval before pushing or creating PRs. After approval, create the release-branch PR with the branch-matching DART 6.x patch milestone and reference the downstream issue.
8. Create the matching main PR with milestone DART 7.0; adapt API differences if needed.

Release-Line Differences

• DART 7 commonly uses DART_WARN() and <dart/All.hpp>.
• DART 6 LTS may use dtwarn << ..., <dart/dart.hpp>, and older test CMake patterns.

Output

• Root cause and fix summary
• Main PR URL and release PR URL, if applicable
• Tests run and CI status
• Link back to the downstream issue

dart-execute-packet

Use this skill in Codex to run the DART dart-execute-packet workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-execute-packet <arguments>
• Codex: $dart-execute-packet <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Execute a work packet in DART: $ARGUMENTS

Required Reading

Read these files first: @AGENTS.md @docs/ai/orchestration.md @docs/ai/principles.md @docs/ai/verification.md @docs/plans/dashboard.md

Inputs

$ARGUMENTS is optional and takes one of three forms:

• WP-<plan>.<n> (for example WP-091.13) — execute exactly that packet.
• PLAN-NNN (for example PLAN-091) — select the first available packet in that plan.
• empty — auto-select: walk docs/plans/dashboard.md top to bottom (document order is priority); for each Active entry whose owner doc is a numbered plan file containing #### WP- packet headings, take the first available packet by the availability rules below. State which packet was selected and why before starting.

If nothing resolves to an available packet, report what was checked (plans walked, packets skipped and the blocking signal for each) and stop; do not invent work.

Availability and conflict check

Run the full check from docs/ai/orchestration.md before claiming. A packet is available only when ALL of these hold:

1. Dependencies — its Dependencies line is satisfied in full: every named packet is marked [done — ...], and every non-packet precondition (for example "maintainer direction on ..." or an accepted design note) has recorded evidence in the plan or the named owner doc. Treat any precondition you cannot verify as unmet and skip the packet.
2. Local markers — its heading carries neither [done — ...] nor [claimed] in the local plan file.
3. Remote markers — git fetch origin (a read-only sync), then check the plan file as it exists on the default branch (git show origin/main:docs/plans/<plan-file>.md) for a marker the local checkout does not have yet.
4. Branch/PR signals — no one else is already working it: git ls-remote --heads origin shows no branch embedding the packet ID in the documented form (wp-<plan>-<n>-<slug>, for example wp-091-13-contact-assembly), and gh pr list --state open --search "WP-<plan>.<n>" returns no open PR carrying the ID in its title. These are read-only queries that mutate nothing; any push, PR creation, or other GitHub mutation still requires explicit maintainer/user approval.

If any signal says the packet is taken: in auto/plan mode skip to the next available packet; for an explicit packet ID, report the conflicting signal and stop.

Readiness check

Before claiming, inspect the packet text and named owner docs for the specification intake required by docs/ai/orchestration.md:

• objective;
• value or rationale;
• scope;
• non-goals;
• assumptions and open decisions;
• acceptance evidence;
• gates; and
• dependencies.

If objective, scope, non-goals, acceptance evidence, gates, or dependencies are missing or too vague to verify, report that the packet is not executable and stop. For older packets that lack an explicit value or assumptions field, proceed only when the owner docs make the value and assumptions unambiguous, and state those inferred fields before editing. If an unresolved decision would materially change public API, release compatibility, numerical correctness, benchmark claims, or roadmap scope, stop and ask the orchestrator to record an owner-local Decision needed block.

Workflow

1. Locate the packet — open the owning numbered plan file linked from docs/plans/dashboard.md and read the packet's objective, scope, value/rationale, assumptions/open decisions, non-goals, acceptance evidence, gates, and dependencies.
2. Claim — append [claimed] to the packet heading in the plan file and create the topic branch named wp-<plan>-<n>-<slug>. The branch name is the cross-machine claim signal once pushed; pushing it (like any GitHub mutation) requires explicit maintainer/user approval, so until then the marker and branch are local and the strongest remote signal stays the merged plan file.
3. Load packet context — read the owner docs the plan names for that workstream plus the files in the packet's scope. Do not load the whole plan corpus; the packet defines the working set.
4. Implement exactly the packet — stay inside scope and non-goals. If the real scope differs materially from the packet's stated scope, stop and report back with what was found; do not widen the packet. One packet, one branch, one verification story.
5. Verify — run the packet's gates plus pixi run lint before any commit. Record each piece of acceptance evidence named by the packet (test names, command output, doc updates). Missing evidence means the packet is not complete — say so explicitly.
6. Hand back — append an Evidence: bullet to the packet in the plan file listing the recorded evidence (or update the dev-task RESUME.md for multi-session packets), leave the [claimed] marker for the orchestrator to replace with [done — ...] on acceptance, then report completion with the evidence list for orchestrator review. Local commits are part of execution; pushes and PR creation require explicit maintainer/user approval first, and the PR title starts with the packet ID (WP-<plan>.<n>: ...) so the claim is searchable.

Rules

• The packet's owner docs win over the packet text on any conflict; report the conflict rather than improvising.
• Do not chain into adjacent packets, refactor outside scope, or "fix while here" — file findings back to the orchestrator instead.
• Never remove another session's [claimed] marker or reuse its branch; stale-claim release is the orchestrator's call (see docs/ai/orchestration.md).
• Behavior-preserving packets must prove preservation (golden trajectories or the tests the packet names), not assert it.
• Solver-family work additionally honors the intake checklist in docs/plans/solver-family-intake.md.
• The author of a packet's implementation does not approve it; acceptance is the orchestrator's or an independent reviewer's call.

Output

• Selected packet ID and owning plan
• Scope implemented and acceptance evidence recorded
• Gates run and their results
• Hand-back state (the [claimed] marker left for the orchestrator) and any blocker
• Any external mutation that was explicitly approved

dart-fix-ci

Use this skill in Codex to run the DART dart-fix-ci workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-fix-ci <arguments>
• Codex: $dart-fix-ci <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix CI failure: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/release-management.md

Workflow

For a failure involving model/scene structure, physics behavior, or GUI output, use dart-verify-sim to reproduce the claim with text and assessed visual evidence. Document a visual exception when the relevant renderer is unavailable or not applicable.

1. Identify the base branch. Default to main; use base=<branch> from $ARGUMENTS or the PR's own base when it is a release-* branch. For a release-* base, also read docs/onboarding/release-management.md and apply the release caveats called out below.
2. Identify failing checks: gh pr checks <PR_NUMBER> or gh run view <RUN_ID>.
3. Inspect the first real failure:

   gh run view <RUN_ID> --log-failed
   gh run view <RUN_ID> --job <JOB_ID> --log
   

4. If a job is still in progress, wait for logs instead of guessing.
5. Choose where to fix. Check whether an equivalent fix already exists on main. If continuing an existing PR, fetch and check out that PR branch instead of creating a new one. For a release-* base, branch from the release branch and prefer cherry-picking the proven main fix; keep any new fix release-scoped and minimal:

   git fetch origin <RELEASE_BRANCH>
   git checkout -B fix/<issue>-<release-branch> origin/<RELEASE_BRANCH>
   

6. Reproduce locally with the smallest relevant command:
   • formatting: pixi run lint
   • tests: pixi run test, pixi run test-unit, or another existing focused pixi run ... test task
   • coverage: add targeted tests for uncovered changed lines
7. Fix the root cause with minimal scope. Explain why the failure was not caught earlier and whether workflow coverage should change.
8. If the failure is infrastructure-only, ask for explicit maintainer/user approval before rerunning the failed job or running:

   gh run rerun <RUN_ID> --failed
   

9. Ask for explicit maintainer/user approval before pushing, CI re-triggers, or other GitHub mutations; after approval, push and watch CI until green. For a release-* base, use the current release milestone and the PR template when creating or updating the release-branch PR.

Output

• Root cause
• Fix or rerun action
• Commands run
• PR URL, when a PR was created or updated
• Current CI status
• Prevention recommendation, if any

dart-fix-issue

Use this skill in Codex to run the DART dart-fix-issue workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-fix-issue <arguments>
• Codex: $dart-fix-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix GitHub issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md @docs/ai/verification.md

Workflow

If the issue's fix depends on model/scene structure, simulation, dynamics, collision/contact/constraints, or GUI output, route through dart-verify-sim: pair the focused behavioral oracle with assessed, claim-tied visual evidence, or document a visual exception when rendering is unavailable or not applicable.

1. gh issue view $1 - Validate issue
2. Classify whether the issue is a bug fix that applies to the active DART 6 LTS branch. For applicable bug fixes, start from the highest maintained origin/release-6.* branch; otherwise start from origin/main.
3. Fix with minimal changes + add regression test. For dual-PR bug fixes, fix the active DART 6 LTS branch first, then cherry-pick or reapply to main.
4. pixi run lint, then run the smallest relevant tests; use pixi run test-all before finalizing when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime
5. Before PR creation, invoke the dart-changelog routine to decide whether CHANGELOG.md needs an entry, then fill .github/PULL_REQUEST_TEMPLATE.md.
6. After explicit maintainer/user approval, git push -u origin HEAD && gh pr create --base <target-branch> --milestone "<milestone>"
7. Before PR: If task used docs/dev_tasks/<task>/, remove the folder (include in this PR, not after merge)

CRITICAL: Dual-PR for Bug Fixes

PRs to BOTH the active DART 6 LTS branch AND main. See docs/onboarding/contributing.md.

Output

• Issue number and classification (bug fix, dual-PR, or main-only)
• Fix summary and regression test added
• Gates run (lint, focused tests, pixi run test-all)
• PR readiness for each target branch, noting any explicitly approved mutation

DART Model Loading (dart::io)

Load this skill when working with robot model files or parsers.

When correctness depends on the loaded model's 3D hierarchy, transforms, collision geometry, or simulated behavior, also load dart-verify-sim for a text scene/behavior oracle plus claim-tied visual corroboration.

Quick Start

#include <dart/io/read.hpp>

// Format auto-detection
auto skel = dart::io::readSkeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf");

Full Documentation

For complete I/O guide: docs/onboarding/io-parsing.md

For module-specific details: dart/io/AGENTS.md

Supported Formats

Common Patterns

// URDF with package resolution
dart::io::ReadOptions options;
options.addPackageDirectory("my_robot", "/path/to/my_robot");
auto skel = dart::io::readSkeleton("package://my_robot/urdf/robot.urdf", options);

// Force specific format
options.format = dart::io::ModelFormat::Sdf;

Key Files

• API: dart/io/read.hpp
• Tests: tests/unit/io/test_read.cpp

dart-manage-pr

Use this skill in Codex to run the DART dart-manage-pr workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-manage-pr <arguments>
• Codex: $dart-manage-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Manage an open DART pull request after explicit maintainer/user approval for mutations: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md @docs/onboarding/testing.md @docs/onboarding/ai-tools.md

Modes

• mode=manage (default): run the full PR-management loop below to the next terminal state.
• mode=merge: maintainer-only. Complete the local pre-merge validation in step 6 and merge a ready PR only after explicit maintainer/user approval for the merge.

Invocation Contract

When the user says manage <PR> or continue managing <PR> without limiting the request to status-only, treat that as approval to run the full PR-management loop to the next terminal state:

• required policy metadata checked and corrected when stale;
• CI monitored until green, failed, or blocked;
• merge conflicts reproduced and resolved locally;
• review comments addressed, pushed, resolved, and re-reviewed when appropriate;
• PR body/testing evidence refreshed when it no longer matches the branch.

This explicit approval covers routine PR-maintenance mutations for that loop: additive fix commits and pushes, PR description/metadata corrections, resolving already-addressed review threads, rerunning failed CI jobs, and requesting a fresh AI review after follow-up fixes. It does not cover merging the PR into the target branch, force-pushes, branch deletion, PR closure, base-branch changes, or human reviewer requests; ask separately for those.

Do not call the PR managed just because checks are green. Continue until the PR is mergeable with required checks complete and addressed review threads resolved, or until a concrete blocker remains.

Identify the PR

Use the PR number or URL from $ARGUMENTS. If none is provided, infer the PR from the current branch:

gh pr view --json number,url,headRefName,baseRefName

Then inspect the full state:

gh pr view <PR_NUMBER> --json number,title,state,isDraft,baseRefName,headRefName,mergeStateStatus,milestone,url,reviewDecision,statusCheckRollup
gh pr checks <PR_NUMBER>

Workflow

1. Confirm scope and policy:
   • Check that the base branch, title, and PR template are correct.
   • Verify the milestone is set before merge: DART 7.0 for a main base, the branch-matching DART 6.x patch milestone for a release-* base. If it is missing, set it only after explicit maintainer/user approval.
   • For bug fixes, verify the required DART 6 LTS + main dual-PR flow.
   • Confirm the PR body's testing/status section matches the current head and does not point reviewers to deleted dev-task evidence as still pending.
   • Confirm the PR body follows template order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first as the skimmable outcome; fold leading problem context into Summary and keep the fuller why in Motivation.
   • When the PR has user-facing API, workflow, behavior, or performance impact, confirm a concise Before / After section compares old and new surfaces; for performance claims make the baseline explicit (CPU path, parent commit, main, or prior implementation) plus workload, metric, and limitations.
   • Ensure transient visual evidence (screenshots, headless renders, GIFs, videos) is hosted as GitHub PR/issue attachments rather than committed to the branch; if committed only for the PR body, replace it with an attachment URL or ask a maintainer to upload.
   • When the claim depends on 3D structure or behavior, accept an optional Visual verification subsection after Testing and verify it agrees with the text oracle, covers explicit claims, names what is not proved and any limitations, records view/debug layers, and includes reproduce commands.
   • Inspect local state before editing:

     git status --short --branch
     git diff --stat
     git diff --check
     

2. Monitor CI:

   gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast
   

   If checks are still queued or running, report the current jobs and keep watching unless the user asked only for status. Also poll mergeability:

   gh pr view <PR_NUMBER> --json mergeStateStatus,headRefOid,isDraft,reviewDecision
   

   If GitHub reports conflicts, fetch the target branch and resolve them before treating green checks as sufficient.
3. Fix failures:
   • Inspect the newest failed run or job, not an older cancelled run. Use the dart-fix-ci workflow for non-trivial CI debugging.
   • Reproduce locally with the relevant pixi run ... task or focused test.
   • Before committing fixes, run pixi run lint; also build or test when code or behavior changed. Commit only intended files.
   • Prefer additive follow-up commits for published PRs. Amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).
   • Merge the latest base branch into the PR branch before any push, and follow the base-merge, automated-review, and bot no-reply rules in docs/onboarding/ai-tools.md; each push, PR comment, review re-trigger, or thread resolution needs explicit maintainer/user approval.
4. Address reviews:
   • Use the dart-review-pr workflow for substantive review feedback and the automated-review handling in docs/onboarding/ai-tools.md (no inline bot replies; verify claims locally; apply AI-review fixes silently).
   • For human reviewers, reply only when a response is useful after a fix or when a question needs clarification.
   • After an approved push that addressed Codex comments on a PR that already had a Codex review, post a fresh top-level @codex review; that PR comment needs explicit maintainer/user approval and must not duplicate an active trigger.
   • For substantive code PRs, an independent review session (a human, or a separate agent session running /dart-review-pr) must record findings before merge approval; docs-only and mechanical changes are exempt.
5. Mark ready or merge only when appropriate:
   • Confirm review requirements are satisfied and local validation matches the intended transition.
   • If the PR is draft, mark it ready after explicit approval once Codex is clean and local validation passed on the current head: default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime. Hosted CI may still be pending.
   • Use the current head SHA when merging so a moved branch cannot be merged accidentally. Prefer squash/rebase over merge commits per repository settings; recent DART main PRs use single-parent PR-title commits.
6. mode=merge gate (maintainer-only): before any merge, run local pre-merge validation on the current head after the latest pushed change: pixi run test-all and, on Linux hosts with a visible NVIDIA CUDA runtime, pixi run -e cuda test-all; do not substitute the default run for the CUDA run, and record a skip or blocker explicitly. Merge only after CI and review are green, the milestone is set, an independent review recorded findings, the PR is not draft, GitHub reports it mergeable, and explicit merge approval is given. PR comments, review re-triggers, thread resolution, reviewer requests, ready-for-review transitions, merges, and branch deletion are external mutations that require explicit maintainer/user approval.
7. Clean up after merge:
   • Confirm the PR merged and identify the head branch before deleting.
   • After explicit maintainer/user approval, prefer merge-time deletion with the approved merge method and head SHA:

     gh pr merge <PR_NUMBER> --squash --match-head-commit <HEAD_SHA> --delete-branch
     

     Use --rebase or --merge instead of --squash when requested.
   • After explicit maintainer/user approval, otherwise delete only the PR branch after confirming it has landed:

     git push origin --delete <HEAD_BRANCH>
     git switch main
     git pull --ff-only
     git branch -D <HEAD_BRANCH>
     

     Squash and rebase merges do not preserve the branch tip in main ancestry, so force-delete locally only after confirming the PR branch landed and only after explicit maintainer/user approval.

Output

Report:

• PR number, URL, base, head, draft state, milestone, and merge status.
• CI summary: passing, failing, pending, or skipped checks.
• Review summary, independent-review status, and whether @codex review ran.
• Local pre-merge validation state when mode=merge ran.
• Commits pushed, merge action, and branch cleanup action.
• Remaining blockers or next action.

dart-mechanical-refactor

Use this skill in Codex to run the DART dart-mechanical-refactor workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-mechanical-refactor <arguments>
• Codex: $dart-mechanical-refactor <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Perform mechanical refactor: $ARGUMENTS

Required Reading

@AGENTS.md @CONTRIBUTING.md @docs/onboarding/code-style.md

Workflow

1. Define the exact transformation and scope before editing.
2. Create a branch from the target branch, usually origin/main.
3. Prefer scriptable or automated edits when the transformation is repetitive.
4. Keep behavior unchanged; do not mix in feature work or cleanup outside scope.
5. If reorganizing files, update CMake, pixi tasks, generated indexes, and docs.
6. Run focused checks first, then broader checks according to risk:
   • pixi run lint
   • pixi run build
   • pixi run test-unit
   • pixi run test-all when feasible
   • pixi run -e cuda test-all when feasible on Linux CUDA hosts
7. Ask for explicit maintainer/user approval before pushing or opening a PR. After approval, open a PR with a clear scope statement and no behavior-change claim unless tested.

Output

• Transformation summary
• Files or areas changed
• Verification run
• Any residual risk

dart-new-task

Use this skill in Codex to run the DART dart-new-task workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-new-task <arguments>
• Codex: $dart-new-task <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Start a new task in DART: $ARGUMENTS

Required Reading

Read these files first: @AGENTS.md @docs/onboarding/building.md @docs/onboarding/contributing.md @docs/onboarding/code-style.md @docs/dev_tasks/README.md @docs/information-architecture.md @docs/ai/sessions.md @docs/ai/principles.md @docs/ai/verification.md

Workflow

1. Understand the task - Parse: goal, constraints, type (feature|bugfix|refactor|docs)
2. Assess scope - Multi-phase or multi-session? Create docs/dev_tasks/<task>/ (see docs/dev_tasks/README.md for criteria). Team-scale work (multiple parallel lanes needing orchestrated worker agents) switches to dart-ultrawork instead. For multi-session, design-heavy, public API, solver/paper, release, or cross-module work, fill the dev-task specification intake before editing: value, scope, assumptions, traceability, non-goals, acceptance evidence, gates, and open decisions. If consequential ambiguity would change public API, release compatibility, numerical correctness, benchmark claims, or roadmap scope, record an owner-local Decision needed block instead of silently choosing.
3. Setup - Choose the target branch before creating a topic branch:
   • features/docs/non-bugfix refactors: branch from origin/main
   • bug fixes that apply to the current release line: branch from the active DART 6 LTS origin/release-6.* branch first, then cherry-pick or reapply to main
4. Implement - Keep commits focused, follow code style
5. Verify - Run pixi run lint before committing, then pixi run test-all; on Linux hosts with a visible NVIDIA CUDA runtime, also run pixi run -e cuda test-all. If the claim depends on scene structure, simulation, dynamics, collision/contact, GUI output, or a visual example, route through dart-verify-sim: prove correctness with text first, then add assessed headless/debug-layer evidence or record why it is not applicable.
6. PR - After explicit maintainer/user approval, git push -u origin HEAD then gh pr create --draft --base <target-branch> --milestone "<milestone>" (DART 7.0 for main, branch-matching DART 6.x patch milestone for the active DART 6 LTS branch); follow .github/PULL_REQUEST_TEMPLATE.md
7. Cleanup - Before PR: if task used docs/dev_tasks/<task>/, first promote durable dashboards, evidence matrices, API inventories, migration maps, or long-lived decisions into the durable owner selected by docs/information-architecture.md. Then remove the dev-task folder completely (include the deletion in this PR, not after merge).

Type-Specific

• Bugfix: Requires PRs to BOTH the active DART 6 LTS branch AND main
• Refactor: No behavior changes
• Feature: Add tests + docs
• New solver/paper implementation: Before any implementation starts, record the full solver-family intake checklist in docs/plans/solver-family-intake.md — including its solver-contract conformance and solver-identity/metrics items; the standing rule in docs/design/dart7_architecture_assessment.md applies, and new families must not bypass the PLAN-091 contracts. Derive an evidence matrix from the paper, project page, reference source, videos, and demos. Do not call the task complete until DART implements all algorithms/features on required CPU and GPU backends, ports all experiments/demos into tests/benchmarks/py-demos, records benchmark JSON proving DART beats reference and paper numbers for every claimed case (with the resolved solver configuration machine-recorded in every packet), and performs any clean API/pipeline refactor needed for the long-term DART 7/8 architecture. For multi-session work, keep the active docs/dev_tasks/<task>/README.md and RESUME.md explicit about the latest completed slice, the next missing paper-parity gap, and why focused green tests are not a full solver/paper completion claim.

Output

• Task type, scope, and whether a docs/dev_tasks/<task>/ folder was created
• Files changed and gates run
• Dev-task promotion and cleanup status when the task completed
• PR readiness, noting any external mutation that was explicitly approved

dart-next

Use this skill in Codex to run the DART dart-next workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-next <arguments>
• Codex: $dart-next <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Select and execute the next bounded DART task: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/ai/workflows.md @docs/ai/verification.md @docs/plans/README.md @docs/plans/dashboard.md @docs/plans/north-star-roadmap.md @docs/dev_tasks/README.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md @docs/onboarding/ai-tools.md

Arguments

Interpret $ARGUMENTS as optional constraints:

• mode=select: choose one task and stop with evidence.
• mode=execute: choose one task, make local changes, and verify locally. This is the default when the user asks to do the work.
• mode=pr: execute locally and prepare PR text, then ask for explicit maintainer/user approval before any GitHub, PR, CI, branch, or review-thread mutation, including pushes, PR creation, PR comments, reviewer requests, review re-triggers, thread resolution, ready-for-review transitions, merges, CI reruns, or branch deletion.
• size=tiny|small|medium|large or days=N: fit the chosen task to the requested scope. Default to small, meaning one focused local session.
• focus=<topic>: prefer a focus area without making it the only allowed candidate. Examples: ai-native, easy-start, algorithm, compute, release, ci, docs, python, io, PLAN-020, world_split, dartpy, or a file path.
• area=<dimension>: alias for focus=<dimension>.
• Any issue, PR, branch, milestone, failing check, file path, or user-stated priority overrides the default dashboard order.

If constraints conflict or make the task unsafe to select, stop and ask one clarifying question.

Workflow

1. Inspect local state before choosing work:

   git status --short --branch
   git diff --stat
   

2. Build the candidate set from tracked evidence:
   • explicit user instruction in $ARGUMENTS;
   • current branch, local diff, or active docs/dev_tasks/<task>/ state;
   • docs/plans/dashboard.md, in priority order, especially Horizon: Now;
   • docs/ai/north-star.md gaps and readiness criteria;
   • issue, PR, or CI state named by the user or inferable from the branch.
3. Exclude candidates that are blocked, larger than the requested size, missing enough evidence to start, likely to require unapproved GitHub mutations, or only bootstrap/maintain the dart-next workflow itself unless explicitly focused.
4. Prefer the highest-value remaining candidate in this order:
   • user-specified issue, PR, failing check, or file path;
   • candidates matching focus=<topic> or area=<dimension>;
   • failing CI or review feedback on the current PR;
   • active dev task with a clear next local step;
   • first unblocked Horizon: Now dashboard item fitting the size;
   • issue triage or plan refinement when implementation evidence is missing.
5. State the selected task before editing:
   • candidate and source evidence;
   • rejected higher-priority candidates and why they were not selected;
   • whether the preferred focus matched the selected task, and why if it did not;
   • size assumption and expected stopping point;
   • workflow to follow next;
   • verification gate from docs/ai/verification.md.

Execution Routing

After selection, follow the most specific DART workflow:

If the selected task is multi-session or needs design tracking, create or update docs/dev_tasks/<task>/ according to docs/dev_tasks/README.md.

Local Work Cycle

1. Load task-specific docs from AGENTS.md and the routed workflow.
2. Make the smallest coherent local change that satisfies the selected task.
3. Run the strongest relevant local gate:
   • docs/AI work: gates from docs/ai/verification.md;
   • C++ or Python behavior: pixi run lint, build, and focused tests;
   • CI work: local reproduction when possible plus the fixed check.
4. Review the local diff before declaring completion:

   git diff --stat
   git diff --check
   

5. Optimize or benchmark only when the selected objective is performance sensitive or the plan gate explicitly requires performance evidence.
6. Update durable docs when the task changes project state, public workflow, or roadmap evidence.
7. Run the completion audit from docs/ai/verification.md before finalizing.

PR And Review Management

Use $dart-pr or /dart-pr only after local verification is complete and the user requested PR preparation. Ask for explicit maintainer/user approval before any GitHub, PR, CI, branch, or review-thread mutation, including push, PR creation, PR comment, reviewer request, review re-trigger, review-thread resolution, ready-for-review transition, CI rerun, merge, or branch deletion.

After a PR exists and explicit approval covers PR management, use $dart-manage-pr or /dart-manage-pr for CI, review, and cleanup. For the first Codex review on a draft PR, prefer a top-level @codex review after explicit approval for PR comments; it can run while the PR remains draft. Once Codex is clean and local validation passes on the current head (default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime), the draft is ready to mark ready for human review after approval, while merge still waits for required hosted checks.

Output

Report:

• selected task, size, evidence, and routed workflow;
• files changed and verification commands run;
• completion-audit result and any remaining blocker;
• PR readiness status, without performing external mutations unless explicit approval was given.

dart-plan-update

Use this skill in Codex to run the DART dart-plan-update workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-plan-update <arguments>
• Codex: $dart-plan-update <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Discuss or update DART living plans: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/plans/README.md @docs/plans/dashboard.md @docs/plans/north-star-roadmap.md @docs/ai/verification.md

Workflow

1. Classify the request:
   • discussion-only: compare options, priority, scope, or sequencing;
   • plan edit: revise docs/plans/** or related indexes;
   • task derivation: turn a plan item into a bounded implementation or docs task.
2. Inspect current evidence before changing plan state. Use repo docs, code, tests, CI evidence, issue/PR state, benchmark data, or explicit maintainer direction.
   • For new solver/paper implementation plans, preserve the full paper-complete bar in docs/ai/verification.md: all algorithms/features, CPU and GPU paths, paper/site/video demos, benchmark JSON that beats reference and paper numbers, and clean long-term API/pipeline work.
   • For active multi-session solver/paper work, update the plan or dev-task resume surface with both the completed slice and the next missing paper-parity gap; do not let focused tests narrow the recorded objective. If the user names source demos, videos, or project pages, keep the corpus matrix explicit: which scenes/experiments are represented by tests, py-demos, visual artifacts, benchmark JSON, CPU reference comparisons, and GPU parity, and which rows remain missing.
3. Keep the plan manageable:
   • revise an existing initiative before adding a duplicate;
   • use stable initiative IDs when renaming, splitting, consolidating, or parking work;
   • keep docs/plans/dashboard.md as the single source of truth for priority, status, horizon, dimension, next step, and gate.
   • when deriving packets or dev-task work, include the DART specification intake from docs/ai/orchestration.md: value, scope, non-goals, assumptions/open decisions, acceptance evidence, gates, and dependencies. Use owner-local Decision needed blocks for consequential ambiguity instead of silent defaults.
4. For discussion-only requests, present the tradeoff and proposed plan delta; do not edit unless the user asks for an edit or the request already implies one.
5. For plan edits, update docs/plans/dashboard.md for operating state, the detailed numbered initiative file or external owner document for rationale and workstreams, and docs/plans/north-star-roadmap.md only for strategic framing.
6. If the plan item becomes implementation work, route to /dart-new-task in Claude/OpenCode or $dart-new-task in Codex, and use docs/dev_tasks/README.md when it is multi-session or needs design tracking.
7. Verify with docs/ai/verification.md: use the docs-only gate for plan-only docs, and the AI docs/adapters gate set when AI docs, workflow sources, or generated adapters change.
8. Do not perform GitHub or remote mutations without explicit maintainer/user approval.

Output

• Request classification (discussion, plan edit, or task derivation)
• Plan files changed and the operating-state updates made
• Verification gate run
• Any routed follow-up task or Decision needed block recorded

dart-pr

Use this skill in Codex to run the DART dart-pr workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-pr <arguments>
• Codex: $dart-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Prepare or open a DART pull request after explicit maintainer/user approval: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ai-tools.md @docs/onboarding/changelog.md @.github/PULL_REQUEST_TEMPLATE.md

Recent PR Patterns

When the expected PR style is unclear, inspect recently merged PRs before drafting the title or body:

gh pr list --repo dartsim/dart --state merged --base main --limit 10 \
  --json number,title,body,mergedAt

Use these practices:

• Keep titles plain, scoped, and outcome-focused. Do not add agent prefixes.
• Fill the PR template in DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first because reviewers need the skimmable outcome before the rationale. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then keep the fuller why in Motivation / Problem rather than moving it above Summary.
• Write Summary and Motivation for a user or downstream maintainer unfamiliar with the implementation: lead with what changes for them, what stays compatible, how they opt in or migrate, and why the evidence matters. Keep implementation mechanics in Changes unless they explain a user-visible outcome or risk.
• When the change has user-facing API, workflow, behavior, or performance impact, add a concise ## Before / After section before Testing covering only relevant dimensions (public API, commands/workflows, behavior, migration, performance baseline). Phrase each row as a user-visible before/after, then name the mechanism as supporting context. For performance claims, name the baseline explicitly (CPU path, parent commit, main, or prior implementation) plus workload, metric, and limitations.
• In Testing, list exact commands, targets, or test names that ran. For CI, performance, or infrastructure work, include evidence such as CI observations, timing, reruns, benchmark output, or why a skipped check is expected.
• For model/scene, dynamics, collision/contact, simulation, rendering, mesh, texture, GUI, or visual-example changes, use dart-verify-sim: report the text correctness oracle and include assessed, claim-relevant visual/debug evidence when applicable (an image alone is not correctness proof):
  • Prefer an existing headless example path (--headless, --frames, --width, --height, --screenshot) over manual screenshots. Capture before and after with the same camera, dimensions, frame count, and renderer; restore the replaced sample/assets or use the base branch to capture the before image. Inspect the images yourself and include the commands and any software-rendering flags in the PR body.
  • Upload transient comparison images, GIFs, and videos through the GitHub PR/issue Markdown attachment flow so the body contains GitHub-hosted https://github.com/user-attachments/assets/... URLs. Do not commit transient visual evidence; commit visual files only when they are durable documentation, fixtures, or source assets.
  • The supported attachment flow is the web PR/issue editor; gh pr edit, gh pr comment, and the REST API do not provide a generic upload, and any command that edits or comments on a PR still requires explicit maintainer/user approval. If the current tool cannot upload attachments, keep the local artifact paths in the working note, ask a maintainer to upload them, then update the PR body with the returned URL after explicit maintainer/user approval. Do not fall back to committing evidence into docs/assets/.
  • If no headless path exists, add a narrowly scoped capture mode when it fits the example or document why visual comparison is not practical.
• Mark non-applicable checklist items as "N/A" with a short reason, and mention related PRs, issues, backports, and follow-ups explicitly, including "None".

Workflow

1. Inspect scope:

   git status --short --branch
   git diff --stat
   git diff --check
   

2. Exclude unrelated dirty files unless the user explicitly includes them.

3. Choose the target branch and milestone:

   Target	Milestone
   main	DART 7.0
   Active DART 6 LTS release-6.*	Branch-matching DART 6.x patch

4. For bug fixes, use the dual-PR flow: fix the active DART 6 LTS branch first, then cherry-pick or reapply to main.

5. Before every commit, run pixi run lint. Also run pixi run build for C++ or Python changes and focused tests for behavior changes.

6. Create or update a topic branch when needed:

   git checkout -b <type>/<topic> origin/<target-branch>
   

7. Commit only intended files with a plain descriptive commit title.

8. Merge the latest base branch into the PR branch before any push, and follow the base-merge and automated-review rules in docs/onboarding/ai-tools.md (no inline bot replies; @codex review re-triggers are throttled to one per approved review-fix round). Ask for explicit maintainer/user approval before pushing or opening the draft PR. After approval:

   git push -u origin HEAD
   gh pr create --draft --base <target-branch> --milestone "<milestone>" \
     --title "<plain title>" --body-file <filled-template-file>
   

9. Prefer additive follow-up commits for updates to a published PR. Amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).

10. Invoke the dart-changelog routine for the changelog decision, entry wording, and PR-link follow-up. If CHANGELOG.md needs the PR number, keep the follow-up changelog commit local until explicit maintainer/user approval is given for the additional push or PR update.

11. Monitor CI: gh pr checks <PR_NUMBER>.

Output

• Branch, target base, and milestone used
• Commit titles and files included
• PR URL and draft/ready state, or the prepared PR text awaiting approval
• Changelog decision
• CI status and any remaining blocker

DART Python Bindings (dartpy)

Load this skill when working with Python bindings or dartpy.

When a binding exposes or changes model/scene loading, dynamics, collision/contact/constraints, simulation stepping, GUI/rendering output, or a visual example, also load dart-verify-sim. Pair a focused Python text/behavior oracle with an assessed, claim-tied headless capture; document a visual exception when rendering is unavailable or not applicable.

Quick Start

import dartpy as dart

world = dart.World()
skel = dart.io.read_skeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf")
world.add_skeleton(skel)

for _ in range(100):
    world.step()

Full Documentation

For complete Python bindings guide: docs/onboarding/python-bindings.md

For module-specific details: python/AGENTS.md

Quick Commands

pixi run build-py-dev    # Build for development
pixi run test-py         # Run Python tests
pixi run generate-stubs  # Generate type stubs

Wheel Building

pixi run -e py314-wheel wheel-build
pixi run -e py314-wheel wheel-repair  # Linux only
pixi run -e py314-wheel wheel-test

Key Patterns

• snake_case preferred (camelCase emits DeprecationWarning)
• NumPy arrays auto-convert to Eigen types
• GUI requires DART_BUILD_GUI=ON

Key Files

• Package config: pyproject.toml
• Build system: python/dartpy/CMakeLists.txt
• Type stubs: python/stubs/dartpy/

DART Research References

Load this skill when adding, updating, auditing, or citing research references (papers, textbooks, model-format standards, or comparative engines) for the DART experimental simulation world — its public API and its algorithms.

Catalog Location

docs/readthedocs/papers.md is the single source of truth and the published website page. It is a companion to the experimental API design docs:

• docs/design/simulation_cpp_api.md
• docs/design/simulation_python_api.md

Entry Schema

Each entry has an id, a full citation, and these properties:

Status is written from the experimental world's perspective. A method shipping in classic DART but not yet in the experimental world is planned, with the classic location noted in Notes.

Workflow: add or update an entry

1. Ground the entry in real evidence — a design doc, code path, test, or an explicit project decision. Do not add aspirational references with no link.
2. Write an accurate citation (authors, title, year, venue/publisher). Prefer an official URL; do not fabricate DOIs.
3. Add a row to the matching summary table and a detail subsection with the full properties and a one-line rationale.
4. Set Status from the experimental world's perspective; note classic-DART status separately in Notes.
5. Set Verdict (adopt to build on, baseline to compare against, reference to cite, evaluate while undecided, reject with a reason).
6. Fill Where used with the design-doc/code/test link.
7. When the relationship changes (e.g. a planned algorithm becomes implemented, or an evaluate is decided), update Status/Verdict and the Where used link in the same change.

Rules

• Prefer robotics/dynamics literature (textbooks, papers) over engine-specific names when a reference informs a terminology decision; record the grounding in the catalog's "Terminology Grounding" section.
• Keep the catalog scoped to the experimental world for now; the schema is general and can extend to the rest of DART later.
• Keep engine entries as baselines/comparisons, never as dependencies.
• Use docs/ai/verification.md to select the docs-only or AI docs/adapters gate set, then run pixi run lint after edits.

Full Documentation

For the catalog and its rationale: docs/readthedocs/papers.md

For the API it supports: docs/design/simulation_cpp_api.md, docs/design/simulation_python_api.md

For DART's research focus: docs/ai/north-star.md

dart-release-merge-main

Use this skill in Codex to run the DART dart-release-merge-main workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-release-merge-main <arguments>
• Codex: $dart-release-merge-main <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Merge release branch into main: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/release-management.md @docs/onboarding/ci-cd.md

Workflow

1. Auto-detect or confirm the active release branch and release version:

   git fetch origin
   git branch -r | grep -oE 'origin/release-[0-9]+\.[0-9]+' | sort -V | tail -1
   

2. Verify the clone is not shallow and a merge base exists.
3. Create merge/<release-branch>-into-main from origin/main.
4. Merge the release branch with a title like Merge release-6.19 into main (v6.19.x).
5. Resolve conflicts using docs/onboarding/release-management.md:
   • deleted in main, updated in release: keep deleted
   • added in both: prefer main unless release has unique needed content
   • content conflicts: prefer main modernization except for manually reviewed changelog entries
   • files only on release: keep if still relevant to main
6. Verify no unresolved conflicts remain.
7. Run pixi run lint and relevant checks.
8. Ask for explicit maintainer/user approval before pushing or creating the PR. After approval, create a PR targeting main with milestone DART 7.0 and use the PR template.
9. Monitor CI until green.

Output

• PR URL and CI status
• Release branch and release version
• Conflict counts and resolution summary
• Any manual changelog decisions

dart-release-packaging

Use this skill in Codex to run the DART dart-release-packaging workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-release-packaging <arguments>
• Codex: $dart-release-packaging <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Create release packaging PR after explicit maintainer/user approval: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/release-management.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Workflow

1. Confirm the new version, for example 6.16.6.
2. Derive the release branch: release-<major>.<minor>.
3. Fetch and branch from the release branch:

   git fetch origin <RELEASE_BRANCH>
   git checkout -B release/<NEW_VERSION>-version-bump origin/<RELEASE_BRANCH>
   

4. Bump versions in package.xml and pixi.toml.
5. Update version requirements in examples/tutorials if needed.
6. Invoke the dart-changelog routine in release-audit mode, then add or finalize the CHANGELOG.md release section with the release date, milestone link, release summary, and audit from docs/onboarding/changelog.md.
7. Run pixi run lint and relevant packaging checks.
8. Commit as Packaging <NEW_VERSION>.
9. Ask for explicit maintainer/user approval before pushing, creating the PR, or setting milestones.
10. After approval, create the PR against the release branch with the release milestone for that branch, for example the specific version milestone if available.

Output

• PR URL
• Version files changed
• Changelog section added
• Checks run

dart-resume

Use this skill in Codex to run the DART dart-resume workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-resume <arguments>
• Codex: $dart-resume <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Resume unfinished work: $ARGUMENTS

Objective

dart-resume is a completion-oriented task manager, not a status lookup or a single-slice helper by default. Resume the named or reconstructed work, build or refresh the execution plan, track progress in the repo-owned task surface, split independent work into verifiable packets, use subagents/sub-sessions only when the user explicitly requested delegation and the current AI surface permits it, verify every result, and keep going until the whole task is complete or a real blocker or approval boundary remains.

Decisions must be evidence-based. Before choosing between meaningful options, first improve or define the verification/debugging method so it can catch false positives and false negatives. Use repository inspection, focused tests, benchmarks, A/B comparisons, GUI or visual evidence, logs, and external resource searches as needed to decide from evidence instead of preference.

For a docs/dev_tasks/<task> target, full completion means all feasible task work is finished, durable decisions and deferred work are promoted, and the temporary dev-task folder is removed in the completing change. Do not stop after one successful slice unless the user explicitly requested a limited mode.

Argument Handling

Use $ARGUMENTS to identify the target, explicit scope limits, and execution modifiers. Interpret arguments in this order:

1. Explicit scope-limited mode: if arguments include status, audit-only, plan-only, slice, or next-slice, honor that limit and state it in the plan. Without one of these limiters, do not downscope the session to a single slice.
2. Execution modifiers: if arguments include no-subagents, run serially but keep the same whole-task completion objective. If arguments explicitly request subagents, parallel, delegation, or workers, use available AI-native delegation when the current surface permits it. Tool-use modifiers do not limit scope unless paired with an explicit scope-limited mode.
3. Explicit target path: if an argument names docs/dev_tasks/<task> or a file under that folder, treat that dev task as the target and read its README.md and RESUME.md after recon. Resolve relative paths from the repo root discovered by git rev-parse --show-toplevel, not from the launch directory.
4. Closeout wording: words such as complete, finish, retire, close out, or cleanup are accepted but not required for dev-task completion. Treat retire / close out as emphasis that the likely end state is durable-doc promotion plus folder removal.
5. Branch/PR/issue hint: otherwise, treat arguments as a branch, PR, issue, topic, or free-form resume hint and reconstruct the task from live repo state.

Examples:

$dart-resume docs/dev_tasks/dart7_core_dynamics_perf_forwardport
$dart-resume docs/dev_tasks/dart7_core_dynamics_perf_forwardport --slice
$dart-resume PR 2991

Required Reading

@AGENTS.md @docs/dev_tasks/README.md @docs/ai/sessions.md @docs/ai/verification.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Workflow

Recon (no changes)

git rev-parse --show-toplevel
git status -sb && git branch -vv && git log -10 --oneline --decorate
git diff --stat && git stash list
gh pr list --head "$(git branch --show-current)"
gh pr status

Reconstruct

If $ARGUMENTS names a docs/dev_tasks/<task> path, use that folder as the target and inspect its README.md, RESUME.md, and any directly referenced owner docs before choosing work. If the folder is already absent, verify whether it was retired on current main, identify the durable owner doc that replaced it, and report that no folder cleanup remains.

Otherwise infer the task from branch name, commits, diffs, issue/PR description, and any docs/dev_tasks/<task>/ state. If the goal is still unclear after recon, stop and ask.

Before editing, write explicit pass/fail criteria for the resumed task:

• what exact dev-task folder, branch, PR, issue, or topic is being completed;
• which remaining checklist items, decisions, or evidence must be resolved;
• how progress will be tracked during this session and across any handoff;
• which independent subtasks, if any, can be delegated when explicitly authorized or run as separate serial sessions without creating conflicting edits;
• which verification/debugging method will make false positives and false negatives unlikely before implementation decisions are made;
• which A/B tests, benchmarks, resource searches, GUI checks, or textual checks are needed to support consequential decisions;
• which durable docs will own any surviving decision or deferred work;
• whether the resumed change may need a changelog entry and how the dart-changelog decision will be recorded;
• which verification commands prove the result.

Continue

• Propose a 3-6 step plan before editing.
• Continue with minimal scope and preserve existing user changes.
• Verification comes first when the route is uncertain. Define the observable signal, build or select the smallest reproducer/check, run a control vs candidate comparison when possible, and only then choose the implementation path. If the existing verification is weak, improve the check or debugging surface before trusting the result.
• For model/scene, simulation, dynamics, collision/contact, GUI, or visual behavior, route through dart-verify-sim: establish a text correctness oracle first, then capture assessed claim-tied images/debug layers or record an unavailable/not-applicable reason. Verify the expected pass path and a failure-sensitive condition when practical; a screenshot alone is not proof.
• When the decision depends on behavior outside the repository, search the relevant upstream docs, papers, issues, standards, or release notes and record the source-backed conclusion in the task docs, durable owner doc, or PR evidence. Prefer primary sources.
• If the task is large, decompose it into independently verifiable work items. Use available AI-native subagent, sub-session, or parallel-worker support only when the user explicitly requested delegation and the current surface permits it. Otherwise, keep the decomposition as a serial plan or explicit handoff packets. Validate and integrate every delegated result yourself; repo-tracked docs remain the source of truth even when agent-specific orchestration is available.
• Keep progress tracking current in the task's README.md, RESUME.md, or durable owner doc after meaningful progress. If the current session cannot finish because of context, environment, approval, or a real blocker, leave the next session with exact current reality, remaining work, blockers, and gates.
• For active solver/paper implementations, keep the plan or dev-task resume surface explicit about the completed slice, the next missing paper-parity gap, and why focused green tests are not a full paper-completion claim.
• Run a completion audit before finalizing a dev-task target: identify the exact docs/dev_tasks/<task>/ folder, inspect it for remaining plans/evidence/decisions, promote any durable dashboard, evidence matrix, API inventory, migration map, long-lived decision, or deferred-but-real work into docs/plans/, docs/design/, or docs/onboarding/, update dashboard/plan progress when the task changes roadmap state, then remove the dev-task folder completely in the completing change.
• In completion mode, do not leave the long-form resume prompt to carry decisions. Record the final decision or parked follow-up in the durable owner doc, then delete or update the dev-task folder according to docs/dev_tasks/README.md.
• Before finalizing a resumed task that changes behavior, public API, packaging, CI, docs workflow, AI-infra workflow, release process, or user-visible docs, invoke the dart-changelog routine in decide or finalize mode. If no entry is needed, keep the reason in the local PR body/checklist draft or task evidence; if an entry is needed, prepare the local CHANGELOG.md edit and PR link when available. Pushing the changelog edit or updating the PR body still requires explicit maintainer/user approval.
• If remaining work is real but blocked by a substantial design decision, maintainer direction, external dependency, or scope boundary that should not be resolved in the current session, ask the human before retiring the folder unless prior maintainer direction is already recorded. Record the parked or blocked work in the durable owner doc before deletion.
• Do not call a dev task complete while docs/dev_tasks/<task>/ still exists. If implementation is done but the folder remains, the remaining work is the durable-doc promotion plus folder cleanup.
• Run pixi run lint before committing. Run relevant tests; use pixi run test-all before done when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime.
• Merge the latest base branch into any published PR branch before pushing, and follow the base-merge rules in docs/onboarding/ai-tools.md. Push with git push -u origin HEAD and create or update the PR only after explicit maintainer/user approval, preferring additive follow-up commits.

Safety

No destructive git commands (reset --hard, dropping stashes, deleting branches) without explicit maintainer/user approval.

Output

• Reconstructed task and current branch/PR state
• Plan followed and files changed
• Verification commands run and their results
• Completion-audit result: dev-task promotion/cleanup done or the remaining blocker
• PR readiness, noting any external mutation that was explicitly approved

dart-retro

Use this skill in Codex to run the DART dart-retro workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-retro <arguments>
• Codex: $dart-retro <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Run a retrospective and capture durable lessons: $ARGUMENTS

Required Reading

@AGENTS.md @docs/AGENTS.md @docs/ai/principles.md @docs/ai/components.md @docs/ai/verification.md @docs/onboarding/ai-tools.md

Skip If

Stop without editing when all are true:

• no new patterns, gotchas, or failure modes were discovered
• no workflow improvement is needed
• the learning is too session-specific to help future agents or contributors
• existing docs already cover what happened
• the task was routine and left no durable insight

Routing

docs/ai/components.md owns routing for durable session learnings. Use this command as the hindsight workflow; do not duplicate the routing table here.

Workflow

1. Search existing docs before adding content.
2. Inventory the completed work before routing lessons. Consider domain/design choices, public API or package compatibility, CI/review failure modes, workflow friction, and cleanup or handoff steps separately so a late operational task does not hide feature-level learnings.
3. Decide whether each lesson is general enough for shared AI infra. Do not update AI components after every session.
4. Prefer update, remove, consolidate, or restructure over adding new files.
5. Make every durable learning discoverable from its owner surface: update an existing owner doc when possible, and when a new durable file is justified, link it from the relevant owner index or plan before retiring temporary context.
6. Keep docs/ai/principles.md compact; put procedures in the owner docs it links to.
7. Avoid ephemeral branch, PR, commit, or username details.
8. If adding a workflow command or skill, edit .claude/ source files and run pixi run sync-ai-commands.
9. Run pixi run lint before committing. For AI docs or adapter changes, also run the verification gates from docs/ai/verification.md: pixi run lint-md, pixi run check-lint-md, pixi run sync-ai-commands, pixi run check-ai-commands, pixi run check-docs-policy, and pixi run check-lint-spell.

Output

• What learning was captured
• Where it was documented
• Checks run

dart-review-pr

Use this skill in Codex to run the DART dart-review-pr workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-review-pr <arguments>
• Codex: $dart-review-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Review or respond to PR: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/code-style.md @docs/onboarding/ai-tools.md (for AI-generated review handling) @docs/ai/verification.md

Workflow

Pick the sub-workflow from mode= in $ARGUMENTS, defaulting to review.

Review

gh pr view $1 && gh pr diff $1

Check code style, tests, docs, and focused commits. When a claim depends on 3D structure or behavior, require the dart-verify-sim text oracle and claim-relevant assessed visual/debug-layer evidence (or a justified replacement), and inspect both rather than accepting a screenshot alone. Record findings as read-only output; do not push, comment, resolve threads, or re-trigger review without explicit maintainer/user approval for that external mutation.

Address Feedback

gh pr view $1 --comments

Apply minimal fixes locally and verify. For published PRs, prefer a new follow-up commit so reviewers can inspect each round; amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).

1. Make the local fix silently (no reply), then run the relevant local gates, including pixi run lint before any commit.
2. Merge the latest base branch into the PR branch before any push, and follow the base-merge, automated-review, and bot no-reply rules in docs/onboarding/ai-tools.md. If the push is rejected because the remote head moved, fetch and compare it before retrying and validate an equivalent remote fix instead of pushing a duplicate.
3. Ask for explicit maintainer/user approval before any push, PR comment, thread resolution, or review re-trigger. After approval, push silently, resolve only reviewed and addressed thread IDs via GraphQL, and — when the approved push addressed Codex comments — re-trigger once with gh pr comment $1 --body "@codex review".
4. Apply the same no-inline-reply loop to github-code-quality[bot] findings; do not re-trigger Codex solely for non-Codex bot findings unless Codex comments were also addressed.
5. Monitor CI (gh pr checks $1) and repeat until no actionable comments remain. For draft PRs, mark ready after explicit approval once Codex is clean and local validation passes on the current head (default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime); merge still waits for required hosted checks.

Output

• PR number and whether the pass was a review or a feedback round
• Findings or fixes applied, with file/line references
• Which actions were local-only and which external mutations were explicitly approved
• Codex/CI state and any remaining blocker

DART Testing

Load this skill when writing or debugging tests.

Quick Commands

pixi run test         # Quick test run
pixi run test-all     # Full validation
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run test-unit    # Unit tests
pixi run test-py      # Python tests

Full Documentation

For complete testing guide: docs/onboarding/testing.md

For CI/CD troubleshooting: docs/onboarding/ci-cd.md

Test Organization

• Unit tests: tests/unit/
• Integration tests: tests/integration/
• Regression tests: Near the code they test

Writing Tests

1. Follow existing patterns in the test directory
2. Use GoogleTest framework
3. Name tests descriptively: TEST(ClassName, MethodName_Condition_ExpectedResult)

CI Validation

Before submitting PR:

pixi run lint         # Must pass
pixi run test-all     # Must pass
pixi run -e cuda test-all # Must pass on Linux CUDA hosts

Debugging Test Failures

# Run the smallest existing Pixi test task that covers the failure
pixi run test-unit

# Get CI logs
gh run view <RUN_ID> --log-failed

Simulation And Visual End-to-End Checks

When a failure or change depends on scene structure, dynamics, collision/contact, simulation stepping, GUI output, or a visual example, also load dart-verify-sim. Use its text-first oracle and then an assessed headless capture with claim-relevant debug layers. Record a concrete no-visual reason only when that corroboration is unavailable or not applicable.

Gotchas

• pixi run build builds libraries only, NOT the unit-test binaries. If you run ctest without building the test target first, you may execute stale binaries that silently pass. Build the test target before running its label, e.g. for the simulation suite: pixi run build-simulation-tests (target dart_simulation_tests) before ctest -L simulation.
• pixi run test-all is the default-environment full gate. On Linux hosts with a visible NVIDIA CUDA runtime, also run pixi run -e cuda test-all; the CUDA run preserves the cuda Pixi environment and executes the CUDA CTest + benchmark smoke path when the runtime is detected.
• The CUDA Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES; unsupported PTX/toolchain errors usually mean the generated CUDA architecture flags need to be checked before blaming test code.

dart-triage-issue

Use this skill in Codex to run the DART dart-triage-issue workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-triage-issue <arguments>
• Codex: $dart-triage-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Triage issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md

Workflow

1. Inspect the issue:

   gh issue view <ISSUE_NUMBER> --comments
   

2. Determine whether the report is still valid on current origin/main.
3. Classify status:
   • still valid
   • already fixed
   • needs more information
   • duplicate
   • out of scope
4. If validity depends on behavior, reproduce or inspect the relevant code path.
5. Do not close or comment unless the user explicitly asks for that action.

Output

• Status
• Rationale in 1-3 bullets
• Recommended next step
• Suggested reply text, if useful

dart-ultrawork

Use this skill in Codex to run the DART dart-ultrawork workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

• Claude Code/OpenCode: /dart-ultrawork <arguments>
• Codex: $dart-ultrawork <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Start a team-scale or autonomous DART task: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/ai/orchestration.md @docs/ai/sessions.md @docs/ai/verification.md @docs/dev_tasks/README.md

Load additional owners only when the matching phase needs them:

• placement or cleanup: docs/information-architecture.md;
• numbered-plan selection or packet state: docs/plans/dashboard.md;
• version control, changelog, tools, or review: docs/onboarding/{contributing,changelog,ai-tools}.md.

Arguments

$ARGUMENTS is a task brief plus optional mode flags:

• mode=interview: ask one up-front batch of critical questions.
• mode=brief: treat provided context as sufficient unless escalation applies.
• mode=resume: start from the existing docs/dev_tasks/<task>/ project home and run the session-start protocol before changing files.
• interview=skip: skip maintainer questions only when the brief already answers all consequential decisions.

The brief may be prose or a structured TASK / CONTEXT block. Extract north star, deliverable, acceptance criteria, constraints, risks, references, paths, issues/PRs/branches, commands, and first step when present.

Workflow

You are the orchestrator, supervisor, and steerer for the entire task: you decompose, delegate, review, and keep evidence honest. Workers implement. Follow the orchestrator/executor contract and packet sizing rules in docs/ai/orchestration.md. Use dart-new-task instead when the work is a bounded single-session task and the user did not ask for autonomous project handling.

1. Session start and current reality - Locate the project home. For DART autonomous projects this is docs/dev_tasks/<task>/, not a parallel project directory. If it exists, read its README.md, RESUME.md, and any autonomous sidecars such as decisions.md, verification.md, or progress-log.md; then verify checkout state, current branch, and any branch/PR evidence named by the docs. Run pixi run ai-doctor when setup, discovery, instruction, agent, or hook state is uncertain. If the docs are stale, update the handoff/current-reality note before relying on them. If no project home exists and the task is multi-session, team-scale, design-heavy, risky, or explicitly autonomous, create docs/dev_tasks/<task>/ before implementation. If prior work exists elsewhere, first absorb or summarize it into the project home.
2. Understand and scout - Restate the north star, final deliverable, acceptance criteria, quality bar, non-goals, constraints, risks, and target branch line (DART 7 main, DART 6 LTS, or both). Scout the territory first with named docs/code, read-only searches, a dart-analyze pass, the Codex dart_scout profile, or focused reference review; draft a candidate decomposition privately before asking anything.
3. Interview decisions; self-resolve uncertainties - Ask at most one up-front batch of critical questions. Escalate before destructive operations, history rewrites, irreversible migrations, meaningful cost, security/credential/secret handling, legal or privacy-sensitive decisions, major product-direction choices not covered by the brief, conflicts with stated constraints, or any assumption whose wrong answer could cause significant harm. If input is unavailable, choose the safest reversible path, document the assumption, and continue only with non-blocked work. Then split consequential unknowns:
   • Maintainer decisions: preference, scope, public API, release, quality-bar, or roadmap calls that evidence cannot settle. Ask the human now in one batched interview (focused questions with 2-4 concrete options each, recommendation first). Do not start large work while a consequential decision is open. Skip this discretionary interview when mode=brief; also skip when interview=skip and the prompt already answers everything consequential. In both cases, still follow the escalation rules above.
   • Evidence-resolvable uncertainties: anything a focused A/B test, benchmark, throwaway spike, reference lookup, or blind-spot review can settle. Do not ask the human; schedule these as spike/research packets and record the method and result as evidence (see "Discovering unknowns before committing" in docs/ai/orchestration.md).
4. Create or refresh the tracking surface - Populate the project home with value, north star, deliverable, scope, non-goals, assumptions, risks, acceptance evidence, gates, dependencies, milestone, next actions, and blockers. Claim-dependent physics/simulation, collision/contact, model, GUI, and visual-example work routes through dart-verify-sim: require a text oracle plus assessed visual/debug evidence, or a justified replacement. Keep RESUME.md as the handoff; add decisions.md, verification.md, and progress-log.md sidecars when they improve resumability or evidence.
5. Set the goal contract - Express done-when as verifiable outcomes (files, tests, gates, artifacts). When the session supports a goal or stop-hook mode (for example /goal in Claude Code), set it to this contract so orchestration cannot stop early or loop forever. Stop once the acceptance criteria are satisfied, verification is recorded, docs are current, known gaps are documented, and unnecessary work has been removed or deferred. Every delegated packet gets its own contract: GOAL (one sentence), DONE WHEN (verifiable), EVIDENCE (what to record), RISKS, and NEXT STEP.
6. Decompose and route to workers - Cut work packets per docs/ai/orchestration.md, then route by docs/ai/README.md. For Codex, use dart_scout for read-only territory mapping, built-in workers or dart-execute-packet for bounded implementation, dart_reviewer for independent acceptance review, and dart_release_auditor for branch adaptation. Without team tooling, execute packets sequentially. Use parallel writers only when file ownership is explicit and disjoint.
7. Run the autonomous work/review cycle - For each meaningful chunk: plan, execute, verify, then run an independent/specialized review lane. Treat review findings as hypotheses: investigate, fix or record no-fix evidence, clean up, re-verify, and re-review. A packet is not done until the current post-fix state has at least two clean review passes recorded.
8. Supervise and steer - Monitor progress; unblock, reassign, or re-cut packets on scope mismatch. Workers return Task, Summary, Files changed, Evidence/tests, Risks, and Recommended next step. Use another tool, an independent session, or the bounded specialist profiles when available; fall back to role-separated local review only when unavailable. Root-cause failures and fold newly discovered unknowns back into step 3.
9. Update docs at each stopping point - Every meaningful cycle updates the project home: README.md for status/plan/risks, RESUME.md for the next fresh-session handoff, decisions.md if decisions changed, verification.md if checks ran or gaps were found, and progress-log.md for completed chunks when that sidecar exists. Keep docs current enough for a zero-context session to resume without hidden chat memory.
10. Version-control and closeout - Keep commits and PRs coherent: separate feature work, bug fixes, refactors, docs, experiments, and AI-infra changes when practical; review the diff, remove unrelated changes, make the changelog decision, and run pixi run lint before commits. Run task-specific gates from docs/ai/verification.md, record evidence per packet, and complete the principle audit. A project is complete only when the north star and acceptance criteria are met, verification evidence is recorded, docs are current, known gaps are documented, unnecessary work is removed or deferred, and final state is summarized in RESUME.md or a durable owner. Promote durable artifacts out of docs/dev_tasks/<task>/ and remove the folder in the completing PR. GitHub mutations (push, PR, comments, re-triggers) only with explicit maintainer/user approval.

Kickoff Prompt Template

Canonical fresh-session prompt. TASK, context, and Done when are per-task; reuse the Logistics block verbatim.

TASK: <one-sentence objective>

<Per-task context: constraints, quality bar, must/never rules, and pointers
to the docs, code, branches, or references that define the territory.>

Done when:
- <verifiable outcome: a file, test, gate, benchmark, or artifact>
- <verifiable outcome>

Logistics:
- Run /dart-ultrawork with this task. You are the orchestrator,
  supervisor, and steerer: decompose, delegate, review, and keep evidence
  honest.
- Interview first: ask the maintainer only the consequential decisions that
  evidence cannot settle; resolve everything else yourself and record the
  evidence.
- Use docs/dev_tasks/<task>/ as the project home. Keep README.md,
  RESUME.md, and any decisions.md / verification.md / progress-log.md
  sidecars current enough for a zero-context session to resume.
- Prioritize correctness over speed, but stop once acceptance criteria are
  satisfied, verification is recorded, docs are current, and known gaps are
  documented. Manage resources responsibly; avoid endless exploration and
  low-value polishing.
- Route well-defined implementation packets to bounded workers with GOAL /
  DONE WHEN / EVIDENCE. Use team mode only when available and file ownership
  can stay disjoint. Keep authoring and review separate; use the strongest
  available reasoning for critical decisions, hard failures, and research
  synthesis.
- Set goal mode to Done-when; use Claude `/goal Run /dart-ultrawork with:
  <real prompt>` or Codex `/goal $dart-ultrawork <real prompt>`. Treat Claude
  goal text beginning `ulw:` or `ultrawok:` as shorthand for the same canonical
  `/dart-ultrawork` workflow, not as separate capabilities.
- Read docs/ai/principles.md, docs/ai/north-star.md,
  docs/ai/orchestration.md, and docs/ai/sessions.md before starting.
- Review loop: use specialized reviewers when available, investigate findings,
  and require two clean passes on the current state before done.
- Verification first: task-specific gates and dart-verify-sim evidence when
  applicable; pixi run lint before commits; GitHub mutations only with approval.

Output

• Interview record, uncertainty-resolution evidence, and project-home path
• Packet list, routing, goal contracts, gates, and review-loop status
• Per-packet evidence, GUI/demo artifacts when relevant, and updated docs
• Principle audit, cleanup status, and approved external mutations

DART Simulation Verification

Load this skill when verifying that a DART 3D scene or physics simulation is correct — implementing, debugging, benchmarking, or reviewing dynamics, collision, contact, or GUI output. DART's domains need 3D understanding that language models lack natively; this tooling makes it checkable without a GUI.

Lead with text, corroborate with images. Measured A/B evidence: per-step metrics and trajectories detect nearly all seeded physics defects; a rendered image alone misses static geometry defects (penetration, interpenetration). Decide correctness from text; use images for scene comprehension and gross dynamic failures.

Applicability contract

Use this skill for any task whose claim depends on 3D structure or behavior: model/scene loading, dynamics, collision/contact/constraints, simulation stepping, GUI/rendering, or visual examples. First run a text oracle (metrics, scene diff, trajectory/contact comparison, or focused behavioral test), then corroborate it end to end with an assessed headless view and only the debug layers needed by the claim. If rendering is unavailable or genuinely irrelevant, record why and name the replacement evidence; never treat an image as the sole correctness oracle.

Full documentation

docs/onboarding/agent-sim-verification.md — the durable guide. docs/ai/verification.md owns the gate policy; docs/onboarding/profiling.md owns text-first profiling.

Quick commands

Text (primary):

• world.compute_step_metrics() — energy/momentum/penetration/contacts/residual
• dartpy.dump_scene_json(world) / dump_scene_text(world) — "what is in this world?" (glTF/USD-flavored hierarchy + flat index)
• pixi run scene-diff — structural JSON verdict for intended-vs-actual scene dumps
• pixi run trajectory-record / pixi run trajectory-compare — per-body TSV + contact JSONL; bit-exact or tolerance diff with first-divergence

Visual (corroboration):

• dart.gui.render(world, camera=None, size=(w, h), debug=(...layers...)) → headless image with optional world-derived debug layers (grid, world_frame, body_frames, coms, inertia_boxes, collision_bounds, velocities, contacts, labels; trajectories additionally requires a sampled dart.gui.TrajectoryTracker via debug_scene_for_world); dart.gui.render_annotated(...) composites label text; .png_bytes() for notebooks; dart.gui.orbit_camera(...) / look_at(...)
• dart.gui.assess_view(world, camera, size, focus=...) → ViewReport with issues (cropped/too-far/too-close/occluded/ambiguous); dart.gui.select_viewpoints(...) picks deterministic best views; dart.gui.frame_body/frame_region reframe onto a subject. Assess first; fix flagged views before capturing evidence.
• viewer camera flags: --view {three-quarter|front|side|top}, --camera-azimuth/-elevation/-distance/-target, --turntable N, --fit
• pixi run py-demo-capture — headless PNG/MP4 capture from Python
• pixi run agent-capture — deterministic evidence harness: auto/explicit cameras, debug layers, stills/turntable/motion video, reproducible sidecar
• pixi run image-compose — side-by-side / blend / diff-heatmap composites
• pixi run evidence-select — claim-driven artifact selection with recorded rationale; pixi run evidence-publish — PR "Visual verification" section with GitHub-hosted media (manual placeholders by default; gh-release upload only with --yes + maintainer approval)
• pixi run image-verdict / image-golden / image-sheet — JSON verdict, golden diff, contact sheet (contrast is report-only; --require-contrast to gate)
• pixi run image-ab-study — blind-judge detection deltas for single-view, multi-view, turntable, and annotated captures
• pixi run image-ab-round2 — prepare a blinded round-2 packet and score completed judge observations

Opt-in:

• pixi run render-golden-gate — opt-in golden gate (backend-specific golden, curated locally with -- --update; not default CI)
• pixi run rerun-trajectory — rerun.io inspection (opt-in; graceful when rerun-sdk is absent)
• pixi run verification-bundle — package text evidence plus still/grid images for a provider-neutral VLM or reviewer call

Default capture for agent review: one ~1280 px frame, UI hidden, 3/4 view; add a 9-frame grid for motion. Keep images as corroboration, never the sole oracle for static geometry.

DART 6 (release-6.20)

Equivalent capture over OpenSceneGraph: dart::gui::osg::setUpOffscreenViewer / captureOffscreen + dartpy bindings, pixi run capture (needs a real X server or Xvfb), the ported image tooling, and pixi run bm-boxes-headless for rendering-free determinism checksums.

DART 7 Architecture

Load this skill when working on the DART 7 simulation World, on solvers/physics domains/compute backends, or whenever a task needs the big-picture map of how DART 7 is generalized for multi-physics, multi-solver, and multi-backend simulation.

The design in one sentence

The World owns topology, time, and a configured set of solvers; each solver advances the dynamics of the entities in its physics domain, and couplers mediate interactions between domains — with parallelizable work expressed as compute-graph nodes that any backend executor runs. Users configure method families and policies, never solver registries, component storage, or execution backends.

Why three axes of choice

• Research, apples-to-apples. A new paper's algorithm should be reproducible and benchmarkable inside DART against baselines on shared foundations, not in a fork. New methods enter through DART-owned solver families.
• End-user choice. Users pick the solver method and (internally) backend that fit their accuracy/speed/platform needs.
• Auto-configuration. Defaults are selected from scene content so the easy path stays trivial; the backend seam is designed for later platform/scene-scale awareness without changing the public API.

Design vs current state (read both)

docs/readthedocs/architecture.md is the single-page map of the design and the options at each seam, with honest status markers. docs/design/dart7_architecture_assessment.md is the verified record of where the implementation still diverges from that design (no internal solver contract yet, conceptual-only Model/State split, executor seam unused by dynamics stages, missing apples-to-apples substrate) and owns the standing rule: new solver families enter only through docs/plans/solver-family-intake.md, including contract conformance and machine-recorded solver identity in all benchmark evidence. PLAN-091 retired the first living hardening packet plan; current follow-up work routes through docs/plans/dashboard.md, the intake checklist, and the durable owner docs named in the assessment. Do not write new code that copies a pattern the assessment still lists as a verified finding.

Key owner documents

The architecture page's Source-of-truth map is the single owner of the full topic → owner-doc mapping (solver, API, extension, compute, differentiable, clean-break, north-star). The docs an agent most often needs inline:

Public-facade rules (do not violate)

• Do not expose Solver, Coupler, PhysicsDomain, ECS storage, component types, executor/backend types, or solver registries as public API.
• Select behavior by documented method-family names and policy value objects.
• Backend names (CUDA, Taskflow, SIMD ISA) may appear in build flags, diagnostics, and benchmarks — never in public types, namespaces, or required configuration.
• Keep the easy path (World + addRigidBody/addMultibody + step) free of solver vocabulary.
• Fallbacks must never silently substitute algorithms: validate capabilities at finalize or record the substitution in diagnostics.

Verification

Use docs/ai/verification.md to select the docs-only or code gate set for the change. Implementation work that realizes parts of this architecture also follows the gates in docs/design/simulation_solver_architecture.md, the solver-family intake checklist, and any active owner plan named in docs/plans/dashboard.md.

DART Build System

Load this skill when working with DART's build system.

Quick Commands

pixi run config       # Configure CMake
pixi run build        # Build
pixi run test         # Run tests
pixi run test-all     # Full validation (lint + build + tests)
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run lint         # Format code

Full Documentation

For complete build instructions, read: docs/onboarding/building.md

For build system internals (CMake, dependencies): docs/onboarding/build-system.md

Common Issues

CUDA Notes

• On Linux hosts with visible NVIDIA GPUs, the CUDA Pixi config auto-detects compute capabilities for DART_CUDA_ARCHITECTURES; set DART_CUDA_ARCHITECTURES=<arch> only when overriding that detected list.
• If CUDA runtime tests fail with unsupported PTX/toolchain errors, verify the generated CUDA flags include the local GPU architecture before assuming a kernel bug.

Pixi Lockfiles

• Do not edit pixi.lock by hand. Change dependency constraints in pixi.toml, then run a Pixi command such as pixi install to let Pixi regenerate the lockfile.
• If pixi.lock changes format or has broad solver churn, keep the generated output and call it out in the PR rather than attempting to splice lockfile entries manually.

Filament GUI Visual Checks

• For Filament GUI, scene, or simulation rendering changes, load dart-verify-sim. Pair a text correctness oracle with agent-capture, view assessment, and claim-relevant engine debug layers; inspect the artifact and sidecar instead of relying only on command success.
• If the user explicitly asks for pixi run ex dartsim, also run that exact entry point and terminate it after confirming the GUI binary launches.

Key Files

• pixi.toml - Package management
• CMakeLists.txt - Build configuration
• cmake/ - CMake modules

DART CI/CD Troubleshooting

Load this skill when debugging CI failures or working with GitHub Actions.

When the failing claim depends on model/scene structure, physics behavior, or GUI/rendering output, also load dart-verify-sim and reproduce it with a text oracle plus assessed visual evidence. Document a visual exception when that renderer is unavailable or not applicable in the failing environment.

Quick Commands

# Monitor PR checks
gh pr checks <PR_NUMBER>
gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast

# View run details
gh run list --branch <BRANCH> -e pull_request -L 20
gh run watch <RUN_ID> --interval 30
gh run view <RUN_ID> --json status,conclusion,url

# Debug failures
gh run view <RUN_ID> --job <JOB_ID> --log-failed
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'

# Rerun failed jobs only after explicit maintainer/user approval
gh run rerun <RUN_ID> --failed
gh run rerun <RUN_ID> --job <DATABASE_ID>

Full Documentation

For complete CI/CD guide: docs/onboarding/ci-cd.md

Common Failure Modes

Workflow Architecture

CUDA Runner Policy

The project has a trusted ubuntu-latest-gpu runner for same-repository CUDA runtime validation, but it must never run untrusted fork-PR code. Consequences:

• Same-repository PRs, protected branch pushes, and manual dispatches use the GPU runner and run pixi run --locked -e cuda test-cuda.
• Fork PRs use a GitHub-hosted fallback and compile CUDA targets without running GPU-only steps.
• Local CUDA validation is pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime; local Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES.
• pixi run check-phase5-cuda-workflow enforces the trusted-event GPU guard and fork-PR hosted fallback in ci_cuda.yml.

Fast Iteration Loop

1. Identify failing step from job logs
2. Reproduce locally with same build toggles
3. Fix the smallest failing test
4. Push only after explicit maintainer/user approval, then monitor: gh run watch <RUN_ID>

Caching And Timing

Use the cache policy, current timing guidance, and investigation steps in docs/onboarding/ci-cd.md. Treat observed job duration and cache diagnostics from the affected run as the current evidence; do not copy mutable timing or hit-rate estimates into this skill.

DART Contribution Workflow

Load this skill when contributing code to DART.

Full Documentation

For complete guide: docs/onboarding/contributing.md

For code style: docs/onboarding/code-style.md

Branch Naming

• feature/<topic> - New features
• fix/<topic> - Bug fixes
• refactor/<topic> - Refactoring
• docs/<topic> - Documentation

PR Workflow

# Features, docs, and non-bugfix refactors start from main
git checkout -b <type>/<topic> origin/main

# Bug fixes that apply to the current release line start from the active DART 6 LTS branch
DART6_LTS_BRANCH=$(git branch -r --list 'origin/release-6.*' | sed 's|.*/||' | sort -V | tail -1)
git checkout -b "fix/<topic>-${DART6_LTS_BRANCH#release-}" "origin/$DART6_LTS_BRANCH"

# Make changes, then
pixi run lint
pixi run test-all
# On Linux hosts with a visible NVIDIA CUDA runtime
pixi run -e cuda test-all

# After explicit maintainer/user approval, push and create PR
git push -u origin HEAD
gh pr create --draft --base <target-branch> --milestone "<milestone>"

Use --base main --milestone "DART 7.0" for main PRs and the branch-matching DART 6.x patch milestone for active DART 6 LTS PRs.

Rule of thumb: run pixi run lint before committing so auto-fixes are included.

Use .github/PULL_REQUEST_TEMPLATE.md and keep DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first as the reviewer skim target. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then put the fuller why in Motivation / Problem rather than moving Motivation above Summary.

Write PR descriptions for a user or downstream maintainer who is not already familiar with the implementation. Lead Summary and Motivation with what changes for them, what stays compatible, how they opt in or migrate, and why the evidence matters; keep implementation mechanics in Changes unless they explain user-visible risk.

When a PR has meaningful user-facing API, workflow, behavior, or performance impact, add a concise Before / After section. Cover only relevant dimensions, phrase rows as user-visible before/after outcomes, and for performance claims name the baseline explicitly: CPU path, parent commit, main, or prior implementation, plus workload, metric, and important limitations.

Use plain descriptive commit messages and PR titles. Do not prefix them with agent tags such as [codex], [claude], or [opencode].

For already-published PRs, keep history inspectable with additive commits. If the PR branch needs the latest target branch, use explicit maintainer/user approval to update that published branch by merging the target branch and pushing normally. Do not rebase published PR branches by default because that invalidates existing CI runs and makes PR review/comment history harder to follow. Rebase or force-push only when the maintainer explicitly requests it.

Milestones (Required)

Always set a milestone when creating PRs after explicit maintainer/user approval:

# After explicit maintainer/user approval, set milestone on existing PR
gh pr edit <PR#> --milestone "DART 7.0"

# List available milestones
gh api repos/dartsim/dart/milestones --jq '.[] | .title'

CRITICAL: Bug Fix Dual-PR

Bug fixes require PRs to BOTH release lines:

1. Active DART 6 LTS release-6.* branch - Current DART 6 maintenance line
2. main - Next release

Steps:

1. Fix on the active DART 6 LTS branch first
2. Cherry-pick to main
3. After explicit maintainer/user approval, create separate PRs for each

CHANGELOG (After Approved PR Exists)

Use the dart-changelog routine with docs/onboarding/changelog.md as the source of truth. After the approved PR exists, check if CHANGELOG.md needs updating:

Format: - Reader-visible outcome. ([#PR](https://github.com/dartsim/dart/pull/PR))

Keep entries concise. If details need more than a few wrapped lines, move the details to the owner doc, plan, or migration note and link that document. Do not add one bullet per PR when several PRs ship one reader-visible outcome; merge them into one human-readable release-note entry.

# Example entry in CHANGELOG.md under appropriate section:
- Added AI-native documentation with AGENTS.md and module-specific guides. ([#2446](https://github.com/dartsim/dart/pull/2446))

Code Review

• Address all feedback
• Keep changes minimal
• Update tests if behavior changed
• Run full validation, then ask for explicit maintainer/user approval before pushing fixes

CI Loop

gh run watch <RUN_ID> --interval 30

Fix failures until green.

DART Model Loading (dart::io)

Load this skill when working with robot model files or parsers.

When correctness depends on the loaded model's 3D hierarchy, transforms, collision geometry, or simulated behavior, also load dart-verify-sim for a text scene/behavior oracle plus claim-tied visual corroboration.

Quick Start

#include <dart/io/read.hpp>

// Format auto-detection
auto skel = dart::io::readSkeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf");

Full Documentation

For complete I/O guide: docs/onboarding/io-parsing.md

For module-specific details: dart/io/AGENTS.md

Supported Formats

Common Patterns

// URDF with package resolution
dart::io::ReadOptions options;
options.addPackageDirectory("my_robot", "/path/to/my_robot");
auto skel = dart::io::readSkeleton("package://my_robot/urdf/robot.urdf", options);

// Force specific format
options.format = dart::io::ModelFormat::Sdf;

Key Files

• API: dart/io/read.hpp
• Tests: tests/unit/io/test_read.cpp

DART Python Bindings (dartpy)

Load this skill when working with Python bindings or dartpy.

When a binding exposes or changes model/scene loading, dynamics, collision/contact/constraints, simulation stepping, GUI/rendering output, or a visual example, also load dart-verify-sim. Pair a focused Python text/behavior oracle with an assessed, claim-tied headless capture; document a visual exception when rendering is unavailable or not applicable.

Quick Start

import dartpy as dart

world = dart.World()
skel = dart.io.read_skeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf")
world.add_skeleton(skel)

for _ in range(100):
    world.step()

Full Documentation

For complete Python bindings guide: docs/onboarding/python-bindings.md

For module-specific details: python/AGENTS.md

Quick Commands

pixi run build-py-dev    # Build for development
pixi run test-py         # Run Python tests
pixi run generate-stubs  # Generate type stubs

Wheel Building

pixi run -e py314-wheel wheel-build
pixi run -e py314-wheel wheel-repair  # Linux only
pixi run -e py314-wheel wheel-test

Key Patterns

• snake_case preferred (camelCase emits DeprecationWarning)
• NumPy arrays auto-convert to Eigen types
• GUI requires DART_BUILD_GUI=ON

Key Files

• Package config: pyproject.toml
• Build system: python/dartpy/CMakeLists.txt
• Type stubs: python/stubs/dartpy/

DART Research References

Load this skill when adding, updating, auditing, or citing research references (papers, textbooks, model-format standards, or comparative engines) for the DART experimental simulation world — its public API and its algorithms.

Catalog Location

docs/readthedocs/papers.md is the single source of truth and the published website page. It is a companion to the experimental API design docs:

• docs/design/simulation_cpp_api.md
• docs/design/simulation_python_api.md

Entry Schema

Each entry has an id, a full citation, and these properties:

Status is written from the experimental world's perspective. A method shipping in classic DART but not yet in the experimental world is planned, with the classic location noted in Notes.

Workflow: add or update an entry

1. Ground the entry in real evidence — a design doc, code path, test, or an explicit project decision. Do not add aspirational references with no link.
2. Write an accurate citation (authors, title, year, venue/publisher). Prefer an official URL; do not fabricate DOIs.
3. Add a row to the matching summary table and a detail subsection with the full properties and a one-line rationale.
4. Set Status from the experimental world's perspective; note classic-DART status separately in Notes.
5. Set Verdict (adopt to build on, baseline to compare against, reference to cite, evaluate while undecided, reject with a reason).
6. Fill Where used with the design-doc/code/test link.
7. When the relationship changes (e.g. a planned algorithm becomes implemented, or an evaluate is decided), update Status/Verdict and the Where used link in the same change.

Rules

• Prefer robotics/dynamics literature (textbooks, papers) over engine-specific names when a reference informs a terminology decision; record the grounding in the catalog's "Terminology Grounding" section.
• Keep the catalog scoped to the experimental world for now; the schema is general and can extend to the rest of DART later.
• Keep engine entries as baselines/comparisons, never as dependencies.
• Use docs/ai/verification.md to select the docs-only or AI docs/adapters gate set, then run pixi run lint after edits.

Full Documentation

For the catalog and its rationale: docs/readthedocs/papers.md

For the API it supports: docs/design/simulation_cpp_api.md, docs/design/simulation_python_api.md

For DART's research focus: docs/ai/north-star.md

DART Testing

Load this skill when writing or debugging tests.

Quick Commands

pixi run test         # Quick test run
pixi run test-all     # Full validation
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run test-unit    # Unit tests
pixi run test-py      # Python tests

Full Documentation

For complete testing guide: docs/onboarding/testing.md

For CI/CD troubleshooting: docs/onboarding/ci-cd.md

Test Organization

• Unit tests: tests/unit/
• Integration tests: tests/integration/
• Regression tests: Near the code they test

Writing Tests

1. Follow existing patterns in the test directory
2. Use GoogleTest framework
3. Name tests descriptively: TEST(ClassName, MethodName_Condition_ExpectedResult)

CI Validation

Before submitting PR:

pixi run lint         # Must pass
pixi run test-all     # Must pass
pixi run -e cuda test-all # Must pass on Linux CUDA hosts

Debugging Test Failures

# Run the smallest existing Pixi test task that covers the failure
pixi run test-unit

# Get CI logs
gh run view <RUN_ID> --log-failed

Simulation And Visual End-to-End Checks

When a failure or change depends on scene structure, dynamics, collision/contact, simulation stepping, GUI output, or a visual example, also load dart-verify-sim. Use its text-first oracle and then an assessed headless capture with claim-relevant debug layers. Record a concrete no-visual reason only when that corroboration is unavailable or not applicable.

Gotchas

• pixi run build builds libraries only, NOT the unit-test binaries. If you run ctest without building the test target first, you may execute stale binaries that silently pass. Build the test target before running its label, e.g. for the simulation suite: pixi run build-simulation-tests (target dart_simulation_tests) before ctest -L simulation.
• pixi run test-all is the default-environment full gate. On Linux hosts with a visible NVIDIA CUDA runtime, also run pixi run -e cuda test-all; the CUDA run preserves the cuda Pixi environment and executes the CUDA CTest + benchmark smoke path when the runtime is detected.
• The CUDA Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES; unsupported PTX/toolchain errors usually mean the generated CUDA architecture flags need to be checked before blaming test code.

DART Simulation Verification

Load this skill when verifying that a DART 3D scene or physics simulation is correct — implementing, debugging, benchmarking, or reviewing dynamics, collision, contact, or GUI output. DART's domains need 3D understanding that language models lack natively; this tooling makes it checkable without a GUI.

Lead with text, corroborate with images. Measured A/B evidence: per-step metrics and trajectories detect nearly all seeded physics defects; a rendered image alone misses static geometry defects (penetration, interpenetration). Decide correctness from text; use images for scene comprehension and gross dynamic failures.

Applicability contract

Use this skill for any task whose claim depends on 3D structure or behavior: model/scene loading, dynamics, collision/contact/constraints, simulation stepping, GUI/rendering, or visual examples. First run a text oracle (metrics, scene diff, trajectory/contact comparison, or focused behavioral test), then corroborate it end to end with an assessed headless view and only the debug layers needed by the claim. If rendering is unavailable or genuinely irrelevant, record why and name the replacement evidence; never treat an image as the sole correctness oracle.

Full documentation

docs/onboarding/agent-sim-verification.md — the durable guide. docs/ai/verification.md owns the gate policy; docs/onboarding/profiling.md owns text-first profiling.

Quick commands

Text (primary):

• world.compute_step_metrics() — energy/momentum/penetration/contacts/residual
• dartpy.dump_scene_json(world) / dump_scene_text(world) — "what is in this world?" (glTF/USD-flavored hierarchy + flat index)
• pixi run scene-diff — structural JSON verdict for intended-vs-actual scene dumps
• pixi run trajectory-record / pixi run trajectory-compare — per-body TSV + contact JSONL; bit-exact or tolerance diff with first-divergence

Visual (corroboration):

• dart.gui.render(world, camera=None, size=(w, h), debug=(...layers...)) → headless image with optional world-derived debug layers (grid, world_frame, body_frames, coms, inertia_boxes, collision_bounds, velocities, contacts, labels; trajectories additionally requires a sampled dart.gui.TrajectoryTracker via debug_scene_for_world); dart.gui.render_annotated(...) composites label text; .png_bytes() for notebooks; dart.gui.orbit_camera(...) / look_at(...)
• dart.gui.assess_view(world, camera, size, focus=...) → ViewReport with issues (cropped/too-far/too-close/occluded/ambiguous); dart.gui.select_viewpoints(...) picks deterministic best views; dart.gui.frame_body/frame_region reframe onto a subject. Assess first; fix flagged views before capturing evidence.
• viewer camera flags: --view {three-quarter|front|side|top}, --camera-azimuth/-elevation/-distance/-target, --turntable N, --fit
• pixi run py-demo-capture — headless PNG/MP4 capture from Python
• pixi run agent-capture — deterministic evidence harness: auto/explicit cameras, debug layers, stills/turntable/motion video, reproducible sidecar
• pixi run image-compose — side-by-side / blend / diff-heatmap composites
• pixi run evidence-select — claim-driven artifact selection with recorded rationale; pixi run evidence-publish — PR "Visual verification" section with GitHub-hosted media (manual placeholders by default; gh-release upload only with --yes + maintainer approval)
• pixi run image-verdict / image-golden / image-sheet — JSON verdict, golden diff, contact sheet (contrast is report-only; --require-contrast to gate)
• pixi run image-ab-study — blind-judge detection deltas for single-view, multi-view, turntable, and annotated captures
• pixi run image-ab-round2 — prepare a blinded round-2 packet and score completed judge observations

Opt-in:

• pixi run render-golden-gate — opt-in golden gate (backend-specific golden, curated locally with -- --update; not default CI)
• pixi run rerun-trajectory — rerun.io inspection (opt-in; graceful when rerun-sdk is absent)
• pixi run verification-bundle — package text evidence plus still/grid images for a provider-neutral VLM or reviewer call

Default capture for agent review: one ~1280 px frame, UI hidden, 3/4 view; add a 9-frame grid for motion. Keep images as corroboration, never the sole oracle for static geometry.

DART 6 (release-6.20)

Equivalent capture over OpenSceneGraph: dart::gui::osg::setUpOffscreenViewer / captureOffscreen + dartpy bindings, pixi run capture (needs a real X server or Xvfb), the ported image tooling, and pixi run bm-boxes-headless for rendering-free determinism checksums.

dart-analyze

Use this skill in Codex to run the DART dart-analyze workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-analyze <arguments>
• Codex: $dart-analyze <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Analyze repository evidence without editing: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/workflows.md @docs/ai/verification.md @docs/onboarding/ai-tools.md

Workflow

1. Restate the question and the read-only boundary. Do not edit files, stage changes, or perform GitHub, CI, branch, or review-thread mutations.
2. Inspect local state enough to avoid misreading user work:

   git status --short --branch
   git diff --stat
   

3. Build an evidence set from repository files, tests, docs, generated artifacts, and command output. Load task-specific docs from AGENTS.md when the question names a subsystem.
4. Separate direct evidence from inference and unknowns. Do not present an inference as a fact, and do not turn a read-only answer into an implementation plan.
5. Rank explanations, risks, or options by confidence when multiple readings are plausible. Use concrete file and line references for material claims.
6. If current external documentation or standards are needed for correctness, gather source-backed evidence and label date/version context explicitly.
7. Stop when the synthesis answers the question with enough evidence, or report the exact proof source that is unavailable.

Output

Report:

• the question answered and the scope inspected;
• ranked synthesis with confidence;
• evidence, inference, and unknowns as separate sections;
• any discriminating read-only probe that would reduce remaining uncertainty;
• confirmation that no local edits or external mutations were performed.

DART 7 Architecture

Load this skill when working on the DART 7 simulation World, on solvers/physics domains/compute backends, or whenever a task needs the big-picture map of how DART 7 is generalized for multi-physics, multi-solver, and multi-backend simulation.

The design in one sentence

The World owns topology, time, and a configured set of solvers; each solver advances the dynamics of the entities in its physics domain, and couplers mediate interactions between domains — with parallelizable work expressed as compute-graph nodes that any backend executor runs. Users configure method families and policies, never solver registries, component storage, or execution backends.

Why three axes of choice

• Research, apples-to-apples. A new paper's algorithm should be reproducible and benchmarkable inside DART against baselines on shared foundations, not in a fork. New methods enter through DART-owned solver families.
• End-user choice. Users pick the solver method and (internally) backend that fit their accuracy/speed/platform needs.
• Auto-configuration. Defaults are selected from scene content so the easy path stays trivial; the backend seam is designed for later platform/scene-scale awareness without changing the public API.

Design vs current state (read both)

docs/readthedocs/architecture.md is the single-page map of the design and the options at each seam, with honest status markers. docs/design/dart7_architecture_assessment.md is the verified record of where the implementation still diverges from that design (no internal solver contract yet, conceptual-only Model/State split, executor seam unused by dynamics stages, missing apples-to-apples substrate) and owns the standing rule: new solver families enter only through docs/plans/solver-family-intake.md, including contract conformance and machine-recorded solver identity in all benchmark evidence. PLAN-091 retired the first living hardening packet plan; current follow-up work routes through docs/plans/dashboard.md, the intake checklist, and the durable owner docs named in the assessment. Do not write new code that copies a pattern the assessment still lists as a verified finding.

Key owner documents

The architecture page's Source-of-truth map is the single owner of the full topic → owner-doc mapping (solver, API, extension, compute, differentiable, clean-break, north-star). The docs an agent most often needs inline:

Public-facade rules (do not violate)

• Do not expose Solver, Coupler, PhysicsDomain, ECS storage, component types, executor/backend types, or solver registries as public API.
• Select behavior by documented method-family names and policy value objects.
• Backend names (CUDA, Taskflow, SIMD ISA) may appear in build flags, diagnostics, and benchmarks — never in public types, namespaces, or required configuration.
• Keep the easy path (World + addRigidBody/addMultibody + step) free of solver vocabulary.
• Fallbacks must never silently substitute algorithms: validate capabilities at finalize or record the substitution in diagnostics.

Verification

Use docs/ai/verification.md to select the docs-only or code gate set for the change. Implementation work that realizes parts of this architecture also follows the gates in docs/design/simulation_solver_architecture.md, the solver-family intake checklist, and any active owner plan named in docs/plans/dashboard.md.

dart-audit-agent-compliance

Use this skill in Codex to run the DART dart-audit-agent-compliance workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-audit-agent-compliance <arguments>
• Codex: $dart-audit-agent-compliance <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Audit agent compliance issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/verification.md @docs/ai/components.md @docs/onboarding/ai-tools.md @docs/onboarding/contributing.md

Incident Inputs

• Rule violated: $1
• Where documented: $2
• Actual behavior: $3
• Expected behavior: $4

Treat missing positional values as details to infer from the user request or ask about before editing.

Workflow

1. Locate the exact existing rule and confirm it is still correct.
2. Diagnose why it was missed:
   • buried in prose
   • wrong file for the task type
   • weak emphasis
   • duplicated or conflicting guidance
   • not referenced from relevant commands or skills
3. Prefer restructuring existing docs over adding duplicate content.
4. Improve visibility with one or more focused changes:
   • move the rule to a loaded file
   • make it scannable with a checklist or mandatory marker
   • consolidate duplicate guidance
   • add cross-references from relevant commands or skills
5. Run the principle audit from docs/ai/principles.md and use docs/ai/verification.md to map audit results to evidence.
6. Run the relevant gate set from docs/ai/verification.md. For AI workflow changes, that includes generated adapter sync/checks, docs policy, spell, Markdown checks, and pixi run lint.

Output

• Root cause for the missed rule
• Files changed and why
• Which audit items were proven by automation vs manual inspection
• Confidence level that the recurrence risk is reduced

dart-backport-pr

Use this skill in Codex to run the DART dart-backport-pr workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-backport-pr <arguments>
• Codex: $dart-backport-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Backport PR or commits: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/release-management.md @docs/onboarding/changelog.md

Workflow

1. Verify the source PR or commit is merged to main:

   gh pr view <SOURCE_PR> --json state,mergedAt,baseRefName,mergeCommit
   

2. Check whether an equivalent change already exists on the release branch:

   git fetch origin <RELEASE_BRANCH> main
   git cherry -v --abbrev=40 origin/<RELEASE_BRANCH> origin/main | grep <COMMIT_HASH>
   

3. For AI-infra or workflow-doc backports, compare the release branch capability inventory and adapter directories against main. If the release branch has a smaller workflow surface, adapt to the release branch instead of importing main-only workflows.
4. Create a release branch from the release target:

   git checkout -B backport/<SOURCE_PR>-to-<RELEASE_BRANCH> origin/<RELEASE_BRANCH>
   

5. Cherry-pick with provenance: git cherry-pick -x <COMMIT_HASH>.
6. Resolve conflicts minimally; stop and ask if conflicts are broad or change behavior.
7. Run the dart-changelog routine for the release-target decision before opening the backport PR.
8. Run pixi run lint and the smallest relevant release-branch checks.
9. Ask for explicit maintainer/user approval before pushing or opening the PR. After approval, open the PR against the release branch with milestone matching that release branch and use the PR template.

Output

• Backport PR URL
• Source PR/commit
• Conflicts resolved, if any
• Changelog decision
• Checks run and CI status

dart-benchmark-packet

Use this skill in Codex to run the DART dart-benchmark-packet workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-benchmark-packet <arguments>
• Codex: $dart-benchmark-packet <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Author or refresh a benchmark evidence packet: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/profiling.md

Also read the owning plan file named by the packet (for example docs/plans/<NNN>-<slug>.md) and its packet convention.

Workflow

1. Identify the owning plan and its packet convention: the packet checker (for example pixi run check-avbd-packets) and the packet generator (for example scripts/write_*_packet.py) that the plan names.
2. Build the benchmark target and run the benchmark that feeds the packet, following docs/onboarding/profiling.md for a stable measurement setup.
3. Run the packet writer to record the machine-generated evidence packet with its provenance and resolved configuration.
4. Validate the packet with the plan's packet checker; treat a failing checker as incomplete evidence and fix the packet, not the checker.
5. Prepare the owning plan's row or link update that task-specific gates require, but leave editing the plan file to the plan's own workflow — this command prepares and validates the packet. This is a local task; do not push or open PRs without explicit maintainer/user approval.

Output

• Owning plan, packet ID, and the checker/generator used
• Benchmark command run and the measurement setup
• Packet file written and checker result
• Whether the packet is new or refreshed, and any remaining gap

dart-branch-cleanup

Use this skill in Codex to run the DART dart-branch-cleanup workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-branch-cleanup <arguments>
• Codex: $dart-branch-cleanup <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Analyze or clean branches: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md

Modes

• analyze: inspect only, no deletions
• action: prepare follow-up, or delete only after ownership/safety are clear and the maintainer/user gives explicit approval for each local or remote branch deletion

Default to analyze if the requested mode is ambiguous.

Workflow

1. git fetch --all --no-prune
2. List stale remote-tracking refs without deleting them:

   git remote prune origin --dry-run
   

   If origin uses SSH and port 22 is unavailable, keep the check read-only and use a temporary HTTPS rewrite instead of changing repository config:

   git -c url.https://github.com/.insteadOf=git@github.com: \
     fetch --all --no-prune
   git -c url.https://github.com/.insteadOf=git@github.com: \
     remote prune origin --dry-run
   

   To confirm that a remote PR branch was deleted without updating refs, query GitHub directly over HTTPS:

   git ls-remote --heads https://github.com/dartsim/dart.git <BRANCH>
   

3. Determine target branch, usually origin/main.
4. For each branch:

   git rev-list --left-right --count <TARGET>...<BRANCH>
   git log --oneline <TARGET>..<BRANCH>
   git diff --stat <TARGET>..<BRANCH>
   git cherry -v <TARGET> <BRANCH>
   

5. Before any explicitly approved local branch deletion, check whether the branch is checked out by a linked worktree:

   git worktree list --porcelain
   git -C <WORKTREE> status --short --branch
   

   Dirty linked worktrees must not be removed, detached, or reset during branch cleanup. Only after explicit maintainer/user approval, switch that worktree to a preservation branch at the same commit to free the obsolete branch name before deleting the merged branch.
6. The command git branch --merged may not prove ancestry for PR branches that landed through a squash or merge commit. Use the merged PR state plus an empty tree diff or equivalent git cherry -v output as the deletion signal; if the history relationship is unclear, keep the branch.
7. Classify recommendations only; deleting a candidate requires explicit maintainer/user approval:
   • ahead=0: safe deletion candidate
   • equivalent commits already landed: deletion candidate
   • no-PR branch whose fix may already be solved differently on the target: confirm supersession with a focused A/B or content check before deciding; superseded is a deletion candidate, otherwise keep or open a follow-up
   • small, current, useful diff: keep or rebase into PR
   • large or unclear diff: document follow-up before action
8. Ask for explicit maintainer/user approval before pruning refs or deleting any local or remote branch, even when ownership, branch purpose, and remote impact look clear.

Output

• Branch summary with ahead/behind count and last commit date
• Useful commits or risks
• Recommendation: delete, keep, rebase, or needs follow-up
• Actions taken after explicit maintainer/user approval, if action mode was explicitly requested

DART Build System

Load this skill when working with DART's build system.

Quick Commands

pixi run configure    # Configure CMake
pixi run build        # Build
pixi run test         # Run tests
pixi run test-all     # Full validation (lint + build + tests)
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run lint         # Format code

Full Documentation

For complete build instructions, read: docs/onboarding/building.md

For build system internals (CMake, dependencies): docs/onboarding/build-system.md

Common Issues

CUDA Notes

• On Linux hosts with visible NVIDIA GPUs, the CUDA Pixi config auto-detects compute capabilities for DART_CUDA_ARCHITECTURES; set DART_CUDA_ARCHITECTURES=<arch> only when overriding that detected list.
• If CUDA runtime tests fail with unsupported PTX/toolchain errors, verify the generated CUDA flags include the local GPU architecture before assuming a kernel bug.

Pixi Lockfiles

• Do not edit pixi.lock by hand. Change dependency constraints in pixi.toml, then run a Pixi command such as pixi install to let Pixi regenerate the lockfile.
• If pixi.lock changes format or has broad solver churn, keep the generated output and call it out in the PR rather than attempting to splice lockfile entries manually.

Filament GUI Visual Checks

• For Filament GUI rendering changes, run a bounded headless capture through pixi run ex dartsim --headless --frames ... --width ... --height ... --screenshot .... Prefer at least 1280px width when judging visual quality.
• Inspect the rendered image yourself; do not rely only on command success. The headless smoke analyzer under the private Filament test helpers is useful for a smoke signal, but it is not a substitute for visual inspection.
• If the user explicitly asks for pixi run ex dartsim, also run that exact entry point and terminate it after confirming the GUI binary launches.

Key Files

• pixi.toml - Package management
• CMakeLists.txt - Build configuration
• cmake/ - CMake modules

dart-changelog

Use this skill in Codex to run the DART dart-changelog workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-changelog <arguments>
• Codex: $dart-changelog <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Maintain DART changelog entries: $ARGUMENTS

Purpose

dart-changelog is the reusable changelog decision and writing routine. It is usually invoked by other DART workflows when they reach a changelog decision, not directly by users.

Use it to decide whether CHANGELOG.md needs an entry, draft an entry at the right level of detail, add a PR link after publication, or audit a release section for missing or over-detailed entries. Keep style, placement, evidence, and release-note density aligned with docs/onboarding/changelog.md.

Required Reading

@AGENTS.md @docs/onboarding/changelog.md @docs/onboarding/release-roadmap.md @docs/onboarding/release-management.md

Modes

Interpret $ARGUMENTS as one of these modes when present:

• decide: determine whether the current change needs a changelog entry and record the reason for the PR checklist/body when no entry is needed.
• draft: write or revise the entry before a PR number exists.
• finalize: add the PR link or adjust the entry after a PR exists, keeping the follow-up local until explicit maintainer/user approval permits a push.
• audit: scan a release section or PR set for missing, duplicate, over-detailed, misplaced, or stale entries.
• release-audit: alias for audit when the caller is finalizing a release section through dart-release-packaging.

If no mode is given, infer the smallest mode that satisfies the caller's need.

Output Contract

Every run must leave the caller with a concise, pasteable decision note. Use this shape in the response, PR body draft, or handoff text:

Changelog decision:

- Mode: decide | draft | finalize | audit | release-audit
- Base evidence: <base ref or PR/release inspected>
- Scope evidence: <diff, PR, issue, or release section inspected>
- Decision: entry required | no entry required | entry deferred | audit only
- Target section: <release/category, or N/A>
- Entry text: <final or draft bullet, or N/A>
- PR-body note: <exact no-entry reason or follow-up, or N/A>
- Follow-up: <PR link, maintainer approval, release audit, or none>

For no entry required, the PR-body note must name the evidence-backed reason rather than just saying "not needed." For entry deferred, say exactly what is missing, usually the PR number or release target. For finalize, confirm the entry still matches nearby CHANGELOG.md style after adding the PR link.

Workflow

1. Inspect the change and target:

   git status --short --branch
   git diff --stat
   git diff --cached --stat
   BASE_REF="$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || true)"
   # If the caller or arguments name a release branch before PR creation, set
   # BASE_REF to that branch before falling back to automatic inference.
   if [ -z "$BASE_REF" ]; then
     CURRENT_BRANCH="$(git branch --show-current)"
     UPSTREAM_REF="$(git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || true)"
     for REF in "$CURRENT_BRANCH" "${UPSTREAM_REF#origin/}"; do
       case "$REF" in
         main|release-*) BASE_REF="$REF"; break ;;
       esac
     done
   fi
   BASE_REF="${BASE_REF:-main}"
   git fetch origin "$BASE_REF"
   git diff --stat "origin/$BASE_REF...HEAD"
   gh pr diff --name-only 2>/dev/null || true
   gh pr list --head "$(git branch --show-current)"
   

   Use the base comparison or PR diff even when the worktree is clean. If a PR, issue, release, or target branch is named, inspect that live object before writing and prefer its base over the main fallback.
2. Read docs/onboarding/changelog.md and the relevant CHANGELOG.md release section. Compare nearby bullets before drafting so wording, section choice, and level of detail match the current file.
3. Decide whether an entry is required using the guide:
   • user-visible API, behavior, packaging, CI, docs workflow, AI-infra, simulation correctness, release, or migration impact usually needs an entry;
   • typo-only, formatting-only, generated-only, and tiny internal refactors usually do not.
4. Record the decision with the Output Contract before modifying CHANGELOG.md or telling a caller to skip it. The decision must cite the diff, PR, issue, release section, or target branch that was inspected.
5. When writing, start with the reader-visible outcome, not the implementation chore. Use one concise bullet, combine closely related changes, avoid author credits, and avoid one-bullet-per-PR diary style.
6. Place the entry under the target branch's release section and nearest existing category. Do not create a new category for one PR unless the release shape genuinely needs it.
7. Add the best evidence link:
   • if a PR number exists, use ([#1234](https://github.com/dartsim/dart/pull/1234));
   • if no PR number exists yet, draft without the link and leave the follow-up local until explicit approval permits another push or PR update.
8. For release audits, consolidate noisy implementation ledgers, confirm breaking/removal/deprecation bullets name a migration or support lane, and preserve human-readable release notes over exhaustive history.
9. Validate with the gate appropriate to the caller. For changelog-only edits, run the docs-only checks from docs/ai/verification.md; before any commit, run pixi run lint.

Caller Contract

Other workflows should call this routine whenever they touch behavior or docs that may need release notes. The caller keeps ownership of the overall task, validation, PR body, and approval boundary; dart-changelog owns the changelog decision, wording, placement, evidence-link hygiene, and the pasteable decision note that lets Claude, Codex, OpenCode, and manual contributors record the same outcome.

Output

Report:

• the changelog decision note in the Output Contract shape above;
• the drafted or finalized entry text and its CHANGELOG.md placement;
• gates run (pixi run lint, docs-only checks) and their results;
• any follow-up left local pending explicit maintainer/user approval.

DART CI/CD Troubleshooting

Load this skill when debugging CI failures or working with GitHub Actions.

Quick Commands

# Monitor PR checks
gh pr checks <PR_NUMBER>
gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast

# View run details
gh run list --branch <BRANCH> -e pull_request -L 20
gh run watch <RUN_ID> --interval 30
gh run view <RUN_ID> --json status,conclusion,url

# Debug failures
gh run view <RUN_ID> --job <JOB_ID> --log-failed
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'

# Rerun failed jobs only after explicit maintainer/user approval
gh run rerun <RUN_ID> --failed
gh run rerun <RUN_ID> --job <DATABASE_ID>

Full Documentation

For complete CI/CD guide: docs/onboarding/ci-cd.md

Common Failure Modes

Workflow Architecture

CUDA Runner Policy

The project has a trusted ubuntu-latest-gpu runner for same-repository CUDA runtime validation, but it must never run untrusted fork-PR code. Consequences:

• Same-repository PRs, protected branch pushes, and manual dispatches use the GPU runner and run pixi run --locked -e cuda test-cuda.
• Fork PRs use a GitHub-hosted fallback and compile CUDA targets without running GPU-only steps.
• Local CUDA validation is pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime; local Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES.
• pixi run check-phase5-cuda-workflow enforces the trusted-event GPU guard and fork-PR hosted fallback in ci_cuda.yml.

Fast Iteration Loop

1. Identify failing step from job logs
2. Reproduce locally with same build toggles
3. Fix the smallest failing test
4. Push only after explicit maintainer/user approval, then monitor: gh run watch <RUN_ID>

Caching

• sccache/ccache reduces build time 50-70%
• Check cache hit rates in workflow logs
• Force cache bust by changing cache key if needed

Expected CI Times

dart-close-issue

Use this skill in Codex to run the DART dart-close-issue workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-close-issue <arguments>
• Codex: $dart-close-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Close or prepare closing message for issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md

Workflow

1. Inspect the issue: gh issue view <ISSUE_NUMBER> --comments.
2. Verify the stated resolution:
   • fixed by merged PR
   • already fixed on main
   • no longer reproducible
   • out of scope or needs a different tracker
3. Draft a concise closing message:
   • thank the reporter
   • state the concrete resolution
   • link the fixing PR or relevant docs when available
4. Only post and close if the user explicitly requested action and explicit maintainer/user approval has been given:

   gh issue comment <ISSUE_NUMBER> --body "<message>"
   gh issue close <ISSUE_NUMBER>
   

Output

• Closing message
• Whether it was posted
• Whether the issue was closed

DART Contribution Workflow

Load this skill when contributing code to DART.

Full Documentation

For complete guide: docs/onboarding/contributing.md

For code style: docs/onboarding/code-style.md

Branch Naming

• feature/<topic> - New features
• fix/<topic> - Bug fixes
• refactor/<topic> - Refactoring
• docs/<topic> - Documentation

PR Workflow

# Features, docs, and non-bugfix refactors start from main
git checkout -b <type>/<topic> origin/main

# Bug fixes that apply to the current release line start from the active DART 6 LTS branch
DART6_LTS_BRANCH=$(git branch -r --list 'origin/release-6.*' | sed 's|.*/||' | sort -V | tail -1)
git checkout -b "fix/<topic>-${DART6_LTS_BRANCH#release-}" "origin/$DART6_LTS_BRANCH"

# Make changes, then
pixi run lint
pixi run test-all
# On Linux hosts with a visible NVIDIA CUDA runtime
pixi run -e cuda test-all

# After explicit maintainer/user approval, push and create PR
git push -u origin HEAD
gh pr create --draft --base <target-branch> --milestone "<milestone>"

Use --base main --milestone "DART 7.0" for main PRs and the branch-matching DART 6.x patch milestone for active DART 6 LTS PRs.

Rule of thumb: run pixi run lint before committing so auto-fixes are included.

Use .github/PULL_REQUEST_TEMPLATE.md and keep DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first as the reviewer skim target. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then put the fuller why in Motivation / Problem rather than moving Motivation above Summary.

Write PR descriptions for a user or downstream maintainer who is not already familiar with the implementation. Lead Summary and Motivation with what changes for them, what stays compatible, how they opt in or migrate, and why the evidence matters; keep implementation mechanics in Changes unless they explain user-visible risk.

When a PR has meaningful user-facing API, workflow, behavior, or performance impact, add a concise Before / After section. Cover only relevant dimensions, phrase rows as user-visible before/after outcomes, and for performance claims name the baseline explicitly: CPU path, parent commit, main, or prior implementation, plus workload, metric, and important limitations.

Use plain descriptive commit messages and PR titles. Do not prefix them with agent tags such as [codex], [claude], or [opencode].

For already-published PRs, keep history inspectable with additive commits. If the PR branch needs the latest target branch, use explicit maintainer/user approval to update that published branch by merging the target branch and pushing normally. Do not rebase published PR branches by default because that invalidates existing CI runs and makes PR review/comment history harder to follow. Rebase or force-push only when the maintainer explicitly requests it.

Milestones (Required)

Always set a milestone when creating PRs after explicit maintainer/user approval:

# After explicit maintainer/user approval, set milestone on existing PR
gh pr edit <PR#> --milestone "DART 7.0"

# List available milestones
gh api repos/dartsim/dart/milestones --jq '.[] | .title'

CRITICAL: Bug Fix Dual-PR

Bug fixes require PRs to BOTH release lines:

1. Active DART 6 LTS release-6.* branch - Current DART 6 maintenance line
2. main - Next release

Steps:

1. Fix on the active DART 6 LTS branch first
2. Cherry-pick to main
3. After explicit maintainer/user approval, create separate PRs for each

CHANGELOG (After Approved PR Exists)

Use the dart-changelog routine with docs/onboarding/changelog.md as the source of truth. After the approved PR exists, check if CHANGELOG.md needs updating:

Format: - Reader-visible outcome. ([#PR](https://github.com/dartsim/dart/pull/PR))

Keep entries concise. If details need more than a few wrapped lines, move the details to the owner doc, plan, or migration note and link that document. Do not add one bullet per PR when several PRs ship one reader-visible outcome; merge them into one human-readable release-note entry.

# Example entry in CHANGELOG.md under appropriate section:
- Added AI-native documentation with AGENTS.md and module-specific guides. ([#2446](https://github.com/dartsim/dart/pull/2446))

Code Review

• Address all feedback
• Keep changes minimal
• Update tests if behavior changed
• Run full validation, then ask for explicit maintainer/user approval before pushing fixes

CI Loop

gh run watch <RUN_ID> --interval 30

Fix failures until green.

dart-deps

Use this skill in Codex to run the DART dart-deps workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-deps <arguments>
• Codex: $dart-deps <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Triage and shepherd dependency and bot PRs: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md

Scope

Handle automated dependency and maintenance PRs: Dependabot GitHub Action version bumps and the scheduled lockfile PRs opened by update_lockfiles.yml. Default to read-only triage; merging any bot PR is an explicit approval gate.

Workflow

1. List open bot PRs:

   gh pr list --repo dartsim/dart --state open \
     --search "author:app/dependabot OR author:app/github-actions" \
     --json number,title,headRefName,author
   

2. For each PR, review the diff (gh pr diff <PR_NUMBER>):
   • Action bumps: confirm the new ref is a pinned commit SHA and sanity-check the upstream changelog for the bumped version.
   • Lockfile PRs: confirm the regenerated lockfile provenance matches the workflow that produced it and that no unrelated content changed.
3. Confirm CI is green for the PR head: gh pr checks <PR_NUMBER>.
4. Merge a reviewed, CI-green bot PR only after explicit maintainer/user approval, using the current head SHA and the repository merge method.
5. Batch-report every triaged PR with its recommendation and status.

Output

• Table of open bot PRs with kind (action bump or lockfile), CI state, and recommendation
• Diff-review notes per PR
• Which PRs were merged after explicit approval and which remain pending

dart-docs-update

Use this skill in Codex to run the DART dart-docs-update workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-docs-update <arguments>
• Codex: $dart-docs-update <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Update documentation: $ARGUMENTS

Required Reading

@AGENTS.md @docs/README.md @docs/AGENTS.md @docs/information-architecture.md @docs/ai/principles.md @docs/ai/verification.md @docs/onboarding/ai-tools.md @docs/onboarding/changelog.md

Workflow

1. Create a branch from the target branch: git checkout -b docs/<topic> origin/main
2. Edit docs and AI workflow sources only:
   • Regular docs: docs/**, README.md, AGENTS.md, CONTRIBUTING.md, and CHANGELOG.md when dart-changelog requires a release-note entry
   • AI source files: .claude/commands/**, .claude/skills/**
3. For AI workflow changes, run pixi run sync-ai-commands; do not hand-edit generated .opencode/ or .codex/ files
4. Classify new or moved docs by lifecycle first, then audience, then topic, using docs/information-architecture.md. For AI docs, keep always-loaded entrypoints compact: improve owner placement or pointers instead of duplicating procedures.
5. Update indexes and cross-references that point to changed docs
6. Use docs/ai/verification.md to select the docs-only or AI docs/adapters gate set, then run pixi run lint before committing
7. Invoke the dart-changelog routine for the CHANGELOG.md decision and any required entry.
8. Ask for explicit maintainer/user approval before pushing or opening the PR. After approval, use .github/PULL_REQUEST_TEMPLATE.md and the proper milestone.

Output

• Docs and AI workflow sources changed
• Sync and verification commands run
• Changelog decision
• PR readiness, noting any external mutation that was explicitly approved

dart-downstream-fix

Use this skill in Codex to run the DART dart-downstream-fix workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-downstream-fix <arguments>
• Codex: $dart-downstream-fix <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix downstream-reported DART issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md

When To Use

Use for downstream issues in gz-physics, Gazebo, or gz-sim that trace back to DART behavior: crashes, assertions, NaN/Inf propagation, missing validation, or DART performance regressions.

Workflow

1. Read the downstream issue, logs, stack traces, and reproduction steps.
2. Identify the DART API, component, and invalid usage pattern involved.
3. Search for related validation and recovery patterns in DART.
4. Plan the smallest fix and the regression test location.
5. Decide whether the bug applies to the active release line. For applicable bug fixes, implement on the active DART 6 LTS branch first, then cherry-pick or reapply to main for DART 7:
   • branch: fix/<downstream-project>-<issue-number>-<brief-description>-6-lts
   • add a regression test that reproduces the downstream symptom
   • keep the fix minimal; no unrelated refactors
6. Run pixi run lint and relevant tests; use pixi run test-all when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime.
7. Ask for explicit maintainer/user approval before pushing or creating PRs. After approval, create the release-branch PR with the branch-matching DART 6.x patch milestone and reference the downstream issue.
8. Create the matching main PR with milestone DART 7.0; adapt API differences if needed.

Release-Line Differences

• DART 7 commonly uses DART_WARN() and <dart/All.hpp>.
• DART 6 LTS may use dtwarn << ..., <dart/dart.hpp>, and older test CMake patterns.

Output

• Root cause and fix summary
• Main PR URL and release PR URL, if applicable
• Tests run and CI status
• Link back to the downstream issue

dart-execute-packet

Use this skill in Codex to run the DART dart-execute-packet workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-execute-packet <arguments>
• Codex: $dart-execute-packet <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Execute a work packet in DART: $ARGUMENTS

Required Reading

Read these files first: @AGENTS.md @docs/ai/orchestration.md @docs/ai/principles.md @docs/ai/verification.md @docs/plans/dashboard.md

Inputs

$ARGUMENTS is optional and takes one of three forms:

• WP-<plan>.<n> (for example WP-091.13) — execute exactly that packet.
• PLAN-NNN (for example PLAN-091) — select the first available packet in that plan.
• empty — auto-select: walk docs/plans/dashboard.md top to bottom (document order is priority); for each Active entry whose owner doc is a numbered plan file containing #### WP- packet headings, take the first available packet by the availability rules below. State which packet was selected and why before starting.

If nothing resolves to an available packet, report what was checked (plans walked, packets skipped and the blocking signal for each) and stop; do not invent work.

Availability and conflict check

Run the full check from docs/ai/orchestration.md before claiming. A packet is available only when ALL of these hold:

1. Dependencies — its Dependencies line is satisfied in full: every named packet is marked [done — ...], and every non-packet precondition (for example "maintainer direction on ..." or an accepted design note) has recorded evidence in the plan or the named owner doc. Treat any precondition you cannot verify as unmet and skip the packet.
2. Local markers — its heading carries neither [done — ...] nor [claimed] in the local plan file.
3. Remote markers — git fetch origin (a read-only sync), then check the plan file as it exists on the default branch (git show origin/main:docs/plans/<plan-file>.md) for a marker the local checkout does not have yet.
4. Branch/PR signals — no one else is already working it: git ls-remote --heads origin shows no branch embedding the packet ID in the documented form (wp-<plan>-<n>-<slug>, for example wp-091-13-contact-assembly), and gh pr list --state open --search "WP-<plan>.<n>" returns no open PR carrying the ID in its title. These are read-only queries that mutate nothing; any push, PR creation, or other GitHub mutation still requires explicit maintainer/user approval.

If any signal says the packet is taken: in auto/plan mode skip to the next available packet; for an explicit packet ID, report the conflicting signal and stop.

Readiness check

Before claiming, inspect the packet text and named owner docs for the specification intake required by docs/ai/orchestration.md:

• objective;
• value or rationale;
• scope;
• non-goals;
• assumptions and open decisions;
• acceptance evidence;
• gates; and
• dependencies.

If objective, scope, non-goals, acceptance evidence, gates, or dependencies are missing or too vague to verify, report that the packet is not executable and stop. For older packets that lack an explicit value or assumptions field, proceed only when the owner docs make the value and assumptions unambiguous, and state those inferred fields before editing. If an unresolved decision would materially change public API, release compatibility, numerical correctness, benchmark claims, or roadmap scope, stop and ask the orchestrator to record an owner-local Decision needed block.

Workflow

1. Locate the packet — open the owning numbered plan file linked from docs/plans/dashboard.md and read the packet's objective, scope, value/rationale, assumptions/open decisions, non-goals, acceptance evidence, gates, and dependencies.
2. Claim — append [claimed] to the packet heading in the plan file and create the topic branch named wp-<plan>-<n>-<slug>. The branch name is the cross-machine claim signal once pushed; pushing it (like any GitHub mutation) requires explicit maintainer/user approval, so until then the marker and branch are local and the strongest remote signal stays the merged plan file.
3. Load packet context — read the owner docs the plan names for that workstream plus the files in the packet's scope. Do not load the whole plan corpus; the packet defines the working set.
4. Implement exactly the packet — stay inside scope and non-goals. If the real scope differs materially from the packet's stated scope, stop and report back with what was found; do not widen the packet. One packet, one branch, one verification story.
5. Verify — run the packet's gates plus pixi run lint before any commit. Record each piece of acceptance evidence named by the packet (test names, command output, doc updates). Missing evidence means the packet is not complete — say so explicitly.
6. Hand back — append an Evidence: bullet to the packet in the plan file listing the recorded evidence (or update the dev-task RESUME.md for multi-session packets), leave the [claimed] marker for the orchestrator to replace with [done — ...] on acceptance, then report completion with the evidence list for orchestrator review. Local commits are part of execution; pushes and PR creation require explicit maintainer/user approval first, and the PR title starts with the packet ID (WP-<plan>.<n>: ...) so the claim is searchable.

Rules

• The packet's owner docs win over the packet text on any conflict; report the conflict rather than improvising.
• Do not chain into adjacent packets, refactor outside scope, or "fix while here" — file findings back to the orchestrator instead.
• Never remove another session's [claimed] marker or reuse its branch; stale-claim release is the orchestrator's call (see docs/ai/orchestration.md).
• Behavior-preserving packets must prove preservation (golden trajectories or the tests the packet names), not assert it.
• Solver-family work additionally honors the intake checklist in docs/plans/solver-family-intake.md.
• The author of a packet's implementation does not approve it; acceptance is the orchestrator's or an independent reviewer's call.

Output

• Selected packet ID and owning plan
• Scope implemented and acceptance evidence recorded
• Gates run and their results
• Hand-back state (the [claimed] marker left for the orchestrator) and any blocker
• Any external mutation that was explicitly approved

dart-fix-ci

Use this skill in Codex to run the DART dart-fix-ci workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-fix-ci <arguments>
• Codex: $dart-fix-ci <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix CI failure: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/ci-cd.md @docs/onboarding/release-management.md

Workflow

1. Identify the base branch. Default to main; use base=<branch> from $ARGUMENTS or the PR's own base when it is a release-* branch. For a release-* base, also read docs/onboarding/release-management.md and apply the release caveats called out below.
2. Identify failing checks: gh pr checks <PR_NUMBER> or gh run view <RUN_ID>.
3. Inspect the first real failure:

   gh run view <RUN_ID> --log-failed
   gh run view <RUN_ID> --job <JOB_ID> --log
   

4. If a job is still in progress, wait for logs instead of guessing.
5. Choose where to fix. Check whether an equivalent fix already exists on main. If continuing an existing PR, fetch and check out that PR branch instead of creating a new one. For a release-* base, branch from the release branch and prefer cherry-picking the proven main fix; keep any new fix release-scoped and minimal:

   git fetch origin <RELEASE_BRANCH>
   git checkout -B fix/<issue>-<release-branch> origin/<RELEASE_BRANCH>
   

6. Reproduce locally with the smallest relevant command:
   • formatting: pixi run lint
   • tests: pixi run test, pixi run test-unit, or another existing focused pixi run ... test task
   • coverage: add targeted tests for uncovered changed lines
7. Fix the root cause with minimal scope. Explain why the failure was not caught earlier and whether workflow coverage should change.
8. If the failure is infrastructure-only, ask for explicit maintainer/user approval before rerunning the failed job or running:

   gh run rerun <RUN_ID> --failed
   

9. Ask for explicit maintainer/user approval before pushing, CI re-triggers, or other GitHub mutations; after approval, push and watch CI until green. For a release-* base, use the current release milestone and the PR template when creating or updating the release-branch PR.

Output

• Root cause
• Fix or rerun action
• Commands run
• PR URL, when a PR was created or updated
• Current CI status
• Prevention recommendation, if any

dart-fix-issue

Use this skill in Codex to run the DART dart-fix-issue workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-fix-issue <arguments>
• Codex: $dart-fix-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Fix GitHub issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Workflow

1. gh issue view $1 - Validate issue
2. Classify whether the issue is a bug fix that applies to the active DART 6 LTS branch. For applicable bug fixes, start from the highest maintained origin/release-6.* branch; otherwise start from origin/main.
3. Fix with minimal changes + add regression test. For dual-PR bug fixes, fix the active DART 6 LTS branch first, then cherry-pick or reapply to main.
4. pixi run lint, then run the smallest relevant tests; use pixi run test-all before finalizing when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime
5. Before PR creation, invoke the dart-changelog routine to decide whether CHANGELOG.md needs an entry, then fill .github/PULL_REQUEST_TEMPLATE.md.
6. After explicit maintainer/user approval, git push -u origin HEAD && gh pr create --base <target-branch> --milestone "<milestone>"
7. Before PR: If task used docs/dev_tasks/<task>/, remove the folder (include in this PR, not after merge)

CRITICAL: Dual-PR for Bug Fixes

PRs to BOTH the active DART 6 LTS branch AND main. See docs/onboarding/contributing.md.

Output

• Issue number and classification (bug fix, dual-PR, or main-only)
• Fix summary and regression test added
• Gates run (lint, focused tests, pixi run test-all)
• PR readiness for each target branch, noting any explicitly approved mutation

DART Model Loading (dart::io)

Load this skill when working with robot model files or parsers.

Quick Start

#include <dart/io/Read.hpp>

// Format auto-detection
auto skel = dart::io::readSkeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf");

Full Documentation

For complete I/O guide: docs/onboarding/io-parsing.md

For module-specific details: dart/io/AGENTS.md

Supported Formats

Common Patterns

// URDF with package resolution
dart::io::ReadOptions options;
options.addPackageDirectory("my_robot", "/path/to/my_robot");
auto skel = dart::io::readSkeleton("package://my_robot/urdf/robot.urdf", options);

// Force specific format
options.format = dart::io::ModelFormat::Sdf;

Key Files

• API: dart/io/Read.hpp
• Tests: tests/unit/io/test_Read.cpp

dart-manage-pr

Use this skill in Codex to run the DART dart-manage-pr workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-manage-pr <arguments>
• Codex: $dart-manage-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Manage an open DART pull request after explicit maintainer/user approval for mutations: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md @docs/onboarding/testing.md @docs/onboarding/ai-tools.md

Modes

• mode=manage (default): run the full PR-management loop below to the next terminal state.
• mode=merge: maintainer-only. Complete the local pre-merge validation in step 6 and merge a ready PR only after explicit maintainer/user approval for the merge.

Invocation Contract

When the user says manage <PR> or continue managing <PR> without limiting the request to status-only, treat that as approval to run the full PR-management loop to the next terminal state:

• required policy metadata checked and corrected when stale;
• CI monitored until green, failed, or blocked;
• merge conflicts reproduced and resolved locally;
• review comments addressed, pushed, resolved, and re-reviewed when appropriate;
• PR body/testing evidence refreshed when it no longer matches the branch.

This explicit approval covers routine PR-maintenance mutations for that loop: additive fix commits and pushes, PR description/metadata corrections, resolving already-addressed review threads, rerunning failed CI jobs, and requesting a fresh AI review after follow-up fixes. It does not cover merging the PR into the target branch, force-pushes, branch deletion, PR closure, base-branch changes, or human reviewer requests; ask separately for those.

Do not call the PR managed just because checks are green. Continue until the PR is mergeable with required checks complete and addressed review threads resolved, or until a concrete blocker remains.

Identify the PR

Use the PR number or URL from $ARGUMENTS. If none is provided, infer the PR from the current branch:

gh pr view --json number,url,headRefName,baseRefName

Then inspect the full state:

gh pr view <PR_NUMBER> --json number,title,state,isDraft,baseRefName,headRefName,mergeStateStatus,milestone,url,reviewDecision,statusCheckRollup
gh pr checks <PR_NUMBER>

Workflow

1. Confirm scope and policy:
   • Check that the base branch, title, and PR template are correct.
   • Verify the milestone is set before merge: DART 7.0 for a main base, the branch-matching DART 6.x patch milestone for a release-* base. If it is missing, set it only after explicit maintainer/user approval.
   • For bug fixes, verify the required DART 6 LTS + main dual-PR flow.
   • Confirm the PR body's testing/status section matches the current head and does not point reviewers to deleted dev-task evidence as still pending.
   • Confirm the PR body follows template order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first as the skimmable outcome; fold leading problem context into Summary and keep the fuller why in Motivation.
   • When the PR has user-facing API, workflow, behavior, or performance impact, confirm a concise Before / After section compares old and new surfaces; for performance claims make the baseline explicit (CPU path, parent commit, main, or prior implementation) plus workload, metric, and limitations.
   • Ensure transient visual evidence (screenshots, headless renders, GIFs, videos) is hosted as GitHub PR/issue attachments rather than committed to the branch; if committed only for the PR body, replace it with an attachment URL or ask a maintainer to upload.
   • Inspect local state before editing:

     git status --short --branch
     git diff --stat
     git diff --check
     

2. Monitor CI:

   gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast
   

   If checks are still queued or running, report the current jobs and keep watching unless the user asked only for status. Also poll mergeability:

   gh pr view <PR_NUMBER> --json mergeStateStatus,headRefOid,isDraft,reviewDecision
   

   If GitHub reports conflicts, fetch the target branch and resolve them before treating green checks as sufficient.
3. Fix failures:
   • Inspect the newest failed run or job, not an older cancelled run. Use the dart-fix-ci workflow for non-trivial CI debugging.
   • Reproduce locally with the relevant pixi run ... task or focused test.
   • Before committing fixes, run pixi run lint; also build or test when code or behavior changed. Commit only intended files.
   • Prefer additive follow-up commits for published PRs. Amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).
   • Merge the latest base branch into the PR branch before any push, and follow the base-merge, automated-review, and bot no-reply rules in docs/onboarding/ai-tools.md; each push, PR comment, review re-trigger, or thread resolution needs explicit maintainer/user approval.
4. Address reviews:
   • Use the dart-review-pr workflow for substantive review feedback and the automated-review handling in docs/onboarding/ai-tools.md (no inline bot replies; verify claims locally; apply AI-review fixes silently).
   • For human reviewers, reply only when a response is useful after a fix or when a question needs clarification.
   • After an approved push that addressed Codex comments on a PR that already had a Codex review, post a fresh top-level @codex review; that PR comment needs explicit maintainer/user approval and must not duplicate an active trigger.
   • For substantive code PRs, an independent review session (a human, or a separate agent session running /dart-review-pr) must record findings before merge approval; docs-only and mechanical changes are exempt.
5. Mark ready or merge only when appropriate:
   • Confirm review requirements are satisfied and local validation matches the intended transition.
   • If the PR is draft, mark it ready after explicit approval once Codex is clean and local validation passed on the current head: default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime. Hosted CI may still be pending.
   • Use the current head SHA when merging so a moved branch cannot be merged accidentally. Prefer squash/rebase over merge commits per repository settings; recent DART main PRs use single-parent PR-title commits.
6. mode=merge gate (maintainer-only): before any merge, run local pre-merge validation on the current head after the latest pushed change: pixi run test-all and, on Linux hosts with a visible NVIDIA CUDA runtime, pixi run -e cuda test-all; do not substitute the default run for the CUDA run, and record a skip or blocker explicitly. Merge only after CI and review are green, the milestone is set, an independent review recorded findings, the PR is not draft, GitHub reports it mergeable, and explicit merge approval is given. PR comments, review re-triggers, thread resolution, reviewer requests, ready-for-review transitions, merges, and branch deletion are external mutations that require explicit maintainer/user approval.
7. Clean up after merge:
   • Confirm the PR merged and identify the head branch before deleting.
   • After explicit maintainer/user approval, prefer merge-time deletion with the approved merge method and head SHA:

     gh pr merge <PR_NUMBER> --squash --match-head-commit <HEAD_SHA> --delete-branch
     

     Use --rebase or --merge instead of --squash when requested.
   • After explicit maintainer/user approval, otherwise delete only the PR branch after confirming it has landed:

     git push origin --delete <HEAD_BRANCH>
     git switch main
     git pull --ff-only
     git branch -D <HEAD_BRANCH>
     

     Squash and rebase merges do not preserve the branch tip in main ancestry, so force-delete locally only after confirming the PR branch landed and only after explicit maintainer/user approval.

Output

Report:

• PR number, URL, base, head, draft state, milestone, and merge status.
• CI summary: passing, failing, pending, or skipped checks.
• Review summary, independent-review status, and whether @codex review ran.
• Local pre-merge validation state when mode=merge ran.
• Commits pushed, merge action, and branch cleanup action.
• Remaining blockers or next action.

dart-mechanical-refactor

Use this skill in Codex to run the DART dart-mechanical-refactor workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-mechanical-refactor <arguments>
• Codex: $dart-mechanical-refactor <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Perform mechanical refactor: $ARGUMENTS

Required Reading

@AGENTS.md @CONTRIBUTING.md @docs/onboarding/code-style.md

Workflow

1. Define the exact transformation and scope before editing.
2. Create a branch from the target branch, usually origin/main.
3. Prefer scriptable or automated edits when the transformation is repetitive.
4. Keep behavior unchanged; do not mix in feature work or cleanup outside scope.
5. If reorganizing files, update CMake, pixi tasks, generated indexes, and docs.
6. Run focused checks first, then broader checks according to risk:
   • pixi run lint
   • pixi run build
   • pixi run test-unit
   • pixi run test-all when feasible
   • pixi run -e cuda test-all when feasible on Linux CUDA hosts
7. Ask for explicit maintainer/user approval before pushing or opening a PR. After approval, open a PR with a clear scope statement and no behavior-change claim unless tested.

Output

• Transformation summary
• Files or areas changed
• Verification run
• Any residual risk

dart-new-task

Use this skill in Codex to run the DART dart-new-task workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-new-task <arguments>
• Codex: $dart-new-task <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Start a new task in DART: $ARGUMENTS

Required Reading

Read these files first: @AGENTS.md @docs/onboarding/building.md @docs/onboarding/contributing.md @docs/onboarding/code-style.md @docs/dev_tasks/README.md @docs/information-architecture.md @docs/ai/sessions.md @docs/ai/principles.md @docs/ai/verification.md

Workflow

1. Understand the task - Parse: goal, constraints, type (feature|bugfix|refactor|docs)
2. Assess scope - Multi-phase or multi-session? Create docs/dev_tasks/<task>/ (see docs/dev_tasks/README.md for criteria). Team-scale work (multiple parallel lanes needing orchestrated worker agents) switches to dart-ultrawork instead. For multi-session, design-heavy, public API, solver/paper, release, or cross-module work, fill the dev-task specification intake before editing: value, scope, assumptions, traceability, non-goals, acceptance evidence, gates, and open decisions. If consequential ambiguity would change public API, release compatibility, numerical correctness, benchmark claims, or roadmap scope, record an owner-local Decision needed block instead of silently choosing.
3. Setup - Choose the target branch before creating a topic branch:
   • features/docs/non-bugfix refactors: branch from origin/main
   • bug fixes that apply to the current release line: branch from the active DART 6 LTS origin/release-6.* branch first, then cherry-pick or reapply to main
4. Implement - Keep commits focused, follow code style
5. Verify - Run pixi run lint before committing, then pixi run test-all; on Linux hosts with a visible NVIDIA CUDA runtime, also run pixi run -e cuda test-all
6. PR - After explicit maintainer/user approval, git push -u origin HEAD then gh pr create --draft --base <target-branch> --milestone "<milestone>" (DART 7.0 for main, branch-matching DART 6.x patch milestone for the active DART 6 LTS branch); follow .github/PULL_REQUEST_TEMPLATE.md
7. Cleanup - Before PR: if task used docs/dev_tasks/<task>/, first promote durable dashboards, evidence matrices, API inventories, migration maps, or long-lived decisions into the durable owner selected by docs/information-architecture.md. Then remove the dev-task folder completely (include the deletion in this PR, not after merge).

Type-Specific

• Bugfix: Requires PRs to BOTH the active DART 6 LTS branch AND main
• Refactor: No behavior changes
• Feature: Add tests + docs
• New solver/paper implementation: Before any implementation starts, record the full solver-family intake checklist in docs/plans/solver-family-intake.md — including its solver-contract conformance and solver-identity/metrics items; the standing rule in docs/design/dart7_architecture_assessment.md applies, and new families must not bypass the PLAN-091 contracts. Derive an evidence matrix from the paper, project page, reference source, videos, and demos. Do not call the task complete until DART implements all algorithms/features on required CPU and GPU backends, ports all experiments/demos into tests/benchmarks/py-demos, records benchmark JSON proving DART beats reference and paper numbers for every claimed case (with the resolved solver configuration machine-recorded in every packet), and performs any clean API/pipeline refactor needed for the long-term DART 7/8 architecture. For multi-session work, keep the active docs/dev_tasks/<task>/README.md and RESUME.md explicit about the latest completed slice, the next missing paper-parity gap, and why focused green tests are not a full solver/paper completion claim.

Output

• Task type, scope, and whether a docs/dev_tasks/<task>/ folder was created
• Files changed and gates run
• Dev-task promotion and cleanup status when the task completed
• PR readiness, noting any external mutation that was explicitly approved

dart-next

Use this skill in Codex to run the DART dart-next workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-next <arguments>
• Codex: $dart-next <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Select and execute the next bounded DART task: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/ai/workflows.md @docs/ai/verification.md @docs/plans/README.md @docs/plans/dashboard.md @docs/plans/north-star-roadmap.md @docs/dev_tasks/README.md @docs/onboarding/contributing.md @docs/onboarding/ci-cd.md @docs/onboarding/ai-tools.md

Arguments

Interpret $ARGUMENTS as optional constraints:

• mode=select: choose one task and stop with evidence.
• mode=execute: choose one task, make local changes, and verify locally. This is the default when the user asks to do the work.
• mode=pr: execute locally and prepare PR text, then ask for explicit maintainer/user approval before any GitHub, PR, CI, branch, or review-thread mutation, including pushes, PR creation, PR comments, reviewer requests, review re-triggers, thread resolution, ready-for-review transitions, merges, CI reruns, or branch deletion.
• size=tiny|small|medium|large or days=N: fit the chosen task to the requested scope. Default to small, meaning one focused local session.
• focus=<topic>: prefer a focus area without making it the only allowed candidate. Examples: ai-native, easy-start, algorithm, compute, release, ci, docs, python, io, PLAN-020, world_split, dartpy, or a file path.
• area=<dimension>: alias for focus=<dimension>.
• Any issue, PR, branch, milestone, failing check, file path, or user-stated priority overrides the default dashboard order.

If constraints conflict or make the task unsafe to select, stop and ask one clarifying question.

Workflow

1. Inspect local state before choosing work:

   git status --short --branch
   git diff --stat
   

2. Build the candidate set from tracked evidence:
   • explicit user instruction in $ARGUMENTS;
   • current branch, local diff, or active docs/dev_tasks/<task>/ state;
   • docs/plans/dashboard.md, in priority order, especially Horizon: Now;
   • docs/ai/north-star.md gaps and readiness criteria;
   • issue, PR, or CI state named by the user or inferable from the branch.
3. Exclude candidates that are blocked, larger than the requested size, missing enough evidence to start, likely to require unapproved GitHub mutations, or only bootstrap/maintain the dart-next workflow itself unless explicitly focused.
4. Prefer the highest-value remaining candidate in this order:
   • user-specified issue, PR, failing check, or file path;
   • candidates matching focus=<topic> or area=<dimension>;
   • failing CI or review feedback on the current PR;
   • active dev task with a clear next local step;
   • first unblocked Horizon: Now dashboard item fitting the size;
   • issue triage or plan refinement when implementation evidence is missing.
5. State the selected task before editing:
   • candidate and source evidence;
   • rejected higher-priority candidates and why they were not selected;
   • whether the preferred focus matched the selected task, and why if it did not;
   • size assumption and expected stopping point;
   • workflow to follow next;
   • verification gate from docs/ai/verification.md.

Execution Routing

After selection, follow the most specific DART workflow:

If the selected task is multi-session or needs design tracking, create or update docs/dev_tasks/<task>/ according to docs/dev_tasks/README.md.

Local Work Cycle

1. Load task-specific docs from AGENTS.md and the routed workflow.
2. Make the smallest coherent local change that satisfies the selected task.
3. Run the strongest relevant local gate:
   • docs/AI work: gates from docs/ai/verification.md;
   • C++ or Python behavior: pixi run lint, build, and focused tests;
   • CI work: local reproduction when possible plus the fixed check.
4. Review the local diff before declaring completion:

   git diff --stat
   git diff --check
   

5. Optimize or benchmark only when the selected objective is performance sensitive or the plan gate explicitly requires performance evidence.
6. Update durable docs when the task changes project state, public workflow, or roadmap evidence.
7. Run the completion audit from docs/ai/verification.md before finalizing.

PR And Review Management

Use $dart-pr or /dart-pr only after local verification is complete and the user requested PR preparation. Ask for explicit maintainer/user approval before any GitHub, PR, CI, branch, or review-thread mutation, including push, PR creation, PR comment, reviewer request, review re-trigger, review-thread resolution, ready-for-review transition, CI rerun, merge, or branch deletion.

After a PR exists and explicit approval covers PR management, use $dart-manage-pr or /dart-manage-pr for CI, review, and cleanup. For the first Codex review on a draft PR, prefer a top-level @codex review after explicit approval for PR comments; it can run while the PR remains draft. Once Codex is clean and local validation passes on the current head (default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime), the draft is ready to mark ready for human review after approval, while merge still waits for required hosted checks.

Output

Report:

• selected task, size, evidence, and routed workflow;
• files changed and verification commands run;
• completion-audit result and any remaining blocker;
• PR readiness status, without performing external mutations unless explicit approval was given.

dart-plan-update

Use this skill in Codex to run the DART dart-plan-update workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-plan-update <arguments>
• Codex: $dart-plan-update <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Discuss or update DART living plans: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/plans/README.md @docs/plans/dashboard.md @docs/plans/north-star-roadmap.md @docs/ai/verification.md

Workflow

1. Classify the request:
   • discussion-only: compare options, priority, scope, or sequencing;
   • plan edit: revise docs/plans/** or related indexes;
   • task derivation: turn a plan item into a bounded implementation or docs task.
2. Inspect current evidence before changing plan state. Use repo docs, code, tests, CI evidence, issue/PR state, benchmark data, or explicit maintainer direction.
   • For new solver/paper implementation plans, preserve the full paper-complete bar in docs/ai/verification.md: all algorithms/features, CPU and GPU paths, paper/site/video demos, benchmark JSON that beats reference and paper numbers, and clean long-term API/pipeline work.
   • For active multi-session solver/paper work, update the plan or dev-task resume surface with both the completed slice and the next missing paper-parity gap; do not let focused tests narrow the recorded objective. If the user names source demos, videos, or project pages, keep the corpus matrix explicit: which scenes/experiments are represented by tests, py-demos, visual artifacts, benchmark JSON, CPU reference comparisons, and GPU parity, and which rows remain missing.
3. Keep the plan manageable:
   • revise an existing initiative before adding a duplicate;
   • use stable initiative IDs when renaming, splitting, consolidating, or parking work;
   • keep docs/plans/dashboard.md as the single source of truth for priority, status, horizon, dimension, next step, and gate.
   • when deriving packets or dev-task work, include the DART specification intake from docs/ai/orchestration.md: value, scope, non-goals, assumptions/open decisions, acceptance evidence, gates, and dependencies. Use owner-local Decision needed blocks for consequential ambiguity instead of silent defaults.
4. For discussion-only requests, present the tradeoff and proposed plan delta; do not edit unless the user asks for an edit or the request already implies one.
5. For plan edits, update docs/plans/dashboard.md for operating state, the detailed numbered initiative file or external owner document for rationale and workstreams, and docs/plans/north-star-roadmap.md only for strategic framing.
6. If the plan item becomes implementation work, route to /dart-new-task in Claude/OpenCode or $dart-new-task in Codex, and use docs/dev_tasks/README.md when it is multi-session or needs design tracking.
7. Verify with docs/ai/verification.md: use the docs-only gate for plan-only docs, and the AI docs/adapters gate set when AI docs, workflow sources, or generated adapters change.
8. Do not perform GitHub or remote mutations without explicit maintainer/user approval.

Output

• Request classification (discussion, plan edit, or task derivation)
• Plan files changed and the operating-state updates made
• Verification gate run
• Any routed follow-up task or Decision needed block recorded

dart-pr

Use this skill in Codex to run the DART dart-pr workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-pr <arguments>
• Codex: $dart-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Prepare or open a DART pull request after explicit maintainer/user approval: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ai-tools.md @docs/onboarding/changelog.md @.github/PULL_REQUEST_TEMPLATE.md

Recent PR Patterns

When the expected PR style is unclear, inspect recently merged PRs before drafting the title or body:

gh pr list --repo dartsim/dart --state merged --base main --limit 10 \
  --json number,title,body,mergedAt

Use these practices:

• Keep titles plain, scoped, and outcome-focused. Do not add agent prefixes.
• Fill the PR template in DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first because reviewers need the skimmable outcome before the rationale. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then keep the fuller why in Motivation / Problem rather than moving it above Summary.
• Write Summary and Motivation for a user or downstream maintainer unfamiliar with the implementation: lead with what changes for them, what stays compatible, how they opt in or migrate, and why the evidence matters. Keep implementation mechanics in Changes unless they explain a user-visible outcome or risk.
• When the change has user-facing API, workflow, behavior, or performance impact, add a concise ## Before / After section before Testing covering only relevant dimensions (public API, commands/workflows, behavior, migration, performance baseline). Phrase each row as a user-visible before/after, then name the mechanism as supporting context. For performance claims, name the baseline explicitly (CPU path, parent commit, main, or prior implementation) plus workload, metric, and limitations.
• In Testing, list exact commands, targets, or test names that ran. For CI, performance, or infrastructure work, include evidence such as CI observations, timing, reruns, benchmark output, or why a skipped check is expected.
• For rendering, model, mesh, texture, GUI, or visual-example changes, include a before/after visual comparison when practical:
  • Prefer an existing headless example path (--headless, --frames, --width, --height, --screenshot) over manual screenshots. Capture before and after with the same camera, dimensions, frame count, and renderer; restore the replaced sample/assets or use the base branch to capture the before image. Inspect the images yourself and include the commands and any software-rendering flags in the PR body.
  • Upload transient comparison images, GIFs, and videos through the GitHub PR/issue Markdown attachment flow so the body contains GitHub-hosted https://github.com/user-attachments/assets/... URLs. Do not commit transient visual evidence; commit visual files only when they are durable documentation, fixtures, or source assets.
  • The supported attachment flow is the web PR/issue editor; gh pr edit, gh pr comment, and the REST API do not provide a generic upload, and any command that edits or comments on a PR still requires explicit maintainer/user approval. If the current tool cannot upload attachments, keep the local artifact paths in the working note, ask a maintainer to upload them, then update the PR body with the returned URL after explicit maintainer/user approval. Do not fall back to committing evidence into docs/assets/.
  • If no headless path exists, add a narrowly scoped capture mode when it fits the example or document why visual comparison is not practical.
• Mark non-applicable checklist items as "N/A" with a short reason, and mention related PRs, issues, backports, and follow-ups explicitly, including "None".

Workflow

1. Inspect scope:

   git status --short --branch
   git diff --stat
   git diff --check
   

2. Exclude unrelated dirty files unless the user explicitly includes them.

3. Choose the target branch and milestone:

   Target	Milestone
   main	DART 7.0
   Active DART 6 LTS release-6.*	Branch-matching DART 6.x patch

4. For bug fixes, use the dual-PR flow: fix the active DART 6 LTS branch first, then cherry-pick or reapply to main.

5. Before every commit, run pixi run lint. Also run pixi run build for C++ or Python changes and focused tests for behavior changes.

6. Create or update a topic branch when needed:

   git checkout -b <type>/<topic> origin/<target-branch>
   

7. Commit only intended files with a plain descriptive commit title.

8. Merge the latest base branch into the PR branch before any push, and follow the base-merge and automated-review rules in docs/onboarding/ai-tools.md (no inline bot replies; @codex review re-triggers are throttled to one per approved review-fix round). Ask for explicit maintainer/user approval before pushing or opening the draft PR. After approval:

   git push -u origin HEAD
   gh pr create --draft --base <target-branch> --milestone "<milestone>" \
     --title "<plain title>" --body-file <filled-template-file>
   

9. Prefer additive follow-up commits for updates to a published PR. Amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).

10. Invoke the dart-changelog routine for the changelog decision, entry wording, and PR-link follow-up. If CHANGELOG.md needs the PR number, keep the follow-up changelog commit local until explicit maintainer/user approval is given for the additional push or PR update.

11. Monitor CI: gh pr checks <PR_NUMBER>.

Output

• Branch, target base, and milestone used
• Commit titles and files included
• PR URL and draft/ready state, or the prepared PR text awaiting approval
• Changelog decision
• CI status and any remaining blocker

DART Python Bindings (dartpy)

Load this skill when working with Python bindings or dartpy.

Quick Start

import dartpy as dart

world = dart.World()
skel = dart.io.read_skeleton("dart://sample/urdf/KR5/KR5 sixx R650.urdf")
world.add_skeleton(skel)

for _ in range(100):
    world.step()

Full Documentation

For complete Python bindings guide: docs/onboarding/python-bindings.md

For module-specific details: python/AGENTS.md

Quick Commands

pixi run build-py-dev    # Build for development
pixi run test-py         # Run Python tests
pixi run generate-stubs  # Generate type stubs

Wheel Building

pixi run -e py314-wheel wheel-build
pixi run -e py314-wheel wheel-repair  # Linux only
pixi run -e py314-wheel wheel-test

Key Patterns

• snake_case preferred (camelCase emits DeprecationWarning)
• NumPy arrays auto-convert to Eigen types
• GUI requires DART_BUILD_GUI=ON

Key Files

• Package config: pyproject.toml
• Build system: python/dartpy/CMakeLists.txt
• Type stubs: python/stubs/dartpy/

DART Research References

Load this skill when adding, updating, auditing, or citing research references (papers, textbooks, model-format standards, or comparative engines) for the DART experimental simulation world — its public API and its algorithms.

Catalog Location

docs/readthedocs/papers.md is the single source of truth and the published website page. It is a companion to the experimental API design docs:

• docs/design/simulation_cpp_api.md
• docs/design/simulation_python_api.md

Entry Schema

Each entry has an id, a full citation, and these properties:

Status is written from the experimental world's perspective. A method shipping in classic DART but not yet in the experimental world is planned, with the classic location noted in Notes.

Workflow: add or update an entry

1. Ground the entry in real evidence — a design doc, code path, test, or an explicit project decision. Do not add aspirational references with no link.
2. Write an accurate citation (authors, title, year, venue/publisher). Prefer an official URL; do not fabricate DOIs.
3. Add a row to the matching summary table and a detail subsection with the full properties and a one-line rationale.
4. Set Status from the experimental world's perspective; note classic-DART status separately in Notes.
5. Set Verdict (adopt to build on, baseline to compare against, reference to cite, evaluate while undecided, reject with a reason).
6. Fill Where used with the design-doc/code/test link.
7. When the relationship changes (e.g. a planned algorithm becomes implemented, or an evaluate is decided), update Status/Verdict and the Where used link in the same change.

Rules

• Prefer robotics/dynamics literature (textbooks, papers) over engine-specific names when a reference informs a terminology decision; record the grounding in the catalog's "Terminology Grounding" section.
• Keep the catalog scoped to the experimental world for now; the schema is general and can extend to the rest of DART later.
• Keep engine entries as baselines/comparisons, never as dependencies.
• Use docs/ai/verification.md to select the docs-only or AI docs/adapters gate set, then run pixi run lint after edits.

Full Documentation

For the catalog and its rationale: docs/readthedocs/papers.md

For the API it supports: docs/design/simulation_cpp_api.md, docs/design/simulation_python_api.md

For DART's research focus: docs/ai/north-star.md

dart-release-merge-main

Use this skill in Codex to run the DART dart-release-merge-main workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-release-merge-main <arguments>
• Codex: $dart-release-merge-main <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Merge release branch into main: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/release-management.md @docs/onboarding/ci-cd.md

Workflow

1. Auto-detect or confirm the active release branch and release version:

   git fetch origin
   git branch -r | grep -oE 'origin/release-[0-9]+\.[0-9]+' | sort -V | tail -1
   

2. Verify the clone is not shallow and a merge base exists.
3. Create merge/<release-branch>-into-main from origin/main.
4. Merge the release branch with a title like Merge release-6.19 into main (v6.19.x).
5. Resolve conflicts using docs/onboarding/release-management.md:
   • deleted in main, updated in release: keep deleted
   • added in both: prefer main unless release has unique needed content
   • content conflicts: prefer main modernization except for manually reviewed changelog entries
   • files only on release: keep if still relevant to main
6. Verify no unresolved conflicts remain.
7. Run pixi run lint and relevant checks.
8. Ask for explicit maintainer/user approval before pushing or creating the PR. After approval, create a PR targeting main with milestone DART 7.0 and use the PR template.
9. Monitor CI until green.

Output

• PR URL and CI status
• Release branch and release version
• Conflict counts and resolution summary
• Any manual changelog decisions

dart-release-packaging

Use this skill in Codex to run the DART dart-release-packaging workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-release-packaging <arguments>
• Codex: $dart-release-packaging <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Create release packaging PR after explicit maintainer/user approval: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/release-management.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Workflow

1. Confirm the new version, for example 6.16.6.
2. Derive the release branch: release-<major>.<minor>.
3. Fetch and branch from the release branch:

   git fetch origin <RELEASE_BRANCH>
   git checkout -B release/<NEW_VERSION>-version-bump origin/<RELEASE_BRANCH>
   

4. Bump versions in package.xml and pixi.toml.
5. Update version requirements in examples/tutorials if needed.
6. Invoke the dart-changelog routine in release-audit mode, then add or finalize the CHANGELOG.md release section with the release date, milestone link, release summary, and audit from docs/onboarding/changelog.md.
7. Run pixi run lint and relevant packaging checks.
8. Commit as Packaging <NEW_VERSION>.
9. Ask for explicit maintainer/user approval before pushing, creating the PR, or setting milestones.
10. After approval, create the PR against the release branch with the release milestone for that branch, for example the specific version milestone if available.

Output

• PR URL
• Version files changed
• Changelog section added
• Checks run

dart-resume

Use this skill in Codex to run the DART dart-resume workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-resume <arguments>
• Codex: $dart-resume <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Resume unfinished work: $ARGUMENTS

Objective

dart-resume is a completion-oriented task manager, not a status lookup or a single-slice helper by default. Resume the named or reconstructed work, build or refresh the execution plan, track progress in the repo-owned task surface, split independent work into verifiable packets, use subagents/sub-sessions only when the user explicitly requested delegation and the current AI surface permits it, verify every result, and keep going until the whole task is complete or a real blocker or approval boundary remains.

Decisions must be evidence-based. Before choosing between meaningful options, first improve or define the verification/debugging method so it can catch false positives and false negatives. Use repository inspection, focused tests, benchmarks, A/B comparisons, GUI or visual evidence, logs, and external resource searches as needed to decide from evidence instead of preference.

For a docs/dev_tasks/<task> target, full completion means all feasible task work is finished, durable decisions and deferred work are promoted, and the temporary dev-task folder is removed in the completing change. Do not stop after one successful slice unless the user explicitly requested a limited mode.

Argument Handling

Use $ARGUMENTS to identify the target, explicit scope limits, and execution modifiers. Interpret arguments in this order:

1. Explicit scope-limited mode: if arguments include status, audit-only, plan-only, slice, or next-slice, honor that limit and state it in the plan. Without one of these limiters, do not downscope the session to a single slice.
2. Execution modifiers: if arguments include no-subagents, run serially but keep the same whole-task completion objective. If arguments explicitly request subagents, parallel, delegation, or workers, use available AI-native delegation when the current surface permits it. Tool-use modifiers do not limit scope unless paired with an explicit scope-limited mode.
3. Explicit target path: if an argument names docs/dev_tasks/<task> or a file under that folder, treat that dev task as the target and read its README.md and RESUME.md after recon. Resolve relative paths from the repo root discovered by git rev-parse --show-toplevel, not from the launch directory.
4. Closeout wording: words such as complete, finish, retire, close out, or cleanup are accepted but not required for dev-task completion. Treat retire / close out as emphasis that the likely end state is durable-doc promotion plus folder removal.
5. Branch/PR/issue hint: otherwise, treat arguments as a branch, PR, issue, topic, or free-form resume hint and reconstruct the task from live repo state.

Examples:

$dart-resume docs/dev_tasks/dart7_core_dynamics_perf_forwardport
$dart-resume docs/dev_tasks/dart7_core_dynamics_perf_forwardport --slice
$dart-resume PR 2991

Required Reading

@AGENTS.md @docs/dev_tasks/README.md @docs/ai/sessions.md @docs/ai/verification.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Workflow

Recon (no changes)

git rev-parse --show-toplevel
git status -sb && git branch -vv && git log -10 --oneline --decorate
git diff --stat && git stash list
gh pr list --head "$(git branch --show-current)"
gh pr status

Reconstruct

If $ARGUMENTS names a docs/dev_tasks/<task> path, use that folder as the target and inspect its README.md, RESUME.md, and any directly referenced owner docs before choosing work. If the folder is already absent, verify whether it was retired on current main, identify the durable owner doc that replaced it, and report that no folder cleanup remains.

Otherwise infer the task from branch name, commits, diffs, issue/PR description, and any docs/dev_tasks/<task>/ state. If the goal is still unclear after recon, stop and ask.

Before editing, write explicit pass/fail criteria for the resumed task:

• what exact dev-task folder, branch, PR, issue, or topic is being completed;
• which remaining checklist items, decisions, or evidence must be resolved;
• how progress will be tracked during this session and across any handoff;
• which independent subtasks, if any, can be delegated when explicitly authorized or run as separate serial sessions without creating conflicting edits;
• which verification/debugging method will make false positives and false negatives unlikely before implementation decisions are made;
• which A/B tests, benchmarks, resource searches, GUI checks, or textual checks are needed to support consequential decisions;
• which durable docs will own any surviving decision or deferred work;
• whether the resumed change may need a changelog entry and how the dart-changelog decision will be recorded;
• which verification commands prove the result.

Continue

• Propose a 3-6 step plan before editing.
• Continue with minimal scope and preserve existing user changes.
• Verification comes first when the route is uncertain. Define the observable signal, build or select the smallest reproducer/check, run a control vs candidate comparison when possible, and only then choose the implementation path. If the existing verification is weak, improve the check or debugging surface before trusting the result.
• For text-based behavior, prefer concrete command output, failing/passing tests, focused scripts, logs, structured packets, assertions, and diffable artifacts. For GUI or visual behavior, capture screenshots, rendered assets, pixel/visual comparisons, smoke runs, or videos where the surface supports them; verify both the expected pass path and at least one failure-sensitive condition when practical.
• When the decision depends on behavior outside the repository, search the relevant upstream docs, papers, issues, standards, or release notes and record the source-backed conclusion in the task docs, durable owner doc, or PR evidence. Prefer primary sources.
• If the task is large, decompose it into independently verifiable work items. Use available AI-native subagent, sub-session, or parallel-worker support only when the user explicitly requested delegation and the current surface permits it. Otherwise, keep the decomposition as a serial plan or explicit handoff packets. Validate and integrate every delegated result yourself; repo-tracked docs remain the source of truth even when agent-specific orchestration is available.
• Keep progress tracking current in the task's README.md, RESUME.md, or durable owner doc after meaningful progress. If the current session cannot finish because of context, environment, approval, or a real blocker, leave the next session with exact current reality, remaining work, blockers, and gates.
• For active solver/paper implementations, keep the plan or dev-task resume surface explicit about the completed slice, the next missing paper-parity gap, and why focused green tests are not a full paper-completion claim.
• Run a completion audit before finalizing a dev-task target: identify the exact docs/dev_tasks/<task>/ folder, inspect it for remaining plans/evidence/decisions, promote any durable dashboard, evidence matrix, API inventory, migration map, long-lived decision, or deferred-but-real work into docs/plans/, docs/design/, or docs/onboarding/, update dashboard/plan progress when the task changes roadmap state, then remove the dev-task folder completely in the completing change.
• In completion mode, do not leave the long-form resume prompt to carry decisions. Record the final decision or parked follow-up in the durable owner doc, then delete or update the dev-task folder according to docs/dev_tasks/README.md.
• Before finalizing a resumed task that changes behavior, public API, packaging, CI, docs workflow, AI-infra workflow, release process, or user-visible docs, invoke the dart-changelog routine in decide or finalize mode. If no entry is needed, keep the reason in the local PR body/checklist draft or task evidence; if an entry is needed, prepare the local CHANGELOG.md edit and PR link when available. Pushing the changelog edit or updating the PR body still requires explicit maintainer/user approval.
• If remaining work is real but blocked by a substantial design decision, maintainer direction, external dependency, or scope boundary that should not be resolved in the current session, ask the human before retiring the folder unless prior maintainer direction is already recorded. Record the parked or blocked work in the durable owner doc before deletion.
• Do not call a dev task complete while docs/dev_tasks/<task>/ still exists. If implementation is done but the folder remains, the remaining work is the durable-doc promotion plus folder cleanup.
• Run pixi run lint before committing. Run relevant tests; use pixi run test-all before done when feasible, and also pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime.
• Merge the latest base branch into any published PR branch before pushing, and follow the base-merge rules in docs/onboarding/ai-tools.md. Push with git push -u origin HEAD and create or update the PR only after explicit maintainer/user approval, preferring additive follow-up commits.

Safety

No destructive git commands (reset --hard, dropping stashes, deleting branches) without explicit maintainer/user approval.

Output

• Reconstructed task and current branch/PR state
• Plan followed and files changed
• Verification commands run and their results
• Completion-audit result: dev-task promotion/cleanup done or the remaining blocker
• PR readiness, noting any external mutation that was explicitly approved

dart-retro

Use this skill in Codex to run the DART dart-retro workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-retro <arguments>
• Codex: $dart-retro <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Run a retrospective and capture durable lessons: $ARGUMENTS

Required Reading

@AGENTS.md @docs/AGENTS.md @docs/ai/principles.md @docs/ai/components.md @docs/ai/verification.md @docs/onboarding/ai-tools.md

Skip If

Stop without editing when all are true:

• no new patterns, gotchas, or failure modes were discovered
• no workflow improvement is needed
• the learning is too session-specific to help future agents or contributors
• existing docs already cover what happened
• the task was routine and left no durable insight

Routing

docs/ai/components.md owns routing for durable session learnings. Use this command as the hindsight workflow; do not duplicate the routing table here.

Workflow

1. Search existing docs before adding content.
2. Inventory the completed work before routing lessons. Consider domain/design choices, public API or package compatibility, CI/review failure modes, workflow friction, and cleanup or handoff steps separately so a late operational task does not hide feature-level learnings.
3. Decide whether each lesson is general enough for shared AI infra. Do not update AI components after every session.
4. Prefer update, remove, consolidate, or restructure over adding new files.
5. Make every durable learning discoverable from its owner surface: update an existing owner doc when possible, and when a new durable file is justified, link it from the relevant owner index or plan before retiring temporary context.
6. Keep docs/ai/principles.md compact; put procedures in the owner docs it links to.
7. Avoid ephemeral branch, PR, commit, or username details.
8. If adding a workflow command or skill, edit .claude/ source files and run pixi run sync-ai-commands.
9. Run pixi run lint before committing. For AI docs or adapter changes, also run the verification gates from docs/ai/verification.md: pixi run lint-md, pixi run check-lint-md, pixi run sync-ai-commands, pixi run check-ai-commands, pixi run check-docs-policy, and pixi run check-lint-spell.

Output

• What learning was captured
• Where it was documented
• Checks run

dart-retrospect

Use this skill in Codex to run the DART dart-retrospect workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a first-class Codex entrypoint.

Invocation

• Claude Code/OpenCode: /dart-retrospect <arguments>
• Codex: $dart-retrospect <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Retrospect on completed work and capture durable lessons: $ARGUMENTS

Required Reading

@AGENTS.md @docs/AGENTS.md @docs/ai/principles.md @docs/ai/components.md @docs/ai/verification.md @docs/onboarding/ai-tools.md

Skip If

Stop without editing when all are true:

• no new patterns, gotchas, or failure modes were discovered
• no workflow improvement is needed
• the learning is too session-specific to help future agents or contributors
• existing docs already cover what happened
• the task was routine and left no durable insight

Routing

docs/ai/components.md owns routing for durable session learnings. Use this command as the hindsight workflow; do not duplicate the routing table here.

Workflow

1. Search existing docs before adding content.
2. Inventory the completed work before routing lessons. Consider domain/design choices, public API or package compatibility, CI/review failure modes, workflow friction, and cleanup or handoff steps separately so a late operational task does not hide feature-level learnings.
3. Decide whether each lesson is general enough for shared AI infra. Do not update AI components after every session.
4. Prefer update, remove, consolidate, or restructure over adding new files.
5. Make every durable learning discoverable from its owner surface: update an existing owner doc when possible, and when a new durable file is justified, link it from the relevant owner index or plan before retiring temporary context.
6. Keep docs/ai/principles.md compact; put procedures in the owner docs it links to.
7. Avoid ephemeral branch, PR, commit, or username details.
8. If adding a workflow command or skill, edit .claude/ source files and run pixi run sync-ai-commands.
9. Run pixi run lint before committing. For AI docs or adapter changes, also run the verification gates from docs/ai/verification.md: pixi run lint-md, pixi run check-lint-md, pixi run sync-ai-commands, pixi run check-ai-commands, pixi run check-docs-policy, and pixi run check-lint-spell.

Output

• What learning was captured
• Where it was documented
• Checks run

dart-review-pr

Use this skill in Codex to run the DART dart-review-pr workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-review-pr <arguments>
• Codex: $dart-review-pr <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Review or respond to PR: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/code-style.md @docs/onboarding/ai-tools.md (for AI-generated review handling)

Workflow

Pick the sub-workflow from mode= in $ARGUMENTS, defaulting to review.

Review

gh pr view $1 && gh pr diff $1

Check code style, tests, docs, and focused commits. Record findings as read-only output; do not push, comment, resolve threads, or re-trigger review without explicit maintainer/user approval for that external mutation.

Address Feedback

gh pr view $1 --comments

Apply minimal fixes locally and verify. For published PRs, prefer a new follow-up commit so reviewers can inspect each round; amend or force-push only after explicit maintainer/user approval and only when the user requests it or a clear reason exists (removing sensitive content, repairing branch history).

1. Make the local fix silently (no reply), then run the relevant local gates, including pixi run lint before any commit.
2. Merge the latest base branch into the PR branch before any push, and follow the base-merge, automated-review, and bot no-reply rules in docs/onboarding/ai-tools.md. If the push is rejected because the remote head moved, fetch and compare it before retrying and validate an equivalent remote fix instead of pushing a duplicate.
3. Ask for explicit maintainer/user approval before any push, PR comment, thread resolution, or review re-trigger. After approval, push silently, resolve only reviewed and addressed thread IDs via GraphQL, and — when the approved push addressed Codex comments — re-trigger once with gh pr comment $1 --body "@codex review".
4. Apply the same no-inline-reply loop to github-code-quality[bot] findings; do not re-trigger Codex solely for non-Codex bot findings unless Codex comments were also addressed.
5. Monitor CI (gh pr checks $1) and repeat until no actionable comments remain. For draft PRs, mark ready after explicit approval once Codex is clean and local validation passes on the current head (default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime); merge still waits for required hosted checks.

Output

• PR number and whether the pass was a review or a feedback round
• Findings or fixes applied, with file/line references
• Which actions were local-only and which external mutations were explicitly approved
• Codex/CI state and any remaining blocker

DART Testing

Load this skill when writing or debugging tests.

Quick Commands

pixi run test         # Quick test run
pixi run test-all     # Full validation
pixi run -e cuda test-all # CUDA-enabled full validation on Linux CUDA hosts
pixi run test-unit    # Unit tests
pixi run test-py      # Python tests

Full Documentation

For complete testing guide: docs/onboarding/testing.md

For CI/CD troubleshooting: docs/onboarding/ci-cd.md

Test Organization

• Unit tests: tests/unit/
• Integration tests: tests/integration/
• Regression tests: Near the code they test

Writing Tests

1. Follow existing patterns in the test directory
2. Use GoogleTest framework
3. Name tests descriptively: TEST(ClassName, MethodName_Condition_ExpectedResult)

CI Validation

Before submitting PR:

pixi run lint         # Must pass
pixi run test-all     # Must pass
pixi run -e cuda test-all # Must pass on Linux CUDA hosts

Debugging Test Failures

# Run the smallest existing Pixi test task that covers the failure
pixi run test-unit

# Get CI logs
gh run view <RUN_ID> --log-failed

Gotchas

• pixi run build builds libraries only, NOT the unit-test binaries. If you run ctest without building the test target first, you may execute stale binaries that silently pass. Build the test target before running its label, e.g. for the simulation suite: pixi run build-simulation-tests (target dart_simulation_tests) before ctest -L simulation.
• pixi run test-all is the default-environment full gate. On Linux hosts with a visible NVIDIA CUDA runtime, also run pixi run -e cuda test-all; the CUDA run preserves the cuda Pixi environment and executes the CUDA CTest + benchmark smoke path when the runtime is detected.
• The CUDA Pixi config auto-detects visible GPU compute capabilities for DART_CUDA_ARCHITECTURES; unsupported PTX/toolchain errors usually mean the generated CUDA architecture flags need to be checked before blaming test code.

dart-triage-issue

Use this skill in Codex to run the DART dart-triage-issue workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-triage-issue <arguments>
• Codex: $dart-triage-issue <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Triage issue: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md

Workflow

1. Inspect the issue:

   gh issue view <ISSUE_NUMBER> --comments
   

2. Determine whether the report is still valid on current origin/main.
3. Classify status:
   • still valid
   • already fixed
   • needs more information
   • duplicate
   • out of scope
4. If validity depends on behavior, reproduce or inspect the relevant code path.
5. Do not close or comment unless the user explicitly asks for that action.

Output

• Status
• Rationale in 1-3 bullets
• Recommended next step
• Suggested reply text, if useful

dart-ultrawork

Use this skill in Codex to run the DART dart-ultrawork workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a generated Codex adapter entrypoint.

Invocation

• Claude Code/OpenCode: /dart-ultrawork <arguments>
• Codex: $dart-ultrawork <arguments>

Treat the text after the skill name as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Start a team-scale or autonomous DART task: $ARGUMENTS

Required Reading

@AGENTS.md @docs/ai/principles.md @docs/ai/north-star.md @docs/ai/orchestration.md @docs/ai/sessions.md @docs/ai/verification.md @docs/dev_tasks/README.md @docs/information-architecture.md @docs/plans/dashboard.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md @docs/onboarding/ai-tools.md

Arguments

$ARGUMENTS is a task brief plus optional mode flags:

• mode=interview: ask one up-front batch of critical questions.
• mode=brief: treat provided context as sufficient unless escalation applies.
• mode=resume: start from the existing docs/dev_tasks/<task>/ project home and run the session-start protocol before changing files.
• interview=skip: skip maintainer questions only when the brief already answers all consequential decisions.

The brief may be prose or a structured TASK / CONTEXT block. Extract north star, deliverable, acceptance criteria, constraints, risks, references, paths, issues/PRs/branches, commands, and first step when present.

Workflow

You are the orchestrator, supervisor, and steerer for the entire task: you decompose, delegate, review, and keep evidence honest. Workers implement. Follow the orchestrator/executor contract and packet sizing rules in docs/ai/orchestration.md. Use dart-new-task instead when the work is a bounded single-session task and the user did not ask for autonomous project handling.

1. Session start and current reality - Locate the project home. For DART autonomous projects this is docs/dev_tasks/<task>/, not a parallel project directory. If it exists, read its README.md, RESUME.md, and any autonomous sidecars such as decisions.md, verification.md, or progress-log.md; then verify checkout state, current branch, and any branch/PR evidence named by the docs. If the docs are stale, update the handoff/current-reality note before relying on them. If no project home exists and the task is multi-session, team-scale, design-heavy, risky, or explicitly autonomous, create docs/dev_tasks/<task>/ before implementation. If prior work exists elsewhere, first absorb or summarize it into the project home.
2. Understand and scout - Restate the north star, final deliverable, acceptance criteria, quality bar, non-goals, constraints, risks, and target branch line (DART 7 main, DART 6 LTS, or both). Scout the territory first with named docs/code, read-only searches, a dart-analyze pass, or focused reference review; draft a candidate decomposition privately before asking anything.
3. Interview decisions; self-resolve uncertainties - Ask at most one up-front batch of critical questions. Escalate before destructive operations, history rewrites, irreversible migrations, meaningful cost, security/credential/secret handling, legal or privacy-sensitive decisions, major product-direction choices not covered by the brief, conflicts with stated constraints, or any assumption whose wrong answer could cause significant harm. If input is unavailable, choose the safest reversible path, document the assumption, and continue only with non-blocked work. Then split consequential unknowns:
   • Maintainer decisions: preference, scope, public API, release, quality-bar, or roadmap calls that evidence cannot settle. Ask the human now in one batched interview (focused questions with 2-4 concrete options each, recommendation first). Do not start large work while a consequential decision is open. Skip this discretionary interview when mode=brief; also skip when interview=skip and the prompt already answers everything consequential. In both cases, still follow the escalation rules above.
   • Evidence-resolvable uncertainties: anything a focused A/B test, benchmark, throwaway spike, reference lookup, or blind-spot review can settle. Do not ask the human; schedule these as spike/research packets and record the method and result as evidence (see "Discovering unknowns before committing" in docs/ai/orchestration.md).
4. Create or refresh the tracking surface - Populate the project home with value, north star, deliverable, scope, non-goals, assumptions, risks, acceptance evidence, gates, dependencies, milestone, next actions, and blockers. Behavior-bearing physics/simulation work needs a high-quality, self-contained GUI or demos-app artifact unless explicitly out of scope. Keep RESUME.md as the handoff; add decisions.md, verification.md, and progress-log.md sidecars when they improve resumability or evidence.
5. Set the goal contract - Express done-when as verifiable outcomes (files, tests, gates, artifacts). When the session supports a goal or stop-hook mode (for example /goal in Claude Code), set it to this contract so orchestration cannot stop early or loop forever. Stop once the acceptance criteria are satisfied, verification is recorded, docs are current, known gaps are documented, and unnecessary work has been removed or deferred. Every delegated packet gets its own contract: GOAL (one sentence), DONE WHEN (verifiable), EVIDENCE (what to record), RISKS, and NEXT STEP.
6. Decompose and route to workers - Cut work packets per docs/ai/orchestration.md, then route by the current model routing in docs/ai/README.md: implementation packets to Codex executors, iterative build/test lanes to team workers when available, review lanes to an independent session, and critical decisions or stuck failures to the oracle. Without team tooling, execute packets sequentially through dart-execute-packet. Use parallelism only when the environment supports it and file ownership can stay disjoint.
7. Run the autonomous work/review cycle - For each meaningful chunk: plan, execute, verify, then run an independent/specialized review lane. Treat review findings as hypotheses: investigate, fix or record no-fix evidence, clean up, re-verify, and re-review. A packet is not done until the current post-fix state has at least two clean review passes recorded.
8. Supervise and steer - Monitor progress; unblock, reassign, or re-cut packets on scope mismatch. Workers return Task, Summary, Files changed, Evidence/tests, Risks, and Recommended next step. Use Codex from Claude, Claude from Codex, subagents, or specialist reviewers when available; fall back to role-separated local review only when unavailable. Root-cause failures and fold newly discovered unknowns back into step 3.
9. Update docs at each stopping point - Every meaningful cycle updates the project home: README.md for status/plan/risks, RESUME.md for the next fresh-session handoff, decisions.md if decisions changed, verification.md if checks ran or gaps were found, and progress-log.md for completed chunks when that sidecar exists. Keep docs current enough for a zero-context session to resume without hidden chat memory.
10. Version-control and closeout - Keep commits and PRs coherent: separate feature work, bug fixes, refactors, docs, experiments, and AI-infra changes when practical; review the diff, remove unrelated changes, make the changelog decision, and run pixi run lint before commits. Run task-specific gates from docs/ai/verification.md, record evidence per packet, and complete the principle audit. A project is complete only when the north star and acceptance criteria are met, verification evidence is recorded, docs are current, known gaps are documented, unnecessary work is removed or deferred, and final state is summarized in RESUME.md or a durable owner. Promote durable artifacts out of docs/dev_tasks/<task>/ and remove the folder in the completing PR. GitHub mutations (push, PR, comments, re-triggers) only with explicit maintainer/user approval.

Kickoff Prompt Template

Canonical fresh-session prompt. TASK, context, and Done when are per-task; reuse the Logistics block verbatim.

TASK: <one-sentence objective>

<Per-task context: constraints, quality bar, must/never rules, and pointers
to the docs, code, branches, or references that define the territory.>

Done when:
- <verifiable outcome: a file, test, gate, benchmark, or artifact>
- <verifiable outcome>

Logistics:
- Run /dart-ultrawork with this task. You are the orchestrator,
  supervisor, and steerer: decompose, delegate, review, and keep evidence
  honest.
- Interview first: ask the maintainer only the consequential decisions that
  evidence cannot settle; resolve everything else yourself and record the
  evidence.
- Use docs/dev_tasks/<task>/ as the project home. Keep README.md,
  RESUME.md, and any decisions.md / verification.md / progress-log.md
  sidecars current enough for a zero-context session to resume.
- Prioritize correctness over speed, but stop once acceptance criteria are
  satisfied, verification is recorded, docs are current, and known gaps are
  documented. Manage resources responsibly; avoid endless exploration and
  low-value polishing.
- Route well-defined implementation packets to Codex executors with GOAL /
  DONE WHEN / EVIDENCE. Use team mode only when available and file ownership
  can stay disjoint. Keep authoring and review separate. Use the oracle for
  critical decisions, hard failures, and research synthesis.
- Set goal mode to Done-when; use Claude `/goal Run /dart-ultrawork with:
  <real prompt>` or Codex `/goal $dart-ultrawork <real prompt>`. Treat Claude
  goal text beginning `ulw:` or `ultrawok:` as shorthand for the same canonical
  `/dart-ultrawork` workflow, not as separate capabilities.
- Read docs/ai/principles.md, docs/ai/north-star.md,
  docs/ai/orchestration.md, and docs/ai/sessions.md before starting.
- Review loop: use specialized reviewers when available, investigate findings,
  and require two clean passes on the current state before done.
- Verification first: task-specific gates, GUI/demo evidence when relevant,
  pixi run lint before commits; GitHub mutations only with approval.

Output

• Interview record, uncertainty-resolution evidence, and project-home path
• Packet list, routing, goal contracts, gates, and review-loop status
• Per-packet evidence, GUI/demo artifacts when relevant, and updated docs
• Principle audit, cleanup status, and approved external mutations

DART Simulation Verification

Load this skill when verifying that a DART 3D scene or physics simulation is correct — implementing, debugging, benchmarking, or reviewing dynamics, collision, contact, or GUI output. DART's domains need 3D understanding that language models lack natively; this tooling makes it checkable without a GUI.

Lead with text, corroborate with images. Measured A/B evidence: per-step metrics and trajectories detect nearly all seeded physics defects; a rendered image alone misses static geometry defects (penetration, interpenetration). Decide correctness from text; use images for scene comprehension and gross dynamic failures.

Full documentation

docs/onboarding/agent-sim-verification.md — the durable guide. docs/ai/verification.md owns the gate policy; docs/onboarding/profiling.md owns text-first profiling.

Quick commands

Text (primary):

• world.compute_step_metrics() — energy/momentum/penetration/contacts/residual
• dartpy.dump_scene_json(world) / dump_scene_text(world) — "what is in this world?" (glTF/USD-flavored hierarchy + flat index)
• pixi run scene-diff — structural JSON verdict for intended-vs-actual scene dumps
• pixi run trajectory-record / pixi run trajectory-compare — per-body TSV + contact JSONL; bit-exact or tolerance diff with first-divergence

Visual (corroboration):

• dart.gui.render(world, camera=None, size=(w, h)) → headless image; .png_bytes() for notebooks; dart.gui.orbit_camera(...) / look_at(...)
• viewer camera flags: --view {three-quarter|front|side|top}, --camera-azimuth/-elevation/-distance/-target, --turntable N, --fit
• pixi run py-demo-capture — headless PNG/MP4 capture from Python
• pixi run image-verdict / image-golden / image-sheet — JSON verdict, golden diff, contact sheet (contrast is report-only; --require-contrast to gate)
• pixi run image-ab-study — blind-judge detection deltas for single-view, multi-view, turntable, and annotated captures
• pixi run image-ab-round2 — prepare a blinded round-2 packet and score completed judge observations

Opt-in:

• pixi run render-golden-gate — opt-in golden gate (backend-specific golden, curated locally with -- --update; not default CI)
• pixi run rerun-trajectory — rerun.io inspection (opt-in; graceful when rerun-sdk is absent)
• pixi run verification-bundle — package text evidence plus still/grid images for a provider-neutral VLM or reviewer call

Default capture for agent review: one ~1280 px frame, UI hidden, 3/4 view; add a 9-frame grid for motion. Keep images as corroboration, never the sole oracle for static geometry.

DART 6 (release-6.20)

Equivalent capture over OpenSceneGraph: dart::gui::osg::setUpOffscreenViewer / captureOffscreen + dartpy bindings, pixi run capture (needs a real X server or Xvfb), the ported image tooling, and pixi run bm-boxes-headless for rendering-free determinism checksums.