diff --git a/src/features/team-mode/AGENTS.md b/src/features/team-mode/AGENTS.md
new file mode 100644
index 000000000..9d226b2ba
--- /dev/null
+++ b/src/features/team-mode/AGENTS.md
@@ -0,0 +1,92 @@
+# team-mode — Parallel Multi-Agent Coordination
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+Parity with Claude Code Agent Teams. OFF by default. Enable via `team_mode.enabled` in config.
+
+Spawns coordinated agent teams with shared mailbox, task list, and lifecycle management. Lead delegates, members claim tasks, graceful shutdown with acks.
+
+## MODULE LAYOUT
+
+```
+team-mode/
+├── index.ts                    # barrel exports (types, worktree)
+├── types.ts                    # Zod schemas: TeamSpec, Member, Message, Task, RuntimeState
+├── member-parser.ts            # member validation with eligibility registry
+├── deps.ts                     # dependency injection types
+├── team-session-registry.ts    # in-memory sessionId -> team/member map for spawn-race-safe lookups
+├── team-registry/              # team spec loading from ~/.omo/teams/
+│   ├── index.ts
+│   ├── loader.ts               # load from user + project scopes
+│   ├── paths.ts                # path resolution
+│   └── validator.ts            # TeamSpec validation
+├── team-state-store/           # durable runtime state
+│   ├── index.ts
+│   ├── store.ts                # CRUD for state.json
+│   ├── resume.ts               # resume orphaned runs
+│   └── locks.ts                # atomic file locks
+├── team-runtime/               # team lifecycle
+│   ├── index.ts
+│   ├── create.ts               # team_create implementation
+│   ├── status.ts               # team_status implementation
+│   ├── shutdown.ts             # shutdown request/approve/reject
+│   ├── resolve-member.ts       # member agent resolution
+│   └── resolve-member-dependencies.ts
+├── team-mailbox/               # async messaging
+│   ├── index.ts
+│   ├── send.ts                 # team_send_message
+│   ├── poll.ts                 # inbox polling
+│   ├── ack.ts                  # message ack
+│   └── inbox.ts                # inbox file ops
+├── team-tasklist/              # shared task list
+│   ├── index.ts
+│   ├── store.ts                # task CRUD
+│   ├── list.ts                 # team_task_list
+│   ├── get.ts                  # team_task_get
+│   ├── update.ts               # team_task_update (claim, complete)
+│   ├── claim.ts                # task claiming with locks
+│   └── dependencies.ts         # task dependency graph
+├── team-worktree/              # git worktree per member
+│   ├── index.ts
+│   ├── manager.ts              # worktree lifecycle
+│   └── cleanup.ts              # worktree removal
+├── team-layout-tmux/           # optional tmux visualization
+│   ├── index.ts
+│   ├── layout.ts               # pane layout management
+│   ├── close-team-member-pane.ts # close member pane + rebalance window
+│   ├── rebalance-team-window.ts  # redistribute layout after pane changes
+│   └── sweep-stale-team-sessions.ts # garbage-collect orphaned team tmux sessions
+└── tools/                      # 12 team_* tools
+    ├── index.ts                # tool registration
+    ├── lifecycle.ts            # create, delete, shutdown
+    ├── messaging.ts            # send_message
+    ├── tasks.ts                # task_create, list, update, get
+    └── query.ts                # status, list
+```
+
+## STORAGE LAYOUT
+
+See user guide: `docs/guide/team-mode.md`
+
+## KEY INVARIANTS
+
+1. **Deferred ack**: Messages are fire-and-forget; recipient acks via separate call.
+2. **Locked tasks**: Task claiming uses atomic file locks; concurrent claims resolve safely.
+3. **Atomic writes**: All state changes write to temp file then rename.
+4. **Eligible agents only**: sisyphus, atlas, sisyphus-junior, hephaestus allowed. Read-only agents rejected at parse.
+5. **No nested teams**: Members cannot call `team_create`.
+6. **Spawn-race-safe session resolution**: Every team session spawn MUST call `registerTeamSession(sessionId, entry)` synchronously when the sessionID becomes known; every hook that resolves a sessionID to a team/member MUST call `lookupTeamSession` before falling back to `loadRuntimeState` to avoid the spawn-race window.
+
+## WHERE TO LOOK
+
+| Task | Location |
+|------|----------|
+| Add new team tool | `tools/` + register in `index.ts` |
+| Modify member eligibility | `types.ts` AGENT_ELIGIBILITY_REGISTRY |
+| Change storage format | `types.ts` Zod schemas |
+| Add worktree features | `team-worktree/manager.ts` |
+| Modify tmux layout | `team-layout-tmux/layout.ts` |
+| Task lifecycle changes | `team-tasklist/` |
+| Mailbox protocol changes | `team-mailbox/` |
diff --git a/src/features/tmux-subagent/AGENTS.md b/src/features/tmux-subagent/AGENTS.md
index 135152452..bfc328318 100644
--- a/src/features/tmux-subagent/AGENTS.md
+++ b/src/features/tmux-subagent/AGENTS.md
@@ -4,7 +4,7 @@
 
 ## OVERVIEW
 
-28 files. State-first tmux integration managing panes for background agent sessions. Handles split decisions, grid planning, polling, and lifecycle events.
+32 files. State-first tmux integration managing panes for background agent sessions. Handles split decisions, grid planning, polling, and lifecycle events.
 
 ## CORE ARCHITECTURE
 
@@ -16,6 +16,8 @@ TmuxSessionManager (manager.ts)
   └─→ EventHandlers: React to session create/delete
 ```
 
+All tmux command execution is centralized through `src/shared/tmux/runner.ts` (`runTmuxCommand`). Do NOT add direct `Bun.spawn([tmux,...])` calls in this module. They will drift from the retry/timeout/terminal-error discipline.
+
 ## KEY FILES
 
 | File | Purpose |