| name | claude-agent-workflow-validation |
| description | This skill should be used automatically when the user asks for strict binary-side validation of Agent, Workflow, /deep-research, /code-review, task lifecycle, foreground/background continuation, completion notifications, scheduling, slash-command dispatch, or official/local terminal parity using the latest built-claude and stable scripted tmux pane evidence. It also triggers for Chinese requests mentioning Agent/Workflow 验收、调度、任务生命周期、前后台续跑、通知、并发隔离 or 官方对照. Never substitute parent-assistant Agent/Workflow/Skill/Task results. Use claude-runtime-debug for quick single-process diagnosis, claude-network-debug for proxy/MITM, and claude-source-binary-analysis for static analysis. |
| version | 0.3.0 |
tmux CLI Agent/Workflow 验收
通过可审计脚本驱动 tmux 中的最新 built-claude，验收只存在于 Claude CLI 进程内的 slash command、Agent、Workflow、任务调度和 TUI 行为。涉及这些行为的实现、修复、回归或验收时自动使用，无须用户再次明确要求 tmux。
不可违反的证据边界
- 被测对象是 tmux 中运行的当前工作区
built-claude。
- assistant-side
Agent、Workflow、Skill、Task/Run 查询或其他同名工具不能作为 binary-side 证据。
- parent-side Task ID、Run ID、Agent 数、token 和报告不得写入 binary-side 结果表。
- parent-side 成功不能作为 tmux 验收失败后的替代证据。
- assistant-side 工具只用于构建、驱动 tmux、捕获 pane、读取 debug log、检查文件和保存证据。
- slash command 必须输入
built-claude stdin，不能作为 shell 命令执行。
- 每份 pane、debug log、输入、Task ID 和 Run ID 必须来自同一次 tmux 运行，禁止拼接不同重试的成功片段。
- 如误启动 parent-side 同名工具，立即停止该调用，从正式结果中排除，并在限制中披露；不得中止仍有效的 binary-side session。
验收入口矩阵
| 目标 | 必须使用的 binary-side 入口 | 禁止替代 |
|---|
| slash command | tmux 向 CLI stdin 输入 /... | shell 执行、parent Skill |
| Agent | 让 tmux 中的 built-claude 实际调用 Agent tool | parent Agent tool |
| Workflow | 让 tmux 中的 built-claude 实际调用 Workflow/WorkflowTool | parent Workflow tool |
| deep-research | CLI stdin 输入 /deep-research ... | parent 同名 skill/tool |
| code-review | CLI stdin 输入 /code-review ... | parent 同名 skill/tool |
无法在 binary 中触发的入口必须报告 not covered，不能用 parent-side 工具补足。
强制准备流程
-
从仓库根目录读取 Makefile，确认 VERSION、构建命令和产物路径。
-
记录 build 前状态：
git status --short
-
涉及当前源码的 CLI、Agent、Workflow、slash command 或 TUI 验收时，本轮必须运行：
make build
“最新 built-claude”指本轮验收开始后由当前工作区源码成功构建的产物。构建失败时不得回退旧 binary 并声称通过。仅在用户明确指定验证既有制品时可不重建，报告必须注明。
-
记录 build 后、CLI 运行前状态，以及：
- 仓库根目录绝对路径；
Makefile 版本；built-claude 绝对路径；stat 时间和 SHA-256；- 非敏感环境变量、CLI flags、终端尺寸。
-
为每次运行创建唯一 session、证据目录、HOME、CLAUDE_CONFIG_DIR 和 XDG state root。每个并行目标必须隔离 settings/cache/side effects。启动前准备已认证的一次性 config fixture，或把最小 auth source 以只读方式映射到隔离 config；禁止把凭证复制进 evidence directory、打印凭证或改写共享 auth。无法安全提供认证时，readiness 应失败并报告阻塞。建议：
/tmp/tmux-cli-validation/<timestamp>-<target>-<pid>/
-
默认保留 tmux session、pane、驱动脚本、stdout/stderr 和 debug log。未经用户要求不删除。
-
默认按目标串行验收：完成并记录当前目标终态后再启动下一个。仅两类情况允许并行：一是用户明确要求并行且目标相互独立；二是验收对象本身就是并发、隔离或竞态行为。其他情况一律串行。
-
每个目标结束后必须立即更新对应的结果表行，记录 binary-side 入口、实际 Agent/Workflow 进度、终态、session、pane/debug 证据路径和限制；未完成目标不得标记为 passed。
必须脚本驱动
不得以人工 attach 后键入命令作为主要验收路径。必须由脚本执行：
- 创建唯一证据目录；
- 启动 tmux；
- 等待 CLI prompt ready；
- 保存 ready pane；
- literal 发送输入；
- 保存 submitted/running/terminal pane；
- 检查 session、pane process、超时和终态；
- 保存脚本 stdout/stderr 和退出状态。
人工 attach 只能辅助观察。
启动
使用仓库和 binary 绝对路径，并固定 cwd：
使用 skill 内固定 launcher，并让 tmux 只接收一个 shell-command 路径。运行参数通过 tmux session environment 注入，避免把用户输入或动态路径拼成 shell command string：
config_dir="/tmp/claude-validation-config/$run_id"
home_dir="/tmp/claude-validation-home/$run_id"
mkdir -p "$config_dir" "$home_dir"
tmux new-session -d -s "$session" -c "$repo_root" -x 200 -y 60 \
-e "CC_VALIDATION_REPO_ROOT=$repo_root" \
-e "CC_VALIDATION_EVIDENCE_DIR=$evidence_dir" \
-e "CC_VALIDATION_CONFIG_DIR=$config_dir" \
-e "CC_VALIDATION_HOME=$home_dir" \
"$repo_root/.claude/skills/claude-agent-workflow-validation/scripts/launch-built-claude.sh"
target="$session:0.0"
printf '%s\n' "$target" > "$evidence_dir/pane-target.txt"
若本机 tmux 不支持 new-session -e，不要退回动态 shell command；改为在 evidence directory 生成权限为 0700 的每次运行 wrapper，并让 tmux 只执行该 wrapper 路径。
session 名应包含项目、目标、时间戳和随机/PID 后缀。创建前确认不存在，不通过 kill-session 解决重名。session 存在不代表 binary 已启动，必须从 pane 和 pane process 核对。
Readiness
发送输入前强制轮询 pane，确认 CLI prompt 已出现；超时则保存 pane/debug 并停止该次验收，不得盲目发送。
精确输入
将完整输入保存到证据目录，使用 literal 模式，Enter 分开发送：
tmux send-keys -t "$target" -l -- "$exact_input"
tmux send-keys -t "$target" Enter
不要把未经转义的用户输入直接拼接进 shell 命令。
slash command 任务设计
示例：
/deep-research <具体、只读、可核验的研究任务>
/code-review <具体、只读、可核验的审查任务>
输入应明确：
- 研究或审查哪些代码和行为；
- 是否允许修改文件；
- 正常使用命令自身的 Agent/Workflow 调度；
- 输出文件和行号；
- 不修改、不提交、不 push、不创建 worktree，除非目标本身必须测试这些行为。
Agent/Workflow 可能产生大量网络调用和 token。限定范围和终止条件，不进行无限重试或无界 fan-out。
并行验收
多个独立命令使用多个独立 tmux/built-claude 进程并行验收，不要塞入同一 CLI session。每个 session 必须使用独立：
- session/pane target；
- evidence directory；
- input file；
- debug log；
- marker；
- Task ID / Run ID。
记录每个命令的入口、计划/实际 Agent 数、token、duration、状态和最终报告。检查并行运行之间没有 ID 或证据串线。
调度检查矩阵
- 入口解析
- pane 出现预期
WorkflowTool(...)、Workflow(...) 或 Agent(...)；
- 没有
Unknown command、错误入口或脚本语法错误。
- Agent fan-out
- 状态从
0/N agents 推进；
- completed count 和 token 更新；
- 并行 workflow 状态相互独立。
- 后台生命周期
- 父 CLI 显示 background workflow running 并恢复可交互；
- 完成通知回到同一父会话；
- terminal 明确变为
done、failed 或 stopped。
- 修复相关路径
- foreground → background 不重启 Agent stream；
- summarizer handoff 不重复启动，terminal 只停止一次；
- completed 后 classifier/worktree 失败不改报 failed；
- failed/killed 通知保留 usage；
- notification retry 不永久丢失且不产生竞态重复；
- warnings 数组和展示文本去重一致。
- 隔离与约束
- nested Agent、worktree、Workflow 内 Agent 正常；
- worktree terminal 后完成清理；
- CLI 运行前后 Git 可见状态没有非预期变化。
普通 CLI 无法稳定触发的故障路径必须标为“自动化测试覆盖”“受控 fault injection”或 not covered，不能假称由普通交互验收覆盖。
Assertion 与证据矩阵
每个结论先声明 assertion，再绑定足以判定它的证据：
| Assertion 类型 | 必要证据 | 不足时的 verdict |
|---|
| CLI 入口已接收 | exact input + submitted pane + 无入口解析错误 | failed 或 not covered |
| Agent/Workflow 已启动 | running pane + 稳定 Task/Run/Agent ID | not covered |
| 内部 routing/handoff/ownership 正确 | 同次运行 debug marker 检索结果 + 关联 ID | not covered |
| 用户可见终态正常 | terminal pane + prompt 恢复 + process/session 状态 | running / failed / stopped |
| 无非预期仓库副作用 | CLI 前后 Git 状态对照 | not covered |
每条 assertion 必须记录：assertion_id、subject、predicate、required_evidence、observed_evidence_paths、runtime_state、validation_verdict 和 reason_if_not_passed。Runtime state 使用 running | done | failed | stopped；validation verdict 使用 passed | running | failed | stopped | not covered。不得把 runtime 的 done 直接等同于 validation passed。
pane、debug 与终态证据
保存多个原始 pane 快照：
01-ready-pane.txt
02-submitted-pane.txt
03-running-pane.txt
04-terminal-pane.txt
优先捕获完整 history；若另存 stripped/normalized 版本，必须保留原始文件并记录转换方式。
- pane 证明用户可见 CLI/TUI 行为。
- debug log 是 Agent/Workflow 路由、handoff、summary ownership、notification 等内部流程的必要证据。
- 两者通过时间戳、session、输入、Task ID 和 Run ID 关联。
- debug log 搜索不到内部流程 marker 时，不得把该内部路径判为通过；只能报告 UI 观察和证据限制。
- 保存 marker 检索 pattern、命令和结果到 evidence directory，例如
debug-marker-search.txt；不得声称 debug log 包含未实际检索到的事件。
终态使用组合证据，而非单一 glyph：
- workflow/Agent 名或稳定 ID；
running → done/failed/stopped 迁移；- 对应 debug 事件；
- 父 CLI 恢复可交互；
- tmux session/pane process 状态；
- 必要时发送无副作用 marker 确认 prompt 恢复。
等待脚本必须有最大时限和 poll interval，并检查 session 消失或进程提前退出。timeout 后仍运行应报告 running，不是 failed。
不要只匹配 prompt 中可能出现的 failed、completed 或 marker；不要依赖易受宽度和 ANSI 影响的完整渲染行。优先使用 case 或结构化状态组合，避免 shell 不兼容的复杂条件。
Git 状态基线
记录三个基线：
- build 前；
- build 后、CLI 启动前；
- CLI 验收结束后。
第 2 与第 3 次比较用于判断被测只读 workflow 是否修改 Git 可见文件；构建产生的预期变化单独报告。git status --short 只证明 Git 可见变化，不代表所有 ignored 文件。
失败与重试
- build、tmux 启动、readiness、入口解析失败后，不得继续套用旧证据。
- 同一 session 内不得重复发送同一 slash command。
- 可用相同 exact input 重试，但必须创建新的 session、evidence directory 和 config directory，并说明原因。
- timeout 或长工作流仍运行时保留 session，报告
X/N agents、token 和 elapsed。
- 不得将
running 报成完成。
四个 skills 的职能边界
| Skill | 负责 | 不负责 |
|---|
claude-source-binary-analysis | 静态源码/二进制分析、Bun section、反混淆、symbol/section、只读 Frida、离线 checksum | CLI 运行、proxy/MITM、正式 tmux 验收 |
claude-runtime-debug | --print、stdout/stderr/exit code、debug flags/log、settings/env、单进程 InteractiveTerminal smoke diagnosis | 网络协议调试、Agent/Workflow 正式验收 |
claude-network-debug | proxy/OAuth/network、SSE/WebSocket、CONNECT、MITM/CCH wire summary | 静态提取、Agent/Workflow 生命周期验收 |
claude-agent-workflow-validation | 最新 binary、scripted tmux、stdin dispatch、pane/TUI、Agent/Workflow、/deep-research、/code-review、task lifecycle、notification/scheduling | 通用网络调试、二进制反混淆 |
本 skill 是严格 scripted tmux 驱动、证据关联和终态判定的唯一权威。可引用 claude-runtime-debug 的 debug flag 与脱敏规则，但不得让其 quick InteractiveTerminal 流程替代正式验收。详细配方见 references/interactive-tmux-validation.md。
若要求 official parity，使用仓库根目录 official-claude，为 official/local 分别创建独立 launcher、tmux session、evidence directory、HOME 和 writable config/cache。两侧 settings 内容、auth state、model env、prompt 和 terminal dimensions 必须等价；如 auth 只能共享，记录只读共享边界。运行前分别记录两侧 binary 的绝对路径、version、mtime、SHA-256、flags、model env、terminal size 和 config roots。官方成功不能证明本地通过。
报告格式
## 范围
- Binary/path/version/hash:
- tmux sessions:
- Evidence directories:
- Exact inputs:
## Assertions
| ID | Subject/predicate | Required evidence | Observed paths | Runtime state | Validation verdict / reason |
|---|---|---|---|---|---|
## 调度结果
| 命令 | binary-side 入口 | Agent 进度 | runtime state | validation verdict | pane/debug 证据 |
|---|---|---:|---|---|---|
## 修复路径检查
1. ...
## 发现
1. ...
## 未完成或限制
- ...
## Git 状态对照
- build 前：
- CLI 前：
- CLI 后：
状态必须严格使用 passed、running、failed、stopped 或 not covered。
