277 lines
7.8 KiB
Markdown
277 lines
7.8 KiB
Markdown
# TOOLS.md - Local Notes
|
|
|
|
Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
|
|
|
|
## What Goes Here
|
|
|
|
Things like:
|
|
|
|
- Camera names and locations
|
|
- SSH hosts and aliases
|
|
- Preferred voices for TTS
|
|
- Speaker/room names
|
|
- Device nicknames
|
|
- Anything environment-specific
|
|
|
|
## Examples
|
|
|
|
```markdown
|
|
### Cameras
|
|
|
|
- living-room → Main area, 180° wide angle
|
|
- front-door → Entrance, motion-triggered
|
|
|
|
### SSH
|
|
|
|
- home-server → 192.168.1.100, user: admin
|
|
|
|
### TTS
|
|
|
|
- Preferred voice. Preferred: "Nova" (warm, slightly British)
|
|
```
|
|
|
|
## ClawTeam Templates
|
|
|
|
Available templates in `~/.clawteam/templates/`:
|
|
|
|
### dev-team.toml
|
|
- **leader** — Tech Lead / Orchestrator
|
|
- **fullstack-dev** — Versatile backend+frontend developer
|
|
- **frontend-dev** — UI components, state, responsive, accessibility
|
|
- **backend-dev** — APIs, databases, auth, security
|
|
- **uxui-dev** — Design system, visual polish, micro-interactions
|
|
- **qc-lead** — Quality gate manager, coordinates reviews
|
|
- **code-reviewer** — Architecture, logic, TDD, security review
|
|
- **qa-engineer** — Test coverage, edge cases, regression tests
|
|
- **devops-engineer** — CI/CD, Docker, deployment, monitoring
|
|
|
|
### qc-team.toml
|
|
- **qc-lead** — QC Lead, quality gate
|
|
- **code-reviewer** — Code quality review
|
|
- **test-engineer** — Test validation
|
|
- **acceptance-auditor** — Final acceptance audit
|
|
|
|
### Template Usage
|
|
```bash
|
|
# Use template when spawning team (clawteam handles template loading)
|
|
clawteam team spawn-team <team-name> -d "<description>" -n leader
|
|
# Then create tasks matching template.tasks
|
|
clawteam task create <team> "<task>" -o <owner>
|
|
# Spawn workers matching template.agents
|
|
# ❌ WRONG: NEVER use subprocess — agents die immediately after shell exits
|
|
# clawteam spawn subprocess openclaw --team <team> --agent-name <name> --task "..."
|
|
|
|
# ✅ CORRECT: always use tmux openclaw for persistent agent sessions
|
|
clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "..."
|
|
```
|
|
|
|
## ClawTeam Multi-Agent Orchestration
|
|
|
|
> **Important:** ClawTeam CLI command is `clawteam`. **ALWAYS** specify `tmux openclaw` as the backend — **NEVER** use `subprocess`. Default `claude` is not available.
|
|
> Official repo: https://github.com/HKUDS/ClawTeam
|
|
|
|
### ⚠️ CRITICAL: Spawn Syntax
|
|
|
|
```
|
|
clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"
|
|
```
|
|
|
|
**NOT** `clawteam spawn --team ...` (defaults to `claude` → will fail)
|
|
**NOT** `clawteam spawn tmux claude` (we don't have claude CLI)
|
|
|
|
### 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"
|
|
|
|
clawteam team spawn-team <team-name> -d "<description>" -n leader
|
|
|
|
# View team status
|
|
clawteam status
|
|
clawteam board show <team-name>
|
|
clawteam board attach <team-name> # tiled tmux view
|
|
```
|
|
|
|
### Task Management
|
|
|
|
```bash
|
|
# Create tasks (with owner, dependencies, priority)
|
|
clawteam task create <team> "<task description>" -o <owner>
|
|
clawteam task create <team> "<task>" -o <owner> --blocked-by <task-id>
|
|
clawteam task create <team> "Hotfix" -o <owner> --priority high
|
|
|
|
# Update status
|
|
clawteam task update <team> <task-id> --status pending
|
|
clawteam task update <team> <task-id> --status in_progress
|
|
clawteam task update <team> <task-id> --status completed
|
|
clawteam task update <team> <task-id> --status blocked
|
|
|
|
# List/filter tasks
|
|
clawteam task list <team> --status pending
|
|
clawteam task list <team> --owner <agent-name>
|
|
clawteam task list <team> --priority high
|
|
|
|
# Wait for all sub-agents to finish
|
|
clawteam task wait <team>
|
|
clawteam task wait <team> --timeout 300 --poll-interval 10
|
|
```
|
|
|
|
### Spawn Workers (OpenClaw Specific)
|
|
|
|
```bash
|
|
# ✅ CORRECT — always use tmux openclaw
|
|
clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"
|
|
|
|
# ✅ With non-default provider/model via profile
|
|
clawteam spawn tmux --profile <profile-name> --team <team> --agent-name <name> --task "<task>"
|
|
|
|
# ❌ WRONG — defaults to claude
|
|
clawteam spawn --team <team> --agent-name <name> --task "<task>"
|
|
clawteam spawn tmux claude --team <team> --agent-name <name> --task "<task>"
|
|
```
|
|
|
|
### Communication (Inbox)
|
|
|
|
```bash
|
|
# Send message to agent
|
|
clawteam inbox send <team> <to-agent> "<message>"
|
|
|
|
# Broadcast to all
|
|
clawteam inbox broadcast <team> "<message>"
|
|
|
|
# Receive (destructive — consumes message)
|
|
clawteam inbox receive <team> --agent <name>
|
|
|
|
# Peek (non-destructive)
|
|
clawteam inbox peek <team> --agent <name>
|
|
|
|
# Watch for new messages
|
|
clawteam inbox watch <team> --agent <name>
|
|
```
|
|
|
|
### Profiles & Presets
|
|
|
|
```bash
|
|
# List built-in provider templates
|
|
clawteam preset list
|
|
clawteam preset show <provider-name>
|
|
|
|
# Generate reusable profile from preset
|
|
clawteam preset generate-profile <preset> <base-agent> --name <profile-name>
|
|
|
|
# Or use interactive TUI
|
|
clawteam profile wizard
|
|
|
|
# Test a profile before using in team
|
|
clawteam profile test <profile-name>
|
|
|
|
# Fix broken profile on fresh machine
|
|
clawteam profile doctor claude
|
|
```
|
|
|
|
### Git Context & Conflict Checks
|
|
|
|
```bash
|
|
clawteam context log <team>
|
|
clawteam context diff <team>
|
|
clawteam context files <team>
|
|
clawteam context conflicts <team>
|
|
clawteam context inject <team> --agent <name>
|
|
```
|
|
|
|
### Workspace Management
|
|
|
|
```bash
|
|
clawteam workspace list <team>
|
|
clawteam workspace merge <team> <agent-name>
|
|
```
|
|
|
|
### Snapshots & Recovery
|
|
|
|
```bash
|
|
clawteam team snapshot <team> --tag <tag-name>
|
|
clawteam team snapshots <team>
|
|
clawteam team restore <team> --snapshot <tag-name>
|
|
```
|
|
|
|
### Worker Loop Protocol
|
|
|
|
Workers should NOT exit after completing their initial task. Expected loop:
|
|
|
|
```bash
|
|
# 1. Check tasks
|
|
clawteam task list <team> --owner <me>
|
|
|
|
# 2. Check inbox for new instructions
|
|
clawteam inbox receive <team> --agent <me>
|
|
|
|
# 3. If idle, notify leader
|
|
clawteam lifecycle idle <team>
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
```bash
|
|
clawteam team cleanup <team> # kill workers, cleanup worktrees
|
|
clawteam lifecycle request-shutdown <team>
|
|
```
|
|
|
|
### JSON Output
|
|
|
|
```bash
|
|
clawteam --json team discover
|
|
clawteam --json board show <team>
|
|
clawteam --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/`
|
|
|
|
### ✅ Confirmed Working Commands
|
|
|
|
```bash
|
|
# Create team
|
|
clawteam team spawn-team <team> -d "<description>" -n <leader>
|
|
|
|
# Create task (gets task ID back)
|
|
clawteam task create <team> "<task>" -o <owner>
|
|
# Output: OK Task created: <TASK_ID>
|
|
|
|
# Spawn worker with task description
|
|
clawteam spawn tmux openclaw --team <team> --agent-name <name> --agent-type coder \
|
|
--task "Do X. After done: clawteam task update <team> <TASK_ID> --status completed"
|
|
|
|
# ❌ WRONG — subprocess agents die immediately; never use this
|
|
# clawteam spawn subprocess openclaw --team <team> --agent-name <name> --task "..."
|
|
|
|
# ✅ ALWAYS use tmux (persistent, monitorable, survives network blips)
|
|
# clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "..."
|
|
|
|
# View board
|
|
clawteam board show <team>
|
|
|
|
# Mark task done
|
|
clawteam task update <team> <task-id> --status completed
|
|
|
|
### ⚠️ Flags That DON'T Exist on clawteam spawn
|
|
- `--model` (model is set by OpenClaw config, not clawteam)
|
|
- `--timeout` (no timeout flag on spawn)
|
|
- `-m` (conflicts with clawteam's own options)
|
|
|
|
### 📌 Critical Reminders
|
|
- **ALWAYS use `tmux openclaw`** — `subprocess` agents die immediately
|
|
- **Set task dependencies**: `clawteam task update <team> <id> --add-blocked-by <dep-id>`
|
|
- **Verify agents alive**: `tmux list-sessions | grep clawteam`
|
|
- **Monitor progress**: `clawteam board attach <team>`
|
|
- **Check in-progress tasks**: `clawteam task list <team> --status in_progress`
|
|
- **Unblock stuck tasks**: use `clawteam task update <team> <id> --status pending` after resolving blocker
|