Skip to content

Commit b054590

Browse files
jaagutjaagut
authored
Add agent instructions and development environment guidelines (#911)
2 parents a986c56 + 85bbdf0 commit b054590

1 file changed

Lines changed: 187 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Agent Instructions
2+
3+
## Workspace Overview
4+
5+
This repository contains the Hamburg Bit-Bots software stack for RoboCup
6+
humanoid soccer robots. It is a ROS 2 workspace with packages for behavior,
7+
motion, navigation, perception, world modeling, team communication, simulation,
8+
robot support, shared messages, and operational tooling. Packages are grouped by
9+
capability under `src/`; reusable or externally maintained projects are imported
10+
under `src/lib`.
11+
12+
The stack is implemented primarily in C++ and Python, with selected Rust
13+
components. ROS 2 packages use `ament_cmake` or Python packaging and are built and
14+
tested with `colcon` through Pixi tasks. Pixi and RoboStack provide the
15+
reproducible ROS and development environment. Common foundational technologies
16+
include:
17+
18+
- ROS 2 client libraries, launch, parameters, actions, services, topics, TF, and
19+
plugin infrastructure.
20+
- CMake, Eigen, OpenCV, and pybind11 for native robotics and vision code.
21+
- Python with pytest, mypy, Ruff, and ROS Python tooling.
22+
- The Dynamic Stack Decider for behavior and state-machine-like control.
23+
- MuJoCo for simulation and ONNX Runtime for learned models where applicable.
24+
- pre-commit, clang-format, and cppcheck for repository-wide quality checks
25+
(available through Pixi).
26+
27+
Do not assume every package uses every technology. Inspect the affected
28+
package's manifests and nearby code before choosing tools or patterns.
29+
30+
## Working Principles
31+
32+
- Read the affected package and its surrounding code before editing.
33+
Prefer established package patterns, helper APIs, and naming conventions.
34+
- Keep changes scoped to the requested behavior.
35+
Do not perform unrelated refactors or reformat unrelated files.
36+
- Preserve existing user changes in a dirty worktree.
37+
Never discard or overwrite changes that are unrelated to the task.
38+
- Inspect `package.xml`, `CMakeLists.txt`, `setup.py`, and `setup.cfg` as
39+
applicable before changing a package's build, dependencies, or entry points.
40+
- Update documentation, configuration examples, and tests when changing public
41+
behavior, parameters, interfaces, or developer workflows.
42+
43+
## Development Environment
44+
45+
This ROS 2 workspace is managed by Pixi. Run development commands through the
46+
repository's Pixi environments; do not invoke `colcon`, ROS 2 tools, or formatters
47+
directly from the host shell.
48+
49+
- Use the `default` environment for normal development.
50+
It contains the `ros` and `format` features.
51+
- Use the `format` environment only for formatting-only work.
52+
- Use the `robot` environment only when robot-specific dependencies are needed.
53+
- Prefer `pixi run -e <environment> <command>` over `pixi shell`.
54+
A persistent shell can become stale after environment changes.
55+
- Use `pixi task list` to inspect available repository tasks.
56+
57+
Common commands:
58+
59+
- Build the workspace with `pixi run -e default build`.
60+
Use the argument `--parallel-workers 2` for resource constrained environments
61+
(< 8 CPU cores, < 8 GB unused RAM), but prefer the default parallelism on CI
62+
and powerful developer machines.
63+
- Build selected packages with
64+
`pixi run -e default build --packages-select <package...>`.
65+
- Run all tests with `pixi run -e default test`.
66+
- Test selected packages with
67+
`pixi run -e default test --packages-select <package...>`.
68+
- Run formatting and linting with `pixi run -e default format`.
69+
Review the resulting diff because this task may modify files.
70+
- Run one-off tools with `pixi run -e default <command>`.
71+
- Clean all workspace build artifacts with `pixi run -e default clean`.
72+
- Clean one package with `pixi run -e default clean <package>`.
73+
- Use `pixi clean` only to reset Pixi's local environment data.
74+
This requires downloading dependencies and rebuilding afterward.
75+
76+
The Pixi environments provide the pinned compiler, ROS 2 installation,
77+
dependencies, activation variables, and workspace setup used by CI. Direct host
78+
commands may use incompatible installations or incomplete environment state.
79+
80+
## Dependencies
81+
82+
- Search the configured channels first with `pixi search <package>`.
83+
- Determine to which section a dependency belongs to in `pixi.toml`.
84+
- Before adding or moving a dependency, propose the suitable feature and
85+
environment to the user, explain why, and ask for confirmation. Do not edit
86+
dependency declarations or regenerate the lockfile until the user confirms.
87+
- Prefer Conda dependencies over PyPI dependencies when a suitable package is
88+
available on the configured channels.
89+
- Keep version constraints consistent with neighboring entries and explain any
90+
new pin or upper bound in a comment when it is not self-evident.
91+
92+
## ROS Packages
93+
94+
- Follow the package's existing Python or CMake structure rather than creating a
95+
new layout.
96+
- Keep `package.xml`, build-system declarations, exports, and runtime imports in
97+
sync when adding or removing dependencies.
98+
- When changing a message, service, or action definition, identify and rebuild
99+
the interface package and affected consumers. Update mocks, tests, and
100+
documentation that depend on the interface.
101+
- For packages using `generate_parameter_library`, edit the source parameter
102+
definition rather than generated headers or installed output.
103+
- Reuse existing launch patterns and substitutions. Keep launch argument,
104+
parameter, topic, and namespace names consistent across launch files, config
105+
files, and node declarations.
106+
107+
## Configuration
108+
109+
- Treat template and default configuration files as the canonical examples.
110+
Update them together when they describe the same parameter set.
111+
- Preserve robot-specific configuration overrides unless the requested change
112+
explicitly applies to those robots.
113+
- Do not silently change calibration, joint limits, hardware addresses, network
114+
settings, or safety thresholds.
115+
- Validate renamed or added parameters against their declarations and all launch
116+
files that load them.
117+
118+
## Generated Files
119+
120+
- Do not manually edit files marked as generated or files produced in `build/`,
121+
`install/`, or `log/`.
122+
- Locate and edit the source schema, parameter definition, model, or generator,
123+
then regenerate output through the repository's normal tooling.
124+
- Treat lockfiles as generated artifacts, but commit their updates when an
125+
approved dependency change requires them.
126+
- Before editing large vendored, minified, protocol-generated, or model files,
127+
verify that they are intended source files and not generator output.
128+
129+
## Testing and Validation
130+
131+
- Start with the narrowest relevant package build and test commands. Broaden
132+
validation when changing shared libraries, interfaces, launch behavior, or
133+
cross-package contracts.
134+
- Add or update focused tests for bug fixes and behavioral changes.
135+
- Run formatting after code changes and inspect all formatter modifications.
136+
- Report commands that could not be run and the concrete reason.
137+
- Identify tests that require a robot, simulator, GPU, camera, audio device,
138+
network access, or other unavailable hardware. Do not claim these tests passed
139+
based only on unit-test results.
140+
141+
## Hardware and Deployment Safety
142+
143+
- Do not deploy, start robot processes, enable motors, command motion, play
144+
animations, or change hardware state without explicit user approval.
145+
- Do not modify calibration or robot-specific hardware configuration without
146+
explicit confirmation of the target robot and intended values.
147+
- Prefer simulation or offline validation when it covers the requested behavior.
148+
- Call out commands that can move hardware or affect devices before running
149+
them, even when the command is wrapped in Pixi.
150+
151+
## Repository Boundaries
152+
153+
- Directories under `src/lib` with a `.gitrepo` file are imported using
154+
git-subrepo. Treat them as separately maintained upstream projects.
155+
- Avoid modifying imported libraries for a repository-local workaround unless
156+
the task explicitly requires an upstream library change.
157+
- When an imported library must change, keep the change focused, run that
158+
library's own tests where available, and note that the corresponding upstream
159+
repository may need the same change.
160+
- Do not commit build output, logs, caches, downloaded models, or local IDE state
161+
unless the repository intentionally tracks that artifact.
162+
163+
## Git Conventions
164+
165+
- Make changes on a branch and open a pull request against `main`.
166+
- Prefix branch names with `feature/`, `fix/`, or `refactor/` when applicable.
167+
- Write commit subjects as `<type>: <description>`, using a concise type such as
168+
`feat`, `fix`, `refactor`, `docs`, `test`, or `chore`.
169+
- Explain why a non-obvious change is needed in the commit body or pull request
170+
description.
171+
- Keep commits focused and do not include unrelated formatter or generated-file
172+
churn.
173+
174+
## Dynamic Stack Decider
175+
176+
Several robot behaviors use the Dynamic Stack Decider (DSD). Read
177+
`src/lib/dynamic_stack_decider/README.md` before changing DSD behavior or syntax.
178+
179+
- DSD behavior files form a tree: decisions use `$Decision`, actions use
180+
`@Action`, and `-->` marks the behavior entry point.
181+
- Implement decisions and actions as Python classes in the package's `*_dsd`
182+
directory, following nearby elements and their shared blackboard APIs.
183+
- Keep decision result strings consistent with branches in the corresponding
184+
`.dsd` file. Decision results conventionally use uppercase names.
185+
- Validate DSD changes with the package's parsing test, such as
186+
`test_dsd_file.py` or `test_dsd_valid.py`, through the selected-package Pixi
187+
test command.

0 commit comments

Comments
 (0)