acp-team: Multi-Agent Team Coordination
Team coordination layer for acpx - mailbox, task board, and multi-agent workflows.
When to Use This Skill
Use this skill when the user:
- Wants to coordinate multiple AI agents working together
- Needs a shared task board with claim/lease mechanics
- Wants agents to communicate via message inboxes
- Asks about spawning team members with different roles
- Needs task assignment and status tracking across agents
Architecture
┌─────────────────────────────────────────────────────────┐
│ acp-team │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ TaskStore │ │ MessageBus │ │ TeamStore │ │
│ │ .tasks/ │ │ .team/inbox │ │ .team/config│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ Coordinator │
│ │ │
│ ▼ │
│ acpx sessions │
└─────────────────────────────────────────────────────────┘
Installation
npm install -g acp-team
Requires acpx to be installed:
npm install -g acpx
Quick Start
# Initialize team in your project
acp-team init --name my-project
# Create tasks
acp-team task create "Fix authentication bug"
acp-team task create "Write unit tests"
# Spawn a team member
acp-team spawn alice -r coder -p "Fix the auth bug in task #1"
# Check status
acp-team status
# Send messages
acp-team msg send alice "How's the bug fix going?"
acp-team msg inbox alice
Commands Reference
Team Management
| Command |
Description |
acp-team init [--name <team>] |
Initialize team in project |
acp-team status |
Show team and task status |
acp-team spawn <name> -r <role> -p <prompt> |
Spawn a team member with acpx |
acp-team shutdown <member> |
Request member shutdown |
Task Board
| Command |
Description |
acp-team task create <subject> |
Create a new task |
acp-team task list |
List all tasks |
acp-team task unclaimed |
List unclaimed tasks |
acp-team task claim <id> [-o <owner>] |
Claim a task |
acp-team task assign <id> <member> |
Assign task to member |
acp-team task done <id> |
Mark task as done |
Task Lease System
| Command |
Description |
acp-team task claim-lease <id> -o <owner> -d <ms> |
Claim with lease (default 60s) |
acp-team task heartbeat <id> -t <token> |
Renew lease |
acp-team task release-expired |
Release all expired leases |
Messaging
| Command |
Description |
acp-team msg send <to> <message> |
Send direct message |
acp-team msg broadcast <message> |
Broadcast to all members |
acp-team msg inbox [name] |
Read inbox (drains messages) |
acp-team msg peek [name] |
Peek inbox (without draining) |
Task State Machine
pending → claimed → running → blocked → completed
↓ ↓
cancelled failed
↓ ↓
timed_out
Message Envelope Format
{
"schema_version": "1.0",
"message_id": "uuid",
"trace_id": "...",
"sender": "alice",
"recipient": "bob",
"type": "message",
"content": "...",
"created_at": 1234567890,
"priority": 1
}
File Structure
.team/
├── config.json # Team configuration
└── inbox/
├── alice.jsonl # Alice's inbox
├── bob.jsonl # Bob's inbox
└── lead.jsonl # Lead's inbox
.tasks/
├── task_1.json # Task #1
├── task_2.json # Task #2
└── ...
Workflow Example
# 1. Initialize
acp-team init --name feature-dev
# 2. Create tasks
acp-team task create "Design API schema"
acp-team task create "Implement backend"
acp-team task create "Write tests"
# 3. Spawn designer
acp-team spawn designer -r architect -p "Design the API schema for task #1" -a claude
# 4. After design is done, spawn implementer
acp-team spawn coder -r backend -p "Implement the API based on the design"
# 5. Monitor progress
acp-team status
acp-team msg inbox lead
# 6. Spawn tester
acp-team spawn tester -r qa -p "Write tests for the new API"
Resources
femto