From d9ab6ab99b0ecf27a617fc88393b08615432c608 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Tue, 13 Jan 2026 21:00:00 +0900 Subject: [PATCH] docs: update AGENTS.md hierarchy with latest structure and line counts - Root: Add Prometheus/Metis/Momus agents, MCP architecture, 82 test files - agents/: Document 7-section delegation and wisdom notepad - auth/: Multi-account load balancing (10 accounts), endpoint fallback - features/: Update background-agent 825 lines, builtin-skills 1230 lines - hooks/: 22+ hooks with event timing details - tools/: sisyphus-task 583 lines, LSP client 632 lines - cli/: config-manager 725 lines, 17+ doctor checks - shared/: Cross-cutting utilities with usage patterns --- AGENTS.md | 66 +++++++++++++++++---------- src/agents/AGENTS.md | 100 +++++++++++++---------------------------- src/auth/AGENTS.md | 46 +++++++++---------- src/cli/AGENTS.md | 61 ++++++++++--------------- src/features/AGENTS.md | 36 +++++++-------- src/hooks/AGENTS.md | 93 +++++++++++++++----------------------- src/shared/AGENTS.md | 21 ++++----- src/tools/AGENTS.md | 91 ++++++++++++++----------------------- 8 files changed, 211 insertions(+), 303 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b9382bb..0194a8d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2026-01-09T15:38:00+09:00 -**Commit:** 0581793 +**Generated:** 2026-01-13T14:45:00+09:00 +**Commit:** e47b5514 **Branch:** dev ## OVERVIEW @@ -13,16 +13,16 @@ OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orc ``` oh-my-opencode/ ├── src/ -│ ├── agents/ # AI agents (7): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker -│ ├── hooks/ # 22 lifecycle hooks - see src/hooks/AGENTS.md +│ ├── agents/ # AI agents (7+): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker, prometheus, metis, momus +│ ├── hooks/ # 22+ lifecycle hooks - see src/hooks/AGENTS.md │ ├── tools/ # LSP, AST-Grep, Grep, Glob, session mgmt - see src/tools/AGENTS.md │ ├── features/ # Claude Code compat layer - see src/features/AGENTS.md │ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md │ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md │ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md -│ ├── mcp/ # MCP configs: context7, grep_app -│ ├── config/ # Zod schema, TypeScript types -│ └── index.ts # Main plugin entry (548 lines) +│ ├── mcp/ # MCP configs: context7, grep_app, websearch +│ ├── config/ # Zod schema (12k lines), TypeScript types +│ └── index.ts # Main plugin entry (563 lines) ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts ├── assets/ # JSON schema └── dist/ # Build output (ESM + .d.ts) @@ -50,7 +50,7 @@ oh-my-opencode/ | Shared utilities | `src/shared/` | Cross-cutting utilities | | Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns | | Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion | -| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (660 lines) | +| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (677 lines) | ## TDD (Test-Driven Development) @@ -83,7 +83,7 @@ oh-my-opencode/ - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly` - **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks - **Naming**: kebab-case directories, createXXXHook/createXXXTool factories -- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR) +- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR), 82 test files - **Temperature**: 0.1 for code agents, max 0.3 ## ANTI-PATTERNS (THIS PROJECT) @@ -122,13 +122,16 @@ oh-my-opencode/ | Agent | Default Model | Purpose | |-------|---------------|---------| -| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator | +| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator with extended thinking | | oracle | openai/gpt-5.2 | Read-only consultation. High-IQ debugging, architecture | | librarian | opencode/glm-4.7-free | Multi-repo analysis, docs | | explore | opencode/grok-code | Fast codebase exploration | | frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation | | document-writer | google/gemini-3-pro-preview | Technical docs | | multimodal-looker | google/gemini-3-flash | PDF/image analysis | +| Prometheus (Planner) | anthropic/claude-opus-4-5 | Strategic planning, interview-driven | +| Metis (Plan Consultant) | anthropic/claude-sonnet-4-5 | Pre-planning analysis | +| Momus (Plan Reviewer) | anthropic/claude-sonnet-4-5 | Plan validation | ## COMMANDS @@ -137,7 +140,7 @@ bun run typecheck # Type check bun run build # ESM + declarations + schema bun run rebuild # Clean + Build bun run build:schema # Schema only -bun test # Run tests (76 test files, 2559+ BDD assertions) +bun test # Run tests (82 test files, 2559+ BDD assertions) ``` ## DEPLOYMENT @@ -160,23 +163,38 @@ bun test # Run tests (76 test files, 2559+ BDD assertions) | File | Lines | Description | |------|-------|-------------| -| `src/agents/orchestrator-sisyphus.ts` | 1484 | Orchestrator agent, complex delegation | +| `src/agents/orchestrator-sisyphus.ts` | 1486 | Orchestrator agent, 7-section delegation, accumulated wisdom | | `src/features/builtin-skills/skills.ts` | 1230 | Skill definitions (frontend-ui-ux, playwright) | -| `src/agents/prometheus-prompt.ts` | 982 | Planning agent system prompt | -| `src/auth/antigravity/fetch.ts` | 798 | Token refresh, URL rewriting | -| `src/auth/antigravity/thinking.ts` | 755 | Thinking block extraction | -| `src/cli/config-manager.ts` | 725 | JSONC parsing, env detection | -| `src/hooks/sisyphus-orchestrator/index.ts` | 660 | Orchestrator hook impl | -| `src/agents/sisyphus.ts` | 641 | Main Sisyphus prompt | -| `src/tools/lsp/client.ts` | 612 | LSP protocol, JSON-RPC | -| `src/features/background-agent/manager.ts` | 608 | Task lifecycle | -| `src/auth/antigravity/response.ts` | 599 | Response transformation, streaming | -| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 556 | Multi-stage recovery | -| `src/index.ts` | 548 | Main plugin, all hook/tool init | +| `src/agents/prometheus-prompt.ts` | 988 | Planning agent, interview mode, multi-agent validation | +| `src/auth/antigravity/fetch.ts` | 798 | Token refresh, multi-account rotation, endpoint fallback | +| `src/auth/antigravity/thinking.ts` | 755 | Thinking block extraction, signature management | +| `src/cli/config-manager.ts` | 725 | JSONC parsing, multi-level config, env detection | +| `src/hooks/sisyphus-orchestrator/index.ts` | 677 | Orchestrator hook impl | +| `src/agents/sisyphus.ts` | 643 | Main Sisyphus prompt | +| `src/tools/lsp/client.ts` | 632 | LSP protocol, JSON-RPC | +| `src/features/background-agent/manager.ts` | 825 | Task lifecycle, concurrency | +| `src/auth/antigravity/response.ts` | 598 | Response transformation, streaming | +| `src/tools/sisyphus-task/tools.ts` | 583 | Category-based task delegation | +| `src/index.ts` | 563 | Main plugin, all hook/tool init | +| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 555 | Multi-stage recovery | + +## MCP ARCHITECTURE + +Three-tier MCP system: +1. **Built-in**: `websearch` (Exa), `context7` (docs), `grep_app` (GitHub search) +2. **Claude Code compatible**: `.mcp.json` files with `${VAR}` expansion +3. **Skill-embedded**: YAML frontmatter in skills (e.g., playwright) + +## CONFIG SYSTEM + +- **Zod validation**: `src/config/schema.ts` (12k lines) +- **JSONC support**: Comments and trailing commas +- **Multi-level**: User (`~/.config/opencode/`) → Project (`.opencode/`) +- **CLI doctor**: Validates config and reports errors ## NOTES -- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 76 test files +- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 82 test files - **OpenCode**: Requires >= 1.0.150 - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN) - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project) diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index e8dfae3c..e1efd964 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -1,25 +1,23 @@ # AGENTS KNOWLEDGE BASE ## OVERVIEW - -AI agent definitions for multi-model orchestration. 7 specialized agents: Sisyphus (orchestrator), oracle (read-only consultation), librarian (research), explore (grep), frontend-ui-ux-engineer, document-writer, multimodal-looker. +AI agent definitions for multi-model orchestration, delegating tasks to specialized experts. ## STRUCTURE - ``` agents/ -├── orchestrator-sisyphus.ts # Orchestrator agent (1484 lines) - complex delegation -├── sisyphus.ts # Main Sisyphus prompt (641 lines) +├── orchestrator-sisyphus.ts # Orchestrator agent (1486 lines) - 7-section delegation, wisdom +├── sisyphus.ts # Main Sisyphus prompt (643 lines) ├── sisyphus-junior.ts # Junior variant for delegated tasks ├── oracle.ts # Strategic advisor (GPT-5.2) -├── librarian.ts # Multi-repo research (Claude Sonnet 4.5) +├── librarian.ts # Multi-repo research (GLM-4.7-free) ├── explore.ts # Fast codebase grep (Grok Code) ├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro) ├── document-writer.ts # Technical docs (Gemini 3 Pro) ├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash) -├── prometheus-prompt.ts # Planning agent prompt (982 lines) -├── metis.ts # Plan Consultant agent (404 lines) -├── momus.ts # Plan Reviewer agent (404 lines) +├── prometheus-prompt.ts # Planning agent prompt (988 lines) - interview mode +├── metis.ts # Plan Consultant agent - pre-planning analysis +├── momus.ts # Plan Reviewer agent - plan validation ├── build-prompt.ts # Shared build agent prompt ├── plan-prompt.ts # Shared plan agent prompt ├── types.ts # AgentModelConfig interface @@ -28,69 +26,35 @@ agents/ ``` ## AGENT MODELS - -| Agent | Default Model | Fallback | Purpose | -|-------|---------------|----------|---------| -| Sisyphus | anthropic/claude-opus-4-5 | - | Primary orchestrator with extended thinking | -| oracle | openai/gpt-5.2 | - | Read-only consultation. High-IQ debugging, architecture | -| librarian | opencode/glm-4.7-free | - | Docs, OSS research, GitHub examples | -| explore | opencode/grok-code | google/gemini-3-flash, anthropic/claude-haiku-4-5 | Fast contextual grep | -| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | UI/UX code generation | -| document-writer | google/gemini-3-pro-preview | - | Technical writing | -| multimodal-looker | google/gemini-3-flash | - | PDF/image analysis | +| Agent | Default Model | Purpose | +|-------|---------------|---------| +| Sisyphus | claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. | +| oracle | openai/gpt-5.2 | High-IQ debugging, architecture, strategic consultation. | +| librarian | glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. | +| explore | grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. | +| frontend-ui-ux | gemini-3-pro | Production-grade UI/UX generation and styling. | +| document-writer | gemini-3-pro | Technical writing, guides, API documentation. | +| Prometheus | claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. | +| Metis | claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. | +| Momus | claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. | ## HOW TO ADD AN AGENT - -1. Create `src/agents/my-agent.ts`: - ```typescript - import type { AgentConfig } from "@opencode-ai/sdk" - - export const myAgent: AgentConfig = { - model: "provider/model-name", - temperature: 0.1, - system: "Agent system prompt...", - tools: { include: ["tool1", "tool2"] }, // or exclude: [...] - } - ``` -2. Add to `builtinAgents` in `src/agents/index.ts` -3. Update `types.ts` if adding new config options - -## AGENT CONFIG OPTIONS - -| Option | Type | Description | -|--------|------|-------------| -| model | string | Model identifier (provider/model-name) | -| temperature | number | 0.0-1.0, most use 0.1 for consistency | -| system | string | System prompt (can be multiline template literal) | -| tools | object | `{ include: [...] }` or `{ exclude: [...] }` | -| top_p | number | Optional nucleus sampling | -| maxTokens | number | Optional max output tokens | +1. Create `src/agents/my-agent.ts` exporting `AgentConfig`. +2. Add to `builtinAgents` in `src/agents/index.ts`. +3. Update `types.ts` if adding new config interfaces. ## MODEL FALLBACK LOGIC +`createBuiltinAgents()` handles resolution: +1. User config override (`agents.{name}.model`). +2. Environment-specific settings (max20, antigravity). +3. Hardcoded defaults in `index.ts`. -`createBuiltinAgents()` in utils.ts handles model fallback: - -1. Check user config override (`agents.{name}.model`) -2. Check installer settings (claude max20, gemini antigravity) -3. Use default model - -**Fallback order for explore**: -- If gemini antigravity enabled → `google/gemini-3-flash` -- If claude max20 enabled → `anthropic/claude-haiku-4-5` -- Default → `opencode/grok-code` (free) - -## ANTI-PATTERNS (AGENTS) - -- **High temperature**: Don't use >0.3 for code-related agents -- **Broad tool access**: Prefer explicit `include` over unrestricted access -- **Monolithic prompts**: Keep prompts focused; delegate to specialized agents -- **Missing fallbacks**: Consider free/cheap fallbacks for rate-limited models +## ANTI-PATTERNS +- **Trusting reports**: NEVER trust subagent self-reports; always verify outputs. +- **High temp**: Don't use >0.3 for code agents (Sisyphus/Prometheus use 0.1). +- **Sequential calls**: Prefer `sisyphus_task` with `run_in_background` for parallelism. ## SHARED PROMPTS - -- **build-prompt.ts**: Base prompt for build agents (OpenCode default + Sisyphus variants) -- **plan-prompt.ts**: Base prompt for plan agents (legacy) -- **prometheus-prompt.ts**: System prompt for Prometheus (Planner) agent -- **metis.ts**: Metis (Plan Consultant) agent for pre-planning analysis - -Used by `src/index.ts` when creating Builder-Sisyphus and Prometheus (Planner) variants. +- **build-prompt.ts**: Unified base for Sisyphus and Builder variants. +- **plan-prompt.ts**: Core planning logic shared across planning agents. +- **orchestrator-sisyphus.ts**: Uses a 7-section prompt structure and "wisdom notepad" to preserve learnings across turns. diff --git a/src/auth/AGENTS.md b/src/auth/AGENTS.md index 526f5f71..e1d2ea10 100644 --- a/src/auth/AGENTS.md +++ b/src/auth/AGENTS.md @@ -1,11 +1,9 @@ # AUTH KNOWLEDGE BASE ## OVERVIEW - Google Antigravity OAuth for Gemini models. Token management, fetch interception, thinking block extraction. ## STRUCTURE - ``` auth/ └── antigravity/ @@ -13,11 +11,11 @@ auth/ ├── oauth.ts # OAuth flow, token acquisition ├── token.ts # Token storage, refresh logic ├── fetch.ts # Fetch interceptor (798 lines) - ├── response.ts # Response transformation (599 lines) + ├── response.ts # Response transformation (598 lines) ├── thinking.ts # Thinking block extraction (755 lines) ├── thought-signature-store.ts # Signature caching ├── message-converter.ts # Format conversion - ├── accounts.ts # Multi-account management + ├── accounts.ts # Multi-account management (up to 10 accounts) ├── browser.ts # Browser automation for OAuth ├── cli.ts # CLI interaction ├── request.ts # Request building @@ -29,33 +27,29 @@ auth/ ``` ## KEY COMPONENTS - | File | Purpose | |------|---------| -| fetch.ts | URL rewriting, token injection, retries | -| thinking.ts | Extract `` blocks | -| response.ts | Streaming SSE parsing | -| oauth.ts | Browser-based OAuth flow | -| token.ts | Token persistence, expiry | +| fetch.ts | URL rewriting, multi-account rotation, endpoint fallback | +| thinking.ts | Thinking block extraction, signature management, budget mapping | +| response.ts | Streaming SSE parsing and response transformation | +| accounts.ts | Load balancing across up to 10 Google accounts | +| thought-signature-store.ts | Caching signatures for multi-turn thinking conversations | ## HOW IT WORKS - -1. **Intercept**: fetch.ts intercepts Anthropic/Google requests -2. **Rewrite**: URLs → Antigravity proxy endpoints -3. **Auth**: Bearer token from stored OAuth credentials -4. **Response**: Streaming parsed, thinking blocks extracted -5. **Transform**: Normalized for OpenCode +1. **Intercept**: `fetch.ts` intercepts Anthropic/Google requests. +2. **Route**: Rotates accounts and selects best endpoint (daily → autopush → prod). +3. **Auth**: Injects Bearer tokens from `token.ts` persistence. +4. **Process**: `response.ts` parses SSE; `thinking.ts` manages thought blocks. +5. **Recovery**: Detects GCP permission errors and triggers recovery/rotation. ## FEATURES - -- Multi-account (up to 10 Google accounts) -- Auto-fallback on rate limit -- Thinking blocks preserved -- Antigravity proxy for AI Studio access +- Multi-account load balancing (up to 10 accounts) +- Strategic endpoint fallback: daily → autopush → prod +- Persistent thought signatures for continuity in thinking models +- Automated GCP permission error recovery ## ANTI-PATTERNS - -- Direct API calls (use fetch interceptor) -- Tokens in code (use token.ts storage) -- Ignoring refresh (check expiry first) -- Blocking on OAuth (always async) +- Hardcoding endpoints: Use `constants.ts` or let `fetch.ts` route. +- Manual token handling: Use `token.ts` and `storage.ts` abstraction. +- Sync OAuth calls: All auth flows must be non-blocking/async. +- Ignoring account rotation: Let `fetch.ts` handle load balancing. diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 1f95d3af..25f02b33 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -1,24 +1,22 @@ # CLI KNOWLEDGE BASE ## OVERVIEW - CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runtime launcher. Entry: `bunx oh-my-opencode`. ## STRUCTURE - ``` cli/ -├── index.ts # Commander.js entry, subcommand routing +├── index.ts # Commander.js entry, subcommand routing (184 lines) ├── install.ts # Interactive TUI installer (436 lines) ├── config-manager.ts # JSONC parsing, env detection (725 lines) ├── types.ts # CLI-specific types -├── commands/ # CLI subcommands +├── commands/ # CLI subcommands (auth.ts) ├── doctor/ # Health check system │ ├── index.ts # Doctor command entry │ ├── runner.ts # Health check orchestration │ ├── constants.ts # Check categories │ ├── types.ts # Check result interfaces -│ └── checks/ # 17+ individual checks (auth, config, dependencies, gh, lsp, mcp, opencode, plugin, version) +│ └── checks/ # 10+ check modules (17+ individual checks) ├── get-local-version/ # Version detection └── run/ # OpenCode session launcher ├── completion.ts # Completion logic @@ -26,47 +24,34 @@ cli/ ``` ## CLI COMMANDS - | Command | Purpose | |---------|---------| -| `install` | Interactive setup wizard | -| `doctor` | Environment health checks | -| `run` | Launch OpenCode session | +| `install` | Interactive setup wizard with subscription detection | +| `doctor` | Environment health checks (LSP, Auth, Config, Deps) | +| `run` | Launch OpenCode session with event handling | +| `auth` | Manage authentication providers | ## DOCTOR CHECKS - 17+ checks in `doctor/checks/`: -- version.ts (OpenCode >= 1.0.150) -- config.ts (plugin registered) -- bun.ts, node.ts, git.ts -- anthropic-auth.ts, openai-auth.ts, google-auth.ts -- lsp-*.ts, mcp-*.ts +- `version.ts`: OpenCode >= 1.0.150 +- `config.ts`: Plugin registration & JSONC validity +- `dependencies.ts`: bun, node, git, gh-cli +- `auth.ts`: Anthropic, OpenAI, Google (Antigravity) +- `lsp.ts`, `mcp.ts`: Tool connectivity checks -## CONFIG-MANAGER (669 lines) - -- JSONC support (comments, trailing commas) -- Multi-source: User (~/.config/opencode/) + Project (.opencode/) -- Zod validation -- Legacy format migration -- Error aggregation for doctor +## CONFIG-MANAGER +- **JSONC**: Supports comments and trailing commas via `parseJsonc` +- **Multi-source**: Merges User (`~/.config/opencode/`) + Project (`.opencode/`) +- **Validation**: Strict Zod schema with error aggregation for `doctor` +- **Env**: Detects `OPENCODE_CONFIG_DIR` for profile isolation ## HOW TO ADD CHECK - -1. Create `src/cli/doctor/checks/my-check.ts`: - ```typescript - export const myCheck: DoctorCheck = { - name: "my-check", - category: "environment", - check: async () => { - return { status: "pass" | "warn" | "fail", message: "..." } - } - } - ``` -2. Add to `src/cli/doctor/checks/index.ts` +1. Create `src/cli/doctor/checks/my-check.ts` returning `DoctorCheck` +2. Export from `checks/index.ts` and add to `getAllCheckDefinitions()` +3. Use `CheckContext` for shared utilities (LSP, Auth) ## ANTI-PATTERNS - - Blocking prompts in non-TTY (check `process.stdout.isTTY`) -- Hardcoded paths (use shared utilities) -- JSON.parse for user files (use parseJsonc) -- Silent failures in doctor checks +- Direct `JSON.parse` (breaks JSONC compatibility) +- Silent failures (always return `warn` or `fail` in `doctor`) +- Environment-specific hardcoding (use `ConfigManager`) diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 75a9b058..835d62d1 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -1,35 +1,34 @@ # FEATURES KNOWLEDGE BASE ## OVERVIEW - Claude Code compatibility layer + core feature modules. Commands, skills, agents, MCPs, hooks from Claude Code work seamlessly. ## STRUCTURE - ``` features/ -├── background-agent/ # Task lifecycle, notifications (608 lines) +├── background-agent/ # Task lifecycle, notifications (825 lines manager.ts) ├── boulder-state/ # Boulder state persistence ├── builtin-commands/ # Built-in slash commands │ └── templates/ # start-work, refactor, init-deep, ralph-loop -├── builtin-skills/ # Built-in skills +├── builtin-skills/ # Built-in skills (1230 lines skills.ts) │ ├── git-master/ # Atomic commits, rebase, history search +│ ├── playwright/ # Browser automation skill │ └── frontend-ui-ux/ # Designer-turned-developer skill ├── claude-code-agent-loader/ # ~/.claude/agents/*.md ├── claude-code-command-loader/ # ~/.claude/commands/*.md ├── claude-code-mcp-loader/ # .mcp.json files │ └── env-expander.ts # ${VAR} expansion -├── claude-code-plugin-loader/ # installed_plugins.json (486 lines) +├── claude-code-plugin-loader/ # installed_plugins.json ├── claude-code-session-state/ # Session state persistence ├── context-injector/ # Context collection and injection ├── opencode-skill-loader/ # Skills from OpenCode + Claude paths ├── skill-mcp-manager/ # MCP servers in skill YAML ├── task-toast-manager/ # Task toast notifications -└── hook-message-injector/ # Inject messages into conversation +├── hook-message-injector/ # Inject messages into conversation +└── context-injector/ # Context collection and injection ``` ## LOADER PRIORITY - | Loader | Priority (highest first) | |--------|--------------------------| | Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` | @@ -38,7 +37,6 @@ features/ | MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` | ## CONFIG TOGGLES - ```json { "claude_code": { @@ -52,21 +50,19 @@ features/ ``` ## BACKGROUND AGENT - - Lifecycle: pending → running → completed/failed -- OS notification on complete -- `background_output` to retrieve results -- `background_cancel` with task_id or all=true +- Concurrency limits per provider/model (manager.ts) +- `background_output` to retrieve results, `background_cancel` for cleanup +- Automatic task expiration and cleanup logic ## SKILL MCP - - MCP servers embedded in skill YAML frontmatter -- Lazy client loading, session-scoped cleanup -- `skill_mcp` tool exposes capabilities +- Lazy client loading via `skill-mcp-manager` +- `skill_mcp` tool for cross-skill tool discovery +- Session-scoped MCP server lifecycle management ## ANTI-PATTERNS - -- Blocking on load (loaders run at startup) -- No error handling (always try/catch) -- Ignoring priority order -- Writing to ~/.claude/ (read-only) +- Sequential execution for independent tasks (use `sisyphus_task`) +- Trusting agent self-reports without verification +- Blocking main thread during loader initialization +- Manual version bumping in `package.json` diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 00697857..9b6106e3 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -1,73 +1,54 @@ # HOOKS KNOWLEDGE BASE ## OVERVIEW - -22+ lifecycle hooks intercepting/modifying agent behavior. Context injection, error recovery, output control, notifications. +22+ lifecycle hooks intercepting/modifying agent behavior via PreToolUse, PostToolUse, UserPromptSubmit, and more. ## STRUCTURE - ``` hooks/ -├── anthropic-context-window-limit-recovery/ # Auto-compact at token limit (556 lines) -├── auto-slash-command/ # Detect and execute /command patterns -├── auto-update-checker/ # Version notifications, startup toast -├── background-notification/ # OS notify on task complete -├── claude-code-hooks/ # settings.json PreToolUse/PostToolUse/etc (408 lines) -├── comment-checker/ # Prevent excessive AI comments -│ ├── filters/ # docstring, directive, bdd, shebang -│ └── output/ # XML builder, formatter -├── compaction-context-injector/ # Preserve context during compaction -├── directory-agents-injector/ # Auto-inject AGENTS.md -├── directory-readme-injector/ # Auto-inject README.md -├── edit-error-recovery/ # Recover from edit failures -├── empty-message-sanitizer/ # Sanitize empty messages -├── interactive-bash-session/ # Tmux session management -├── keyword-detector/ # ultrawork/search keyword activation -├── non-interactive-env/ # CI/headless handling -├── preemptive-compaction/ # Pre-emptive at 85% usage -├── prometheus-md-only/ # Restrict prometheus to read-only -├── ralph-loop/ # Self-referential dev loop +├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (555 lines) +├── sisyphus-orchestrator/ # Main orchestration & agent delegation (677 lines) +├── ralph-loop/ # Self-referential dev loop (364 lines) +├── claude-code-hooks/ # settings.json hook compatibility layer +├── comment-checker/ # Prevents AI slop/excessive comments +├── auto-slash-command/ # Detects and executes /command patterns ├── rules-injector/ # Conditional rules from .claude/rules/ -├── session-recovery/ # Recover from errors (432 lines) -├── sisyphus-orchestrator/ # Main orchestration hook (660 lines) -├── start-work/ # Initialize Sisyphus work session -├── task-resume-info/ # Track task resume state -├── think-mode/ # Auto-detect thinking triggers -├── thinking-block-validator/ # Validate thinking block format -├── agent-usage-reminder/ # Remind to use specialists -├── context-window-monitor.ts # Monitor usage (standalone) -├── session-notification.ts # OS notify on idle -├── todo-continuation-enforcer.ts # Force TODO completion (413 lines) -└── tool-output-truncator.ts # Truncate verbose outputs +├── directory-agents-injector/ # Auto-injects local AGENTS.md files +├── directory-readme-injector/ # Auto-injects local README.md files +├── preemptive-compaction/ # Triggers summary at 85% usage +├── edit-error-recovery/ # Recovers from tool execution failures +├── thinking-block-validator/ # Ensures valid format +├── context-window-monitor.ts # Reminds agents of remaining headroom +├── session-recovery/ # Auto-recovers from session crashes +├── start-work/ # Initializes work sessions (ulw/ulw) +├── think-mode/ # Dynamic thinking budget adjustment +├── background-notification/ # OS notification on task completion +├── todo-continuation-enforcer.ts # Force completion of [ ] items +└── tool-output-truncator.ts # Prevents context bloat from verbose tools ``` ## HOOK EVENTS - -| Event | Timing | Can Block | Use Case | -|-------|--------|-----------|----------| -| PreToolUse | Before tool | Yes | Validate, modify input | -| PostToolUse | After tool | No | Add context, warnings | -| UserPromptSubmit | On prompt | Yes | Inject messages, block | -| Stop | Session idle | No | Inject follow-ups | -| onSummarize | Compaction | No | Preserve context | +| Event | Timing | Can Block | Description | +|-------|--------|-----------|-------------| +| PreToolUse | Before tool | Yes | Validate/modify inputs (e.g., directory-agents-injector) | +| PostToolUse | After tool | No | Append context/warnings (e.g., edit-error-recovery) | +| UserPromptSubmit | On prompt | Yes | Filter/modify user input (e.g., keyword-detector) | +| Stop | Session idle | No | Auto-continue tasks (e.g., todo-continuation-enforcer) | +| onSummarize | Compaction | No | State preservation (e.g., compaction-context-injector) | ## HOW TO ADD - -1. Create `src/hooks/my-hook/` -2. Files: `index.ts` (createMyHook), `constants.ts`, `types.ts` (optional) -3. Return: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }` -4. Export from `src/hooks/index.ts` +1. Create `src/hooks/name/` with `index.ts` factory (e.g., `createMyHook`). +2. Implement `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, or `onSummarize`. +3. Register in `src/hooks/index.ts`. ## PATTERNS - -- **Storage**: JSON file for persistent state across sessions -- **Once-per-session**: Track injected paths in Set -- **Message injection**: Return `{ messages: [...] }` -- **Blocking**: Return `{ blocked: true, message: "..." }` from PreToolUse +- **Context Injection**: Use `PreToolUse` to prepend instructions to tool inputs. +- **Resilience**: Implement `edit-error-recovery` style logic to retry failed tools. +- **Telegraphic UI**: Use `PostToolUse` to add brief warnings without bloating transcript. +- **Statelessness**: Prefer local file storage for state that must persist across sessions. ## ANTI-PATTERNS - -- Heavy computation in PreToolUse (slows every tool call) -- Blocking without actionable message -- Duplicate injection (track what's injected) -- Missing try/catch (don't crash session) +- **Blocking**: Avoid blocking tools unless critical (use warnings in `PostToolUse` instead). +- **Latency**: No heavy computation in `PreToolUse`; it slows every interaction. +- **Redundancy**: Don't inject the same file multiple times; track state in session storage. +- **Prose**: Never use verbose prose in hook outputs; keep it technical and brief. diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index bce0138c..5d8cf37d 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -1,11 +1,9 @@ # SHARED UTILITIES KNOWLEDGE BASE ## OVERVIEW - -Cross-cutting utilities: path resolution, config management, text processing, Claude Code compatibility helpers. +Cross-cutting utilities for path resolution, config management, text processing, and Claude Code compatibility. ## STRUCTURE - ``` shared/ ├── index.ts # Barrel export @@ -30,7 +28,6 @@ shared/ ``` ## WHEN TO USE - | Task | Utility | |------|---------| | Find ~/.claude | `getClaudeConfigDir()` | @@ -43,21 +40,19 @@ shared/ | Legacy names | `migrateLegacyAgentNames()` | ## CRITICAL PATTERNS - ```typescript -// Dynamic truncation +// Dynamic truncation with context budget const output = dynamicTruncate(result, remainingTokens, 0.5) -// Deep merge priority +// Config resolution priority const final = deepMerge(deepMerge(defaults, userConfig), projectConfig) -// Safe JSONC +// Safe JSONC parsing for user-edited files const { config, error } = parseJsoncSafe(content) ``` ## ANTI-PATTERNS - -- Hardcoding paths (use getClaudeConfigDir, getUserConfigPath) -- JSON.parse for user files (use parseJsonc) -- Ignoring truncation (large outputs MUST use dynamicTruncate) -- Direct string concat for configs (use deepMerge) +- Hardcoding paths (use `getClaudeConfigDir`, `getUserConfigPath`) +- Using `JSON.parse` for user configs (always use `parseJsonc`) +- Ignoring output size (large tool outputs MUST use `dynamicTruncate`) +- Manual case conversion (use `toSnakeCase`, `normalizeToolName`) diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index ce6f8284..fd895d47 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -1,85 +1,60 @@ # TOOLS KNOWLEDGE BASE ## OVERVIEW - -Custom tools extending agent capabilities: LSP integration (11 tools), AST-aware code search/replace, file operations with timeouts, background task management. +Custom tools extending agent capabilities: LSP (11 tools), AST-aware search/replace, background tasks, and multimodal analysis. ## STRUCTURE - ``` tools/ -├── ast-grep/ # AST-aware code search/replace (25 languages) -│ ├── cli.ts # @ast-grep/cli subprocess -│ ├── napi.ts # @ast-grep/napi native binding (preferred) -│ ├── constants.ts, types.ts, tools.ts, utils.ts +├── ast-grep/ # AST-aware search/replace (25 languages) +│ ├── cli.ts # @ast-grep/cli fallback +│ └── napi.ts # @ast-grep/napi native binding (preferred) ├── background-task/ # Async agent task management ├── call-omo-agent/ # Spawn explore/librarian agents ├── glob/ # File pattern matching (timeout-safe) ├── grep/ # Content search (timeout-safe) ├── interactive-bash/ # Tmux session management ├── look-at/ # Multimodal analysis (PDF, images) -├── lsp/ # 11 LSP tools -│ ├── client.ts # LSP connection lifecycle (612 lines) -│ ├── utils.ts # LSP utilities (461 lines) -│ ├── config.ts # Server configurations -│ ├── tools.ts # Tool implementations (405 lines) -│ └── types.ts -├── session-manager/ # OpenCode session file management -│ ├── constants.ts # Storage paths, descriptions -│ ├── types.ts # Session data interfaces -│ ├── storage.ts # File I/O operations -│ ├── utils.ts # Formatting, filtering -│ └── tools.ts # Tool implementations -├── sisyphus-task/ # Category-based task delegation (493 lines) -├── skill/ # Skill loading and execution +├── lsp/ # IDE-like code intelligence +│ ├── client.ts # LSP connection lifecycle (632 lines) +│ ├── tools.ts # Tool implementations +│ └── config.ts, types.ts, utils.ts +├── session-manager/ # OpenCode session history management +├── sisyphus-task/ # Category-based delegation (583 lines) +├── skill/ # Skill loading/execution ├── skill-mcp/ # Skill-embedded MCP invocation ├── slashcommand/ # Slash command execution -└── index.ts # builtinTools export +└── index.ts # builtinTools export (82 lines) ``` ## TOOL CATEGORIES - | Category | Tools | Purpose | |----------|-------|---------| -| LSP | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_servers, lsp_prepare_rename, lsp_rename, lsp_code_actions, lsp_code_action_resolve | IDE-like code intelligence | -| AST | ast_grep_search, ast_grep_replace | Pattern-based code search/replace | -| File Search | grep, glob | Content and file pattern matching | -| Session | session_list, session_read, session_search, session_info | OpenCode session file management | -| Background | sisyphus_task, background_output, background_cancel | Async agent orchestration | -| Multimodal | look_at | PDF/image analysis via Gemini | -| Terminal | interactive_bash | Tmux session control | -| Commands | slashcommand | Execute slash commands | -| Skills | skill, skill_mcp | Load skills, invoke skill-embedded MCPs | -| Agents | call_omo_agent | Spawn explore/librarian | +| LSP | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_diagnostics, lsp_rename, etc. | IDE-grade code intelligence (11 tools) | +| AST | ast_grep_search, ast_grep_replace | Structural pattern matching/rewriting | +| Search | grep, glob | Timeout-safe file and content search | +| Session | session_list, session_read, session_search, session_info | History navigation and retrieval | +| Background | sisyphus_task, background_output, background_cancel | Parallel agent orchestration | +| UI/Terminal | look_at, interactive_bash | Visual analysis and tmux control | +| Execution | slashcommand, skill, skill_mcp | Command and skill-based extensibility | ## HOW TO ADD A TOOL - -1. Create directory: `src/tools/my-tool/` -2. Create files: - - `constants.ts`: `TOOL_NAME`, `TOOL_DESCRIPTION` - - `types.ts`: Parameter/result interfaces - - `tools.ts`: Tool implementation (returns OpenCode tool object) - - `index.ts`: Barrel export - - `utils.ts`: Helpers (optional) -3. Add to `builtinTools` in `src/tools/index.ts` +1. Create directory `src/tools/my-tool/`. +2. Implement `tools.ts` (factory), `types.ts`, and `constants.ts`. +3. Export via `index.ts` and register in `src/tools/index.ts`. ## LSP SPECIFICS - -- **Client lifecycle**: Lazy init on first use, auto-shutdown on idle -- **Config priority**: opencode.json > oh-my-opencode.json > defaults -- **Supported servers**: typescript-language-server, pylsp, gopls, rust-analyzer, etc. -- **Custom servers**: Add via `lsp` config in oh-my-opencode.json +- **Lifecycle**: Lazy initialization on first call; auto-shutdown on idle. +- **Config**: Merges `opencode.json` and `oh-my-opencode.json`. +- **Capability**: Supports full LSP spec including `codeAction/resolve` and `prepareRename`. ## AST-GREP SPECIFICS +- **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls). +- **Binding**: Uses `@ast-grep/napi` for performance; ensure patterns are valid AST nodes. +- **Variables**: Supports `$VAR` and `$$$` meta-variables for capture. -- **Meta-variables**: `$VAR` (single node), `$$$` (multiple nodes) -- **Languages**: 25 supported (typescript, tsx, python, rust, go, etc.) -- **Binding**: Prefers @ast-grep/napi (native), falls back to @ast-grep/cli -- **Pattern must be valid AST**: `export async function $NAME($$$) { $$$ }` not fragments - -## ANTI-PATTERNS (TOOLS) - -- **No timeout**: Always use timeout for file operations (default 60s) -- **Blocking main thread**: Use async/await, never sync file ops -- **Ignoring LSP errors**: Gracefully handle server not found/crashed -- **Raw subprocess for ast-grep**: Prefer napi binding for performance +## ANTI-PATTERNS +- **Sync Ops**: Never use synchronous file I/O; blocking the main thread kills responsiveness. +- **No Timeouts**: Always wrap external CLI/LSP calls in timeouts (default 60s). +- **Direct Subprocess**: Avoid raw `spawn` for ast-grep; use NAPI binding. +- **Manual Pathing**: Use `shared/utils` for path normalization across platforms.