# Teams

A team is a reusable setup you install into a fresh house: a bundle of agents plus a few threads, defined once and installed any number of times. Think quickstart, or "share my setup" — instead of hand-creating a house, pinning threads, and wiring up bots one by one, you write it down once as a `team.json` and run one command. It adds no new runtime concepts; installing one is the same `createHouse` / `createThread` / `createAgent` you'd do by hand, bundled together.

## Install a team

A few teams ship with arbe (see [Bundled teams](#bundled-teams) below). `mull`, for instance, is a structured-thinking setup — a thread plus a handful of bots that take an idea through clarify → research → design → plan. To install it into a new house:

```
arbe team install packages/teams/mull/team.json --param title="Auth rewrite"
```

That creates the house, the [pinned threads](./system/threads.md), and the bots, then prints their ids, URLs, and each bot's one-time API key. Every thread is tagged with the team slug so one install is addressable as a group, and bots get `rw` on the house so they reach every thread without per-thread grants.

`--param key=value` fills in values the team asks for (see `params` below). It's a generic flag rather than `--title` because each team declares its own params and the CLI parses flags before reading the team file — so one `--param` accepts any team's params. Those values substitute into `house.name_template`: `"Mull: {{title}}"` becomes `"Mull: Auth rewrite"`. Install is one-way with no rollback — if it fails partway, delete the half-made house by hand. Pass `--json` for a stable machine-readable result (`TeamInstallOutput`).

## Write your own

Teams live in `packages/teams/<slug>/`. A long system prompt lives in its own markdown file under `prompts/` and is pulled in with `{ "$ref": "./prompts/name.md" }`; a ref that climbs out of the folder (`../`) is rejected. A minimal `team.json`:

```json
{
  "schema_version": 1,
  "slug": "standup",
  "title": "Standup",
  "version": "0.1.0",
  "house": { "name_template": "Standup: {{team}}" },
  "params": [{ "key": "team", "label": "Which team?", "required": true }],
  "threads": [{ "name": "daily", "tags": ["standup"] }],
  "agents": [
    {
      "kind": "bot",
      "name": "facilitator",
      "trigger_mode": "mention",
      "system_prompt": { "$ref": "./prompts/facilitator.md" }
    }
  ]
}
```

- **`params`** — values the operator supplies at install time (`key`, `label`, optional `required`, default true). A missing required param fails the install. v1 only substitutes them into `house.name_template`.
- **`threads`** — each has a `name` and optional free-form `tags`; the installer also stamps the team slug.
- **`agents`** — bots only in v1. Each needs `system_prompt` (inline or `$ref`) and a `trigger_mode` of `mention`, `ambient`, or `always` (`ambient` may set `ambient_delay_ms`, 100–30000). `model` is optional and falls back to the default bot model. `role` is a label for humans, stripped before install — behaviour lives in the prompt.

The team agent shape is deliberately separate from the DB agent row: adding a field to the canonical agent schema does **not** flow into teams. Changing either is a conscious choice.

## Bundled teams

- **mull** — staged thinking. `@0-orchestrator`, six stage agents (`@1-clarify` → `@6-plan`), and a `@check` reviewer, all on the default model and mention-only.
- **pingpong** — bot→bot dispatch verifier. Two pairs producing a deterministic 3-message rally, used by `tests/operator-debug-prompt.md`.
- **kanteen** — a fictional restaurant: three threads (`floor`, `kitchen`, `finance`) with mixed trigger modes, exercising multi-thread flows the others don't reach.

## Under the hood

`TeamSchema` validates the on-disk file (`$ref`s unresolved); `ResolvedTeamSchema` validates it once prompts are inlined; the installer takes a resolved team.

Code: `@arbe/teams` (resolver), `@arbe/core/install-team` (installer), `@arbe/core/schemas/team` (shapes).<br>
See also [system/agents](./system/agents.md) and [cli](./cli.md).

_Not yet: a team registry or remote origins (install by local path only); uninstall / reinstall (delete the house by hand); routing rules in the schema; per-agent param substitution; `kind: 'human'` agents._