Skip to content

Latest commit

 

History

History
187 lines (139 loc) · 8.04 KB

AGENTS.md

File metadata and controls

187 lines (139 loc) · 8.04 KB

Agent Guidelines for DART

This file is a pointer board for agents working in this repository. Keep it concise and expand other documents instead.

Project Overview

WHAT: C++20 physics engine for robotics simulation with Python bindings (dartpy) WHY: Research-grade dynamics for robotics, animation, and machine learning HOW: Build/test with pixi run tasks; format with pixi run lint before commits

Quick Commands

pixi run test-all       # Lint + build + all tests (fails fast)
pixi run lint           # Format code/docs (auto-fixes)
pixi run build          # Build C++ and Python
pixi run test-unit      # Unit tests only (faster)
pixi run test-py        # Python tests only
pixi run check-lint     # Check formatting without fixing

Success: "All tests passed!"

If this fails, see docs/onboarding/ci-cd.md for troubleshooting.

Context Loading (IMPORTANT)

Agents MUST load relevant docs before starting work. Use @file syntax to auto-load context:

Task Type Load These Files
Any task This file (auto-loaded)
Building @docs/onboarding/building.md
Testing @docs/onboarding/testing.md
Contributing @docs/onboarding/contributing.md @CONTRIBUTING.md
Code style @docs/onboarding/code-style.md
Architecture @docs/onboarding/architecture.md @docs/onboarding/README.md
Theory (math) @docs/background/dynamics/ @docs/background/lcp/
CI/CD issues @docs/onboarding/ci-cd.md
Python bindings @docs/onboarding/python-bindings.md
Model loading @docs/onboarding/io-parsing.md
Build system @docs/onboarding/build-system.md
AI tools @docs/onboarding/ai-tools.md
PR reviews @docs/onboarding/ai-tools.md (AI review handling rules)
Dev tasks @docs/dev_tasks/README.md (when to create, cleanup rules)

Slash Commands

Use /dart-* commands for consistent, context-aware workflows:

Command Purpose
/dart-new-task Start new feature/bugfix/refactor
/dart-resume Continue work from previous session
/dart-fix-issue <#> Resolve a GitHub issue
/dart-fix-ci Debug and fix CI failures
/dart-review-pr Review or address PR feedback
/dart-docs-update Update documentation

Commands are defined in .claude/commands/ (synced to .opencode/command/).

Skills (On-Demand Knowledge)

Skills provide domain-specific knowledge loaded when needed:

Skill When to Load
dart-build Build system, CMake, dependencies
dart-test Writing tests, debugging failures
dart-contribute PR workflow, code review, dual-PR for bugfixes

Skills are in .claude/skills/ (synced to .codex/skills/ for Codex).

Key Rules

  • Bug fixes: Require PRs to BOTH release-6.16 AND main branches. See docs/onboarding/contributing.md.
  • Multi-phase tasks: Create docs/dev_tasks/<task>/ for tracking. See docs/dev_tasks/README.md for criteria.
  • AI reviews: NEVER reply to AI-generated review comments (usernames ending in [bot] like chatgpt-codex-connector[bot]}, github-actions[bot], copilot[bot]). No gh pr comment, no PR comment replies. Just push the fix silently, then re-trigger with @codex review. See docs/onboarding/ai-tools.md.
  • Commands: Use pixi run ... tasks; don't invent new entry points.
  • Formatting: Run pixi run lint before committing (auto-fixes).
  • PRs: Use .github/PULL_REQUEST_TEMPLATE.md and set the milestone (DART 7.0 for main, DART 6.16.x for release-6.16).
  • Subdirectories: May have their own AGENTS.md for module-specific rules.

Pre-Commit Checklist (MANDATORY)

STOP before every git commit. Verify:

  • pixi run lint — ALWAYS run, even for docs-only changes. CI WILL fail without this.
  • pixi run build — If C++/Python code changed
  • pixi run test-unit — If behavior could be affected
  • CHANGELOG.md — Update if adding features, fixing bugs, or making breaking changes
  • Dev task cleanup — If task used docs/dev_tasks/<task>/, remove folder in this PR (not after merge)

Shortcut: pixi run test-all runs lint + build + all tests.

Why this exists: Agents often skip pixi run lint when focused on the task. CI will catch issues, but fixing post-push wastes time and CI resources. Run lint locally first—EVERY time.

Tool Compatibility

Note: Tool compatibility assumptions below are based on testing as of Jan 2025. AI tools evolve rapidly. Verify these assumptions when:

  • Setting up a new environment
  • Updating tool versions
  • Experiencing unexpected behavior

See docs/onboarding/ai-tools.md for detailed compatibility notes.

Tool Instructions Commands Skills
Claude Code CLAUDE.md -> AGENTS.md .claude/commands/ .claude/skills/
OpenCode AGENTS.md .opencode/command/ .claude/skills/
Codex AGENTS.md ~/.codex/prompts/ .codex/skills/
Gemini CLI GEMINI.md -> AGENTS.md Read manually Read manually

Prompt Templates (Reference)

docs/prompts/ contains prompt template documentation. Prefer slash commands over manual prompts when available.

Index: docs/prompts/AGENTS.md

<skills_system priority="1">

Available Skills

When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

How to use skills:

  • Invoke: npx openskills read <skill-name> (run in your shell)
    • For multiple: npx openskills read skill-one,skill-two
  • The skill content will load with detailed instructions on how to complete the task
  • Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

Usage notes:

  • Only use skills listed in <available_skills> below
  • Do not invoke a skill that is already loaded in your context
  • Each skill invocation is stateless

<available_skills>

dart-build DART build system knowledge - CMake, pixi, dependencies, troubleshooting project dart-ci DART CI/CD troubleshooting - GitHub Actions, cache debugging, platform-specific failures project dart-contribute DART contribution workflow - branching, PRs, code review, dual-PR for bugfixes project dart-io DART model loading - URDF, SDF, MJCF, SKEL parsers and dart::io unified API project dart-python DART Python bindings (dartpy) - nanobind, wheel building, API patterns project dart-test DART testing patterns - unit tests, integration tests, CI validation project

</available_skills>

</skills_system>