refactor: alias ClawTeam CLI usage to 'oh' and update config for multi-agent coordination

2026-04-03 11:24:09 +07:00
parent e9fd48950c
commit e9a3a623a5
12 changed files with 563 additions and 124 deletions
@@ -27,32 +27,176 @@ Things like:

 ### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
+- Preferred voice. Preferred: "Nova" (warm, slightly British)
 ```

-## Why Separate?
+## ClawTeam Multi-Agent Orchestration

-Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
+> **Important:** ClawTeam CLI command is `oh`. On our OpenClaw setup, ALWAYS explicitly specify `tmux openclaw` as backend+agent — `oh spawn` defaults to `claude` which we don't have.
+> Official repo: https://github.com/HKUDS/ClawTeam

-## ClawTeam Orchestration
+### ⚠️ CRITICAL: Spawn Syntax

- CLI: `clawteam`
- Purpose: Multi-agent team coordination with git worktree isolation
- Default backend: tmux
- Supported agents: claude, codex, openclaw, gemini, kimi, nanobot
- Key commands:
-  - `clawteam team spawn-team <team> -n <leader>` — create team
-  - `clawteam spawn --team <team> --agent-name <name> --task "..."` — spawn worker
-  - `clawteam task create <team> "..." -o <owner>` — create task
-  - `clawteam task update <team> <id> --status completed` — update status
-  - `clawteam inbox send <team> <to> "..."` — message agent
-  - `clawteam board show/attach <team>` — monitor progress
-  - `clawteam workspace merge <team> <agent>` — merge worktree back
- Profiles: Use `clawteam preset generate-profile` and `--profile` for non-default providers
- Data dir: `~/.clawteam/` (default)
- Requires: Python 3.10+, tmux, git, network/filesystem access for worktrees
+```
+oh spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"
+```

---
+**NOT** `oh spawn --team ...` (defaults to `claude` → will fail)
+**NOT** `oh spawn tmux claude` (we don't have claude CLI)

-Add whatever helps you do your job. This is your cheat sheet.
+### Team Setup
+
+```bash
+# Create team (you become the leader — set env vars first)
+export CLAWTEAM_AGENT_ID="leader-001"
+export CLAWTEAM_AGENT_NAME="leader"
+export CLAWTEAM_AGENT_TYPE="leader"
+
+oh team spawn-team <team-name> -d "<description>" -n leader
+
+# View team status
+oh status
+oh board show <team-name>
+oh board attach <team-name>          # tiled tmux view
+```
+
+### Task Management
+
+```bash
+# Create tasks (with owner, dependencies, priority)
+oh task create <team> "<task description>" -o <owner>
+oh task create <team> "<task>" -o <owner> --blocked-by <task-id>
+oh task create <team> "Hotfix" -o <owner> --priority high
+
+# Update status
+oh task update <team> <task-id> --status pending
+oh task update <team> <task-id> --status in_progress
+oh task update <team> <task-id> --status completed
+oh task update <team> <task-id> --status blocked
+
+# List/filter tasks
+oh task list <team> --status pending
+oh task list <team> --owner <agent-name>
+oh task list <team> --priority high
+
+# Wait for all sub-agents to finish
+oh task wait <team>
+oh task wait <team> --timeout 300 --poll-interval 10
+```
+
+### Spawn Workers (OpenClaw Specific)
+
+```bash
+# ✅ CORRECT — always use tmux openclaw
+oh spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"
+
+# ✅ With non-default provider/model via profile
+oh spawn tmux --profile <profile-name> --team <team> --agent-name <name> --task "<task>"
+
+# ❌ WRONG — defaults to claude
+oh spawn --team <team> --agent-name <name> --task "<task>"
+oh spawn tmux claude --team <team> --agent-name <name> --task "<task>"
+```
+
+### Communication (Inbox)
+
+```bash
+# Send message to agent
+oh inbox send <team> <to-agent> "<message>"
+
+# Broadcast to all
+oh inbox broadcast <team> "<message>"
+
+# Receive (destructive — consumes message)
+oh inbox receive <team> --agent <name>
+
+# Peek (non-destructive)
+oh inbox peek <team> --agent <name>
+
+# Watch for new messages
+oh inbox watch <team> --agent <name>
+```
+
+### Profiles & Presets
+
+```bash
+# List built-in provider templates
+oh preset list
+oh preset show <provider-name>
+
+# Generate reusable profile from preset
+oh preset generate-profile <preset> <base-agent> --name <profile-name>
+
+# Or use interactive TUI
+oh profile wizard
+
+# Test a profile before using in team
+oh profile test <profile-name>
+
+# Fix broken profile on fresh machine
+oh profile doctor claude
+```
+
+### Git Context & Conflict Checks
+
+```bash
+oh context log <team>
+oh context diff <team>
+oh context files <team>
+oh context conflicts <team>
+oh context inject <team> --agent <name>
+```
+
+### Workspace Management
+
+```bash
+oh workspace list <team>
+oh workspace merge <team> <agent-name>
+```
+
+### Snapshots & Recovery
+
+```bash
+oh team snapshot <team> --tag <tag-name>
+oh team snapshots <team>
+oh team restore <team> --snapshot <tag-name>
+```
+
+### Worker Loop Protocol
+
+Workers should NOT exit after completing their initial task. Expected loop:
+
+```bash
+# 1. Check tasks
+oh task list <team> --owner <me>
+
+# 2. Check inbox for new instructions
+oh inbox receive <team> --agent <me>
+
+# 3. If idle, notify leader
+oh lifecycle idle <team>
+```
+
+### Cleanup
+
+```bash
+oh team cleanup <team>          # kill workers, cleanup worktrees
+oh lifecycle request-shutdown <team>
+```
+
+### JSON Output
+
+```bash
+oh --json team discover
+oh --json board show <team>
+oh --json task list <team> --status pending
+```
+
+Requires:
+
+- `pip install clawteam`
+- Python 3.10+
+- `tmux` installed
+- OpenClaw CLI available on PATH (`openclaw`)
+- Git repo for worktree isolation
+- Data directory: `~/.clawteam/`