teams git:20260715.71aa758A

Immutable. This exact content is served forever at /api/v1/blob/3fffdda2dbb08ee9.

---
name: teams
description: "Organize AI coding agents into teams that collaborate on a shared task. Create teams, add teammates, start them, monitor progress, and collect results. Use this skill when you need parallel agent execution. For single-agent dispatch, use `agents run` instead."
argument-hint: "[create|add|start|status|disband]"
allowed-tools: Bash(agents teams*), Bash(agents run*), Bash(agents feed*), Bash(agents mailboxes*), Bash(agents message*)
user-invocable: true
---

# Teams Skill

Organize AI coding agents into teams for parallel collaboration. This skill teaches you how to use the `agents teams` CLI.

## Single Agent vs Teams

- **Single agent**: Use `agents run <agent> "prompt" --mode edit` for one-off tasks
- **Multiple agents**: Use `agents teams` when you need parallel execution

## Quick Start

```bash
# Create a team
agents teams create my-feature

# Add teammates
agents teams add my-feature claude "Implement the auth middleware" --name auth
agents teams add my-feature codex "Build the login UI" --name frontend

# Start the team
agents teams start my-feature --watch
```

## Commands

| Command | Description | Example |
|---------|-------------|---------|
| `create` | Start a new team | `agents teams create my-team` |
| `add` | Add a teammate | `agents teams add my-team claude "Task" --name role` |
| `start` | Launch pending teammates | `agents teams start my-team --watch` |
| `status` | Check who's working | `agents teams status my-team` |
| `logs` | Read teammate output | `agents teams logs my-team frontend` |
| `remove` | Remove a teammate | `agents teams remove my-team frontend` |
| `disband` | Stop all and remove | `agents teams disband my-team` |
| `doctor` | Check installed agents | `agents teams doctor` |

## DAG Dependencies

Use `--after` to create dependencies:

```bash
# Backend first
agents teams add my-feature claude "Build API" --name backend

# Frontend waits for backend
agents teams add my-feature codex "Build UI" --name frontend --after backend

# QA waits for both
agents teams add my-feature claude "Run tests" --name qa --after backend,frontend

# Start drains the DAG automatically
agents teams start my-feature --watch
```

## Distributed Teams (teammates on other machines)

Place teammates on **different machines** across your fleet (from `agents devices`)
instead of all on the box running `teams start`. One orchestrator still drives the
DAG, polls status, and cleans up — teammates just execute over SSH. One vocabulary —
`--device` / `--devices` (aliases `--host` / `--hosts`); all optional (omit it and
every teammate runs local, exactly as before).

```bash
# Send ONE teammate elsewhere — no pool needed
agents teams create feat
agents teams add feat claude "build the API" --name backend --device yosemite-s0
agents teams add feat claude "build the UI"  --name ui               # stays local
agents teams start feat --watch

# A device POOL — unpinned teammates auto-schedule across it (least-loaded)
agents teams create feat --devices zion,yosemite-s0 --repo https://github.com/you/repo.git
agents teams add feat claude "..." --name w1                         # auto-scheduled
agents teams add feat claude "..." --name w2 --device yosemite-s0    # or pin
```

**Where a teammate runs** — resolved at launch, top-down:

1. teammate `--device X` → **X** (explicit pin, no pool required)
2. else single-device pool → that device (whole team there)
3. else multi-device pool → **auto-scheduled** (least-loaded)
4. else → **local** (today's behavior)

- `--devices <list>` on `create` declares the pool; `--repo <url|path>` is how each
  device gets the code (defaults to the local checkout's `origin`, reused or cloned
  into `~/.agents/repos/<team>`). Per-teammate worktrees work over SSH too.
- `status` / `logs` show each teammate's host. **POSIX hosts only** in v1 (Windows
  hosts are rejected with a clear message).

## Modes

| Mode | Use When |
|------|----------|
| `plan` (default) | Read-only work: research, audit, analysis |
| `edit` | Code changes: implementation, refactoring |

Always use `--mode plan` for security audits, research, and analysis.

## Monitoring

```bash
# Check status
agents teams status my-feature

# Delta poll (efficient)
agents teams status my-feature --since 2026-04-24T09:00:00-07:00

# Read one teammate's log
agents teams logs my-feature frontend
```

### Watch the fleet's comms

`agents teams status` tells you *where each teammate is*; the fleet-comms surface
tells you *what they're saying*. Both ride the same mailbox spool teammates use to
message each other and to page you:

```bash
agents feed                  # what agents need FROM YOU — open questions / blocks, with the reply command
agents mailboxes             # what agents say TO EACH OTHER — boxes + a recent cross-box message log
agents mailboxes --watch     # live tail of all fleet traffic (▲ you when a teammate pages you); Ctrl-C to stop
agents mailboxes --graph     # who-talks-to-whom, busiest first
agents mailboxes --between <a> <b>   # one teammate relationship as a thread
```

Reply to a teammate (or answer a `feed` block) with `agents message <id> "…"` /
`agents teams message <team> <teammate> "…"`.

## Best Practices

- **Mix agents** if available — different agents have different blind spots
- **Use `--mode plan`** for read-only work (audits, research)
- **Give full context** — each teammate needs the big picture plus their specific task
- **Demand evidence** — end prompts with: `Return file:line quotes for every claim`
- **Run in parallel** — most tasks don't depend on each other
- **Name teammates** with `--name` for easy reference

## Budget Guardrails

Teammates **inherit the project's budget caps** from `agents.yaml` (see
[docs/06-observability.md](../../docs/06-observability.md#budget-guardrails-agents-budget)).
Before each teammate launches, its estimated cost is projected onto current
spend; under `on_exceed: block`, a teammate that would breach a cap is
**refused** (the spawn fails with `[budget] BLOCKED teammate …`). Caps are
**cross-vendor**: a Claude teammate and a Codex teammate draw down the *same*
`per_project` / `per_day` pool — one budget governs the whole team.

Teammate budgeting is **pre-flight only** in v1 — a teammate is estimated and
blocked *before* it spawns, but there is **no live mid-run hard-cap kill** for
teammates (that applies to local headless `agents run` today; teams is a planned
follow-up).

```yaml
# project agents.yaml
budget:
  per_project: 100.00   # shared by every teammate, regardless of agent
  on_exceed: block
```

Check spend-to-cap any time with `agents budget`.

## Short Aliases

```
teams c  = create    teams a  = add       teams s  = status
teams rm = remove    teams d  = disband   teams ls = list
```