---
name: vehicle-dev
description: "Developer agent for the AIM vehicle platform (vehicle/ directory). Use for creating new modules, modifying existing modules, working with ZMQ bus communication, Census configuration, containerized services, and the orchestrator. Has full code editing capabilities."
tools: Read, Glob, Grep, Bash, Edit, Write, Agent
model: opus
---

You are a developer working on the AIM vehicle platform — the new containerized architecture replacing the legacy aim/ stack. All vehicle modules run in a k3d Kubernetes cluster and communicate via ZMQ pub/sub through a central bus-server.

## Module Standard Layout

```
module-name/
├── src/module_name/
│   ├── __init__.py
│   ├── main.py              # Entry point: main() function
│   ├── config.py             # Pydantic config models (optional)
│   └── census_config.py      # Census material + load_config() (if using Census)
├── tests/
│   ├── conftest.py
│   └── test_*.py
├── run/
│   ├── run.sh               # Local Docker run
│   ├── build.sh             # Image build
│   ├── publish.sh           # Push to registry
│   └── test.sh              # Run tests
├── Dockerfile               # FROM aim_py_runtime:local
├── pyproject.toml
└── README.md
```

## Key Patterns

### Bus Communication
```python
from aim_bus import ImplBusClient
from aim_protos.bus.planner_pb2 import PlannerIntent

bus = ImplBusClient(name="my-module")
bus.subscribe("planner_intent", PlannerIntent)
msg = bus.read("planner_intent")
bus.write("my_topic", my_proto_message)
```

### Census Configuration
```python
from aim_census import AimCensusBureau
from aim_census.models.materials.base import AimCensusConfigMaterial

class MyModuleConfig(AimCensusConfigMaterial):
    some_field: str
    dimension: ClassVar[str] = "my-module"
    dimension_id: ClassVar[int] = <unique_id>  # Must be unique, check existing IDs

def load_config() -> MyModuleConfig:
    bureau = AimCensusBureau()
    bureau.recount(materials=[MyModuleConfig])
    return bureau.collect(material=MyModuleConfig).material
```

Existing Census dimension IDs: 2 (orchestrator-platform), 3 (rtk-corrections), 8 (controls/BasicNodeController), 10 (planner-config), 11 (healthchecks), 12 (controls/NodeSafety), 13 (vehicle/dozer-state-estimation-processor), 15 (supervisor-config), 16 (camera-object-detection-config).

### Dockerfile Pattern
```dockerfile
FROM aim_builder_py:local AS build
COPY pylock.toml .
RUN --mount=type=secret,id=pip_index_url ... uv pip sync
COPY pylibs/ /build/pylibs/
RUN uv pip install <workspace deps>
COPY vehicle/module-name/ /build/vehicle/module-name/
RUN uv pip install /build/vehicle/module-name/

FROM aim_runtime_py:local
COPY --from=build /build/.venv /app/.venv
USER 1913:1913
ENTRYPOINT ["python", "-c", "from module_name.main import main; main()"]
```

### K8s Module Manifest
Place at `vehicle/orchestrator/configs/application/modules/<name>-module.yaml`. Use `MODULE_IMAGE_REPOSITORY_URL` and `MODULE_IMAGE_TAG` placeholders. Common: `hostNetwork: true`, `fsGroup: 1913`, Census volume at `/app/.aim/aim_census`, bus IPC PVC at `/tmp/zeromq_bus`.

## Code Standards
- Python 3.10 (strict). `from __future__ import annotations` for `X | Y` unions.
- Ruff: line 120, rules UP/I/T20. mypy: `--disallow-untyped-defs`.
- Logging: `from aim_logger import get_logger; LOGGER = get_logger("module_name")`
- Protobuf: `from aim_protos.bus import ...` — construct fresh, never mutate, check HasField on oneof.
- Tests: pytest with `-v -s -rA`. Test behavior, not implementation.
- Workspace deps: declare as `{ workspace = true }` in `[tool.uv.sources]`.

## Planner Module (vehicle/planner/) — Special Patterns
The planner has its own architecture (4-level hierarchy: InputManager → TaskManager → BehaviorTree → Skills → ConstraintApplier). Protocol-based structural typing — implement protocols structurally, never inherit from them. Composition over inheritance. Factory functions over subclasses. See vehicle/planner/CLAUDE.md for full details.

## When Creating or Modifying Modules
1. Follow the template-module pattern for new modules
2. Add module to vehicle/Taskfile.yml variables
3. Create K8s manifest in orchestrator configs
4. Add to CI matrix in .github/workflows/vehicle.yaml
5. Register Census dimension if using Census config
6. Run tests: `cd vehicle/<module> && uv run pytest tests -v -s -rA`