# pi-team commands

Every command the `pi-team` product exposes, in two groups:

1. **`/team …`** — slash commands you type **inside a running Pi session** once the pi-team extension is loaded. These drive a live team of agents.
2. **`pi-team …`** — the terminal CLI you run **from your shell** to install, seed a project, check health, and run the test harness.

Everything below is derived from the actually registered commands (`extensions/pi-team/index.ts` and `scripts/pi-team-cli.ts`). No flag or subcommand is documented that the code does not accept. A test (`tests/pi-team-docs.test.ts`) fails if this file names a command that no longer exists, so it can't quietly rot.

> **Tip:** inside Pi, type `/team ` and press Tab — the extension autocompletes every subcommand below with a one-line description. After `/team tidy ` and `/team lesson ` it also completes the fixed next word (`--apply`, and `incident|pattern|fix|note`).

---

## `/team` — in-session team controls

`/team` with no argument is the same as `/team status`. Start a run with `/team on`, then coordinate with the rest.

| Command | What it does |
|---|---|
| `/team on <preset\|workflow\|task>` | Activate lead mode and start a run. Locks this session to the team control-plane tools, creates a shared worktree + run state, and launches agents. With no argument it prompts you for one. |
| `/team off` | Deactivate lead mode and restore the tools you had before `/team on`. Leaves any running agents alone. |
| `/team status [agent]` | Show run status — roster, assignment totals by status, resend counts. Add an agent name to scope it to one agent. |
| `/team catalog` | List the launchable specialists and IDC roles plus the control-plane tools, without launching anything. |
| `/team inbox [agent]` | Show recent status packets agents have sent. Optionally filter to one agent. |
| `/team send <agent> <message>` | Send a focused message to one agent. |
| `/team broadcast <message>` | Send the same message to every agent. |
| `/team add <specialist[:N]> [task]` | Add one (or `:N`) more specialists to the run, with an optional initial task. |
| `/team resend [assignment-id\|agent\|all]` | Retry an initial assignment whose first delivery failed. Defaults to all failed deliveries. |
| `/team refresh [agent]` | Replace an agent's generation with a fresh one, carrying a compact handoff. With no name it recovers a single agent left in a recoverable state. |
| `/team kill [agent]` | Stop one agent, or the whole run when no name is given. Verifies the process actually terminated. |
| `/team doctor` | One-shot team + install health report (hub, agents, worktree, context %, prerequisites, recent errors). |
| `/team lesson [incident\|pattern\|fix\|note] <summary>` | Record a lesson to the run's `lessons.jsonl` and search your local Research Wiki / Engineering Logbook for related notes (read-only). |
| `/team models` | Print the per-agent model / thinking override syntax. |
| `/team list` | List known durable runs. |
| `/team resume [run-id]` | Reload a prior run's state without relaunching its agents. |
| `/team tidy [--apply]` | Preview safe worktree cleanup; add `--apply` to actually remove them. |
| `/team finalize` | Wrap the run up: push the shared branch and open a PR. Never merges, force-pushes, or removes the worktree. |

### Notes on a few commands

**`/team on <preset|workflow|task>`** accepts three kinds of subject:
- a **task** in plain language (e.g. `/team on "fix the flaky auth test with a debugger, test, and review team"`) — pi-team infers a roster and sends each agent an initial assignment;
- a **preset** name (e.g. `/team on debug` for the built-in debugger/test/review trio) — agents launch without an initial prompt;
- a **workflow** name (`/team on idc`) — launches the detected IDC role set instead of `pi-` specialists.

**`/team finalize`** fails closed unless the worktree is clean and at least one commit ahead of its base. If no git remote is configured it prints the exact `git push` command instead of pushing; if `gh` is not installed it records the exact `gh pr create` command for you to run. It moves the run to a terminal `finalized` state.

**`/team kill`** requests a best-effort final handoff from each agent, then verifies the process/RPC connection is really gone before reporting success — an agent it cannot confirm stopped is reported as `kill_failed` with evidence, never a false "killed".

---

## `pi-team` — the shell CLI

Two ways to get the CLI: **`bun add -g pi-team-harness`** puts `pi-team` (and `pi-`) on your PATH, or run any verb with no install via **`bunx pi-team-harness <verb>`** (the package ships a `pi-team-harness` bin alias for the same CLI — never bare `bunx pi-team`, which fetches an unrelated package). From a clone of this repo, `pi-team install` below symlinks the checkout's scripts instead.

Run `pi-team help` to see this usage verbatim:

```
pi-team install [--prefix DIR] [--dry-run] [--force] [--no-shell-rc]
pi-team repair [--prefix DIR] [--dry-run] [--no-shell-rc]
pi-team uninstall [--prefix DIR] [--dry-run]
pi-team doctor [--prefix DIR]
pi-team init [--dry-run]
pi-team e2e [<bun test args>]
pi-team smoke [specialist|debug|idc|all] [--dry-run]
```

| Command | What it does |
|---|---|
| `pi-team install` | Symlink `pi-team` and `pi-` into `~/.local/bin` (or `--prefix DIR`), register the pi-team Pi extension in `~/.pi/agent/settings.json`, and add a PATH block to your shell rc. |
| `pi-team repair` | Same as `install` but re-points existing symlinks (implies `--force`). Use it after moving the checkout. |
| `pi-team uninstall` | Remove the symlinks, unregister the extension, and delete the managed PATH block. Leaves foreign/non-symlink files in place. |
| `pi-team doctor` | Check install + prerequisite health without starting Pi. Reports symlink status, extension registration, PATH block, and the bun/pi/git prerequisite block. |
| `pi-team init` | Prepare the **current** directory for a team run: seed a commented `.pi/team-lead.yaml` and add a `.gitignore` block for run state + worktrees. Idempotent and never destructive. |
| `pi-team e2e` | Run the no-LLM end-to-end test harness (`bun test tests/pi-team-e2e`). Extra args forward to `bun test`. Repo checkout only. |
| `pi-team smoke` | Operator-only real-agent smoke tests. `--dry-run` prints the plan without spawning anything; a real run is hard-gated behind `PI_TEAM_REAL_SMOKE=1` plus a provider key. Repo checkout only. |

### Common flags

- `--dry-run` — print what would happen; write nothing. Available on `install`, `repair`, `uninstall`, `init`, and `smoke`.
- `--prefix DIR` — install symlinks under `DIR` instead of `~/.local/bin`.
- `--force` — relink/overwrite an existing target (default on for `repair`).
- `--no-shell-rc` — skip editing your shell rc file.

### Example transcripts

**First-time install:**

```
$ pi-team install
installed: /Users/you/.local/bin/pi-team -> /path/to/pi-harnesses/scripts/pi-team
installed: /Users/you/.local/bin/pi- -> /path/to/pi-harnesses/scripts/pi-
registered: Pi extension /path/to/pi-harnesses/extensions/pi-team
installed: PATH block added to /Users/you/.zshrc
pi-team installed. Open any repo with `pi` and type `/team on`.
```

**Seed a project:**

```
$ pi-team init
pi-team init
  project: /Users/you/dev/my-app
created: /Users/you/dev/my-app/.pi/team-lead.yaml (commented starter — edit to override defaults)
updated: added pi-team init block (.pi/team-lead/, .worktrees/) to /Users/you/dev/my-app/.gitignore
prerequisites:
  Bun: found
  Pi CLI: found
  git: found
  platform: darwin — supported
next steps:
  1. Review .pi/team-lead.yaml and uncomment any presets you want to override.
  2. Commit .pi/team-lead.yaml and .gitignore.
  3. Start Pi in this repo (`pi`), then run `/team on <task>`.
```

**Check health:**

```
$ pi-team doctor
pi-team doctor
  package root: /path/to/pi-harnesses
  install prefix: /Users/you/.local/bin
  pi-team shim: installed (/Users/you/.local/bin/pi-team -> /path/to/pi-harnesses/scripts/pi-team)
  pi- launcher: installed (/Users/you/.local/bin/pi- -> /path/to/pi-harnesses/scripts/pi-)
  extension source: found /path/to/pi-harnesses/extensions/pi-team
  extension registration: registered
  shell PATH block: managed (/Users/you/.zshrc)
prerequisites:
  Bun: found
  Pi CLI: found
  git: found
  platform: darwin — supported
  pi- on PATH: found
```

If any line reports a problem, see [`troubleshooting.md`](troubleshooting.md) — it maps every failure line to its fix.

---

## Related launchers

The pi-team CLI ships alongside two sibling launchers you can also run directly. They are documented in their own references:

- **`pi- <specialist>`** — the flat `pi-` specialist network. See [`pi-specialist-harness.md`](pi-specialist-harness.md).
- **`idc-pi …`** — the governed IDC role network. See [`idc-pi-network.md`](idc-pi-network.md).