metabot-team

# MetaBot Agent Team

MetaBot Agent Teams mirror the compact Claude Agent Teams workflow, but the
coordination model is MetaBot-native and engine-neutral. Teammates may be
declared as Claude, Codex, Kimi, or future engines, but execution still goes
through the current bridge/session-engine path. Do not assume every engine can
handle every workflow until runtime capability validation or per-engine
adapters are added.

## Core Model

Team = Agents + Messages + Tasks + Runs.

Use the CLI for all team coordination. Plain chat output is not visible to
teammates unless you send it through the team mailbox.

## Lead Workflow

```bash
metabot teams create <team> --description "..."
metabot teams agents spawn <team> <name> --role <role> --prompt "..."  # engine defaults to codex
metabot teams dispatch <team> <name> "<subject>" --description "..." --plain
metabot teams next <team> <name> --summary
metabot teams runs list <team>
metabot teams status <team> --summary
```

Lead rules:
- Keep the team task list current.
- Prefer `metabot teams dispatch` over separate `tasks create` + `tasks update --owner` + `send`; it creates the task, assigns the owner, and wakes the teammate in one command.
- Use `agents spawn` without `--engine` for Codex teammates. Pass `--engine claude|kimi` only when a teammate specifically needs another engine.
- Use `next` to inspect a teammate's unread messages and open assigned tasks before deciding whether to send more work.
- Integrate completed work before reporting to the user.
- Stop or delete the team when the work is done.

## Teammate Workflow

```bash
metabot teams next <team> <your-name> --read
metabot teams tasks get <team> <taskId>
metabot teams tasks claim <team> <taskId> <your-name>
metabot teams tasks done <team> <taskId> "..."
metabot teams tasks block <team> <taskId> "blocked reason" --blocked-by <id,id>
metabot teams runs list <team>
metabot teams send <team> lead "Completed task <taskId>: ..."
```

Teammate rules:
- Claim a task before working on it.
- Prefer available tasks in ID order.
- Mark a task completed only after the requested verification is done.
- If blocked, use `tasks block` and message the lead with the concrete blocker.
- After completing a task, check the task list again.

## Smooth CLI Shortcuts

Lead handoff:

```bash
metabot teams dispatch metabot-core-chat bridge-runtime "Review agent bus relay" \
  --description "Read-only. Report exact files and risks." \
  --plain
```

This is equivalent to creating a task, assigning it, and sending a start
message. It returns both the task and the message ids.

Teammate loop:

```bash
metabot teams next metabot-core-chat bridge-runtime --read
metabot teams status metabot-core-chat --summary
metabot teams tasks claim metabot-core-chat 18 bridge-runtime
metabot teams tasks done metabot-core-chat 18 "Reviewed, no code edits."
```

For local shell aliases, set `METABOT_TEAM_AGENT=<name>` and omit the owner in
`tasks claim`.

Use `--summary` or `--plain` on `status`, `next`, `inbox`, `tasks list`,
`runs list`, `dispatch`, and `watch` when a concise text view is easier to scan
than JSON. The default output stays JSON for scripting.

## Parallel Same-Agent Runs

One agent can run multiple assigned tasks concurrently. This is useful for a
single `reviewer` or `verifier` member checking several independent areas in
parallel:

```bash
metabot teams dispatch metabot-core-chat reviewer "Verify backend routes" --description "Read-only. Run focused tests." --plain
metabot teams dispatch metabot-core-chat reviewer "Verify web UI build" --description "Read-only. Check UI build and risks." --plain
metabot teams dispatch metabot-core-chat reviewer "Verify package install" --description "Read-only. Inspect latest.tgz contents." --plain
metabot teams status metabot-core-chat --summary
```

Supervisor behavior:
- Pending tasks for the same agent are split into separate runs.
- Default max parallelism per agent is `4`.
- Override with `METABOT_AGENT_TEAM_MAX_PARALLEL_PER_AGENT=<n>`.
- Parallel runs use isolated run-scoped chats like
  `team:<team>:<agent>:<runId>` so one Codex session does not bleed into
  another. Single non-parallel runs keep the stable `team:<team>:<agent>` chat.
- The agent remains `working` until all its running tasks finish.

## Runs

Runs are background execution records. The supervisor creates them
automatically when it starts a teammate, but leads and teammates can also use
them for smoke tests or long-running work:

```bash
metabot teams runs list <team>
metabot teams runs create <team> [--agent <name>] [--task-id <id>] [--status running|completed|failed|stopped] [--output <text>] [--error <text>]
metabot teams runs update <team> <runId> [--status running|completed|failed|stopped] [--output <text>] [--error <text>]
metabot teams runs output <team> <runId>
metabot teams runs stop <team> <runId>
```

Run statuses: `running`, `completed`, `failed`, `stopped`.

Stop semantics: `metabot teams runs stop` marks the stored run as `stopped`.
When the supervisor owns the in-flight run, it also asks the bridge to stop the
teammate chat task, requeues assigned in-progress tasks to `pending` with a
stop note, and suppresses late executor output so delayed success cannot
overwrite the stopped run.

Failed-run rules:
- If a manual run fails, update it with `--status failed --error "<reason>"`.
- Inspect failure details with `metabot teams runs output <team> <runId>`.
- The supervisor marks failed or crashed executions as `failed`, records the
  error, requeues assigned in-progress tasks to `pending` with failure context
  in `result`, returns the agent to idle, and sends a failure message to
  `lead` for non-lead teammates.
- Do not manually mark a requeued task completed just because a failed run
  produced partial output; let the supervisor retry it or ask the lead whether
  to reassign/stop it.

## Supervisor Behavior

The bridge supervisor scans active teams for agents with unread messages or
assigned