From 32f7620c34a3c98fde5ff22bfcff6815fb5f0d2d Mon Sep 17 00:00:00 2001
From: sl-firmware <sl-firmware@saltylab.local>
Date: Sat, 28 Feb 2026 18:49:41 -0500
Subject: [PATCH] docs: multi-variant branch strategy (issue #28)

Document 6 variant branches (saltylab/dev, saltyrover/dev, saltytank/dev),
promotion rules, and agent targeting conventions. Remove resolved USB CDC
blocker note.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e390876
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,59 @@
+# 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"
+```
-- 
2.47.2