teammode

# Teammode

Run a named team of cooperating Codex workers under one leader, with durable state on disk.
This is a Codex-only workflow. It never depends on an external terminal runner - it
coordinates through Codex's own collaboration tools plus a bundled state script, on ONE of
two transports chosen up front: native MultiAgentV2 agents, or Codex App threads as the
fallback.

## When to use a team (and when to use plain subagents instead)

Use a TEAM when EITHER holds:
- the work does NOT split into perfectly isolated pieces, but doing it in parallel is clearly
  more convenient - members will need to see and react to each other's findings; or
- one task still needs exploration, yet its GOAL is already clear - parallel investigation under
  a fixed objective.

Use plain fire-and-forget subagents (`$ulw` / one-off `spawn_agent` workers) - NOT a team - when
EITHER holds:
- the work IS perfectly isolated, so there is no coordination cost worth paying; or
- the GOAL is still ambiguous, where one mind should resolve direction before any fan-out.

A team buys cross-member coordination at a real overhead cost; only spend it when coordination
is the thing you actually need.

## Pick the transport FIRST - then tell the user

Before creating any team state, decide which transport this session can run.
Inspect your active tool list and select:

1. **MultiAgentV2 (preferred)** - select when the flat V2 collaboration tools are ALL active:
   flat `spawn_agent` whose schema requires `task_name`, plus `send_message`, `followup_task`,
   `wait_agent`, `list_agents`, and `interrupt_agent`. Members are durable native agents
   addressed by task name / agent path (`/root/<task_name>`). The namespaced
   `multi_agent_v1.*` surface never qualifies as a team transport.
2. **Codex App threads (fallback)** - select when flat V2 is not available but the
   `codex_app.*` thread tools are (`create_thread`, `read_thread`, `send_message_to_thread`,
   `set_thread_title`, `set_thread_archived`).
3. **Neither set visible** - if a `tool_search` tool is active, search for the missing sets
   (e.g. `spawn_agent`, `codex_app`) before concluding: some environments defer tools behind
   tool search. A hit is only a lead: revalidate that the visible result is the COMPLETE,
   mutually compatible transport set from case 1 or 2 before selecting it. Do not combine
   partial hits from different transports.
4. **Neither set exists** - teammode cannot run here. Do NOT run `init` or fake a team with
   partial tooling. If another visible plain-subagent mechanism can independently spawn,
   communicate with, and observe plain workers, announce that exact mechanism and use it for
   non-overlapping scopes. Otherwise continue serially and report the capability limitation;
   never promise or imply plain subagents that this session cannot create.

Then, BEFORE running `init` (or instead of it in case 4), tell the user in one line what this
environment provides and which route you picked:
- `Teammode transport: MultiAgentV2 (flat spawn_agent with task_name).`
- `Teammode transport: Codex App threads (flat V2 tools not present in this session).`
- `Teammode unavailable: neither MultiAgentV2 nor codex_app tools exist in this session -
  using <visible plain-subagent mechanism> for independent scopes.`
- `Teammode unavailable: neither MultiAgentV2 nor codex_app tools exist in this session, and
  no compatible plain-subagent mechanism is available - continuing serially.`

Pass the choice to `init` as `--transport multi_agent_v2` or `--transport codex_app`. The
transport is recorded in `team.json` and is IMMUTABLE for the team's lifetime: a V2 spawn
failure is a V2 blocker to report, never permission to mix Codex App threads into the same
team. Never probe by trial-calling tools; read your tool list, and search it with
`tool_search` only when a needed set is not visible.

## You are the leader - orchestrate, do not implement

The main session is ALWAYS the team leader; you orchestrate directly and never spin up a separate
leader worker. Your job is orchestration, NOT writing product code: split the work and assign each
slice, hold live situational awareness of every member, verify and QA what they deliver, relay
findings between members, instruct and unblock, and synthesize the result. DELEGATE every code edit
to a member - if you catch yourself editing product files while the team runs, that work was a
member's slice you should have handed off. You own direction, verification, and integration (the
merge), not the keystrokes.

## Compose by part, ownership, or perspective - not by job title

A team is ALWAYS two or more members - never a single-member team. One worker on an isolated
job is a plain subagent, not a team; if you end up with a single member,
either split off a second distinct slice or drop the team and use a subagent.

Compose the team from what you actually KNOW about the work. Ground the split in real knowledge
of the problem, then divide it into clear, non-overlapping responsibilities - one per aspect of
the work - and give each member exactly one. No two members may own the same thing. Define each
member by a concrete slice: a specific part of the codebase, an ownership area, or a distinct
perspective/lens. Assigning a vague role ("backend dev", "release analyst", "the tester") is an
anti-pattern - it gives the member no real boundary and invites overlap. Each member's `focus`
names what they own concretely; the `lens` is one of `area`, `ownership`, or `perspective`.
Give each member a short, distinct `--name` too - its role or what it watches (e.g.
`app-server-lifecycle`, `mailbox-delivery`) - it labels the member everywhere; never reuse
one name for two members. On MultiAgentV2 teams also give each member a unique
`--task-name` in `lowercase_digits_underscores` form - it becomes the member's permanent
agent path `/root/<task_name>`.

## Run the script - never hand-write team state

A bundled, dependency-free Node script o