teammode

# Teammode

Run a named team of cooperating Codex threads under one leader, with durable state on disk.
This is a Codex-only workflow. It is inspired by the lifecycle concerns in the
Yeachan-Heo/oh-my-codex team skill, but it does not copy that runtime model and never depends
on an external terminal runner - it coordinates through Codex's own thread tools plus a bundled
state script.

## 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 subagents (`$ulw` / `multi_agent_v1.spawn_agent`) - 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.

## 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 thread. 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 subagent (`multi_agent_v1.spawn_agent`), 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`) - because that name titles its thread; never reuse
one name for two members.

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

A bundled, dependency-free Node script owns all team state so you never author `team.json` or
the member manual by hand. Run it with `node` (or `bun`); it works on macOS, Linux, and Windows.
Replace `<skill-root>` with this skill's own directory.

```
node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<session>" [--session <leader_session_id>] [--worktree] [--base-branch dev]
node "<skill-root>/scripts/team.mjs" add-member  --team <session_id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <branch>]
node "<skill-root>/scripts/team.mjs" bind-thread  --team <session_id> --id A --thread <thread_id> [--cwd <path>]
node "<skill-root>/scripts/team.mjs" member-prompt --team <session_id> --id A
node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --status reported|blocked|active|archived [--note "<...>"]
node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
node "<skill-root>/scripts/team.mjs" worktree-remove --team <session_id> --id A [--force]
node "<skill-root>/scripts/team.mjs" integrate       --team <session_id> [--id A]
node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A]
node "<skill-root>/scripts/team.mjs" delete       --team <session_id> [--force]
node "<skill-root>/scripts/team.mjs" status       --team <session_id>
```

`init` creates `.omo/teams/{session_id}/` containing `team.json` (the single durable state file:
team id, the main-session leader, the member roster, status, worktree config, and a lifecycle
log), `guide.md` (the auto-generated member field manual), and `artifacts/` (a shared exchange
space). `{session_id}` is the leader's Codex session id when you can pass it via `--session`;
otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
subcommand rewrites `guide.md`, so the manual always matches the current team.

## Create the team and its threads

1. `init` the team, then `add-member` once per member.
2. Create a durable thread per member with `codex_app.create_thread` - ALWAYS this tool for every
   member, never a spawned agent - titled `[team name] <member name>`, using THAT member's own
   name (its role / what it watches), so no two threads share a title. `add-member` prints the
   exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
   set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
   Use `codex_app.set_thread_title` if the title did not land at creation.
   If Codex returns only `pendingWorktreeId`, the worktree-backed thread is not ready yet: do not
   `bind-thread` and do not send the member bootstrap. Wait until Codex surfaces a real `threadId`
   or the thread appears in the thr