AGENTS.md

1# src/features/ — 23 Feature Modules
2 
3**Generated:** 2026-08-07
4 
5## OVERVIEW
6 
7Standalone feature modules wired into `plugin/` layer. Each is self-contained with own types, implementation, and co-located tests. Several directories now provide OpenCode adapter shims over extracted Core packages; keep those shim paths stable unless the plugin wiring is moved at the same time.
8 
9## MODULE MAP
10 
11| Module | Complexity | Has sub-AGENTS.md | Purpose |
12|--------|------------|-------------------|---------|
13| **team-mode** | HIGH | yes | Parallel multi-agent coordination — 12 `team_*` tools; domain primitives live in `packages/team-core/` with OpenCode runtime/session wiring here |
14| **background-agent** | HIGH | yes | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker. Newer files include `parent-wake-notifier.ts`, `loop-detector`, `error-classifier`, `fallback-retry-handler`, `process-cleanup`, `subagent-spawn-limits`, `session-status-classifier`, and `compaction-aware-message-resolver`. |
15| **tmux-subagent** | HIGH | yes | Tmux pane management, grid planning, session orchestration via `runTmuxCommand`; reusable tmux primitives live in `packages/tmux-core/` |
16| **opencode-skill-loader** | HIGH | yes | OpenCode adapter for YAML frontmatter skill discovery; reusable loader primitives live in `packages/skills-loader-core/` |
17| **builtin-skills** | LOW–MED | yes | Built-in skill files (git-master, playwright, frontend, review-work, remove-ai-slops, init-deep, security-research, security-review, dev-browser, playwright-cli, **team-mode**, …) |
18| **skill-mcp-manager** | HIGH | yes | OpenCode adapter for tier-3 MCP client lifecycle; reusable client/OAuth primitives live in `packages/mcp-client-core/` |
19| **claude-code-plugin-loader** | MEDIUM | yes | OpenCode adapter for Claude Code plugin discovery; reusable compatibility loaders live in `packages/claude-code-compat-core/` |
20| **builtin-commands** | LOW | yes | Command templates: refactor, init-deep, handoff, ulw-loop, etc. |
21| **mcp-oauth** | HIGH | yes | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers |
22| **claude-code-agent-loader** | LOW | yes | OpenCode adapter for agents from `.opencode/agents/` and Claude Code plugins; shared loader lives in `packages/claude-code-compat-core/` |
23| **claude-code-mcp-loader** | MEDIUM | yes | OpenCode adapter for tier-2 MCP loader; `.mcp.json` parse + `${VAR}` env expansion live in `packages/claude-code-compat-core/` |
24| **tool-metadata-store** | LOW–MED | no | Tool execution metadata cache; publish/recover lifecycle + task metadata contract |
25| **boulder-state** | LOW | yes | Persistent state for boulder (active work plan tracking across sessions/worktrees) |
26| **context-injector** | LOW | no | AGENTS.md/README.md injection into session context |
27| **hook-message-injector** | LOW | no | System message injection helper used by hooks |
28| **run-continuation-state** | LOW | no | Persistent state for `oh-my-opencode run` continuation across invocations |
29| **opencode-runtime-skills** | LOW–MED | no | Runtime security-skill source — `selectRuntimeSecuritySkills()` + `createRuntimeSkillSourceServer()` serve security skills to sessions at runtime |
30| **claude-code-command-loader** | LOW | no | Load `/commands` from `.opencode/commands/` and Claude Code plugins |
31| **claude-tasks** | MEDIUM | yes | Sisyphus task schema + atomic file storage + OpenCode todo API sync |
32| **task-toast-manager** | MEDIUM | no | Task progress notifications |
33| **claude-code-session-state** | LOW | no | Subagent session state tracking |
34| **monitor** | MEDIUM | no | `monitor_*` tools backend: managed watcher processes, line filtering, ring buffer, batched output injection (gated on `monitor.enabled`) |
35| **tui-sidebar** | MEDIUM | no | TUI sidebar snapshot builder + mirror manager (roster/state derivers rendered into the OpenCode TUI; gated on `tui.sidebar.enabled`) |
36 
37## KEY MODULES
38 
39### background-agent
40 
41Core orchestration engine. `BackgroundManager` manages task lifecycle:
42- States: `pending → running → completed | error | cancelled | interrupt`
43- Concurrency: per-key (`${providerID}/${modelID}`) limits via `ConcurrencyManager` (FIFO queue)
44- Polling: 3s interval, completion detected via idle event AND stability detection (10s unchanged)
45- Circuit breaker: automatic failure detection and recovery in `manager-circuit-breaker.test.ts`
46- `spawner/`: focused files composing via `SpawnerContext` interface
47- Parent-wake state extracted to `parent-wake-notifier.ts` (587 LOC, dependency-injected client + enqueue callback)
48 
49### team-mode (~13k LOC)
50 
51Parallel multi-agent coordination, OFF by default. Harness-neutral domain primitives are extracted to `packages/team-core/`; this directory owns OpenCode-specific spawning, tool registration, and hook integration. Subdirs:
52- `team-registry/` — load/validate `~/.omo/teams/{name}/config.json`
53- `team-state-store/` — durable runtime state with atomic locks
54- `team-runtime/` — `team_create`, status, shutdown lifecycle
55- `team-mailbox/` — async messaging (send/poll/ack)
56- `team-tasklist/` — shared tasks with atomic claiming
57- `team-worktree/` — git worktree per member
58- `team-layout-tmux/` — optional tmux pane visualization
59- `tools/` — 12 `team_*` tool implementations
60 
61Eligible members: sisyphus, atlas, sisyphus-junior, hephaestus only. See [`team-mode/AGENTS.md`](team-mode/AGENTS.md).
62 
63### opencode-skill-loader (~2.8k LOC)
64 
654-scope skill discovery (project > opencode > user > global):
66- YAML frontmatter parsing from SKILL.md files
67- Skill merger with priority deduplication
68- Provider gating for model-specific skills
69 
70### tmux-subagent (~3.6k LOC)
71 
72State-first tmux integration. Shared tmux primitives are extracted to `packages/tmux-core/`, while this feature owns OpenCode session tracking and pane decisions. Centralized tmux command execution goes through the shared runner. Direct `Bun.spawn(["tmux", ...])` is FORBIDDEN — would drift from retry/timeout discipline.
73 
74### builtin-skills (12 skills)
75 
76| Skill | LOC | MCP | Notes |
77|-------|-----|-----|-------|
78| git-master | 1111 | — | Atomic commits, rebase, history search |
79| playwright | 312 | @playwright/mcp | Browser automation via MCP |
80| playwright-cli | 268 | — | Browser automation via CLI |
81| dev-browser | 221 | — | Persistent page state browser |
82| review-work | ~500 | — | 5-agent post-implementation review orchestrator |
83| $omo:remove-ai-slops | — | — | Remove AI code patterns |
84| init-deep | — | — | Hierarchical AGENTS.md generation |
85| security-research | SKILL.md | — | Team Mode exploitability-driven security research |
86| security-review | wrapper | — | Alias for security-research |
87| **team-mode** | — | — | Loaded only when `team_mode.enabled` (skill explains the 12 tools to agents) |
88| frontend | 79 | — | Design-first UI development |
89| (git-master-skill-metadata) | — | — | Companion to git-master |
90 
91Browser variant selected by `browser_automation_engine` config: `playwright` (default) | `playwright-cli` | `agent-browser`.
92