feat: skills - add auto-tmux shell completion

skills/auto-tmux/AGENTS.md

@@ -21,6 +21,7 @@ skills/auto-tmux/
 │   ├── swarm-assign.sh
 │   ├── swarm-health.sh
 │   ├── record-summary.sh
+│   ├── completion.bash
 │   ├── safety-check.sh
 │   ├── render-swarm-prompt.sh
 │   ├── swarm-dispatch.sh
@@ -53,6 +54,7 @@ skills/auto-tmux/
 - `scripts/swarm-assign.sh` 是分配建议层，将 ready task 轮询映射到 worker pane。
 - `scripts/swarm-health.sh` 是健康检查层，汇总 tmux 和 swarm state 的只读报告包。
 - `scripts/record-summary.sh` 是复盘摘要层，将 pane 录制日志整理为 Markdown。
+- `scripts/completion.bash` 是本地补全层，补全 `auto-tmux.sh` 与 `swarm-state.sh`。
 - `scripts/safety-check.sh` 是安全预检层，检查待发送 payload 的危险命令、敏感信息和大小。
 - `scripts/render-swarm-prompt.sh` 是提示词渲染层，生成 commander/worker/reviewer 协议文本。
 - `scripts/swarm-dispatch.sh` 是提示词下发层，默认写文件，显式 `--send` 后才发送到 pane。
@@ -65,4 +67,4 @@ skills/auto-tmux/
 - 上游来源：`tools/external/.tmux` 与 `tools/external/tmux`。
 - 下游使用：`SKILL.md` 和 `references/` 中的命令示例。
 - 验证入口：`skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict`。
-- 脚本验证：`skills/auto-tmux/scripts/validate-auto-tmux.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/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。
+- 脚本验证：`skills/auto-tmux/scripts/validate-auto-tmux.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/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh`、`skills/auto-tmux/scripts/auto-tmux-smoke-test.sh`。

skills/auto-tmux/README.md

@@ -28,6 +28,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
+bash -n skills/auto-tmux/scripts/completion.bash
 bash -n skills/auto-tmux/scripts/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 bash -n skills/auto-tmux/scripts/swarm-dispatch.sh

skills/auto-tmux/SKILL.md

@@ -42,6 +42,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
+bash -n skills/auto-tmux/scripts/completion.bash
 bash -n skills/auto-tmux/scripts/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 bash -n skills/auto-tmux/scripts/swarm-dispatch.sh
@@ -180,6 +181,7 @@ skills/auto-tmux/scripts/swarm-state.sh report --dir /tmp/ai_swarm
 
 **脚本端到端自测**
 ```bash
+source skills/auto-tmux/scripts/completion.bash
 skills/auto-tmux/scripts/auto-tmux-smoke-test.sh
 skills/auto-tmux/scripts/validate-auto-tmux.sh
 ```
@@ -271,6 +273,7 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 - `scripts/swarm-assign.sh`: 根据 ready tasks 和 worker pane 生成只读分配建议
 - `scripts/swarm-health.sh`: 汇总 tmux 与 swarm state 的只读健康检查报告包
 - `scripts/record-summary.sh`: 汇总 pane 录制日志并生成复盘摘要
+- `scripts/completion.bash`: Bash completion，补全 `auto-tmux.sh` 与 `swarm-state.sh`
 - `scripts/safety-check.sh`: 发送/粘贴/分发前检查危险命令、敏感信息和过大 payload
 - `scripts/render-swarm-prompt.sh`: commander/worker/reviewer 提示词渲染脚本
 - `scripts/swarm-dispatch.sh`: 渲染并可选下发 commander/worker/reviewer 提示词
@@ -294,6 +297,6 @@ skills/auto-tmux/scripts/swarm-dispatch.sh --role worker --target <session>:<win
 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`、`bash -n skills/auto-tmux/scripts/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh` 与 `bash -n skills/auto-tmux/scripts/validate-auto-tmux.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/swarm-brief.sh`、`bash -n skills/auto-tmux/scripts/swarm-watch.sh`、`bash -n skills/auto-tmux/scripts/swarm-archive.sh`、`bash -n skills/auto-tmux/scripts/swarm-board.sh`、`bash -n skills/auto-tmux/scripts/swarm-assign.sh`、`bash -n skills/auto-tmux/scripts/swarm-health.sh`、`bash -n skills/auto-tmux/scripts/record-summary.sh`、`bash -n skills/auto-tmux/scripts/completion.bash`、`bash -n skills/auto-tmux/scripts/safety-check.sh`、`bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh`、`bash -n skills/auto-tmux/scripts/swarm-dispatch.sh` 与 `bash -n skills/auto-tmux/scripts/validate-auto-tmux.sh` 通过。
 8. `skills/auto-tmux/scripts/auto-tmux-smoke-test.sh` 通过或在无 tmux 环境下明确跳过。
 9. 运行 `skills/auto-tmux/scripts/validate-auto-tmux.sh` 和 `skills/auto-skill/scripts/validate-skill.sh skills/auto-tmux --strict` 通过。

skills/auto-tmux/references/automation.md

@@ -37,6 +37,7 @@
 | `swarm-assign.sh` | 生成 ready task 到 worker pane 的分配建议 | 只读，不 claim，不发送 |
 | `swarm-health.sh` | 汇总 tmux 与 swarm state 健康报告 | 只读，不自动修复 |
 | `record-summary.sh` | 汇总 pane 录制日志 | 只读，输出默认脱敏 |
+| `completion.bash` | Bash 子命令和常用参数补全 | 只定义 shell completion |
 | `swarm-dispatch.sh` | 渲染并可选下发提示词 | 默认只写文件，发送需 `--send` |
 | `validate-auto-tmux.sh` | 执行技能专属质量门禁 | 覆盖脚本、文档索引、strict 和 smoke |
 
@@ -262,6 +263,7 @@ bash -n skills/auto-tmux/scripts/swarm-board.sh
 bash -n skills/auto-tmux/scripts/swarm-assign.sh
 bash -n skills/auto-tmux/scripts/swarm-health.sh
 bash -n skills/auto-tmux/scripts/record-summary.sh
+bash -n skills/auto-tmux/scripts/completion.bash
 bash -n skills/auto-tmux/scripts/safety-check.sh
 bash -n skills/auto-tmux/scripts/render-swarm-prompt.sh
 bash -n skills/auto-tmux/scripts/swarm-dispatch.sh

skills/auto-tmux/references/iteration-roadmap.md

@@ -29,14 +29,14 @@
 | 21 | `d8e7d31` | 依赖领取一致性 | `task-next` 尊重 `blocked-by` |
 | 22 | `cc69865` | worker 分配 | `swarm-assign.sh` |
 | 23 | `004d942` | replay 审计 | `record-summary.sh` |
-| 24 | `本轮` | 健康检查 | `swarm-health.sh` |
+| 24 | `16afbee` | 健康检查 | `swarm-health.sh` |
+| 25 | `本轮` | shell completion | `completion.bash` |
 
 ## 后续候选方向
 
 | 优先级 | 方向 | 说明 |
 |:---|:---|:---|
 | P3 | 远程 session | SSH 场景下的只读拓扑和安全边界 |
-| P3 | shell completion | 为常用子命令生成补全脚本 |
 
 ## 每轮验收清单
 

skills/auto-tmux/scripts/AGENTS.md

@@ -17,6 +17,7 @@ scripts/
 ├── swarm-assign.sh # 生成 ready task 到 worker pane 的分配建议
 ├── swarm-health.sh # 汇总只读健康检查报告包
 ├── record-summary.sh # 汇总 pipe-pane 录制日志
+├── completion.bash # Bash completion
 ├── safety-check.sh # 发送/粘贴/分发前的 payload 安全预检
 ├── render-swarm-prompt.sh # commander/worker/reviewer 提示词渲染
 ├── swarm-dispatch.sh # 渲染并可选下发蜂群提示词
@@ -40,6 +41,7 @@ scripts/
 - 分配建议脚本只读任务和 pane 拓扑，不 claim 任务、不发送 prompt。
 - 健康检查脚本只读 tmux 与 swarm state，失败项写入报告，不做自动修复。
 - 录制摘要脚本只读 record 日志，输出默认脱敏，不修改日志源文件。
+- completion 文件只能定义 shell completion，不执行 tmux 写操作。
 - 安全预检脚本只能读取文本或文件，不控制 tmux，不写状态目录。
 - 状态脚本只能写入显式状态目录，不保存密钥、Token、密码或私密项目内容。
 - 自测脚本必须创建独立临时 tmux session，并在退出时清理。

skills/auto-tmux/scripts/README.md

@@ -13,6 +13,7 @@
 - [`swarm-assign.sh`](./swarm-assign.sh) - 根据 ready tasks 和 worker pane 生成只读分配建议。
 - [`swarm-health.sh`](./swarm-health.sh) - 汇总 doctor、topology、scan、validate、metrics、board 和 assign。
 - [`record-summary.sh`](./record-summary.sh) - 汇总 `record start` 产生的 pane 日志，生成复盘摘要。
+- [`completion.bash`](./completion.bash) - Bash completion，补全 `auto-tmux.sh` 和 `swarm-state.sh` 子命令。
 - [`safety-check.sh`](./safety-check.sh) - 发送、粘贴或分发前检查危险命令、敏感信息和过大 payload。
 - [`render-swarm-prompt.sh`](./render-swarm-prompt.sh) - commander、worker、reviewer 提示词渲染。
 - [`swarm-dispatch.sh`](./swarm-dispatch.sh) - 渲染提示词并可选发送到指定 pane，默认只写文件。
@@ -74,6 +75,9 @@ skills/auto-tmux/scripts/swarm-health.sh --session ai-hub --swarm-dir /tmp/ai_sw
 # 汇总 pane 录制日志
 skills/auto-tmux/scripts/record-summary.sh --dir /tmp/auto-tmux-records --out /tmp/auto-tmux-record-summary.md
 
+# 启用当前 shell 的补全
+source skills/auto-tmux/scripts/completion.bash
+
 # 初始化蜂群状态并添加任务
 skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/ai_swarm
 skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"

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

@@ -13,6 +13,7 @@ SWARM_BOARD="$SCRIPT_DIR/swarm-board.sh"
 SWARM_ASSIGN="$SCRIPT_DIR/swarm-assign.sh"
 SWARM_HEALTH="$SCRIPT_DIR/swarm-health.sh"
 RECORD_SUMMARY="$SCRIPT_DIR/record-summary.sh"
+COMPLETION="$SCRIPT_DIR/completion.bash"
 SAFETY_CHECK="$SCRIPT_DIR/safety-check.sh"
 SWARM_DISPATCH="$SCRIPT_DIR/swarm-dispatch.sh"
 SESSION="auto-tmux-smoke-$$"
@@ -52,6 +53,7 @@ bash -n "$SWARM_BOARD"
 bash -n "$SWARM_ASSIGN"
 bash -n "$SWARM_HEALTH"
 bash -n "$RECORD_SUMMARY"
+bash -n "$COMPLETION"
 bash -n "$SAFETY_CHECK"
 bash -n "$SWARM_DISPATCH"
 

skills/auto-tmux/scripts/completion.bash

@@ -0,0 +1,57 @@
+# Bash completion for auto-tmux helper scripts.
+
+_auto_tmux_complete_words() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local prev="${COMP_WORDS[COMP_CWORD-1]}"
+  local subcommands="help doctor topology inspect capture send paste broadcast rescue scan record snapshot hub cleanup wait"
+  local common_opts="-h --help --session -t --target -n --lines --dir --out --pattern --dry-run --force"
+
+  if [[ "$COMP_CWORD" -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "$subcommands" -- "$cur"))
+    return 0
+  fi
+
+  case "$prev" in
+    -t|--target)
+      if command -v tmux >/dev/null 2>&1; then
+        local targets
+        targets="$(tmux list-panes -a -F '#S:#{window_index}.#{pane_index}' 2>/dev/null || true)"
+        COMPREPLY=($(compgen -W "$targets" -- "$cur"))
+      fi
+      ;;
+    --session)
+      if command -v tmux >/dev/null 2>&1; then
+        local sessions
+        sessions="$(tmux list-sessions -F '#S' 2>/dev/null || true)"
+        COMPREPLY=($(compgen -W "$sessions" -- "$cur"))
+      fi
+      ;;
+    --dir|--out)
+      COMPREPLY=($(compgen -d -- "$cur"))
+      ;;
+    *)
+      COMPREPLY=($(compgen -W "$common_opts" -- "$cur"))
+      ;;
+  esac
+}
+
+_swarm_state_complete_words() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local subcommands="init log status task-add task-import task-list task-depend task-ready task-next task-claim task-done task-block task-fail task-reopen lock-acquire lock-release lock-list lock-prune report metrics validate"
+  local common_opts="-h --help --dir --id --text --file --prefix --status --owner --target --message --blocked-by --result --reason --name --force --older-than --dry-run"
+
+  if [[ "$COMP_CWORD" -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "$subcommands" -- "$cur"))
+    return 0
+  fi
+
+  COMPREPLY=($(compgen -W "$common_opts" -- "$cur"))
+}
+
+complete -F _auto_tmux_complete_words auto-tmux.sh
+complete -F _auto_tmux_complete_words ./auto-tmux.sh
+complete -F _auto_tmux_complete_words skills/auto-tmux/scripts/auto-tmux.sh
+
+complete -F _swarm_state_complete_words swarm-state.sh
+complete -F _swarm_state_complete_words ./swarm-state.sh
+complete -F _swarm_state_complete_words skills/auto-tmux/scripts/swarm-state.sh

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

@@ -97,6 +97,9 @@ for script in "${scripts[@]}"; do
   run_gate "bash syntax: ${script##*/}" bash -n "$script"
 done
 
+[[ -f "$script_dir/completion.bash" ]] && pass "completion file: skills/auto-tmux/scripts/completion.bash" || fail "missing completion.bash"
+run_gate "bash syntax: completion.bash" bash -n "$script_dir/completion.bash"
+
 run_gate "auto-tmux help" "$script_dir/auto-tmux.sh" help
 run_gate "swarm-state help" "$script_dir/swarm-state.sh" help
 run_gate "swarm-brief help" "$script_dir/swarm-brief.sh" --help
@@ -124,6 +127,7 @@ require_contains "$skill_dir/SKILL.md" "scripts/swarm-board.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-assign.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-health.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/record-summary.sh"
+require_contains "$skill_dir/SKILL.md" "scripts/completion.bash"
 require_contains "$skill_dir/SKILL.md" "scripts/safety-check.sh"
 require_contains "$skill_dir/SKILL.md" "scripts/swarm-dispatch.sh"
 require_contains "$skill_dir/references/index.md" "automation.md"
@@ -138,6 +142,7 @@ require_contains "$script_dir/README.md" "swarm-board.sh"
 require_contains "$script_dir/README.md" "swarm-assign.sh"
 require_contains "$script_dir/README.md" "swarm-health.sh"
 require_contains "$script_dir/README.md" "record-summary.sh"
+require_contains "$script_dir/README.md" "completion.bash"
 require_contains "$script_dir/README.md" "safety-check.sh"
 require_contains "$script_dir/AGENTS.md" "validate-auto-tmux.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-dispatch.sh"
@@ -147,6 +152,7 @@ require_contains "$script_dir/AGENTS.md" "swarm-board.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-assign.sh"
 require_contains "$script_dir/AGENTS.md" "swarm-health.sh"
 require_contains "$script_dir/AGENTS.md" "record-summary.sh"
+require_contains "$script_dir/AGENTS.md" "completion.bash"
 require_contains "$script_dir/AGENTS.md" "safety-check.sh"
 
 if [[ -x "$repo_root/skills/auto-skill/scripts/validate-skill.sh" ]]; then