OpenClaw + ClawTeam + Superpowers Git Initialization
This commit is contained in:
+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