luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(agents): refresh hierarchical AGENTS.md with team-mode coverage

Browse Source 
Update root + 43 directory-level AGENTS.md files to reflect current state:
- Root AGENTS.md rewritten with accurate counts (1967 TS files, 1304 source +
  663 test, 278k LOC, 120 barrel index.ts), 7-step init flow, 5-tier hook
  composition, and full Team Mode section (12 team_* tools, eligibility,
  storage layout, config gate)
- src/AGENTS.md adds team-mode init step, current per-subdir file/LOC table
- src/tools/AGENTS.md documents conditional gates (team-mode +12, task
  system +4, hashline +1, interactive_bash +1, look_at +1) with always-on
  baseline of 20
- src/hooks/AGENTS.md splits into 5 tiers + 4 conditional team-mode hooks
- src/features/team-mode/AGENTS.md surfaces 12 tools, eligible agents,
  spawn-race-safe invariants, and integration points
- src/features/builtin-skills/AGENTS.md tracks 10 skills incl. team-mode
- src/agents/AGENTS.md, src/plugin/AGENTS.md, src/config/AGENTS.md updated
  for team-mode awareness, accurate counts, and current schema field list
- All other AGENTS.md files refreshed to 2026-05-08 generation date
This commit is contained in:
YeonGyu-Kim
2026-05-08 12:08:42 +09:00
parent cd31d2a1a8
commit 838b5ae216
44 changed files with 909 additions and 648 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/features/AGENTS.md
+55 -44
View File
@@ -1,73 +1,84 @@
# src/features/ — 19 Feature Modules
# src/features/ — 20 Feature Modules
**Generated:** 2026-04-18
**Generated:** 2026-05-08
## OVERVIEW
Standalone feature modules wired into plugin/ layer. Each is self-contained with own types, implementation, and tests.
Standalone feature modules wired into `plugin/` layer. Each is self-contained with own types, implementation, and co-located tests. Most expose a single factory or class via `index.ts` barrel.
## MODULE MAP
| Module | Files | Complexity | Purpose |
|--------|-------|------------|---------|
| **opencode-skill-loader** | 33 | HIGH | YAML frontmatter skill loading from 4 scopes |
| **background-agent** | 47 | HIGH | Task lifecycle, concurrency (5/model), polling, spawner pattern, circuit breaker |
| **tmux-subagent** | 34 | HIGH | Tmux pane management, grid planning, session orchestration |
| **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) for MCP servers |
| **builtin-skills** | 17 | LOW | 8 skills: git-master, playwright, playwright-cli, agent-browser, dev-browser, frontend-ui-ux, review-work, ai-slop-remover |
| **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth step-up) |
| **claude-code-plugin-loader** | 15 | MEDIUM | Unified plugin discovery from .opencode/plugins/ |
| **builtin-commands** | 11 | LOW | Command templates: refactor, init-deep, handoff, etc. |
| **claude-tasks** | 7 | MEDIUM | Task schema + file storage + OpenCode todo sync |
| **claude-code-mcp-loader** | 6 | MEDIUM | .mcp.json loading with ${VAR} env expansion |
| **context-injector** | 6 | MEDIUM | AGENTS.md/README.md injection into context |
| **run-continuation-state** | 5 | LOW | Persistent state for `run` command continuation across sessions |
| **hook-message-injector** | 5 | MEDIUM | System message injection for hooks |
| **boulder-state** | 5 | LOW | Persistent state for multi-step operations |
| **background-agent** | 47 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker |
| **opencode-skill-loader** | 33 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
| **tmux-subagent** | 34 | HIGH | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` |
| **team-mode** | 24 dirs / 100+ files | HIGH | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout |
| **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers |
| **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) |
| **claude-code-plugin-loader** | 16 | MEDIUM | Unified Claude Code plugin discovery (commands, agents, skills, hooks, MCPs) |
| **builtin-skills** | 17 | LOW–MED | 10 built-in skill files (git-master, playwright, frontend-ui-ux, review-work, ai-slop-remover, dev-browser, playwright-cli, **team-mode**, …) |
| **builtin-commands** | 11 | LOW | Command templates: refactor, init-deep, handoff, ulw-loop, etc. |
| **claude-tasks** | 7 | MEDIUM | Sisyphus task schema + atomic file storage + OpenCode todo API sync |
| **claude-code-mcp-loader** | 11 | MEDIUM | Tier-2 MCP loader: `.mcp.json` parse + `${VAR}` env expansion |
| **context-injector** | 6 | MEDIUM | AGENTS.md/README.md injection into session context |
| **run-continuation-state** | 5 | LOW | Persistent state for `oh-my-opencode run` continuation across invocations |
| **hook-message-injector** | 5 | MEDIUM | System message injection helper used by hooks |
| **boulder-state** | 5 | LOW | Persistent state for boulder/multi-step operations |
| **task-toast-manager** | 4 | MEDIUM | Task progress notifications |
| **tool-metadata-store** | 3 | LOW | Tool execution metadata cache |
| **claude-code-session-state** | 3 | LOW | Subagent session state tracking |
| **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ |
| **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ |
| **claude-code-command-loader** | 3 | LOW | Load `/commands` from `.opencode/commands/` and Claude Code plugins |
| **claude-code-agent-loader** | 3 | LOW | Load agents from `.opencode/agents/` and Claude Code plugins |
## KEY MODULES
### background-agent (47 files, ~10k LOC)
### background-agent (~10k LOC)
Core orchestration engine. `BackgroundManager` manages task lifecycle:
- States: pending → running → completed/error/cancelled/interrupt
- Concurrency: per-model/provider limits via `ConcurrencyManager` (FIFO queue)
- Polling: 3s interval, completion via idle events + stability detection (10s unchanged)
- States: `pending → running → completed | error | cancelled | interrupt`
- Concurrency: per-key (`${providerID}/${modelID}`) limits via `ConcurrencyManager` (FIFO queue)
- Polling: 3s interval, completion detected via idle event AND stability detection (10s unchanged)
- Circuit breaker: automatic failure detection and recovery
- spawner/: 8 focused files composing via `SpawnerContext` interface
- `spawner/`: 8 focused files composing via `SpawnerContext` interface
### opencode-skill-loader (33 files, ~3.2k LOC)
### team-mode (~13k LOC)
Parallel multi-agent coordination, OFF by default. Subdirs:
- `team-registry/` — load/validate `~/.omo/teams/{name}/config.json`
- `team-state-store/` — durable runtime state with atomic locks
- `team-runtime/` — `team_create`, status, shutdown lifecycle
- `team-mailbox/` — async messaging (send/poll/ack)
- `team-tasklist/` — shared tasks with atomic claiming
- `team-worktree/` — git worktree per member
- `team-layout-tmux/` — optional tmux pane visualization
- `tools/` — 12 `team_*` tool implementations
Eligible members: sisyphus, atlas, sisyphus-junior, hephaestus only. See [`team-mode/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/AGENTS.md).
### opencode-skill-loader (~3.2k LOC)
4-scope skill discovery (project > opencode > user > global):
- YAML frontmatter parsing from SKILL.md files
- Skill merger with priority deduplication
- Template resolution with variable substitution
- Provider gating for model-specific skills
### tmux-subagent (34 files, ~3.6k LOC)
### tmux-subagent (~3.6k LOC)
State-first tmux integration:
- `TmuxSessionManager`: pane lifecycle, grid planning
- Spawn action decider + target finder
- Polling manager for session health
- Event handlers for pane creation/destruction
State-first tmux integration. Centralized tmux command execution through `src/shared/tmux/runner.ts` (`runTmuxCommand`). Direct `Bun.spawn(["tmux", ...])` is FORBIDDEN — would drift from retry/timeout discipline.
### builtin-skills (8 skill objects)
### builtin-skills (10 skills)
| Skill | Size | MCP | Tools |
|-------|------|-----|-------|
| git-master | 1111 LOC | — | Bash |
| playwright | 312 LOC | @playwright/mcp | — |
| agent-browser | (in playwright.ts) | — | Bash(agent-browser:*) |
| playwright-cli | 268 LOC | — | Bash(playwright-cli:*) |
| dev-browser | 221 LOC | — | Bash |
| frontend-ui-ux | 79 LOC | — | — |
| review-work | ~LOC | --- | --- |
| ai-slop-remover | ~LOC | --- | --- |
| Skill | LOC | MCP | Notes |
|-------|-----|-----|-------|
| git-master | 1111 | — | Atomic commits, rebase, history search |
| playwright | 312 | @playwright/mcp | Browser automation via MCP |
| playwright-cli | 268 | — | Browser automation via CLI |
| dev-browser | 221 | — | Persistent page state browser |
| review-work | ~500 | — | 5-agent post-implementation review orchestrator |
| ai-slop-remover | ~300 | — | Remove AI code patterns |
| **team-mode** | — | — | Loaded only when `team_mode.enabled` (skill explains the 12 tools to agents) |
| frontend-ui-ux | 79 | — | Design-first UI development |
| (git-master-skill-metadata) | — | — | Companion to git-master |
Browser variant selected by `browserProvider` config: playwright (default) | playwright-cli | agent-browser.
Browser variant selected by `browser_automation_engine` config: `playwright` (default) | `playwright-cli` | `agent-browser`.
src/features/background-agent/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/background-agent/ — Core Orchestration Engine
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
src/features/builtin-skills/AGENTS.md
+60 -29
View File
@@ -1,50 +1,81 @@
# src/features/builtin-skills/ -- 8 Built-in Skills
# src/features/builtin-skills/ — 10 Built-in Skill Files
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
24 files. 8 built-in skills registered via `createBuiltinSkills()`. Each skill implements `BuiltinSkill` interface with name, description, content, and optional MCP config.
Skills shipped inside the plugin (always available, no install). Registered via `createBuiltinSkills()`. Each skill implements the `BuiltinSkill` interface with name, description, content, and optional MCP config. Loaded by `opencode-skill-loader` with priority: project > opencode > user > **builtin**. User-installed skills with the same name override built-ins.
## STRUCTURE
```
builtin-skills/
├── index.ts # Barrel exports
├── skills.ts # createBuiltinSkills() factory
├── skills.ts # createBuiltinSkills() factory — registers all 10 below
├── types.ts # BuiltinSkill interface
├── git-master/ # SKILL.md + resources
├── frontend-ui-ux/ # SKILL.md
├── agent-browser/ # SKILL.md
├── dev-browser/ # SKILL.md
└── skills/ # Skill implementations as .ts files
├── git-master-sections/ # Git master prompt sections
├── playwright.ts # Playwright + agent-browser + playwright-cli + dev-browser
├── frontend-ui-ux.ts # Frontend UI/UX skill
├── review-work.ts # 5-agent parallel review orchestrator
└── ai-slop-remover.ts # AI code smell remover
├── skills/
│ ├── git-master.ts # 1111 LOC
│ ├── git-master-skill-metadata.ts # Companion to git-master
│ ├── playwright.ts # MCP variant + agent-browser
│ ├── playwright-cli.ts # CLI variant
│ ├── dev-browser.ts # Persistent page state
│ ├── frontend-ui-ux.ts # Design-first UI guidance
│ ├── review-work.ts # 5-agent post-implementation review
│ ├── ai-slop-remover.ts # Remove AI-generated code patterns
│ ├── team-mode.ts # 12 team_* tool documentation (gated)
│ ├── git-master-sections/ # Git-master prompt sub-sections
│ └── index.ts # skill barrel
├── git-master/ # Resources for git-master skill
├── frontend-ui-ux/ # Resources for frontend-ui-ux skill
├── agent-browser/ # Resources for agent-browser variant
└── dev-browser/ # Resources for dev-browser
```
## SKILL CATALOG
| Skill | LOC | MCP | Purpose |
|-------|-----|-----|---------|
| **git-master** | 1111 | -- | Atomic commits, rebase, history search |
| **playwright** | 312 | @playwright/mcp | Browser automation via MCP |
| **playwright-cli** | 268 | -- | Browser automation via CLI |
| **agent-browser** | (in playwright.ts) | -- | Browser via agent-browser tool |
| **dev-browser** | 221 | -- | Persistent page state browser |
| **frontend-ui-ux** | 79 | -- | Design-first UI development |
| **review-work** | ~500 | -- | 5-agent post-implementation review |
| **ai-slop-remover** | ~300 | -- | Remove AI code patterns |
| Skill | Approx LOC | MCP | Notes |
|-------|------------|-----|-------|
| `git-master` | 1111 | — | Atomic commits, rebase, history search; included by default for delegate-task `git` category |
| `playwright` | 312 | `@playwright/mcp` | Browser automation via MCP |
| `playwright-cli` | 268 | — | Browser automation via shell CLI (no MCP) |
| `agent-browser` | (in playwright.ts) | — | Browser via `agent-browser:*` Bash commands |
| `dev-browser` | 221 | — | Persistent page state browser for dev work |
| `frontend-ui-ux` | 79 | — | Design-first UI development guidance |
| `review-work` | ~500 | — | Post-implementation review orchestrator (5 parallel agents) |
| `ai-slop-remover` | ~300 | — | Remove AI-generated code smells |
| `team-mode` | — | — | **Conditional** — only loaded when `team_mode.enabled`; documents the 12 `team_*` tools and lifecycle |
## BROWSER VARIANT SELECTION
Config `browser_automation_engine` selects which browser skill loads:
- `"playwright"` (default) -> playwright with @playwright/mcp
- `"playwright-cli"` -> CLI-based playwright
- `"agent-browser"` -> agent-browser tool
## SKILL LOADING
| Value | Skill Loaded |
|-------|-------------|
| `"playwright"` (default) | playwright (MCP-backed) |
| `"playwright-cli"` | playwright-cli (CLI-backed) |
| `"agent-browser"` | agent-browser (in playwright.ts) |
Skills loaded by `opencode-skill-loader` with priority: project > opencode > user > builtin. User-installed skills with same name override built-ins.
Only one browser skill is active per session — non-selected variants are skipped.
## TEAM-MODE SKILL GATING
The `team-mode` skill is registered unconditionally but only **rendered** when `team_mode.enabled: true`:
```typescript
// skills/team-mode.ts (paraphrase)
const teamModeSkill: BuiltinSkill = {
name: "team-mode",
shouldLoad: (config) => config.team_mode?.enabled === true,
// ...
}
```
When disabled, the skill is filtered out before agent prompt assembly so agents do not see `team_*` tool docs they cannot use.
## ADDING A NEW BUILT-IN SKILL
1. Create `skills/{name}.ts` exporting a `BuiltinSkill` object
2. Register in `skills.ts` `createBuiltinSkills()` factory
3. Add resources (if any) under a sibling directory: `{name}/SKILL.md`, prompt sections, etc.
4. If the skill is conditional, set `shouldLoad: (config) => …`
5. Optionally declare an MCP server in the skill (loaded by `skill-mcp-manager` per session)
src/features/claude-code-mcp-loader/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
**Generated:** 2026-04-18
**Generated:** 2026-05-08
## OVERVIEW
src/features/claude-code-plugin-loader/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/claude-code-plugin-loader/ — Unified Claude Code Plugin Loader
**Generated:** 2026-04-18
**Generated:** 2026-05-08
## OVERVIEW
src/features/claude-tasks/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/claude-tasks/ — Task Schema + Storage
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
src/features/mcp-oauth/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
src/features/opencode-skill-loader/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/opencode-skill-loader/ — 4-Scope Skill Discovery
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
src/features/skill-mcp-manager/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/skill-mcp-manager/ — Skill-Embedded MCP Client Lifecycle
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW
src/features/team-mode/AGENTS.md
+133 -65
View File
@@ -1,92 +1,160 @@
# team-mode — Parallel Multi-Agent Coordination
**Generated:** 2026-04-18
**Generated:** 2026-05-08
## 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, optional tmux layout, and graceful lifecycle. Modeled after Claude Code Agent Teams. **OFF by default.** Enable via `team_mode.enabled` in `oh-my-opencode.jsonc`; restart OpenCode after enabling.
Spawns coordinated agent teams with shared mailbox, task list, and lifecycle management. Lead delegates, members claim tasks, graceful shutdown with acks.
User docs: [`docs/guide/team-mode.md`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/team-mode.md).
## CONFIG
```jsonc
{
"team_mode": {
"enabled": true,
"max_parallel_members": 4, // concurrent active members
"max_members": 8, // hard cap on team size
"tmux_visualization": false // optional tmux pane layout
}
}
```
Schema: [`src/config/schema/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/team-mode.ts).
## 12 TEAM_* TOOLS
Registered via [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) `teamModeToolsRecord` only when enabled.
| Tool | Source File | Purpose |
|------|-------------|---------|
| `team_create` | `tools/lifecycle.ts` | Spawn team + member sessions from named or inline TeamSpec |
| `team_delete` | `tools/lifecycle.ts` | Tear down state, mailbox, tasklist, worktrees, optional tmux |
| `team_shutdown_request` | `tools/lifecycle.ts` | Member or lead requests its own shutdown |
| `team_approve_shutdown` | `tools/lifecycle.ts` | Lead acks shutdown |
| `team_reject_shutdown` | `tools/lifecycle.ts` | Lead rejects shutdown with reason |
| `team_send_message` | `tools/messaging.ts` | Send to member name or `*` broadcast |
| `team_task_create` | `tools/tasks.ts` | Create task on shared list |
| `team_task_list` | `tools/tasks.ts` | List tasks (filter by status / owner) |
| `team_task_update` | `tools/tasks.ts` | Claim / complete / delete (atomic file lock) |
| `team_task_get` | `tools/tasks.ts` | Fetch single task |
| `team_status` | `tools/query.ts` | Full team run status (members, tasks, mailbox) |
| `team_list` | `tools/query.ts` | List declared + active teams |
## ELIGIBLE AGENTS
```
ALLOWED: sisyphus, atlas, sisyphus-junior, hephaestus
REJECTED at parse: oracle, librarian, explore, multimodal-looker, metis, momus, prometheus
```
Read-only and orchestration-only agents are blocked at TeamSpec parse time. For those, the lead delegates via `task` (delegate-task) instead.
Eligibility registry: [`types.ts`](file:///Users/yeongyu/local-workspaces/omo/src/features/team-mode/types.ts) `AGENT_ELIGIBILITY_REGISTRY`.
## MEMBER KINDS
```jsonc
{
"members": [
{ "kind": "subagent_type", "name": "scout", "subagent_type": "sisyphus" },
{ "kind": "category", "name": "writer", "category": "writing", "prompt": "Write release notes" }
]
}
```
- `kind: "subagent_type"` — direct agent. `prompt` optional.
- `kind: "category"` — routed through `sisyphus-junior` with the chosen category model. `prompt` REQUIRED.
## 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
├── index.ts # barrel
├── types.ts # Zod schemas: TeamSpec, Member, Message, Task, RuntimeState; AGENT_ELIGIBILITY_REGISTRY
├── deps.ts # checkTeamModeDependencies (git, tmux availability)
├── member-parser.ts # member validation against eligibility registry
├── member-guidance.ts # auto-injected guidance per member kind
├── member-session-resolution.ts
├── member-session-routing.ts
├── resolve-caller-team-lead.ts # determine if a session is acting as lead
├── team-session-registry.ts # spawn-race-safe sessionID → team/member lookups
├── team-registry/ # team spec loading from ~/.omo/teams/{name}/config.json
│ ├── loader.ts
│ ├── paths.ts # ensureBaseDirs, resolveBaseDir
│ └── validator.ts
├── team-state-store/ # durable runtime state.json with atomic locks
├── team-runtime/ # create/status/shutdown lifecycle
├── team-mailbox/ # async messaging (send / poll / ack / inbox)
├── team-tasklist/ # CRUD + claiming + dependencies
├── team-worktree/ # one git worktree per member; cleanup on delete
├── team-layout-tmux/ # optional pane layout — close-team-member-pane, sweep-stale-team-sessions
└── tools/ # 12 team_* tool implementations + tests
```
## STORAGE LAYOUT
See user guide: `docs/guide/team-mode.md`
```
~/.omo/teams/{name}/ # user scope
<project>/.omo/teams/{name}/ # project scope (wins on collision)
├── config.json # TeamSpec
├── state.json # runtime: members, sessionIDs, lifecycle
├── mailbox/ # one .jsonl per recipient
├── tasklist.jsonl # shared task list
└── worktrees/{member-name}/ # git worktree per member
```
## LIFECYCLE
```
1. team_create
→ load TeamSpec → validate eligibility → spawn member sessions
→ init mailbox + tasklist + worktrees → optional tmux layout
2. Lead delegates via team_send_message + team_task_create
3. Members claim tasks (team_task_update status="claimed") → execute → report (team_send_message)
4. team_shutdown_request → team_approve_shutdown / team_reject_shutdown
5. team_delete → cleanup state, mailbox, tasklist, worktrees, panes
```
## 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.
1. **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.
2. **Deferred ack:** messages are fire-and-forget; recipient acks via separate call.
3. **Locked tasks:** task claiming uses atomic file locks; concurrent claims resolve safely.
4. **Atomic writes:** state changes write to temp file then rename.
5. **Eligible agents only:** rejection at parse, never at runtime.
6. **No nested teams:** members CANNOT call `team_create`.
## INTEGRATION POINTS
| Where | What |
|-------|------|
| [`src/index.ts`](file:///Users/yeongyu/local-workspaces/omo/src/index.ts) (entry) | `checkTeamModeDependencies()` + `ensureBaseDirs()` if `team_mode.enabled` |
| [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) | `teamModeToolsRecord` gate registers 12 tools |
| `src/hooks/team-mode-status-injector/` | Injects `<team_mode_status>` block into messages |
| `src/hooks/team-mailbox-injector/` | Pulls pending mailbox messages into agent context |
| `src/hooks/team-session-events/` | React to member session lifecycle |
| `src/hooks/team-tool-gating/` | Restrict `team_*` tools by member role |
| [`src/cli/doctor/checks/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/cli/doctor/checks/team-mode.ts) | Doctor check for team-mode prerequisites |
| [`src/features/builtin-skills/skills/team-mode.ts`](file:///Users/yeongyu/local-workspaces/omo/src/features/builtin-skills/skills/team-mode.ts) | Built-in skill that documents the tools — only loaded when enabled |
## WHERE TO LOOK
| Task | Location |
|------|----------|
| Add new team tool | `tools/` + register in `index.ts` |
| Modify member eligibility | `types.ts` AGENT_ELIGIBILITY_REGISTRY |
| Add new team tool | `tools/` + register in [`src/plugin/tool-registry.ts`](file:///Users/yeongyu/local-workspaces/omo/src/plugin/tool-registry.ts) `teamModeToolsRecord` |
| Modify member eligibility | `types.ts` `AGENT_ELIGIBILITY_REGISTRY` |
| Change storage format | `types.ts` Zod schemas |
| Add worktree features | `team-worktree/manager.ts` |
| Add worktree behavior | `team-worktree/manager.ts` |
| Modify tmux layout | `team-layout-tmux/layout.ts` |
| Task lifecycle changes | `team-tasklist/` |
| Mailbox protocol changes | `team-mailbox/` |
| Recover orphaned runs | `team-state-store/resume.ts` |
## ANTI-PATTERNS
- Never bypass `team-session-registry` — direct `loadRuntimeState` lookups will hit the spawn-race window.
- Never write team state files without the atomic lock from `team-state-store/locks.ts`.
- Never substitute `task` (delegate-task) for `team_*` tools when the user explicitly asks for team-mode work — they are not equivalent.
- Never allow members to call `team_create` (nested teams are forbidden by `team-tool-gating` hook).
src/features/tmux-subagent/AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# src/features/tmux-subagent/ — Tmux Pane Management
**Generated:** 2026-04-11
**Generated:** 2026-05-08
## OVERVIEW