docs: update AGENTS.md knowledge base (043b1a33)

- Add 7 missing hooks, remove deleted background-compaction
- Update line counts (atlas 572, sisyphus 450, config-manager 664)
- Add 18 undocumented shared utilities, remove stale references
- Add task-toast-manager, remove-deadcode command
- Update test count 90→95, add 4 complexity hotspots
This commit is contained in:
justsisyphus 2026-01-25 13:12:40 +09:00
parent 043b1a3377
commit fd72ce5ce7
7 changed files with 58 additions and 24 deletions

View File

@ -1,7 +1,7 @@
# PROJECT KNOWLEDGE BASE # PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-23T15:59:00+09:00 **Generated:** 2026-01-25T13:10:00+09:00
**Commit:** 599fad0e **Commit:** 043b1a33
**Branch:** dev **Branch:** dev
## OVERVIEW ## OVERVIEW
@ -21,7 +21,7 @@ oh-my-opencode/
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md │ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
│ ├── mcp/ # Built-in MCPs - see src/mcp/AGENTS.md │ ├── mcp/ # Built-in MCPs - see src/mcp/AGENTS.md
│ ├── config/ # Zod schema, TypeScript types │ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (593 lines) │ └── index.ts # Main plugin entry (601 lines)
├── script/ # build-schema.ts, build-binaries.ts ├── script/ # build-schema.ts, build-binaries.ts
├── packages/ # 7 platform-specific binaries ├── packages/ # 7 platform-specific binaries
└── dist/ # Build output (ESM + .d.ts) └── dist/ # Build output (ESM + .d.ts)
@ -36,6 +36,7 @@ oh-my-opencode/
| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts | | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts |
| Add MCP | `src/mcp/` | Create config, add to index.ts | | Add MCP | `src/mcp/` | Create config, add to index.ts |
| Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md | | Add skill | `src/features/builtin-skills/` | Create dir with SKILL.md |
| Add command | `src/features/builtin-commands/` | Add template + register in commands.ts |
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` | | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` |
| Background agents | `src/features/background-agent/` | manager.ts (1335 lines) | | Background agents | `src/features/background-agent/` | manager.ts (1335 lines) |
| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (773 lines) | | Orchestrator | `src/hooks/atlas/` | Main orchestration hook (773 lines) |
@ -60,7 +61,7 @@ oh-my-opencode/
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
- **Exports**: Barrel pattern via index.ts - **Exports**: Barrel pattern via index.ts
- **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
- **Testing**: BDD comments, 90 test files - **Testing**: BDD comments, 95 test files
- **Temperature**: 0.1 for code agents, max 0.3 - **Temperature**: 0.1 for code agents, max 0.3
## ANTI-PATTERNS ## ANTI-PATTERNS
@ -99,7 +100,7 @@ oh-my-opencode/
bun run typecheck # Type check bun run typecheck # Type check
bun run build # ESM + declarations + schema bun run build # ESM + declarations + schema
bun run rebuild # Clean + Build bun run rebuild # Clean + Build
bun test # 90 test files bun test # 95 test files
``` ```
## DEPLOYMENT ## DEPLOYMENT
@ -118,7 +119,11 @@ bun test # 90 test files
| `src/agents/prometheus-prompt.ts` | 1196 | Planning agent | | `src/agents/prometheus-prompt.ts` | 1196 | Planning agent |
| `src/tools/delegate-task/tools.ts` | 1039 | Category-based delegation | | `src/tools/delegate-task/tools.ts` | 1039 | Category-based delegation |
| `src/hooks/atlas/index.ts` | 773 | Orchestrator hook | | `src/hooks/atlas/index.ts` | 773 | Orchestrator hook |
| `src/cli/config-manager.ts` | 641 | JSONC config parsing | | `src/cli/config-manager.ts` | 664 | JSONC config parsing |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactor command template |
| `src/index.ts` | 601 | Main plugin entry |
| `src/tools/lsp/client.ts` | 596 | LSP JSON-RPC client |
| `src/agents/atlas.ts` | 572 | Atlas orchestrator agent |
## MCP ARCHITECTURE ## MCP ARCHITECTURE

View File

@ -8,17 +8,17 @@
``` ```
agents/ agents/
├── atlas.ts # Master Orchestrator (543 lines) ├── atlas.ts # Master Orchestrator (572 lines)
├── sisyphus.ts # Main prompt (615 lines) ├── sisyphus.ts # Main prompt (450 lines)
├── sisyphus-junior.ts # Delegated task executor ├── sisyphus-junior.ts # Delegated task executor (135 lines)
├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation ├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (359 lines)
├── oracle.ts # Strategic advisor (GPT-5.2) ├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free) ├── librarian.ts # Multi-repo research (326 lines)
├── explore.ts # Fast grep (Grok Code) ├── explore.ts # Fast grep (Grok Code)
├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash) ├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash)
├── prometheus-prompt.ts # Planning (1196 lines) ├── prometheus-prompt.ts # Planning (1196 lines)
├── metis.ts # Plan consultant ├── metis.ts # Plan consultant (315 lines)
├── momus.ts # Plan reviewer ├── momus.ts # Plan reviewer (444 lines)
├── types.ts # AgentModelConfig, AgentPromptMetadata ├── types.ts # AgentModelConfig, AgentPromptMetadata
├── utils.ts # createBuiltinAgents(), resolveModelWithFallback() ├── utils.ts # createBuiltinAgents(), resolveModelWithFallback()
└── index.ts # builtinAgents export └── index.ts # builtinAgents export

View File

@ -10,8 +10,9 @@ CLI entry: `bunx oh-my-opencode`. Interactive installer, doctor diagnostics. Com
cli/ cli/
├── index.ts # Commander.js entry ├── index.ts # Commander.js entry
├── install.ts # Interactive TUI (520 lines) ├── install.ts # Interactive TUI (520 lines)
├── config-manager.ts # JSONC parsing (641 lines) ├── config-manager.ts # JSONC parsing (664 lines)
├── types.ts # InstallArgs, InstallConfig ├── types.ts # InstallArgs, InstallConfig
├── model-fallback.ts # Model fallback configuration
├── doctor/ ├── doctor/
│ ├── index.ts # Doctor entry │ ├── index.ts # Doctor entry
│ ├── runner.ts # Check orchestration │ ├── runner.ts # Check orchestration
@ -25,6 +26,7 @@ cli/
│ ├── dependencies.ts # AST-Grep, Comment Checker │ ├── dependencies.ts # AST-Grep, Comment Checker
│ ├── lsp.ts # LSP connectivity │ ├── lsp.ts # LSP connectivity
│ ├── mcp.ts # MCP validation │ ├── mcp.ts # MCP validation
│ ├── model-resolution.ts # Model resolution check
│ └── gh.ts # GitHub CLI │ └── gh.ts # GitHub CLI
├── run/ ├── run/
│ └── index.ts # Session launcher │ └── index.ts # Session launcher

View File

@ -12,12 +12,14 @@ features/
│ ├── manager.ts # Launch → poll → complete │ ├── manager.ts # Launch → poll → complete
│ ├── concurrency.ts # Per-provider limits │ ├── concurrency.ts # Per-provider limits
│ └── types.ts # BackgroundTask, LaunchInput │ └── types.ts # BackgroundTask, LaunchInput
├── skill-mcp-manager/ # MCP client lifecycle ├── skill-mcp-manager/ # MCP client lifecycle (520 lines)
│ ├── manager.ts # Lazy loading, cleanup │ ├── manager.ts # Lazy loading, cleanup
│ └── types.ts # SkillMcpConfig │ └── types.ts # SkillMcpConfig
├── builtin-skills/ # Playwright, git-master, frontend-ui-ux ├── builtin-skills/ # Playwright, git-master, frontend-ui-ux
│ └── skills.ts # 1203 lines │ └── skills.ts # 1203 lines
├── builtin-commands/ # ralph-loop, refactor, init-deep ├── builtin-commands/ # ralph-loop, refactor, init-deep, start-work, remove-deadcode
│ ├── commands.ts # Command registry
│ └── templates/ # Command templates (4 files)
├── claude-code-agent-loader/ # ~/.claude/agents/*.md ├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md ├── claude-code-command-loader/ # ~/.claude/commands/*.md
├── claude-code-mcp-loader/ # .mcp.json ├── claude-code-mcp-loader/ # .mcp.json
@ -26,7 +28,8 @@ features/
├── opencode-skill-loader/ # Skills from 6 directories ├── opencode-skill-loader/ # Skills from 6 directories
├── context-injector/ # AGENTS.md/README.md injection ├── context-injector/ # AGENTS.md/README.md injection
├── boulder-state/ # Todo state persistence ├── boulder-state/ # Todo state persistence
└── hook-message-injector/ # Message injection ├── hook-message-injector/ # Message injection
└── task-toast-manager/ # Background task notifications
``` ```
## LOADER PRIORITY ## LOADER PRIORITY

View File

@ -10,7 +10,7 @@
hooks/ hooks/
├── atlas/ # Main orchestration (773 lines) ├── atlas/ # Main orchestration (773 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize ├── anthropic-context-window-limit-recovery/ # Auto-summarize
├── todo-continuation-enforcer.ts # Force TODO completion ├── todo-continuation-enforcer.ts # Force TODO completion (489 lines)
├── ralph-loop/ # Self-referential dev loop ├── ralph-loop/ # Self-referential dev loop
├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md ├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md
├── comment-checker/ # Prevents AI slop ├── comment-checker/ # Prevents AI slop
@ -28,7 +28,15 @@ hooks/
├── prometheus-md-only/ # Planner read-only mode ├── prometheus-md-only/ # Planner read-only mode
├── agent-usage-reminder/ # Specialized agent hints ├── agent-usage-reminder/ # Specialized agent hints
├── auto-update-checker/ # Plugin update check ├── auto-update-checker/ # Plugin update check
└── tool-output-truncator.ts # Prevents context bloat ├── tool-output-truncator.ts # Prevents context bloat
├── compaction-context-injector/ # Injects context on compaction
├── delegate-task-retry/ # Retries failed delegations
├── interactive-bash-session/ # Tmux session management
├── non-interactive-env/ # Non-TTY environment handling
├── start-work/ # Sisyphus work session starter
├── task-resume-info/ # Resume info for cancelled tasks
├── question-label-truncator/ # Auto-truncates question labels >30 chars
└── index.ts # Hook aggregation + registration
``` ```
## HOOK EVENTS ## HOOK EVENTS

View File

@ -2,7 +2,7 @@
## OVERVIEW ## OVERVIEW
50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution. 34 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution, agent display names.
## STRUCTURE ## STRUCTURE
@ -19,12 +19,27 @@ shared/
├── migration.ts # Legacy config migration ├── migration.ts # Legacy config migration
├── opencode-version.ts # Version comparison ├── opencode-version.ts # Version comparison
├── external-plugin-detector.ts # OAuth spoofing detection ├── external-plugin-detector.ts # OAuth spoofing detection
├── env-expander.ts # ${VAR} expansion
├── model-requirements.ts # Agent/Category requirements ├── model-requirements.ts # Agent/Category requirements
├── model-availability.ts # Models fetch + fuzzy match ├── model-availability.ts # Models fetch + fuzzy match
├── model-resolver.ts # 3-step resolution ├── model-resolver.ts # 3-step resolution
├── model-sanitizer.ts # Model ID normalization
├── shell-env.ts # Cross-platform shell ├── shell-env.ts # Cross-platform shell
├── prompt-parts-helper.ts # Prompt manipulation ├── agent-display-names.ts # Agent display name mapping
├── agent-tool-restrictions.ts # Tool restriction helpers
├── agent-variant.ts # Agent variant detection
├── command-executor.ts # Subprocess execution
├── config-errors.ts # Config error types
├── deep-merge.ts # Deep object merge
├── file-reference-resolver.ts # File path resolution
├── file-utils.ts # File utilities
├── hook-disabled.ts # Hook enable/disable check
├── pattern-matcher.ts # Glob pattern matching
├── session-cursor.ts # Session cursor tracking
├── snake-case.ts # String case conversion
├── system-directive.ts # System prompt helpers
├── tool-name.ts # Tool name constants
├── zip-extractor.ts # ZIP file extraction
├── index.ts # Barrel export
└── *.test.ts # Colocated tests └── *.test.ts # Colocated tests
``` ```
@ -40,6 +55,7 @@ shared/
| Resolve paths | `getOpenCodeConfigDir()` | | Resolve paths | `getOpenCodeConfigDir()` |
| Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` | | Compare versions | `isOpenCodeVersionAtLeast("1.1.0")` |
| Resolve model | `resolveModelWithFallback()` | | Resolve model | `resolveModelWithFallback()` |
| Agent display name | `getAgentDisplayName(agentName)` |
## PATTERNS ## PATTERNS

View File

@ -25,7 +25,7 @@ tools/
├── skill-mcp/ # Skill MCP operations ├── skill-mcp/ # Skill MCP operations
├── slashcommand/ # Slash command dispatch ├── slashcommand/ # Slash command dispatch
├── call-omo-agent/ # Direct agent invocation ├── call-omo-agent/ # Direct agent invocation
└── background-task/ # background_output, background_cancel └── background-task/ # background_output, background_cancel (513 lines)
``` ```
## TOOL CATEGORIES ## TOOL CATEGORIES
@ -48,7 +48,7 @@ tools/
## LSP SPECIFICS ## LSP SPECIFICS
- **Client**: `client.ts` manages stdio, JSON-RPC - **Client**: `client.ts` manages stdio, JSON-RPC (596 lines)
- **Singleton**: `LSPServerManager` with ref counting - **Singleton**: `LSPServerManager` with ref counting
- **Capabilities**: definition, references, symbols, diagnostics, rename - **Capabilities**: definition, references, symbols, diagnostics, rename