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

docs(agents): regenerate hierarchical AGENTS.md for 2026-05-20

Browse Source 
Sync the AGENTS.md hierarchy to current code state:

Drift fixes in 11 existing files
- Root: 2026-05-20 commit 39aadbf9f, ~2167 TS files, 120 barrel index.ts,
  57 src/hooks dirs, 297 (179 non-test) src/shared files, 11 OpenCode hook
  handlers in plugin-interface.ts, packages list adds ast-grep-mcp + rules-core,
  first-prompt-watchdog 206 LOC, parent-wake-notifier 587 LOC
- src/AGENTS.md: file counts, plugin-interface handler count
- src/shared/AGENTS.md: title + counts 278/170 -> 297/179
- src/hooks/AGENTS.md: 57 dirs, note unwired WIP (task-reminder,
  hashline-edit-diff-enhancer)
- src/features/AGENTS.md: module map with NON-TEST counts + sub-AGENTS.md
  column, 7 modules without sub-doc
- src/features/background-agent/AGENTS.md: add 12 newer files (parent-wake-
  notifier 587 LOC, loop-detector, error-classifier, fallback-retry-handler,
  process-cleanup, subagent-spawn-limits, session-status-classifier,
  compaction-aware-message-resolver, etc.)
- src/plugin/AGENTS.md: 11 handlers, add system-transform.ts + command-
  execute-before.ts + build-team-idle-wake-hint-client.ts
- src/config/AGENTS.md: note schema/internal/permission.ts
- src/cli/AGENTS.md: 8 commands including 'version'
- src/plugin-handlers/AGENTS.md, packages/web/AGENTS.md: date bump

New AGENTS.md in 4 directories
- packages/AGENTS.md: index of 15 packages (11 platform binaries + 2 MCP
  packages + rules-core + web), role map, conventions
- docs/AGENTS.md: WHERE TO LOOK table for 19 docs across 6 subdirs
- .opencode/AGENTS.md: 5 skills + 4 slash commands + relationship to .agents/
- .agents/AGENTS.md: superset migration target (9 skills + 4 commands)
This commit is contained in:
YeonGyu-Kim
2026-05-20 17:18:44 +09:00
parent 39aadbf9f0
commit 330e437f08
15 changed files with 314 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/features/AGENTS.md
+29 -26
View File
@@ -1,6 +1,6 @@
# src/features/ — 20 Feature Modules
**Generated:** 2026-05-15
**Generated:** 2026-05-20
## OVERVIEW
@@ -8,39 +8,42 @@ Standalone feature modules wired into `plugin/` layer. Each is self-contained wi
## MODULE MAP
| Module | Files | Complexity | Purpose |
|--------|-------|------------|---------|
| **background-agent** | 57 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker, archive fallback |
| **opencode-skill-loader** | 30 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
| **tmux-subagent** | 32 | 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/` and Claude Code plugins |
| **claude-code-agent-loader** | 3 | LOW | Load agents from `.opencode/agents/` and Claude Code plugins |
File counts are NON-TEST `.ts` files only (test files co-located but excluded from the count).
| Module | Files | Complexity | Has sub-AGENTS.md | Purpose |
|--------|-------|------------|-------------------|---------|
| **team-mode** | 60 / 8 subdirs | HIGH | yes | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout |
| **background-agent** | 30 / 1 subdir (spawner/) | HIGH | yes | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker. Newer files: `parent-wake-notifier.ts` (587 LOC), `loop-detector`, `error-classifier`, `fallback-retry-handler`, `process-cleanup`, `subagent-spawn-limits`, `session-status-classifier`, `compaction-aware-message-resolver`. |
| **tmux-subagent** | 27 | HIGH | yes | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` |
| **opencode-skill-loader** | 25 / 1 subdir (merger/) | HIGH | yes | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
| **builtin-skills** | 18 / 5 subdirs | LOW–MED | yes | 10 built-in skill files (git-master, playwright, frontend-ui-ux, review-work, ai-slop-remover, dev-browser, playwright-cli, **team-mode**, …) |
| **skill-mcp-manager** | 11 | HIGH | yes | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) |
| **claude-code-plugin-loader** | 11 | MEDIUM | yes | Unified Claude Code plugin discovery (commands, agents, skills, hooks, MCPs) |
| **builtin-commands** | 11 / 1 subdir (templates/) | LOW | yes | Command templates: refactor, init-deep, handoff, ulw-loop, etc. |
| **mcp-oauth** | 10 | HIGH | yes | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers |
| **claude-code-agent-loader** | 7 | LOW | yes | Load agents from `.opencode/agents/` and Claude Code plugins |
| **claude-code-mcp-loader** | 7 | MEDIUM | yes | Tier-2 MCP loader: `.mcp.json` parse + `${VAR}` env expansion |
| **tool-metadata-store** | 6 | LOW–MED | no | Tool execution metadata cache; publish/recover lifecycle + task metadata contract |
| **boulder-state** | 6 | LOW | yes | Persistent state for boulder (active work plan tracking across sessions/worktrees) |
| **context-injector** | 4 | LOW | no | AGENTS.md/README.md injection into session context |
| **hook-message-injector** | 4 | LOW | no | System message injection helper used by hooks |
| **run-continuation-state** | 4 | LOW | no | Persistent state for `oh-my-opencode run` continuation across invocations |
| **claude-code-command-loader** | 4 | LOW | no | Load `/commands` from `.opencode/commands/` and Claude Code plugins |
| **claude-tasks** | 3 | MEDIUM | yes | Sisyphus task schema + atomic file storage + OpenCode todo API sync |
| **task-toast-manager** | 3 | MEDIUM | no | Task progress notifications |
| **claude-code-session-state** | 2 | LOW | no | Subagent session state tracking |
## KEY MODULES
### background-agent (~10k LOC)
### background-agent
Core orchestration engine. `BackgroundManager` manages task lifecycle:
- 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
- Circuit breaker: automatic failure detection and recovery in `manager-circuit-breaker.test.ts`
- `spawner/`: focused files composing via `SpawnerContext` interface
- Parent-wake state extracted to `parent-wake-notifier.ts` (587 LOC, dependency-injected client + enqueue callback)
### team-mode (~13k LOC)
src/features/background-agent/AGENTS.md
+18 -4
View File
@@ -1,10 +1,10 @@
# src/features/background-agent/ — Core Orchestration Engine
**Generated:** 2026-05-15
**Generated:** 2026-05-20
## OVERVIEW
30 files (~10k LOC). Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration.
30 non-test files (62 entries total including tests + spawner/ subdir). Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration.
## TASK LIFECYCLE
@@ -20,11 +20,25 @@ LaunchInput → pending → [ConcurrencyManager queue] → running → polling
| `spawner.ts` | Task spawning: create session → inject prompt → start polling |
| `concurrency.ts` | `ConcurrencyManager` — FIFO queue per concurrency key, slot acquisition/release |
| `task-poller.ts` | 3s interval polling, completion via idle events + stability detection (10s unchanged) |
| `result-handler.ts` | Process completed tasks: extract result, notify parent, cleanup |
| `state.ts` | In-memory task store (Map-based) |
| `types.ts` | `BackgroundTask`, `LaunchInput`, `ResumeInput`, `BackgroundTaskStatus` |
| `parent-wake-notifier.ts` | 587 LOC. Dependency-injected client + enqueue callback. Notifies parent session when a background task wants attention. |
| `loop-detector.ts` | Detects polling/event loops that would otherwise burn budget. |
| `error-classifier.ts` | Maps raw provider errors → `BackgroundTaskError` categories. |
| `fallback-retry-handler.ts` | Coordinates retries with the runtime-fallback system. |
| `process-cleanup.ts` | Best-effort cleanup on parent exit. `OMO_DISABLE_PROCESS_CLEANUP=1` opts out entirely. |
| `subagent-spawn-limits.ts` | Enforces per-parent subagent spawn caps. |
| `session-status-classifier.ts` | Normalizes OpenCode session status across versions. |
| `compaction-aware-message-resolver.ts` | Resolves task result content even across mid-task compaction. |
| `attempt-lifecycle.ts` | Tracks retry attempts on a single task. |
| `task-history.ts` | Append-only history for completed tasks. |
| `session-idle-event-handler.ts` | Bridges OpenCode `session.idle` → task-poller completion signal. |
| `session-existence.ts` | Cheap existence check used by recovery code. |
| `abort-with-timeout.ts` | Force-abort tasks past `syncPollTimeoutMs`. |
| `remove-task-toast-tracking.ts` | Strips lingering toast tracker entries on task end. |
| `background-task-notification-template.ts` | Template for parent-session result injection. |
## SPAWNER SUBDIRECTORY (6 files)
## SPAWNER SUBDIRECTORY
| File | Purpose |
|------|---------|