diff --git a/AGENTS.md b/AGENTS.md index 0194a8d7..2338365c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2026-01-13T14:45:00+09:00 -**Commit:** e47b5514 +**Generated:** 2026-01-15T14:53:00+09:00 +**Commit:** 89fa9ff1 **Branch:** dev ## OVERVIEW @@ -13,16 +13,15 @@ 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, prometheus, metis, momus +│ ├── agents/ # AI agents (10+): 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, websearch -│ ├── config/ # Zod schema (12k lines), TypeScript types -│ └── index.ts # Main plugin entry (563 lines) +│ ├── config/ # Zod schema, TypeScript types +│ └── index.ts # Main plugin entry (580 lines) ├── script/ # build-schema.ts, publish.ts, generate-changelog.ts ├── assets/ # JSON schema └── dist/ # Build output (ESM + .d.ts) @@ -39,7 +38,6 @@ oh-my-opencode/ | Add skill | `src/features/builtin-skills/` | Create skill dir with SKILL.md | | LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) | | AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding | -| Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google/Gemini models | | Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes | | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders | | Background agents | `src/features/background-agent/` | manager.ts for task management | @@ -50,7 +48,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 (677 lines) | +| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (684 lines) | ## TDD (Test-Driven Development) @@ -83,7 +81,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), 82 test files +- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR), 80+ test files - **Temperature**: 0.1 for code agents, max 0.3 ## ANTI-PATTERNS (THIS PROJECT) @@ -140,7 +138,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 (82 test files, 2559+ BDD assertions) +bun test # Run tests (80+ test files, 2500+ BDD assertions) ``` ## DEPLOYMENT @@ -157,26 +155,23 @@ bun test # Run tests (82 test files, 2559+ BDD assertions) - **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release - **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish -- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions ## COMPLEXITY HOTSPOTS | File | Lines | Description | |------|-------|-------------| -| `src/agents/orchestrator-sisyphus.ts` | 1486 | Orchestrator agent, 7-section delegation, accumulated wisdom | +| `src/agents/orchestrator-sisyphus.ts` | 1485 | 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` | 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/prometheus-prompt.ts` | 991 | Planning agent, interview mode, multi-agent validation | +| `src/features/background-agent/manager.ts` | 928 | Task lifecycle, concurrency | +| `src/cli/config-manager.ts` | 730 | JSONC parsing, multi-level config, env detection | +| `src/hooks/sisyphus-orchestrator/index.ts` | 684 | Orchestrator hook impl | +| `src/tools/sisyphus-task/tools.ts` | 667 | Category-based task delegation | | `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 | +| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template | +| `src/index.ts` | 580 | Main plugin, all hook/tool init | +| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 554 | Multi-stage recovery | ## MCP ARCHITECTURE @@ -187,14 +182,14 @@ Three-tier MCP system: ## CONFIG SYSTEM -- **Zod validation**: `src/config/schema.ts` (12k lines) +- **Zod validation**: `src/config/schema.ts` - **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`, 82 test files +- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 80+ 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 e1efd964..86862d6d 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -6,20 +6,21 @@ AI agent definitions for multi-model orchestration, delegating tasks to speciali ## STRUCTURE ``` agents/ -├── orchestrator-sisyphus.ts # Orchestrator agent (1486 lines) - 7-section delegation, wisdom +├── orchestrator-sisyphus.ts # Orchestrator agent (1485 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 (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) +├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro Preview) +├── document-writer.ts # Technical docs (Gemini 3 Pro Preview) ├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash) -├── prometheus-prompt.ts # Planning agent prompt (988 lines) - interview mode +├── prometheus-prompt.ts # Planning agent prompt (991 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 +├── sisyphus-prompt-builder.ts # Factory for orchestrator prompts ├── types.ts # AgentModelConfig interface ├── utils.ts # createBuiltinAgents(), getAgentName() └── index.ts # builtinAgents export @@ -28,15 +29,15 @@ agents/ ## AGENT MODELS | Agent | Default Model | Purpose | |-------|---------------|---------| -| Sisyphus | claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. | +| Sisyphus | anthropic/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. | +| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. | +| explore | opencode/grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. | +| frontend-ui-ux | google/gemini-3-pro-preview | Production-grade UI/UX generation and styling. | +| document-writer | google/gemini-3-pro-preview | Technical writing, guides, API documentation. | +| Prometheus | anthropic/claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. | +| Metis | anthropic/claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. | +| Momus | anthropic/claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. | ## HOW TO ADD AN AGENT 1. Create `src/agents/my-agent.ts` exporting `AgentConfig`. diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 25f02b33..ff408341 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -6,17 +6,16 @@ CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runt ## STRUCTURE ``` cli/ -├── 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) +├── index.ts # Commander.js entry, subcommand routing (146 lines) +├── install.ts # Interactive TUI installer (462 lines) +├── config-manager.ts # JSONC parsing, env detection (730 lines) ├── types.ts # CLI-specific types -├── 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/ # 10+ check modules (17+ individual checks) +│ └── checks/ # 10 check modules (14 individual checks) ├── get-local-version/ # Version detection └── run/ # OpenCode session launcher ├── completion.ts # Completion logic @@ -28,16 +27,17 @@ cli/ |---------|---------| | `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 | +| `run` | Launch OpenCode session with todo/background completion enforcement | +| `get-local-version` | Detect and return local plugin version & update status | ## DOCTOR CHECKS -17+ checks in `doctor/checks/`: -- `version.ts`: OpenCode >= 1.0.150 +14 checks in `doctor/checks/`: +- `version.ts`: OpenCode >= 1.0.150 & plugin update status - `config.ts`: Plugin registration & JSONC validity -- `dependencies.ts`: bun, node, git, gh-cli +- `dependencies.ts`: AST-Grep (CLI/NAPI), Comment Checker - `auth.ts`: Anthropic, OpenAI, Google (Antigravity) - `lsp.ts`, `mcp.ts`: Tool connectivity checks +- `gh.ts`: GitHub CLI availability ## CONFIG-MANAGER - **JSONC**: Supports comments and trailing commas via `parseJsonc` diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 835d62d1..5bd154cc 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -6,13 +6,13 @@ Claude Code compatibility layer + core feature modules. Commands, skills, agents ## STRUCTURE ``` features/ -├── background-agent/ # Task lifecycle, notifications (825 lines manager.ts) +├── background-agent/ # Task lifecycle, notifications (928 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 (1230 lines skills.ts) │ ├── git-master/ # Atomic commits, rebase, history search -│ ├── playwright/ # Browser automation skill +│ ├── 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 @@ -24,8 +24,7 @@ features/ ├── 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 -└── context-injector/ # Context collection and injection +└── hook-message-injector/ # Inject messages into conversation ``` ## LOADER PRIORITY diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 9b6106e3..7a24a794 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -6,8 +6,9 @@ ## STRUCTURE ``` hooks/ -├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (555 lines) -├── sisyphus-orchestrator/ # Main orchestration & agent delegation (677 lines) +├── sisyphus-orchestrator/ # Main orchestration & agent delegation (684 lines) +├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (554 lines) +├── todo-continuation-enforcer.ts # Force completion of [ ] items (445 lines) ├── ralph-loop/ # Self-referential dev loop (364 lines) ├── claude-code-hooks/ # settings.json hook compatibility layer ├── comment-checker/ # Prevents AI slop/excessive comments @@ -23,7 +24,6 @@ hooks/ ├── 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 ``` diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index 5d8cf37d..0161968b 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -7,6 +7,7 @@ Cross-cutting utilities for path resolution, config management, text processing, ``` shared/ ├── index.ts # Barrel export +├── agent-variant.ts # Agent model/prompt variation logic ├── claude-config-dir.ts # ~/.claude resolution ├── command-executor.ts # Shell exec with variable expansion ├── config-errors.ts # Global error tracking @@ -14,23 +15,31 @@ shared/ ├── data-path.ts # XDG data directory ├── deep-merge.ts # Type-safe recursive merge ├── dynamic-truncator.ts # Token-aware truncation +├── external-plugin-detector.ts # Detect marketplace plugins ├── file-reference-resolver.ts # @filename syntax ├── file-utils.ts # Symlink, markdown detection +├── first-message-variant.ts # Initial prompt variations ├── frontmatter.ts # YAML frontmatter parsing ├── hook-disabled.ts # Check if hook disabled ├── jsonc-parser.ts # JSON with Comments ├── logger.ts # File-based logging ├── migration.ts # Legacy name compat (omo → Sisyphus) ├── model-sanitizer.ts # Normalize model names +├── opencode-config-dir.ts # ~/.config/opencode resolution +├── opencode-version.ts # Version comparison logic ├── pattern-matcher.ts # Tool name matching +├── permission-compat.ts # Legacy permission mapping +├── session-cursor.ts # Track message history pointer ├── snake-case.ts # Case conversion -└── tool-name.ts # PascalCase normalization +├── tool-name.ts # PascalCase normalization +└── zip-extractor.ts # Plugin installation utility ``` ## WHEN TO USE | Task | Utility | |------|---------| | Find ~/.claude | `getClaudeConfigDir()` | +| Find ~/.config/opencode | `getOpenCodeConfigDir()` | | Merge configs | `deepMerge(base, override)` | | Parse user files | `parseJsonc()` | | Check hook enabled | `isHookDisabled(name, list)` | @@ -38,6 +47,9 @@ shared/ | Resolve @file | `resolveFileReferencesInText()` | | Execute shell | `resolveCommandsInText()` | | Legacy names | `migrateLegacyAgentNames()` | +| Version check | `isOpenCodeVersionAtLeast(version)` | +| Map permissions | `normalizePermission()` | +| Track session | `SessionCursor` | ## CRITICAL PATTERNS ```typescript @@ -49,10 +61,14 @@ const final = deepMerge(deepMerge(defaults, userConfig), projectConfig) // Safe JSONC parsing for user-edited files const { config, error } = parseJsoncSafe(content) + +// Version-gated features +if (isOpenCodeVersionAtLeast('1.0.150')) { /* ... */ } ``` ## ANTI-PATTERNS -- Hardcoding paths (use `getClaudeConfigDir`, `getUserConfigPath`) +- Hardcoding paths (use `getClaudeConfigDir`, `getOpenCodeConfigDir`) - Using `JSON.parse` for user configs (always use `parseJsonc`) - Ignoring output size (large tool outputs MUST use `dynamicTruncate`) -- Manual case conversion (use `toSnakeCase`, `normalizeToolName`) +- Manual version parsing (use `opencode-version.ts` utilities) +- Raw permission checks (use `permission-compat.ts`) diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index ee73fed9..277f4eb1 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -1,7 +1,7 @@ # TOOLS KNOWLEDGE BASE ## OVERVIEW -Custom tools extending agent capabilities: LSP (11 tools), AST-aware search/replace, background tasks, and multimodal analysis. +Custom tools extending agent capabilities: LSP (7 tools), AST-aware search/replace, background tasks, and multimodal analysis. ## STRUCTURE ``` @@ -20,11 +20,11 @@ tools/ │ ├── tools.ts # Tool implementations │ └── config.ts, types.ts, utils.ts ├── session-manager/ # OpenCode session history management -├── sisyphus-task/ # Category-based delegation (583 lines) +├── sisyphus-task/ # Category-based delegation (667 lines) ├── skill/ # Skill loading/execution ├── skill-mcp/ # Skill-embedded MCP invocation ├── slashcommand/ # Slash command execution -└── index.ts # builtinTools export (82 lines) +└── index.ts # builtinTools export (75 lines) ``` ## TOOL CATEGORIES @@ -46,7 +46,7 @@ tools/ ## LSP SPECIFICS - **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`. +- **Capability**: Supports full LSP spec including `rename` and `prepareRename`. ## AST-GREP SPECIFICS - **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls).