diff --git a/docs/superpowers/specs/2026-07-30-xrobotoolkit-controller-inputs-design.md b/docs/superpowers/specs/2026-07-30-xrobotoolkit-controller-inputs-design.md
new file mode 100644
index 0000000..87e1f3e
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-30-xrobotoolkit-controller-inputs-design.md
@@ -0,0 +1,140 @@
+# XRoboToolkit 手柄输入扩展设计
+
+## 背景
+
+当前 `xrobotoolkit_to_udp_bridge` 已从 XRoboToolkit PC-Service SDK 读取左右
+手柄摇杆、主键和副键，但 `udp_controller_receiver` 只把 `grip`、`trigger`
+和位姿写入 `XrController`，其余信息在 UDP 到 ROS2 的转换中丢失。
+
+后续项目会使用 LeRobot 同时记录相机、RM75 状态和手柄输入。本次只补齐当前
+明确需要的手柄字段，不实现 LeRobot 录制，不改变现有机械臂控制逻辑。
+
+## 目标
+
+- 将左右手柄摇杆、主键和副键发布到现有 `XrController` 话题。
+- 保持现有 `grip`、`trigger` 和 `pose` 的语义及控制行为不变。
+- 兼容不包含新增字段的旧 UDP 数据包。
+- 使用现有节点、消息和 UDP 协议，不增加依赖或新话题。
+- 更新 README 和 AGENTS，记录接口及 Superpowers 的 Git 操作边界。
+
+## 不在本次范围
+
+- Grip 和 Trigger 原始模拟量。
+- 菜单键、摇杆按键、SDK 时间戳和 bridge 序号。
+- 头显位姿、26 点手部骨骼、身体追踪和 Motion Tracker。
+- LeRobot 数据集录制、相机同步和 RM75 状态采集。
+- 任何机械臂控制参数、安全逻辑或真机行为修改。
+
+## 方案选择
+
+采用直接扩展 `XrController` 的方案。相比新增 `sensor_msgs/Joy` 话题，该方案
+不需要额外同步左右手柄话题；相比继续只保留 UDP JSON，它能让 ROS2 和后续
+LeRobot 适配层直接读取类型明确的数据。
+
+修改消息定义后必须重新构建并重启相关节点。重新构建后的现有遥操作代码仍只读取
+原字段，不需要修改控制逻辑。
+
+## ROS2 消息格式
+
+`XrController.msg` 使用以下固定顺序：
+
+```text
+std_msgs/Header header
+string hand
+
+bool grip
+float32 trigger
+bool primary
+bool secondary
+float32[2] axis
+
+geometry_msgs/Pose pose
+```
+
+字段语义：
+
+- `primary`：左手 X 键，右手 A 键。
+- `secondary`：左手 Y 键，右手 B 键。
+- `axis`：对应手柄摇杆的 `[x, y]`，每个分量限制在 `[-1.0, 1.0]`。
+
+## 数据流
+
+正常链路保持不变：
+
+```text
+XRoboToolkit PC-Service SDK
+→ xrobotoolkit_to_udp_bridge
+→ UDP JSON
+→ udp_controller_receiver
+→ /xr/left_controller、/xr/right_controller
+→ single_arm_velocity_teleop
+```
+
+bridge 继续读取 Grip 和 Trigger 模拟量并应用现有滞回，只是不再把未使用的
+`grip_value`、`trigger_value`、`menu` 和 `axis_click` 放入 UDP JSON。
+
+UDP 中的按钮继续使用现有嵌套结构：
+
+```json
+{
+  "grip": true,
+  "trigger": 0.0,
+  "axis": [0.2, -0.4],
+  "buttons": {
+    "primary": true,
+    "secondary": false
+  },
+  "pos": [0.0, 1.0, 0.0],
+  "quat": [0.0, 0.0, 0.0, 1.0]
+}
+```
+
+`udp_controller_receiver` 将嵌套按钮展平到 ROS2 消息字段。现有遥操作节点忽略
+新增字段，因此目标位姿、夹爪触发和安全停止路径均不变化。
+
+## 兼容与异常处理
+
+- 旧 UDP 包缺少 `axis` 或 `buttons` 时，发布
+  `axis=[0.0, 0.0]`、`primary=false`、`secondary=false`。
+- 新增可选字段格式错误时使用上述默认值，不丢弃有效的 Grip、Trigger 和位姿。
+- bridge 和 receiver 均将摇杆分量限制在 `[-1.0, 1.0]`。
+- 旧包中存在 `menu`、`axis_click` 或其他按钮字段时忽略，不报错。
+- `sample_udp_sender` 保持旧格式，用它验证向后兼容，不为本次需求增加新参数。
+
+## 文件范围
+
+- `xr_rm_interfaces/msg/XrController.msg`
+- `xr_rm_input/xr_rm_input/xrobotoolkit_to_udp_bridge.py`
+- `xr_rm_input/xr_rm_input/udp_controller_receiver.py`
+- `xr_rm_input/test/` 下的一份最小兼容性测试
+- `README.md`
+- `AGENTS.md`
+
+不修改 `xr_rm_teleop` 控制实现及三个机械臂 YAML。
+
+## README 与 AGENTS 规则
+
+README 增加新的手柄字段、UDP 格式和兼容行为说明。
+
+AGENTS 和 README 同时明确：使用 Superpowers 执行任务时，只允许按 skill
+工作流创建本地 Git 提交；不得推送、合并或执行其他远程写操作。skill 如需本地
+worktree 或配套分支，可以创建，但不得将其合并到其他分支。
+
+## 验证
+
+自动验证包括：
+
+- bridge 生成的 UDP payload 只包含确认保留的按钮和摇杆字段。
+- 左手 X/Y 与右手 A/B 正确映射到 `primary/secondary`。
+- receiver 正确发布新增字段。
+- 旧 UDP 包继续发布，新增字段使用默认值。
+- 非法新增字段不会阻断现有 Grip、Trigger 和位姿。
+- 在 `/home/robot/WS_xr` source ROS2 Humble 后运行相关 pytest。
+- 运行 `colcon build --symlink-install`。
+
+运行验证只使用 mock，不连接真机、不移动机械臂、不操作夹爪。
+
+## Git 边界
+
+本设计和后续实现可以按 Superpowers 流程创建本地提交。禁止执行 `git push`、
+创建或合并 PR、合并本地分支以及任何远程写操作。