orchestrix-guide
v2.0.0Orchestrix multi-agent workflow guide for OpenClaw. Defines two operational phases: (1) Planning Phase — sequential agent orchestration in a single tmux window from project-brief through PRD, UX spec, architecture, to PO shard; (2) Development Phase — automated multi-window tmux collaboration via HA...
Sourced from ClawHub,
Authored by dorayo
Installation
Please help me install the skill `orchestrix-guide` from SkillHub official store.
npx skills add dorayo/orchestrix-guide
Orchestrix Guide — OpenClaw 操作手册
本文档是 OpenClaw 操控 Orchestrix Agent 的唯一操作手册。 严格按照本文档的阶段和协议执行，不得跳步。
一、架构与原理
OpenClaw (自动化控制层，接收用户指令: Telegram / WhatsApp / Slack)
↓
tmux (终端复用层) ← OpenClaw 通过 tmux send-keys 发送命令
↓
Claude Code - cc (AI 编码助手，交互式 CLI，无 HTTP API)
↓ 通过 /o 激活 Agent
Orchestrix MCP Server → 返回 Agent 配置和工作流
↓
Claude Code 执行 Agent 工作流 → 输出文档/代码/HANDOFF
关键约束：Claude Code (cc) 只接受终端标准输入。OpenClaw 唯一的操控方式是 tmux send-keys。
二、tmux 操作协议（铁律）
2.1 指令发送三步序列
每次向 Agent 发送任务前，必须完整执行此三步。不得跳过任何一步。
WIN="{session}:{window}"
# Step 1: 清空上下文（防止角色残留和混乱）
tmux send-keys -t $WIN "/clear" Enter
sleep 2
# Step 2: 激活目标 Agent
tmux send-keys -t $WIN "/o {agent}" Enter
sleep 3
# Step 3: 发送任务指令
tmux send-keys -t $WIN "*{command}" Enter
唯一例外：同一 Agent 的连续对话中追加指令（不切换 Agent），可省略 Step 1-2。
2.2 等待时间参考
| 操作 | 等待时间 | 原因 |
|---|---|---|
cc 启动后 |
5s | 等待 Claude Code 初始化 |
/clear 后 |
2s | 等待上下文清空 |
/o {agent} 后 |
3s | 等待 Agent 加载和问候输出 |
*command 后 |
按任务检测 | 见下方完成检测策略 |
2.3 任务完成检测（四级优先级）
Agent 任务执行时间不确定，OpenClaw 必须准确判断任务是否完成。按优先级依次尝试：
P0：检测 HANDOFF 指令（最高优先级）
tmux capture-pane -t {session}:{window} -p | grep -q "🎯 HANDOFF TO"
适用场景：tmux 多窗口模式下所有任务。检测到即表示当前 Agent 已完成。
P1：检测预期输出文件
# 记录任务开始前时间戳
BEFORE=$(date +%s)
# ... 发送命令后轮询 ...
find ~/Codes/{project-name}/docs/ -newer /tmp/task-start-marker -type f | head -1
适用任务：*create-doc *、*draft、*shard、*develop-story（有 git commit）等有文件产出的任务。
P2：检测终端完成标志
# Claude Code 执行完毕后显示 "Xxxed for <duration>"（如 "Worked for 33s"）
tmux capture-pane -t {session}:{window} -p | grep -qE '[A-Z][a-z]+ed for'
适用场景：所有任务。可作为 P1 的辅助确认。
P3：终端内容稳定性（兜底）
PREV_HASH=""
STABLE_COUNT=0
while [ $STABLE_COUNT -lt 5 ]; do
HASH=$(tmux capture-pane -t {session}:{window} -p | md5)
if [ "$HASH" = "$PREV_HASH" ]; then
STABLE_COUNT=$((STABLE_COUNT + 1))
else
STABLE_COUNT=0
fi
PREV_HASH=$HASH
sleep 10
done
连续 5 次以上 hash 不变才判定完成，防止 Agent 思考间隙被误判。
检测优先级总结
| 优先级 | 方法 | 可靠性 |
|---|---|---|
| P0 | HANDOFF 指令 | 最高（仅多窗口模式） |
| P1 | 预期输出文件 | 高 |
| P2 | 终端完成标志 [A-Z][a-z]+ed for |
高 |
| P3 | 终端内容 hash 稳定 | 中（兜底） |
建议组合：规划阶段用 P1 + P2 双重确认；开发阶段用 P0 + P2 为主。
三、全局流程总览
一个 Orchestrix 项目的完整生命周期分为两大阶段。
┌─────────────────────────────────────────────────────────┐
│ Phase A: 规划阶段 │
│ （单窗口模式，逐个切换 Agent） │
│ │
│ 前提条件: 项目已通过 /create-project 创建 │
│ docs/project-brief.md 已存在（初版） │
│ │
│ Step 0: Analyst → *create-doc project-brief (可选深化) │
│ Step 1: PM → *create-doc prd │
│ Step 2: UX Expert → *create-doc front-end-spec (可选) │
│ Step 3: Architect → *create-doc fullstack-architecture │
│ Step 4: PO → *execute-checklist + *shard │
│ │
│ ✅ 规划完成标志: PO *shard 执行完毕 │
└─────────────────────┬───────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Phase B: 开发阶段 │
│ （多窗口模式，HANDOFF 自动协作） │
│ │
│ 启动: bash .orchestrix-core/scripts/start-orchestrix.sh │
│ │
│ SM *draft → Architect *review → Dev *develop-story │
│ → QA *review → SM *draft (下一个) → ... 循环 │
│ │
│ ✅ 开发完成标志: 所有 Story 通过 QA 审查 │
└─────────────────────────────────────────────────────────┘
四、Phase A：规划阶段（单窗口模式）
规划阶段在一个 tmux 窗口中完成，通过逐个切换 Agent 生成全套规划文档。
4.0 启动 tmux 会话
SESSION="orchestrix-planning"
PROJECT_DIR=~/Codes/{project-name}
# 创建 session 并启动 Claude Code
tmux new-session -d -s $SESSION -c $PROJECT_DIR
tmux send-keys -t $SESSION:0 "cc" Enter
sleep 5
4.1 Step 0: Analyst — 深化项目简报（可选）
此步骤可选。
docs/project-brief.md已由/create-project生成初版（含问题陈述、目标用户、MVP 功能、技术栈），PM 可直接使用。 Analyst 的作用是在初版基础上深化（加市场调研、竞品分析），适合对项目背景需要更深入了解的场景。
WIN="$SESSION:0"
tmux send-keys -t $WIN "/o analyst" Enter
sleep 3
tmux send-keys -t $WIN "*create-doc project-brief" Enter
# 等待完成（P1: 检查 docs/project-brief.md 更新时间 + P2: 终端完成标志）
预期产出：docs/project-brief.md（深化版）
4.2 Step 1: PM — 生成 PRD
这是规划阶段的必要起点。 PM 基于已有的
docs/project-brief.md（无论初版还是深化版）生成产品需求文档。
# 如果前面执行了 Step 0，需要先 /clear；如果直接从 Step 1 开始，这是第一条命令
tmux send-keys -t $WIN "/clear" Enter
sleep 2
tmux send-keys -t $WIN "/o pm" Enter
sleep 3
tmux send-keys -t $WIN "*create-doc prd" Enter
# 等待完成（P1: 检查 docs/prd/ 目录下新文件 + P2）
预期产出：docs/prd/*.md（产品需求文档）
4.3 Step 2: UX Expert — 前端规格（可选）
仅当项目有前端需求时执行。 纯后端/CLI 项目跳过此步。
tmux send-keys -t $WIN "/clear" Enter
sleep 2
tmux send-keys -t $WIN "/o ux-expert" Enter
sleep 3
tmux send-keys -t $WIN "*create-doc front-end-spec" Enter
# 等待完成（P1: 检查 docs/ 下前端规格文件 + P2）
预期产出：docs/front-end-spec*.md
4.4 Step 3: Architect — 架构文档
tmux send-keys -t $WIN "/clear" Enter
sleep 2
tmux send-keys -t $WIN "/o architect" Enter
sleep 3
tmux send-keys -t $WIN "*create-doc fullstack-architecture" Enter
# 等待完成（P1: 检查 docs/ 下架构文件 + P2）
预期产出：docs/architecture*.md
4.5 Step 4: PO — 验证一致性 + 分片
这是规划阶段的最后一步。PO 需要连续执行两个命令。
# 4a: PO 验证文档一致性
tmux send-keys -t $WIN "/clear" Enter
sleep 2
tmux send-keys -t $WIN "/o po" Enter
sleep 3
tmux send-keys -t $WIN "*execute-checklist po-master-validation" Enter
# 等待完成（P2: 终端完成标志）
# 4b: PO 分片文档（同一 Agent，无需 /clear）
tmux send-keys -t $WIN "*shard" Enter
# 等待完成（P1: 检查 .orchestrix-core/context/ 或 docs/ 下分片文件 + P2）
预期产出： - 验证报告 - 分片后的上下文文件（供开发阶段 Agent 消费）
4.6 规划完成
PO *shard 执行完毕后，规划阶段结束。销毁规划会话：
tmux kill-session -t $SESSION
此时项目 docs/ 目录应包含：
- project-brief.md — 深化后的项目简报
- prd/*.md — 产品需求文档
- front-end-spec*.md — 前端规格（如适用）
- architecture*.md — 架构文档
- 分片上下文文件
✅ 规划完成。可以进入 Phase B 开发阶段。
4.7 OpenClaw 完整执行脚本（规划阶段）
#!/bin/bash
# OpenClaw 规划阶段自动化脚本
# 用法: bash planning.sh {project-name} [--with-analyst]
# --with-analyst 先让 Analyst 深化项目简报（可选）
PROJECT_NAME="$1"
WITH_ANALYST="$2"
PROJECT_DIR=~/Codes/$PROJECT_NAME
SESSION="orchestrix-planning"
WIN="$SESSION:0"
# 检查项目和 project-brief 是否存在
if [ ! -f "$PROJECT_DIR/docs/project-brief.md" ]; then
echo "ERROR: $PROJECT_DIR/docs/project-brief.md not found. Run /create-project first."
exit 1
fi
# 启动 tmux + cc
tmux new-session -d -s $SESSION -c $PROJECT_DIR
tmux send-keys -t $WIN "cc" Enter
sleep 5
# --- Step 0: Analyst (可选) ---
if [ "$WITH_ANALYST" = "--with-analyst" ]; then
tmux send-keys -t $WIN "/o analyst" Enter
sleep 3
tmux send-keys -t $WIN "*create-doc project-brief" Enter
# → OpenClaw 在此等待任务完成（P1 + P2 检测）
tmux send-keys -t $WIN "/clear" Enter && sleep 2
fi
# --- Step 1: PM ---
tmux send-keys -t $WIN "/o pm" Enter && sleep 3
tmux send-keys -t $WIN "*create-doc prd" Enter
# → 等待完成
# --- Step 2: UX Expert (可选，根据项目技术栈判断) ---
# if [ "$HAS_FRONTEND" = "true" ]; then
# tmux send-keys -t $WIN "/clear" Enter && sleep 2
# tmux send-keys -t $WIN "/o ux-expert" Enter && sleep 3
# tmux send-keys -t $WIN "*create-doc front-end-spec" Enter
# # → 等待完成
# fi
# --- Step 3: Architect ---
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o architect" Enter && sleep 3
tmux send-keys -t $WIN "*create-doc fullstack-architecture" Enter
# → 等待完成
# --- Step 4: PO 验证 + 分片 ---
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o po" Enter && sleep 3
tmux send-keys -t $WIN "*execute-checklist po-master-validation" Enter
# → 等待完成
tmux send-keys -t $WIN "*shard" Enter
# → 等待完成
# 规划完成
echo "✅ Planning phase complete for $PROJECT_NAME"
echo "Next: cd $PROJECT_DIR && bash .orchestrix-core/scripts/start-orchestrix.sh"
tmux kill-session -t $SESSION
五、Phase B：开发阶段（多窗口自动化）
开发阶段通过 tmux 多窗口模式运行，4 个 Agent 通过 HANDOFF 自动协作，无需人工切换。
5.1 前提条件
- Phase A 规划阶段已完成（PO
*shard已执行） docs/目录下有完整的规划文档
5.2 启动
cd ~/Codes/{project-name}/
bash .orchestrix-core/scripts/start-orchestrix.sh
脚本自动完成：
1. 创建 tmux session：orchestrix-{repo-id}
2. 创建 4 个窗口，每个窗口启动 cc
3. 在每个窗口激活对应 Agent
4. 在 SM 窗口自动执行 *draft 开始第一个 Story
5.3 窗口布局
| 窗口 | Agent | 职责 |
|---|---|---|
0 |
Architect | 技术审查、架构守护 |
1 |
SM | Story 创建、流程编排 |
2 |
Dev | 代码实现 |
3 |
QA | 代码审查、质量验证 |
5.4 HANDOFF 自动协作流程
SM (窗口1) *draft → 创建 Story
↓ 🎯 HANDOFF TO architect: *review {story_id}
Architect (窗口0) → 技术审查
↓ 🎯 HANDOFF TO dev: *develop-story {story_id}
Dev (窗口2) → 编码实现
↓ 🎯 HANDOFF TO qa: *review {story_id}
QA (窗口3) → 代码审查
↓ 🎯 HANDOFF TO sm: *draft (下一个 Story)
SM (窗口1) → 创建下一个 Story
↓ ... 循环直到所有 Story 完成
handoff-detector.sh 自动完成：
- 扫描所有窗口终端输出，检测 🎯 HANDOFF TO {agent}: *{command}
- 将命令发送到目标 Agent 的 tmux 窗口
- 在源 Agent 窗口执行 /clear + 重新加载 Agent
- Hash 去重 + 原子锁防止重复处理
5.5 监控
# 实时查看 HANDOFF 日志
tail -f /tmp/orchestrix-{repo-id}-handoff.log
# 查看各窗口当前输出
tmux capture-pane -t orchestrix-{repo-id}:1 -p | tail -10 # SM
tmux capture-pane -t orchestrix-{repo-id}:2 -p | tail -10 # Dev
# 查看 Story 完成情况
ls ~/Codes/{project-name}/docs/stories/
# 查看 git 提交记录
cd ~/Codes/{project-name}/ && git log --oneline -10
5.6 异常处理
| 情况 | OpenClaw 操作 |
|---|---|
| Agent 卡住不输出 HANDOFF | tmux send-keys -t {session}:{window} "/clear" Enter → sleep 2 → /o {agent} |
| HANDOFF 没被检测到 | tail -20 /tmp/orchestrix-{repo-id}-handoff.log 排查 |
| 需要暂停 | tmux send-keys -t {session}:{window} C-c |
| 需要恢复 | tmux send-keys -t {session}:1 "*draft --continue" Enter |
| 需要完全停止 | tmux kill-session -t orchestrix-{repo-id} |
5.7 并行扩展窗口（可选）
当需要额外 Agent 并行工作时（如 UX Expert），可动态创建窗口：
SESSION="orchestrix-{repo-id}"
# 创建新窗口
tmux new-window -t $SESSION -c ~/Codes/{project-name}/
NEW_WIN=$(tmux list-windows -t $SESSION -F '#{window_index}' | tail -1)
# 启动 cc 并加载 Agent
tmux send-keys -t $SESSION:$NEW_WIN "cc" Enter
sleep 5
tmux send-keys -t $SESSION:$NEW_WIN "/o ux-expert" Enter
sleep 3
tmux send-keys -t $SESSION:$NEW_WIN '*create-doc front-end-spec' Enter
# 任务完成后销毁临时窗口
# tmux kill-window -t $SESSION:$NEW_WIN
注意：动态窗口不参与 HANDOFF 自动协作，需 OpenClaw 自行管理生命周期。
六、补充流程
6.1 Solo 开发模式
跳过 Story/QA 关卡，适用于小型独立项目或快速原型。
# 单窗口即可
tmux send-keys -t $WIN "/o dev" Enter && sleep 3
tmux send-keys -t $WIN '*solo "实现用户登录功能，支持邮箱和手机号"' Enter
Dev 自动完成：创建 Story → 编码 → 测试 → 提交。
6.2 Bug 修复
轻量修复（不需要 Story）：
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o dev" Enter && sleep 3
tmux send-keys -t $WIN '*quick-fix "登录页面在 Safari 下白屏"' Enter
正式修复（需要追踪）：
# SM 创建 bugfix Story
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o sm" Enter && sleep 3
tmux send-keys -t $WIN '*draft-bugfix "用户并发下单时库存出现负数"' Enter
# → 等待完成，获取 story_id
# Dev 开发修复
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o dev" Enter && sleep 3
tmux send-keys -t $WIN "*develop-story {bugfix_story_id}" Enter
# QA 验证
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o qa" Enter && sleep 3
tmux send-keys -t $WIN "*review {bugfix_story_id}" Enter
tmux send-keys -t $WIN "*finalize-commit {bugfix_story_id}" Enter
6.3 Epic 冒烟测试
当一个 Epic 下所有 Story 都通过 QA 审查后执行。
# 单窗口模式
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o qa" Enter && sleep 3
tmux send-keys -t $WIN "*smoke-test {epic_id}" Enter
# 多窗口模式（直接发到 QA 窗口）
tmux send-keys -t orchestrix-{repo-id}:3 "*smoke-test {epic_id}" Enter
如果冒烟测试发现问题 → 走 6.2 正式修复流程 → 再次冒烟测试。
6.4 新迭代（Iteration）
MVP 完成后，基于反馈启动新一轮迭代。
# Step 1: PM 生成 next-steps
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o pm" Enter && sleep 3
tmux send-keys -t $WIN "*start-iteration" Enter
# → 等待完成，产出 docs/prd/*next-steps.md
# Step 2: OpenClaw 读取 next-steps.md，解析 🎯 HANDOFF TO 块
# Step 3: 按文件中的 HANDOFF 顺序依次执行
# 通常顺序：ux-expert → architect → sm
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o ux-expert" Enter && sleep 3
tmux send-keys -t $WIN "{HANDOFF TO ux-expert 部分内容}" Enter
# → 等待完成
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o architect" Enter && sleep 3
tmux send-keys -t $WIN "{HANDOFF TO architect 部分内容}" Enter
# → 等待完成
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o sm" Enter && sleep 3
tmux send-keys -t $WIN "{HANDOFF TO sm 部分内容}" Enter
# → 等待完成
# Step 4: 启动多窗口自动化开发（同 Phase B）
cd ~/Codes/{project-name}/
bash .orchestrix-core/scripts/start-orchestrix.sh
6.5 需求变更管理
# 所有变更先经 PO 路由
tmux send-keys -t $WIN "/clear" Enter && sleep 2
tmux send-keys -t $WIN "/o po" Enter && sleep 3
tmux send-keys -t $WIN "*route-change" Enter
PO 根据变更类型自动路由：
- 需求/范围变更 → PM (*revise-prd)
- 技术/架构变更 → Architect (*resolve-change)
- 两者都涉及 → 先 PM 再 Architect
6.6 Brownfield（已有项目增强）
| 变更规模 | 推荐方式 |
|---|---|
| < 1h 快速修复 | /o dev → *quick-fix |
| < 4h 单功能 | /o sm → *draft |
| 4h-2d 小型增强 | /o sm → *draft（brownfield epic） |
| > 2d 大型增强 | 走完整 Phase A → Phase B 流程 |
对不熟悉的项目先摸底：/o architect → *document-project
七、Agent 命令速查表
规划阶段 Agent
| Agent | ID | 核心命令 | 产出 |
|---|---|---|---|
| Analyst | analyst |
*create-doc project-brief |
docs/project-brief.md |
| PM | pm |
*create-doc prd, *revise-prd, *start-iteration |
docs/prd/*.md |
| UX Expert | ux-expert |
*create-doc front-end-spec |
docs/front-end-spec*.md |
| Architect | architect |
*create-doc fullstack-architecture, *document-project |
docs/architecture*.md |
| PO | po |
*execute-checklist po-master-validation, *shard |
验证报告 + 分片文件 |
开发阶段 Agent
| Agent | ID | 核心命令 | 产出 |
|---|---|---|---|
| SM | sm |
*draft, *draft-bugfix {bug} |
docs/stories/*.md |
| Architect | architect |
*review {story_id} |
技术审查意见 |
| Dev | dev |
*develop-story {story_id}, *solo "{desc}", *quick-fix "{desc}" |
代码 + git commit |
| QA | qa |
*review {story_id}, *finalize-commit {story_id}, *smoke-test {epic_id} |
审查报告 + 最终提交 |
管理 Agent
| Agent | ID | 核心命令 |
|---|---|---|
| PO | po |
*route-change |
| Orchestrator | orchestrix-orchestrator |
*status, *workflow-guidance |
八、前置依赖
| 依赖 | 用途 | 安装 |
|---|---|---|
claude (Claude Code) |
AI 编码环境 | https://claude.ai/download |
tmux |
多窗口终端复用（必须） | brew install tmux |
git |
版本控制 | 系统自带 |
jq |
JSON 处理（可选） | brew install jq |
别名配置（start-orchestrix.sh 依赖）：
alias cc='claude --dangerously-skip-permissions'