acp-team

Team coordination layer for acpx - mailbox, task board, and multi-agent workflows.

Overview

┌─────────────────────────────────────────────────────────┐
│                    acp-team                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  TaskStore  │  │ MessageBus  │  │  TeamStore  │     │
│  │  .tasks/    │  │ .team/inbox │  │ .team/config│     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│         │                │                │             │
│         └────────────────┼────────────────┘             │
│                          │                              │
│                    Coordinator                          │
│                          │                              │
│                          ▼                              │
│                   acpx sessions                         │
└─────────────────────────────────────────────────────────┘

Install

npm install -g acp-team
# or
npx 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

Task Lease System

任务使用租约机制防止僵尸任务：

| 字段 | 说明 | |------|------| | lease_token | 租约令牌（UUID） | | lease_expires_at | 过期时间戳 | | heartbeat_at | 最后心跳时间 | | revision | CAS 乐观锁版本 | | attempt / max_attempts | 重试控制 |

Lease 命令

# 带租约 claim（默认 60 秒）
acp-team task claim-lease <id> -o <owner> -d <ms>

# 续租（延长 lease 时间）
acp-team task heartbeat <id> -t <token>

# 释放所有过期租约
acp-team task release-expired

Task 状态机

pending → claimed → running → blocked → completed
                                 ↓           ↓
                            cancelled    failed
                                 ↓           ↓
                                     timed_out

Message Envelope

标准化消息格式：

{
  "schema_version": "1.0",
  "message_id": "uuid",
  "trace_id": "...",
  "correlation_id": "...",
  "sender": "alice",
  "recipient": "bob",
  "type": "message",
  "content": "...",
  "created_at": 1234567890,
  "expires_at": null,
  "priority": 1,
  "idempotency_key": "..."
}

Commands

Team Management

# Initialize team
acp-team init [--name <team-name>]

# Show team and task status
acp-team status

# Spawn a team member with acpx
acp-team spawn <name> -r <role> -p <prompt> [-a <agent>]

# Request shutdown
acp-team shutdown <member>

Task Board

# Create a task
acp-team task create <subject> [-d <description>]

# List all tasks
acp-team task list

# List unclaimed tasks
acp-team task unclaimed

# Claim a task
acp-team task claim <taskId> [-o <owner>]

# Assign task to member
acp-team task assign <taskId> <member>

# Mark task done
acp-team task done <taskId>

Messaging

# Send a direct message
acp-team msg send <to> <message> [-f <from>]

# Broadcast to all members
acp-team msg broadcast <message> [-f <from>]

# Read inbox (drains messages)
acp-team msg inbox [name]

# Peek inbox (without draining)
acp-team msg peek [name]

File Structure

.team/
├── config.json          # Team configuration
└── inbox/
    ├── alice.jsonl      # Alice's inbox (JSONL)
    ├── 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. Check .tasks/task_1.json for context"

# 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"

Future: Remote Coordination

The stores are designed with pluggable backends. When ACP supports HTTP transport:

// Local (current)
const tasks = new FileTaskStore(".tasks");

// Remote (future)
const tasks = new RemoteTaskStore("https://coordinator.example.com");

This will enable cross-machine agent collaboration.

License

MIT