From cfb8164d9ae1730022bfaa1c6dafc05786cc061a Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 16 Feb 2026 15:26:53 +0900 Subject: [PATCH] docs: regenerate all 13 AGENTS.md files from deep codebase exploration --- AGENTS.md | 72 ++++++------- src/AGENTS.md | 25 ++--- src/agents/AGENTS.md | 53 ++++------ src/cli/AGENTS.md | 43 ++++---- src/features/AGENTS.md | 26 +++-- src/features/claude-tasks/AGENTS.md | 31 +----- src/hooks/AGENTS.md | 18 ++-- src/hooks/claude-code-hooks/AGENTS.md | 33 +++--- src/plugin-handlers/AGENTS.md | 2 +- src/shared/AGENTS.md | 40 +++---- src/tools/AGENTS.md | 147 ++++++-------------------- 11 files changed, 182 insertions(+), 308 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a5b8d1442..40a72f6af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2026-02-10T14:44:00+09:00 -**Commit:** b538806d -**Branch:** dev +**Generated:** 2026-02-16T14:58:00+09:00 +**Commit:** 28cd34c3 +**Branch:** fuck-v1.2 --- @@ -102,32 +102,32 @@ Oh-My-OpenCode is a **plugin for OpenCode**. You will frequently need to examine ## OVERVIEW -OpenCode plugin (v3.4.0): multi-model agent orchestration with 11 specialized agents (Claude Opus 4.6, GPT-5.3 Codex, Gemini 3 Flash, GLM-4.7, Grok). 41 lifecycle hooks across 7 event types, 25+ tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer. "oh-my-zsh" for OpenCode. +OpenCode plugin (oh-my-opencode): multi-model agent orchestration with 11 specialized agents, 41 lifecycle hooks across 7 event types, 26 tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer, 4-scope skill loading, background agent concurrency, tmux integration, and 3-tier MCP system. "oh-my-zsh" for OpenCode. ## STRUCTURE ``` oh-my-opencode/ ├── src/ -│ ├── agents/ # 11 AI agents - see src/agents/AGENTS.md -│ ├── hooks/ # 41 lifecycle hooks - see src/hooks/AGENTS.md -│ ├── tools/ # 25+ tools - see src/tools/AGENTS.md -│ ├── features/ # Background agents, skills, CC compat - see src/features/AGENTS.md -│ ├── shared/ # 84 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 - see src/config/AGENTS.md -│ ├── plugin-handlers/ # Config loading - see src/plugin-handlers/AGENTS.md +│ ├── agents/ # 11 AI agents — see src/agents/AGENTS.md +│ ├── hooks/ # 41 lifecycle hooks — see src/hooks/AGENTS.md +│ ├── tools/ # 26 tools — see src/tools/AGENTS.md +│ ├── features/ # Background agents, skills, CC compat — see src/features/AGENTS.md +│ ├── shared/ # 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 — see src/config/AGENTS.md +│ ├── plugin-handlers/ # Config loading pipeline — see src/plugin-handlers/AGENTS.md │ ├── plugin/ # Plugin interface composition (21 files) -│ ├── index.ts # Main plugin entry (88 lines) +│ ├── index.ts # Main plugin entry (106 lines) │ ├── create-hooks.ts # Hook creation coordination (62 lines) │ ├── create-managers.ts # Manager initialization (80 lines) │ ├── create-tools.ts # Tool registry composition (54 lines) │ ├── plugin-interface.ts # Plugin interface assembly (66 lines) -│ ├── plugin-config.ts # Config loading orchestration -│ └── plugin-state.ts # Model cache state +│ ├── plugin-config.ts # Config loading orchestration (180 lines) +│ └── plugin-state.ts # Model cache state (12 lines) ├── script/ # build-schema.ts, build-binaries.ts, publish.ts, generate-changelog.ts -├── packages/ # 7 platform-specific binary packages +├── packages/ # 11 platform-specific binary packages └── dist/ # Build output (ESM + .d.ts) ``` @@ -143,7 +143,7 @@ OhMyOpenCodePlugin(ctx) 6. createManagers(ctx, config, tmux, cache) → TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler 7. createTools(ctx, config, managers) → filteredTools, mergedSkills, availableSkills, availableCategories 8. createHooks(ctx, config, backgroundMgr) → 41 hooks (core + continuation + skill) - 9. createPluginInterface(...) → tool, chat.params, chat.message, event, tool.execute.before/after + 9. createPluginInterface(...) → 7 OpenCode hook handlers 10. Return plugin with experimental.session.compacting ``` @@ -159,7 +159,7 @@ OhMyOpenCodePlugin(ctx) | Add command | `src/features/builtin-commands/` | Add template + register in commands.ts | | Config schema | `src/config/schema/` | 21 schema component files, 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 (1646 lines) | +| Background agents | `src/features/background-agent/` | manager.ts (1701 lines) | | Orchestrator | `src/hooks/atlas/` | Main orchestration hook (1976 lines) | | Delegation | `src/tools/delegate-task/` | Category routing (constants.ts 569 lines) | | Task system | `src/features/claude-tasks/` | Task schema, storage, todo sync | @@ -174,7 +174,7 @@ OhMyOpenCodePlugin(ctx) **Rules:** - NEVER write implementation before test -- NEVER delete failing tests - fix the code +- NEVER delete failing tests — fix the code - Test file: `*.test.ts` alongside source (176 test files) - BDD comments: `//#given`, `//#when`, `//#then` @@ -185,7 +185,7 @@ OhMyOpenCodePlugin(ctx) - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Exports**: Barrel pattern via index.ts - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories -- **Testing**: BDD comments, 176 test files, 117k+ lines TypeScript +- **Testing**: BDD comments, 176 test files, 1130 TypeScript files - **Temperature**: 0.1 for code agents, max 0.3 - **Modular architecture**: 200 LOC hard limit per file (prompt strings exempt) @@ -193,24 +193,24 @@ OhMyOpenCodePlugin(ctx) | Category | Forbidden | |----------|-----------| -| Package Manager | npm, yarn - Bun exclusively | -| Types | @types/node - use bun-types | -| File Ops | mkdir/touch/rm/cp/mv in code - use bash tool | -| Publishing | Direct `bun publish` - GitHub Actions only | -| Versioning | Local version bump - CI manages | +| Package Manager | npm, yarn — Bun exclusively | +| Types | @types/node — use bun-types | +| File Ops | mkdir/touch/rm/cp/mv in code — use bash tool | +| Publishing | Direct `bun publish` — GitHub Actions only | +| Versioning | Local version bump — CI manages | | Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` | | Error Handling | Empty catch blocks | | Testing | Deleting failing tests, writing implementation before test | -| Agent Calls | Sequential - use `task` parallel | -| Hook Logic | Heavy PreToolUse - slows every call | +| Agent Calls | Sequential — use `task` parallel | +| Hook Logic | Heavy PreToolUse — slows every call | | Commits | Giant (3+ files), separate test from impl | | Temperature | >0.3 for code agents | -| Trust | Agent self-reports - ALWAYS verify | +| Trust | Agent self-reports — ALWAYS verify | | Git | `git add -i`, `git rebase -i` (no interactive input) | | Git | Skip hooks (--no-verify), force push without request | -| Bash | `sleep N` - use conditional waits | -| Bash | `cd dir && cmd` - use workdir parameter | -| Files | Catch-all utils.ts/helpers.ts - name by purpose | +| Bash | `sleep N` — use conditional waits | +| Bash | `cd dir && cmd` — use workdir parameter | +| Files | Catch-all utils.ts/helpers.ts — name by purpose | ## AGENT MODELS @@ -230,7 +230,7 @@ OhMyOpenCodePlugin(ctx) ## OPENCODE PLUGIN API -Plugin SDK from `@opencode-ai/plugin` (v1.1.19). Plugin = `async (PluginInput) => Hooks`. +Plugin SDK from `@opencode-ai/plugin`. Plugin = `async (PluginInput) => Hooks`. | Hook | Purpose | |------|---------| @@ -283,7 +283,7 @@ bun run build:schema # Regenerate JSON schema | File | Lines | Description | |------|-------|-------------| -| `src/features/background-agent/manager.ts` | 1646 | Task lifecycle, concurrency | +| `src/features/background-agent/manager.ts` | 1701 | Task lifecycle, concurrency | | `src/hooks/anthropic-context-window-limit-recovery/` | 2232 | Multi-strategy context recovery | | `src/hooks/claude-code-hooks/` | 2110 | Claude Code settings.json compat | | `src/hooks/todo-continuation-enforcer/` | 2061 | Core boulder mechanism | @@ -293,7 +293,7 @@ bun run build:schema # Regenerate JSON schema | `src/hooks/rules-injector/` | 1604 | Conditional rules injection | | `src/hooks/think-mode/` | 1365 | Model/variant switching | | `src/hooks/session-recovery/` | 1279 | Auto error recovery | -| `src/features/builtin-skills/skills/git-master.ts` | 1111 | Git master skill | +| `src/features/builtin-skills/skills/git-master.ts` | 1112 | Git master skill | | `src/tools/delegate-task/constants.ts` | 569 | Category routing configs | ## MCP ARCHITECTURE @@ -313,7 +313,7 @@ Three-tier system: ## NOTES - **OpenCode**: Requires >= 1.0.150 -- **1069 TypeScript files**, 176 test files, 117k+ lines +- **1130 TypeScript files**, 176 test files, 127k+ lines - **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution) - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker - **No linter/formatter**: No ESLint, Prettier, or Biome configured diff --git a/src/AGENTS.md b/src/AGENTS.md index 0724e41e6..5c98a4046 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -5,25 +5,26 @@ Main plugin entry point and orchestration layer. Plugin initialization, hook registration, tool composition, and lifecycle management. ## STRUCTURE + ``` src/ -├── index.ts # Main plugin entry (88 lines) — OhMyOpenCodePlugin factory +├── index.ts # Main plugin entry (106 lines) — OhMyOpenCodePlugin factory ├── create-hooks.ts # Hook coordination: core, continuation, skill (62 lines) ├── create-managers.ts # Manager initialization: Tmux, Background, SkillMcp, Config (80 lines) ├── create-tools.ts # Tool registry + skill context composition (54 lines) ├── plugin-interface.ts # Plugin interface assembly — 7 OpenCode hooks (66 lines) -├── plugin-config.ts # Config loading orchestration (user + project merge) -├── plugin-state.ts # Model cache state (context limits, anthropic 1M flag) -├── agents/ # 11 AI agents (32 files) - see agents/AGENTS.md -├── cli/ # CLI installer, doctor (107+ files) - see cli/AGENTS.md -├── config/ # Zod schema (21 component files) - see config/AGENTS.md -├── features/ # Background agents, skills, commands (18 dirs) - see features/AGENTS.md -├── hooks/ # 41 lifecycle hooks (36 dirs) - see hooks/AGENTS.md -├── mcp/ # Built-in MCPs (6 files) - see mcp/AGENTS.md +├── plugin-config.ts # Config loading orchestration (user + project merge, 180 lines) +├── plugin-state.ts # Model cache state (context limits, anthropic 1M flag, 12 lines) +├── agents/ # 11 AI agents (32 files) — see agents/AGENTS.md +├── cli/ # CLI installer, doctor (107+ files) — see cli/AGENTS.md +├── config/ # Zod schema (21 component files) — see config/AGENTS.md +├── features/ # Background agents, skills, commands (18 dirs) — see features/AGENTS.md +├── hooks/ # 41 lifecycle hooks (36 dirs) — see hooks/AGENTS.md +├── mcp/ # Built-in MCPs (6 files) — see mcp/AGENTS.md ├── plugin/ # Plugin interface composition (21 files) -├── plugin-handlers/ # Config loading, plan inheritance (15 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 +├── plugin-handlers/ # Config loading, plan inheritance (15 files) — see plugin-handlers/AGENTS.md +├── shared/ # Cross-cutting utilities (96 files) — see shared/AGENTS.md +└── tools/ # 26 tools (14 dirs) — see tools/AGENTS.md ``` ## PLUGIN INITIALIZATION (10 steps) diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index 2ae8e4dda..4946b8925 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -7,36 +7,22 @@ ## STRUCTURE ``` agents/ -├── sisyphus.ts # Main orchestrator (530 lines) -├── hephaestus.ts # Autonomous deep worker (624 lines) -├── oracle.ts # Strategic advisor (170 lines) -├── librarian.ts # Multi-repo research (328 lines) -├── explore.ts # Fast codebase grep (124 lines) -├── multimodal-looker.ts # Media analyzer (58 lines) +├── sisyphus.ts # Main orchestrator (559 lines) +├── hephaestus.ts # Autonomous deep worker (651 lines) +├── oracle.ts # Strategic advisor (171 lines) +├── librarian.ts # Multi-repo research (329 lines) +├── explore.ts # Fast codebase grep (125 lines) +├── multimodal-looker.ts # Media analyzer (59 lines) ├── metis.ts # Pre-planning analysis (347 lines) ├── momus.ts # Plan validator (244 lines) -├── atlas/ # Master orchestrator -│ ├── agent.ts # Atlas factory -│ ├── default.ts # Claude-optimized prompt -│ ├── gpt.ts # GPT-optimized prompt -│ └── utils.ts -├── prometheus/ # Planning agent -│ ├── index.ts -│ ├── system-prompt.ts # 6-section prompt assembly -│ ├── plan-template.ts # Work plan structure (423 lines) -│ ├── interview-mode.ts # Interview flow (335 lines) -│ ├── plan-generation.ts -│ ├── high-accuracy-mode.ts -│ ├── identity-constraints.ts # Identity rules (301 lines) -│ └── behavioral-summary.ts -├── sisyphus-junior/ # Delegated task executor -│ ├── agent.ts -│ ├── default.ts # Claude prompt -│ └── gpt.ts # GPT prompt -├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (431 lines) -├── builtin-agents/ # Agent registry (8 files) +├── atlas/ # Master orchestrator (agent.ts + default.ts + gpt.ts) +├── prometheus/ # Planning agent (8 files, plan-template 423 lines) +├── sisyphus-junior/ # Delegated task executor (agent.ts + default.ts + gpt.ts) +├── dynamic-agent-prompt-builder.ts # Dynamic prompt generation (433 lines) +├── builtin-agents/ # Agent registry + model resolution +├── agent-builder.ts # Agent construction with category merging (51 lines) ├── utils.ts # Agent creation, model fallback resolution (571 lines) -├── types.ts # AgentModelConfig, AgentPromptMetadata +├── types.ts # AgentModelConfig, AgentPromptMetadata (106 lines) └── index.ts # Exports ``` @@ -78,6 +64,12 @@ agents/ | Momus | 32k budget tokens | reasoningEffort: "medium" | | Sisyphus-Junior | 32k budget tokens | reasoningEffort: "medium" | +## KEY PROMPT PATTERNS + +- **Sisyphus/Hephaestus**: Dynamic prompts via `dynamic-agent-prompt-builder.ts` injecting available tools/skills/categories +- **Atlas, Sisyphus-Junior**: Model-specific prompts (Claude vs GPT variants) +- **Prometheus**: 6-section modular prompt (identity → interview → plan-generation → high-accuracy → template → behavioral) + ## HOW TO ADD 1. Create `src/agents/my-agent.ts` exporting factory + metadata @@ -85,13 +77,6 @@ agents/ 3. Update `AgentNameSchema` in `src/config/schema/agent-names.ts` 4. Register in `src/plugin-handlers/agent-config-handler.ts` -## KEY PATTERNS - -- **Factory**: `createXXXAgent(model): AgentConfig` -- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers -- **Model-specific prompts**: Atlas, Sisyphus-Junior have GPT vs Claude variants -- **Dynamic prompts**: Sisyphus, Hephaestus use `dynamic-agent-prompt-builder.ts` to inject available tools/skills/categories - ## ANTI-PATTERNS - **Trust agent self-reports**: NEVER — always verify outputs diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 46f177a98..5ac159ab2 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -2,9 +2,7 @@ ## OVERVIEW -CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI. - -**Commands**: install, run, doctor, get-local-version, mcp-oauth +CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI. 5 commands: install, run, doctor, get-local-version, mcp-oauth. ## STRUCTURE ``` @@ -14,20 +12,22 @@ cli/ ├── install.ts # TTY routing (TUI or CLI installer) ├── cli-installer.ts # Non-interactive installer (164 lines) ├── tui-installer.ts # Interactive TUI with @clack/prompts (140 lines) -├── config-manager/ # 17 config utilities +├── config-manager/ # 20 config utilities │ ├── add-plugin-to-opencode-config.ts # Plugin registration -│ ├── add-provider-config.ts # Provider setup -│ ├── detect-current-config.ts # Project vs user config +│ ├── add-provider-config.ts # Provider setup (Google/Antigravity) +│ ├── detect-current-config.ts # Installed providers detection │ ├── write-omo-config.ts # JSONC writing -│ └── ... -├── doctor/ # 14 health checks -│ ├── runner.ts # Check orchestration -│ ├── formatter.ts # Colored output -│ └── checks/ # 29 files: auth, config, dependencies, gh, lsp, mcp, opencode, plugin, version, model-resolution (6 sub-checks) +│ ├── generate-omo-config.ts # Config generation +│ ├── jsonc-provider-editor.ts # JSONC editing +│ └── ... # 14 more utilities +├── doctor/ # 4 check categories, 21 check files +│ ├── runner.ts # Parallel check execution + result aggregation +│ ├── formatter.ts # Colored output (default/status/verbose/JSON) +│ └── checks/ # system (4), config (1), tools (4), models (6 sub-checks) ├── run/ # Session launcher (24 files) │ ├── runner.ts # Run orchestration (126 lines) -│ ├── agent-resolver.ts # Agent selection: flag → env → config → fallback -│ ├── session-resolver.ts # Session creation or resume +│ ├── agent-resolver.ts # Agent: flag → env → config → Sisyphus +│ ├── session-resolver.ts # Session create or resume with retries │ ├── event-handlers.ts # Event processing (125 lines) │ ├── completion.ts # Completion detection │ └── poll-for-completion.ts # Polling with timeout @@ -43,20 +43,17 @@ cli/ |---------|---------|-----------| | `install` | Interactive setup | Provider selection → config generation → plugin registration | | `run` | Session launcher | Agent: flag → env → config → Sisyphus. Enforces todo completion. | -| `doctor` | 14 health checks | installation, config, auth, deps, tools, updates | +| `doctor` | 4-category health checks | system, config, tools, models (6 sub-checks) | | `get-local-version` | Version check | Detects installed, compares with npm latest | | `mcp-oauth` | OAuth tokens | login (PKCE flow), logout, status | -## DOCTOR CHECK CATEGORIES +## RUN SESSION LIFECYCLE -| Category | Checks | -|----------|--------| -| installation | opencode, plugin | -| configuration | config validity, Zod, model-resolution (6 sub-checks) | -| authentication | anthropic, openai, google | -| dependencies | ast-grep, comment-checker, gh-cli | -| tools | LSP, MCP, MCP-OAuth | -| updates | version comparison | +1. Load config, resolve agent (CLI > env > config > Sisyphus) +2. Create server connection (port/attach), setup cleanup/signal handlers +3. Resolve session (create new or resume with retries) +4. Send prompt, start event processing, poll for completion +5. Execute on-complete hook, output JSON if requested, cleanup ## HOW TO ADD CHECK diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 1da29b14e..8844ab186 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -7,16 +7,17 @@ ## STRUCTURE ``` features/ -├── background-agent/ # Task lifecycle, concurrency (50 files, 8330 LOC) -│ ├── manager.ts # Main task orchestration (1646 lines) -│ ├── concurrency.ts # Parallel execution limits per provider/model -│ └── spawner/ # Task spawning utilities (8 files) +├── background-agent/ # Task lifecycle, concurrency (56 files, 1701-line manager) +│ ├── manager.ts # Main task orchestration (1701 lines) +│ ├── concurrency.ts # Parallel execution limits per provider/model (137 lines) +│ ├── task-history.ts # Task execution history per parent session (76 lines) +│ └── spawner/ # Task spawning: factory, starter, resumer, tmux (8 files) ├── tmux-subagent/ # Tmux integration (28 files, 3303 LOC) │ └── manager.ts # Pane management, grid planning (350 lines) ├── opencode-skill-loader/ # YAML frontmatter skill loading (28 files, 2967 LOC) │ ├── loader.ts # Skill discovery (4 scopes) -│ ├── skill-directory-loader.ts # Recursive directory scanning -│ ├── skill-discovery.ts # getAllSkills() with caching +│ ├── skill-directory-loader.ts # Recursive directory scanning (maxDepth=2) +│ ├── skill-discovery.ts # getAllSkills() with caching + provider gating │ └── merger/ # Skill merging with scope priority ├── mcp-oauth/ # OAuth 2.0 flow for MCP (18 files, 2164 LOC) │ ├── provider.ts # McpOAuthProvider class @@ -25,10 +26,10 @@ features/ ├── skill-mcp-manager/ # MCP client lifecycle per session (12 files, 1769 LOC) │ └── manager.ts # SkillMcpManager class (150 lines) ├── builtin-skills/ # 5 built-in skills (10 files, 1921 LOC) -│ └── skills/ # git-master (1111), playwright, dev-browser, frontend-ui-ux -├── builtin-commands/ # 6 command templates (11 files, 1511 LOC) -│ └── templates/ # refactor, ralph-loop, init-deep, handoff, start-work, stop-continuation -├── claude-tasks/ # Task schema + storage (7 files, 1165 LOC) +│ └── skills/ # git-master (1112), playwright (313), dev-browser (222), frontend-ui-ux (80) +├── builtin-commands/ # 7 command templates (11 files, 1511 LOC) +│ └── templates/ # refactor (620), init-deep (306), handoff (178), start-work, ralph-loop, stop-continuation +├── claude-tasks/ # Task schema + storage (7 files) — see AGENTS.md ├── context-injector/ # AGENTS.md, README.md, rules injection (6 files, 809 LOC) ├── claude-code-plugin-loader/ # Plugin discovery from .opencode/plugins/ (10 files) ├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion (6 files) @@ -44,7 +45,10 @@ features/ ## KEY PATTERNS **Background Agent Lifecycle:** -Task creation → Queue → Concurrency check → Execute → Monitor/Poll → Notification → Cleanup +pending → running → completed/error/cancelled/interrupt +- Concurrency: Per provider/model limits (default: 5), queue-based FIFO +- Events: session.idle + session.error drive completion detection +- Key methods: `launch()`, `resume()`, `cancelTask()`, `getTask()`, `getAllDescendantTasks()` **Skill Loading Pipeline (4-scope priority):** opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`) diff --git a/src/features/claude-tasks/AGENTS.md b/src/features/claude-tasks/AGENTS.md index b79c65065..25cbcee97 100644 --- a/src/features/claude-tasks/AGENTS.md +++ b/src/features/claude-tasks/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW -Claude Code compatible task schema and storage. Core task management with file-based persistence and atomic writes. +Claude Code compatible task schema and storage. Core task management with file-based persistence, atomic writes, and OpenCode todo sync. ## STRUCTURE ``` @@ -50,39 +50,16 @@ interface Task { ## TODO SYNC -Automatic bidirectional synchronization between tasks and OpenCode's todo system. - -| Function | Purpose | -|----------|---------| -| `syncTaskToTodo(task)` | Convert Task to TodoInfo, returns `null` for deleted tasks | -| `syncTaskTodoUpdate(ctx, task, sessionID, writer?)` | Fetch current todos, update specific task, write back | -| `syncAllTasksToTodos(ctx, tasks, sessionID?)` | Bulk sync multiple tasks to todos | - -### Status Mapping +Automatic bidirectional sync between tasks and OpenCode's todo system. | Task Status | Todo Status | |-------------|-------------| | `pending` | `pending` | | `in_progress` | `in_progress` | | `completed` | `completed` | -| `deleted` | `null` (removed from todos) | +| `deleted` | `null` (removed) | -### Field Mapping - -| Task Field | Todo Field | -|------------|------------| -| `task.id` | `todo.id` | -| `task.subject` | `todo.content` | -| `task.status` (mapped) | `todo.status` | -| `task.metadata.priority` | `todo.priority` | - -Priority values: `"low"`, `"medium"`, `"high"` - -### Automatic Sync Triggers - -Sync occurs automatically on: -- `task_create` — new task added to todos -- `task_update` — task changes reflected in todos +Sync triggers: `task_create`, `task_update`. ## ANTI-PATTERNS diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 1baad1546..1e1b7b34c 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -8,18 +8,18 @@ ``` hooks/ ├── agent-usage-reminder/ # Specialized agent hints (109 lines) -├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines) +├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines, 29 files) ├── anthropic-effort/ # Effort=max for Opus max variant (56 lines) -├── atlas/ # Main orchestration hook (1976 lines) +├── atlas/ # Main orchestration hook (1976 lines, 17 files) ├── auto-slash-command/ # Detects /command patterns (1134 lines) -├── auto-update-checker/ # Plugin update check (1140 lines) +├── auto-update-checker/ # Plugin update check (1140 lines, 20 files) ├── background-notification/ # OS notifications (33 lines) ├── category-skill-reminder/ # Category+skill delegation reminders (597 lines) -├── claude-code-hooks/ # settings.json compat (2110 lines) - see AGENTS.md +├── claude-code-hooks/ # settings.json compat (2110 lines) — see AGENTS.md ├── 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 at 70% (99 lines) +├── context-window-monitor.ts # Reminds of headroom at 70% (100 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) @@ -34,7 +34,7 @@ hooks/ ├── ralph-loop/ # Self-referential dev loop (1687 lines) ├── rules-injector/ # Conditional .sisyphus/rules injection (1604 lines) ├── session-notification.ts # OS idle notifications (108 lines) -├── session-recovery/ # Auto-recovers from crashes (1279 lines) +├── session-recovery/ # Auto-recovers from crashes (1279 lines, 14 files) ├── sisyphus-junior-notepad/ # Junior notepad directive (76 lines) ├── start-work/ # Sisyphus work session starter (648 lines) ├── stop-continuation-guard/ # Guards stop continuation (214 lines) @@ -57,10 +57,10 @@ hooks/ | UserPromptSubmit | `chat.message` | Yes | 4 | | ChatParams | `chat.params` | No | 2 | | PreToolUse | `tool.execute.before` | Yes | 13 | -| PostToolUse | `tool.execute.after` | No | 18 | +| PostToolUse | `tool.execute.after` | No | 15 | | SessionEvent | `event` | No | 17 | | MessagesTransform | `experimental.chat.messages.transform` | No | 1 | -| Compaction | `onSummarize` | No | 1 | +| Compaction | `onSummarize` | No | 2 | ## BLOCKING HOOKS (8) @@ -78,7 +78,7 @@ hooks/ ## EXECUTION ORDER **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork -**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → atlasHook +**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → tasksToDoWriteDisabler → atlasHook **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder ## HOW TO ADD diff --git a/src/hooks/claude-code-hooks/AGENTS.md b/src/hooks/claude-code-hooks/AGENTS.md index e9204a186..46d0d01ab 100644 --- a/src/hooks/claude-code-hooks/AGENTS.md +++ b/src/hooks/claude-code-hooks/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW -Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands. +Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in settings.json. **Config Sources** (priority): `.claude/settings.local.json` > `.claude/settings.json` (project) > `~/.claude/settings.json` (global) @@ -10,21 +10,26 @@ Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode e ``` claude-code-hooks/ ├── 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 -├── pre-compact.ts # PreCompact executor -├── transcript.ts # Tool use recording -├── tool-input-cache.ts # Pre→post input caching +├── claude-code-hooks-hook.ts # Main factory (22 lines) +├── config.ts # Claude settings.json loader (105 lines) +├── config-loader.ts # Extended plugin config (107 lines) +├── pre-tool-use.ts # PreToolUse hook executor (173 lines) +├── post-tool-use.ts # PostToolUse hook executor (200 lines) +├── user-prompt-submit.ts # UserPromptSubmit executor (125 lines) +├── stop.ts # Stop hook executor (122 lines) +├── pre-compact.ts # PreCompact executor (110 lines) +├── transcript.ts # Tool use recording (235 lines) +├── tool-input-cache.ts # Pre→post input caching (51 lines) ├── todo.ts # Todo integration -├── session-hook-state.ts # Active state tracking -├── types.ts # Hook & IO type definitions -├── plugin-config.ts # Default config constants +├── session-hook-state.ts # Active state tracking (11 lines) +├── types.ts # Hook & IO type definitions (204 lines) +├── plugin-config.ts # Default config constants (12 lines) └── handlers/ # Event handlers (5 files) + ├── pre-compact-handler.ts + ├── tool-execute-before-handler.ts + ├── tool-execute-after-handler.ts + ├── chat-message-handler.ts + └── session-event-handler.ts ``` ## HOOK LIFECYCLE diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index 5b3af3e0e..b8288e33e 100644 --- a/src/plugin-handlers/AGENTS.md +++ b/src/plugin-handlers/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW -Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures. +Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures via 6-phase sequential loading. ## STRUCTURE ``` diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index db4e12538..b164fa0e6 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -2,21 +2,21 @@ ## OVERVIEW -84 cross-cutting utilities across 6 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"` +96 cross-cutting utilities across 4 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"` ## STRUCTURE ``` shared/ ├── logger.ts # File logging (/tmp/oh-my-opencode.log) — 62 imports -├── dynamic-truncator.ts # Token-aware context window management (201 lines) -├── model-resolver.ts # 3-step resolution (Override → Fallback → Default) -├── model-availability.ts # Provider model fetching & fuzzy matching (358 lines) -├── model-requirements.ts # Agent/category fallback chains (160 lines) -├── model-resolution-pipeline.ts # Pipeline orchestration (175 lines) +├── dynamic-truncator.ts # Token-aware context window management (202 lines) +├── model-resolver.ts # 3-step resolution entry point (65 lines) +├── model-availability.ts # Provider model fetching & fuzzy matching (359 lines) +├── model-requirements.ts # Agent/category fallback chains (161 lines) — 11 imports +├── model-resolution-pipeline.ts # Pipeline orchestration (176 lines) ├── model-resolution-types.ts # Resolution request/provenance types ├── model-sanitizer.ts # Model name sanitization ├── model-name-matcher.ts # Model name matching (91 lines) -├── model-suggestion-retry.ts # Suggest models on failure (129 lines) +├── model-suggestion-retry.ts # Suggest models on failure (144 lines) ├── model-cache-availability.ts # Cache availability checking ├── fallback-model-availability.ts # Fallback model logic (67 lines) ├── available-models-fetcher.ts # Fetch models from providers (114 lines) @@ -27,42 +27,34 @@ shared/ ├── session-utils.ts # Session cursor, orchestrator detection ├── session-cursor.ts # Message cursor tracking (85 lines) ├── session-injected-paths.ts # Injected file path tracking -├── permission-compat.ts # Tool restriction enforcement (86 lines) +├── permission-compat.ts # Tool restriction enforcement (87 lines) — 9 imports ├── agent-tool-restrictions.ts # Tool restriction definitions ├── agent-variant.ts # Agent variant from config (91 lines) ├── agent-display-names.ts # Agent display name mapping ├── first-message-variant.ts # First message variant types ├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines) ├── claude-config-dir.ts # ~/.claude resolution -├── data-path.ts # XDG-compliant storage (47 lines) +├── data-path.ts # XDG-compliant storage (47 lines) — 11 imports ├── jsonc-parser.ts # JSONC with comment support (66 lines) ├── frontmatter.ts # YAML frontmatter extraction (31 lines) — 10 imports ├── deep-merge.ts # Recursive merge (proto-pollution safe, MAX_DEPTH=50) ├── shell-env.ts # Cross-platform shell environment (111 lines) -├── opencode-version.ts # Semantic version comparison (74 lines) +├── opencode-version.ts # Semantic version comparison (80 lines) ├── external-plugin-detector.ts # Plugin conflict detection (137 lines) -├── opencode-server-auth.ts # Authentication utilities (69 lines) +├── opencode-server-auth.ts # Authentication utilities (190 lines) ├── safe-create-hook.ts # Hook error wrapper (24 lines) ├── pattern-matcher.ts # Pattern matching (40 lines) -├── file-utils.ts # File operations (40 lines) — 9 imports +├── file-utils.ts # File operations (34 lines) — 9 imports ├── file-reference-resolver.ts # File reference resolution (85 lines) ├── snake-case.ts # Case conversion (44 lines) ├── tool-name.ts # Tool naming conventions -├── truncate-description.ts # Description truncation ├── port-utils.ts # Port management (48 lines) ├── zip-extractor.ts # ZIP extraction (83 lines) ├── binary-downloader.ts # Binary download (60 lines) -├── skill-path-resolver.ts # Skill path resolution -├── hook-disabled.ts # Hook disable checking -├── config-errors.ts # Config error types -├── disabled-tools.ts # Disabled tools tracking -├── record-type-guard.ts # Record type guard -├── open-code-client-accessors.ts # Client accessor utilities -├── open-code-client-shapes.ts # Client shape types ├── command-executor/ # Shell execution (6 files, 213 lines) ├── git-worktree/ # Git status/diff parsing (8 files, 311 lines) ├── migration/ # Legacy config migration (5 files, 341 lines) -│ ├── config-migration.ts # Migration orchestration (126 lines) +│ ├── config-migration.ts # Migration orchestration (133 lines) │ ├── agent-names.ts # Agent name mapping (70 lines) │ ├── hook-names.ts # Hook name mapping (36 lines) │ └── model-versions.ts # Model version migration (49 lines) @@ -86,9 +78,9 @@ shared/ ## KEY PATTERNS **3-Step Model Resolution** (Override → Fallback → Default): -```typescript -resolveModelWithFallback({ userModel, fallbackChain, availableModels }) -``` +1. **Override**: UI-selected or user-configured model +2. **Fallback**: Provider/model chain with availability checking +3. **Default**: System fallback when no matches found **System Directive Filtering**: ```typescript diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index ac6e359b4..6c8731caf 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -2,19 +2,19 @@ ## OVERVIEW -24 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent). +26 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent). ## STRUCTURE ``` tools/ ├── delegate-task/ # Category routing (constants.ts 569 lines, tools.ts 213 lines) -├── task/ # 4 individual tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts) +├── task/ # 4 tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts) ├── lsp/ # 6 LSP tools: goto_definition, find_references, symbols, diagnostics, prepare_rename, rename ├── ast-grep/ # 2 tools: search, replace (25 languages) -├── grep/ # Custom grep (60s timeout, 10MB limit) -├── glob/ # File search (60s timeout, 100 file limit) -├── session-manager/ # 4 tools: list, read, search, info (151 lines) -├── call-omo-agent/ # Direct agent invocation (57 lines) +├── grep/ # Content search (60s timeout, 10MB limit) +├── glob/ # File pattern matching (60s timeout, 100 file limit) +├── session-manager/ # 4 tools: list, read, search, info +├── call-omo-agent/ # Direct agent invocation (explore/librarian) ├── background-task/ # background_output, background_cancel ├── interactive-bash/ # Tmux session management (135 lines) ├── look-at/ # Multimodal PDF/image analysis (156 lines) @@ -27,13 +27,14 @@ tools/ | Tool | Category | Pattern | Key Logic | |------|----------|---------|-----------| -| `task_create` | Task | Factory | Create task with auto-generated T-{uuid} ID, threadID recording | -| `task_list` | Task | Factory | List active tasks with summary (excludes completed/deleted) | -| `task_get` | Task | Factory | Retrieve full task object by ID | -| `task_update` | Task | Factory | Update task fields, supports addBlocks/addBlockedBy for dependencies | +| `task_create` | Task | Factory | Auto-generated T-{uuid} ID, threadID recording, dependency management | +| `task_list` | Task | Factory | Active tasks with summary (excludes completed/deleted), filters unresolved blockers | +| `task_get` | Task | Factory | Full task object by ID | +| `task_update` | Task | Factory | Status/field updates, additive addBlocks/addBlockedBy for dependencies | +| `task` | Delegation | Factory | Category routing with skill injection, background execution | | `call_omo_agent` | Agent | Factory | Direct explore/librarian invocation | -| `background_output` | Background | Factory | Retrieve background task result | -| `background_cancel` | Background | Factory | Cancel running background tasks | +| `background_output` | Background | Factory | Retrieve background task result (block, timeout, full_session) | +| `background_cancel` | Background | Factory | Cancel running/all background tasks | | `lsp_goto_definition` | LSP | Direct | Jump to symbol definition | | `lsp_find_references` | LSP | Direct | Find all usages across workspace | | `lsp_symbols` | LSP | Direct | Document or workspace symbol search | @@ -41,121 +42,33 @@ tools/ | `lsp_prepare_rename` | LSP | Direct | Validate rename is possible | | `lsp_rename` | LSP | Direct | Rename symbol across workspace | | `ast_grep_search` | Search | Factory | AST-aware code search (25 languages) | -| `ast_grep_replace` | Search | Factory | AST-aware code replacement | +| `ast_grep_replace` | Search | Factory | AST-aware code replacement (dry-run default) | | `grep` | Search | Factory | Regex content search with safety limits | | `glob` | Search | Factory | File pattern matching | | `session_list` | Session | Factory | List all sessions | -| `session_read` | Session | Factory | Read session messages | +| `session_read` | Session | Factory | Read session messages with filters | | `session_search` | Session | Factory | Search across sessions | | `session_info` | Session | Factory | Session metadata and stats | | `interactive_bash` | System | Direct | Tmux session management | -| `look_at` | System | Factory | Multimodal PDF/image analysis | -| `skill` | Skill | Factory | Execute skill with MCP capabilities | -| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts | -| `slashcommand` | Command | Factory | Slash command dispatch | - -## TASK TOOLS - -Task management system with auto-generated T-{uuid} IDs, dependency tracking, and OpenCode Todo API sync. - -### task_create - -Create a new task with auto-generated ID and threadID recording. - -**Args:** -| Arg | Type | Required | Description | -|-----|------|----------|-------------| -| `subject` | string | Yes | Task subject/title | -| `description` | string | No | Task description | -| `activeForm` | string | No | Active form (present continuous) | -| `metadata` | Record | No | Task metadata | -| `blockedBy` | string[] | No | Task IDs that must complete before this task | -| `blocks` | string[] | No | Task IDs this task blocks | -| `repoURL` | string | No | Repository URL | -| `parentID` | string | No | Parent task ID | - -**Example:** -```typescript -task_create({ - subject: "Implement user authentication", - description: "Add JWT-based auth to API endpoints", - blockedBy: ["T-abc123"] // Wait for database migration -}) -``` - -**Returns:** `{ task: { id, subject } }` - -### task_list - -List all active tasks with summary information. - -**Args:** None - -**Returns:** Array of task summaries with id, subject, status, owner, blockedBy. Excludes completed and deleted tasks. The blockedBy field is filtered to only include unresolved (non-completed) blockers. - -**Example:** -```typescript -task_list() // Returns all active tasks -``` - -**Response includes reminder:** "1 task = 1 task. Maximize parallel execution by running independent tasks (tasks with empty blockedBy) concurrently." - -### task_get - -Retrieve a full task object by ID. - -**Args:** -| Arg | Type | Required | Description | -|-----|------|----------|-------------| -| `id` | string | Yes | Task ID (format: T-{uuid}) | - -**Example:** -```typescript -task_get({ id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694" }) -``` - -**Returns:** `{ task: TaskObject | null }` with all fields: id, subject, description, status, activeForm, blocks, blockedBy, owner, metadata, repoURL, parentID, threadID. - -### task_update - -Update an existing task with new values. Supports additive updates for dependencies. - -**Args:** -| Arg | Type | Required | Description | -|-----|------|----------|-------------| -| `id` | string | Yes | Task ID to update | -| `subject` | string | No | New subject | -| `description` | string | No | New description | -| `status` | "pending" \| "in_progress" \| "completed" \| "deleted" | No | Task status | -| `activeForm` | string | No | Active form (present continuous) | -| `owner` | string | No | Task owner (agent name) | -| `addBlocks` | string[] | No | Task IDs to add to blocks (additive) | -| `addBlockedBy` | string[] | No | Task IDs to add to blockedBy (additive) | -| `metadata` | Record | No | Metadata to merge (set key to null to delete) | - -**Example:** -```typescript -task_update({ - id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694", - status: "completed" -}) - -// Add dependencies -task_update({ - id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694", - addBlockedBy: ["T-other-task"] -}) -``` - -**Returns:** `{ task: TaskObject }` with full updated task. - -**Dependency Management:** Use `addBlockedBy` to declare dependencies on other tasks. Properly managed dependencies enable maximum parallel execution. +| `look_at` | System | Factory | Multimodal PDF/image analysis via dedicated agent | +| `skill` | Skill | Factory | Load skill instructions with MCP support | +| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts from skill-embedded servers | +| `slashcommand` | Command | Factory | Slash command dispatch with argument substitution | ## DELEGATION SYSTEM (delegate-task) -8 built-in categories: `visual-engineering`, `ultrabrain`, `deep`, `artistry`, `quick`, `unspecified-low`, `unspecified-high`, `writing` +8 built-in categories with domain-optimized models: -Each category defines: model, variant, temperature, max tokens, thinking/reasoning config, prompt append, stability flag. +| Category | Model | Domain | +|----------|-------|--------| +| `visual-engineering` | gemini-3-pro | UI/UX, design, styling | +| `ultrabrain` | gpt-5.3-codex xhigh | Deep logic, architecture | +| `deep` | gpt-5.3-codex medium | Autonomous problem-solving | +| `artistry` | gemini-3-pro high | Creative, unconventional | +| `quick` | claude-haiku-4-5 | Trivial tasks | +| `unspecified-low` | claude-sonnet-4-5 | Moderate effort | +| `unspecified-high` | claude-opus-4-6 max | High effort | +| `writing` | kimi-k2p5 | Documentation, prose | ## HOW TO ADD