AGENTS.md

1# team-mode — Parallel Multi-Agent Coordination
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7Spawns coordinated agent teams with shared mailbox, task list, optional tmux layout, and graceful lifecycle. Modeled after Claude Code Agent Teams. **OFF by default.** Enable via `team_mode.enabled` in `.omo/omo.jsonc`; restart OpenCode after enabling. Harness-neutral registry/mailbox/tasklist/state/worktree/tmux-layout primitives are extracted to [`packages/team-core/`](../../../../../packages/team-core); this directory remains the OpenCode adapter for session spawning, hooks, tools, and config integration.
8 
9User docs: [`docs/guide/team-mode.md`](../../../../../docs/guide/team-mode.md).
10 
11## CONFIG
12 
13Full schema: [`src/config/schema/team-mode.ts`](../../config/schema/team-mode.ts).
14 
15```jsonc
16{
17  "team_mode": {
18    "enabled": false,                       // gate
19    "tmux_visualization": false,            // optional tmux pane layout
20    "max_parallel_members": 4,              // 1..8
21    "max_members": 8,                       // 1..8 hard cap
22    "max_messages_per_run": 10000,          // 1..∞
23    "max_wall_clock_minutes": 120,          // 1..∞
24    "max_member_turns": 500,                // 1..∞
25    "base_dir": null,                       // optional override of ~/.omo/teams or <project>/.omo/teams
26    "message_payload_max_bytes": 32768,     // 1024..∞ — per-message payload cap
27    "recipient_unread_max_bytes": 262144,   // 1024..∞ — per-recipient inbox cap
28    "mailbox_poll_interval_ms": 3000        // 500..∞ — recipient poll cadence
29  }
30}
31```
32 
33## 12 TEAM_* TOOLS
34 
35Registered via [`src/plugin/tool-registry.ts`](../../plugin/tool-registry.ts) `teamModeToolsRecord` only when enabled.
36 
37| Tool | Source File | Purpose |
38|------|-------------|---------|
39| `team_create` | `tools/lifecycle.ts` | Spawn team + member sessions from named or inline TeamSpec |
40| `team_delete` | `tools/lifecycle.ts` | Tear down state, mailbox, tasklist, worktrees, optional tmux |
41| `team_shutdown_request` | `tools/lifecycle.ts` | Member or lead requests its own shutdown |
42| `team_approve_shutdown` | `tools/lifecycle.ts` | Lead acks shutdown |
43| `team_reject_shutdown` | `tools/lifecycle.ts` | Lead rejects shutdown with reason |
44| `team_send_message` | `tools/messaging.ts` | Send to member name or `*` broadcast |
45| `team_task_create` | `tools/tasks.ts` | Create task on shared list |
46| `team_task_list` | `tools/tasks.ts` | List tasks (filter by status / owner) |
47| `team_task_update` | `tools/tasks.ts` | Claim / complete / delete (atomic file lock) |
48| `team_task_get` | `tools/tasks.ts` | Fetch single task |
49| `team_status` | `tools/query.ts` | Full team run status (members, tasks, mailbox) |
50| `team_list` | `tools/query.ts` | List declared + active teams |
51 
52## ELIGIBLE AGENTS
53 
54[`AGENT_ELIGIBILITY_REGISTRY`](types.ts) in `types.ts` — three verdict tiers, each with its own rejection message:
55 
56| Verdict | Agents | Notes |
57|---------|--------|-------|
58| `eligible` | sisyphus, atlas, sisyphus-junior | Three only |
59| `conditional` | hephaestus | Lacks `teammate: "allow"` permission by default. Either apply D-36 patch (add `teammate: "allow"` in `tool-config-handler.ts`) or use `subagent_type: "sisyphus"` instead |
60| `hard-reject` | oracle, librarian, explore, multimodal-looker, metis, momus, prometheus | Read-only or plan-mode-only — cannot write to mailbox; use `task` (delegate-task) instead |
61 
62Hard-reject agents throw at TeamSpec parse with a specific message ("Agent 'X' is read-only…"). The error message points members at delegate-task as the right escape hatch.
63 
64## MEMBER KINDS
65 
66```jsonc
67{
68  "members": [
69    { "kind": "subagent_type", "name": "scout", "subagent_type": "sisyphus" },
70    { "kind": "category", "name": "writer", "category": "writing", "prompt": "Write release notes" }
71  ]
72}
73```
74 
75- `kind: "subagent_type"` — direct agent. `prompt` optional.
76- `kind: "category"` — routed through `sisyphus-junior` with the chosen category model. `prompt` REQUIRED.
77 
78## MODULE LAYOUT
79 
80```
81team-mode/
82├── index.ts                    # barrel and adapter exports
83├── types.ts                    # OpenCode-facing re-exports/wrappers for team-core schemas plus AGENT_ELIGIBILITY_REGISTRY
84├── deps.ts                     # checkTeamModeDependencies (git, tmux availability)
85├── member-parser.ts            # member validation against eligibility registry
86├── member-guidance.ts          # auto-injected guidance per member kind
87├── member-session-resolution.ts
88├── member-session-routing.ts
89├── resolve-caller-team-lead.ts # determine if a session is acting as lead
90├── team-session-registry.ts    # spawn-race-safe sessionID → team/member lookups
91├── team-registry/              # adapter shim over team-core team spec loading
92│   ├── loader.ts
93│   ├── paths.ts                # ensureBaseDirs, resolveBaseDir
94│   └── validator.ts
95├── team-state-store/           # adapter shim over team-core durable runtime state.json with atomic locks
96├── team-runtime/               # create/status/shutdown lifecycle
97├── team-mailbox/               # adapter shim over team-core async messaging (send / poll / ack / inbox)
98├── team-tasklist/              # adapter shim over team-core CRUD + claiming + dependencies
99├── team-worktree/              # adapter shim over team-core git worktree primitives
100├── team-layout-tmux/           # adapter shim over team-core optional pane layout
101└── tools/                      # 12 team_* tool implementations + tests
102```
103 
104## STORAGE LAYOUT
105 
106```
107~/.omo/teams/{name}/                       # user scope
108<project>/.omo/teams/{name}/               # project scope (wins on collision)
109  ├── config.json                          # TeamSpec
110  ├── state.json                           # runtime: members, sessionIDs, lifecycle
111  ├── mailbox/                             # one .jsonl per recipient
112  ├── tasklist.jsonl                       # shared task list
113  └── worktrees/{member-name}/             # git worktree per member
114```
115 
116## LIFECYCLE
117 
118```
1191. team_create
120   → load TeamSpec → validate eligibility → spawn member sessions
121   → init mailbox + tasklist + worktrees → optional tmux layout
1222. Lead delegates via team_send_message + team_task_create
1233. Members claim tasks (team_task_update status="claimed") → execute → report (team_send_message)
1244. team_shutdown_request → team_approve_shutdown / team_reject_shutdown
1255. team_delete → cleanup state, mailbox, tasklist, worktrees, panes
126```
127 
128## KEY INVARIANTS
129 
1301. **Spawn-race-safe resolution:** every team spawn calls `registerTeamSession(sessionId, entry)` synchronously when sessionID is known; every hook resolving sessionID calls `lookupTeamSession` BEFORE `loadRuntimeState` to avoid the spawn-race window.
1312. **Deferred ack:** messages are fire-and-forget; recipient acks via separate call.
1323. **Locked tasks:** task claiming uses atomic file locks; concurrent claims resolve safely.
1334. **Atomic writes:** state changes write to temp file then rename.
1345. **Eligible agents only:** rejection at parse, never at runtime.
1356. **No nested teams:** members CANNOT call `team_create`.
136 
137## INTEGRATION POINTS
138 
139| Where | What |
140|-------|------|
141| [`src/index.ts`](../../index.ts) (entry) | `checkTeamModeDependencies()` + `ensureBaseDirs()` if `team_mode.enabled` |
142| [`src/plugin/tool-registry.ts`](../../plugin/tool-registry.ts) `teamModeToolsRecord` | Registers 12 `team_*` tools |
143| [`create-transform-hooks.ts`](../../plugin/hooks/create-transform-hooks.ts) | Conditionally builds `teamModeStatusInjector` (`team-mode-status-injector` hook) and `teamMailboxInjector` (`team-mailbox-injector` hook) — both Transform tier |
144| [`create-tool-guard-hooks.ts`](../../plugin/hooks/create-tool-guard-hooks.ts) | Conditionally builds `teamToolGating` (`team-tool-gating` hook) — Tool Guard tier |
145| [`src/plugin/event.ts`](../../plugin/event.ts) | Registers 4 team-session-event handlers from `src/hooks/team-session-events/`: `team-idle-wake-hint`, `team-lead-orphan-handler`, `team-member-error-handler`, `team-member-status-handler` |
146| [`src/cli/doctor/checks/team-mode.ts`](../../cli/doctor/checks/team-mode.ts) | Doctor check for team-mode prerequisites |
147| [`src/features/builtin-skills/skills/team-mode.ts`](../builtin-skills/skills/team-mode.ts) | Built-in skill documenting the 12 tools — gated on `team_mode.enabled` |
148 
149## WHERE TO LOOK
150 
151| Task | Location |
152|------|----------|
153| Add new team tool | `tools/` + register in [`src/plugin/tool-registry.ts`](../../plugin/tool-registry.ts) `teamModeToolsRecord` |
154| Modify member eligibility | `types.ts` `AGENT_ELIGIBILITY_REGISTRY` |
155| Change storage format | `types.ts` Zod schemas |
156| Add worktree behavior | `team-worktree/manager.ts` |
157| Modify tmux layout | `team-layout-tmux/layout.ts` |
158| Task lifecycle changes | `team-tasklist/` |
159| Mailbox protocol changes | `team-mailbox/` |
160| Recover orphaned runs | `team-state-store/resume.ts` |
161 
162## ANTI-PATTERNS
163 
164- Never bypass `team-session-registry` — direct `loadRuntimeState` lookups will hit the spawn-race window.
165- Never write team state files without the atomic lock from `team-state-store/locks.ts`.
166- Never substitute `task` (delegate-task) for `team_*` tools when the user explicitly asks for team-mode work — they are not equivalent.
167- Never allow members to call `team_create` (nested teams are forbidden by `team-tool-gating` hook).
168