From 20d009964d31e9e94c827b92ab210c48ccc5a69a Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 9 Feb 2026 14:29:53 +0900 Subject: [PATCH] docs: refresh all 13 hierarchical AGENTS.md files with current codebase state --- AGENTS.md | 56 +++++++-------- src/AGENTS.md | 100 ++++++++------------------ src/agents/AGENTS.md | 19 ++--- src/cli/AGENTS.md | 47 +++++------- src/config/AGENTS.md | 34 ++++----- src/features/AGENTS.md | 70 +++++++++++++----- src/features/claude-tasks/AGENTS.md | 29 ++++---- src/hooks/AGENTS.md | 82 ++++++++++----------- src/hooks/claude-code-hooks/AGENTS.md | 20 +++--- src/mcp/AGENTS.md | 14 ++-- src/plugin-handlers/AGENTS.md | 8 +-- src/shared/AGENTS.md | 16 ++--- src/tools/AGENTS.md | 21 +++--- 13 files changed, 246 insertions(+), 270 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bdce1b27d..98b4ef7f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2026-02-08T16:45:00+09:00 -**Commit:** edee865f +**Generated:** 2026-02-09T14:16:00+09:00 +**Commit:** f22f14d9 **Branch:** dev --- @@ -131,16 +131,18 @@ oh-my-opencode/ │ ├── hooks/ # 40+ lifecycle hooks - see src/hooks/AGENTS.md │ ├── tools/ # 25+ tools - see src/tools/AGENTS.md │ ├── features/ # Background agents, skills, Claude Code compat - see src/features/AGENTS.md -│ ├── shared/ # 66 cross-cutting utilities - see src/shared/AGENTS.md +│ ├── shared/ # 88 cross-cutting utilities - see src/shared/AGENTS.md │ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md │ ├── mcp/ # Built-in MCPs - see src/mcp/AGENTS.md -│ ├── config/ # Zod schema (schema.ts 455 lines), TypeScript types -│ ├── plugin-handlers/ # Plugin config loading (config-handler.ts 562 lines) +│ ├── config/ # Zod schema (schema.ts 455 lines) - see src/config/AGENTS.md +│ ├── plugin-handlers/ # Plugin config loading - see src/plugin-handlers/AGENTS.md +│ ├── plugin/ # Plugin SDK types │ ├── index.ts # Main plugin entry (999 lines) +│ ├── create-hooks.ts # Hook creation coordination (core, continuation, skill) │ ├── plugin-config.ts # Config loading orchestration │ └── plugin-state.ts # Model cache state -├── script/ # build-schema.ts, build-binaries.ts, publish.ts -├── packages/ # 11 platform-specific binaries +├── script/ # build-schema.ts, build-binaries.ts, publish.ts, generate-changelog.ts +├── packages/ # 11 platform-specific binaries (darwin-*, linux-*, windows-*) └── dist/ # Build output (ESM + .d.ts) ``` @@ -148,17 +150,18 @@ oh-my-opencode/ | Task | Location | Notes | |------|----------|-------| -| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` in utils.ts | -| Add hook | `src/hooks/` | Create dir with `createXXXHook()`, register in index.ts | +| Add agent | `src/agents/` | Create .ts with factory, add to `agentSources` in builtin-agents.ts | +| Add hook | `src/hooks/` | Create dir with `createXXXHook()`, register in create-hooks.ts | | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts | | Add MCP | `src/mcp/` | Create config, add to `createBuiltinMcps()` | | 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` | | Plugin config | `src/plugin-handlers/config-handler.ts` | JSONC loading, merging, migration | -| Background agents | `src/features/background-agent/` | manager.ts (1556 lines) | -| Orchestrator | `src/hooks/atlas/` | Main orchestration hook (770 lines) | -| Delegation | `src/tools/delegate-task/` | Category routing (executor.ts 983 lines) | +| Background agents | `src/features/background-agent/` | manager.ts (1646 lines) | +| Orchestrator | `src/hooks/atlas/` | Main orchestration hook | +| Delegation | `src/tools/delegate-task/` | Category routing (constants.ts 569 lines) | +| Task system | `src/features/claude-tasks/` | Task schema, storage, todo sync | ## TDD (Test-Driven Development) @@ -170,7 +173,7 @@ oh-my-opencode/ **Rules:** - NEVER write implementation before test - NEVER delete failing tests - fix the code -- Test file: `*.test.ts` alongside source (163 test files) +- Test file: `*.test.ts` alongside source (163+ test files) - BDD comments: `//#given`, `//#when`, `//#then` ## CONVENTIONS @@ -180,7 +183,7 @@ oh-my-opencode/ - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Exports**: Barrel pattern via index.ts - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories -- **Testing**: BDD comments, 163 test files +- **Testing**: BDD comments, 163+ test files, 115k+ lines TypeScript - **Temperature**: 0.1 for code agents, max 0.3 ## ANTI-PATTERNS @@ -227,7 +230,7 @@ oh-my-opencode/ bun run typecheck # Type check bun run build # ESM + declarations + schema bun run rebuild # Clean + Build -bun test # 100+ test files +bun test # 163+ test files ``` ## DEPLOYMENT @@ -241,23 +244,18 @@ bun test # 100+ test files | File | Lines | Description | |------|-------|-------------| -| `src/features/background-agent/manager.ts` | 1642 | Task lifecycle, concurrency | -| `src/features/builtin-skills/skills/git-master.ts` | 1107 | Git master skill definition | +| `src/features/background-agent/manager.ts` | 1646 | Task lifecycle, concurrency | +| `src/features/builtin-skills/skills/git-master.ts` | 1111 | Git master skill definition | | `src/index.ts` | 999 | Main plugin entry | -| `src/tools/delegate-task/executor.ts` | 969 | Category-based delegation executor | -| `src/tools/lsp/client.ts` | 851 | LSP client operations | -| `src/tools/background-task/tools.ts` | 757 | Background task tools | -| `src/hooks/atlas/index.ts` | 697 | Orchestrator hook | -| `src/cli/config-manager.ts` | 667 | JSONC config parsing | -| `src/features/skill-mcp-manager/manager.ts` | 640 | MCP client lifecycle | -| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactor command template | +| `src/tools/delegate-task/tools.test.ts` | 3582 | Delegation tool tests | +| `src/features/background-agent/manager.test.ts` | 2843 | Background manager tests | +| `src/hooks/atlas/index.test.ts` | 1182 | Atlas hook tests | | `src/agents/hephaestus.ts` | 618 | Autonomous deep worker agent | -| `src/agents/utils.ts` | 571 | Agent creation, model fallback resolution | -| `src/plugin-handlers/config-handler.ts` | 562 | Plugin config loading | -| `src/tools/delegate-task/constants.ts` | 552 | Delegation constants | -| `src/cli/install.ts` | 542 | Interactive CLI installer | -| `src/hooks/task-continuation-enforcer.ts` | 530 | Task completion enforcement | +| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactor command template | +| `src/tools/delegate-task/constants.ts` | 569 | Category routing configs | | `src/agents/sisyphus.ts` | 530 | Main orchestrator agent | +| `src/agents/utils.ts` | 571 | Agent creation, model fallback resolution | +| `src/plugin-handlers/config-handler.ts` | 563 | Plugin config loading | ## MCP ARCHITECTURE diff --git a/src/AGENTS.md b/src/AGENTS.md index bb69e0a9b..11fd3de84 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -2,38 +2,38 @@ ## OVERVIEW -Main plugin entry point and orchestration layer. 1000+ lines of plugin initialization, hook registration, tool composition, and lifecycle management. +Main plugin entry point and orchestration layer. Plugin initialization, hook registration, tool composition, and lifecycle management. **Core Responsibilities:** -- Plugin initialization and configuration loading -- 40+ lifecycle hooks orchestration -- 25+ tools composition and filtering -- Background agent management -- Session state coordination -- MCP server lifecycle -- Tmux integration -- Claude Code compatibility layer +- Plugin initialization via `OhMyOpenCodePlugin()` factory +- Hook registration: `createCoreHooks()`, `createContinuationHooks()`, `createSkillHooks()` +- Tool composition with filtering +- Background agent management via `BackgroundManager` +- MCP lifecycle via `SkillMcpManager` ## STRUCTURE ``` src/ -├── index.ts # Main plugin entry (1000 lines) - orchestration layer -├── index.compaction-model-agnostic.static.test.ts # Compaction hook tests -├── agents/ # 11 AI agents (16 files) -├── cli/ # CLI commands (9 files) -├── config/ # Schema validation (3 files) -├── features/ # Background features (20+ files) -├── hooks/ # 40+ lifecycle hooks (14 files) -├── mcp/ # MCP server configs (7 files) -├── plugin-handlers/ # Config loading (3 files) -├── shared/ # Utilities (70 files) -└── tools/ # 25+ tools (15 files) +├── index.ts # Main plugin entry (999 lines) +├── create-hooks.ts # Hook coordination: core, continuation, skill +├── plugin-config.ts # Config loading orchestration +├── plugin-state.ts # Model cache state +├── agents/ # 11 AI agents (20 files) - see agents/AGENTS.md +├── cli/ # CLI installer, doctor (100+ files) - see cli/AGENTS.md +├── config/ # Zod schema (21 files) - see config/AGENTS.md +├── features/ # Background agents, skills, commands (17 dirs) - see features/AGENTS.md +├── hooks/ # 40+ lifecycle hooks (30+ dirs) - see hooks/AGENTS.md +├── mcp/ # Built-in MCPs (8 files) - see mcp/AGENTS.md +├── plugin/ # Plugin SDK types +├── plugin-handlers/ # Plugin config loading (5 files) - see plugin-handlers/AGENTS.md +├── shared/ # Cross-cutting utilities (84 files) - see shared/AGENTS.md +└── tools/ # 25+ tools (14 dirs) - see tools/AGENTS.md ``` ## KEY COMPONENTS **Plugin Initialization:** -- `OhMyOpenCodePlugin()`: Main plugin factory (lines 124-841) +- `OhMyOpenCodePlugin()`: Main plugin factory - Configuration loading via `loadPluginConfig()` - Hook registration with safe creation patterns - Tool composition and disabled tool filtering @@ -49,13 +49,7 @@ src/ - Tool filtering based on agent permissions and user config - Metadata restoration for tool outputs -**Integration Points:** -- Claude Code compatibility hooks and commands -- OpenCode SDK client interactions -- Session state persistence and recovery -- Model variant resolution and application - -## HOOK REGISTRATION PATTERNS +## HOOK REGISTRATION **Safe Hook Creation:** ```typescript @@ -68,61 +62,27 @@ const hook = isHookEnabled("hook-name") - **Session Management**: recovery, notification, compaction - **Continuation**: todo/task enforcers, stop guards - **Context**: injection, rules, directory content -- **Tool Enhancement**: output truncation, error recovery, validation +- **Tool Enhancement**: output truncation, error recovery - **Agent Coordination**: usage reminders, babysitting, delegation ## TOOL COMPOSITION -**Core Tools:** ```typescript const allTools: Record = { - ...builtinTools, // Basic file/session operations - ...createGrepTools(ctx), // Content search - ...createAstGrepTools(ctx), // AST-aware refactoring - task: delegateTask, // Agent delegation - skill: skillTool, // Skill execution - // ... 20+ more tools + ...builtinTools, + ...createGrepTools(ctx), + ...createAstGrepTools(ctx), + task: delegateTask, + skill: skillTool, }; ``` -**Tool Filtering:** -- Agent permission-based restrictions -- User-configured disabled tools -- Dynamic tool availability based on session state +**Filtering:** Agent permissions, user `disabled_tools`, session state. -## SESSION LIFECYCLE +## LIFECYCLE FLOW -**Session Events:** -- `session.created`: Initialize session state, tmux setup -- `session.deleted`: Cleanup resources, clear caches -- `message.updated`: Update agent assignments -- `session.error`: Trigger recovery mechanisms - -**Continuation Flow:** 1. User message triggers agent selection 2. Model/variant resolution applied 3. Tools execute with hook interception 4. Continuation enforcers monitor completion 5. Session compaction preserves context - -## CONFIGURATION INTEGRATION - -**Plugin Config Loading:** -- Project + user config merging -- Schema validation via Zod -- Migration support for legacy configs -- Dynamic feature enablement - -**Runtime Configuration:** -- Hook enablement based on `disabled_hooks` -- Tool filtering via `disabled_tools` -- Agent overrides and category definitions -- Experimental feature toggles - -## ANTI-PATTERNS - -- **Direct hook exports**: All hooks created via factories for testability -- **Global state pollution**: Session-scoped state management -- **Synchronous blocking**: Async-first architecture with background coordination -- **Tight coupling**: Plugin components communicate via events, not direct calls -- **Memory leaks**: Proper cleanup on session deletion and plugin unload diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index 4d41e2bdc..419fb15ad 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -30,18 +30,19 @@ agents/ │ ├── index.ts │ ├── default.ts │ └── gpt.ts -├── sisyphus.ts # Main orchestrator prompt (530 lines) -├── hephaestus.ts # Autonomous deep worker (618 lines, GPT 5.3 Codex) -├── oracle.ts # Strategic advisor (GPT-5.2) +├── sisyphus.ts # Main orchestrator (530 lines) +├── hephaestus.ts # Autonomous deep worker (618 lines) +├── oracle.ts # Strategic advisor (170 lines) ├── librarian.ts # Multi-repo research (328 lines) -├── explore.ts # Fast contextual grep -├── multimodal-looker.ts # Media analyzer (Gemini 3 Flash) -├── metis.ts # Pre-planning analysis (347 lines) -├── momus.ts # Plan reviewer +├── explore.ts # Fast codebase grep (124 lines) +├── multimodal-looker.ts # Media analyzer (58 lines) +├── metis.ts # Pre-planning analysis (346 lines) +├── momus.ts # Plan validator (243 lines) ├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (431 lines) +├── builtin-agents.ts # Agent registry (179 lines) ├── types.ts # AgentModelConfig, AgentPromptMetadata -├── utils.ts # createBuiltinAgents(), resolveModelWithFallback() (485 lines) -└── index.ts # builtinAgents export +├── utils.ts # Agent creation, model fallback resolution (571 lines) +└── index.ts # Exports ``` ## AGENT MODELS diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 9f9d83712..66147307c 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW -CLI entry: `bunx oh-my-opencode`. 70 CLI utilities and commands with Commander.js + @clack/prompts TUI. +CLI entry: `bunx oh-my-opencode`. 107 CLI utilities with Commander.js + @clack/prompts TUI. **Commands**: install (interactive setup), doctor (14 health checks), run (session launcher), get-local-version, mcp-oauth @@ -10,33 +10,22 @@ CLI entry: `bunx oh-my-opencode`. 70 CLI utilities and commands with Commander.j ``` cli/ -├── index.ts # Commander.js entry (5 commands) -├── install.ts # Interactive TUI (542 lines) -├── config-manager.ts # JSONC parsing (667 lines) -├── model-fallback.ts # Model fallback configuration -├── types.ts # InstallArgs, InstallConfig +├── index.ts # Commander.js entry (5 commands) +├── install.ts # TTY routing to TUI or CLI installer +├── cli-installer.ts # Non-interactive installer (164 lines) +├── tui-installer.ts # Interactive TUI with @clack/prompts (140 lines) +├── config-manager/ # Config management utilities (17 files) +├── model-fallback.ts # Model fallback configuration +├── model-fallback.test.ts # Fallback tests (523 lines) ├── doctor/ -│ ├── index.ts # Doctor entry -│ ├── runner.ts # Check orchestration -│ ├── formatter.ts # Colored output -│ ├── constants.ts # Check IDs, symbols -│ ├── types.ts # CheckResult, CheckDefinition -│ └── checks/ # 14 checks, 23 files -│ ├── version.ts # OpenCode + plugin version -│ ├── config.ts # JSONC validity, Zod -│ ├── auth.ts # Anthropic, OpenAI, Google -│ ├── dependencies.ts # AST-Grep, Comment Checker -│ ├── lsp.ts # LSP connectivity -│ ├── mcp.ts # MCP validation -│ ├── model-resolution.ts # Model resolution check (323 lines) -│ └── gh.ts # GitHub CLI -├── run/ -│ ├── index.ts # Session launcher -│ └── events.ts # CLI run events (325 lines) -├── mcp-oauth/ -│ └── index.ts # MCP OAuth flow -└── get-local-version/ - └── index.ts # Version detection +│ ├── runner.ts # Check orchestration +│ ├── formatter.ts # Colored output +│ └── checks/ # 29 files with individual checks +├── run/ # Session launcher (24 files) +│ ├── events.ts # CLI run events +│ └── runner.ts # Run orchestration +├── mcp-oauth/ # OAuth flow +└── get-local-version/ # Version detection ``` ## COMMANDS @@ -70,11 +59,11 @@ cli/ - **@clack/prompts**: `select()`, `spinner()`, `intro()`, `outro()` - **picocolors**: Terminal colors for status and headers -- **Symbols**: ✓ (pass), ✗ (fail), ⚠ (warn), ℹ (info) +- **Symbols**: check (pass), cross (fail), warning (warn), info (info) ## ANTI-PATTERNS - **Blocking in non-TTY**: Always check `process.stdout.isTTY` - **Direct JSON.parse**: Use `parseJsonc()` from shared utils - **Silent failures**: Return `warn` or `fail` in doctor instead of throwing -- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from `config-manager.ts` +- **Hardcoded paths**: Use `getOpenCodeConfigPaths()` from `config-manager` diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md index ce20d3dd6..a219fc82e 100644 --- a/src/config/AGENTS.md +++ b/src/config/AGENTS.md @@ -1,5 +1,5 @@ -**Generated:** 2026-02-08T16:45:00+09:00 -**Commit:** f2b7b759 +**Generated:** 2026-02-09T14:16:00+09:00 +**Commit:** f22f14d9 **Branch:** dev ## OVERVIEW @@ -7,33 +7,27 @@ Zod schema definitions for plugin configuration. 455+ lines of type-safe config validation with JSONC support, multi-level inheritance, and comprehensive agent/category overrides. ## STRUCTURE + ``` config/ -├── schema.ts # Main Zod schema (455 lines) - agents, categories, experimental features -├── schema.test.ts # Schema validation tests (17909 lines) -└── index.ts # Barrel export +├── schema/ # Schema components (21 files) +│ ├── index.ts # Main schema composition +│ └── [module].ts # Agent names, overrides, categories, hooks, etc. +├── schema.ts # Main Zod schema (455 lines) +├── schema.test.ts # Schema validation tests (735 lines) +├── types.ts # TypeScript types +└── index.ts # Barrel export ``` ## SCHEMA COMPONENTS -**Agent Configuration:** -- `AgentOverrideConfigSchema`: Model, variant, temperature, permissions, tools -- `AgentOverridesSchema`: Per-agent overrides (sisyphus, hephaestus, prometheus, etc.) -- `AgentPermissionSchema`: Tool access control (edit, bash, webfetch, task) +**Agent Config:** `AgentOverrideConfigSchema`, `AgentOverridesSchema`, `AgentPermissionSchema` -**Category Configuration:** -- `CategoryConfigSchema`: Model defaults, thinking budgets, tool restrictions -- `CategoriesConfigSchema`: Named categories (visual-engineering, ultrabrain, deep, etc.) +**Category Config:** `CategoryConfigSchema`, `CategoriesConfigSchema` (visual-engineering, ultrabrain, deep) -**Experimental Features:** -- `ExperimentalConfigSchema`: Dynamic context pruning, task system, plugin timeouts -- `DynamicContextPruningConfigSchema`: Intelligent context management +**Experimental:** `ExperimentalConfigSchema`, `DynamicContextPruningConfigSchema` -**Built-in Enums:** -- `AgentNameSchema`: sisyphus, hephaestus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas -- `HookNameSchema`: 100+ hook names for lifecycle management -- `BuiltinCommandNameSchema`: init-deep, ralph-loop, refactor, start-work -- `BuiltinSkillNameSchema`: playwright, agent-browser, git-master +**Built-in Enums:** `AgentNameSchema` (11 agents), `HookNameSchema` (100+ hooks), `BuiltinCommandNameSchema`, `BuiltinSkillNameSchema` ## CONFIGURATION HIERARCHY diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 738d52591..acf910f5a 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -2,29 +2,61 @@ ## OVERVIEW -Background agents, skills, Claude Code compat, builtin commands, MCP managers, etc. +Background systems that extend plugin capabilities: agents, skills, Claude Code compatibility layer, MCP managers, and task orchestration. ## STRUCTURE +``` features/ -├── background-agent/ # Task lifecycle, concurrency (manager.ts 1642 lines) -├── builtin-skills/ # Skills like git-master (1107 lines) -├── builtin-commands/ # Commands like refactor (619 lines) -├── skill-mcp-manager/ # MCP client lifecycle (640 lines) -├── claude-code-plugin-loader/ # Plugin loading -├── claude-code-mcp-loader/ # MCP loading -├── claude-code-session-state/ # Session state -├── claude-code-command-loader/ # Command loading -├── claude-code-agent-loader/ # Agent loading -├── context-injector/ # Context injection -├── hook-message-injector/ # Message injection -├── task-toast-manager/ # Task toasts -├── boulder-state/ # State management -├── tmux-subagent/ # Tmux subagent -├── mcp-oauth/ # OAuth for MCP -├── opencode-skill-loader/ # Skill loading -├── tool-metadata-store/ # Tool metadata +├── background-agent/ # Task lifecycle, concurrency (manager.ts 1646 lines, concurrency.ts) +├── boulder-state/ # Persistent state for multi-step operations +├── builtin-commands/ # Command templates: refactor (619 lines), ralph-loop, handoff, init-deep +├── builtin-skills/ # Skills: git-master (1111 lines), playwright, dev-browser, frontend-ui-ux +├── claude-code-agent-loader/ # CC agent loading from .opencode/agents/ +├── claude-code-command-loader/ # CC command loading from .opencode/commands/ +├── claude-code-mcp-loader/ # CC MCP loading from .opencode/mcp/ +├── claude-code-plugin-loader/ # CC plugin discovery from .opencode/plugins/ +├── claude-code-session-state/ # Subagent session state tracking +├── claude-tasks/ # Task schema + storage (has own AGENTS.md) +├── context-injector/ # Auto-injects AGENTS.md, README.md, rules +├── hook-message-injector/ # System message injection +├── mcp-oauth/ # OAuth flow for MCP servers +├── opencode-skill-loader/ # YAML frontmatter skill loading +├── skill-mcp-manager/ # MCP client lifecycle per session (manager.ts 150 lines) +├── task-toast-manager/ # Task progress notifications +├── tmux-subagent/ # Tmux integration (manager.ts 350 lines) +└── tool-metadata-store/ # Tool execution metadata caching +``` + +## KEY PATTERNS + +**Background Agent Lifecycle:** +- Task creation -> Queue -> Concurrency check -> Execute -> Monitor -> Cleanup +- Manager.ts handles full lifecycle with 1646 lines of task orchestration +- Concurrency.ts manages parallel execution limits per provider/model +- Tasks survive session restarts via persistent storage + +**Claude Code Compatibility Layer:** +5 directories provide full CC compatibility: +- agent-loader: Loads custom agents from .opencode/agents/ +- command-loader: Loads slash commands from .opencode/commands/ +- mcp-loader: Loads MCP servers from .opencode/mcp/ +- plugin-loader: Discovers plugins from .opencode/plugins/ +- session-state: Tracks subagent session state and recovery + +**Skill Loading Pipeline:** +1. opencode-skill-loader: Parses YAML frontmatter from skill files +2. skill-mcp-manager: Manages MCP lifecycle per skill session (manager.ts 150 lines) +3. Context injection: Auto-loads AGENTS.md, README.md, rules into context +4. Hook message injector: Injects system messages for skill activation ## HOW TO ADD -Create dir with index.ts, types.ts, etc. +1. Create directory under `src/features/` +2. Add `index.ts`, `types.ts`, `constants.ts` as needed +3. Export from `index.ts` following barrel pattern +4. Register in main plugin if plugin-level feature + +## CHILD DOCUMENTATION + +- See `claude-tasks/AGENTS.md` for task schema and storage details diff --git a/src/features/claude-tasks/AGENTS.md b/src/features/claude-tasks/AGENTS.md index 3c0c140d1..a0c4da164 100644 --- a/src/features/claude-tasks/AGENTS.md +++ b/src/features/claude-tasks/AGENTS.md @@ -8,12 +8,13 @@ Claude Code compatible task schema and storage. Provides core task management ut ``` claude-tasks/ -├── types.ts # Task schema (Zod) -├── types.test.ts # Schema validation tests (8 tests) -├── storage.ts # File operations -├── storage.test.ts # Storage tests (14 tests) -├── todo-sync.ts # Task → Todo synchronization -└── index.ts # Barrel exports +├── types.ts # Task schema (Zod) +├── types.test.ts # Schema validation tests (8 tests) +├── storage.ts # File operations +├── storage.test.ts # Storage tests (30 tests, 543 lines) +├── session-storage.ts # Session-scoped task storage +├── session-storage.test.ts +└── index.ts # Barrel exports ``` ## TASK SCHEMA @@ -31,9 +32,6 @@ interface Task { blockedBy: string[] // Task IDs blocking this task (was: dependsOn) owner?: string // Agent name metadata?: Record - repoURL?: string // oh-my-opencode specific - parentID?: string // oh-my-opencode specific - threadID: string // oh-my-opencode specific } ``` @@ -43,14 +41,6 @@ interface Task { - `blocks` (new field) - `activeForm` (new field) -## TODO SYNC - -Task system includes sync layer (`todo-sync.ts`) that automatically mirrors task state to the project's Todo system. - -- **Creation**: `task_create` adds corresponding Todo item -- **Updates**: `task_update` reflects in Todo list -- **Completion**: `completed` status marks Todo item done - ## STORAGE UTILITIES | Function | Purpose | @@ -60,6 +50,11 @@ Task system includes sync layer (`todo-sync.ts`) that automatically mirrors task | `readJsonSafe(path, schema)` | Parse + validate, returns null on failure | | `writeJsonAtomic(path, data)` | Atomic write via temp file + rename | | `acquireLock(dirPath)` | File-based lock with 30s stale threshold | +| `generateTaskId()` | Generates `T-{uuid}` task ID | +| `listTaskFiles(config)` | Lists all task IDs in storage | +| `getSessionTaskDir(config, sessionID)` | Returns session-scoped task directory | +| `listSessionTaskFiles(config, sessionID)` | Lists tasks for specific session | +| `findTaskAcrossSessions(config, taskId)` | Locates task in any session directory | ## ANTI-PATTERNS diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index d1307c317..45ea23eb5 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -14,46 +14,48 @@ ## STRUCTURE ``` hooks/ -├── atlas/ # Main orchestration (770 lines) -├── anthropic-context-window-limit-recovery/ # Auto-summarize -├── todo-continuation-enforcer.ts # Force TODO completion (517 lines) -├── ralph-loop/ # Self-referential dev loop (428 lines) -├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md -├── comment-checker/ # Prevents AI slop -├── auto-slash-command/ # Detects /command patterns -├── rules-injector/ # Conditional rules -├── directory-agents-injector/ # Auto-injects AGENTS.md -├── directory-readme-injector/ # Auto-injects README.md -├── edit-error-recovery/ # Recovers from failures -├── thinking-block-validator/ # Ensures valid -├── context-window-monitor.ts # Reminds of headroom -├── session-recovery/ # Auto-recovers from crashes (436 lines) -├── session-notification.ts # Session event notifications (337 lines) -├── think-mode/ # Dynamic thinking budget -├── keyword-detector/ # ultrawork/search/analyze modes -├── background-notification/ # OS notification -├── prometheus-md-only/ # Planner read-only mode -├── agent-usage-reminder/ # Specialized agent hints -├── auto-update-checker/ # Plugin update check (304 lines) -├── 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 -├── category-skill-reminder/ # Reminds of category skills -├── empty-task-response-detector.ts # Detects empty responses -├── sisyphus-junior-notepad/ # Sisyphus Junior notepad -├── stop-continuation-guard/ # Guards stop continuation -├── subagent-question-blocker/ # Blocks subagent questions -├── task-reminder/ # Task progress reminders -├── tasks-todowrite-disabler/ # Disables TodoWrite when task system active -├── unstable-agent-babysitter/ # Monitors unstable agent behavior -├── write-existing-file-guard/ # Guards against overwriting existing files -├── preemptive-compaction.ts # Preemptive context compaction -└── index.ts # Hook aggregation + registration +├── agent-usage-reminder/ # Specialized agent hints (212 lines) +├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines) +├── anthropic-effort/ # Anthropic effort level management (272 lines) +├── atlas/ # Main orchestration hook (1976 lines) +├── auto-slash-command/ # Detects /command patterns (1134 lines) +├── auto-update-checker/ # Plugin update check (1140 lines) +├── background-notification/ # OS notifications (33 lines) +├── category-skill-reminder/ # Reminds of category skills (597 lines) +├── claude-code-hooks/ # settings.json compat - see AGENTS.md (2110 lines) +├── comment-checker/ # Prevents AI slop comments (710 lines) +├── compaction-context-injector/ # Injects context on compaction (128 lines) +├── compaction-todo-preserver/ # Preserves todos during compaction (203 lines) +├── context-window-monitor.ts # Reminds of headroom (99 lines) +├── delegate-task-retry/ # Retries failed delegations (266 lines) +├── directory-agents-injector/ # Auto-injects AGENTS.md (195 lines) +├── directory-readme-injector/ # Auto-injects README.md (190 lines) +├── edit-error-recovery/ # Recovers from edit failures (188 lines) +├── empty-task-response-detector.ts # Detects empty responses (27 lines) +├── index.ts # Hook aggregation + registration (46 lines) +├── interactive-bash-session/ # Tmux session management (695 lines) +├── keyword-detector/ # ultrawork/search/analyze modes (1665 lines) +├── non-interactive-env/ # Non-TTY environment handling (483 lines) +├── preemptive-compaction.ts # Preemptive context compaction (108 lines) +├── prometheus-md-only/ # Planner read-only mode (955 lines) +├── question-label-truncator/ # Auto-truncates question labels (199 lines) +├── ralph-loop/ # Self-referential dev loop (1687 lines) +├── rules-injector/ # Conditional rules injection (1604 lines) +├── session-notification.ts # Session event notifications (108 lines) +├── session-recovery/ # Auto-recovers from crashes (1279 lines) +├── sisyphus-junior-notepad/ # Sisyphus Junior notepad (76 lines) +├── start-work/ # Sisyphus work session starter (648 lines) +├── stop-continuation-guard/ # Guards stop continuation (214 lines) +├── subagent-question-blocker/ # Blocks subagent questions (112 lines) +├── task-reminder/ # Task progress reminders (210 lines) +├── task-resume-info/ # Resume info for cancelled tasks (39 lines) +├── tasks-todowrite-disabler/ # Disables TodoWrite when tasks active (202 lines) +├── think-mode/ # Dynamic thinking budget (1365 lines) +├── thinking-block-validator/ # Ensures valid blocks (169 lines) +├── todo-continuation-enforcer/ # Force TODO completion (2061 lines) +├── tool-output-truncator.ts # Prevents context bloat (62 lines) +├── unstable-agent-babysitter/ # Monitors unstable agent behavior (451 lines) +└── write-existing-file-guard/ # Guards against overwriting files (356 lines) ``` ## HOOK EVENTS diff --git a/src/hooks/claude-code-hooks/AGENTS.md b/src/hooks/claude-code-hooks/AGENTS.md index ca0d1927d..4b74c33eb 100644 --- a/src/hooks/claude-code-hooks/AGENTS.md +++ b/src/hooks/claude-code-hooks/AGENTS.md @@ -9,18 +9,22 @@ Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode e ## STRUCTURE ``` claude-code-hooks/ -├── index.ts # Main factory (421 lines) -├── config.ts # Loads ~/.claude/settings.json -├── config-loader.ts # Extended config (disabledHooks) -├── pre-tool-use.ts # PreToolUse executor -├── post-tool-use.ts # PostToolUse executor +├── index.ts # Barrel export +├── claude-code-hooks-hook.ts # Main factory +├── config.ts # Claude settings.json loader +├── config-loader.ts # Extended plugin config +├── pre-tool-use.ts # PreToolUse hook executor +├── post-tool-use.ts # PostToolUse hook executor ├── user-prompt-submit.ts # UserPromptSubmit executor -├── stop.ts # Stop hook executor (with active state tracking) +├── stop.ts # Stop hook executor ├── pre-compact.ts # PreCompact executor ├── transcript.ts # Tool use recording ├── tool-input-cache.ts # Pre→post input caching ├── todo.ts # Todo integration -└── types.ts # Hook & IO type definitions +├── session-hook-state.ts # Active state tracking +├── types.ts # Hook & IO type definitions +├── plugin-config.ts # Default config constants +└── handlers/ # Event handlers (5 files) ``` ## HOOK LIFECYCLE @@ -44,4 +48,4 @@ claude-code-hooks/ - **Heavy PreToolUse**: Runs before EVERY tool; keep logic light to avoid latency - **Blocking non-critical**: Prefer PostToolUse warnings for non-fatal issues - **Direct state mutation**: Use `updatedInput` in PreToolUse instead of side effects -- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools +- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools \ No newline at end of file diff --git a/src/mcp/AGENTS.md b/src/mcp/AGENTS.md index f3f387aa8..699cf43fe 100644 --- a/src/mcp/AGENTS.md +++ b/src/mcp/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW -Tier 1 of three-tier MCP system: 8 built-in remote HTTP MCPs. +Tier 1 of three-tier MCP system: 3 built-in remote HTTP MCPs. **Three-Tier System**: 1. **Built-in** (this directory): websearch, context7, grep_app @@ -25,7 +25,7 @@ mcp/ | Name | URL | Purpose | Auth | |------|-----|---------|------| -| websearch | mcp.exa.ai / mcp.tavily.com | Real-time web search | EXA_API_KEY / TAVILY_API_KEY | +| websearch | mcp.exa.ai/mcp?tools=web_search_exa or mcp.tavily.com/mcp/ | Real-time web search | EXA_API_KEY (optional) / TAVILY_API_KEY (required) | | context7 | mcp.context7.com/mcp | Library docs | CONTEXT7_API_KEY (optional) | | grep_app | mcp.grep.app | GitHub code search | None | @@ -33,8 +33,8 @@ mcp/ | Provider | URL | Auth | API Key Required | |----------|-----|------|------------------| -| exa (default) | mcp.exa.ai | x-api-key header | No (optional) | -| tavily | mcp.tavily.com | Authorization Bearer | Yes | +| exa (default) | mcp.exa.ai/mcp?tools=web_search_exa | query param | No (optional) | +| tavily | mcp.tavily.com/mcp/ | Authorization Bearer | Yes | ```jsonc { @@ -58,9 +58,9 @@ export const mcp_name = { ## HOW TO ADD -1. Create `src/mcp/my-mcp.ts` -2. Add to `allBuiltinMcps` in `index.ts` -3. Add to `McpNameSchema` in `types.ts` +1. Create `src/mcp/my-mcp.ts` with MCP config object +2. Add conditional check in `createBuiltinMcps()` in `index.ts` +3. Add name to `McpNameSchema` in `types.ts` ## NOTES diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index 74dcf9a77..9060a3098 100644 --- a/src/plugin-handlers/AGENTS.md +++ b/src/plugin-handlers/AGENTS.md @@ -1,5 +1,5 @@ -**Generated:** 2026-02-08T16:45:00+09:00 -**Commit:** f2b7b759 +**Generated:** 2026-02-09T14:16:00+09:00 +**Commit:** f22f14d9 **Branch:** dev ## OVERVIEW @@ -10,7 +10,7 @@ Plugin component loading and configuration orchestration. 500+ lines of config m ``` plugin-handlers/ ├── config-handler.ts # Main config orchestrator (563 lines) - agent/skill/command loading -├── config-handler.test.ts # Config handler tests (34426 lines) +├── config-handler.test.ts # Config handler tests (1061 lines) ├── plan-model-inheritance.ts # Plan agent model inheritance logic (657 lines) ├── plan-model-inheritance.test.ts # Inheritance tests (3696 lines) └── index.ts # Barrel export @@ -62,7 +62,7 @@ User Config → Migration → Merging → Validation → Agent Creation → Perm ## TESTING COVERAGE -- **Config Handler**: 34426 lines of tests +- **Config Handler**: 1061 lines of tests - **Plan Inheritance**: 3696 lines of tests - **Migration Logic**: Legacy compatibility verification - **Parallel Loading**: Timeout and error handling diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index 1200bceaf..cb12f8699 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -9,20 +9,21 @@ ## STRUCTURE ``` shared/ -├── tmux/ # Tmux TUI integration (types, utils 312 lines, constants) +├── git-worktree/ # Git worktree operations (311 lines) +├── tmux/ # Tmux TUI integration (227 lines) ├── logger.ts # File-based logging (/tmp/oh-my-opencode.log) - 53 imports -├── dynamic-truncator.ts # Token-aware context window management (194 lines) +├── dynamic-truncator.ts # Token-aware context window management (201 lines) ├── model-resolver.ts # 3-step resolution (Override → Fallback → Default) -├── model-requirements.ts # Agent/category model fallback chains (162 lines) -├── model-availability.ts # Provider model fetching & fuzzy matching (357 lines) +├── model-requirements.ts # Agent/category model fallback chains (160 lines) +├── model-availability.ts # Provider model fetching & fuzzy matching (358 lines) ├── model-sanitizer.ts # Model name sanitization ├── model-suggestion-retry.ts # Model suggestion on failure ├── jsonc-parser.ts # JSONC parsing with comment support ├── frontmatter.ts # YAML frontmatter extraction (JSON_SCHEMA only) - 9 imports ├── data-path.ts # XDG-compliant storage resolution -├── opencode-config-dir.ts # ~/.config/opencode resolution (143 lines) - 9 imports +├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines) - 9 imports ├── claude-config-dir.ts # ~/.claude resolution - 9 imports -├── migration.ts # Legacy config migration logic (231 lines) +├── migration.ts # Legacy config migration logic (341 lines across dir) ├── opencode-version.ts # Semantic version comparison ├── permission-compat.ts # Agent tool restriction enforcement - 6 imports ├── system-directive.ts # Unified system message prefix & types - 8 imports @@ -32,8 +33,7 @@ shared/ ├── agent-variant.ts # Agent variant from config ├── zip-extractor.ts # Binary/Resource ZIP extraction ├── deep-merge.ts # Recursive object merging (proto-pollution safe, MAX_DEPTH=50) -├── case-insensitive.ts # Case-insensitive object lookups -├── command-executor.ts # Shell command execution (225 lines) +├── command-executor.ts # Shell command execution (213 lines across dir) ├── snake-case.ts # Case conversion utilities ├── tool-name.ts # Tool naming conventions ├── pattern-matcher.ts # Pattern matching utilities diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index fedcf96bc..3fcfadcb8 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -2,9 +2,9 @@ ## OVERVIEW -113 tools across 8 categories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent). +25+ tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent). -**Categories**: LSP (6), AST-Grep (2), Search (2), Session (4), Task (4), Agent delegation (2), Background (2), Skill (3), System (2) +**Categories**: LSP (6), AST-Grep (2), Search (2), Session (4), Task (4), Agent delegation (1), Background (2), Skill (2), System (2), MCP (1), Command (1) ## STRUCTURE @@ -15,20 +15,20 @@ tools/ │ ├── tools.ts # ToolDefinition or factory │ ├── types.ts # Zod schemas │ └── constants.ts # Fixed values -├── lsp/ # 6 tools: definition, references, symbols, diagnostics, rename (client.ts 803 lines) +├── lsp/ # 6 tools: goto_definition, find_references, symbols, diagnostics, prepare_rename, rename ├── ast-grep/ # 2 tools: search, replace (25 languages) -├── delegate-task/ # Category-based routing (executor.ts 983 lines, constants.ts 552 lines) +├── delegate-task/ # Category routing (constants.ts 569 lines, tools.test.ts 3582 lines) ├── task/ # 4 tools: create, get, list, update (Claude Code compatible) ├── session-manager/ # 4 tools: list, read, search, info -├── grep/ # Custom grep with timeout (60s, 10MB) +├── grep/ # Custom grep (60s timeout, 10MB limit) ├── glob/ # 60s timeout, 100 file limit ├── interactive-bash/ # Tmux session management -├── look-at/ # Multimodal PDF/image (307 lines) +├── look-at/ # Multimodal PDF/image analysis ├── skill/ # Skill execution ├── skill-mcp/ # Skill MCP operations ├── slashcommand/ # Slash command dispatch -├── call-omo-agent/ # Direct agent invocation (358 lines) -└── background-task/ # background_output, background_cancel (734 lines) +├── call-omo-agent/ # Direct agent invocation +└── background-task/ # background_output, background_cancel ``` ## TOOL CATEGORIES @@ -39,10 +39,11 @@ tools/ | Search | ast_grep_search, ast_grep_replace, grep, glob | Direct | | Session | session_list, session_read, session_search, session_info | Direct | | Task | task_create, task_get, task_list, task_update | Factory | -| Agent | task, call_omo_agent | Factory | +| Agent | call_omo_agent | Factory | | Background | background_output, background_cancel | Factory | | System | interactive_bash, look_at | Mixed | -| Skill | skill, skill_mcp, slashcommand | Factory | +| Skill | skill, skill_mcp | Factory | +| Command | slashcommand | Factory | ## TASK TOOLS