# 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
clawteam spawn subprocess openclaw --team <team> --agent-name <name> --task "..."
```

## ClawTeam Multi-Agent Orchestration

> **Important:** ClawTeam CLI command is `clawteam`. ALWAYS specify `tmux openclaw` or `subprocess openclaw` as backend+agent — 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"

# Or with subprocess (faster, no tmux monitor)
clawteam spawn subprocess 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)