OpenClaw + ClawTeam + Superpowers Git Initialization
This commit is contained in:
@@ -0,0 +1,261 @@
|
||||
---
|
||||
name: ClawTeam Multi-Agent Coordination
|
||||
description: >
|
||||
This skill should be used when the user asks to "create a team", "spawn agents",
|
||||
"assign tasks", "coordinate multiple agents", "check team status", "view kanban board",
|
||||
"send messages between agents", "manage team tasks", "monitor team progress",
|
||||
or mentions "clawteam", "multi-agent coordination", "team collaboration",
|
||||
"agent inbox", "task board", "spawn worker". This skill should also be triggered
|
||||
when the current task is complex enough to benefit from splitting into subtasks
|
||||
and delegating to multiple agents — for example when the user asks to "build a
|
||||
full-stack app", "refactor the entire codebase", "implement multiple features
|
||||
in parallel", or when the agent determines that the work scope exceeds what a
|
||||
single agent can efficiently handle alone. Provides comprehensive guidance for
|
||||
using the ClawTeam CLI to orchestrate multi-agent teams with task management,
|
||||
messaging, monitoring, runtime profiles, git context, and recovery tooling.
|
||||
version: 0.3.1
|
||||
---
|
||||
|
||||
# ClawTeam Multi-Agent Coordination
|
||||
|
||||
ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as a team.
|
||||
It provides team/task management, inter-agent messaging, git worktree isolation, provider-aware
|
||||
runtime profiles, git context injection, snapshots, and terminal-based monitoring dashboards.
|
||||
|
||||
All operations are performed via the `clawteam` CLI. Data is stored in `~/.clawteam/` by default.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install clawteam
|
||||
```
|
||||
|
||||
Requires Python 3.10+. For P2P transport support: `pip install clawteam[p2p]`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `tmux` installed (default spawn backend)
|
||||
- A CLI coding agent such as `claude`, `codex`, `gemini`, `kimi`, `nanobot`, or `openclaw`
|
||||
- A git repository for worktree isolation and context features
|
||||
- Default dependencies installed if you want the TUI wizard (`clawteam profile wizard`)
|
||||
|
||||
## Core Concepts
|
||||
|
||||
**Teams** — Named groups of agents with one leader and zero or more workers.
|
||||
|
||||
**Inbox** — File-based message queue per agent. `receive` is destructive; `peek` is not.
|
||||
|
||||
**Tasks** — Shared task board with `pending`, `in_progress`, `completed`, and `blocked`.
|
||||
Tasks support dependency chains and priorities.
|
||||
|
||||
**Profiles** — Reusable client/provider/runtime configs used by `spawn` and `launch`.
|
||||
|
||||
**Presets** — Shared provider templates used to generate one or more profiles.
|
||||
|
||||
**Context** — Git/worktree-aware context tools for overlap checks, recent changes, and prompt injection.
|
||||
|
||||
**Board** — Team dashboard with kanban tasks, inbox counts, and message history views, plus gource activity visualization.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Set Up a Team with Tasks
|
||||
|
||||
```bash
|
||||
export CLAWTEAM_AGENT_ID="leader-001"
|
||||
export CLAWTEAM_AGENT_NAME="leader"
|
||||
export CLAWTEAM_AGENT_TYPE="leader"
|
||||
|
||||
clawteam team spawn-team my-team -d "Project team" -n leader
|
||||
clawteam task create my-team "Design system" -o leader
|
||||
clawteam task create my-team "Implement feature" -o worker1
|
||||
clawteam task create my-team "Write tests" -o worker2
|
||||
clawteam board show my-team
|
||||
```
|
||||
|
||||
### Configure Runtime Profiles
|
||||
|
||||
```bash
|
||||
# Inspect built-in provider templates
|
||||
clawteam preset list
|
||||
clawteam preset show moonshot-cn
|
||||
|
||||
# Generate a reusable profile from a preset
|
||||
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
|
||||
|
||||
# Or use the interactive TUI
|
||||
clawteam profile wizard
|
||||
|
||||
# Claude Code on a fresh machine/home may need onboarding repair once
|
||||
clawteam profile doctor claude
|
||||
|
||||
# Smoke-test the profile before using it in a team
|
||||
MOONSHOT_API_KEY=... clawteam profile test claude-kimi
|
||||
```
|
||||
|
||||
### Spawn and Coordinate Agents
|
||||
|
||||
```bash
|
||||
# Default path: tmux backend, claude command, git worktree isolation, skip-permissions on
|
||||
clawteam spawn --team my-team --agent-name worker1 --task "Implement the auth module"
|
||||
clawteam spawn --team my-team --agent-name worker2 --task "Write unit tests"
|
||||
|
||||
# Explicit backend and command
|
||||
clawteam spawn tmux claude --team my-team --agent-name worker3 --task "Build API endpoints"
|
||||
clawteam spawn subprocess claude --team my-team --agent-name worker4 --task "Run linting"
|
||||
|
||||
# Recommended for non-default providers/models
|
||||
clawteam spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"
|
||||
clawteam spawn subprocess --profile gemini-vertex --team my-team --agent-name worker6 --task "Run linting"
|
||||
|
||||
clawteam board attach my-team
|
||||
clawteam inbox send my-team worker1 "Start implementing the auth module"
|
||||
clawteam board live my-team --interval 3
|
||||
```
|
||||
|
||||
### Spawn Defaults
|
||||
|
||||
| Setting | Default | Override |
|
||||
|---------|---------|----------|
|
||||
| Backend | `tmux` | `clawteam spawn subprocess ...` |
|
||||
| Command | `claude` | `clawteam spawn tmux my-cmd ...` |
|
||||
| Workspace | `auto` (git worktree) | `--no-workspace` or config `workspace=never` |
|
||||
| Permissions | skip | `--no-skip-permissions` or config `skip_permissions=false` |
|
||||
| Runtime profile | none | `--profile <name>` |
|
||||
|
||||
Use `--profile` whenever you need a non-default provider, model, endpoint, or auth mapping.
|
||||
|
||||
### Task Lifecycle
|
||||
|
||||
```bash
|
||||
# Create with dependencies
|
||||
clawteam task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>
|
||||
|
||||
# Create with priority
|
||||
clawteam task create my-team "Hotfix prod issue" --priority high
|
||||
|
||||
# Update status
|
||||
clawteam task update my-team <task-id> --status in_progress
|
||||
clawteam task update my-team <task-id> --status completed
|
||||
|
||||
# Filter tasks
|
||||
clawteam task list my-team --status blocked
|
||||
clawteam task list my-team --owner worker1
|
||||
clawteam task list my-team --priority high
|
||||
```
|
||||
|
||||
### Waiting for Sub-Agents
|
||||
|
||||
```bash
|
||||
clawteam task wait my-team
|
||||
clawteam task wait my-team --timeout 300 --poll-interval 10
|
||||
clawteam task wait my-team --agent coordinator
|
||||
clawteam --json task wait my-team --timeout 600
|
||||
```
|
||||
|
||||
### Worker Loop Protocol
|
||||
|
||||
Workers should not stop after completing the initial `--task`. The expected loop is:
|
||||
|
||||
```bash
|
||||
# 1. Check tasks assigned to you
|
||||
clawteam task list my-team --owner worker1
|
||||
|
||||
# 2. Finish any pending work, then check for new instructions
|
||||
clawteam inbox receive my-team --agent worker1
|
||||
|
||||
# 3. If idle, notify the leader and keep monitoring for follow-ups
|
||||
clawteam lifecycle idle my-team
|
||||
```
|
||||
|
||||
Repeat the loop until the leader explicitly shuts the worker down.
|
||||
|
||||
### Git Context and Conflict Checks
|
||||
|
||||
```bash
|
||||
clawteam context log my-team
|
||||
clawteam context conflicts my-team
|
||||
clawteam context inject my-team --agent worker1
|
||||
```
|
||||
|
||||
Use these before reassigning work, continuing another worker's task, or merging overlapping changes.
|
||||
|
||||
### Snapshots and Recovery
|
||||
|
||||
```bash
|
||||
clawteam team snapshot my-team --tag before-refactor
|
||||
clawteam team snapshots my-team
|
||||
clawteam team restore my-team --snapshot before-refactor
|
||||
```
|
||||
|
||||
### Activity Visualization
|
||||
|
||||
```bash
|
||||
clawteam board gource my-team --log-only
|
||||
clawteam board gource my-team --live
|
||||
```
|
||||
|
||||
Prefer `--log-only` in headless environments.
|
||||
|
||||
## Supported CLI Agents
|
||||
|
||||
Common validated CLIs include:
|
||||
- `claude`
|
||||
- `codex`
|
||||
- `gemini`
|
||||
- `kimi`
|
||||
- `nanobot`
|
||||
- `openclaw`
|
||||
|
||||
OpenClaw worker spawns are normalized automatically. Bare `openclaw` commands are promoted to
|
||||
the agent entrypoint and wired with `--local`, `--session-id`, and `--message` as needed.
|
||||
|
||||
Configure non-default providers through `profile` + `preset` instead of hardcoding env vars into prompts.
|
||||
|
||||
## Command Groups
|
||||
|
||||
| Group | Purpose | Key Commands |
|
||||
|-------|---------|-------------|
|
||||
| `preset` | Shared provider templates | `list`, `show`, `generate-profile`, `bootstrap` |
|
||||
| `profile` | Reusable client/provider configs | `list`, `show`, `set`, `test`, `wizard`, `doctor` |
|
||||
| `team` | Team lifecycle | `spawn-team`, `discover`, `status`, `request-join`, `approve-join`, `cleanup`, `snapshot`, `restore` |
|
||||
| `inbox` | Messaging | `send`, `broadcast`, `receive`, `peek`, `watch` |
|
||||
| `task` | Task management | `create`, `get`, `update`, `list`, `wait` |
|
||||
| `board` | Monitoring and visualization | `show`, `overview`, `live`, `attach`, `serve`, `gource` |
|
||||
| `context` | Git/worktree context | `diff`, `files`, `conflicts`, `log`, `inject` |
|
||||
| `plan` | Plan approval | `submit`, `approve`, `reject` |
|
||||
| `lifecycle` | Agent lifecycle | `request-shutdown`, `approve-shutdown`, `idle` |
|
||||
| `spawn` | Process spawning | `spawn [backend] [command]` |
|
||||
| `identity` | Identity management | `show`, `set` |
|
||||
|
||||
## JSON Output
|
||||
|
||||
All commands support `--json` for machine-readable output. Put the flag before the subcommand:
|
||||
|
||||
```bash
|
||||
clawteam --json team discover
|
||||
clawteam --json board show my-team
|
||||
clawteam --json task list my-team --status pending
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
- `inbox receive` consumes messages. Use `inbox peek` for non-destructive reads.
|
||||
- Task status `blocked` is auto-set when `--blocked-by` is specified at creation.
|
||||
- Completing a task auto-unblocks tasks that list it in `blockedBy`.
|
||||
- Tasks also support `priority`; use `high` for urgent unblockers and production fixes.
|
||||
- Workers are expected to keep polling tasks/inbox after the first task instead of exiting immediately.
|
||||
- `clawteam spawn` defaults to tmux, git worktree isolation, and skip-permissions.
|
||||
- `clawteam launch` also respects `skip_permissions`, so template workers no longer stall on approval prompts.
|
||||
- All file writes use atomic tmp+rename to prevent corruption.
|
||||
- Identity env vars are set automatically when spawning via `clawteam spawn`.
|
||||
- Use `board attach <team>` to watch all agents in a tiled tmux layout.
|
||||
- `board show` JSON and the browser board now include message history with member-aware aliases, which is useful for inbox triage and handoffs.
|
||||
- Prefer `--profile` for non-default providers/models instead of manually exporting provider env vars.
|
||||
- `profile` is the final runtime object; `preset` is a reusable template for generating profiles.
|
||||
- For Claude Code on a fresh machine/home, run `clawteam profile doctor claude` once before spawning.
|
||||
- `context inject` and `context conflicts` are the recommended way to hand off cross-worktree tasks safely.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **`references/cli-reference.md`** — Complete CLI reference with commands, options, and data models
|
||||
- **`references/workflows.md`** — Multi-agent workflows: setup, spawn coordination, join protocol, plan approval, graceful shutdown, monitoring patterns
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "ClawTeam"
|
||||
short_description: "Create and coordinate multi-agent teams from Codex."
|
||||
default_prompt: "Use $clawteam to create a team, split this task into tracked work items, spawn workers, coordinate them, and deliver the result."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
+400
@@ -0,0 +1,400 @@
|
||||
# ClawTeam CLI Complete Reference
|
||||
|
||||
## Global Options
|
||||
|
||||
```
|
||||
clawteam [--version] [--json] [--data-dir PATH] <command>
|
||||
```
|
||||
|
||||
- `--json` — Output JSON instead of human-readable text. Apply before subcommand: `clawteam --json team discover`
|
||||
- `--data-dir PATH` — Override data directory (default: `~/.clawteam`)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
ClawTeam agents use these environment variables for identity:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `CLAWTEAM_AGENT_ID` | Unique agent identifier | `a1b2c3d4e5f6` |
|
||||
| `CLAWTEAM_AGENT_NAME` | Human-readable agent name | `alice` |
|
||||
| `CLAWTEAM_AGENT_TYPE` | Agent role type | `leader`, `general-purpose`, `researcher` |
|
||||
| `CLAWTEAM_TEAM_NAME` | Team the agent belongs to | `dev-team` |
|
||||
| `CLAWTEAM_DATA_DIR` | Override data directory | `/tmp/clawteam-data` |
|
||||
|
||||
When spawning agents via `clawteam spawn`, these are set automatically.
|
||||
|
||||
---
|
||||
|
||||
## Team Commands (`clawteam team`)
|
||||
|
||||
### `team spawn-team`
|
||||
|
||||
Create a new team and register the leader.
|
||||
|
||||
```bash
|
||||
clawteam team spawn-team <name> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--description, -d` | Team description | `""` |
|
||||
| `--agent-name, -n` | Leader agent name | `"leader"` |
|
||||
| `--agent-type` | Leader agent type | `"leader"` |
|
||||
|
||||
Example:
|
||||
```bash
|
||||
clawteam team spawn-team dev-team -d "Backend development team" -n alice
|
||||
```
|
||||
|
||||
### `team discover`
|
||||
|
||||
List all existing teams.
|
||||
|
||||
```bash
|
||||
clawteam team discover
|
||||
clawteam --json team discover
|
||||
```
|
||||
|
||||
Returns: name, description, leadAgentId, memberCount for each team.
|
||||
|
||||
### `team status`
|
||||
|
||||
Show team configuration and member list.
|
||||
|
||||
```bash
|
||||
clawteam team status <team>
|
||||
```
|
||||
|
||||
### `team request-join`
|
||||
|
||||
Request to join a team. Blocks until leader approves/rejects or timeout.
|
||||
|
||||
```bash
|
||||
clawteam team request-join <team> <proposed-name> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--capabilities, -c` | Agent capabilities description | `""` |
|
||||
| `--timeout, -t` | Timeout in seconds | `60` |
|
||||
|
||||
### `team approve-join`
|
||||
|
||||
Approve a pending join request (leader only).
|
||||
|
||||
```bash
|
||||
clawteam team approve-join <team> <request-id> [--assigned-name NAME]
|
||||
```
|
||||
|
||||
### `team reject-join`
|
||||
|
||||
Reject a pending join request (leader only).
|
||||
|
||||
```bash
|
||||
clawteam team reject-join <team> <request-id> [--reason TEXT]
|
||||
```
|
||||
|
||||
### `team cleanup`
|
||||
|
||||
Delete a team and all its data (config, inboxes, tasks).
|
||||
|
||||
```bash
|
||||
clawteam team cleanup <team> [--force]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inbox Commands (`clawteam inbox`)
|
||||
|
||||
### `inbox send`
|
||||
|
||||
Send a point-to-point message to an agent.
|
||||
|
||||
```bash
|
||||
clawteam inbox send <team> <to> <content> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--key, -k` | Routing key | `None` |
|
||||
| `--type` | Message type | `"message"` |
|
||||
|
||||
### `inbox broadcast`
|
||||
|
||||
Broadcast a message to all team members (except sender).
|
||||
|
||||
```bash
|
||||
clawteam inbox broadcast <team> <content> [options]
|
||||
```
|
||||
|
||||
### `inbox receive`
|
||||
|
||||
Receive and consume messages from inbox (destructive — messages are deleted).
|
||||
|
||||
```bash
|
||||
clawteam inbox receive <team> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--agent, -a` | Agent name (default: from env) | env |
|
||||
| `--limit, -l` | Max messages to receive | `10` |
|
||||
|
||||
### `inbox peek`
|
||||
|
||||
Peek at messages without consuming them (non-destructive).
|
||||
|
||||
```bash
|
||||
clawteam inbox peek <team> [--agent NAME]
|
||||
```
|
||||
|
||||
### `inbox watch`
|
||||
|
||||
Watch inbox for new messages in real-time (blocking, Ctrl+C to stop).
|
||||
|
||||
```bash
|
||||
clawteam inbox watch <team> [--agent NAME] [--poll-interval 1.0]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Commands (`clawteam task`)
|
||||
|
||||
### `task create`
|
||||
|
||||
Create a new task.
|
||||
|
||||
```bash
|
||||
clawteam task create <team> <subject> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--description, -d` | Task description | `""` |
|
||||
| `--owner, -o` | Owner agent name | `""` |
|
||||
| `--priority, -p` | Task priority: `low`, `medium`, `high`, `urgent` | `"medium"` |
|
||||
| `--blocks` | Comma-separated task IDs this blocks | `None` |
|
||||
| `--blocked-by` | Comma-separated task IDs blocking this | `None` |
|
||||
|
||||
Example:
|
||||
```bash
|
||||
clawteam task create dev-team "Implement auth" -o alice -d "Add JWT authentication"
|
||||
```
|
||||
|
||||
### `task get`
|
||||
|
||||
Get a single task by ID.
|
||||
|
||||
```bash
|
||||
clawteam task get <team> <task-id>
|
||||
```
|
||||
|
||||
### `task update`
|
||||
|
||||
Update a task's status, owner, or dependencies.
|
||||
|
||||
```bash
|
||||
clawteam task update <team> <task-id> [options]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--status, -s` | New status: `pending`, `in_progress`, `completed`, `blocked` |
|
||||
| `--owner, -o` | New owner |
|
||||
| `--subject` | New subject |
|
||||
| `--description, -d` | New description |
|
||||
| `--priority, -p` | New priority: `low`, `medium`, `high`, `urgent` |
|
||||
| `--add-blocks` | Comma-separated task IDs to add to blocks |
|
||||
| `--add-blocked-by` | Comma-separated task IDs to add to blocked-by |
|
||||
| `--force, -f` | Force override task lock |
|
||||
|
||||
When a task is marked `completed`, any tasks blocked by it are automatically unblocked (moved from `blocked` to `pending` if no other blockers remain).
|
||||
|
||||
### `task list`
|
||||
|
||||
List all tasks for a team, with optional filters.
|
||||
|
||||
```bash
|
||||
clawteam task list <team> [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Board Commands (`clawteam board`)
|
||||
|
||||
### `board show`
|
||||
|
||||
Show detailed team board data. Human output renders the kanban board; JSON output also includes
|
||||
members with inbox identity fields plus persistent message history from the event log.
|
||||
|
||||
```bash
|
||||
clawteam board show <team>
|
||||
clawteam --json board show <team>
|
||||
```
|
||||
|
||||
Recent board payloads include member-aware message aliases such as `memberKey`, `inboxName`,
|
||||
`fromLabel`, and `toLabel`, which are used by the browser board to filter inbox history.
|
||||
|
||||
### `board overview`
|
||||
|
||||
Show summary of all teams in a table.
|
||||
|
||||
```bash
|
||||
clawteam board overview
|
||||
clawteam --json board overview
|
||||
```
|
||||
|
||||
### `board live`
|
||||
|
||||
Live-refreshing kanban board. Auto-refreshes at interval. Ctrl+C to stop.
|
||||
|
||||
```bash
|
||||
clawteam board live <team> [--interval 2.0]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plan Commands (`clawteam plan`)
|
||||
|
||||
### `plan submit`
|
||||
|
||||
Submit a plan for leader approval. Content can be inline text or a file path.
|
||||
|
||||
```bash
|
||||
clawteam plan submit <team> <agent> <plan-content-or-file> [--summary TEXT]
|
||||
```
|
||||
|
||||
### `plan approve`
|
||||
|
||||
Approve a submitted plan.
|
||||
|
||||
```bash
|
||||
clawteam plan approve <team> <plan-id> <agent> [--feedback TEXT]
|
||||
```
|
||||
|
||||
### `plan reject`
|
||||
|
||||
Reject a submitted plan.
|
||||
|
||||
```bash
|
||||
clawteam plan reject <team> <plan-id> <agent> [--feedback TEXT]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle Commands (`clawteam lifecycle`)
|
||||
|
||||
### `lifecycle request-shutdown`
|
||||
|
||||
Request an agent to shut down.
|
||||
|
||||
```bash
|
||||
clawteam lifecycle request-shutdown <team> <from-agent> <to-agent> [--reason TEXT]
|
||||
```
|
||||
|
||||
### `lifecycle approve-shutdown`
|
||||
|
||||
Agent agrees to shut down.
|
||||
|
||||
```bash
|
||||
clawteam lifecycle approve-shutdown <team> <request-id> <agent>
|
||||
```
|
||||
|
||||
### `lifecycle reject-shutdown`
|
||||
|
||||
Agent rejects shutdown request.
|
||||
|
||||
```bash
|
||||
clawteam lifecycle reject-shutdown <team> <request-id> <agent> [--reason TEXT]
|
||||
```
|
||||
|
||||
### `lifecycle idle`
|
||||
|
||||
Send idle notification to leader (agent has no more work).
|
||||
|
||||
```bash
|
||||
clawteam lifecycle idle <team> [--last-task ID] [--task-status STATUS]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spawn Command
|
||||
|
||||
Spawn a new agent process with team environment variables.
|
||||
|
||||
```bash
|
||||
clawteam spawn <backend> <command...> [options]
|
||||
```
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--team, -t` | Team name | `"default"` |
|
||||
| `--agent-name, -n` | Agent name | auto-generated |
|
||||
| `--agent-type` | Agent type | `"general-purpose"` |
|
||||
|
||||
Backends: `subprocess`, `tmux`
|
||||
|
||||
Example:
|
||||
```bash
|
||||
clawteam spawn subprocess claude --team dev-team --agent-name bob --agent-type researcher
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Identity Commands (`clawteam identity`)
|
||||
|
||||
### `identity show`
|
||||
|
||||
Show current agent identity from environment variables.
|
||||
|
||||
```bash
|
||||
clawteam identity show
|
||||
```
|
||||
|
||||
### `identity set`
|
||||
|
||||
Print shell export commands to set identity environment variables.
|
||||
|
||||
```bash
|
||||
eval $(clawteam identity set --agent-name alice --team dev-team)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Task Statuses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `pending` | Not yet started |
|
||||
| `in_progress` | Currently being worked on |
|
||||
| `completed` | Done (auto-unblocks dependents) |
|
||||
| `blocked` | Waiting on other tasks |
|
||||
|
||||
### Message Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `message` | General point-to-point message |
|
||||
| `broadcast` | Broadcast to all members |
|
||||
| `join_request` | Request to join team |
|
||||
| `join_approved` / `join_rejected` | Join response |
|
||||
| `plan_approval_request` | Plan submitted for review |
|
||||
| `plan_approved` / `plan_rejected` | Plan response |
|
||||
| `shutdown_request` | Shutdown request |
|
||||
| `shutdown_approved` / `shutdown_rejected` | Shutdown response |
|
||||
| `idle` | Agent idle notification |
|
||||
|
||||
### File Storage Layout
|
||||
|
||||
```
|
||||
~/.clawteam/
|
||||
├── teams/{team}/
|
||||
│ ├── config.json # TeamConfig (name, members, leader)
|
||||
│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json files
|
||||
├── tasks/{team}/
|
||||
│ └── task-{id}.json # Individual task files
|
||||
└── plans/
|
||||
└── {agent}-{id}.md # Plan documents
|
||||
```
|
||||
@@ -0,0 +1,207 @@
|
||||
# ClawTeam Coordination Workflows
|
||||
|
||||
## Workflow 1: Create a Team and Assign Tasks
|
||||
|
||||
A common workflow for setting up a new project team.
|
||||
|
||||
```bash
|
||||
# 1. Set leader identity
|
||||
export CLAWTEAM_AGENT_ID="leader-001"
|
||||
export CLAWTEAM_AGENT_NAME="leader"
|
||||
export CLAWTEAM_AGENT_TYPE="leader"
|
||||
|
||||
# 2. Create team
|
||||
clawteam team spawn-team my-project -d "Web app development" -n leader
|
||||
|
||||
# 3. Create tasks with dependencies
|
||||
clawteam task create my-project "Design API schema" -o leader
|
||||
# => Task ID: aaa11111
|
||||
|
||||
clawteam task create my-project "Implement backend" -o backend-dev --blocked-by aaa11111
|
||||
# => Task ID: bbb22222 (auto-set to blocked status)
|
||||
|
||||
clawteam task create my-project "Build frontend" -o frontend-dev --blocked-by aaa11111
|
||||
# => Task ID: ccc33333
|
||||
|
||||
clawteam task create my-project "Integration testing" --blocked-by bbb22222,ccc33333
|
||||
# => Task ID: ddd44444
|
||||
|
||||
# 4. Check board
|
||||
clawteam board show my-project
|
||||
|
||||
# 5. As tasks complete, update status (auto-unblocks dependents)
|
||||
clawteam task update my-project aaa11111 --status completed
|
||||
# bbb22222 and ccc33333 auto-unblock from blocked -> pending
|
||||
```
|
||||
|
||||
## Workflow 2: Multi-Agent Spawn and Coordination
|
||||
|
||||
Full lifecycle of spawning multiple agents and coordinating work.
|
||||
|
||||
```bash
|
||||
# Leader creates team
|
||||
clawteam team spawn-team dev-team -d "Feature development" -n leader
|
||||
|
||||
# Spawn worker agents (each gets identity env vars automatically)
|
||||
clawteam spawn tmux claude --team dev-team --agent-name researcher --agent-type researcher
|
||||
clawteam spawn tmux claude --team dev-team --agent-name coder --agent-type general-purpose
|
||||
|
||||
# Leader creates tasks
|
||||
clawteam task create dev-team "Research best practices" -o researcher
|
||||
clawteam task create dev-team "Implement solution" -o coder
|
||||
|
||||
# Leader sends instructions via inbox
|
||||
clawteam inbox send dev-team researcher "Research authentication patterns for microservices"
|
||||
clawteam inbox send dev-team coder "Wait for researcher's findings before starting implementation"
|
||||
|
||||
# Monitor progress
|
||||
clawteam board live dev-team --interval 5
|
||||
```
|
||||
|
||||
### Worker Agent Perspective
|
||||
|
||||
From inside a spawned worker agent:
|
||||
|
||||
```bash
|
||||
# Identity is pre-set via environment
|
||||
clawteam identity show
|
||||
# => agentName: researcher, teamName: dev-team
|
||||
|
||||
# Check inbox for instructions
|
||||
clawteam inbox receive dev-team
|
||||
|
||||
# Do work, then update task
|
||||
clawteam task update dev-team <task-id> --status in_progress
|
||||
# ... work ...
|
||||
clawteam task update dev-team <task-id> --status completed
|
||||
|
||||
# Notify leader when idle
|
||||
clawteam lifecycle idle dev-team --last-task <task-id> --task-status completed
|
||||
```
|
||||
|
||||
## Workflow 3: Join Request Protocol
|
||||
|
||||
When an agent wants to join an existing team dynamically.
|
||||
|
||||
```bash
|
||||
# Agent side: request to join (blocks until response)
|
||||
clawteam team request-join dev-team bob --capabilities "frontend specialist" --timeout 120
|
||||
|
||||
# Leader side: check inbox for join requests
|
||||
clawteam inbox peek dev-team --agent leader
|
||||
# => join_request from bob, requestId: join-abc123
|
||||
|
||||
# Leader approves
|
||||
clawteam team approve-join dev-team join-abc123
|
||||
|
||||
# Agent receives approval with assigned name and agent ID
|
||||
# => Approved! Joined as 'bob' (agentId: xyz789)
|
||||
```
|
||||
|
||||
## Workflow 4: Plan Approval Flow
|
||||
|
||||
For teams requiring plan review before execution.
|
||||
|
||||
```bash
|
||||
# Worker submits plan
|
||||
clawteam plan submit dev-team coder "1. Refactor auth module\n2. Add OAuth2\n3. Update tests" \
|
||||
--summary "Auth system modernization"
|
||||
|
||||
# Leader reviews (checks inbox)
|
||||
clawteam inbox receive dev-team --agent leader
|
||||
# => plan_approval_request with planId
|
||||
|
||||
# Leader approves or rejects
|
||||
clawteam plan approve dev-team <plan-id> coder --feedback "Looks good, proceed"
|
||||
# or
|
||||
clawteam plan reject dev-team <plan-id> coder --feedback "Add error handling section"
|
||||
```
|
||||
|
||||
## Workflow 5: Graceful Shutdown
|
||||
|
||||
Coordinated shutdown of team agents.
|
||||
|
||||
```bash
|
||||
# Leader requests shutdown of a worker
|
||||
clawteam lifecycle request-shutdown dev-team leader coder --reason "All tasks complete"
|
||||
|
||||
# Worker checks inbox, sees shutdown request
|
||||
clawteam inbox receive dev-team --agent coder
|
||||
# => shutdown_request, requestId: shut-xyz
|
||||
|
||||
# Worker finishes current work, then approves
|
||||
clawteam lifecycle approve-shutdown dev-team shut-xyz coder
|
||||
|
||||
# Leader cleans up team when all agents are done
|
||||
clawteam team cleanup dev-team --force
|
||||
```
|
||||
|
||||
## Workflow 6: Monitoring and Debugging
|
||||
|
||||
Using board and inbox commands to monitor team health.
|
||||
|
||||
```bash
|
||||
# Quick overview of all teams
|
||||
clawteam board overview
|
||||
|
||||
# Detailed view of one team
|
||||
clawteam board show dev-team
|
||||
|
||||
# JSON output for scripting/parsing
|
||||
clawteam --json board show dev-team | jq '.taskSummary'
|
||||
clawteam --json task list dev-team --status blocked | jq '.[].subject'
|
||||
|
||||
# Check who has unread messages
|
||||
clawteam --json board show dev-team | jq '.members[] | select(.inboxCount > 0) | .name'
|
||||
|
||||
# Live monitoring
|
||||
clawteam board live dev-team --interval 3
|
||||
|
||||
# Watch a specific agent's inbox
|
||||
clawteam inbox watch dev-team --agent leader
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Task with Dependencies
|
||||
|
||||
```bash
|
||||
# Create a chain: A -> B -> C
|
||||
clawteam task create team "Task A" -o alice
|
||||
# ID: aaa
|
||||
clawteam task create team "Task B" -o bob --blocked-by aaa
|
||||
# ID: bbb (status: blocked)
|
||||
clawteam task create team "Task C" -o carol --blocked-by bbb
|
||||
# ID: ccc (status: blocked)
|
||||
|
||||
# When A completes, B auto-unblocks
|
||||
clawteam task update team aaa --status completed
|
||||
# B moves from blocked -> pending
|
||||
|
||||
# When B completes, C auto-unblocks
|
||||
clawteam task update team bbb --status completed
|
||||
```
|
||||
|
||||
### Broadcasting Updates
|
||||
|
||||
```bash
|
||||
# Leader broadcasts to all team members
|
||||
clawteam inbox broadcast dev-team "Sprint planning at 2pm. Check your tasks."
|
||||
|
||||
# Broadcast with routing key for filtering
|
||||
clawteam inbox broadcast dev-team "Build passed" --key "ci-notification"
|
||||
```
|
||||
|
||||
### Using JSON Output in Scripts
|
||||
|
||||
```bash
|
||||
# Get all blocked tasks
|
||||
BLOCKED=$(clawteam --json task list dev-team --status blocked)
|
||||
echo "$BLOCKED" | jq -r '.[].id'
|
||||
|
||||
# Count pending messages per team
|
||||
clawteam --json board overview | jq '.[] | "\(.name): \(.pendingMessages) pending"'
|
||||
|
||||
# Get team member names
|
||||
clawteam --json team status dev-team | jq -r '.members[].name'
|
||||
```
|
||||
Reference in New Issue
Block a user