feat: skills - expand auto-tmux prompt tooling

skills/auto-tmux/AGENTS.md

@@ -14,6 +14,7 @@ skills/auto-tmux/
 ├── scripts/                  # 安全封装的 tmux 自动化脚本
 │   ├── auto-tmux.sh
 │   ├── swarm-state.sh
+│   ├── render-swarm-prompt.sh
 │   ├── auto-tmux-smoke-test.sh
 │   ├── README.md
 │   └── AGENTS.md
@@ -23,6 +24,7 @@ skills/auto-tmux/
     ├── api.md
     ├── automation.md
     ├── swarm-state.md
+    ├── prompt-templates.md
     ├── ai-swarm-collaboration.md
     ├── examples.md
     └── troubleshooting.md
@@ -34,6 +36,7 @@ skills/auto-tmux/
 - `assets/tmux-src` 只暴露 tmux/tmux submodule，供需要查看源码或上游文档时定位。
 - `scripts/auto-tmux.sh` 是技能执行层，封装 topology/capture/send/scan/rescue/record/snapshot/hub/wait。
 - `scripts/swarm-state.sh` 是蜂群协作状态层，管理任务、锁、状态日志和结果报告。
+- `scripts/render-swarm-prompt.sh` 是提示词渲染层，生成 commander/worker/reviewer 协议文本。
 - 技能文档可以引用软链接入口；更新上游内容必须通过 `tools/external/` 下的 submodule 指针完成。
 - 不在本目录直接修改 submodule 内容；如需改造，先 fork 上游并更新 submodule 来源。
 
@@ -42,4 +45,4 @@ skills/auto-tmux/
 - 上游来源：`tools/external/.tmux` 与 `tools/external/tmux`。
 - 下游使用：`SKILL.md` 和 `references/` 中的命令示例。
 - 验证入口：`skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict`。
-- 脚本验证：`bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。
+- 脚本验证：`bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。

skills/auto-tmux/README.md

@@ -21,8 +21,10 @@
 ```bash
 bash -n skills/auto-tmux/scripts/auto-tmux.sh
 bash -n skills/auto-tmux/scripts/swarm-state.sh
+bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 skills/auto-tmux/scripts/auto-tmux.sh help
 skills/auto-tmux/scripts/swarm-state.sh help
+skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "smoke"
 skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict
 ```

skills/auto-tmux/SKILL.md

@@ -35,6 +35,7 @@ description: "tmux 自动化操控：用 scripts/auto-tmux.sh 安全读取、发
 ```bash
 bash -n skills/auto-tmux/scripts/auto-tmux.sh
 bash -n skills/auto-tmux/scripts/swarm-state.sh
+bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 skills/auto-tmux/scripts/auto-tmux.sh help
 skills/auto-tmux/scripts/swarm-state.sh help
 ```
@@ -95,6 +96,11 @@ skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80
 skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback" --save-dir /tmp/auto-tmux-scan
 ```
 
+**受控广播到指定 session**
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run
+```
+
 **生成证据快照**
 ```bash
 skills/auto-tmux/scripts/auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot -n 120
@@ -144,6 +150,13 @@ skills/auto-tmux/scripts/swarm-state.sh report --dir /tmp/ai_swarm
 skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 ```
 
+**渲染 commander / worker / reviewer 提示词**
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "拆分并推进任务"
+skills/auto-tmux/scripts/render-swarm-prompt.sh worker --target <session>:<window>.<pane> --task "只处理指定子任务"
+skills/auto-tmux/scripts/render-swarm-prompt.sh reviewer --session ai-hub --task "审查 worker 产出"
+```
+
 ## Rules & Constraints
 
 - MUST：优先使用 `scripts/auto-tmux.sh`；直接使用 tmux 原生命令时必须保留同等安全约束。
@@ -155,6 +168,7 @@ skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 - SHOULD：pane 处在 Codex UI 时，先发送 `/exit` 回到 shell 再执行命令。
 - SHOULD：长任务开启 `pipe-pane` 记录审计；广播完成后立即 `synchronize-panes off`。
 - SHOULD：多 worker 修改同一文件、目录或服务前，先用 `swarm-state.sh lock-acquire` 声明锁。
+- SHOULD：批量下发先用 `broadcast --dry-run` 预览目标，再决定是否真实发送。
 - NEVER：在未知 pane 发送破坏性命令；NEVER 在 root 会话不经确认发送 `Ctrl+C`/`Ctrl+D`。
 
 ## Examples
@@ -206,11 +220,13 @@ skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 - `references/api.md`: tmux/oh-my-tmux 常用命令、选项与 gpakosz 特色键位
 - `references/automation.md`: `scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `references/swarm-state.md`: 蜂群状态、任务、锁和报告协议
+- `references/prompt-templates.md`: commander/worker/reviewer 提示词模板和下发方式
 - `references/ai-swarm-collaboration.md`: tmux 蜂群协作历史文档、架构模式、协议、案例和风险限制
 - `references/examples.md`: 蜂群协议脚本与长示例
 - `references/troubleshooting.md`: 典型故障到修复路径
 - `scripts/auto-tmux.sh`: 安全封装的 tmux 自动化脚本入口
 - `scripts/swarm-state.sh`: 蜂群任务、锁、状态和报告脚本
+- `scripts/render-swarm-prompt.sh`: commander/worker/reviewer 提示词渲染脚本
 - `scripts/auto-tmux-smoke-test.sh`: tmux 自动化脚本端到端自测
 - `assets/oh-my-tmux`: gpakosz/oh-my-tmux submodule 的相对软链接入口
 - `assets/tmux-src`: tmux/tmux submodule 的相对软链接入口
@@ -230,6 +246,6 @@ skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 4. ≥3 个端到端示例，含输入/步骤/验收。
 5. 长文档放在 `references/` 并可导航；无文档堆砌。
 6. 不确定项给出验证路径；禁止虚构 tmux 行为。
-7. `bash -n skills/auto-tmux/scripts/auto-tmux.sh` 与 `bash -n skills/auto-tmux/scripts/swarm-state.sh` 通过。
+7. `bash -n skills/auto-tmux/scripts/auto-tmux.sh`、`bash -n skills/auto-tmux/scripts/swarm-state.sh` 与 `bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh` 通过。
 8. `skills/auto-tmux/scripts/auto-tmux-smoke-test.sh` 通过或在无 tmux 环境下明确跳过。
 9. 运行 `skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict` 通过。

skills/auto-tmux/references/README.md

@@ -9,6 +9,7 @@
 | [api.md](./api.md) | tmux / oh-my-tmux 常用命令与配置速查 |
 | [automation.md](./automation.md) | `auto-tmux.sh` 脚本子命令、安全模型和 AI 蜂群协作流程 |
 | [swarm-state.md](./swarm-state.md) | 蜂群状态、任务、锁和报告协议 |
+| [prompt-templates.md](./prompt-templates.md) | commander/worker/reviewer 提示词模板和下发方式 |
 | [ai-swarm-collaboration.md](./ai-swarm-collaboration.md) | tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制 |
 | [examples.md](./examples.md) | 巡检、救援、审计和多 AI 工作台示例 |
 | [troubleshooting.md](./troubleshooting.md) | 常见故障与修复路径 |

skills/auto-tmux/references/ai-swarm-collaboration.md

@@ -22,6 +22,7 @@ tmux 蜂群协作的核心是：让 AI 不再只是孤立会话，而是通过 t
 | 感知 | `capture-pane` / `auto-tmux.sh capture` | 读取指定终端输出 |
 | 控制 | `send-keys` / `auto-tmux.sh send` | 向指定终端发送按键或命令 |
 | 巡检 | `auto-tmux.sh scan` | 批量检查多个 pane 状态 |
+| 广播 | `auto-tmux.sh broadcast` | 受控批量下发同一指令 |
 | 救援 | `auto-tmux.sh rescue` | 对等待确认、卡住或异常的 pane 做最小干预 |
 | 记录 | `pipe-pane` / `auto-tmux.sh record` | 保留长任务审计日志 |
 | 协调 | `swarm-state.sh` + 明确 target | 任务同步、分工、加锁、避免冲突 |
@@ -291,6 +292,12 @@ skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --re
 
 ### 7.1 Worker 模板
 
+推荐直接渲染：
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh worker --target <target> --task "只处理指定子任务"
+```
+
 ```markdown
 你是 tmux AI 蜂群中的 worker。
 
@@ -304,6 +311,12 @@ skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --re
 
 ### 7.2 Commander 模板
 
+推荐直接渲染：
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "拆分并推进任务"
+```
+
 ```markdown
 你是 tmux AI 蜂群中的 commander。
 

skills/auto-tmux/references/automation.md

@@ -14,9 +14,11 @@
 
 | 子命令 | 用途 | 风险控制 |
 |:---|:---|:---|
+| `doctor` | 检查 tmux、脚本、资产、session 健康状态 | 只读诊断 |
 | `topology` | 列出 session/window/pane 拓扑 | 只读 |
 | `capture` | 读取指定 pane 最近输出 | 默认脱敏，可保存到文件 |
 | `send` | 向指定 pane 发送文本或按键 | 先打印上下文，危险文本需 `--force` |
+| `broadcast` | 向指定 session 全部 pane 发送文本或按键 | 必须显式 session，支持 `--dry-run` |
 | `rescue` | pattern 命中后发送确认 | 不命中不发送 |
 | `scan` | 批量巡检 pane 输出 | 可按 session 限定范围 |
 | `record` | 开启/停止 pane 输出审计日志 | 文件写入到显式目录 |
@@ -26,6 +28,12 @@
 
 ## 典型流程
 
+### 0. 诊断环境
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh doctor --session ai-hub
+```
+
 ### 1. 建立 AI 工作台
 
 ```bash
@@ -56,6 +64,12 @@ skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Tra
 skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --save-dir /tmp/auto-tmux-scan
 ```
 
+受控广播前先预览：
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run
+```
+
 生成完整证据快照：
 
 ```bash
@@ -165,8 +179,10 @@ skills/auto-tmux/scripts/swarm-state.sh report
 ```bash
 bash -n skills/auto-tmux/scripts/auto-tmux.sh
 bash -n skills/auto-tmux/scripts/swarm-state.sh
+bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 skills/auto-tmux/scripts/auto-tmux.sh help
 skills/auto-tmux/scripts/swarm-state.sh help
+skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "smoke"
 skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict
 ```

skills/auto-tmux/references/index.md

@@ -6,6 +6,7 @@
 - `api.md`：tmux/oh-my-tmux 常用命令、同步广播、安全写法
 - `automation.md`：`scripts/auto-tmux.sh` 子命令、安全模型与 AI 蜂群协作流程
 - `swarm-state.md`：蜂群状态、任务、锁和报告协议
+- `prompt-templates.md`：commander/worker/reviewer 提示词模板和下发方式
 - `ai-swarm-collaboration.md`：tmux 蜂群协作完整说明、架构模式、协议、案例和风险限制
 - `examples.md`：蜂群巡检脚本、自动救援脚本、Skill Seeker 抓取示例
 - `troubleshooting.md`：常见报错与修复路径

skills/auto-tmux/references/prompt-templates.md

@@ -0,0 +1,92 @@
+# Swarm Prompt Templates
+
+`scripts/render-swarm-prompt.sh` 用于渲染 tmux 蜂群协作的 commander、worker 和 reviewer 提示词。它把常用协作协议固化成可复制模板，避免每次手写时遗漏边界、状态、锁和验收要求。
+
+## 子命令
+
+| 角色 | 命令 | 用途 |
+|:---|:---|:---|
+| commander | `render-swarm-prompt.sh commander` | 任务拆分、巡检、救援、验收 |
+| worker | `render-swarm-prompt.sh worker` | 执行单一子任务并回报证据 |
+| reviewer | `render-swarm-prompt.sh reviewer` | 独立审查 worker 产出 |
+
+## Commander Prompt
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh commander \
+  --session ai-hub \
+  --swarm-dir /tmp/ai_swarm \
+  --task "重构 README 实验性方法入口"
+```
+
+适用场景：
+
+- 开始一个多 worker 协作任务。
+- 需要统一任务拆分、锁、巡检和验收。
+- 需要让 commander 只做调度，不直接混入 worker 实现。
+
+## Worker Prompt
+
+先获取 worker target：
+
+```bash
+target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
+```
+
+渲染 worker 提示词：
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh worker \
+  --session ai-hub \
+  --target "$target" \
+  --swarm-dir /tmp/ai_swarm \
+  --task "只检查 docs/research/README.md 的链接和锚点"
+```
+
+适用场景：
+
+- 给某个 worker 下发边界清晰的单一任务。
+- 需要强制 worker 在修改前加锁，完成后写状态和结果。
+- 需要让 worker 汇报修改文件、验证结果、风险和下一步。
+
+## Reviewer Prompt
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh reviewer \
+  --session ai-hub \
+  --swarm-dir /tmp/ai_swarm \
+  --task "审查本轮 auto-tmux 脚本和文档改动"
+```
+
+适用场景：
+
+- worker 完成后，需要另一个 AI 做独立审查。
+- 需要重点检查 correctness、越界修改、缺失测试、文档不同步。
+- 需要避免同一上下文自我确认。
+
+## 推荐下发方式
+
+渲染到临时文件：
+
+```bash
+skills/auto-tmux/scripts/render-swarm-prompt.sh worker \
+  --target "$target" \
+  --task "运行 make test 并分析失败" \
+  > /tmp/worker-prompt.md
+```
+
+发送到 worker：
+
+```bash
+skills/auto-tmux/scripts/auto-tmux.sh send \
+  -t "$target" \
+  --text "$(cat /tmp/worker-prompt.md)" \
+  --enter
+```
+
+## 注意事项
+
+- Prompt 只定义职责和边界，不替代测试、lint、diff、CI 等硬门禁。
+- commander、worker、reviewer 应使用不同 pane，避免角色混淆。
+- 长任务必须配合 `record` 或 `snapshot` 保留证据。
+- 多 worker 修改同一资源前必须配合 `swarm-state.sh lock-acquire`。

skills/auto-tmux/scripts/AGENTS.md

@@ -10,6 +10,7 @@ scripts/
 ├── README.md       # 面向人类的脚本入口说明
 ├── auto-tmux.sh    # 统一 tmux 自动化命令入口
 ├── swarm-state.sh  # 蜂群状态、任务、锁和报告管理
+├── render-swarm-prompt.sh # commander/worker/reviewer 提示词渲染
 └── auto-tmux-smoke-test.sh # 临时 tmux 会话端到端自测
 ```
 
@@ -19,6 +20,8 @@ scripts/
 - 发送按键类功能必须先验证目标 pane 存在，并优先打印上下文。
 - 捕获输出默认脱敏；只有显式 `--no-redact` 才允许输出原文。
 - 批量救援必须通过 pattern 匹配触发，不允许无条件向所有 pane 发送输入。
+- 批量广播必须要求显式 session，并支持 `--dry-run`。
+- Prompt 渲染脚本只输出文本，不直接控制 tmux。
 - 状态脚本只能写入显式状态目录，不保存密钥、Token、密码或私密项目内容。
 - 自测脚本必须创建独立临时 tmux session，并在退出时清理。
 - 新增脚本后必须更新 `README.md`、`SKILL.md`、`references/index.md`，并运行 `bash -n` 与 skill strict 校验。

skills/auto-tmux/scripts/README.md

@@ -6,6 +6,7 @@
 
 - [`auto-tmux.sh`](./auto-tmux.sh) - 统一命令入口，支持拓扑、读取、发送、巡检、救援、录制、等待和 AI 工作台初始化。
 - [`swarm-state.sh`](./swarm-state.sh) - 蜂群状态、任务、锁和报告管理。
+- [`render-swarm-prompt.sh`](./render-swarm-prompt.sh) - commander、worker、reviewer 提示词渲染。
 - [`auto-tmux-smoke-test.sh`](./auto-tmux-smoke-test.sh) - 创建临时 tmux 会话，端到端验证脚本能力。
 
 ## 常用命令
@@ -17,6 +18,9 @@ skills/auto-tmux/scripts/auto-tmux.sh help
 # 查看 tmux 拓扑
 skills/auto-tmux/scripts/auto-tmux.sh topology
 
+# 诊断环境
+skills/auto-tmux/scripts/auto-tmux.sh doctor --session ai-hub
+
 target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
 
 # 读取指定 pane 最近 80 行
@@ -28,6 +32,9 @@ skills/auto-tmux/scripts/auto-tmux.sh send -t "$target" --text "make test" --ent
 # 扫描某个 session 的错误
 skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback"
 
+# 受控广播，先 dry-run
+skills/auto-tmux/scripts/auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run
+
 # 生成证据快照
 skills/auto-tmux/scripts/auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot
 
@@ -38,6 +45,9 @@ skills/auto-tmux/scripts/swarm-state.sh report --dir /tmp/ai_swarm
 
 # 端到端自测
 skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
+
+# 渲染 worker prompt
+skills/auto-tmux/scripts/render-swarm-prompt.sh worker --target "$target" --task "只运行 make test"
 ```
 
 ## 安全约束
@@ -46,4 +56,5 @@ skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 - `send` 会先打印目标 pane 最近上下文，再发送按键。
 - 危险命令默认拒绝，必须显式 `--force`。
 - 批量操作必须使用明确的 session/window/pane 目标。
+- 批量广播必须先 `--dry-run`，确认目标列表后再真实发送。
 - 多 worker 协作时用 `swarm-state.sh lock-acquire` 声明文件、目录或服务锁。

skills/auto-tmux/scripts/auto-tmux-smoke-test.sh

@@ -5,6 +5,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 AUTO_TMUX="$SCRIPT_DIR/auto-tmux.sh"
 SWARM_STATE="$SCRIPT_DIR/swarm-state.sh"
+RENDER_PROMPT="$SCRIPT_DIR/render-swarm-prompt.sh"
 SESSION="auto-tmux-smoke-$$"
 SWARM_DIR="/tmp/auto-tmux-smoke-swarm-$$"
 SNAPSHOT_DIR="/tmp/auto-tmux-smoke-snapshot-$$"
@@ -23,14 +24,17 @@ command -v tmux >/dev/null 2>&1 || {
 
 bash -n "$AUTO_TMUX"
 bash -n "$SWARM_STATE"
+bash -n "$RENDER_PROMPT"
 
 "$AUTO_TMUX" hub --session "$SESSION" --workers 1 --cmd bash
+"$AUTO_TMUX" doctor --session "$SESSION" >/tmp/auto-tmux-smoke-doctor.txt
 "$AUTO_TMUX" topology --session "$SESSION" >/tmp/auto-tmux-smoke-topology.txt
 
 commander_target="$(tmux list-panes -t "$SESSION:commander" -F '#S:#I.#P' | head -n 1)"
 worker_target="$(tmux list-panes -t "$SESSION:worker1" -F '#S:#I.#P' | head -n 1)"
 
 "$AUTO_TMUX" capture -t "$commander_target" -n 10 >/tmp/auto-tmux-smoke-capture.txt
+"$AUTO_TMUX" broadcast --session "$SESSION" --text "pwd" --enter --dry-run >/tmp/auto-tmux-smoke-broadcast.txt
 "$AUTO_TMUX" send -t "$worker_target" --text "echo AUTO_TMUX_SMOKE_OK" --enter
 "$AUTO_TMUX" wait -t "$worker_target" --pattern "AUTO_TMUX_SMOKE_OK" --timeout 10 >/tmp/auto-tmux-smoke-wait.txt
 "$AUTO_TMUX" snapshot --session "$SESSION" --dir "$SNAPSHOT_DIR" -n 20 >/tmp/auto-tmux-smoke-snapshot.txt
@@ -47,5 +51,9 @@ test -s "$SNAPSHOT_DIR/topology.txt"
 "$SWARM_STATE" task-done --dir "$SWARM_DIR" --id smoke-task --owner "$worker_target" --result "ok"
 "$SWARM_STATE" report --dir "$SWARM_DIR" >/tmp/auto-tmux-smoke-report.txt
 grep -q 'smoke-task' /tmp/auto-tmux-smoke-report.txt
+"$RENDER_PROMPT" commander --session "$SESSION" --swarm-dir "$SWARM_DIR" --task "smoke" >/tmp/auto-tmux-smoke-commander-prompt.md
+"$RENDER_PROMPT" worker --session "$SESSION" --target "$worker_target" --swarm-dir "$SWARM_DIR" --task "smoke" >/tmp/auto-tmux-smoke-worker-prompt.md
+grep -q 'Commander Prompt' /tmp/auto-tmux-smoke-commander-prompt.md
+grep -q 'Worker Prompt' /tmp/auto-tmux-smoke-worker-prompt.md
 
 printf 'auto-tmux smoke test ok: session=%s worker=%s\n' "$SESSION" "$worker_target"

skills/auto-tmux/scripts/auto-tmux.sh

@@ -13,9 +13,11 @@ auto-tmux: safe tmux automation wrapper
 
 Usage:
   auto-tmux.sh help
+  auto-tmux.sh doctor [--session NAME]
   auto-tmux.sh topology [--session NAME]
   auto-tmux.sh capture -t TARGET [-n LINES] [--save FILE] [--no-redact]
   auto-tmux.sh send -t TARGET (--text TEXT | --key KEY) [--enter] [--clear] [--force] [--dry-run]
+  auto-tmux.sh broadcast --session NAME (--text TEXT | --key KEY) [--enter] [--clear] [--force] [--dry-run]
   auto-tmux.sh rescue -t TARGET [--pattern REGEX] [--reply TEXT] [-n LINES] [--force] [--dry-run]
   auto-tmux.sh scan [--session NAME] [-n LINES] [--pattern REGEX] [--rescue] [--reply TEXT] [--save-dir DIR]
   auto-tmux.sh record start -t TARGET [--dir DIR]
@@ -28,9 +30,11 @@ Target format:
   <session>:<window>.<pane>
 
 Examples:
+  auto-tmux.sh doctor --session ai-hub
   auto-tmux.sh topology
   auto-tmux.sh capture -t <target-from-topology> -n 80
   auto-tmux.sh send -t <target-from-topology> --text "make test" --enter
+  auto-tmux.sh broadcast --session ai-hub --text "pwd" --enter --dry-run
   auto-tmux.sh rescue -t <target-from-topology> --pattern "(y/n)" --reply y
   auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback"
   auto-tmux.sh snapshot --session ai-hub --dir /tmp/auto-tmux-snapshot
@@ -47,6 +51,12 @@ warn() {
   printf 'warn: %s\n' "$*" >&2
 }
 
+status_line() {
+  local status="$1"
+  local message="$2"
+  printf '[%s] %s\n' "$status" "$message"
+}
+
 require_tmux() {
   command -v tmux >/dev/null 2>&1 || die "tmux is not installed or not in PATH"
   tmux list-sessions >/dev/null 2>&1 || die "no tmux server/session found"
@@ -110,6 +120,71 @@ pane_list() {
   fi
 }
 
+cmd_doctor() {
+  local session=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --session) session="${2:-}"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown doctor option: $1" ;;
+    esac
+  done
+
+  local failures=0
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+  if command -v tmux >/dev/null 2>&1; then
+    status_line "OK" "tmux found: $(tmux -V)"
+  else
+    status_line "FAIL" "tmux not found in PATH"
+    failures=$((failures + 1))
+  fi
+
+  if tmux list-sessions >/dev/null 2>&1; then
+    status_line "OK" "tmux server is reachable"
+  else
+    status_line "WARN" "tmux server has no reachable session yet"
+  fi
+
+  for script in auto-tmux.sh swarm-state.sh auto-tmux-smoke-test.sh render-swarm-prompt.sh; do
+    if [[ -x "$script_dir/$script" ]]; then
+      status_line "OK" "script executable: $script"
+    else
+      status_line "FAIL" "script missing or not executable: $script"
+      failures=$((failures + 1))
+    fi
+  done
+
+  local root
+  root="$(git -C "$script_dir" rev-parse --show-toplevel 2>/dev/null || true)"
+  if [[ -n "$root" ]]; then
+    for rel in skills/auto-tmux/assets/oh-my-tmux skills/auto-tmux/assets/tmux-src; do
+      if [[ -e "$root/$rel" ]]; then
+        status_line "OK" "asset exists: $rel"
+      else
+        status_line "WARN" "asset missing: $rel (run git submodule update --init --recursive)"
+      fi
+    done
+  else
+    status_line "WARN" "not inside a git worktree; skipped asset checks"
+  fi
+
+  if [[ -n "$session" ]]; then
+    if tmux has-session -t "$session" 2>/dev/null; then
+      status_line "OK" "session exists: $session"
+      tmux list-panes -t "$session" -F '  pane #S:#{window_index}.#{pane_index} cmd=#{pane_current_command}'
+    else
+      status_line "FAIL" "session not found: $session"
+      failures=$((failures + 1))
+    fi
+  fi
+
+  if (( failures > 0 )); then
+    return 1
+  fi
+}
+
 cmd_topology() {
   local session=""
   while [[ $# -gt 0 ]]; do
@@ -134,6 +209,65 @@ cmd_topology() {
   fi
 }
 
+cmd_broadcast() {
+  local session=""
+  local text=""
+  local key=""
+  local enter="0"
+  local clear="0"
+  local force="0"
+  local dry_run="0"
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --session) session="${2:-}"; shift 2 ;;
+      --text) text="${2:-}"; shift 2 ;;
+      --key) key="${2:-}"; shift 2 ;;
+      --enter) enter="1"; shift ;;
+      --clear) clear="1"; shift ;;
+      --force) force="1"; shift ;;
+      --dry-run) dry_run="1"; shift ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "unknown broadcast option: $1" ;;
+    esac
+  done
+
+  require_tmux
+  [[ -n "$session" ]] || die "broadcast requires --session NAME"
+  tmux has-session -t "$session" 2>/dev/null || die "session not found: $session"
+  [[ -n "$text" || -n "$key" ]] || die "broadcast requires --text TEXT or --key KEY"
+  [[ -z "$text" || -z "$key" ]] || die "broadcast accepts only one of --text or --key"
+  if [[ -n "$text" && "$force" != "1" ]] && is_dangerous_text "$text"; then
+    die "refusing dangerous broadcast text without --force: $text"
+  fi
+
+  local panes=()
+  mapfile -t panes < <(pane_list "$session")
+  [[ "${#panes[@]}" -gt 0 ]] || die "no panes found in session: $session"
+  printf 'broadcast targets (%s):\n' "${#panes[@]}"
+  printf '  %s\n' "${panes[@]}"
+
+  local pane
+  for pane in "${panes[@]}"; do
+    if [[ "$dry_run" == "1" ]]; then
+      printf '[dry-run] would send to %s\n' "$pane"
+      continue
+    fi
+    if [[ -n "$text" ]]; then
+      local args=(-t "$pane" --text "$text")
+      [[ "$enter" == "1" ]] && args+=(--enter)
+      [[ "$clear" == "1" ]] && args+=(--clear)
+      [[ "$force" == "1" ]] && args+=(--force)
+      cmd_send "${args[@]}"
+    else
+      local args=(-t "$pane" --key "$key")
+      [[ "$enter" == "1" ]] && args+=(--enter)
+      [[ "$clear" == "1" ]] && args+=(--clear)
+      [[ "$force" == "1" ]] && args+=(--force)
+      cmd_send "${args[@]}"
+    fi
+  done
+}
+
 cmd_capture() {
   local target=""
   local lines="$DEFAULT_LINES"
@@ -448,9 +582,11 @@ main() {
   shift || true
   case "$cmd" in
     help|-h|--help) usage ;;
+    doctor) cmd_doctor "$@" ;;
     topology) cmd_topology "$@" ;;
     capture) cmd_capture "$@" ;;
     send) cmd_send "$@" ;;
+    broadcast) cmd_broadcast "$@" ;;
     rescue) cmd_rescue "$@" ;;
     scan) cmd_scan "$@" ;;
     record) cmd_record "$@" ;;

skills/auto-tmux/scripts/render-swarm-prompt.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Render reusable commander/worker/reviewer prompts for tmux AI swarm sessions.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+render-swarm-prompt: render tmux AI swarm prompt templates
+
+Usage:
+  render-swarm-prompt.sh commander [--session NAME] [--swarm-dir DIR] [--task TEXT]
+  render-swarm-prompt.sh worker --target TARGET [--session NAME] [--swarm-dir DIR] [--task TEXT]
+  render-swarm-prompt.sh reviewer [--session NAME] [--swarm-dir DIR] [--task TEXT]
+
+Examples:
+  render-swarm-prompt.sh commander --session ai-hub --task "重构 README"
+  render-swarm-prompt.sh worker --target ai-hub:2.1 --task "只检查链接"
+  render-swarm-prompt.sh reviewer --session ai-hub
+EOF
+}
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+role="${1:-help}"
+shift || true
+
+session="ai-hub"
+swarm_dir="/tmp/ai_swarm"
+target=""
+task="未指定；请等待 commander 分配具体任务。"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --session) session="${2:-}"; shift 2 ;;
+    --swarm-dir) swarm_dir="${2:-}"; shift 2 ;;
+    --target) target="${2:-}"; shift 2 ;;
+    --task) task="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+
+case "$role" in
+  help|-h|--help)
+    usage
+    ;;
+  commander)
+    cat <<EOF
+# tmux AI 蜂群 Commander Prompt
+
+你是 tmux AI 蜂群的 commander。
+
+## 当前上下文
+
+- session: \`$session\`
+- swarm state dir: \`$swarm_dir\`
+- 总任务: $task
+
+## 你的职责
+
+1. 用 \`skills/auto-tmux/scripts/auto-tmux.sh topology --session $session\` 读取工作台拓扑。
+2. 用 \`skills/auto-tmux/scripts/swarm-state.sh init --dir $swarm_dir\` 初始化状态目录。
+3. 把总任务拆成互不冲突的 worker 子任务。
+4. 给每个子任务创建 task，并在涉及同一文件、目录或服务时要求 worker 先加锁。
+5. 用 scan/capture/snapshot 收集 worker 状态与证据。
+6. 对卡住任务先 dry-run rescue，再做最小干预。
+7. 最终只用测试、diff、日志、报告和人工验收作为完成依据。
+
+## 禁止
+
+- 不盲目广播危险命令。
+- 不让多个 worker 同时修改同一文件。
+- 不把 AI 口头保证当成验收结果。
+EOF
+    ;;
+  worker)
+    [[ -n "$target" ]] || die "worker role requires --target TARGET"
+    cat <<EOF
+# tmux AI 蜂群 Worker Prompt
+
+你是 tmux AI 蜂群中的 worker。
+
+## 当前上下文
+
+- session: \`$session\`
+- target: \`$target\`
+- swarm state dir: \`$swarm_dir\`
+- 分配任务: $task
+
+## 你的职责
+
+1. 只处理分配给你的单一任务。
+2. 开始前用 \`swarm-state.sh task-claim\` 认领任务。
+3. 修改文件、目录或服务前，用 \`swarm-state.sh lock-acquire\` 获取锁。
+4. 执行中保留关键命令、错误、测试结果和风险。
+5. 完成后用 \`swarm-state.sh task-done\` 写入结果。
+6. 汇报格式必须包含：状态、修改文件、验证结果、风险、下一步。
+
+## 禁止
+
+- 不修改无关文件。
+- 不绕过测试、lint、类型检查或用户指定门禁。
+- 不覆盖其他 worker 的工作。
+EOF
+    ;;
+  reviewer)
+    cat <<EOF
+# tmux AI 蜂群 Reviewer Prompt
+
+你是 tmux AI 蜂群的独立 reviewer。
+
+## 当前上下文
+
+- session: \`$session\`
+- swarm state dir: \`$swarm_dir\`
+- 审查目标: $task
+
+## 你的职责
+
+1. 读取 commander 汇总、worker 结果、snapshot、record 日志和 git diff。
+2. 优先寻找 correctness、越界修改、缺失测试、风险遗漏和文档不同步。
+3. 对每个问题给出文件、证据、影响和最小修复建议。
+4. 如果没有阻塞问题，明确说明剩余风险和建议补充验证。
+
+## 禁止
+
+- 不只做风格审查。
+- 不把 worker 自评当作事实。
+- 不在缺少证据时宣布通过。
+EOF
+    ;;
+  *)
+    die "unknown role: $role"
+    ;;
+esac