# SaltyLab Firmware — Agent Playbook

## Project
Self-balancing two-wheeled robot: STM32F722 flight controller, hoverboard hub motors, Jetson Nano for AI/SLAM.

## Team
| Agent | Role | Focus |
|-------|------|-------|
| **sl-firmware** | Embedded Firmware Lead | STM32 HAL, USB CDC debugging, SPI/UART, PlatformIO, DFU bootloader |
| **sl-controls** | Control Systems Engineer | PID tuning, IMU sensor fusion, real-time control loops, safety systems |
| **sl-perception** | Perception / SLAM Engineer | Jetson Nano, RealSense D435i, RPLIDAR, ROS2, Nav2 |

## Status
USB CDC TX bug resolved (PR #10 — DCache MPU non-cacheable region + IWDG ordering fix).

## Repo Structure
- `projects/saltybot/SALTYLAB.md` — Design doc
- `USB_CDC_BUG.md` — USB peripheral conflict details
- `TEAM.md` — Team roles specification

## Branch Strategy (issue #28)

### Variant branches
| Branch | Purpose |
|--------|---------|
| `saltylab` | Stable — SaltyLab 2-wheel balance bot (promoted from saltylab-dev) |
| `saltylab-dev` | Integration — SaltyLab balance bot; agents target this branch |
| `saltyrover` | Stable — 4-wheel rover variant |
| `saltyrover-dev` | Integration — rover variant |
| `saltytank` | Stable — tracked tank variant |
| `saltytank-dev` | Integration — tank variant |
| `main` | Shared code only (IMU drivers, USB CDC, balance core, safety) |

### Rules
- Agents branch FROM `<variant>-dev` and PR back TO `<variant>-dev`
- Shared/infrastructure code (IMU drivers, USB CDC, balance core, safety) goes in `main`
- Variant-specific code (motor topology, kinematics, config) goes in variant branches
- Stable branches get promoted from `-dev` after review and hardware testing
- **Current SaltyLab team** works against `saltylab-dev`

### Git Workflow
- Branch naming: `<agent>/<slug>` (e.g., `sl-firmware/usb-cdc-fix`)
- For shared code targeting `main`: `<agent>/bd-<id>-<slug>`
- Before every push: `git fetch origin && git rebase origin/<base-branch>`
- Gitea: `gitea.vayrette.com/seb/saltylab-firmware`

## Communication
- Report progress to max via MQTT: `AGENT_NAME=<agent> ~/agent-mqtt/agent-send max "<message>"`
- Check inbox: `~/agent-mqtt/agent-read 2>/dev/null | tail -15`
- Prioritize messages from max (PM)

## Beads (Task System)
```bash
cd /Users/seb/AI/saltylab-firmware
br list                    # List open beads
br update <id> --claim     # Claim a bead
br close <id> --reason "Done. PR #N"
br comment <id> "message"
```