docs(agents): regenerate hierarchical AGENTS.md for 2026-05-20
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
@@ -2,11 +2,11 @@
|
||||
|
||||
> **HOLD THE FUCK UP. THIS ENTIRE GODDAMN CODEBASE IS BEING RIPPED APART AND REBUILT RIGHT NOW. A MASSIVE MULTI-HARNESS AGENT OS REFACTOR IS IN PROGRESS — WE ARE RESTRUCTURING EVERYTHING TO SUPPORT MULTIPLE AGENT HARNESSES (OPENCODE, CODEX, PI, AND OTHERS). DO NOT TRUST THE STRUCTURE BELOW AS STABLE. READ THE [ROADMAP](./ROADMAP.md) BEFORE YOU TOUCH ANYTHING OR SO HELP ME GOD.**
|
||||
|
||||
**Generated:** 2026-05-18 | **Commit:** 4d417a33b | **Branch:** dev | **Release:** v4.2.0
|
||||
**Generated:** 2026-05-20 | **Commit:** 39aadbf9f | **Branch:** dev | **Release:** v4.2.0
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 59 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains 2165 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~314k LOC; `src/` itself has 122 barrel `index.ts` files.** Entry: `src/index.ts` is now an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init.
|
||||
OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 57 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains ~2167 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~313k LOC; `src/` itself has 120 barrel `index.ts` files.** Entry: `src/index.ts` is an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
@@ -15,24 +15,24 @@ oh-my-opencode/
|
||||
├── src/
|
||||
│ ├── index.ts # Plugin entry; thin wrapper that re-exports `createPluginModule()` from `src/testing/`
|
||||
│ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4)
|
||||
│ ├── plugin-interface.ts # 10 OpenCode hook handlers
|
||||
│ ├── plugin-interface.ts # 11 OpenCode hook handlers (+2 wired in src/testing/create-plugin-module.ts)
|
||||
│ ├── create-managers.ts # 4 managers (Tmux, Background, SkillMcp, ConfigHandler)
|
||||
│ ├── create-tools.ts # ToolRegistry composition
|
||||
│ ├── create-hooks.ts # 5-tier hook composition
|
||||
│ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
|
||||
│ ├── hooks/ # ~52 lifecycle hooks across 59 dirs (incl. 5 zauc-mocks + 1 shared + 1 `.sisyphus/` legacy state)
|
||||
│ ├── hooks/ # ~52 lifecycle hooks across 57 dirs (incl. 5 zauc-mocks + 1 shared + 1 `.sisyphus/` legacy state + 1 `team-session-events/`; 2 unwired WIP: `task-reminder/`, `hashline-edit-diff-enhancer/`)
|
||||
│ ├── tools/ # 13 native tool dirs; LSP + AST-grep now served via built-in MCPs
|
||||
│ ├── features/ # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, opencode-skill-loader, tmux-subagent, mcp-oauth, claude-code-plugin-loader, boulder-state, etc.)
|
||||
│ ├── shared/ # 278 utility files (170 non-test); logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups)
|
||||
│ ├── shared/ # 297 utility files (179 non-test); logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups)
|
||||
│ ├── config/ # Zod v4 schema system (30 schema files)
|
||||
│ ├── cli/ # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, boulder
|
||||
│ ├── mcp/ # 5 built-in MCPs (3 remote + local stdio lsp + ast_grep)
|
||||
│ ├── plugin/ # 10 OpenCode hook handlers + 5-tier hook composition
|
||||
│ ├── plugin/ # 11 OpenCode hook handlers + 5-tier hook composition
|
||||
│ ├── plugin-handlers/ # 6-phase config loading pipeline
|
||||
│ ├── openclaw/ # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon)
|
||||
│ ├── generated/ # model-capabilities.generated.json (refreshed via build:model-capabilities)
|
||||
│ └── testing/ # Test utilities + `create-plugin-module.ts` (extracted plugin entry factory, 182 LOC)
|
||||
├── packages/ # 11 platform-specific binary packages, lsp-tools-mcp submodule, and web package
|
||||
├── packages/ # 11 platform-specific binary packages + lsp-tools-mcp submodule + ast-grep-mcp + rules-core + web
|
||||
│ └── web/ # Marketing site (Next.js 15 + Cloudflare Workers). Independent package with own bun.lock
|
||||
├── bin/ # Platform-detection JS shim (oh-my-opencode + oh-my-openagent)
|
||||
├── script/ # Build/publish automation (singular, not scripts/)
|
||||
@@ -62,7 +62,7 @@ pluginModule.server(input, options)
|
||||
├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
|
||||
├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry
|
||||
├─→ createHooks() # 5-tier: Session + ToolGuard + Transform + Continuation + Skill
|
||||
└─→ createPluginInterface() # 10 OpenCode hook handlers → PluginInterface
|
||||
└─→ createPluginInterface() # 11 OpenCode hook handlers → PluginInterface
|
||||
```
|
||||
|
||||
## 13 OPENCODE HOOK HANDLERS
|
||||
@@ -269,7 +269,7 @@ bunx oh-my-opencode mcp-oauth login <server-url> # Tier-3 MCP OAuth (PKCE + DCR
|
||||
- **Config migration:** idempotent via `_migrations` tracking, atomic writes with timestamped backups.
|
||||
- **Build:** `bun build` (ESM) + `tsc --emitDeclarationOnly`, externals: `@ast-grep/napi`, `zod`.
|
||||
- **CI tests:** root tests run through plain `bun test`; `packages/web/**` has its own package-level CI workflow.
|
||||
- **122 barrel `index.ts` files** establish module boundaries.
|
||||
- **120 barrel `index.ts` files** establish module boundaries.
|
||||
- **Architecture rules** enforced via the `rules-injector` hook reading `.omo/rules/*.md`. As of v4.2.0 only `test-discipline.md` ships; legacy `modular-code-enforcement.md` was retired.
|
||||
- **Windows builds:** run on `windows-latest` (not cross-compiled) to avoid Bun segfaults.
|
||||
- **Platform binaries:** detect AVX2 + libc family at runtime, fallback to baseline if needed.
|
||||
@@ -280,7 +280,7 @@ bunx oh-my-opencode mcp-oauth login <server-url> # Tier-3 MCP OAuth (PKCE + DCR
|
||||
- **Docs:** see [`docs/guide/`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/) for user-facing guides (overview, installation, orchestration, agent-model-matching, team-mode), [`docs/reference/`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/) for CLI/configuration/features reference. v4.2.0+ adds [`CHANGELOG.md`](file:///Users/yeongyu/local-workspaces/omo/CHANGELOG.md), [`docs/reference/known-issues.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/known-issues.md), [`docs/reference/prompt-async-gate-rfc.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/prompt-async-gate-rfc.md), and [`docs/reference/release-process.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/release-process.md).
|
||||
- **Rules files** (auto-injected by `rules-injector` hook): [`.omo/rules/modular-code-enforcement.md`](file:///Users/yeongyu/local-workspaces/omo/.omo/rules/modular-code-enforcement.md) + [`.omo/rules/test-discipline.md`](file:///Users/yeongyu/local-workspaces/omo/.omo/rules/test-discipline.md) (forbids `setTimeout(resolve, N)` / `await sleep(N)` in tests unless time IS the SUT). Scans `.omo/rules/`, `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, plus `.github/copilot-instructions.md` and `.mdc` files.
|
||||
- **Process cleanup:** Background-agent error handlers are now log-only — no force-exit on transient errors. Opt out entirely via `OMO_DISABLE_PROCESS_CLEANUP=1` env var.
|
||||
- **First-prompt watchdog:** `src/hooks/runtime-fallback/first-prompt-watchdog.ts` (193 LOC) detects subagent sessions producing no progress within 90s and triggers fallback / abort.
|
||||
- **ParentWakeNotifier:** Background-agent parent-wake state extracted to `src/features/background-agent/parent-wake-notifier.ts` (432 LOC) with dependency-injected client and enqueue callback.
|
||||
- **First-prompt watchdog:** `src/hooks/runtime-fallback/first-prompt-watchdog.ts` (206 LOC) detects subagent sessions producing no progress within 90s and triggers fallback / abort.
|
||||
- **ParentWakeNotifier:** Background-agent parent-wake state extracted to `src/features/background-agent/parent-wake-notifier.ts` (587 LOC) with dependency-injected client and enqueue callback.
|
||||
- **Workspace migration:** Runtime state migrated from `.sisyphus/` → `.omo/`. Legacy `.sisyphus/` still exists during transition; `src/shared/legacy-workspace-migration.ts` copies it forward on first load.
|
||||
- **CI nuance:** PRs targeting `master` are hard-blocked — they MUST target `dev`. CI auto-commits schema changes on master push and creates a draft "next" release on dev push.
|
||||
|
||||
Reference in New Issue
Block a user