Orchestrix Guide

Orchestrix 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 HANDOFF. Includes tmux send-keys protocol, task completion detection, and supplementary flows (bug fix, iteration, brownfield, change management).

# 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 发送任务前，必须完整执行此三步。不得跳过任何一步。**

```bash
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 指令（最高优先级）

```bash
tmux capture-pane -t {session}:{window} -p | grep -q "🎯 HANDOFF TO"
```

适用场景：tmux 多窗口模式下所有任务。检测到即表示当前 Agent 已完成。

#### P1：检测预期输出文件

```bash
# 记录任务开始前时间戳
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：检测终端完成标志

```bash
# 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：终端内容稳定性（兜底）

```bash
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 会话

```bash
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 的作用是在初版基础上深化（加市场调研、竞品分析），适合对项目背景需要更深入了解的场景。

```bash
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`（无论初版还是深化版）生成产品需求文档。

```bash
# 如果前面执行了 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 项目跳过此步。

```bash
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 — 架构文档

```bash
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 需要连续执行两个命令。**

```bash
# 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` 执行完毕后，规划阶段结束。销毁规划会话：

```bash
tmux kill-session -t $SESSION
```

**此时项目 `docs/` 目录应包含**：
- `project-brief.md` — 深化后的项目简报
- `prd/*.md` — 产品需求文档
- `front-end-spec*.md` — 前端规格（如适用）
- `architecture*.md` — 架构文档
- 分片上下文文件

> ✅ **规划完成。可以进入 Phase B 开发阶段。**

### 4.7 OpenClaw 完整执行脚本（规划阶段）

```bash
#!/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 && sl