release: v2.12.2

- Remove unused import OhMyOpenCodeConfig from src/index.ts
- Remove unused import dirname from src/features/opencode-skill-loader/loader.ts
- Remove unused import detectKeywords from src/hooks/keyword-detector/index.ts
- Remove unused import CliMatch from src/tools/ast-grep/utils.ts
- Prefix unused parameter _original in src/tools/ast-grep/utils.ts

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

.github/workflows/sisyphus-agent.yml

@@ -316,10 +316,9 @@ jobs:
 
           ---
 
-          First, acknowledge with `gh issue comment NUMBER_PLACEHOLDER --body "👋 Hey @AUTHOR_PLACEHOLDER! I'm on it..."`
-
-          Then write everything using the todo tools.
-          Then investigate and satisfy the request. Only if user requested to you to work explicitely, then use plan agent to plan, todo obsessivley then create a PR to `BRANCH_PLACEHOLDER` branch.
+          Plan everything using todo tools.
+          Then investigate and satisfy the request. Only if user requested to you to work explicitly, then use plan agent to plan, todo obsessively then create a PR to `BRANCH_PLACEHOLDER` branch.
+          When done, report the result to the issue/PR with `gh issue comment NUMBER_PLACEHOLDER` or `gh pr comment NUMBER_PLACEHOLDER`.
           PROMPT_EOF
           )
 

.opencode/command/publish.md

@@ -1,7 +1,6 @@
 ---
 description: Publish oh-my-opencode to npm via GitHub Actions workflow
 argument-hint: <patch|minor|major>
-model: opencode/big-pickle
 ---
 
 <command-instruction>

AGENTS.md

@@ -1,29 +1,29 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2025-12-28T19:26:00+09:00
-**Commit:** 122e918
+**Generated:** 2026-01-02T22:41:22+09:00
+**Commit:** d0694e5
 **Branch:** dev
 
 ## OVERVIEW
 
-OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orchestration (GPT-5.2, Claude, Gemini, Grok), LSP tools (11), AST-Grep search, MCP integrations (context7, websearch_exa, grep_app). "oh-my-zsh" for OpenCode.
+OpenCode plugin: multi-model agent orchestration (Claude Opus 4.5, GPT-5.2, Gemini 3, Grok), 11 LSP tools, AST-Grep, Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
 
 ## STRUCTURE
 
 ```
 oh-my-opencode/
 ├── src/
-│   ├── agents/        # AI agents (7): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker
-│   ├── hooks/         # 21 lifecycle hooks - see src/hooks/AGENTS.md
-│   ├── tools/         # LSP, AST-Grep, Grep, Glob, etc. - see src/tools/AGENTS.md
-│   ├── mcp/           # MCP servers: context7, websearch_exa, grep_app
-│   ├── features/      # Claude Code compatibility - see src/features/AGENTS.md
+│   ├── agents/        # 7 AI agents - see src/agents/AGENTS.md
+│   ├── hooks/         # 22 lifecycle hooks - see src/hooks/AGENTS.md
+│   ├── tools/         # LSP, AST-Grep, 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, websearch_exa, grep_app
 │   ├── config/        # Zod schema, TypeScript types
-│   ├── auth/          # Google Antigravity OAuth (antigravity/)
-│   ├── shared/        # Utilities: deep-merge, pattern-matcher, logger, etc.
-│   └── index.ts       # Main plugin entry (OhMyOpenCodePlugin)
+│   └── index.ts       # Main plugin entry (464 lines)
 ├── script/            # build-schema.ts, publish.ts, generate-changelog.ts
-├── assets/            # JSON schema
 └── dist/              # Build output (ESM + .d.ts)
 ```
 
@@ -31,58 +31,44 @@ oh-my-opencode/
 
 | Task | Location | Notes |
 |------|----------|-------|
-| Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts |
-| Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts |
-| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools |
+| Add agent | `src/agents/` | Create .ts, add to builtinAgents, update types.ts |
+| Add hook | `src/hooks/` | Dir with createXXXHook(), export from index.ts |
+| Add tool | `src/tools/` | Dir with constants/types/tools.ts, add to builtinTools |
 | Add MCP | `src/mcp/` | Create config, add to index.ts |
-| 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 models |
-| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
+| Add skill | `src/features/builtin-skills/` | Dir with SKILL.md |
+| Config schema | `src/config/schema.ts` | Run `bun run build:schema` after |
 | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
-| Background agents | `src/features/background-agent/` | manager.ts for task management |
-| Interactive terminal | `src/tools/interactive-bash/` | tmux session management |
 
 ## CONVENTIONS
 
-- **Package manager**: Bun only (`bun run`, `bun build`, `bunx`)
+- **Bun only**: `bun run`, `bun test`, `bunx` (NEVER npm/npx)
 - **Types**: bun-types (not @types/node)
-- **Build**: Dual output - `bun build` (ESM) + `tsc --emitDeclarationOnly`
-- **Exports**: Barrel pattern - `export * from "./module"` in index.ts
-- **Directory naming**: kebab-case (`ast-grep/`, `claude-code-hooks/`)
-- **Tool structure**: index.ts, types.ts, constants.ts, tools.ts, utils.ts
-- **Hook pattern**: `createXXXHook(input: PluginInput)` returning event handlers
-- **Test style**: BDD comments `#given`, `#when`, `#then` (same as AAA)
+- **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` (same as AAA)
+- **Temperature**: 0.1 for code agents, max 0.3
 
-## ANTI-PATTERNS (THIS PROJECT)
+## ANTI-PATTERNS
 
-- **npm/yarn**: Use bun exclusively
-- **@types/node**: Use bun-types
-- **Bash file ops**: Never mkdir/touch/rm/cp/mv for file creation in code
-- **Direct bun publish**: GitHub Actions workflow_dispatch only (OIDC provenance)
-- **Local version bump**: Version managed by CI workflow
-- **Year 2024**: NEVER use 2024 in code/prompts (use current year)
-- **Rush completion**: Never mark tasks complete without verification
-- **Over-exploration**: Stop searching when sufficient context found
-
-## UNIQUE STYLES
-
-- **Platform**: Union type `"darwin" | "linux" | "win32" | "unsupported"`
-- **Optional props**: Extensive `?` for optional interface properties
-- **Flexible objects**: `Record<string, unknown>` for dynamic configs
-- **Error handling**: Consistent try/catch with async/await
-- **Agent tools**: `tools: { include: [...] }` or `tools: { exclude: [...] }`
-- **Temperature**: Most agents use `0.1` for consistency
-- **Hook naming**: `createXXXHook` function convention
+| Category | Forbidden |
+|----------|-----------|
+| Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
+| Package Manager | npm, yarn, npx |
+| File Ops | Bash mkdir/touch/rm for code file creation |
+| Publishing | Direct `bun publish`, local version bump |
+| Agent Behavior | High temp (>0.3), broad tool access, sequential agent calls |
+| Hooks | Heavy PreToolUse logic, blocking without reason |
+| Year | 2024 in code/prompts (use current year) |
 
 ## AGENT MODELS
 
 | Agent | Model | Purpose |
 |-------|-------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
-| oracle | openai/gpt-5.2 | Strategic advisor, code review |
-| librarian | anthropic/claude-sonnet-4-5 | Multi-repo analysis, docs |
-| explore | opencode/grok-code | Fast codebase exploration |
+| oracle | openai/gpt-5.2 | Strategy, code review |
+| librarian | anthropic/claude-sonnet-4-5 | Docs, OSS research |
+| explore | opencode/grok-code | Fast codebase grep |
 | 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 |
@@ -93,8 +79,7 @@ oh-my-opencode/
 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
+bun test               # Run tests (380+)
 ```
 
 ## DEPLOYMENT
@@ -102,20 +87,26 @@ bun test               # Run tests
 **GitHub Actions workflow_dispatch only**
 
 1. Never modify package.json version locally
-2. Commit & push changes
-3. Trigger `publish` workflow: `gh workflow run publish -f bump=patch`
+2. Commit & push to dev
+3. Trigger: `gh workflow run publish -f bump=patch|minor|major`
 
-**Critical**: Never `bun publish` directly. Never bump version locally.
+CI auto-commits schema changes on master, maintains rolling `next` draft release on dev.
 
-## CI PIPELINE
+## COMPLEXITY HOTSPOTS
 
-- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master
-- **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish
+| File | Lines | Description |
+|------|-------|-------------|
+| `src/index.ts` | 464 | Main plugin, all hook/tool init |
+| `src/cli/config-manager.ts` | 669 | JSONC parsing, env detection |
+| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting |
+| `src/tools/lsp/client.ts` | 611 | LSP protocol, JSON-RPC |
+| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 564 | Multi-stage recovery |
+| `src/agents/sisyphus.ts` | 504 | Orchestrator prompt |
 
 ## NOTES
 
-- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`
 - **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)
-- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
+- **Config**: `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`
+- **JSONC**: Config files support comments and trailing commas
+- **Claude Code**: Full compat layer for settings.json hooks, commands, skills, agents, MCPs
+- **Skill MCP**: Skills can embed MCP server configs in YAML frontmatter

README.ja.md

@@ -4,7 +4,7 @@
 >
 > 一緒に歩みましょう！
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | [Discordコミュニティ](https://discord.gg/PWpXmbhF)に参加して、コントリビューターや`oh-my-opencode`仲間とつながりましょう。 |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/aSfGzWtYxM) | [Discordコミュニティ](https://discord.gg/aSfGzWtYxM)に参加して、コントリビューターや`oh-my-opencode`仲間とつながりましょう。 |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode`に関するニュースは私のXアカウントで投稿していましたが、無実の罪で凍結されたため、<br />[@justsisyphus](https://x.com/justsisyphus)が代わりに更新を投稿しています。 |
 > | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [スポンサーになって](https://github.com/sponsors/code-yeongyu) `oh-my-opencode` の開発を応援してください。皆さまのご支援がこのプロジェクトを成長させます。 |
@@ -128,6 +128,12 @@ Windows から Linux に初めて乗り換えた時のこと、自分の思い
   - なぜこれが良いのか、単なるボイラープレートではないのか、具体的に何が良くなるのか聞いてみてください。
   - もしあなたが LLM エージェントなら、このプロジェクトによって今すぐ何が可能になるのか、ユーザーに説明してください。
 
+### 🪄 魔法の言葉：`ultrawork`
+
+**これ全部読みたくない？プロンプトに `ultrawork`（または `ulw`）を入れるだけでOK。**
+
+それだけです。私たちが提供するすべての機能が魔法のように動作します—並列エージェント、バックグラウンドタスク、深い探索、そして完了するまで止まらない実行。エージェントが自動的にすべてを処理します。
+
 ### 読みたい方のために：シジフォスに会う
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -223,8 +229,12 @@ OpenCode がインストールされていない場合は、[OpenCode インス
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# bunx が動作しない場合は npx を使用
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian ユーザーへの注意**: Snap で Bun をインストールした場合 (`/snap/bin/bun`)、Snap のサンドボックス化により `bunx` が「script not found」エラーで失敗します。代わりに `npx` を使用するか、公式インストーラーで Bun を再インストールしてください: `curl -fsSL https://bun.sh/install | bash`
+
 **例：**
 - すべてのサブスクリプション + max20: `bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - Claude のみ（max20 なし）: `bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -635,6 +645,12 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 
 エージェントが活躍すれば、あなたも幸せになります。ですが、私はあなた自身も助けたいのです。
 
+- **Ralph Loop**: タスクが完了するまで実行し続ける自己参照型開発ループ。Anthropic の Ralph Wiggum プラグインにインスパイアされています。**すべてのプログラミング言語をサポート。**
+  - `/ralph-loop "REST API を構築"` で開始するとエージェントが継続的に作業します
+  - `<promise>DONE</promise>` の出力で完了を検知
+  - 完了プロミスなしで停止すると自動再開
+  - 終了条件: 完了検知、最大反復回数到達（デフォルト 100）、または `/cancel-ralph`
+  - `oh-my-opencode.json` で設定: `{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }`
 - **Keyword Detector**: プロンプト内のキーワードを自動検知して専門モードを有効化します：
   - `ultrawork` / `ulw`: 並列エージェントオーケストレーションによる最大パフォーマンスモード
   - `search` / `find` / `찾아` / `検索`: 並列 explore/librarian エージェントによる検索最大化
@@ -654,6 +670,10 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 - **Empty Message Sanitizer**: 空のチャットメッセージによるAPIエラーを防止します。送信前にメッセージ内容を自動的にサニタイズします。
 - **Grep Output Truncator**: grep は山のようなテキストを返すことがあります。残りのコンテキストウィンドウに応じて動的に出力を切り詰めます—50% の余裕を維持し、最大 50k トークンに制限します。
 - **Tool Output Truncator**: 同じ考え方をより広範囲に適用します。Grep、Glob、LSP ツール、AST-grep の出力を切り詰めます。一度の冗長な検索がコンテキスト全体を食いつぶすのを防ぎます。
+- **Preemptive Compaction**: トークン制限に達する前にセッションを事前にコンパクションします。コンテキストウィンドウ使用率85%で実行されます。**デフォルトで有効。** `disabled_hooks: ["preemptive-compaction"]`で無効化できます。
+- **Compaction Context Injector**: セッションコンパクション中に重要なコンテキスト（AGENTS.md、現在のディレクトリ情報）を保持し、重要な状態を失わないようにします。
+- **Thinking Block Validator**: thinking ブロックを検証し、適切なフォーマットを確保し、不正な thinking コンテンツによる API エラーを防ぎます。
+- **Claude Code Hooks**: Claude Code の settings.json からフックを実行します - これは PreToolUse/PostToolUse/UserPromptSubmit/Stop フックを実行する互換性レイヤーです。
 
 ## 設定
 
@@ -749,7 +769,19 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-各エージェントでサポートされるオプション：`model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`。
+各エージェントでサポートされるオプション：`model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`。
+
+`prompt_append` を使用すると、デフォルトのシステムプロンプトを置き換えずに追加の指示を付け加えられます：
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Emacs Lisp のドキュメント検索には常に elisp-dev-mcp を使用してください。"
+    }
+  }
+}
+```
 
 `Sisyphus` (メインオーケストレーター) と `build` (デフォルトエージェント) も同じオプションで設定をオーバーライドできます。
 
@@ -868,7 +900,7 @@ Oh My OpenCode は以下の場所からフックを読み込んで実行しま
 }
 ```
 
-利用可能なフック：`todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-auto-compact`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `preemptive-compaction`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`
+利用可能なフック：`todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **`auto-update-checker`と`startup-toast`について**: `startup-toast` フックは `auto-update-checker` のサブ機能です。アップデートチェックは有効なまま起動トースト通知のみを無効化するには、`disabled_hooks` に `"startup-toast"` を追加してください。すべてのアップデートチェック機能（トーストを含む）を無効化するには、`"auto-update-checker"` を追加してください。
 
@@ -920,20 +952,21 @@ OpenCode でサポートされるすべての LSP 構成およびカスタム設
 ```json
 {
   "experimental": {
+    "preemptive_compaction_threshold": 0.85,
+    "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
-    "auto_resume": true,
-    "truncate_all_tool_outputs": false,
-    "dcp_on_compaction_failure": true
+    "auto_resume": true
   }
 }
 ```
 
-| オプション                  | デフォルト | 説明                                                                                                                                                                   |
-| --------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aggressive_truncation`     | `false`    | トークン制限を超えた場合、ツール出力を積極的に切り詰めて制限内に収めます。デフォルトの切り詰めより積極的です。不十分な場合は要約/復元にフォールバックします。                 |
-| `auto_resume`               | `false`    | thinking block エラーや thinking disabled violation からの回復成功後、自動的にセッションを再開します。最後のユーザーメッセージを抽出して続行します。                        |
-| `truncate_all_tool_outputs` | `true`     | プロンプトが長くなりすぎるのを防ぐため、コンテキストウィンドウの使用状況に基づいてすべてのツール出力を動的に切り詰めます。完全なツール出力が必要な場合は`false`に設定して無効化します。 |
-| `dcp_for_compaction`        | `false`    | 有効にすると、トークン制限エラー発生時にDCP（Dynamic Context Pruning）が最初に実行され、その後コンパクションが実行されます。DCPが不要なコンテキストを整理した後、すぐにコンパクションが進行します。トークン制限に達した際によりスマートな回復が必要な場合は有効にしてください。 |
+| オプション                        | デフォルト | 説明                                                                                                                                                                   |
+| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preemptive_compaction_threshold` | `0.85`     | プリエンプティブコンパクションをトリガーする閾値（0.5-0.95）。`preemptive-compaction` フックはデフォルトで有効です。このオプションで閾値をカスタマイズできます。                 |
+| `truncate_all_tool_outputs`       | `false`    | ホワイトリストのツール（Grep、Glob、LSP、AST-grep）だけでなく、すべてのツール出力を切り詰めます。Tool output truncator はデフォルトで有効です - `disabled_hooks`で無効化できます。 |
+| `aggressive_truncation`           | `false`    | トークン制限を超えた場合、ツール出力を積極的に切り詰めて制限内に収めます。デフォルトの切り詰めより積極的です。不十分な場合は要約/復元にフォールバックします。                 |
+| `auto_resume`                     | `false`    | thinking block エラーや thinking disabled violation からの回復成功後、自動的にセッションを再開します。最後のユーザーメッセージを抽出して続行します。                        |
+| `dcp_for_compaction`              | `false`    | コンパクション用DCP（動的コンテキスト整理）を有効化 - トークン制限超過時に最初に実行されます。コンパクション前に重複したツール呼び出しと古いツール出力を整理します。                |
 
 **警告**：これらの機能は実験的であり、予期しない動作を引き起こす可能性があります。影響を理解した場合にのみ有効にしてください。
 

README.ko.md

@@ -4,7 +4,7 @@
 >
 > 함께해주세요!
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | [Discord 커뮤니티](https://discord.gg/PWpXmbhF)에서 기여자들과 `oh-my-opencode` 사용자들을 만나보세요. |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/aSfGzWtYxM) | [Discord 커뮤니티](https://discord.gg/aSfGzWtYxM)에서 기여자들과 `oh-my-opencode` 사용자들을 만나보세요. |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode` 관련 소식은 제 X 계정에서 올렸었는데, 억울하게 정지당해서 <br />[@justsisyphus](https://x.com/justsisyphus)가 대신 소식을 전하고 있습니다. |
 > | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [스폰서가 되어](https://github.com/sponsors/code-yeongyu) `oh-my-opencode` 개발을 응원해주세요. 여러분의 후원이 이 프로젝트를 계속 성장시킵니다. |
@@ -127,6 +127,12 @@ OpenCode 가 낭만이 사라진것같은 오늘날의 시대에, 당신에게
   - 이게 왜 좋고, 그냥 뻔한 셋업이 아닌지, 당장 무엇이 더 좋아지는지 알려달라고 해보세요.
   - 당신이 LLM 에이전트라면, 사용자의 입장에서 이 프로젝트와 함께 당장 어떤것들이 가능해지는지 사용자에게 설명하세요.
 
+### 🪄 마법의 단어: `ultrawork`
+
+**이거 다 읽기 싫으시죠? 프롬프트에 `ultrawork` (또는 `ulw`) 만 넣으세요.**
+
+그게 다입니다. 우리가 제공하는 모든 기능이 마법처럼 작동합니다—병렬 에이전트, 백그라운드 태스크, 깊은 탐색, 그리고 완료될 때까지 멈추지 않는 실행. 에이전트가 알아서 다 합니다.
+
 ### 하지만 읽고 싶은 당신을 위해: 시지푸스를 만나보세요
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -220,8 +226,12 @@ OpenCode가 설치되어 있지 않다면, [OpenCode 설치 가이드](https://o
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# bunx가 작동하지 않으면 npx 사용
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian 사용자 참고**: Snap으로 Bun을 설치한 경우 (`/snap/bin/bun`), Snap의 샌드박싱으로 인해 `bunx`가 "script not found" 오류와 함께 실패합니다. 대신 `npx`를 사용하거나, 공식 설치 스크립트로 Bun을 재설치하세요: `curl -fsSL https://bun.sh/install | bash`
+
 **예시:**
 - 모든 구독 + max20: `bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - Claude만 (max20 없음): `bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -628,6 +638,12 @@ Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
 
 에이전트들이 행복해지면, 당신이 제일 행복해집니다, 그렇지만 저는 당신도 돕고싶습니다.
 
+- **Ralph Loop**: 작업이 완료될 때까지 계속 실행되는 자기 참조 개발 루프. Anthropic의 Ralph Wiggum 플러그인에서 영감을 받았습니다. **모든 프로그래밍 언어 지원.**
+  - `/ralph-loop "REST API 구축"`으로 시작하면 에이전트가 지속적으로 작업합니다
+  - `<promise>DONE</promise>` 출력 시 완료로 감지
+  - 완료 프라미스 없이 멈추면 자동 재시작
+  - 종료 조건: 완료 감지, 최대 반복 도달 (기본 100회), 또는 `/cancel-ralph`
+  - `oh-my-opencode.json`에서 설정: `{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }`
 - **Keyword Detector**: 프롬프트의 키워드를 자동 감지하여 전문 모드를 활성화합니다:
   - `ultrawork` / `ulw`: 병렬 에이전트 오케스트레이션으로 최대 성능 모드
   - `search` / `find` / `찾아` / `検索`: 병렬 explore/librarian 에이전트로 검색 극대화
@@ -647,7 +663,7 @@ Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
 - **Empty Message Sanitizer**: 빈 채팅 메시지로 인한 API 오류를 방지합니다. 전송 전 메시지 내용을 자동으로 정리합니다.
 - **Grep Output Truncator**: grep은 산더미 같은 텍스트를 반환할 수 있습니다. 남은 컨텍스트 윈도우에 따라 동적으로 출력을 축소합니다—50% 여유 공간 유지, 최대 50k 토큰.
 - **Tool Output Truncator**: 같은 아이디어, 더 넓은 범위. Grep, Glob, LSP 도구, AST-grep의 출력을 축소합니다. 한 번의 장황한 검색이 전체 컨텍스트를 잡아먹는 것을 방지합니다.
-- **선제적 압축 (Preemptive Compaction)**: 세션 토큰 한계에 도달하기 전에 선제적으로 세션을 압축합니다. 문제가 발생하기 전에 미리 실행됩니다.
+- **선제적 압축 (Preemptive Compaction)**: 세션 토큰 한계에 도달하기 전에 선제적으로 세션을 압축합니다. 컨텍스트 윈도우 사용량 85%에서 실행됩니다. **기본적으로 활성화됨.** `disabled_hooks: ["preemptive-compaction"]`으로 비활성화 가능.
 - **압축 컨텍스트 주입기 (Compaction Context Injector)**: 세션 압축 중에 중요한 컨텍스트(AGENTS.md, 현재 디렉토리 정보 등)를 유지하여 중요한 상태를 잃지 않도록 합니다.
 - **사고 블록 검증기 (Thinking Block Validator)**: 사고(thinking) 블록의 형식이 올바른지 검증하여 잘못된 형식으로 인한 API 오류를 방지합니다.
 - **Claude Code 훅 (Claude Code Hooks)**: Claude Code의 settings.json에 설정된 훅을 실행합니다. PreToolUse/PostToolUse/UserPromptSubmit/Stop 이벤트를 지원하는 호환성 레이어입니다.
@@ -746,7 +762,19 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-각 에이전트에서 지원하는 옵션: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+각 에이전트에서 지원하는 옵션: `model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+`prompt_append`를 사용하면 기본 시스템 프롬프트를 대체하지 않고 추가 지시사항을 덧붙일 수 있습니다:
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Emacs Lisp 문서 조회 시 항상 elisp-dev-mcp를 사용하세요."
+    }
+  }
+}
+```
 
 `Sisyphus` (메인 오케스트레이터)와 `build` (기본 에이전트)도 동일한 옵션으로 설정을 오버라이드할 수 있습니다.
 
@@ -865,7 +893,7 @@ Schema 자동 완성이 지원됩니다:
 }
 ```
 
-사용 가능한 훅: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-auto-compact`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `preemptive-compaction`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`
+사용 가능한 훅: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **`auto-update-checker`와 `startup-toast`에 대한 참고사항**: `startup-toast` 훅은 `auto-update-checker`의 하위 기능입니다. 업데이트 확인은 유지하면서 시작 토스트 알림만 비활성화하려면 `disabled_hooks`에 `"startup-toast"`를 추가하세요. 모든 업데이트 확인 기능(토스트 포함)을 비활성화하려면 `"auto-update-checker"`를 추가하세요.
 
@@ -917,20 +945,21 @@ OpenCode 에서 지원하는 모든 LSP 구성 및 커스텀 설정 (opencode.js
 ```json
 {
   "experimental": {
+    "preemptive_compaction_threshold": 0.85,
+    "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
-    "auto_resume": true,
-    "truncate_all_tool_outputs": false,
-    "dcp_on_compaction_failure": true
+    "auto_resume": true
   }
 }
 ```
 
-| 옵션                        | 기본값  | 설명                                                                                                                                                              |
-| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aggressive_truncation`     | `false` | 토큰 제한을 초과하면 도구 출력을 공격적으로 잘라내어 제한 내에 맞춥니다. 기본 truncation보다 더 공격적입니다. 부족하면 요약/복구로 fallback합니다.                      |
-| `auto_resume`               | `false` | thinking block 에러나 thinking disabled violation으로부터 성공적으로 복구한 후 자동으로 세션을 재개합니다. 마지막 사용자 메시지를 추출하여 계속합니다.                |
-| `truncate_all_tool_outputs` | `true`  | 프롬프트가 너무 길어지는 것을 방지하기 위해 컨텍스트 윈도우 사용량에 따라 모든 도구 출력을 동적으로 잘라냅니다. 전체 도구 출력이 필요한 경우 `false`로 설정하여 비활성화하세요. |
-| `dcp_for_compaction`        | `false` | 활성화하면, 토큰 제한 에러 발생 시 DCP(Dynamic Context Pruning)가 가장 먼저 실행되고, 그 다음 compaction이 실행됩니다. DCP가 불필요한 컨텍스트를 정리한 후 바로 compaction이 진행됩니다. 토큰 제한에 도달했을 때 더 스마트한 복구를 원하면 활성화하세요. |
+| 옵션                              | 기본값  | 설명                                                                                                                                                              |
+| --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preemptive_compaction_threshold` | `0.85`  | 선제적 컴팩션을 트리거할 임계값 비율(0.5-0.95). `preemptive-compaction` 훅은 기본적으로 활성화되어 있으며, 이 옵션으로 임계값을 커스터마이즈할 수 있습니다.                 |
+| `truncate_all_tool_outputs`       | `false` | 화이트리스트 도구(Grep, Glob, LSP, AST-grep)만이 아닌 모든 도구 출력을 잘라냅니다. Tool output truncator는 기본적으로 활성화됩니다 - `disabled_hooks`로 비활성화 가능합니다. |
+| `aggressive_truncation`           | `false` | 토큰 제한을 초과하면 도구 출력을 공격적으로 잘라내어 제한 내에 맞춥니다. 기본 truncation보다 더 공격적입니다. 부족하면 요약/복구로 fallback합니다.                      |
+| `auto_resume`                     | `false` | thinking block 에러나 thinking disabled violation으로부터 성공적으로 복구한 후 자동으로 세션을 재개합니다. 마지막 사용자 메시지를 추출하여 계속합니다.                |
+| `dcp_for_compaction`              | `false` | 컴팩션용 DCP(동적 컨텍스트 정리) 활성화 - 토큰 제한 초과 시 먼저 실행됩니다. 컴팩션 전에 중복 도구 호출과 오래된 도구 출력을 정리합니다.                                  |
 
 **경고**: 이 기능들은 실험적이며 예상치 못한 동작을 유발할 수 있습니다. 의미를 이해한 경우에만 활성화하세요.
 

README.md

@@ -2,9 +2,12 @@
 >
 > *"I aim to spark a software revolution by creating a world where agent-generated code is indistinguishable from human code, yet capable of achieving vastly more. I have poured my personal time, passion, and funds into this journey, and I will continue to do so."*
 >
+> [![The Orchestrator is coming](./.github/assets/orchestrator-sisyphus.png)](https://x.com/justsisyphus/status/2006250634354548963)
+> > **The Orchestrator is coming. This Week. [Get notified on X](https://x.com/justsisyphus/status/2006250634354548963)**
+>
 > Be with us!
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | Join our [Discord community](https://discord.gg/PWpXmbhF) to connect with contributors and fellow `oh-my-opencode` users. |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/aSfGzWtYxM) | Join our [Discord community](https://discord.gg/aSfGzWtYxM) to connect with contributors and fellow `oh-my-opencode` users. |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | News and updates for `oh-my-opencode` used to be posted on my X account. <br /> Since it was suspended mistakenly, [@justsisyphus](https://x.com/justsisyphus) now posts updates on my behalf. |
 > | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | Support the development of `oh-my-opencode` by [becoming a sponsor](https://github.com/sponsors/code-yeongyu). Your contribution helps keep this project alive and growing. |
@@ -149,6 +152,12 @@ Hand this doc to an agent and let them set it up.
   - Ask why it's good, why it's not just another boilerplate setup, what actually gets better.
   - If you're an LLM agent, explain to the user what becomes possible right now with this project.
 
+### 🪄 The Magic Word: `ultrawork`
+
+**Don't want to read all this? Just include `ultrawork` (or `ulw`) in your prompt.**
+
+That's it. All the features we provide will work like magic—parallel agents, background tasks, deep exploration, and relentless execution until completion. The agent figures out the rest automatically.
+
 ### For Those Who Want to Read: Meet Sisyphus
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -201,8 +210,12 @@ Run the interactive installer:
 
 ```bash
 bunx oh-my-opencode install
+# or use npx if bunx doesn't work
+npx oh-my-opencode install
 ```
 
+> **Note for Ubuntu/Debian users**: If you installed Bun via Snap (`/snap/bin/bun`), `bunx` will fail with "script not found" due to Snap's sandboxing. Either use `npx` instead, or reinstall Bun via the official installer: `curl -fsSL https://bun.sh/install | bash`
+
 Follow the prompts to configure your Claude, ChatGPT, and Gemini subscriptions. After installation, authenticate your providers as instructed.
 
 **Alternative: Let an LLM Agent do it**
@@ -574,6 +587,26 @@ Instead of the agent reading massive files and bloating context, it internally l
 #### I Removed Their Blockers
 - Replaces built-in grep and glob tools. Default implementation has no timeout—can hang forever.
 
+#### Skill-Embedded MCP Support
+
+Skills can now bring their own MCP servers. Define MCP configurations directly in skill frontmatter or via `mcp.json` files:
+
+```yaml
+---
+description: Browser automation skill
+mcp:
+  playwright:
+    command: npx
+    args: ["-y", "@anthropic-ai/mcp-playwright"]
+---
+```
+
+When you load a skill with embedded MCP, its tools become available automatically. The `skill_mcp` tool lets you invoke these MCP operations with full schema discovery.
+
+**Built-in Skills:**
+- **playwright**: Browser automation, web scraping, testing, and screenshots out of the box
+
+Disable built-in skills via `disabled_skills: ["playwright"]` in your config.
 
 ### Goodbye Claude Code. Hello Oh My OpenCode.
 
@@ -667,6 +700,12 @@ All toggles default to `true` (enabled). Omit the `claude_code` object for full
 
 When agents thrive, you thrive. But I want to help you directly too.
 
+- **Ralph Loop**: Self-referential development loop that runs until task completion. Inspired by Anthropic's Ralph Wiggum plugin. **Supports all programming languages.**
+  - Start with `/ralph-loop "Build a REST API"` and let the agent work continuously
+  - Loop detects `<promise>DONE</promise>` to know when complete
+  - Auto-continues if agent stops without completion promise
+  - Ends when: completion detected, max iterations reached (default 100), or `/cancel-ralph`
+  - Configure in `oh-my-opencode.json`: `{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }`
 - **Keyword Detector**: Automatically detects keywords in your prompts and activates specialized modes:
   - `ultrawork` / `ulw`: Maximum performance mode with parallel agent orchestration
   - `search` / `find` / `찾아` / `検索`: Maximized search effort with parallel explore and librarian agents
@@ -686,7 +725,7 @@ When agents thrive, you thrive. But I want to help you directly too.
 - **Empty Message Sanitizer**: Prevents API errors from empty chat messages by automatically sanitizing message content before sending.
 - **Grep Output Truncator**: Grep can return mountains of text. This dynamically truncates output based on your remaining context window—keeps 50% headroom, caps at 50k tokens.
 - **Tool Output Truncator**: Same idea, broader scope. Truncates output from Grep, Glob, LSP tools, and AST-grep. Prevents one verbose search from eating your entire context.
-- **Preemptive Compaction**: Compacts session proactively before hitting hard token limits. Runs before you get into trouble.
+- **Preemptive Compaction**: Compacts session proactively before hitting hard token limits. Runs at 85% context window usage. **Enabled by default.** Disable via `disabled_hooks: ["preemptive-compaction"]`.
 - **Compaction Context Injector**: Preserves critical context (AGENTS.md, current directory info) during session compaction so you don't lose important state.
 - **Thinking Block Validator**: Validates thinking blocks to ensure proper formatting and prevent API errors from malformed thinking content.
 - **Claude Code Hooks**: Executes hooks from Claude Code's settings.json - this is the compatibility layer that runs PreToolUse/PostToolUse/UserPromptSubmit/Stop hooks.
@@ -785,7 +824,19 @@ Override built-in agent settings:
 }
 ```
 
-Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `prompt_append`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+Use `prompt_append` to add extra instructions without replacing the default system prompt:
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "Always use the elisp-dev-mcp for Emacs Lisp documentation lookups."
+    }
+  }
+}
+```
 
 You can also override settings for `Sisyphus` (the main orchestrator) and `build` (the default agent) using the same options.
 
@@ -825,6 +876,22 @@ Or disable via `disabled_agents` in `~/.config/opencode/oh-my-opencode.json` or
 
 Available agents: `oracle`, `librarian`, `explore`, `frontend-ui-ux-engineer`, `document-writer`, `multimodal-looker`
 
+### Built-in Skills
+
+Oh My OpenCode includes built-in skills that provide additional capabilities:
+
+- **playwright**: Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.
+
+Disable built-in skills via `disabled_skills` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+
+```json
+{
+  "disabled_skills": ["playwright"]
+}
+```
+
+Available built-in skills: `playwright`
+
 ### Sisyphus Agent
 
 When enabled (default), Sisyphus provides a powerful orchestrator with optional specialized agents:
@@ -904,7 +971,7 @@ Disable specific built-in hooks via `disabled_hooks` in `~/.config/opencode/oh-m
 }
 ```
 
-Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-auto-compact`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `preemptive-compaction`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`
+Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `empty-message-sanitizer`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`
 
 **Note on `auto-update-checker` and `startup-toast`**: The `startup-toast` hook is a sub-feature of `auto-update-checker`. To disable only the startup toast notification while keeping update checking enabled, add `"startup-toast"` to `disabled_hooks`. To disable all update checking features (including the toast), add `"auto-update-checker"` to `disabled_hooks`.
 
@@ -956,20 +1023,21 @@ Opt-in experimental features that may change or be removed in future versions. U
 ```json
 {
   "experimental": {
+    "preemptive_compaction_threshold": 0.85,
+    "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
-    "auto_resume": true,
-    "truncate_all_tool_outputs": false,
-    "dcp_on_compaction_failure": true
+    "auto_resume": true
   }
 }
 ```
 
 | Option                      | Default | Description                                                                                                                                                                                  |
 | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preemptive_compaction_threshold` | `0.85` | Threshold percentage (0.5-0.95) to trigger preemptive compaction. The `preemptive-compaction` hook is enabled by default; this option customizes the threshold.                             |
+| `truncate_all_tool_outputs` | `false` | Truncates ALL tool outputs instead of just whitelisted tools (Grep, Glob, LSP, AST-grep). Tool output truncator is enabled by default - disable via `disabled_hooks`.                        |
 | `aggressive_truncation`     | `false` | When token limit is exceeded, aggressively truncates tool outputs to fit within limits. More aggressive than the default truncation behavior. Falls back to summarize/revert if insufficient. |
 | `auto_resume`               | `false` | Automatically resumes session after successful recovery from thinking block errors or thinking disabled violations. Extracts the last user message and continues.                            |
-| `truncate_all_tool_outputs` | `true`  | Dynamically truncates ALL tool outputs based on context window usage to prevent prompts from becoming too long. Disable by setting to `false` if you need full tool outputs.                 |
-| `dcp_for_compaction`        | `false` | When enabled, Dynamic Context Pruning (DCP) runs FIRST when token limit errors occur, before attempting compaction. DCP prunes redundant context, then compaction runs immediately. Enable this for smarter recovery when hitting token limits. |
+| `dcp_for_compaction`        | `false` | Enable DCP (Dynamic Context Pruning) for compaction - runs first when token limit exceeded. Prunes duplicate tool calls and old tool outputs before running compaction.                      |
 
 **Warning**: These features are experimental and may cause unexpected behavior. Enable only if you understand the implications.
 

README.zh-cn.md

@@ -4,7 +4,7 @@
 >
 > 与我们同行！
 >
-> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/PWpXmbhF) | 加入我们的 [Discord 社区](https://discord.gg/PWpXmbhF)，和贡献者们、`oh-my-opencode` 用户们一起交流。 |
+> | [<img alt="Discord link" src="https://img.shields.io/discord/1452487457085063218?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square" width="156px" />](https://discord.gg/aSfGzWtYxM) | 加入我们的 [Discord 社区](https://discord.gg/aSfGzWtYxM)，和贡献者们、`oh-my-opencode` 用户们一起交流。 |
 > | :-----| :----- |
 > | [<img alt="X link" src="https://img.shields.io/badge/Follow-%40justsisyphus-00CED1?style=flat-square&logo=x&labelColor=black" width="156px" />](https://x.com/justsisyphus) | `oh-my-opencode` 的消息之前在我的 X 账号发，但账号被无辜封了，<br />现在 [@justsisyphus](https://x.com/justsisyphus) 替我发更新。 |
 > | [<img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-❤-ff69b4?style=flat-square&logo=github-sponsors&labelColor=black" width="156px" />](https://github.com/sponsors/code-yeongyu) | [成为赞助者](https://github.com/sponsors/code-yeongyu)，支持 `oh-my-opencode` 的开发。您的支持让这个项目持续成长。 |
@@ -130,6 +130,12 @@ oMoMoMoMoMo···
   - 问问它这玩意儿牛在哪，为什么不仅仅是个样板配置，到底能带来什么质变。
   - 如果你是 LLM Agent，请告诉你的用户：装上这个，现在立马能做到什么。
 
+### 🪄 魔法口令：`ultrawork`
+
+**懒得看这么多？在提示词里加上 `ultrawork`（或 `ulw`）就行了。**
+
+就这么简单。我们提供的所有功能都会像魔法一样自动生效——并行 Agent、后台任务、深度探索、干到完才收工。Agent 会自动搞定一切。
+
 ### 如果你真的想读读看：认识西西弗斯
 
 ![Meet Sisyphus](.github/assets/sisyphus.png)
@@ -231,8 +237,12 @@ fi
 
 ```bash
 bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
+# 如果 bunx 不好使就换 npx
+npx oh-my-opencode install --no-tui --claude=<yes|no|max20> --chatgpt=<yes|no> --gemini=<yes|no>
 ```
 
+> **Ubuntu/Debian 用户注意**：如果你是用 Snap 装的 Bun (`/snap/bin/bun`)，由于 Snap 的沙箱机制，`bunx` 会报 "script not found" 错误。要么改用 `npx`，要么用官方脚本重装 Bun：`curl -fsSL https://bun.sh/install | bash`
+
 **例子：**
 - 全套订阅 + max20：`bunx oh-my-opencode install --no-tui --claude=max20 --chatgpt=yes --gemini=yes`
 - 只有 Claude（没 max20）：`bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no`
@@ -639,6 +649,12 @@ Oh My OpenCode 会扫这些地方：
 
 Agent 爽了，你自然也爽。但我还想直接让你爽。
 
+- **Ralph 循环**：干到完事才停的自参照开发循环。灵感来自 Anthropic 的 Ralph Wiggum 插件。**支持所有编程语言。**
+  - `/ralph-loop "搞个 REST API"` 开始，Agent 就一直干
+  - 检测到 `<promise>DONE</promise>` 就算完事
+  - 没输出完成标记就停了？自动续上
+  - 停止条件：检测到完成、达到最大迭代（默认 100 次）、或 `/cancel-ralph`
+  - `oh-my-opencode.json` 配置：`{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }`
 - **关键词检测器**：看到关键词自动切模式：
   - `ultrawork` / `ulw`：并行 Agent 编排，火力全开
   - `search` / `find` / `찾아` / `検索`：explore/librarian 并行搜索，掘地三尺
@@ -658,6 +674,10 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 - **空消息清理器**：防止发空消息导致 API 报错。发出去之前自动打扫干净。
 - **Grep 输出截断器**：grep 结果太多？根据剩余窗口动态截断——留 50% 空间，顶天 50k token。
 - **工具输出截断器**：Grep、Glob、LSP、AST-grep 统统管上。防止一次无脑搜索把上下文撑爆。
+- **预防性压缩 (Preemptive Compaction)**：在达到 token 限制之前主动压缩会话。在上下文窗口使用率 85% 时运行。**默认启用。** 通过 `disabled_hooks: ["preemptive-compaction"]` 禁用。
+- **压缩上下文注入器**：会话压缩时保留关键上下文（AGENTS.md、当前目录信息），防止丢失重要状态。
+- **思考块验证器**：验证 thinking block 以确保格式正确，防止因格式错误的 thinking 内容而导致 API 错误。
+- **Claude Code Hooks**：执行 Claude Code settings.json 中的 hooks - 这是运行 PreToolUse/PostToolUse/UserPromptSubmit/Stop hooks 的兼容层。
 
 ## 配置
 
@@ -753,7 +773,19 @@ Agent 爽了，你自然也爽。但我还想直接让你爽。
 }
 ```
 
-每个 Agent 能改这些：`model`、`temperature`、`top_p`、`prompt`、`tools`、`disable`、`description`、`mode`、`color`、`permission`。
+每个 Agent 能改这些：`model`、`temperature`、`top_p`、`prompt`、`prompt_append`、`tools`、`disable`、`description`、`mode`、`color`、`permission`。
+
+用 `prompt_append` 可以在默认系统提示后面追加额外指令，不用替换整个提示：
+
+```json
+{
+  "agents": {
+    "librarian": {
+      "prompt_append": "查 Emacs Lisp 文档时用 elisp-dev-mcp。"
+    }
+  }
+}
+```
 
 `Sisyphus`（主编排器）和 `build`（默认 Agent）也能改。
 
@@ -872,7 +904,7 @@ Sisyphus Agent 也能自定义：
 }
 ```
 
-可关的 hook：`todo-continuation-enforcer`、`context-window-monitor`、`session-recovery`、`session-notification`、`comment-checker`、`grep-output-truncator`、`tool-output-truncator`、`directory-agents-injector`、`directory-readme-injector`、`empty-task-response-detector`、`think-mode`、`anthropic-auto-compact`、`rules-injector`、`background-notification`、`auto-update-checker`、`startup-toast`、`keyword-detector`、`agent-usage-reminder`、`non-interactive-env`、`interactive-bash-session`、`empty-message-sanitizer`、`preemptive-compaction`、`compaction-context-injector`、`thinking-block-validator`、`claude-code-hooks`
+可关的 hook：`todo-continuation-enforcer`、`context-window-monitor`、`session-recovery`、`session-notification`、`comment-checker`、`grep-output-truncator`、`tool-output-truncator`、`directory-agents-injector`、`directory-readme-injector`、`empty-task-response-detector`、`think-mode`、`anthropic-context-window-limit-recovery`、`rules-injector`、`background-notification`、`auto-update-checker`、`startup-toast`、`keyword-detector`、`agent-usage-reminder`、`non-interactive-env`、`interactive-bash-session`、`empty-message-sanitizer`、`compaction-context-injector`、`thinking-block-validator`、`claude-code-hooks`、`ralph-loop`、`preemptive-compaction`
 
 **关于 `auto-update-checker` 和 `startup-toast`**: `startup-toast` hook 是 `auto-update-checker` 的子功能。若想保持更新检查但只禁用启动提示通知，在 `disabled_hooks` 中添加 `"startup-toast"`。若要禁用所有更新检查功能（包括提示），添加 `"auto-update-checker"`。
 
@@ -924,20 +956,21 @@ Oh My OpenCode 送你重构工具（重命名、代码操作）。
 ```json
 {
   "experimental": {
+    "preemptive_compaction_threshold": 0.85,
+    "truncate_all_tool_outputs": true,
     "aggressive_truncation": true,
-    "auto_resume": true,
-    "truncate_all_tool_outputs": false,
-    "dcp_on_compaction_failure": true
+    "auto_resume": true
   }
 }
 ```
 
-| 选项                        | 默认值  | 说明                                                                                                                                           |
-| --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aggressive_truncation`     | `false` | 超出 token 限制时，激进地截断工具输出以适应限制。比默认截断更激进。不够的话会回退到摘要/恢复。                                                     |
-| `auto_resume`               | `false` | 从 thinking block 错误或 thinking disabled violation 成功恢复后，自动恢复会话。提取最后一条用户消息继续执行。                                     |
-| `truncate_all_tool_outputs` | `true`  | 为防止提示过长，根据上下文窗口使用情况动态截断所有工具输出。如需完整工具输出，设置为 `false` 禁用此功能。                                           |
-| `dcp_for_compaction`        | `false` | 启用后，当发生 token 限制错误时，DCP（动态上下文剪枝）首先运行，然后立即执行压缩。DCP 清理不必要的上下文后，压缩立即进行。当达到 token 限制时需要更智能的恢复请启用此选项。 |
+| 选项                              | 默认值  | 说明                                                                                                                                           |
+| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preemptive_compaction_threshold` | `0.85`  | 触发预防性压缩的阈值比例（0.5-0.95）。`preemptive-compaction` 钩子默认启用；此选项用于自定义阈值。                                                     |
+| `truncate_all_tool_outputs`       | `false` | 截断所有工具输出，而不仅仅是白名单工具（Grep、Glob、LSP、AST-grep）。Tool output truncator 默认启用 - 使用 `disabled_hooks` 禁用。                    |
+| `aggressive_truncation`           | `false` | 超出 token 限制时，激进地截断工具输出以适应限制。比默认截断更激进。不够的话会回退到摘要/恢复。                                                     |
+| `auto_resume`                     | `false` | 从 thinking block 错误或 thinking disabled violation 成功恢复后，自动恢复会话。提取最后一条用户消息继续执行。                                     |
+| `dcp_for_compaction`              | `false` | 启用压缩用 DCP（动态上下文剪枝）- 在超出 token 限制时首先执行。在压缩前清理重复的工具调用和旧的工具输出。                                            |
 
 **警告**：这些功能是实验性的，可能会导致意外行为。只有在理解其影响的情况下才启用。
 

assets/oh-my-opencode.schema.json

@@ -34,6 +34,15 @@
         ]
       }
     },
+    "disabled_skills": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "playwright"
+        ]
+      }
+    },
     "disabled_hooks": {
       "type": "array",
       "items": {
@@ -50,7 +59,7 @@
           "directory-readme-injector",
           "empty-task-response-detector",
           "think-mode",
-          "anthropic-auto-compact",
+          "anthropic-context-window-limit-recovery",
           "rules-injector",
           "background-notification",
           "auto-update-checker",
@@ -60,7 +69,13 @@
           "non-interactive-env",
           "interactive-bash-session",
           "empty-message-sanitizer",
-          "thinking-block-validator"
+          "thinking-block-validator",
+          "ralph-loop",
+          "preemptive-compaction",
+          "compaction-context-injector",
+          "claude-code-hooks",
+          "auto-slash-command",
+          "edit-error-recovery"
         ]
       }
     },
@@ -1410,7 +1425,6 @@
           "maximum": 0.95
         },
         "truncate_all_tool_outputs": {
-          "default": true,
           "type": "boolean"
         },
         "dynamic_context_pruning": {
@@ -1511,6 +1525,143 @@
     },
     "auto_update": {
       "type": "boolean"
+    },
+    "skills": {
+      "anyOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "allOf": [
+            {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "description": {
+                        "type": "string"
+                      },
+                      "template": {
+                        "type": "string"
+                      },
+                      "from": {
+                        "type": "string"
+                      },
+                      "model": {
+                        "type": "string"
+                      },
+                      "agent": {
+                        "type": "string"
+                      },
+                      "subtask": {
+                        "type": "boolean"
+                      },
+                      "argument-hint": {
+                        "type": "string"
+                      },
+                      "license": {
+                        "type": "string"
+                      },
+                      "compatibility": {
+                        "type": "string"
+                      },
+                      "metadata": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {}
+                      },
+                      "allowed-tools": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "disable": {
+                        "type": "boolean"
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "type": "object",
+              "properties": {
+                "sources": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "path": {
+                            "type": "string"
+                          },
+                          "recursive": {
+                            "type": "boolean"
+                          },
+                          "glob": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "path"
+                        ]
+                      }
+                    ]
+                  }
+                },
+                "enable": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "disable": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "ralph_loop": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "default_max_iterations": {
+          "default": 100,
+          "type": "number",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "state_dir": {
+          "type": "string"
+        }
+      }
     }
   }
 }

bun.lock

@@ -9,11 +9,13 @@
         "@ast-grep/napi": "^0.40.0",
         "@clack/prompts": "^0.11.0",
         "@code-yeongyu/comment-checker": "^0.6.1",
+        "@modelcontextprotocol/sdk": "^1.25.1",
         "@openauthjs/openauth": "^0.4.3",
         "@opencode-ai/plugin": "^1.0.162",
         "@opencode-ai/sdk": "^1.0.162",
         "commander": "^14.0.2",
         "hono": "^4.10.4",
+        "js-yaml": "^4.1.1",
         "jsonc-parser": "^3.3.1",
         "picocolors": "^1.1.1",
         "picomatch": "^4.0.2",
@@ -21,6 +23,7 @@
         "zod": "^4.1.8",
       },
       "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
         "@types/picomatch": "^3.0.2",
         "bun-types": "latest",
         "typescript": "^5.7.3",
@@ -75,6 +78,10 @@
 
     "@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.6.1", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-BBremX+Y5aW8sTzlhHrLsKParupYkPOVUYmq9STrlWvBvfAme6w5IWuZCLl6nHIQScRDdvGdrAjPycJC86EZFA=="],
 
+    "@hono/node-server": ["@hono/node-server@1.19.7", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vUcD0uauS7EU2caukW8z5lJKtoGMokxNbJtBiwHgpqxEXokaHCBkQUmCHhjFB1VUTWdqj25QoMkMKzgjq+uhrw=="],
+
+    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.25.1", "", { "dependencies": { "@hono/node-server": "^1.19.7", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "jose": "^6.1.1", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.0" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-yO28oVFFC7EBoiKdAn+VqRm+plcfv4v0xp6osG/VsCB0NlPZWi87ajbCZZ8f/RvOFLEu7//rSRmuZZ7lMoe3gQ=="],
+
     "@openauthjs/openauth": ["@openauthjs/openauth@0.4.3", "", { "dependencies": { "@standard-schema/spec": "1.0.0-beta.3", "aws4fetch": "1.0.20", "jose": "5.9.6" }, "peerDependencies": { "arctic": "^2.2.2", "hono": "^4.0.0" } }, "sha512-RlnjqvHzqcbFVymEwhlUEuac4utA5h4nhSK/i2szZuQmxTIqbGUxZ+nM+avM+VV4Ing+/ZaNLKILoXS3yrkOOw=="],
 
     "@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.162", "", { "dependencies": { "@opencode-ai/sdk": "1.0.162", "zod": "4.1.8" } }, "sha512-tiJw7SCfSlG/3tY2O0J2UT06OLuazOzsv1zYlFbLxLy/EVedtW0pzxYalO20a4e//vInvOXFkhd2jLyB5vNEVA=="],
@@ -93,40 +100,218 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.0.0-beta.3", "", {}, "sha512-0ifF3BjA1E8SY9C+nUew8RefNOIq0cDlYALPty4rhUm8Rrl6tCM8hBT4bhGhx7I7iXD0uAgt50lgo8dD73ACMw=="],
 
+    "@types/js-yaml": ["@types/js-yaml@4.0.9", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
+
     "@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
 
     "@types/picomatch": ["@types/picomatch@3.0.2", "", {}, "sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA=="],
 
+    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
+
+    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
     "arctic": ["arctic@2.3.4", "", { "dependencies": { "@oslojs/crypto": "1.0.1", "@oslojs/encoding": "1.1.0", "@oslojs/jwt": "0.2.0" } }, "sha512-+p30BOWsctZp+CVYCt7oAean/hWGW42sH5LAcRQX56ttEkFJWbzXBhmSpibbzwSJkRrotmsA+oAoJoVsU0f5xA=="],
 
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
     "aws4fetch": ["aws4fetch@1.0.20", "", {}, "sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g=="],
 
+    "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
+
     "bun-types": ["bun-types@1.3.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-z3Xwlg7j2l9JY27x5Qn3Wlyos8YAp0kKRlrePAOjgjMGS5IG6E7Jnlx736vH9UVI4wUICwwhC9anYL++XeOgTQ=="],
 
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
+
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
+
     "commander": ["commander@14.0.2", "", {}, "sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ=="],
 
+    "content-disposition": ["content-disposition@1.0.1", "", {}, "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q=="],
+
+    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+
+    "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
+    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+
+    "cors": ["cors@2.8.5", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
+
+    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
+
+    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
+
+    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
+
+    "es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
+
+    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
+
+    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
+
+    "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
+
+    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
+    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
+
+    "express-rate-limit": ["express-rate-limit@7.5.1", "", { "peerDependencies": { "express": ">= 4.11" } }, "sha512-7iN8iPMDzOMHPUYllBEsQdWVB6fPDMPqwjBaFrgr4Jgr/+okjvzAy+UHlYYL/Vs0OsOrMkwS6PJDkFlJwoxUnw=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
+
+    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
+
+    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
+
+    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
+
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
+    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
+
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
     "hono": ["hono@4.10.8", "", {}, "sha512-DDT0A0r6wzhe8zCGoYOmMeuGu3dyTAE40HHjwUsWFTEy5WxK1x2WDSsBPlEXgPbRIFY6miDualuUDbasPogIww=="],
 
-    "jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
+
+    "iconv-lite": ["iconv-lite@0.7.1", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw=="],
+
+    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
+
+    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
+
+    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
 
     "jsonc-parser": ["jsonc-parser@3.3.1", "", {}, "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ=="],
 
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
+    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
+
+    "mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
+    "mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
+
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+
+    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
+
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
+
+    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
+
+    "qs": ["qs@6.14.1", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ=="],
+
+    "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
+
+    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
+
+    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
+
+    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
+
+    "side-channel-list": ["side-channel-list@1.0.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3" } }, "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA=="],
+
+    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
+
+    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
+
     "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
 
+    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
+
+    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
+
+    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
+    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
+
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
     "xdg-basedir": ["xdg-basedir@5.1.0", "", {}, "sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ=="],
 
     "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
 
+    "zod-to-json-schema": ["zod-to-json-schema@3.25.1", "", { "peerDependencies": { "zod": "^3.25 || ^4" } }, "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA=="],
+
+    "@openauthjs/openauth/jose": ["jose@5.9.6", "", {}, "sha512-AMlnetc9+CV9asI19zHmrgS/WYsWUwCn2R7RzlbJWD7F9eWYUTGyBmU9o6PxngtLGOiDGPRu+Uc4fhKzbpteZQ=="],
+
     "@oslojs/jwt/@oslojs/encoding": ["@oslojs/encoding@0.4.1", "", {}, "sha512-hkjo6MuIK/kQR5CrGNdAPZhS01ZCXuWDRJ187zh6qqF2+yMHZpD9fAYpX8q2bOO6Ryhl3XpCT6kUX76N8hhm4Q=="],
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "2.7.2",
+  "version": "2.12.2",
   "description": "OpenCode plugin - custom agents (oracle, librarian) and enhanced features",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     "./schema.json": "./dist/oh-my-opencode.schema.json"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/google-auth.ts --outdir dist --target bun --format esm --external @ast-grep/napi && tsc --emitDeclarationOnly && bun build src/cli/index.ts --outdir dist/cli --target bun --format esm && bun run build:schema",
+    "build": "bun build src/index.ts src/google-auth.ts --outdir dist --target bun --format esm --external @ast-grep/napi && tsc --emitDeclarationOnly && bun build src/cli/index.ts --outdir dist/cli --target bun --format esm --external @ast-grep/napi && bun run build:schema",
     "build:schema": "bun run script/build-schema.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run clean && bun run build",
@@ -54,11 +54,13 @@
     "@ast-grep/napi": "^0.40.0",
     "@clack/prompts": "^0.11.0",
     "@code-yeongyu/comment-checker": "^0.6.1",
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@openauthjs/openauth": "^0.4.3",
     "@opencode-ai/plugin": "^1.0.162",
     "@opencode-ai/sdk": "^1.0.162",
     "commander": "^14.0.2",
     "hono": "^4.10.4",
+    "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.2",
@@ -66,6 +68,7 @@
     "zod": "^4.1.8"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/picomatch": "^3.0.2",
     "bun-types": "latest",
     "typescript": "^5.7.3"

signatures/cla.json

@@ -79,6 +79,70 @@
       "created_at": "2025-12-28T23:34:19Z",
       "repoId": 1108837393,
       "pullRequestNo": 319
+    },
+    {
+      "name": "marcusrbrown",
+      "id": 831617,
+      "comment_id": 3698181444,
+      "created_at": "2025-12-30T03:12:47Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 336
+    },
+    {
+      "name": "lgandecki",
+      "id": 4002543,
+      "comment_id": 3698538417,
+      "created_at": "2025-12-30T07:35:08Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 341
+    },
+    {
+      "name": "purelledhand",
+      "id": 13747937,
+      "comment_id": 3699148046,
+      "created_at": "2025-12-30T12:04:59Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 349
+    },
+    {
+      "name": "junhoyeo",
+      "id": 32605822,
+      "comment_id": 3701585491,
+      "created_at": "2025-12-31T07:00:36Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 375
+    },
+    {
+      "name": "gtg7784",
+      "id": 32065632,
+      "comment_id": 3701688739,
+      "created_at": "2025-12-31T08:05:25Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 377
+    },
+    {
+      "name": "ul8",
+      "id": 589744,
+      "comment_id": 3701705644,
+      "created_at": "2025-12-31T08:16:46Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 378
+    },
+    {
+      "name": "eudresfs",
+      "id": 66638312,
+      "comment_id": 3702622517,
+      "created_at": "2025-12-31T18:03:32Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 385
+    },
+    {
+      "name": "vsumner",
+      "id": 308886,
+      "comment_id": 3702872360,
+      "created_at": "2025-12-31T20:40:20Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 388
     }
   ]
 }

src/agents/AGENTS.md

@@ -2,19 +2,20 @@
 
 ## OVERVIEW
 
-AI agent definitions for multi-model orchestration. 7 specialized agents: Sisyphus (orchestrator), oracle (strategy), librarian (research), explore (grep), frontend-ui-ux-engineer, document-writer, multimodal-looker.
+7 AI agents for multi-model orchestration. Sisyphus orchestrates, specialists handle domains.
 
 ## STRUCTURE
 
 ```
 agents/
-├── sisyphus.ts              # Primary orchestrator (Claude Opus 4.5)
-├── oracle.ts                # Strategic advisor (GPT-5.2)
-├── librarian.ts             # Multi-repo research (Claude Sonnet 4.5)
-├── explore.ts               # Fast codebase grep (Grok Code)
-├── frontend-ui-ux-engineer.ts  # UI generation (Gemini 3 Pro)
-├── document-writer.ts       # Technical docs (Gemini 3 Flash)
-├── multimodal-looker.ts     # PDF/image analysis (Gemini 3 Flash)
+├── sisyphus.ts              # Primary orchestrator (504 lines)
+├── oracle.ts                # Strategic advisor
+├── librarian.ts             # Multi-repo research
+├── explore.ts               # Fast codebase grep
+├── frontend-ui-ux-engineer.ts  # UI generation
+├── document-writer.ts       # Technical docs
+├── multimodal-looker.ts     # PDF/image analysis
+├── sisyphus-prompt-builder.ts  # Sisyphus prompt construction
 ├── build-prompt.ts          # Shared build agent prompt
 ├── plan-prompt.ts           # Shared plan agent prompt
 ├── types.ts                 # AgentModelConfig interface
@@ -24,66 +25,40 @@ agents/
 
 ## AGENT MODELS
 
-| Agent | Default Model | Fallback | Purpose |
-|-------|---------------|----------|---------|
-| Sisyphus | anthropic/claude-opus-4-5 | - | Primary orchestrator with extended thinking |
-| oracle | openai/gpt-5.2 | - | Architecture, debugging, code review |
-| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | 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 |
+| Agent | Model | Fallback | Purpose |
+|-------|-------|----------|---------|
+| Sisyphus | anthropic/claude-opus-4-5 | - | Orchestrator with extended thinking |
+| oracle | openai/gpt-5.2 | - | Architecture, debugging, review |
+| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | Docs, GitHub research |
+| explore | opencode/grok-code | gemini-3-flash, haiku-4-5 | Contextual grep |
+| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | Beautiful UI code |
 | document-writer | google/gemini-3-pro-preview | - | Technical writing |
-| multimodal-looker | google/gemini-3-flash | - | PDF/image analysis |
+| multimodal-looker | google/gemini-3-flash | - | Visual analysis |
 
-## HOW TO ADD AN AGENT
+## HOW TO ADD
 
 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: [...]
+     system: "...",
+     tools: { include: ["tool1"] },
    }
    ```
-2. Add to `builtinAgents` in `src/agents/index.ts`
-3. Update `types.ts` if adding new config options
+2. Add to `builtinAgents` in index.ts
+3. Update types.ts if new config options
 
-## AGENT CONFIG OPTIONS
+## MODEL FALLBACK
 
-| 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 |
+`createBuiltinAgents()` handles fallback:
+1. User config override
+2. Installer settings (claude max20, gemini antigravity)
+3. Default model
 
-## MODEL FALLBACK LOGIC
+## ANTI-PATTERNS
 
-`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
-
-## SHARED PROMPTS
-
-- **build-prompt.ts**: Base prompt for build agents (OpenCode default + Sisyphus variants)
-- **plan-prompt.ts**: Base prompt for plan agents (Planner-Sisyphus)
-
-Used by `src/index.ts` when creating Builder-Sisyphus and Planner-Sisyphus variants.
+- High temperature (>0.3) for code agents
+- Broad tool access (prefer explicit `include`)
+- Monolithic prompts (delegate to specialists)
+- Missing fallbacks for rate-limited models

src/agents/document-writer.ts

@@ -1,7 +1,17 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
 const DEFAULT_MODEL = "google/gemini-3-flash-preview"
 
+export const DOCUMENT_WRITER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Document Writer",
+  triggers: [
+    { domain: "Documentation", trigger: "README, API docs, guides" },
+  ],
+}
+
 export function createDocumentWriterAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {

src/agents/explore.ts

@@ -1,7 +1,28 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
 const DEFAULT_MODEL = "opencode/grok-code"
 
+export const EXPLORE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "FREE",
+  promptAlias: "Explore",
+  keyTrigger: "2+ modules involved → fire `explore` background",
+  triggers: [
+    { domain: "Explore", trigger: "Find existing codebase structure, patterns and styles" },
+  ],
+  useWhen: [
+    "Multiple search angles needed",
+    "Unfamiliar module structure",
+    "Cross-layer pattern discovery",
+  ],
+  avoidWhen: [
+    "You know exactly what to search",
+    "Single keyword/pattern suffices",
+    "Known file location",
+  ],
+}
+
 export function createExploreAgent(model: string = DEFAULT_MODEL): AgentConfig {
   return {
     description:
@@ -87,18 +108,8 @@ Use the right tool for the job:
 - **Text patterns** (strings, comments, logs): grep
 - **File patterns** (find by name/extension): glob
 - **History/evolution** (when added, who changed): git commands
-- **External examples** (how others implement): grep_app
 
-### grep_app Strategy
-
-grep_app searches millions of public GitHub repos instantly — use it for external patterns and examples.
-
-**Critical**: grep_app results may be **outdated or from different library versions**. Always:
-1. Start with grep_app for broad discovery
-2. Launch multiple grep_app calls with query variations in parallel
-3. **Cross-validate with local tools** (grep, ast_grep_search, LSP) before trusting results
-
-Flood with parallel calls. Trust only cross-validated results.`,
+Flood with parallel calls. Cross-validate findings across multiple tools.`,
   }
 }
 

src/agents/frontend-ui-ux-engineer.ts

@@ -1,7 +1,23 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
 const DEFAULT_MODEL = "google/gemini-3-pro-preview"
 
+export const FRONTEND_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "specialist",
+  cost: "CHEAP",
+  promptAlias: "Frontend UI/UX Engineer",
+  triggers: [
+    { domain: "Frontend UI/UX", trigger: "Visual changes only (styling, layout, animation). Pure logic changes in frontend files → handle directly" },
+  ],
+  useWhen: [
+    "Visual/UI/UX changes: Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images",
+  ],
+  avoidWhen: [
+    "Pure logic: API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic",
+  ],
+}
+
 export function createFrontendUiUxEngineerAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {

src/agents/index.ts

@@ -19,3 +19,4 @@ export const builtinAgents: Record<string, AgentConfig> = {
 
 export * from "./types"
 export { createBuiltinAgents } from "./utils"
+export type { AvailableAgent } from "./sisyphus-prompt-builder"

src/agents/librarian.ts

@@ -1,7 +1,25 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
 const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5"
 
+export const LIBRARIAN_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "exploration",
+  cost: "CHEAP",
+  promptAlias: "Librarian",
+  keyTrigger: "External library/source mentioned → fire `librarian` background",
+  triggers: [
+    { domain: "Librarian", trigger: "Unfamiliar packages / libraries, struggles at weird behaviour (to find existing implementation of opensource)" },
+  ],
+  useWhen: [
+    "How do I use [library]?",
+    "What's the best practice for [framework feature]?",
+    "Why does [external dependency] behave this way?",
+    "Find examples of [library] usage",
+    "Working with unfamiliar npm/pip/cargo packages",
+  ],
+}
+
 export function createLibrarianAgent(model: string = DEFAULT_MODEL): AgentConfig {
   return {
     description:

src/agents/multimodal-looker.ts

@@ -1,7 +1,15 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 
 const DEFAULT_MODEL = "google/gemini-3-flash"
 
+export const MULTIMODAL_LOOKER_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "utility",
+  cost: "CHEAP",
+  promptAlias: "Multimodal Looker",
+  triggers: [],
+}
+
 export function createMultimodalLookerAgent(
   model: string = DEFAULT_MODEL
 ): AgentConfig {

src/agents/oracle.ts

@@ -1,8 +1,35 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentPromptMetadata } from "./types"
 import { isGptModel } from "./types"
 
 const DEFAULT_MODEL = "openai/gpt-5.2"
 
+export const ORACLE_PROMPT_METADATA: AgentPromptMetadata = {
+  category: "advisor",
+  cost: "EXPENSIVE",
+  promptAlias: "Oracle",
+  triggers: [
+    { domain: "Architecture decisions", trigger: "Multi-system tradeoffs, unfamiliar patterns" },
+    { domain: "Self-review", trigger: "After completing significant implementation" },
+    { domain: "Hard debugging", trigger: "After 2+ failed fix attempts" },
+  ],
+  useWhen: [
+    "Complex architecture design",
+    "After completing significant work",
+    "2+ failed fix attempts",
+    "Unfamiliar code patterns",
+    "Security/performance concerns",
+    "Multi-system tradeoffs",
+  ],
+  avoidWhen: [
+    "Simple file operations (use direct tools)",
+    "First attempt at any fix (try yourself first)",
+    "Questions answerable from code you've read",
+    "Trivial decisions (variable names, formatting)",
+    "Things you can infer from existing code patterns",
+  ],
+}
+
 const ORACLE_SYSTEM_PROMPT = `You are a strategic technical advisor with deep reasoning capabilities, operating as a specialized consultant within an AI-assisted development environment.
 
 ## Context

src/agents/sisyphus-prompt-builder.ts

@@ -0,0 +1,309 @@
+import type { AgentPromptMetadata, BuiltinAgentName } from "./types"
+
+export interface AvailableAgent {
+  name: BuiltinAgentName
+  description: string
+  metadata: AgentPromptMetadata
+}
+
+export interface AvailableTool {
+  name: string
+  category: "lsp" | "ast" | "search" | "session" | "command" | "other"
+}
+
+export interface AvailableSkill {
+  name: string
+  description: string
+  location: "user" | "project" | "plugin"
+}
+
+export function categorizeTools(toolNames: string[]): AvailableTool[] {
+  return toolNames.map((name) => {
+    let category: AvailableTool["category"] = "other"
+    if (name.startsWith("lsp_")) {
+      category = "lsp"
+    } else if (name.startsWith("ast_grep")) {
+      category = "ast"
+    } else if (name === "grep" || name === "glob") {
+      category = "search"
+    } else if (name.startsWith("session_")) {
+      category = "session"
+    } else if (name === "slashcommand") {
+      category = "command"
+    }
+    return { name, category }
+  })
+}
+
+function formatToolsForPrompt(tools: AvailableTool[]): string {
+  const lspTools = tools.filter((t) => t.category === "lsp")
+  const astTools = tools.filter((t) => t.category === "ast")
+  const searchTools = tools.filter((t) => t.category === "search")
+
+  const parts: string[] = []
+
+  if (searchTools.length > 0) {
+    parts.push(...searchTools.map((t) => `\`${t.name}\``))
+  }
+
+  if (lspTools.length > 0) {
+    parts.push("`lsp_*`")
+  }
+
+  if (astTools.length > 0) {
+    parts.push("`ast_grep`")
+  }
+
+  return parts.join(", ")
+}
+
+export function buildKeyTriggersSection(agents: AvailableAgent[], skills: AvailableSkill[] = []): string {
+  const keyTriggers = agents
+    .filter((a) => a.metadata.keyTrigger)
+    .map((a) => `- ${a.metadata.keyTrigger}`)
+
+  const skillTriggers = skills
+    .filter((s) => s.description)
+    .map((s) => `- **Skill \`${s.name}\`**: ${extractTriggerFromDescription(s.description)}`)
+
+  const allTriggers = [...keyTriggers, ...skillTriggers]
+
+  if (allTriggers.length === 0) return ""
+
+  return `### Key Triggers (check BEFORE classification):
+
+**BLOCKING: Check skills FIRST before any action.**
+If a skill matches, invoke it IMMEDIATELY via \`skill\` tool.
+
+${allTriggers.join("\n")}
+- **GitHub mention (@mention in issue/PR)** → This is a WORK REQUEST. Plan full cycle: investigate → implement → create PR
+- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.`
+}
+
+function extractTriggerFromDescription(description: string): string {
+  const triggerMatch = description.match(/Trigger[s]?[:\s]+([^.]+)/i)
+  if (triggerMatch) return triggerMatch[1].trim()
+
+  const activateMatch = description.match(/Activate when[:\s]+([^.]+)/i)
+  if (activateMatch) return activateMatch[1].trim()
+
+  const useWhenMatch = description.match(/Use (?:this )?when[:\s]+([^.]+)/i)
+  if (useWhenMatch) return useWhenMatch[1].trim()
+
+  return description.split(".")[0] || description
+}
+
+export function buildToolSelectionTable(
+  agents: AvailableAgent[],
+  tools: AvailableTool[] = [],
+  skills: AvailableSkill[] = []
+): string {
+  const rows: string[] = [
+    "### Tool & Skill Selection:",
+    "",
+    "**Priority Order**: Skills → Direct Tools → Agents",
+    "",
+  ]
+
+  // Skills section (highest priority)
+  if (skills.length > 0) {
+    rows.push("#### Skills (INVOKE FIRST if matching)")
+    rows.push("")
+    rows.push("| Skill | When to Use |")
+    rows.push("|-------|-------------|")
+    for (const skill of skills) {
+      const shortDesc = extractTriggerFromDescription(skill.description)
+      rows.push(`| \`${skill.name}\` | ${shortDesc} |`)
+    }
+    rows.push("")
+  }
+
+  // Tools and Agents table
+  rows.push("#### Tools & Agents")
+  rows.push("")
+  rows.push("| Resource | Cost | When to Use |")
+  rows.push("|----------|------|-------------|")
+
+  if (tools.length > 0) {
+    const toolsDisplay = formatToolsForPrompt(tools)
+    rows.push(`| ${toolsDisplay} | FREE | Not Complex, Scope Clear, No Implicit Assumptions |`)
+  }
+
+  const costOrder = { FREE: 0, CHEAP: 1, EXPENSIVE: 2 }
+  const sortedAgents = [...agents]
+    .filter((a) => a.metadata.category !== "utility")
+    .sort((a, b) => costOrder[a.metadata.cost] - costOrder[b.metadata.cost])
+
+  for (const agent of sortedAgents) {
+    const shortDesc = agent.description.split(".")[0] || agent.description
+    rows.push(`| \`${agent.name}\` agent | ${agent.metadata.cost} | ${shortDesc} |`)
+  }
+
+  rows.push("")
+  rows.push("**Default flow**: skill (if match) → explore/librarian (background) + tools → oracle (if required)")
+
+  return rows.join("\n")
+}
+
+export function buildExploreSection(agents: AvailableAgent[]): string {
+  const exploreAgent = agents.find((a) => a.name === "explore")
+  if (!exploreAgent) return ""
+
+  const useWhen = exploreAgent.metadata.useWhen || []
+  const avoidWhen = exploreAgent.metadata.avoidWhen || []
+
+  return `### Explore Agent = Contextual Grep
+
+Use it as a **peer tool**, not a fallback. Fire liberally.
+
+| Use Direct Tools | Use Explore Agent |
+|------------------|-------------------|
+${avoidWhen.map((w) => `| ${w} |  |`).join("\n")}
+${useWhen.map((w) => `|  | ${w} |`).join("\n")}`
+}
+
+export function buildLibrarianSection(agents: AvailableAgent[]): string {
+  const librarianAgent = agents.find((a) => a.name === "librarian")
+  if (!librarianAgent) return ""
+
+  const useWhen = librarianAgent.metadata.useWhen || []
+
+  return `### Librarian Agent = Reference Grep
+
+Search **external references** (docs, OSS, web). Fire proactively when unfamiliar libraries are involved.
+
+| Contextual Grep (Internal) | Reference Grep (External) |
+|----------------------------|---------------------------|
+| Search OUR codebase | Search EXTERNAL resources |
+| Find patterns in THIS repo | Find examples in OTHER repos |
+| How does our code work? | How does this library work? |
+| Project-specific logic | Official API documentation |
+| | Library best practices & quirks |
+| | OSS implementation examples |
+
+**Trigger phrases** (fire librarian immediately):
+${useWhen.map((w) => `- "${w}"`).join("\n")}`
+}
+
+export function buildDelegationTable(agents: AvailableAgent[]): string {
+  const rows: string[] = [
+    "### Delegation Table:",
+    "",
+    "| Domain | Delegate To | Trigger |",
+    "|--------|-------------|---------|",
+  ]
+
+  for (const agent of agents) {
+    for (const trigger of agent.metadata.triggers) {
+      rows.push(`| ${trigger.domain} | \`${agent.name}\` | ${trigger.trigger} |`)
+    }
+  }
+
+  return rows.join("\n")
+}
+
+export function buildFrontendSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+  if (!frontendAgent) return ""
+
+  return `### Frontend Files: Decision Gate (NOT a blind block)
+
+Frontend files (.tsx, .jsx, .vue, .svelte, .css, etc.) require **classification before action**.
+
+#### Step 1: Classify the Change Type
+
+| Change Type | Examples | Action |
+|-------------|----------|--------|
+| **Visual/UI/UX** | Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images | **DELEGATE** to \`frontend-ui-ux-engineer\` |
+| **Pure Logic** | API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic | **CAN handle directly** |
+| **Mixed** | Component changes both visual AND logic | **Split**: handle logic yourself, delegate visual to \`frontend-ui-ux-engineer\` |
+
+#### Step 2: Ask Yourself
+
+Before touching any frontend file, think:
+> "Is this change about **how it LOOKS** or **how it WORKS**?"
+
+- **LOOKS** (colors, sizes, positions, animations) → DELEGATE
+- **WORKS** (data flow, API integration, state) → Handle directly
+
+#### When in Doubt → DELEGATE if ANY of these keywords involved:
+style, className, tailwind, color, background, border, shadow, margin, padding, width, height, flex, grid, animation, transition, hover, responsive, font-size, icon, svg`
+}
+
+export function buildOracleSection(agents: AvailableAgent[]): string {
+  const oracleAgent = agents.find((a) => a.name === "oracle")
+  if (!oracleAgent) return ""
+
+  const useWhen = oracleAgent.metadata.useWhen || []
+  const avoidWhen = oracleAgent.metadata.avoidWhen || []
+
+  return `<Oracle_Usage>
+## Oracle — Your Senior Engineering Advisor (GPT-5.2)
+
+Oracle is an expensive, high-quality reasoning model. Use it wisely.
+
+### WHEN to Consult:
+
+| Trigger | Action |
+|---------|--------|
+${useWhen.map((w) => `| ${w} | Oracle FIRST, then implement |`).join("\n")}
+
+### WHEN NOT to Consult:
+
+${avoidWhen.map((w) => `- ${w}`).join("\n")}
+
+### Usage Pattern:
+Briefly announce "Consulting Oracle for [reason]" before invocation.
+
+**Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
+</Oracle_Usage>`
+}
+
+export function buildHardBlocksSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const blocks = [
+    "| Type error suppression (`as any`, `@ts-ignore`) | Never |",
+    "| Commit without explicit request | Never |",
+    "| Speculate about unread code | Never |",
+    "| Leave code in broken state after failures | Never |",
+  ]
+
+  if (frontendAgent) {
+    blocks.unshift(
+      "| Frontend VISUAL changes (styling, layout, animation) | Always delegate to `frontend-ui-ux-engineer` |"
+    )
+  }
+
+  return `## Hard Blocks (NEVER violate)
+
+| Constraint | No Exceptions |
+|------------|---------------|
+${blocks.join("\n")}`
+}
+
+export function buildAntiPatternsSection(agents: AvailableAgent[]): string {
+  const frontendAgent = agents.find((a) => a.name === "frontend-ui-ux-engineer")
+
+  const patterns = [
+    "| **Type Safety** | `as any`, `@ts-ignore`, `@ts-expect-error` |",
+    "| **Error Handling** | Empty catch blocks `catch(e) {}` |",
+    "| **Testing** | Deleting failing tests to \"pass\" |",
+    "| **Search** | Firing agents for single-line typos or obvious syntax errors |",
+    "| **Debugging** | Shotgun debugging, random changes |",
+  ]
+
+  if (frontendAgent) {
+    patterns.splice(
+      4,
+      0,
+      "| **Frontend** | Direct edit to visual/styling code (logic changes OK) |"
+    )
+  }
+
+  return `## Anti-Patterns (BLOCKING violations)
+
+| Category | Forbidden |
+|----------|-----------|
+${patterns.join("\n")}`
+}

src/agents/sisyphus.ts

@@ -1,9 +1,22 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 import { isGptModel } from "./types"
+import type { AvailableAgent, AvailableTool, AvailableSkill } from "./sisyphus-prompt-builder"
+import {
+  buildKeyTriggersSection,
+  buildToolSelectionTable,
+  buildExploreSection,
+  buildLibrarianSection,
+  buildDelegationTable,
+  buildFrontendSection,
+  buildOracleSection,
+  buildHardBlocksSection,
+  buildAntiPatternsSection,
+  categorizeTools,
+} from "./sisyphus-prompt-builder"
 
 const DEFAULT_MODEL = "anthropic/claude-opus-4-5"
 
-const SISYPHUS_SYSTEM_PROMPT = `<Role>
+const SISYPHUS_ROLE_SECTION = `<Role>
 You are "Sisyphus" - Powerful AI Agent with orchestration capabilities from OhMyOpenCode.
 Named by [YeonGyu Kim](https://github.com/code-yeongyu).
 
@@ -21,22 +34,27 @@ Named by [YeonGyu Kim](https://github.com/code-yeongyu).
 
 **Operating Mode**: You NEVER work alone when specialists are available. Frontend work → delegate. Deep research → parallel background agents (async subagents). Complex architecture → consult Oracle.
 
-</Role>
+</Role>`
 
-<Behavior_Instructions>
+const SISYPHUS_PHASE0_STEP1_3 = `### Step 0: Check Skills FIRST (BLOCKING)
 
-## Phase 0 - Intent Gate (EVERY message)
+**Before ANY classification or action, scan for matching skills.**
 
-### Key Triggers (check BEFORE classification):
-- External library/source mentioned → fire \`librarian\` background
-- 2+ modules involved → fire \`explore\` background
-- **GitHub mention (@mention in issue/PR)** → This is a WORK REQUEST. Plan full cycle: investigate → implement → create PR
-- **"Look into" + "create PR"** → Not just research. Full implementation cycle expected.
+\`\`\`
+IF request matches a skill trigger:
+  → INVOKE skill tool IMMEDIATELY
+  → Do NOT proceed to Step 1 until skill is invoked
+\`\`\`
+
+Skills are specialized workflows. When relevant, they handle the task better than manual orchestration.
+
+---
 
 ### Step 1: Classify Request Type
 
 | Type | Signal | Action |
 |------|--------|--------|
+| **Skill Match** | Matches skill trigger phrase | **INVOKE skill FIRST** via \`skill\` tool |
 | **Trivial** | Single file, known location, direct answer | Direct tools only (UNLESS Key Trigger applies) |
 | **Explicit** | Specific file/line, clear command | Execute directly |
 | **Exploratory** | "How does X work?", "Find Y" | Fire explore (1-3) + tools in parallel |
@@ -78,11 +96,9 @@ Then: Raise your concern concisely. Propose an alternative. Ask if they want to
 I notice [observation]. This might cause [problem] because [reason].
 Alternative: [your suggestion].
 Should I proceed with your original request, or try the alternative?
-\`\`\`
+\`\`\``
 
----
-
-## Phase 1 - Codebase Assessment (for Open-ended tasks)
+const SISYPHUS_PHASE1 = `## Phase 1 - Codebase Assessment (for Open-ended tasks)
 
 Before following existing patterns, assess whether they're worth following.
 
@@ -103,54 +119,9 @@ Before following existing patterns, assess whether they're worth following.
 IMPORTANT: If codebase appears undisciplined, verify before assuming:
 - Different patterns may serve different purposes (intentional)
 - Migration might be in progress
-- You might be looking at the wrong reference files
+- You might be looking at the wrong reference files`
 
----
-
-## Phase 2A - Exploration & Research
-
-### Tool Selection:
-
-| Tool | Cost | When to Use |
-|------|------|-------------|
-| \`grep\`, \`glob\`, \`lsp_*\`, \`ast_grep\` | FREE | Not Complex, Scope Clear, No Implicit Assumptions |
-| \`explore\` agent | FREE | Multiple search angles, unfamiliar modules, cross-layer patterns |
-| \`librarian\` agent | CHEAP | External docs, GitHub examples, OpenSource Implementations, OSS reference |
-| \`oracle\` agent | EXPENSIVE | Architecture, review, debugging after 2+ failures |
-
-**Default flow**: explore/librarian (background) + tools → oracle (if required)
-
-### Explore Agent = Contextual Grep
-
-Use it as a **peer tool**, not a fallback. Fire liberally.
-
-| Use Direct Tools | Use Explore Agent |
-|------------------|-------------------|
-| You know exactly what to search | Multiple search angles needed |
-| Single keyword/pattern suffices | Unfamiliar module structure |
-| Known file location | Cross-layer pattern discovery |
-
-### Librarian Agent = Reference Grep
-
-Search **external references** (docs, OSS, web). Fire proactively when unfamiliar libraries are involved.
-
-| Contextual Grep (Internal) | Reference Grep (External) |
-|----------------------------|---------------------------|
-| Search OUR codebase | Search EXTERNAL resources |
-| Find patterns in THIS repo | Find examples in OTHER repos |
-| How does our code work? | How does this library work? |
-| Project-specific logic | Official API documentation |
-| | Library best practices & quirks |
-| | OSS implementation examples |
-
-**Trigger phrases** (fire librarian immediately):
-- "How do I use [library]?"
-- "What's the best practice for [framework feature]?"
-- "Why does [external dependency] behave this way?"
-- "Find examples of [library] usage"
-- Working with unfamiliar npm/pip/cargo packages
-
-### Parallel Execution (DEFAULT behavior)
+const SISYPHUS_PARALLEL_EXECUTION = `### Parallel Execution (DEFAULT behavior)
 
 **Explore/Librarian = Grep, not consultants.
 
@@ -182,64 +153,16 @@ STOP searching when:
 - 2 search iterations yielded no new useful data
 - Direct answer found
 
-**DO NOT over-explore. Time is precious.**
+**DO NOT over-explore. Time is precious.**`
 
----
-
-## Phase 2B - Implementation
+const SISYPHUS_PHASE2B_PRE_IMPLEMENTATION = `## Phase 2B - Implementation
 
 ### Pre-Implementation:
 1. If task has 2+ steps → Create todo list IMMEDIATELY, IN SUPER DETAIL. No announcements—just create it.
 2. Mark current task \`in_progress\` before starting
-3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS
+3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS`
 
-### Frontend Files: Decision Gate (NOT a blind block)
-
-Frontend files (.tsx, .jsx, .vue, .svelte, .css, etc.) require **classification before action**.
-
-#### Step 1: Classify the Change Type
-
-| Change Type | Examples | Action |
-|-------------|----------|--------|
-| **Visual/UI/UX** | Color, spacing, layout, typography, animation, responsive breakpoints, hover states, shadows, borders, icons, images | **DELEGATE** to \`frontend-ui-ux-engineer\` |
-| **Pure Logic** | API calls, data fetching, state management, event handlers (non-visual), type definitions, utility functions, business logic | **CAN handle directly** |
-| **Mixed** | Component changes both visual AND logic | **Split**: handle logic yourself, delegate visual to \`frontend-ui-ux-engineer\` |
-
-#### Step 2: Ask Yourself
-
-Before touching any frontend file, think:
-> "Is this change about **how it LOOKS** or **how it WORKS**?"
-
-- **LOOKS** (colors, sizes, positions, animations) → DELEGATE
-- **WORKS** (data flow, API integration, state) → Handle directly
-
-#### Quick Reference Examples
-
-| File | Change | Type | Action |
-|------|--------|------|--------|
-| \`Button.tsx\` | Change color blue→green | Visual | DELEGATE |
-| \`Button.tsx\` | Add onClick API call | Logic | Direct |
-| \`UserList.tsx\` | Add loading spinner animation | Visual | DELEGATE |
-| \`UserList.tsx\` | Fix pagination logic bug | Logic | Direct |
-| \`Modal.tsx\` | Make responsive for mobile | Visual | DELEGATE |
-| \`Modal.tsx\` | Add form validation logic | Logic | Direct |
-
-#### When in Doubt → DELEGATE if ANY of these keywords involved:
-style, className, tailwind, color, background, border, shadow, margin, padding, width, height, flex, grid, animation, transition, hover, responsive, font-size, icon, svg
-
-### Delegation Table:
-
-| Domain | Delegate To | Trigger |
-|--------|-------------|---------|
-| Explore | \`explore\` | Find existing codebase structure, patterns and styles |
-| Frontend UI/UX | \`frontend-ui-ux-engineer\` | Visual changes only (styling, layout, animation). Pure logic changes in frontend files → handle directly |
-| Librarian | \`librarian\` | Unfamiliar packages / libraries, struggles at weird behaviour (to find existing implementation of opensource) |
-| Documentation | \`document-writer\` | README, API docs, guides |
-| Architecture decisions | \`oracle\` | Multi-system tradeoffs, unfamiliar patterns |
-| Self-review | \`oracle\` | After completing significant implementation |
-| Hard debugging | \`oracle\` | After 2+ failed fix attempts |
-
-### Delegation Prompt Structure (MANDATORY - ALL 7 sections):
+const SISYPHUS_DELEGATION_PROMPT_STRUCTURE = `### Delegation Prompt Structure (MANDATORY - ALL 7 sections):
 
 When delegating, your prompt MUST include:
 
@@ -259,9 +182,9 @@ AFTER THE WORK YOU DELEGATED SEEMS DONE, ALWAYS VERIFY THE RESULTS AS FOLLOWING:
 - EXPECTED RESULT CAME OUT?
 - DID THE AGENT FOLLOWED "MUST DO" AND "MUST NOT DO" REQUIREMENTS?
 
-**Vague prompts = rejected. Be exhaustive.**
+**Vague prompts = rejected. Be exhaustive.**`
 
-### GitHub Workflow (CRITICAL - When mentioned in issues/PRs):
+const SISYPHUS_GITHUB_WORKFLOW = `### GitHub Workflow (CRITICAL - When mentioned in issues/PRs):
 
 When you're mentioned in GitHub issues or asked to "look into" something and "create PR":
 
@@ -294,9 +217,9 @@ When you're mentioned in GitHub issues or asked to "look into" something and "cr
 **EMPHASIS**: "Look into" does NOT mean "just investigate and report back." 
 It means "investigate, understand, implement a solution, and create a PR."
 
-**If the user says "look into X and create PR", they expect a PR, not just analysis.**
+**If the user says "look into X and create PR", they expect a PR, not just analysis.**`
 
-### Code Changes:
+const SISYPHUS_CODE_CHANGES = `### Code Changes:
 - Match existing patterns (if codebase is disciplined)
 - Propose approach first (if codebase is chaotic)
 - Never suppress type errors with \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\`
@@ -322,11 +245,9 @@ If project has build/test commands, run them at task completion.
 | Test run | Pass (or explicit note of pre-existing failures) |
 | Delegation | Agent result received and verified |
 
-**NO EVIDENCE = NOT COMPLETE.**
+**NO EVIDENCE = NOT COMPLETE.**`
 
----
-
-## Phase 2C - Failure Recovery
+const SISYPHUS_PHASE2C = `## Phase 2C - Failure Recovery
 
 ### When Fixes Fail:
 
@@ -342,11 +263,9 @@ If project has build/test commands, run them at task completion.
 4. **CONSULT** Oracle with full failure context
 5. If Oracle cannot resolve → **ASK USER** before proceeding
 
-**Never**: Leave code in broken state, continue hoping it'll work, delete failing tests to "pass"
+**Never**: Leave code in broken state, continue hoping it'll work, delete failing tests to "pass"`
 
----
-
-## Phase 3 - Completion
+const SISYPHUS_PHASE3 = `## Phase 3 - Completion
 
 A task is complete when:
 - [ ] All planned todo items marked done
@@ -361,41 +280,9 @@ If verification fails:
 
 ### Before Delivering Final Answer:
 - Cancel ALL running background tasks: \`background_cancel(all=true)\`
-- This conserves resources and ensures clean workflow completion
+- This conserves resources and ensures clean workflow completion`
 
-</Behavior_Instructions>
-
-<Oracle_Usage>
-## Oracle — Your Senior Engineering Advisor (GPT-5.2)
-
-Oracle is an expensive, high-quality reasoning model. Use it wisely.
-
-### WHEN to Consult:
-
-| Trigger | Action |
-|---------|--------|
-| Complex architecture design | Oracle FIRST, then implement |
-| After completing significant work | Oracle review before marking complete |
-| 2+ failed fix attempts | Oracle for debugging guidance |
-| Unfamiliar code patterns | Oracle to explain behavior |
-| Security/performance concerns | Oracle for analysis |
-| Multi-system tradeoffs | Oracle for architectural decision |
-
-### WHEN NOT to Consult:
-
-- Simple file operations (use direct tools)
-- First attempt at any fix (try yourself first)
-- Questions answerable from code you've read
-- Trivial decisions (variable names, formatting)
-- Things you can infer from existing code patterns
-
-### Usage Pattern:
-Briefly announce "Consulting Oracle for [reason]" before invocation.
-
-**Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
-</Oracle_Usage>
-
-<Task_Management>
+const SISYPHUS_TASK_MANAGEMENT = `<Task_Management>
 ## Todo Management (CRITICAL)
 
 **DEFAULT BEHAVIOR**: Create todos BEFORE starting any non-trivial task. This is your PRIMARY coordination mechanism.
@@ -450,9 +337,9 @@ I want to make sure I understand correctly.
 
 Should I proceed with [recommendation], or would you prefer differently?
 \`\`\`
-</Task_Management>
+</Task_Management>`
 
-<Tone_and_Style>
+const SISYPHUS_TONE_AND_STYLE = `<Tone_and_Style>
 ## Communication Style
 
 ### Be Concise
@@ -492,31 +379,9 @@ If the user's approach seems problematic:
 - If user is terse, be terse
 - If user wants detail, provide detail
 - Adapt to their communication preference
-</Tone_and_Style>
+</Tone_and_Style>`
 
-<Constraints>
-## Hard Blocks (NEVER violate)
-
-| Constraint | No Exceptions |
-|------------|---------------|
-| Frontend VISUAL changes (styling, layout, animation) | Always delegate to \`frontend-ui-ux-engineer\` |
-| Type error suppression (\`as any\`, \`@ts-ignore\`) | Never |
-| Commit without explicit request | Never |
-| Speculate about unread code | Never |
-| Leave code in broken state after failures | Never |
-
-## Anti-Patterns (BLOCKING violations)
-
-| Category | Forbidden |
-|----------|-----------|
-| **Type Safety** | \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\` |
-| **Error Handling** | Empty catch blocks \`catch(e) {}\` |
-| **Testing** | Deleting failing tests to "pass" |
-| **Search** | Firing agents for single-line typos or obvious syntax errors |
-| **Frontend** | Direct edit to visual/styling code (logic changes OK) |
-| **Debugging** | Shotgun debugging, random changes |
-
-## Soft Guidelines
+const SISYPHUS_SOFT_GUIDELINES = `## Soft Guidelines
 
 - Prefer existing libraries over new dependencies
 - Prefer small, focused changes over large refactors
@@ -525,14 +390,107 @@ If the user's approach seems problematic:
 
 `
 
-export function createSisyphusAgent(model: string = DEFAULT_MODEL): AgentConfig {
+function buildDynamicSisyphusPrompt(
+  availableAgents: AvailableAgent[],
+  availableTools: AvailableTool[] = [],
+  availableSkills: AvailableSkill[] = []
+): string {
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
+  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
+  const exploreSection = buildExploreSection(availableAgents)
+  const librarianSection = buildLibrarianSection(availableAgents)
+  const frontendSection = buildFrontendSection(availableAgents)
+  const delegationTable = buildDelegationTable(availableAgents)
+  const oracleSection = buildOracleSection(availableAgents)
+  const hardBlocks = buildHardBlocksSection(availableAgents)
+  const antiPatterns = buildAntiPatternsSection(availableAgents)
+
+  const sections = [
+    SISYPHUS_ROLE_SECTION,
+    "<Behavior_Instructions>",
+    "",
+    "## Phase 0 - Intent Gate (EVERY message)",
+    "",
+    keyTriggers,
+    "",
+    SISYPHUS_PHASE0_STEP1_3,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE1,
+    "",
+    "---",
+    "",
+    "## Phase 2A - Exploration & Research",
+    "",
+    toolSelection,
+    "",
+    exploreSection,
+    "",
+    librarianSection,
+    "",
+    SISYPHUS_PARALLEL_EXECUTION,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2B_PRE_IMPLEMENTATION,
+    "",
+    frontendSection,
+    "",
+    delegationTable,
+    "",
+    SISYPHUS_DELEGATION_PROMPT_STRUCTURE,
+    "",
+    SISYPHUS_GITHUB_WORKFLOW,
+    "",
+    SISYPHUS_CODE_CHANGES,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE2C,
+    "",
+    "---",
+    "",
+    SISYPHUS_PHASE3,
+    "",
+    "</Behavior_Instructions>",
+    "",
+    oracleSection,
+    "",
+    SISYPHUS_TASK_MANAGEMENT,
+    "",
+    SISYPHUS_TONE_AND_STYLE,
+    "",
+    "<Constraints>",
+    hardBlocks,
+    "",
+    antiPatterns,
+    "",
+    SISYPHUS_SOFT_GUIDELINES,
+  ]
+
+  return sections.filter((s) => s !== "").join("\n")
+}
+
+export function createSisyphusAgent(
+  model: string = DEFAULT_MODEL,
+  availableAgents?: AvailableAgent[],
+  availableToolNames?: string[],
+  availableSkills?: AvailableSkill[]
+): AgentConfig {
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
+  const skills = availableSkills ?? []
+  const prompt = availableAgents
+    ? buildDynamicSisyphusPrompt(availableAgents, tools, skills)
+    : buildDynamicSisyphusPrompt([], tools, skills)
+
   const base = {
     description:
       "Sisyphus - Powerful AI orchestrator from OhMyOpenCode. Plans obsessively with todos, assesses search complexity before exploration, delegates strategically to specialized agents. Uses explore for internal code (parallel-friendly), librarian only for external docs, and always delegates UI work to frontend engineer.",
     mode: "primary" as const,
     model,
     maxTokens: 64000,
-    prompt: SISYPHUS_SYSTEM_PROMPT,
+    prompt,
     color: "#00CED1",
   }
 

src/agents/types.ts

@@ -2,6 +2,56 @@ import type { AgentConfig } from "@opencode-ai/sdk"
 
 export type AgentFactory = (model?: string) => AgentConfig
 
+/**
+ * Agent category for grouping in Sisyphus prompt sections
+ */
+export type AgentCategory = "exploration" | "specialist" | "advisor" | "utility"
+
+/**
+ * Cost classification for Tool Selection table
+ */
+export type AgentCost = "FREE" | "CHEAP" | "EXPENSIVE"
+
+/**
+ * Delegation trigger for Sisyphus prompt's Delegation Table
+ */
+export interface DelegationTrigger {
+  /** Domain of work (e.g., "Frontend UI/UX") */
+  domain: string
+  /** When to delegate (e.g., "Visual changes only...") */
+  trigger: string
+}
+
+/**
+ * Metadata for generating Sisyphus prompt sections dynamically
+ * This allows adding/removing agents without manually updating the Sisyphus prompt
+ */
+export interface AgentPromptMetadata {
+  /** Category for grouping in prompt sections */
+  category: AgentCategory
+
+  /** Cost classification for Tool Selection table */
+  cost: AgentCost
+
+  /** Domain triggers for Delegation Table */
+  triggers: DelegationTrigger[]
+
+  /** When to use this agent (for detailed sections) */
+  useWhen?: string[]
+
+  /** When NOT to use this agent */
+  avoidWhen?: string[]
+
+  /** Optional dedicated prompt section (markdown) - for agents like Oracle that have special sections */
+  dedicatedSection?: string
+
+  /** Nickname/alias used in prompt (e.g., "Oracle" instead of "oracle") */
+  promptAlias?: string
+
+  /** Key triggers that should appear in Phase 0 (e.g., "External library mentioned → fire librarian") */
+  keyTrigger?: string
+}
+
 export function isGptModel(model: string): boolean {
   return model.startsWith("openai/") || model.startsWith("github-copilot/gpt-")
 }

src/agents/utils.ts

@@ -1,12 +1,13 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
-import type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, AgentFactory } from "./types"
+import type { BuiltinAgentName, AgentOverrideConfig, AgentOverrides, AgentFactory, AgentPromptMetadata } from "./types"
 import { createSisyphusAgent } from "./sisyphus"
-import { createOracleAgent } from "./oracle"
-import { createLibrarianAgent } from "./librarian"
-import { createExploreAgent } from "./explore"
-import { createFrontendUiUxEngineerAgent } from "./frontend-ui-ux-engineer"
-import { createDocumentWriterAgent } from "./document-writer"
-import { createMultimodalLookerAgent } from "./multimodal-looker"
+import { createOracleAgent, ORACLE_PROMPT_METADATA } from "./oracle"
+import { createLibrarianAgent, LIBRARIAN_PROMPT_METADATA } from "./librarian"
+import { createExploreAgent, EXPLORE_PROMPT_METADATA } from "./explore"
+import { createFrontendUiUxEngineerAgent, FRONTEND_PROMPT_METADATA } from "./frontend-ui-ux-engineer"
+import { createDocumentWriterAgent, DOCUMENT_WRITER_PROMPT_METADATA } from "./document-writer"
+import { createMultimodalLookerAgent, MULTIMODAL_LOOKER_PROMPT_METADATA } from "./multimodal-looker"
+import type { AvailableAgent } from "./sisyphus-prompt-builder"
 import { deepMerge } from "../shared"
 
 type AgentSource = AgentFactory | AgentConfig
@@ -21,6 +22,19 @@ const agentSources: Record<BuiltinAgentName, AgentSource> = {
   "multimodal-looker": createMultimodalLookerAgent,
 }
 
+/**
+ * Metadata for each agent, used to build Sisyphus's dynamic prompt sections
+ * (Delegation Table, Tool Selection, Key Triggers, etc.)
+ */
+const agentMetadata: Partial<Record<BuiltinAgentName, AgentPromptMetadata>> = {
+  oracle: ORACLE_PROMPT_METADATA,
+  librarian: LIBRARIAN_PROMPT_METADATA,
+  explore: EXPLORE_PROMPT_METADATA,
+  "frontend-ui-ux-engineer": FRONTEND_PROMPT_METADATA,
+  "document-writer": DOCUMENT_WRITER_PROMPT_METADATA,
+  "multimodal-looker": MULTIMODAL_LOOKER_PROMPT_METADATA,
+}
+
 function isFactory(source: AgentSource): source is AgentFactory {
   return typeof source === "function"
 }
@@ -29,18 +43,17 @@ function buildAgent(source: AgentSource, model?: string): AgentConfig {
   return isFactory(source) ? source(model) : source
 }
 
-export function createEnvContext(directory: string): string {
+/**
+ * Creates OmO-specific environment context (time, timezone, locale).
+ * Note: Working directory, platform, and date are already provided by OpenCode's system.ts,
+ * so we only include fields that OpenCode doesn't provide to avoid duplication.
+ * See: https://github.com/code-yeongyu/oh-my-opencode/issues/379
+ */
+export function createEnvContext(): string {
   const now = new Date()
   const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
   const locale = Intl.DateTimeFormat().resolvedOptions().locale
 
-  const dateStr = now.toLocaleDateString("en-US", {
-    weekday: "short",
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  })
-
   const timeStr = now.toLocaleTimeString("en-US", {
     hour: "2-digit",
     minute: "2-digit",
@@ -48,18 +61,12 @@ export function createEnvContext(directory: string): string {
     hour12: true,
   })
 
-  const platform = process.platform as "darwin" | "linux" | "win32" | string
-
   return `
-Here is some useful information about the environment you are running in:
-<env>
-  Working directory: ${directory}
-  Platform: ${platform}
-  Today's date: ${dateStr} (NOT 2024, NEVEREVER 2024)
+<omo-env>
   Current time: ${timeStr}
   Timezone: ${timezone}
   Locale: ${locale}
-</env>`
+</omo-env>`
 }
 
 function mergeAgentConfig(
@@ -83,21 +90,21 @@ export function createBuiltinAgents(
   systemDefaultModel?: string
 ): Record<string, AgentConfig> {
   const result: Record<string, AgentConfig> = {}
+  const availableAgents: AvailableAgent[] = []
 
   for (const [name, source] of Object.entries(agentSources)) {
     const agentName = name as BuiltinAgentName
 
-    if (disabledAgents.includes(agentName)) {
-      continue
-    }
+    if (agentName === "Sisyphus") continue
+    if (disabledAgents.includes(agentName)) continue
 
     const override = agentOverrides[agentName]
-    const model = override?.model ?? (agentName === "Sisyphus" ? systemDefaultModel : undefined)
+    const model = override?.model
 
     let config = buildAgent(source, model)
 
-    if ((agentName === "Sisyphus" || agentName === "librarian") && directory && config.prompt) {
-      const envContext = createEnvContext(directory)
+    if (agentName === "librarian" && directory && config.prompt) {
+      const envContext = createEnvContext()
       config = { ...config, prompt: config.prompt + envContext }
     }
 
@@ -106,6 +113,33 @@ export function createBuiltinAgents(
     }
 
     result[name] = config
+
+    const metadata = agentMetadata[agentName]
+    if (metadata) {
+      availableAgents.push({
+        name: agentName,
+        description: config.description ?? "",
+        metadata,
+      })
+    }
+  }
+
+  if (!disabledAgents.includes("Sisyphus")) {
+    const sisyphusOverride = agentOverrides["Sisyphus"]
+    const sisyphusModel = sisyphusOverride?.model ?? systemDefaultModel
+
+    let sisyphusConfig = createSisyphusAgent(sisyphusModel, availableAgents)
+
+    if (directory && sisyphusConfig.prompt) {
+      const envContext = createEnvContext()
+      sisyphusConfig = { ...sisyphusConfig, prompt: sisyphusConfig.prompt + envContext }
+    }
+
+    if (sisyphusOverride) {
+      sisyphusConfig = mergeAgentConfig(sisyphusConfig, sisyphusOverride)
+    }
+
+    result["Sisyphus"] = sisyphusConfig
   }
 
   return result

src/auth/AGENTS.md

@@ -0,0 +1,57 @@
+# AUTH KNOWLEDGE BASE
+
+## OVERVIEW
+
+Google Antigravity OAuth for Gemini models. Token management, fetch interception, thinking block extraction.
+
+## STRUCTURE
+
+```
+auth/
+└── antigravity/
+    ├── plugin.ts         # Main export, hooks registration
+    ├── oauth.ts          # OAuth flow, token acquisition
+    ├── token.ts          # Token storage, refresh logic
+    ├── fetch.ts          # Fetch interceptor (621 lines)
+    ├── response.ts       # Response transformation (598 lines)
+    ├── thinking.ts       # Thinking block extraction (571 lines)
+    ├── thought-signature-store.ts  # Signature caching
+    ├── message-converter.ts        # Format conversion
+    ├── request.ts        # Request building
+    ├── project.ts        # Project ID management
+    ├── tools.ts          # OAuth tool registration
+    ├── constants.ts      # API endpoints, model mappings
+    └── types.ts
+```
+
+## KEY COMPONENTS
+
+| File | Purpose |
+|------|---------|
+| fetch.ts | URL rewriting, token injection, retries |
+| thinking.ts | Extract `<antThinking>` blocks |
+| response.ts | Streaming SSE parsing |
+| oauth.ts | Browser-based OAuth flow |
+| token.ts | Token persistence, expiry |
+
+## 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
+
+## FEATURES
+
+- Multi-account (up to 10 Google accounts)
+- Auto-fallback on rate limit
+- Thinking blocks preserved
+- Antigravity proxy for AI Studio access
+
+## 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)

src/cli/AGENTS.md

@@ -0,0 +1,68 @@
+# 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
+├── install.ts            # Interactive TUI installer (477 lines)
+├── config-manager.ts     # JSONC parsing, env detection (669 lines)
+├── types.ts              # CLI-specific types
+├── doctor/               # Health check system
+│   ├── index.ts          # Doctor command entry
+│   ├── constants.ts      # Check categories
+│   ├── types.ts          # Check result interfaces
+│   └── checks/           # 17+ individual checks
+├── get-local-version/    # Version detection
+└── run/                  # OpenCode session launcher
+```
+
+## CLI COMMANDS
+
+| Command | Purpose |
+|---------|---------|
+| `install` | Interactive setup wizard |
+| `doctor` | Environment health checks |
+| `run` | Launch OpenCode session |
+
+## 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
+
+## 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
+
+## 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`
+
+## 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

src/cli/config-manager.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { parseJsonc } from "../shared"
@@ -14,6 +14,49 @@ const OPENCODE_BINARIES = ["opencode", "opencode-desktop"] as const
 
 const CHATGPT_HOTFIX_REPO = "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
 
+const BUN_INSTALL_TIMEOUT_SECONDS = 60
+const BUN_INSTALL_TIMEOUT_MS = BUN_INSTALL_TIMEOUT_SECONDS * 1000
+
+interface NodeError extends Error {
+  code?: string
+}
+
+function isPermissionError(err: unknown): boolean {
+  const nodeErr = err as NodeError
+  return nodeErr?.code === "EACCES" || nodeErr?.code === "EPERM"
+}
+
+function isFileNotFoundError(err: unknown): boolean {
+  const nodeErr = err as NodeError
+  return nodeErr?.code === "ENOENT"
+}
+
+function formatErrorWithSuggestion(err: unknown, context: string): string {
+  if (isPermissionError(err)) {
+    return `Permission denied: Cannot ${context}. Try running with elevated permissions or check file ownership.`
+  }
+
+  if (isFileNotFoundError(err)) {
+    return `File not found while trying to ${context}. The file may have been deleted or moved.`
+  }
+
+  if (err instanceof SyntaxError) {
+    return `JSON syntax error while trying to ${context}: ${err.message}. Check for missing commas, brackets, or invalid characters.`
+  }
+
+  const message = err instanceof Error ? err.message : String(err)
+
+  if (message.includes("ENOSPC")) {
+    return `Disk full: Cannot ${context}. Free up disk space and try again.`
+  }
+
+  if (message.includes("EROFS")) {
+    return `Read-only filesystem: Cannot ${context}. Check if the filesystem is mounted read-only.`
+  }
+
+  return `Failed to ${context}: ${message}`
+}
+
 export async function fetchLatestVersion(packageName: string): Promise<string | null> {
   try {
     const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`)
@@ -42,12 +85,46 @@ export function detectConfigFormat(): { format: ConfigFormat; path: string } {
   return { format: "none", path: OPENCODE_JSON }
 }
 
-function parseConfig(path: string, isJsonc: boolean): OpenCodeConfig | null {
+interface ParseConfigResult {
+  config: OpenCodeConfig | null
+  error?: string
+}
+
+function isEmptyOrWhitespace(content: string): boolean {
+  return content.trim().length === 0
+}
+
+function parseConfig(path: string, _isJsonc: boolean): OpenCodeConfig | null {
+  const result = parseConfigWithError(path)
+  return result.config
+}
+
+function parseConfigWithError(path: string): ParseConfigResult {
   try {
+    const stat = statSync(path)
+    if (stat.size === 0) {
+      return { config: null, error: `Config file is empty: ${path}. Delete it or add valid JSON content.` }
+    }
+
     const content = readFileSync(path, "utf-8")
-    return parseJsonc<OpenCodeConfig>(content)
-  } catch {
-    return null
+
+    if (isEmptyOrWhitespace(content)) {
+      return { config: null, error: `Config file contains only whitespace: ${path}. Delete it or add valid JSON content.` }
+    }
+
+    const config = parseJsonc<OpenCodeConfig>(content)
+
+    if (config === null || config === undefined) {
+      return { config: null, error: `Config file parsed to null/undefined: ${path}. Ensure it contains valid JSON.` }
+    }
+
+    if (typeof config !== "object" || Array.isArray(config)) {
+      return { config: null, error: `Config file must contain a JSON object, not ${Array.isArray(config) ? "an array" : typeof config}: ${path}` }
+    }
+
+    return { config }
+  } catch (err) {
+    return { config: null, error: formatErrorWithSuggestion(err, `parse config file ${path}`) }
   }
 }
 
@@ -58,7 +135,11 @@ function ensureConfigDir(): void {
 }
 
 export function addPluginToOpenCodeConfig(): ConfigMergeResult {
-  ensureConfigDir()
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
 
   const { format, path } = detectConfigFormat()
   const pluginName = "oh-my-opencode"
@@ -70,11 +151,12 @@ export function addPluginToOpenCodeConfig(): ConfigMergeResult {
       return { success: true, configPath: path }
     }
 
-    const config = parseConfig(path, format === "jsonc")
-    if (!config) {
-      return { success: false, configPath: path, error: "Failed to parse config" }
+    const parseResult = parseConfigWithError(path)
+    if (!parseResult.config) {
+      return { success: false, configPath: path, error: parseResult.error ?? "Failed to parse config file" }
     }
 
+    const config = parseResult.config
     const plugins = config.plugin ?? []
     if (plugins.some((p) => p.startsWith(pluginName))) {
       return { success: true, configPath: path }
@@ -104,7 +186,7 @@ export function addPluginToOpenCodeConfig(): ConfigMergeResult {
 
     return { success: true, configPath: path }
   } catch (err) {
-    return { success: false, configPath: path, error: String(err) }
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "update opencode config") }
   }
 }
 
@@ -185,24 +267,48 @@ export function generateOmoConfig(installConfig: InstallConfig): Record<string,
 }
 
 export function writeOmoConfig(installConfig: InstallConfig): ConfigMergeResult {
-  ensureConfigDir()
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
 
   try {
     const newConfig = generateOmoConfig(installConfig)
 
     if (existsSync(OMO_CONFIG)) {
-      const content = readFileSync(OMO_CONFIG, "utf-8")
-      const existing = parseJsonc<Record<string, unknown>>(content)
-      delete existing.agents
-      const merged = deepMerge(existing, newConfig)
-      writeFileSync(OMO_CONFIG, JSON.stringify(merged, null, 2) + "\n")
+      try {
+        const stat = statSync(OMO_CONFIG)
+        const content = readFileSync(OMO_CONFIG, "utf-8")
+
+        if (stat.size === 0 || isEmptyOrWhitespace(content)) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+
+        const existing = parseJsonc<Record<string, unknown>>(content)
+        if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+
+        delete existing.agents
+        const merged = deepMerge(existing, newConfig)
+        writeFileSync(OMO_CONFIG, JSON.stringify(merged, null, 2) + "\n")
+      } catch (parseErr) {
+        if (parseErr instanceof SyntaxError) {
+          writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
+          return { success: true, configPath: OMO_CONFIG }
+        }
+        throw parseErr
+      }
     } else {
       writeFileSync(OMO_CONFIG, JSON.stringify(newConfig, null, 2) + "\n")
     }
 
     return { success: true, configPath: OMO_CONFIG }
   } catch (err) {
-    return { success: false, configPath: OMO_CONFIG, error: String(err) }
+    return { success: false, configPath: OMO_CONFIG, error: formatErrorWithSuggestion(err, "write oh-my-opencode config") }
   }
 }
 
@@ -241,11 +347,25 @@ export async function getOpenCodeVersion(): Promise<string | null> {
 }
 
 export async function addAuthPlugins(config: InstallConfig): Promise<ConfigMergeResult> {
-  ensureConfigDir()
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
   const { format, path } = detectConfigFormat()
 
   try {
-    const existingConfig = format !== "none" ? parseConfig(path, format === "jsonc") : null
+    let existingConfig: OpenCodeConfig | null = null
+    if (format !== "none") {
+      const parseResult = parseConfigWithError(path)
+      if (parseResult.error && !parseResult.config) {
+        existingConfig = {}
+      } else {
+        existingConfig = parseResult.config
+      }
+    }
+
     const plugins: string[] = existingConfig?.plugin ?? []
 
     if (config.hasGemini) {
@@ -266,18 +386,37 @@ export async function addAuthPlugins(config: InstallConfig): Promise<ConfigMerge
     writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n")
     return { success: true, configPath: path }
   } catch (err) {
-    return { success: false, configPath: path, error: String(err) }
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "add auth plugins to config") }
   }
 }
 
 export function setupChatGPTHotfix(): ConfigMergeResult {
-  ensureConfigDir()
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
 
   try {
     let packageJson: Record<string, unknown> = {}
     if (existsSync(OPENCODE_PACKAGE_JSON)) {
-      const content = readFileSync(OPENCODE_PACKAGE_JSON, "utf-8")
-      packageJson = JSON.parse(content)
+      try {
+        const stat = statSync(OPENCODE_PACKAGE_JSON)
+        const content = readFileSync(OPENCODE_PACKAGE_JSON, "utf-8")
+
+        if (stat.size > 0 && !isEmptyOrWhitespace(content)) {
+          packageJson = JSON.parse(content)
+          if (typeof packageJson !== "object" || packageJson === null || Array.isArray(packageJson)) {
+            packageJson = {}
+          }
+        }
+      } catch (parseErr) {
+        if (parseErr instanceof SyntaxError) {
+          packageJson = {}
+        } else {
+          throw parseErr
+        }
+      }
     }
 
     const deps = (packageJson.dependencies ?? {}) as Record<string, string>
@@ -287,21 +426,65 @@ export function setupChatGPTHotfix(): ConfigMergeResult {
     writeFileSync(OPENCODE_PACKAGE_JSON, JSON.stringify(packageJson, null, 2) + "\n")
     return { success: true, configPath: OPENCODE_PACKAGE_JSON }
   } catch (err) {
-    return { success: false, configPath: OPENCODE_PACKAGE_JSON, error: String(err) }
+    return { success: false, configPath: OPENCODE_PACKAGE_JSON, error: formatErrorWithSuggestion(err, "setup ChatGPT hotfix in package.json") }
   }
 }
 
+export interface BunInstallResult {
+  success: boolean
+  timedOut?: boolean
+  error?: string
+}
+
 export async function runBunInstall(): Promise<boolean> {
+  const result = await runBunInstallWithDetails()
+  return result.success
+}
+
+export async function runBunInstallWithDetails(): Promise<BunInstallResult> {
   try {
     const proc = Bun.spawn(["bun", "install"], {
       cwd: OPENCODE_CONFIG_DIR,
       stdout: "pipe",
       stderr: "pipe",
     })
-    await proc.exited
-    return proc.exitCode === 0
-  } catch {
-    return false
+
+    const timeoutPromise = new Promise<"timeout">((resolve) =>
+      setTimeout(() => resolve("timeout"), BUN_INSTALL_TIMEOUT_MS)
+    )
+
+    const exitPromise = proc.exited.then(() => "completed" as const)
+
+    const result = await Promise.race([exitPromise, timeoutPromise])
+
+    if (result === "timeout") {
+      try {
+        proc.kill()
+      } catch {
+        /* intentionally empty - process may have already exited */
+      }
+      return {
+        success: false,
+        timedOut: true,
+        error: `bun install timed out after ${BUN_INSTALL_TIMEOUT_SECONDS} seconds. Try running manually: cd ~/.config/opencode && bun i`,
+      }
+    }
+
+    if (proc.exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text()
+      return {
+        success: false,
+        error: stderr.trim() || `bun install failed with exit code ${proc.exitCode}`,
+      }
+    }
+
+    return { success: true }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return {
+      success: false,
+      error: `bun install failed: ${message}. Is bun installed? Try: curl -fsSL https://bun.sh/install | bash`,
+    }
   }
 }
 
@@ -362,11 +545,25 @@ const CODEX_PROVIDER_CONFIG = {
 }
 
 export function addProviderConfig(config: InstallConfig): ConfigMergeResult {
-  ensureConfigDir()
+  try {
+    ensureConfigDir()
+  } catch (err) {
+    return { success: false, configPath: OPENCODE_CONFIG_DIR, error: formatErrorWithSuggestion(err, "create config directory") }
+  }
+
   const { format, path } = detectConfigFormat()
 
   try {
-    const existingConfig = format !== "none" ? parseConfig(path, format === "jsonc") : null
+    let existingConfig: OpenCodeConfig | null = null
+    if (format !== "none") {
+      const parseResult = parseConfigWithError(path)
+      if (parseResult.error && !parseResult.config) {
+        existingConfig = {}
+      } else {
+        existingConfig = parseResult.config
+      }
+    }
+
     const newConfig = { ...(existingConfig ?? {}) }
 
     const providers = (newConfig.provider ?? {}) as Record<string, unknown>
@@ -386,7 +583,7 @@ export function addProviderConfig(config: InstallConfig): ConfigMergeResult {
     writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n")
     return { success: true, configPath: path }
   } catch (err) {
-    return { success: false, configPath: path, error: String(err) }
+    return { success: false, configPath: path, error: formatErrorWithSuggestion(err, "add provider config") }
   }
 }
 
@@ -409,11 +606,12 @@ export function detectCurrentConfig(): DetectedConfig {
     return result
   }
 
-  const openCodeConfig = parseConfig(path, format === "jsonc")
-  if (!openCodeConfig) {
+  const parseResult = parseConfigWithError(path)
+  if (!parseResult.config) {
     return result
   }
 
+  const openCodeConfig = parseResult.config
   const plugins = openCodeConfig.plugin ?? []
   result.isInstalled = plugins.some((p) => p.startsWith("oh-my-opencode"))
 
@@ -429,8 +627,20 @@ export function detectCurrentConfig(): DetectedConfig {
   }
 
   try {
+    const stat = statSync(OMO_CONFIG)
+    if (stat.size === 0) {
+      return result
+    }
+
     const content = readFileSync(OMO_CONFIG, "utf-8")
+    if (isEmptyOrWhitespace(content)) {
+      return result
+    }
+
     const omoConfig = parseJsonc<OmoConfigData>(content)
+    if (!omoConfig || typeof omoConfig !== "object") {
+      return result
+    }
 
     const agents = omoConfig.agents ?? {}
 
@@ -452,7 +662,7 @@ export function detectCurrentConfig(): DetectedConfig {
       result.hasGemini = plugins.some((p) => p.startsWith("opencode-antigravity-auth"))
     }
   } catch {
-    /* intentionally empty - malformed config returns defaults */
+    /* intentionally empty - malformed omo config returns defaults from opencode config detection */
   }
 
   return result

src/cli/doctor/checks/auth.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as auth from "./auth"
+
+describe("auth check", () => {
+  describe("getAuthProviderInfo", () => {
+    it("returns anthropic as always available", () => {
+      // #given anthropic provider
+      // #when getting info
+      const info = auth.getAuthProviderInfo("anthropic")
+
+      // #then should show plugin installed (builtin)
+      expect(info.id).toBe("anthropic")
+      expect(info.pluginInstalled).toBe(true)
+    })
+
+    it("returns correct name for each provider", () => {
+      // #given each provider
+      // #when getting info
+      // #then should have correct names
+      expect(auth.getAuthProviderInfo("anthropic").name).toContain("Claude")
+      expect(auth.getAuthProviderInfo("openai").name).toContain("ChatGPT")
+      expect(auth.getAuthProviderInfo("google").name).toContain("Gemini")
+    })
+  })
+
+  describe("checkAuthProvider", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when plugin installed", async () => {
+      // #given plugin installed
+      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
+        id: "anthropic",
+        name: "Anthropic (Claude)",
+        pluginInstalled: true,
+        configured: true,
+      })
+
+      // #when checking
+      const result = await auth.checkAuthProvider("anthropic")
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+    })
+
+    it("returns skip when plugin not installed", async () => {
+      // #given plugin not installed
+      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
+        id: "openai",
+        name: "OpenAI (ChatGPT)",
+        pluginInstalled: false,
+        configured: false,
+      })
+
+      // #when checking
+      const result = await auth.checkAuthProvider("openai")
+
+      // #then should skip
+      expect(result.status).toBe("skip")
+      expect(result.message).toContain("not installed")
+    })
+  })
+
+  describe("checkAnthropicAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking anthropic
+      const result = await auth.checkAnthropicAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("checkOpenAIAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking openai
+      const result = await auth.checkOpenAIAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("checkGoogleAuth", () => {
+    it("returns a check result", async () => {
+      // #given
+      // #when checking google
+      const result = await auth.checkGoogleAuth()
+
+      // #then should return valid result
+      expect(result.name).toBeDefined()
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+    })
+  })
+
+  describe("getAuthCheckDefinitions", () => {
+    it("returns definitions for all three providers", () => {
+      // #given
+      // #when getting definitions
+      const defs = auth.getAuthCheckDefinitions()
+
+      // #then should have 3 definitions
+      expect(defs.length).toBe(3)
+      expect(defs.every((d) => d.category === "authentication")).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/auth.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, AuthProviderInfo, AuthProviderId } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+
+const AUTH_PLUGINS: Record<AuthProviderId, { plugin: string; name: string }> = {
+  anthropic: { plugin: "builtin", name: "Anthropic (Claude)" },
+  openai: { plugin: "opencode-openai-codex-auth", name: "OpenAI (ChatGPT)" },
+  google: { plugin: "opencode-antigravity-auth", name: "Google (Gemini)" },
+}
+
+function getOpenCodeConfig(): { plugin?: string[] } | null {
+  const configPath = existsSync(OPENCODE_JSONC) ? OPENCODE_JSONC : OPENCODE_JSON
+  if (!existsSync(configPath)) return null
+
+  try {
+    const content = readFileSync(configPath, "utf-8")
+    return parseJsonc<{ plugin?: string[] }>(content)
+  } catch {
+    return null
+  }
+}
+
+function isPluginInstalled(plugins: string[], pluginName: string): boolean {
+  if (pluginName === "builtin") return true
+  return plugins.some((p) => p === pluginName || p.startsWith(`${pluginName}@`))
+}
+
+export function getAuthProviderInfo(providerId: AuthProviderId): AuthProviderInfo {
+  const config = getOpenCodeConfig()
+  const plugins = config?.plugin ?? []
+  const authConfig = AUTH_PLUGINS[providerId]
+
+  const pluginInstalled = isPluginInstalled(plugins, authConfig.plugin)
+
+  return {
+    id: providerId,
+    name: authConfig.name,
+    pluginInstalled,
+    configured: pluginInstalled,
+  }
+}
+
+export async function checkAuthProvider(providerId: AuthProviderId): Promise<CheckResult> {
+  const info = getAuthProviderInfo(providerId)
+  const checkId = `auth-${providerId}` as keyof typeof CHECK_NAMES
+  const checkName = CHECK_NAMES[checkId] || info.name
+
+  if (!info.pluginInstalled) {
+    return {
+      name: checkName,
+      status: "skip",
+      message: "Auth plugin not installed",
+      details: [
+        `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
+        "Run: bunx oh-my-opencode install",
+      ],
+    }
+  }
+
+  return {
+    name: checkName,
+    status: "pass",
+    message: "Auth plugin available",
+    details: [
+      providerId === "anthropic"
+        ? "Run: opencode auth login (select Anthropic)"
+        : `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
+    ],
+  }
+}
+
+export async function checkAnthropicAuth(): Promise<CheckResult> {
+  return checkAuthProvider("anthropic")
+}
+
+export async function checkOpenAIAuth(): Promise<CheckResult> {
+  return checkAuthProvider("openai")
+}
+
+export async function checkGoogleAuth(): Promise<CheckResult> {
+  return checkAuthProvider("google")
+}
+
+export function getAuthCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.AUTH_ANTHROPIC,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_ANTHROPIC],
+      category: "authentication",
+      check: checkAnthropicAuth,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.AUTH_OPENAI,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_OPENAI],
+      category: "authentication",
+      check: checkOpenAIAuth,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.AUTH_GOOGLE,
+      name: CHECK_NAMES[CHECK_IDS.AUTH_GOOGLE],
+      category: "authentication",
+      check: checkGoogleAuth,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/config.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as config from "./config"
+
+describe("config check", () => {
+  describe("validateConfig", () => {
+    it("returns valid: false for non-existent file", () => {
+      // #given non-existent file path
+      // #when validating
+      const result = config.validateConfig("/non/existent/path.json")
+
+      // #then should indicate invalid
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe("getConfigInfo", () => {
+    it("returns exists: false when no config found", () => {
+      // #given no config file exists
+      // #when getting config info
+      const info = config.getConfigInfo()
+
+      // #then should handle gracefully
+      expect(typeof info.exists).toBe("boolean")
+      expect(typeof info.valid).toBe("boolean")
+    })
+  })
+
+  describe("checkConfigValidity", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when no config exists (uses defaults)", async () => {
+      // #given no config file
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: false,
+        path: null,
+        format: null,
+        valid: true,
+        errors: [],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should pass with default message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("default")
+    })
+
+    it("returns pass when config is valid", async () => {
+      // #given valid config
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: true,
+        path: "/home/user/.config/opencode/oh-my-opencode.json",
+        format: "json",
+        valid: true,
+        errors: [],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("JSON")
+    })
+
+    it("returns fail when config has validation errors", async () => {
+      // #given invalid config
+      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
+        exists: true,
+        path: "/home/user/.config/opencode/oh-my-opencode.json",
+        format: "json",
+        valid: false,
+        errors: ["agents.oracle: Invalid model format"],
+      })
+
+      // #when checking validity
+      const result = await config.checkConfigValidity()
+
+      // #then should fail with errors
+      expect(result.status).toBe("fail")
+      expect(result.details?.some((d) => d.includes("Error"))).toBe(true)
+    })
+  })
+
+  describe("getConfigCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = config.getConfigCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("config-validation")
+      expect(def.category).toBe("configuration")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/config.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, ConfigInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
+import { parseJsonc, detectConfigFile } from "../../../shared"
+import { OhMyOpenCodeConfigSchema } from "../../../config"
+
+const USER_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const USER_CONFIG_BASE = join(USER_CONFIG_DIR, `${PACKAGE_NAME}`)
+const PROJECT_CONFIG_BASE = join(process.cwd(), ".opencode", PACKAGE_NAME)
+
+function findConfigPath(): { path: string; format: "json" | "jsonc" } | null {
+  const projectDetected = detectConfigFile(PROJECT_CONFIG_BASE)
+  if (projectDetected.format !== "none") {
+    return { path: projectDetected.path, format: projectDetected.format as "json" | "jsonc" }
+  }
+
+  const userDetected = detectConfigFile(USER_CONFIG_BASE)
+  if (userDetected.format !== "none") {
+    return { path: userDetected.path, format: userDetected.format as "json" | "jsonc" }
+  }
+
+  return null
+}
+
+export function validateConfig(configPath: string): { valid: boolean; errors: string[] } {
+  try {
+    const content = readFileSync(configPath, "utf-8")
+    const rawConfig = parseJsonc<Record<string, unknown>>(content)
+    const result = OhMyOpenCodeConfigSchema.safeParse(rawConfig)
+
+    if (!result.success) {
+      const errors = result.error.issues.map(
+        (i) => `${i.path.join(".")}: ${i.message}`
+      )
+      return { valid: false, errors }
+    }
+
+    return { valid: true, errors: [] }
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [err instanceof Error ? err.message : "Failed to parse config"],
+    }
+  }
+}
+
+export function getConfigInfo(): ConfigInfo {
+  const configPath = findConfigPath()
+
+  if (!configPath) {
+    return {
+      exists: false,
+      path: null,
+      format: null,
+      valid: true,
+      errors: [],
+    }
+  }
+
+  if (!existsSync(configPath.path)) {
+    return {
+      exists: false,
+      path: configPath.path,
+      format: configPath.format,
+      valid: true,
+      errors: [],
+    }
+  }
+
+  const validation = validateConfig(configPath.path)
+
+  return {
+    exists: true,
+    path: configPath.path,
+    format: configPath.format,
+    valid: validation.valid,
+    errors: validation.errors,
+  }
+}
+
+export async function checkConfigValidity(): Promise<CheckResult> {
+  const info = getConfigInfo()
+
+  if (!info.exists) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      status: "pass",
+      message: "Using default configuration",
+      details: ["No custom config file found (optional)"],
+    }
+  }
+
+  if (!info.valid) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      status: "fail",
+      message: "Configuration has validation errors",
+      details: [
+        `Path: ${info.path}`,
+        ...info.errors.map((e) => `Error: ${e}`),
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+    status: "pass",
+    message: `Valid ${info.format?.toUpperCase()} config`,
+    details: [`Path: ${info.path}`],
+  }
+}
+
+export function getConfigCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.CONFIG_VALIDATION,
+    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+    category: "configuration",
+    check: checkConfigValidity,
+    critical: false,
+  }
+}

src/cli/doctor/checks/dependencies.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as deps from "./dependencies"
+
+describe("dependencies check", () => {
+  describe("checkAstGrepCli", () => {
+    it("returns dependency info", async () => {
+      // #given
+      // #when checking ast-grep cli
+      const info = await deps.checkAstGrepCli()
+
+      // #then should return valid info
+      expect(info.name).toBe("AST-Grep CLI")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkAstGrepNapi", () => {
+    it("returns dependency info", () => {
+      // #given
+      // #when checking ast-grep napi
+      const info = deps.checkAstGrepNapi()
+
+      // #then should return valid info
+      expect(info.name).toBe("AST-Grep NAPI")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkCommentChecker", () => {
+    it("returns dependency info", async () => {
+      // #given
+      // #when checking comment checker
+      const info = await deps.checkCommentChecker()
+
+      // #then should return valid info
+      expect(info.name).toBe("Comment Checker")
+      expect(info.required).toBe(false)
+      expect(typeof info.installed).toBe("boolean")
+    })
+  })
+
+  describe("checkDependencyAstGrepCli", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns pass when installed", async () => {
+      // #given ast-grep installed
+      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
+        name: "AST-Grep CLI",
+        required: false,
+        installed: true,
+        version: "0.25.0",
+        path: "/usr/local/bin/sg",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepCli()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("0.25.0")
+    })
+
+    it("returns warn when not installed", async () => {
+      // #given ast-grep not installed
+      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
+        name: "AST-Grep CLI",
+        required: false,
+        installed: false,
+        version: null,
+        path: null,
+        installHint: "Install: npm install -g @ast-grep/cli",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepCli()
+
+      // #then should warn (optional)
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("optional")
+    })
+  })
+
+  describe("checkDependencyAstGrepNapi", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns pass when installed", async () => {
+      // #given napi installed
+      checkSpy = spyOn(deps, "checkAstGrepNapi").mockReturnValue({
+        name: "AST-Grep NAPI",
+        required: false,
+        installed: true,
+        version: null,
+        path: null,
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyAstGrepNapi()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+    })
+  })
+
+  describe("checkDependencyCommentChecker", () => {
+    let checkSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      checkSpy?.mockRestore()
+    })
+
+    it("returns warn when not installed", async () => {
+      // #given comment checker not installed
+      checkSpy = spyOn(deps, "checkCommentChecker").mockResolvedValue({
+        name: "Comment Checker",
+        required: false,
+        installed: false,
+        version: null,
+        path: null,
+        installHint: "Hook will be disabled if not available",
+      })
+
+      // #when checking
+      const result = await deps.checkDependencyCommentChecker()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+    })
+  })
+
+  describe("getDependencyCheckDefinitions", () => {
+    it("returns definitions for all dependencies", () => {
+      // #given
+      // #when getting definitions
+      const defs = deps.getDependencyCheckDefinitions()
+
+      // #then should have 3 definitions
+      expect(defs.length).toBe(3)
+      expect(defs.every((d) => d.category === "dependencies")).toBe(true)
+      expect(defs.every((d) => d.critical === false)).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/dependencies.ts

@@ -0,0 +1,163 @@
+import type { CheckResult, CheckDefinition, DependencyInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return { exists: true, path: output.trim() }
+    }
+  } catch {
+    // intentionally empty - binary not found
+  }
+  return { exists: false, path: null }
+}
+
+async function getBinaryVersion(binary: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([binary, "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return output.trim().split("\n")[0]
+    }
+  } catch {
+    // intentionally empty - version unavailable
+  }
+  return null
+}
+
+export async function checkAstGrepCli(): Promise<DependencyInfo> {
+  const binaryCheck = await checkBinaryExists("sg")
+  const altBinaryCheck = !binaryCheck.exists ? await checkBinaryExists("ast-grep") : null
+
+  const binary = binaryCheck.exists ? binaryCheck : altBinaryCheck
+  if (!binary || !binary.exists) {
+    return {
+      name: "AST-Grep CLI",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Install: npm install -g @ast-grep/cli",
+    }
+  }
+
+  const version = await getBinaryVersion(binary.path!)
+
+  return {
+    name: "AST-Grep CLI",
+    required: false,
+    installed: true,
+    version,
+    path: binary.path,
+  }
+}
+
+export function checkAstGrepNapi(): DependencyInfo {
+  try {
+    require.resolve("@ast-grep/napi")
+    return {
+      name: "AST-Grep NAPI",
+      required: false,
+      installed: true,
+      version: null,
+      path: null,
+    }
+  } catch {
+    return {
+      name: "AST-Grep NAPI",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Will use CLI fallback if available",
+    }
+  }
+}
+
+export async function checkCommentChecker(): Promise<DependencyInfo> {
+  const binaryCheck = await checkBinaryExists("comment-checker")
+
+  if (!binaryCheck.exists) {
+    return {
+      name: "Comment Checker",
+      required: false,
+      installed: false,
+      version: null,
+      path: null,
+      installHint: "Hook will be disabled if not available",
+    }
+  }
+
+  const version = await getBinaryVersion("comment-checker")
+
+  return {
+    name: "Comment Checker",
+    required: false,
+    installed: true,
+    version,
+    path: binaryCheck.path,
+  }
+}
+
+function dependencyToCheckResult(dep: DependencyInfo, checkName: string): CheckResult {
+  if (dep.installed) {
+    return {
+      name: checkName,
+      status: "pass",
+      message: dep.version ?? "installed",
+      details: dep.path ? [`Path: ${dep.path}`] : undefined,
+    }
+  }
+
+  return {
+    name: checkName,
+    status: "warn",
+    message: "Not installed (optional)",
+    details: dep.installHint ? [dep.installHint] : undefined,
+  }
+}
+
+export async function checkDependencyAstGrepCli(): Promise<CheckResult> {
+  const info = await checkAstGrepCli()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI])
+}
+
+export async function checkDependencyAstGrepNapi(): Promise<CheckResult> {
+  const info = checkAstGrepNapi()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI])
+}
+
+export async function checkDependencyCommentChecker(): Promise<CheckResult> {
+  const info = await checkCommentChecker()
+  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER])
+}
+
+export function getDependencyCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.DEP_AST_GREP_CLI,
+      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI],
+      category: "dependencies",
+      check: checkDependencyAstGrepCli,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.DEP_AST_GREP_NAPI,
+      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI],
+      category: "dependencies",
+      check: checkDependencyAstGrepNapi,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.DEP_COMMENT_CHECKER,
+      name: CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER],
+      category: "dependencies",
+      check: checkDependencyCommentChecker,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/gh.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as gh from "./gh"
+
+describe("gh cli check", () => {
+  describe("getGhCliInfo", () => {
+    it("returns gh cli info structure", async () => {
+      // #given
+      // #when checking gh cli info
+      const info = await gh.getGhCliInfo()
+
+      // #then should return valid info structure
+      expect(typeof info.installed).toBe("boolean")
+      expect(info.authenticated === true || info.authenticated === false).toBe(true)
+      expect(Array.isArray(info.scopes)).toBe(true)
+    })
+  })
+
+  describe("checkGhCli", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns warn when gh is not installed", async () => {
+      // #given gh not installed
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: false,
+        version: null,
+        path: null,
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn (optional)
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Not installed")
+      expect(result.details).toContain("Install: https://cli.github.com/")
+    })
+
+    it("returns warn when gh is installed but not authenticated", async () => {
+      // #given gh installed but not authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: false,
+        username: null,
+        scopes: [],
+        error: "not logged in",
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should warn about auth
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("not authenticated")
+      expect(result.details).toContain("Authenticate: gh auth login")
+    })
+
+    it("returns pass when gh is installed and authenticated", async () => {
+      // #given gh installed and authenticated
+      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
+        installed: true,
+        version: "2.40.0",
+        path: "/usr/local/bin/gh",
+        authenticated: true,
+        username: "octocat",
+        scopes: ["repo", "read:org"],
+        error: null,
+      })
+
+      // #when checking
+      const result = await gh.checkGhCli()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("2.40.0")
+      expect(result.message).toContain("octocat")
+      expect(result.details).toContain("Account: octocat")
+      expect(result.details).toContain("Scopes: repo, read:org")
+    })
+  })
+
+  describe("getGhCliCheckDefinition", () => {
+    it("returns correct check definition", () => {
+      // #given
+      // #when getting definition
+      const def = gh.getGhCliCheckDefinition()
+
+      // #then should have correct properties
+      expect(def.id).toBe("gh-cli")
+      expect(def.name).toBe("GitHub CLI")
+      expect(def.category).toBe("tools")
+      expect(def.critical).toBe(false)
+      expect(typeof def.check).toBe("function")
+    })
+  })
+})

src/cli/doctor/checks/gh.ts

@@ -0,0 +1,171 @@
+import type { CheckResult, CheckDefinition } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+export interface GhCliInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return { exists: true, path: output.trim() }
+    }
+  } catch {
+    // intentionally empty - binary not found
+  }
+  return { exists: false, path: null }
+}
+
+async function getGhVersion(): Promise<string | null> {
+  try {
+    const proc = Bun.spawn(["gh", "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      const match = output.match(/gh version (\S+)/)
+      return match?.[1] ?? output.trim().split("\n")[0]
+    }
+  } catch {
+    // intentionally empty - version unavailable
+  }
+  return null
+}
+
+async function getGhAuthStatus(): Promise<{
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}> {
+  try {
+    const proc = Bun.spawn(["gh", "auth", "status"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GH_NO_UPDATE_NOTIFIER: "1" },
+    })
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    await proc.exited
+
+    const output = stderr || stdout
+
+    if (proc.exitCode === 0) {
+      const usernameMatch = output.match(/Logged in to github\.com account (\S+)/)
+      const username = usernameMatch?.[1]?.replace(/[()]/g, "") ?? null
+
+      const scopesMatch = output.match(/Token scopes?:\s*(.+)/i)
+      const scopes = scopesMatch?.[1]
+        ? scopesMatch[1]
+            .split(/,\s*/)
+            .map((s) => s.replace(/['"]/g, "").trim())
+            .filter(Boolean)
+        : []
+
+      return { authenticated: true, username, scopes, error: null }
+    }
+
+    const errorMatch = output.match(/error[:\s]+(.+)/i)
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: errorMatch?.[1]?.trim() ?? "Not authenticated",
+    }
+  } catch (err) {
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: err instanceof Error ? err.message : "Failed to check auth status",
+    }
+  }
+}
+
+export async function getGhCliInfo(): Promise<GhCliInfo> {
+  const binaryCheck = await checkBinaryExists("gh")
+
+  if (!binaryCheck.exists) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: null,
+    }
+  }
+
+  const [version, authStatus] = await Promise.all([getGhVersion(), getGhAuthStatus()])
+
+  return {
+    installed: true,
+    version,
+    path: binaryCheck.path,
+    authenticated: authStatus.authenticated,
+    username: authStatus.username,
+    scopes: authStatus.scopes,
+    error: authStatus.error,
+  }
+}
+
+export async function checkGhCli(): Promise<CheckResult> {
+  const info = await getGhCliInfo()
+  const name = CHECK_NAMES[CHECK_IDS.GH_CLI]
+
+  if (!info.installed) {
+    return {
+      name,
+      status: "warn",
+      message: "Not installed (optional)",
+      details: [
+        "GitHub CLI is used by librarian agent and scripts",
+        "Install: https://cli.github.com/",
+      ],
+    }
+  }
+
+  if (!info.authenticated) {
+    return {
+      name,
+      status: "warn",
+      message: `${info.version ?? "installed"} - not authenticated`,
+      details: [
+        info.path ? `Path: ${info.path}` : null,
+        "Authenticate: gh auth login",
+        info.error ? `Error: ${info.error}` : null,
+      ].filter((d): d is string => d !== null),
+    }
+  }
+
+  const details: string[] = []
+  if (info.path) details.push(`Path: ${info.path}`)
+  if (info.username) details.push(`Account: ${info.username}`)
+  if (info.scopes.length > 0) details.push(`Scopes: ${info.scopes.join(", ")}`)
+
+  return {
+    name,
+    status: "pass",
+    message: `${info.version ?? "installed"} - authenticated as ${info.username ?? "unknown"}`,
+    details: details.length > 0 ? details : undefined,
+  }
+}
+
+export function getGhCliCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.GH_CLI,
+    name: CHECK_NAMES[CHECK_IDS.GH_CLI],
+    category: "tools",
+    check: checkGhCli,
+    critical: false,
+  }
+}

src/cli/doctor/checks/index.ts

@@ -0,0 +1,34 @@
+import type { CheckDefinition } from "../types"
+import { getOpenCodeCheckDefinition } from "./opencode"
+import { getPluginCheckDefinition } from "./plugin"
+import { getConfigCheckDefinition } from "./config"
+import { getAuthCheckDefinitions } from "./auth"
+import { getDependencyCheckDefinitions } from "./dependencies"
+import { getGhCliCheckDefinition } from "./gh"
+import { getLspCheckDefinition } from "./lsp"
+import { getMcpCheckDefinitions } from "./mcp"
+import { getVersionCheckDefinition } from "./version"
+
+export * from "./opencode"
+export * from "./plugin"
+export * from "./config"
+export * from "./auth"
+export * from "./dependencies"
+export * from "./gh"
+export * from "./lsp"
+export * from "./mcp"
+export * from "./version"
+
+export function getAllCheckDefinitions(): CheckDefinition[] {
+  return [
+    getOpenCodeCheckDefinition(),
+    getPluginCheckDefinition(),
+    getConfigCheckDefinition(),
+    ...getAuthCheckDefinitions(),
+    ...getDependencyCheckDefinitions(),
+    getGhCliCheckDefinition(),
+    getLspCheckDefinition(),
+    ...getMcpCheckDefinitions(),
+    getVersionCheckDefinition(),
+  ]
+}

src/cli/doctor/checks/lsp.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as lsp from "./lsp"
+import type { LspServerInfo } from "../types"
+
+describe("lsp check", () => {
+  describe("getLspServersInfo", () => {
+    it("returns array of server info", async () => {
+      // #given
+      // #when getting servers info
+      const servers = await lsp.getLspServersInfo()
+
+      // #then should return array with expected structure
+      expect(Array.isArray(servers)).toBe(true)
+      servers.forEach((s) => {
+        expect(s.id).toBeDefined()
+        expect(typeof s.installed).toBe("boolean")
+        expect(Array.isArray(s.extensions)).toBe(true)
+      })
+    })
+  })
+
+  describe("getLspServerStats", () => {
+    it("counts installed servers correctly", () => {
+      // #given servers with mixed installation status
+      const servers = [
+        { id: "ts", installed: true, extensions: [".ts"], source: "builtin" as const },
+        { id: "py", installed: false, extensions: [".py"], source: "builtin" as const },
+        { id: "go", installed: true, extensions: [".go"], source: "builtin" as const },
+      ]
+
+      // #when getting stats
+      const stats = lsp.getLspServerStats(servers)
+
+      // #then should count correctly
+      expect(stats.installed).toBe(2)
+      expect(stats.total).toBe(3)
+    })
+
+    it("handles empty array", () => {
+      // #given no servers
+      const servers: LspServerInfo[] = []
+
+      // #when getting stats
+      const stats = lsp.getLspServerStats(servers)
+
+      // #then should return zeros
+      expect(stats.installed).toBe(0)
+      expect(stats.total).toBe(0)
+    })
+  })
+
+  describe("checkLspServers", () => {
+    let getServersSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getServersSpy?.mockRestore()
+    })
+
+    it("returns warn when no servers installed", async () => {
+      // #given no servers installed
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: false, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("No LSP servers")
+    })
+
+    it("returns pass when servers installed", async () => {
+      // #given some servers installed
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should pass with count
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1/2")
+    })
+
+    it("lists installed and missing servers in details", async () => {
+      // #given mixed installation
+      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
+        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
+        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
+      ])
+
+      // #when checking
+      const result = await lsp.checkLspServers()
+
+      // #then should list both
+      expect(result.details?.some((d) => d.includes("Installed"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("Not found"))).toBe(true)
+    })
+  })
+
+  describe("getLspCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = lsp.getLspCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("lsp-servers")
+      expect(def.category).toBe("tools")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/lsp.ts

@@ -0,0 +1,85 @@
+import type { CheckResult, CheckDefinition, LspServerInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+
+const DEFAULT_LSP_SERVERS: Array<{
+  id: string
+  binary: string
+  extensions: string[]
+}> = [
+  { id: "typescript-language-server", binary: "typescript-language-server", extensions: [".ts", ".tsx", ".js", ".jsx"] },
+  { id: "pyright", binary: "pyright-langserver", extensions: [".py"] },
+  { id: "rust-analyzer", binary: "rust-analyzer", extensions: [".rs"] },
+  { id: "gopls", binary: "gopls", extensions: [".go"] },
+]
+
+async function checkBinaryExists(binary: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+    await proc.exited
+    return proc.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+export async function getLspServersInfo(): Promise<LspServerInfo[]> {
+  const servers: LspServerInfo[] = []
+
+  for (const server of DEFAULT_LSP_SERVERS) {
+    const installed = await checkBinaryExists(server.binary)
+    servers.push({
+      id: server.id,
+      installed,
+      extensions: server.extensions,
+      source: "builtin",
+    })
+  }
+
+  return servers
+}
+
+export function getLspServerStats(servers: LspServerInfo[]): { installed: number; total: number } {
+  const installed = servers.filter((s) => s.installed).length
+  return { installed, total: servers.length }
+}
+
+export async function checkLspServers(): Promise<CheckResult> {
+  const servers = await getLspServersInfo()
+  const stats = getLspServerStats(servers)
+  const installedServers = servers.filter((s) => s.installed)
+  const missingServers = servers.filter((s) => !s.installed)
+
+  if (stats.installed === 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+      status: "warn",
+      message: "No LSP servers detected",
+      details: [
+        "LSP tools will have limited functionality",
+        ...missingServers.map((s) => `Missing: ${s.id}`),
+      ],
+    }
+  }
+
+  const details = [
+    ...installedServers.map((s) => `Installed: ${s.id}`),
+    ...missingServers.map((s) => `Not found: ${s.id} (optional)`),
+  ]
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+    status: "pass",
+    message: `${stats.installed}/${stats.total} servers available`,
+    details,
+  }
+}
+
+export function getLspCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.LSP_SERVERS,
+    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
+    category: "tools",
+    check: checkLspServers,
+    critical: false,
+  }
+}

src/cli/doctor/checks/mcp.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as mcp from "./mcp"
+
+describe("mcp check", () => {
+  describe("getBuiltinMcpInfo", () => {
+    it("returns builtin servers", () => {
+      // #given
+      // #when getting builtin info
+      const servers = mcp.getBuiltinMcpInfo()
+
+      // #then should include expected servers
+      expect(servers.length).toBe(3)
+      expect(servers.every((s) => s.type === "builtin")).toBe(true)
+      expect(servers.every((s) => s.enabled === true)).toBe(true)
+      expect(servers.map((s) => s.id)).toContain("context7")
+      expect(servers.map((s) => s.id)).toContain("websearch_exa")
+      expect(servers.map((s) => s.id)).toContain("grep_app")
+    })
+  })
+
+  describe("getUserMcpInfo", () => {
+    it("returns empty array when no user config", () => {
+      // #given no user config exists
+      // #when getting user info
+      const servers = mcp.getUserMcpInfo()
+
+      // #then should return array (may be empty)
+      expect(Array.isArray(servers)).toBe(true)
+    })
+  })
+
+  describe("checkBuiltinMcpServers", () => {
+    it("returns pass with server count", async () => {
+      // #given
+      // #when checking builtin servers
+      const result = await mcp.checkBuiltinMcpServers()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("3")
+      expect(result.message).toContain("enabled")
+    })
+
+    it("lists enabled servers in details", async () => {
+      // #given
+      // #when checking builtin servers
+      const result = await mcp.checkBuiltinMcpServers()
+
+      // #then should list servers
+      expect(result.details?.some((d) => d.includes("context7"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("websearch_exa"))).toBe(true)
+      expect(result.details?.some((d) => d.includes("grep_app"))).toBe(true)
+    })
+  })
+
+  describe("checkUserMcpServers", () => {
+    let getUserSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getUserSpy?.mockRestore()
+    })
+
+    it("returns skip when no user config", async () => {
+      // #given no user servers
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should skip
+      expect(result.status).toBe("skip")
+      expect(result.message).toContain("No user MCP")
+    })
+
+    it("returns pass when valid user servers", async () => {
+      // #given valid user servers
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
+        { id: "custom-mcp", type: "user", enabled: true, valid: true },
+      ])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1")
+    })
+
+    it("returns warn when servers have issues", async () => {
+      // #given invalid server config
+      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
+        { id: "bad-mcp", type: "user", enabled: true, valid: false, error: "Missing command" },
+      ])
+
+      // #when checking
+      const result = await mcp.checkUserMcpServers()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.details?.some((d) => d.includes("Invalid"))).toBe(true)
+    })
+  })
+
+  describe("getMcpCheckDefinitions", () => {
+    it("returns definitions for builtin and user", () => {
+      // #given
+      // #when getting definitions
+      const defs = mcp.getMcpCheckDefinitions()
+
+      // #then should have 2 definitions
+      expect(defs.length).toBe(2)
+      expect(defs.every((d) => d.category === "tools")).toBe(true)
+      expect(defs.map((d) => d.id)).toContain("mcp-builtin")
+      expect(defs.map((d) => d.id)).toContain("mcp-user")
+    })
+  })
+})

src/cli/doctor/checks/mcp.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, McpServerInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const BUILTIN_MCP_SERVERS = ["context7", "websearch_exa", "grep_app"]
+
+const MCP_CONFIG_PATHS = [
+  join(homedir(), ".claude", ".mcp.json"),
+  join(process.cwd(), ".mcp.json"),
+  join(process.cwd(), ".claude", ".mcp.json"),
+]
+
+interface McpConfig {
+  mcpServers?: Record<string, unknown>
+}
+
+function loadUserMcpConfig(): Record<string, unknown> {
+  const servers: Record<string, unknown> = {}
+
+  for (const configPath of MCP_CONFIG_PATHS) {
+    if (!existsSync(configPath)) continue
+
+    try {
+      const content = readFileSync(configPath, "utf-8")
+      const config = parseJsonc<McpConfig>(content)
+      if (config.mcpServers) {
+        Object.assign(servers, config.mcpServers)
+      }
+    } catch {
+      // intentionally empty - skip invalid configs
+    }
+  }
+
+  return servers
+}
+
+export function getBuiltinMcpInfo(): McpServerInfo[] {
+  return BUILTIN_MCP_SERVERS.map((id) => ({
+    id,
+    type: "builtin" as const,
+    enabled: true,
+    valid: true,
+  }))
+}
+
+export function getUserMcpInfo(): McpServerInfo[] {
+  const userServers = loadUserMcpConfig()
+  const servers: McpServerInfo[] = []
+
+  for (const [id, config] of Object.entries(userServers)) {
+    const isValid = typeof config === "object" && config !== null
+    servers.push({
+      id,
+      type: "user",
+      enabled: true,
+      valid: isValid,
+      error: isValid ? undefined : "Invalid configuration format",
+    })
+  }
+
+  return servers
+}
+
+export async function checkBuiltinMcpServers(): Promise<CheckResult> {
+  const servers = getBuiltinMcpInfo()
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
+    status: "pass",
+    message: `${servers.length} built-in servers enabled`,
+    details: servers.map((s) => `Enabled: ${s.id}`),
+  }
+}
+
+export async function checkUserMcpServers(): Promise<CheckResult> {
+  const servers = getUserMcpInfo()
+
+  if (servers.length === 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      status: "skip",
+      message: "No user MCP configuration found",
+      details: ["Optional: Add .mcp.json for custom MCP servers"],
+    }
+  }
+
+  const invalidServers = servers.filter((s) => !s.valid)
+  if (invalidServers.length > 0) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      status: "warn",
+      message: `${invalidServers.length} server(s) have configuration issues`,
+      details: [
+        ...servers.filter((s) => s.valid).map((s) => `Valid: ${s.id}`),
+        ...invalidServers.map((s) => `Invalid: ${s.id} - ${s.error}`),
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+    status: "pass",
+    message: `${servers.length} user server(s) configured`,
+    details: servers.map((s) => `Configured: ${s.id}`),
+  }
+}
+
+export function getMcpCheckDefinitions(): CheckDefinition[] {
+  return [
+    {
+      id: CHECK_IDS.MCP_BUILTIN,
+      name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
+      category: "tools",
+      check: checkBuiltinMcpServers,
+      critical: false,
+    },
+    {
+      id: CHECK_IDS.MCP_USER,
+      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
+      category: "tools",
+      check: checkUserMcpServers,
+      critical: false,
+    },
+  ]
+}

src/cli/doctor/checks/opencode.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, spyOn, beforeEach, afterEach } from "bun:test"
+import * as opencode from "./opencode"
+import { MIN_OPENCODE_VERSION } from "../constants"
+
+describe("opencode check", () => {
+  describe("compareVersions", () => {
+    it("returns true when current >= minimum", () => {
+      // #given versions where current is greater
+      // #when comparing
+      // #then should return true
+      expect(opencode.compareVersions("1.0.200", "1.0.150")).toBe(true)
+      expect(opencode.compareVersions("1.1.0", "1.0.150")).toBe(true)
+      expect(opencode.compareVersions("2.0.0", "1.0.150")).toBe(true)
+    })
+
+    it("returns true when versions are equal", () => {
+      // #given equal versions
+      // #when comparing
+      // #then should return true
+      expect(opencode.compareVersions("1.0.150", "1.0.150")).toBe(true)
+    })
+
+    it("returns false when current < minimum", () => {
+      // #given version below minimum
+      // #when comparing
+      // #then should return false
+      expect(opencode.compareVersions("1.0.100", "1.0.150")).toBe(false)
+      expect(opencode.compareVersions("0.9.0", "1.0.150")).toBe(false)
+    })
+
+    it("handles version prefixes", () => {
+      // #given version with v prefix
+      // #when comparing
+      // #then should strip prefix and compare correctly
+      expect(opencode.compareVersions("v1.0.200", "1.0.150")).toBe(true)
+    })
+
+    it("handles prerelease versions", () => {
+      // #given prerelease version
+      // #when comparing
+      // #then should use base version
+      expect(opencode.compareVersions("1.0.200-beta.1", "1.0.150")).toBe(true)
+    })
+  })
+
+  describe("getOpenCodeInfo", () => {
+    it("returns installed: false when binary not found", async () => {
+      // #given no opencode binary
+      const spy = spyOn(opencode, "findOpenCodeBinary").mockResolvedValue(null)
+
+      // #when getting info
+      const info = await opencode.getOpenCodeInfo()
+
+      // #then should indicate not installed
+      expect(info.installed).toBe(false)
+      expect(info.version).toBeNull()
+      expect(info.path).toBeNull()
+      expect(info.binary).toBeNull()
+
+      spy.mockRestore()
+    })
+  })
+
+  describe("checkOpenCodeInstallation", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns fail when not installed", async () => {
+      // #given opencode not installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: false,
+        version: null,
+        path: null,
+        binary: null,
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should fail with installation hint
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not installed")
+      expect(result.details).toBeDefined()
+      expect(result.details?.some((d) => d.includes("opencode.ai"))).toBe(true)
+    })
+
+    it("returns warn when version below minimum", async () => {
+      // #given old version installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: true,
+        version: "1.0.100",
+        path: "/usr/local/bin/opencode",
+        binary: "opencode",
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should warn about old version
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("below minimum")
+      expect(result.details?.some((d) => d.includes(MIN_OPENCODE_VERSION))).toBe(true)
+    })
+
+    it("returns pass when properly installed", async () => {
+      // #given current version installed
+      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
+        installed: true,
+        version: "1.0.200",
+        path: "/usr/local/bin/opencode",
+        binary: "opencode",
+      })
+
+      // #when checking installation
+      const result = await opencode.checkOpenCodeInstallation()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("1.0.200")
+    })
+  })
+
+  describe("getOpenCodeCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = opencode.getOpenCodeCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("opencode-installation")
+      expect(def.category).toBe("installation")
+      expect(def.critical).toBe(true)
+      expect(typeof def.check).toBe("function")
+    })
+  })
+})

src/cli/doctor/checks/opencode.ts

@@ -0,0 +1,118 @@
+import type { CheckResult, CheckDefinition, OpenCodeInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, MIN_OPENCODE_VERSION, OPENCODE_BINARIES } from "../constants"
+
+export async function findOpenCodeBinary(): Promise<{ binary: string; path: string } | null> {
+  for (const binary of OPENCODE_BINARIES) {
+    try {
+      const proc = Bun.spawn(["which", binary], { stdout: "pipe", stderr: "pipe" })
+      const output = await new Response(proc.stdout).text()
+      await proc.exited
+      if (proc.exitCode === 0) {
+        return { binary, path: output.trim() }
+      }
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
+export async function getOpenCodeVersion(binary: string): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([binary, "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(proc.stdout).text()
+    await proc.exited
+    if (proc.exitCode === 0) {
+      return output.trim()
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+export function compareVersions(current: string, minimum: string): boolean {
+  const parseVersion = (v: string): number[] => {
+    const cleaned = v.replace(/^v/, "").split("-")[0]
+    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
+  }
+
+  const curr = parseVersion(current)
+  const min = parseVersion(minimum)
+
+  for (let i = 0; i < Math.max(curr.length, min.length); i++) {
+    const c = curr[i] ?? 0
+    const m = min[i] ?? 0
+    if (c > m) return true
+    if (c < m) return false
+  }
+  return true
+}
+
+export async function getOpenCodeInfo(): Promise<OpenCodeInfo> {
+  const binaryInfo = await findOpenCodeBinary()
+
+  if (!binaryInfo) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      binary: null,
+    }
+  }
+
+  const version = await getOpenCodeVersion(binaryInfo.binary)
+
+  return {
+    installed: true,
+    version,
+    path: binaryInfo.path,
+    binary: binaryInfo.binary as "opencode" | "opencode-desktop",
+  }
+}
+
+export async function checkOpenCodeInstallation(): Promise<CheckResult> {
+  const info = await getOpenCodeInfo()
+
+  if (!info.installed) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+      status: "fail",
+      message: "OpenCode is not installed",
+      details: [
+        "Visit: https://opencode.ai/docs for installation instructions",
+        "Run: npm install -g opencode",
+      ],
+    }
+  }
+
+  if (info.version && !compareVersions(info.version, MIN_OPENCODE_VERSION)) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+      status: "warn",
+      message: `Version ${info.version} is below minimum ${MIN_OPENCODE_VERSION}`,
+      details: [
+        `Current: ${info.version}`,
+        `Required: >= ${MIN_OPENCODE_VERSION}`,
+        "Run: npm update -g opencode",
+      ],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+    status: "pass",
+    message: info.version ?? "installed",
+    details: info.path ? [`Path: ${info.path}`] : undefined,
+  }
+}
+
+export function getOpenCodeCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.OPENCODE_INSTALLATION,
+    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
+    category: "installation",
+    check: checkOpenCodeInstallation,
+    critical: true,
+  }
+}

src/cli/doctor/checks/plugin.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as plugin from "./plugin"
+
+describe("plugin check", () => {
+  describe("getPluginInfo", () => {
+    it("returns registered: false when config not found", () => {
+      // #given no config file exists
+      // #when getting plugin info
+      // #then should indicate not registered
+      const info = plugin.getPluginInfo()
+      expect(typeof info.registered).toBe("boolean")
+      expect(typeof info.isPinned).toBe("boolean")
+    })
+  })
+
+  describe("checkPluginRegistration", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns fail when config file not found", async () => {
+      // #given no config file
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: false,
+        configPath: null,
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should fail with hint
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not found")
+    })
+
+    it("returns fail when plugin not registered", async () => {
+      // #given config exists but plugin not registered
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: false,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should fail
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("not registered")
+    })
+
+    it("returns pass when plugin registered", async () => {
+      // #given plugin registered
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: true,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: "oh-my-opencode",
+        isPinned: false,
+        pinnedVersion: null,
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Registered")
+    })
+
+    it("indicates pinned version when applicable", async () => {
+      // #given plugin pinned to version
+      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
+        registered: true,
+        configPath: "/home/user/.config/opencode/opencode.json",
+        entry: "oh-my-opencode@2.7.0",
+        isPinned: true,
+        pinnedVersion: "2.7.0",
+      })
+
+      // #when checking registration
+      const result = await plugin.checkPluginRegistration()
+
+      // #then should show pinned version
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("pinned")
+      expect(result.message).toContain("2.7.0")
+    })
+  })
+
+  describe("getPluginCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = plugin.getPluginCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("plugin-registration")
+      expect(def.category).toBe("installation")
+      expect(def.critical).toBe(true)
+    })
+  })
+})

src/cli/doctor/checks/plugin.ts

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import type { CheckResult, CheckDefinition, PluginInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
+import { parseJsonc } from "../../../shared"
+
+const OPENCODE_CONFIG_DIR = join(homedir(), ".config", "opencode")
+const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
+
+function detectConfigPath(): { path: string; format: "json" | "jsonc" } | null {
+  if (existsSync(OPENCODE_JSONC)) {
+    return { path: OPENCODE_JSONC, format: "jsonc" }
+  }
+  if (existsSync(OPENCODE_JSON)) {
+    return { path: OPENCODE_JSON, format: "json" }
+  }
+  return null
+}
+
+function findPluginEntry(plugins: string[]): { entry: string; isPinned: boolean; version: string | null } | null {
+  for (const plugin of plugins) {
+    if (plugin === PACKAGE_NAME || plugin.startsWith(`${PACKAGE_NAME}@`)) {
+      const isPinned = plugin.includes("@")
+      const version = isPinned ? plugin.split("@")[1] : null
+      return { entry: plugin, isPinned, version }
+    }
+  }
+  return null
+}
+
+export function getPluginInfo(): PluginInfo {
+  const configInfo = detectConfigPath()
+
+  if (!configInfo) {
+    return {
+      registered: false,
+      configPath: null,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+    }
+  }
+
+  try {
+    const content = readFileSync(configInfo.path, "utf-8")
+    const config = parseJsonc<{ plugin?: string[] }>(content)
+    const plugins = config.plugin ?? []
+    const pluginEntry = findPluginEntry(plugins)
+
+    if (!pluginEntry) {
+      return {
+        registered: false,
+        configPath: configInfo.path,
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+      }
+    }
+
+    return {
+      registered: true,
+      configPath: configInfo.path,
+      entry: pluginEntry.entry,
+      isPinned: pluginEntry.isPinned,
+      pinnedVersion: pluginEntry.version,
+    }
+  } catch {
+    return {
+      registered: false,
+      configPath: configInfo.path,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+    }
+  }
+}
+
+export async function checkPluginRegistration(): Promise<CheckResult> {
+  const info = getPluginInfo()
+
+  if (!info.configPath) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+      status: "fail",
+      message: "OpenCode config file not found",
+      details: [
+        "Run: bunx oh-my-opencode install",
+        `Expected: ${OPENCODE_JSON} or ${OPENCODE_JSONC}`,
+      ],
+    }
+  }
+
+  if (!info.registered) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+      status: "fail",
+      message: "Plugin not registered in config",
+      details: [
+        "Run: bunx oh-my-opencode install",
+        `Config: ${info.configPath}`,
+      ],
+    }
+  }
+
+  const message = info.isPinned
+    ? `Registered (pinned: ${info.pinnedVersion})`
+    : "Registered"
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+    status: "pass",
+    message,
+    details: [`Config: ${info.configPath}`],
+  }
+}
+
+export function getPluginCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.PLUGIN_REGISTRATION,
+    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
+    category: "installation",
+    check: checkPluginRegistration,
+    critical: true,
+  }
+}

src/cli/doctor/checks/version.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import * as version from "./version"
+
+describe("version check", () => {
+  describe("getVersionInfo", () => {
+    it("returns version check info structure", async () => {
+      // #given
+      // #when getting version info
+      const info = await version.getVersionInfo()
+
+      // #then should have expected structure
+      expect(typeof info.isUpToDate).toBe("boolean")
+      expect(typeof info.isLocalDev).toBe("boolean")
+      expect(typeof info.isPinned).toBe("boolean")
+    })
+  })
+
+  describe("checkVersionStatus", () => {
+    let getInfoSpy: ReturnType<typeof spyOn>
+
+    afterEach(() => {
+      getInfoSpy?.mockRestore()
+    })
+
+    it("returns pass when in local dev mode", async () => {
+      // #given local dev mode
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "local-dev",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: true,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass with dev message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("local development")
+    })
+
+    it("returns pass when pinned", async () => {
+      // #given pinned version
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: true,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass with pinned message
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Pinned")
+    })
+
+    it("returns warn when unable to determine version", async () => {
+      // #given no version info
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: null,
+        latestVersion: "2.7.0",
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Unable to determine")
+    })
+
+    it("returns warn when network error", async () => {
+      // #given network error
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: null,
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn
+      expect(result.status).toBe("warn")
+      expect(result.details?.some((d) => d.includes("network"))).toBe(true)
+    })
+
+    it("returns warn when update available", async () => {
+      // #given update available
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.6.0",
+        latestVersion: "2.7.0",
+        isUpToDate: false,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should warn with update info
+      expect(result.status).toBe("warn")
+      expect(result.message).toContain("Update available")
+      expect(result.message).toContain("2.6.0")
+      expect(result.message).toContain("2.7.0")
+    })
+
+    it("returns pass when up to date", async () => {
+      // #given up to date
+      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
+        currentVersion: "2.7.0",
+        latestVersion: "2.7.0",
+        isUpToDate: true,
+        isLocalDev: false,
+        isPinned: false,
+      })
+
+      // #when checking
+      const result = await version.checkVersionStatus()
+
+      // #then should pass
+      expect(result.status).toBe("pass")
+      expect(result.message).toContain("Up to date")
+    })
+  })
+
+  describe("getVersionCheckDefinition", () => {
+    it("returns valid check definition", () => {
+      // #given
+      // #when getting definition
+      const def = version.getVersionCheckDefinition()
+
+      // #then should have required properties
+      expect(def.id).toBe("version-status")
+      expect(def.category).toBe("updates")
+      expect(def.critical).toBe(false)
+    })
+  })
+})

src/cli/doctor/checks/version.ts

@@ -0,0 +1,133 @@
+import type { CheckResult, CheckDefinition, VersionCheckInfo } from "../types"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import {
+  getCachedVersion,
+  getLatestVersion,
+  isLocalDevMode,
+  findPluginEntry,
+} from "../../../hooks/auto-update-checker/checker"
+
+function compareVersions(current: string, latest: string): boolean {
+  const parseVersion = (v: string): number[] => {
+    const cleaned = v.replace(/^v/, "").split("-")[0]
+    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
+  }
+
+  const curr = parseVersion(current)
+  const lat = parseVersion(latest)
+
+  for (let i = 0; i < Math.max(curr.length, lat.length); i++) {
+    const c = curr[i] ?? 0
+    const l = lat[i] ?? 0
+    if (c < l) return false
+    if (c > l) return true
+  }
+  return true
+}
+
+export async function getVersionInfo(): Promise<VersionCheckInfo> {
+  const cwd = process.cwd()
+
+  if (isLocalDevMode(cwd)) {
+    return {
+      currentVersion: "local-dev",
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: true,
+      isPinned: false,
+    }
+  }
+
+  const pluginInfo = findPluginEntry(cwd)
+  if (pluginInfo?.isPinned) {
+    return {
+      currentVersion: pluginInfo.pinnedVersion,
+      latestVersion: null,
+      isUpToDate: true,
+      isLocalDev: false,
+      isPinned: true,
+    }
+  }
+
+  const currentVersion = getCachedVersion()
+  const latestVersion = await getLatestVersion()
+
+  const isUpToDate =
+    !currentVersion ||
+    !latestVersion ||
+    compareVersions(currentVersion, latestVersion)
+
+  return {
+    currentVersion,
+    latestVersion,
+    isUpToDate,
+    isLocalDev: false,
+    isPinned: false,
+  }
+}
+
+export async function checkVersionStatus(): Promise<CheckResult> {
+  const info = await getVersionInfo()
+
+  if (info.isLocalDev) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "pass",
+      message: "Running in local development mode",
+      details: ["Using file:// protocol from config"],
+    }
+  }
+
+  if (info.isPinned) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "pass",
+      message: `Pinned to version ${info.currentVersion}`,
+      details: ["Update check skipped for pinned versions"],
+    }
+  }
+
+  if (!info.currentVersion) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: "Unable to determine current version",
+      details: ["Run: bunx oh-my-opencode get-local-version"],
+    }
+  }
+
+  if (!info.latestVersion) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: `Current: ${info.currentVersion}`,
+      details: ["Unable to check for updates (network error)"],
+    }
+  }
+
+  if (!info.isUpToDate) {
+    return {
+      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+      status: "warn",
+      message: `Update available: ${info.currentVersion} -> ${info.latestVersion}`,
+      details: ["Run: cd ~/.config/opencode && bun update oh-my-opencode"],
+    }
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+    status: "pass",
+    message: `Up to date (${info.currentVersion})`,
+    details: info.latestVersion ? [`Latest: ${info.latestVersion}`] : undefined,
+  }
+}
+
+export function getVersionCheckDefinition(): CheckDefinition {
+  return {
+    id: CHECK_IDS.VERSION_STATUS,
+    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
+    category: "updates",
+    check: checkVersionStatus,
+    critical: false,
+  }
+}

src/cli/doctor/constants.ts

@@ -0,0 +1,72 @@
+import color from "picocolors"
+
+export const SYMBOLS = {
+  check: color.green("\u2713"),
+  cross: color.red("\u2717"),
+  warn: color.yellow("\u26A0"),
+  info: color.blue("\u2139"),
+  arrow: color.cyan("\u2192"),
+  bullet: color.dim("\u2022"),
+  skip: color.dim("\u25CB"),
+} as const
+
+export const STATUS_COLORS = {
+  pass: color.green,
+  fail: color.red,
+  warn: color.yellow,
+  skip: color.dim,
+} as const
+
+export const CHECK_IDS = {
+  OPENCODE_INSTALLATION: "opencode-installation",
+  PLUGIN_REGISTRATION: "plugin-registration",
+  CONFIG_VALIDATION: "config-validation",
+  AUTH_ANTHROPIC: "auth-anthropic",
+  AUTH_OPENAI: "auth-openai",
+  AUTH_GOOGLE: "auth-google",
+  DEP_AST_GREP_CLI: "dep-ast-grep-cli",
+  DEP_AST_GREP_NAPI: "dep-ast-grep-napi",
+  DEP_COMMENT_CHECKER: "dep-comment-checker",
+  GH_CLI: "gh-cli",
+  LSP_SERVERS: "lsp-servers",
+  MCP_BUILTIN: "mcp-builtin",
+  MCP_USER: "mcp-user",
+  VERSION_STATUS: "version-status",
+} as const
+
+export const CHECK_NAMES: Record<string, string> = {
+  [CHECK_IDS.OPENCODE_INSTALLATION]: "OpenCode Installation",
+  [CHECK_IDS.PLUGIN_REGISTRATION]: "Plugin Registration",
+  [CHECK_IDS.CONFIG_VALIDATION]: "Configuration Validity",
+  [CHECK_IDS.AUTH_ANTHROPIC]: "Anthropic (Claude) Auth",
+  [CHECK_IDS.AUTH_OPENAI]: "OpenAI (ChatGPT) Auth",
+  [CHECK_IDS.AUTH_GOOGLE]: "Google (Gemini) Auth",
+  [CHECK_IDS.DEP_AST_GREP_CLI]: "AST-Grep CLI",
+  [CHECK_IDS.DEP_AST_GREP_NAPI]: "AST-Grep NAPI",
+  [CHECK_IDS.DEP_COMMENT_CHECKER]: "Comment Checker",
+  [CHECK_IDS.GH_CLI]: "GitHub CLI",
+  [CHECK_IDS.LSP_SERVERS]: "LSP Servers",
+  [CHECK_IDS.MCP_BUILTIN]: "Built-in MCP Servers",
+  [CHECK_IDS.MCP_USER]: "User MCP Configuration",
+  [CHECK_IDS.VERSION_STATUS]: "Version Status",
+} as const
+
+export const CATEGORY_NAMES: Record<string, string> = {
+  installation: "Installation",
+  configuration: "Configuration",
+  authentication: "Authentication",
+  dependencies: "Dependencies",
+  tools: "Tools & Servers",
+  updates: "Updates",
+} as const
+
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  FAILURE: 1,
+} as const
+
+export const MIN_OPENCODE_VERSION = "1.0.150"
+
+export const PACKAGE_NAME = "oh-my-opencode"
+
+export const OPENCODE_BINARIES = ["opencode", "opencode-desktop"] as const

src/cli/doctor/formatter.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect } from "bun:test"
+import {
+  formatStatusSymbol,
+  formatCheckResult,
+  formatCategoryHeader,
+  formatSummary,
+  formatHeader,
+  formatFooter,
+  formatJsonOutput,
+  formatBox,
+  formatHelpSuggestions,
+} from "./formatter"
+import type { CheckResult, DoctorSummary, DoctorResult } from "./types"
+
+describe("formatter", () => {
+  describe("formatStatusSymbol", () => {
+    it("returns green check for pass", () => {
+      const symbol = formatStatusSymbol("pass")
+      expect(symbol).toContain("\u2713")
+    })
+
+    it("returns red cross for fail", () => {
+      const symbol = formatStatusSymbol("fail")
+      expect(symbol).toContain("\u2717")
+    })
+
+    it("returns yellow warning for warn", () => {
+      const symbol = formatStatusSymbol("warn")
+      expect(symbol).toContain("\u26A0")
+    })
+
+    it("returns dim circle for skip", () => {
+      const symbol = formatStatusSymbol("skip")
+      expect(symbol).toContain("\u25CB")
+    })
+  })
+
+  describe("formatCheckResult", () => {
+    it("includes name and message", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "All good",
+      }
+
+      const output = formatCheckResult(result, false)
+
+      expect(output).toContain("Test Check")
+      expect(output).toContain("All good")
+    })
+
+    it("includes details when verbose", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "OK",
+        details: ["Detail 1", "Detail 2"],
+      }
+
+      const output = formatCheckResult(result, true)
+
+      expect(output).toContain("Detail 1")
+      expect(output).toContain("Detail 2")
+    })
+
+    it("hides details when not verbose", () => {
+      const result: CheckResult = {
+        name: "Test Check",
+        status: "pass",
+        message: "OK",
+        details: ["Detail 1"],
+      }
+
+      const output = formatCheckResult(result, false)
+
+      expect(output).not.toContain("Detail 1")
+    })
+  })
+
+  describe("formatCategoryHeader", () => {
+    it("formats category name with styling", () => {
+      const header = formatCategoryHeader("installation")
+
+      expect(header).toContain("Installation")
+    })
+  })
+
+  describe("formatSummary", () => {
+    it("shows all counts", () => {
+      const summary: DoctorSummary = {
+        total: 10,
+        passed: 7,
+        failed: 1,
+        warnings: 2,
+        skipped: 0,
+        duration: 150,
+      }
+
+      const output = formatSummary(summary)
+
+      expect(output).toContain("7 passed")
+      expect(output).toContain("1 failed")
+      expect(output).toContain("2 warnings")
+      expect(output).toContain("10 checks")
+      expect(output).toContain("150ms")
+    })
+  })
+
+  describe("formatHeader", () => {
+    it("includes doctor branding", () => {
+      const header = formatHeader()
+
+      expect(header).toContain("Doctor")
+    })
+  })
+
+  describe("formatFooter", () => {
+    it("shows error message when failures", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 4,
+        failed: 1,
+        warnings: 0,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("Issues detected")
+    })
+
+    it("shows warning message when warnings only", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 4,
+        failed: 0,
+        warnings: 1,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("warnings")
+    })
+
+    it("shows success message when all pass", () => {
+      const summary: DoctorSummary = {
+        total: 5,
+        passed: 5,
+        failed: 0,
+        warnings: 0,
+        skipped: 0,
+        duration: 100,
+      }
+
+      const footer = formatFooter(summary)
+
+      expect(footer).toContain("operational")
+    })
+  })
+
+  describe("formatJsonOutput", () => {
+    it("returns valid JSON", () => {
+      const result: DoctorResult = {
+        results: [{ name: "Test", status: "pass", message: "OK" }],
+        summary: { total: 1, passed: 1, failed: 0, warnings: 0, skipped: 0, duration: 50 },
+        exitCode: 0,
+      }
+
+      const output = formatJsonOutput(result)
+      const parsed = JSON.parse(output)
+
+      expect(parsed.results.length).toBe(1)
+      expect(parsed.summary.total).toBe(1)
+      expect(parsed.exitCode).toBe(0)
+    })
+  })
+
+  describe("formatBox", () => {
+    it("wraps content in box", () => {
+      const box = formatBox("Test content")
+
+      expect(box).toContain("Test content")
+      expect(box).toContain("\u2500")
+    })
+
+    it("includes title when provided", () => {
+      const box = formatBox("Content", "My Title")
+
+      expect(box).toContain("My Title")
+    })
+  })
+
+  describe("formatHelpSuggestions", () => {
+    it("extracts suggestions from failed checks", () => {
+      const results: CheckResult[] = [
+        { name: "Test", status: "fail", message: "Error", details: ["Run: fix-command"] },
+        { name: "OK", status: "pass", message: "Good" },
+      ]
+
+      const suggestions = formatHelpSuggestions(results)
+
+      expect(suggestions).toContain("Run: fix-command")
+    })
+
+    it("returns empty array when no failures", () => {
+      const results: CheckResult[] = [
+        { name: "OK", status: "pass", message: "Good" },
+      ]
+
+      const suggestions = formatHelpSuggestions(results)
+
+      expect(suggestions.length).toBe(0)
+    })
+  })
+})

src/cli/doctor/formatter.ts

@@ -0,0 +1,140 @@
+import color from "picocolors"
+import type { CheckResult, DoctorSummary, CheckCategory, DoctorResult } from "./types"
+import { SYMBOLS, STATUS_COLORS, CATEGORY_NAMES } from "./constants"
+
+export function formatStatusSymbol(status: CheckResult["status"]): string {
+  switch (status) {
+    case "pass":
+      return SYMBOLS.check
+    case "fail":
+      return SYMBOLS.cross
+    case "warn":
+      return SYMBOLS.warn
+    case "skip":
+      return SYMBOLS.skip
+  }
+}
+
+export function formatCheckResult(result: CheckResult, verbose: boolean): string {
+  const symbol = formatStatusSymbol(result.status)
+  const colorFn = STATUS_COLORS[result.status]
+  const name = colorFn(result.name)
+  const message = color.dim(result.message)
+
+  let line = `  ${symbol} ${name}`
+  if (result.message) {
+    line += ` ${SYMBOLS.arrow} ${message}`
+  }
+
+  if (verbose && result.details && result.details.length > 0) {
+    const detailLines = result.details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
+    line += "\n" + detailLines
+  }
+
+  return line
+}
+
+export function formatCategoryHeader(category: CheckCategory): string {
+  const name = CATEGORY_NAMES[category] || category
+  return `\n${color.bold(color.white(name))}\n${color.dim("\u2500".repeat(40))}`
+}
+
+export function formatSummary(summary: DoctorSummary): string {
+  const lines: string[] = []
+
+  lines.push(color.bold(color.white("Summary")))
+  lines.push(color.dim("\u2500".repeat(40)))
+  lines.push("")
+
+  const passText = summary.passed > 0 ? color.green(`${summary.passed} passed`) : color.dim("0 passed")
+  const failText = summary.failed > 0 ? color.red(`${summary.failed} failed`) : color.dim("0 failed")
+  const warnText = summary.warnings > 0 ? color.yellow(`${summary.warnings} warnings`) : color.dim("0 warnings")
+  const skipText = summary.skipped > 0 ? color.dim(`${summary.skipped} skipped`) : ""
+
+  const parts = [passText, failText, warnText]
+  if (skipText) parts.push(skipText)
+
+  lines.push(`  ${parts.join(", ")}`)
+  lines.push(`  ${color.dim(`Total: ${summary.total} checks in ${summary.duration}ms`)}`)
+
+  return lines.join("\n")
+}
+
+export function formatHeader(): string {
+  return `\n${color.bgMagenta(color.white(" oMoMoMoMo... Doctor "))}\n`
+}
+
+export function formatFooter(summary: DoctorSummary): string {
+  if (summary.failed > 0) {
+    return `\n${SYMBOLS.cross} ${color.red("Issues detected. Please review the errors above.")}\n`
+  }
+  if (summary.warnings > 0) {
+    return `\n${SYMBOLS.warn} ${color.yellow("All systems operational with warnings.")}\n`
+  }
+  return `\n${SYMBOLS.check} ${color.green("All systems operational!")}\n`
+}
+
+export function formatProgress(current: number, total: number, name: string): string {
+  const progress = color.dim(`[${current}/${total}]`)
+  return `${progress} Checking ${name}...`
+}
+
+export function formatJsonOutput(result: DoctorResult): string {
+  return JSON.stringify(result, null, 2)
+}
+
+export function formatDetails(details: string[]): string {
+  return details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
+}
+
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "")
+}
+
+export function formatBox(content: string, title?: string): string {
+  const lines = content.split("\n")
+  const maxWidth = Math.max(...lines.map((l) => stripAnsi(l).length), title?.length ?? 0) + 4
+  const border = color.dim("\u2500".repeat(maxWidth))
+
+  const output: string[] = []
+  output.push("")
+
+  if (title) {
+    output.push(
+      color.dim("\u250C\u2500") +
+        color.bold(` ${title} `) +
+        color.dim("\u2500".repeat(maxWidth - title.length - 4)) +
+        color.dim("\u2510")
+    )
+  } else {
+    output.push(color.dim("\u250C") + border + color.dim("\u2510"))
+  }
+
+  for (const line of lines) {
+    const stripped = stripAnsi(line)
+    const padding = maxWidth - stripped.length
+    output.push(color.dim("\u2502") + ` ${line}${" ".repeat(padding - 1)}` + color.dim("\u2502"))
+  }
+
+  output.push(color.dim("\u2514") + border + color.dim("\u2518"))
+  output.push("")
+
+  return output.join("\n")
+}
+
+export function formatHelpSuggestions(results: CheckResult[]): string[] {
+  const suggestions: string[] = []
+
+  for (const result of results) {
+    if (result.status === "fail" && result.details) {
+      for (const detail of result.details) {
+        if (detail.includes("Run:") || detail.includes("Install:") || detail.includes("Visit:")) {
+          suggestions.push(detail)
+        }
+      }
+    }
+  }
+
+  return suggestions
+}

src/cli/doctor/index.ts

@@ -0,0 +1,11 @@
+import type { DoctorOptions } from "./types"
+import { runDoctor } from "./runner"
+
+export async function doctor(options: DoctorOptions = {}): Promise<number> {
+  const result = await runDoctor(options)
+  return result.exitCode
+}
+
+export * from "./types"
+export { runDoctor } from "./runner"
+export { formatJsonOutput } from "./formatter"

src/cli/doctor/runner.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import {
+  runCheck,
+  calculateSummary,
+  determineExitCode,
+  filterChecksByCategory,
+  groupChecksByCategory,
+} from "./runner"
+import type { CheckResult, CheckDefinition, CheckCategory } from "./types"
+
+describe("runner", () => {
+  describe("runCheck", () => {
+    it("returns result from check function", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => ({ name: "Test Check", status: "pass", message: "OK" }),
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.name).toBe("Test Check")
+      expect(result.status).toBe("pass")
+    })
+
+    it("measures duration", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => {
+          await new Promise((r) => setTimeout(r, 10))
+          return { name: "Test", status: "pass", message: "OK" }
+        },
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.duration).toBeGreaterThanOrEqual(10)
+    })
+
+    it("returns fail on error", async () => {
+      const check: CheckDefinition = {
+        id: "test",
+        name: "Test Check",
+        category: "installation",
+        check: async () => {
+          throw new Error("Test error")
+        },
+      }
+
+      const result = await runCheck(check)
+
+      expect(result.status).toBe("fail")
+      expect(result.message).toContain("Test error")
+    })
+  })
+
+  describe("calculateSummary", () => {
+    it("counts each status correctly", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "pass", message: "" },
+        { name: "3", status: "fail", message: "" },
+        { name: "4", status: "warn", message: "" },
+        { name: "5", status: "skip", message: "" },
+      ]
+
+      const summary = calculateSummary(results, 100)
+
+      expect(summary.total).toBe(5)
+      expect(summary.passed).toBe(2)
+      expect(summary.failed).toBe(1)
+      expect(summary.warnings).toBe(1)
+      expect(summary.skipped).toBe(1)
+      expect(summary.duration).toBe(100)
+    })
+  })
+
+  describe("determineExitCode", () => {
+    it("returns 0 when all pass", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "pass", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(0)
+    })
+
+    it("returns 0 when only warnings", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "warn", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(0)
+    })
+
+    it("returns 1 when any failures", () => {
+      const results: CheckResult[] = [
+        { name: "1", status: "pass", message: "" },
+        { name: "2", status: "fail", message: "" },
+      ]
+
+      expect(determineExitCode(results)).toBe(1)
+    })
+  })
+
+  describe("filterChecksByCategory", () => {
+    const checks: CheckDefinition[] = [
+      { id: "1", name: "Install", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "2", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "3", name: "Auth", category: "authentication", check: async () => ({ name: "", status: "pass", message: "" }) },
+    ]
+
+    it("returns all checks when no category", () => {
+      const filtered = filterChecksByCategory(checks)
+
+      expect(filtered.length).toBe(3)
+    })
+
+    it("filters to specific category", () => {
+      const filtered = filterChecksByCategory(checks, "installation")
+
+      expect(filtered.length).toBe(1)
+      expect(filtered[0].name).toBe("Install")
+    })
+  })
+
+  describe("groupChecksByCategory", () => {
+    const checks: CheckDefinition[] = [
+      { id: "1", name: "Install1", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "2", name: "Install2", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
+      { id: "3", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
+    ]
+
+    it("groups checks by category", () => {
+      const groups = groupChecksByCategory(checks)
+
+      expect(groups.get("installation")?.length).toBe(2)
+      expect(groups.get("configuration")?.length).toBe(1)
+    })
+
+    it("maintains order within categories", () => {
+      const groups = groupChecksByCategory(checks)
+      const installChecks = groups.get("installation")!
+
+      expect(installChecks[0].name).toBe("Install1")
+      expect(installChecks[1].name).toBe("Install2")
+    })
+  })
+})

src/cli/doctor/runner.ts

@@ -0,0 +1,132 @@
+import type {
+  DoctorOptions,
+  DoctorResult,
+  CheckDefinition,
+  CheckResult,
+  DoctorSummary,
+  CheckCategory,
+} from "./types"
+import { getAllCheckDefinitions } from "./checks"
+import { EXIT_CODES, CATEGORY_NAMES } from "./constants"
+import {
+  formatHeader,
+  formatCategoryHeader,
+  formatCheckResult,
+  formatSummary,
+  formatFooter,
+  formatJsonOutput,
+} from "./formatter"
+
+export async function runCheck(check: CheckDefinition): Promise<CheckResult> {
+  const start = performance.now()
+  try {
+    const result = await check.check()
+    result.duration = Math.round(performance.now() - start)
+    return result
+  } catch (err) {
+    return {
+      name: check.name,
+      status: "fail",
+      message: err instanceof Error ? err.message : "Unknown error",
+      duration: Math.round(performance.now() - start),
+    }
+  }
+}
+
+export function calculateSummary(results: CheckResult[], duration: number): DoctorSummary {
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "pass").length,
+    failed: results.filter((r) => r.status === "fail").length,
+    warnings: results.filter((r) => r.status === "warn").length,
+    skipped: results.filter((r) => r.status === "skip").length,
+    duration: Math.round(duration),
+  }
+}
+
+export function determineExitCode(results: CheckResult[]): number {
+  const hasFailures = results.some((r) => r.status === "fail")
+  return hasFailures ? EXIT_CODES.FAILURE : EXIT_CODES.SUCCESS
+}
+
+export function filterChecksByCategory(
+  checks: CheckDefinition[],
+  category?: CheckCategory
+): CheckDefinition[] {
+  if (!category) return checks
+  return checks.filter((c) => c.category === category)
+}
+
+export function groupChecksByCategory(
+  checks: CheckDefinition[]
+): Map<CheckCategory, CheckDefinition[]> {
+  const groups = new Map<CheckCategory, CheckDefinition[]>()
+
+  for (const check of checks) {
+    const existing = groups.get(check.category) ?? []
+    existing.push(check)
+    groups.set(check.category, existing)
+  }
+
+  return groups
+}
+
+const CATEGORY_ORDER: CheckCategory[] = [
+  "installation",
+  "configuration",
+  "authentication",
+  "dependencies",
+  "tools",
+  "updates",
+]
+
+export async function runDoctor(options: DoctorOptions): Promise<DoctorResult> {
+  const start = performance.now()
+  const allChecks = getAllCheckDefinitions()
+  const filteredChecks = filterChecksByCategory(allChecks, options.category)
+  const groupedChecks = groupChecksByCategory(filteredChecks)
+
+  const results: CheckResult[] = []
+
+  if (!options.json) {
+    console.log(formatHeader())
+  }
+
+  for (const category of CATEGORY_ORDER) {
+    const checks = groupedChecks.get(category)
+    if (!checks || checks.length === 0) continue
+
+    if (!options.json) {
+      console.log(formatCategoryHeader(category))
+    }
+
+    for (const check of checks) {
+      const result = await runCheck(check)
+      results.push(result)
+
+      if (!options.json) {
+        console.log(formatCheckResult(result, options.verbose ?? false))
+      }
+    }
+  }
+
+  const duration = performance.now() - start
+  const summary = calculateSummary(results, duration)
+  const exitCode = determineExitCode(results)
+
+  const doctorResult: DoctorResult = {
+    results,
+    summary,
+    exitCode,
+  }
+
+  if (options.json) {
+    console.log(formatJsonOutput(doctorResult))
+  } else {
+    console.log("")
+    console.log(formatSummary(summary))
+    console.log(formatFooter(summary))
+  }
+
+  return doctorResult
+}

src/cli/doctor/types.ts

@@ -0,0 +1,113 @@
+export type CheckStatus = "pass" | "fail" | "warn" | "skip"
+
+export interface CheckResult {
+  name: string
+  status: CheckStatus
+  message: string
+  details?: string[]
+  duration?: number
+}
+
+export type CheckFunction = () => Promise<CheckResult>
+
+export type CheckCategory =
+  | "installation"
+  | "configuration"
+  | "authentication"
+  | "dependencies"
+  | "tools"
+  | "updates"
+
+export interface CheckDefinition {
+  id: string
+  name: string
+  category: CheckCategory
+  check: CheckFunction
+  critical?: boolean
+}
+
+export interface DoctorOptions {
+  verbose?: boolean
+  json?: boolean
+  category?: CheckCategory
+}
+
+export interface DoctorSummary {
+  total: number
+  passed: number
+  failed: number
+  warnings: number
+  skipped: number
+  duration: number
+}
+
+export interface DoctorResult {
+  results: CheckResult[]
+  summary: DoctorSummary
+  exitCode: number
+}
+
+export interface OpenCodeInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  binary: "opencode" | "opencode-desktop" | null
+}
+
+export interface PluginInfo {
+  registered: boolean
+  configPath: string | null
+  entry: string | null
+  isPinned: boolean
+  pinnedVersion: string | null
+}
+
+export interface ConfigInfo {
+  exists: boolean
+  path: string | null
+  format: "json" | "jsonc" | null
+  valid: boolean
+  errors: string[]
+}
+
+export type AuthProviderId = "anthropic" | "openai" | "google"
+
+export interface AuthProviderInfo {
+  id: AuthProviderId
+  name: string
+  pluginInstalled: boolean
+  configured: boolean
+  error?: string
+}
+
+export interface DependencyInfo {
+  name: string
+  required: boolean
+  installed: boolean
+  version: string | null
+  path: string | null
+  installHint?: string
+}
+
+export interface LspServerInfo {
+  id: string
+  installed: boolean
+  extensions: string[]
+  source: "builtin" | "config" | "plugin"
+}
+
+export interface McpServerInfo {
+  id: string
+  type: "builtin" | "user"
+  enabled: boolean
+  valid: boolean
+  error?: string
+}
+
+export interface VersionCheckInfo {
+  currentVersion: string | null
+  latestVersion: string | null
+  isUpToDate: boolean
+  isLocalDev: boolean
+  isPinned: boolean
+}

src/cli/index.ts

@@ -3,9 +3,11 @@ import { Command } from "commander"
 import { install } from "./install"
 import { run } from "./run"
 import { getLocalVersion } from "./get-local-version"
+import { doctor } from "./doctor"
 import type { InstallArgs } from "./types"
 import type { RunOptions } from "./run"
 import type { GetLocalVersionOptions } from "./get-local-version/types"
+import type { DoctorOptions } from "./doctor"
 
 const packageJson = await import("../../package.json")
 const VERSION = packageJson.version
@@ -101,6 +103,37 @@ This command shows:
     process.exit(exitCode)
   })
 
+program
+  .command("doctor")
+  .description("Check oh-my-opencode installation health and diagnose issues")
+  .option("--verbose", "Show detailed diagnostic information")
+  .option("--json", "Output results in JSON format")
+  .option("--category <category>", "Run only specific category")
+  .addHelpText("after", `
+Examples:
+  $ bunx oh-my-opencode doctor
+  $ bunx oh-my-opencode doctor --verbose
+  $ bunx oh-my-opencode doctor --json
+  $ bunx oh-my-opencode doctor --category authentication
+
+Categories:
+  installation     Check OpenCode and plugin installation
+  configuration    Validate configuration files
+  authentication   Check auth provider status
+  dependencies     Check external dependencies
+  tools            Check LSP and MCP servers
+  updates          Check for version updates
+`)
+  .action(async (options) => {
+    const doctorOptions: DoctorOptions = {
+      verbose: options.verbose ?? false,
+      json: options.json ?? false,
+      category: options.category,
+    }
+    const exitCode = await doctor(doctorOptions)
+    process.exit(exitCode)
+  })
+
 program
   .command("version")
   .description("Show version information")

src/cli/install.ts

@@ -331,6 +331,17 @@ async function runNonTuiInstall(args: InstallArgs): Promise<number> {
   console.log(`${SYMBOLS.star} ${color.bold(color.green(isUpdate ? "Configuration updated!" : "Installation complete!"))}`)
   console.log(`  Run ${color.cyan("opencode")} to start!`)
   console.log()
+
+  printBox(
+    `${color.bold("Pro Tip:")} Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  console.log(`${SYMBOLS.star} ${color.yellow("If you found this helpful, consider starring the repo!")}`)
+  console.log(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+  console.log()
   console.log(color.dim("oMoMoMoMo... Enjoy!"))
   console.log()
 
@@ -450,6 +461,16 @@ export async function install(args: InstallArgs): Promise<number> {
   p.log.success(color.bold(isUpdate ? "Configuration updated!" : "Installation complete!"))
   p.log.message(`Run ${color.cyan("opencode")} to start!`)
 
+  p.note(
+    `Include ${color.cyan("ultrawork")} (or ${color.cyan("ulw")}) in your prompt.\n` +
+    `All features work like magic—parallel agents, background tasks,\n` +
+    `deep exploration, and relentless execution until completion.`,
+    "🪄 The Magic Word"
+  )
+
+  p.log.message(`${color.yellow("★")} If you found this helpful, consider starring the repo!`)
+  p.log.message(`  ${color.dim("gh repo star code-yeongyu/oh-my-opencode")}`)
+
   p.outro(color.green("oMoMoMoMo... Enjoy!"))
 
   return 0

src/cli/run/events.ts

@@ -79,15 +79,11 @@ function logEventVerbose(ctx: RunContext, payload: EventPayload): void {
     }
 
     case "message.part.updated": {
+      // Skip verbose logging for partial message updates
+      // Only log tool invocation state changes, not text streaming
       const partProps = props as MessagePartUpdatedProps | undefined
-      const role = partProps?.info?.role ?? "unknown"
       const part = partProps?.part
-      if (part?.type === "text" && part.text) {
-        const preview = part.text.slice(0, 100).replace(/\n/g, "\\n")
-        console.error(
-          pc.dim(`${sessionTag} message.part (${role}): "${preview}${part.text.length > 100 ? "..." : ""}"`)
-        )
-      } else if (part?.type === "tool-invocation") {
+      if (part?.type === "tool-invocation") {
         const toolPart = part as { toolName?: string; state?: string }
         console.error(
           pc.dim(`${sessionTag} message.part (tool): ${toolPart.toolName} [${toolPart.state}]`)

src/config/index.ts

@@ -8,6 +8,7 @@ export {
   BuiltinCommandNameSchema,
   SisyphusAgentConfigSchema,
   ExperimentalConfigSchema,
+  RalphLoopConfigSchema,
 } from "./schema"
 
 export type {
@@ -21,4 +22,5 @@ export type {
   SisyphusAgentConfig,
   ExperimentalConfig,
   DynamicContextPruningConfig,
+  RalphLoopConfig,
 } from "./schema"

src/config/schema.ts

@@ -26,6 +26,10 @@ export const BuiltinAgentNameSchema = z.enum([
   "multimodal-looker",
 ])
 
+export const BuiltinSkillNameSchema = z.enum([
+  "playwright",
+])
+
 export const OverridableAgentNameSchema = z.enum([
   "build",
   "plan",
@@ -54,7 +58,7 @@ export const HookNameSchema = z.enum([
   "directory-readme-injector",
   "empty-task-response-detector",
   "think-mode",
-  "anthropic-auto-compact",
+  "anthropic-context-window-limit-recovery",
   "rules-injector",
   "background-notification",
   "auto-update-checker",
@@ -65,6 +69,12 @@ export const HookNameSchema = z.enum([
   "interactive-bash-session",
   "empty-message-sanitizer",
   "thinking-block-validator",
+  "ralph-loop",
+  "preemptive-compaction",
+  "compaction-context-injector",
+  "claude-code-hooks",
+  "auto-slash-command",
+  "edit-error-recovery",
 ])
 
 export const BuiltinCommandNameSchema = z.enum([
@@ -163,22 +173,70 @@ export const DynamicContextPruningConfigSchema = z.object({
 export const ExperimentalConfigSchema = z.object({
   aggressive_truncation: z.boolean().optional(),
   auto_resume: z.boolean().optional(),
-  /** Enable preemptive compaction at threshold (default: true) */
+  /** Enable preemptive compaction at threshold (default: true since v2.9.0) */
   preemptive_compaction: z.boolean().optional(),
   /** Threshold percentage to trigger preemptive compaction (default: 0.80) */
   preemptive_compaction_threshold: z.number().min(0.5).max(0.95).optional(),
-  /** Truncate all tool outputs, not just whitelisted tools (default: true) */
-  truncate_all_tool_outputs: z.boolean().default(true),
+  /** Truncate all tool outputs, not just whitelisted tools (default: false). Tool output truncator is enabled by default - disable via disabled_hooks. */
+  truncate_all_tool_outputs: z.boolean().optional(),
   /** Dynamic context pruning configuration */
   dynamic_context_pruning: DynamicContextPruningConfigSchema.optional(),
   /** Enable DCP (Dynamic Context Pruning) for compaction - runs first when token limit exceeded (default: false) */
   dcp_for_compaction: z.boolean().optional(),
 })
 
+export const SkillSourceSchema = z.union([
+  z.string(),
+  z.object({
+    path: z.string(),
+    recursive: z.boolean().optional(),
+    glob: z.string().optional(),
+  }),
+])
+
+export const SkillDefinitionSchema = z.object({
+  description: z.string().optional(),
+  template: z.string().optional(),
+  from: z.string().optional(),
+  model: z.string().optional(),
+  agent: z.string().optional(),
+  subtask: z.boolean().optional(),
+  "argument-hint": z.string().optional(),
+  license: z.string().optional(),
+  compatibility: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  "allowed-tools": z.array(z.string()).optional(),
+  disable: z.boolean().optional(),
+})
+
+export const SkillEntrySchema = z.union([
+  z.boolean(),
+  SkillDefinitionSchema,
+])
+
+export const SkillsConfigSchema = z.union([
+  z.array(z.string()),
+  z.record(z.string(), SkillEntrySchema).and(z.object({
+    sources: z.array(SkillSourceSchema).optional(),
+    enable: z.array(z.string()).optional(),
+    disable: z.array(z.string()).optional(),
+  }).partial()),
+])
+
+export const RalphLoopConfigSchema = z.object({
+  /** Enable ralph loop functionality (default: false - opt-in feature) */
+  enabled: z.boolean().default(false),
+  /** Default max iterations if not specified in command (default: 100) */
+  default_max_iterations: z.number().min(1).max(1000).default(100),
+  /** Custom state file directory relative to project root (default: .opencode/) */
+  state_dir: z.string().optional(),
+})
+
 export const OhMyOpenCodeConfigSchema = z.object({
   $schema: z.string().optional(),
   disabled_mcps: z.array(McpNameSchema).optional(),
   disabled_agents: z.array(BuiltinAgentNameSchema).optional(),
+  disabled_skills: z.array(BuiltinSkillNameSchema).optional(),
   disabled_hooks: z.array(HookNameSchema).optional(),
   disabled_commands: z.array(BuiltinCommandNameSchema).optional(),
   agents: AgentOverridesSchema.optional(),
@@ -188,6 +246,8 @@ export const OhMyOpenCodeConfigSchema = z.object({
   comment_checker: CommentCheckerConfigSchema.optional(),
   experimental: ExperimentalConfigSchema.optional(),
   auto_update: z.boolean().optional(),
+  skills: SkillsConfigSchema.optional(),
+  ralph_loop: RalphLoopConfigSchema.optional(),
 })
 
 export type OhMyOpenCodeConfig = z.infer<typeof OhMyOpenCodeConfigSchema>
@@ -196,9 +256,13 @@ export type AgentOverrides = z.infer<typeof AgentOverridesSchema>
 export type AgentName = z.infer<typeof AgentNameSchema>
 export type HookName = z.infer<typeof HookNameSchema>
 export type BuiltinCommandName = z.infer<typeof BuiltinCommandNameSchema>
+export type BuiltinSkillName = z.infer<typeof BuiltinSkillNameSchema>
 export type SisyphusAgentConfig = z.infer<typeof SisyphusAgentConfigSchema>
 export type CommentCheckerConfig = z.infer<typeof CommentCheckerConfigSchema>
 export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>
 export type DynamicContextPruningConfig = z.infer<typeof DynamicContextPruningConfigSchema>
+export type SkillsConfig = z.infer<typeof SkillsConfigSchema>
+export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>
+export type RalphLoopConfig = z.infer<typeof RalphLoopConfigSchema>
 
 export { McpNameSchema, type McpName } from "../mcp/types"

src/features/AGENTS.md

@@ -2,79 +2,65 @@
 
 ## OVERVIEW
 
-Claude Code compatibility layer and core feature modules. Enables Claude Code configs/commands/skills/MCPs/hooks to work seamlessly in OpenCode.
+Claude Code compatibility layer + core feature modules. Commands, skills, agents, MCPs, hooks from Claude Code work seamlessly.
 
 ## STRUCTURE
 
 ```
 features/
-├── background-agent/           # Background task management
-│   ├── manager.ts              # Task lifecycle, notifications
-│   ├── manager.test.ts
-│   └── types.ts
-├── builtin-commands/           # Built-in slash command definitions
-├── claude-code-agent-loader/   # Load agents from ~/.claude/agents/*.md
-├── claude-code-command-loader/ # Load commands from ~/.claude/commands/*.md
-├── claude-code-mcp-loader/     # Load MCPs from .mcp.json
+├── background-agent/           # Task lifecycle, notifications (460 lines)
+├── builtin-commands/           # Built-in slash commands
+├── builtin-skills/             # Built-in skills (playwright)
+├── 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/  # Load external plugins from installed_plugins.json
+├── claude-code-plugin-loader/  # installed_plugins.json (484 lines)
 ├── claude-code-session-state/  # Session state persistence
-├── claude-code-skill-loader/   # Load skills from ~/.claude/skills/*/SKILL.md
+├── opencode-skill-loader/      # Skills from OpenCode + Claude paths
+├── skill-mcp-manager/          # MCP servers in skill YAML
 └── hook-message-injector/      # Inject messages into conversation
 ```
 
 ## LOADER PRIORITY
 
-Each loader reads from multiple directories (highest priority first):
-
-| Loader | Priority Order |
-|--------|---------------|
+| Loader | Priority (highest first) |
+|--------|--------------------------|
 | Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` |
-| Skills | `.claude/skills/` > `~/.claude/skills/` |
+| Skills | `.opencode/skill/` > `~/.config/opencode/skill/` > `.claude/skills/` > `~/.claude/skills/` |
 | Agents | `.claude/agents/` > `~/.claude/agents/` |
 | MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
 
-## HOW TO ADD A LOADER
-
-1. Create directory: `src/features/claude-code-my-loader/`
-2. Create files:
-   - `loader.ts`: Main loader logic with `load()` function
-   - `types.ts`: TypeScript interfaces
-   - `index.ts`: Barrel export
-3. Pattern: Read from multiple dirs, merge with priority, return normalized config
-
-## BACKGROUND AGENT SPECIFICS
-
-- **Task lifecycle**: pending → running → completed/failed
-- **Notifications**: OS notification on task complete (configurable)
-- **Result retrieval**: `background_output` tool with task_id
-- **Cancellation**: `background_cancel` with task_id or all=true
-
 ## CONFIG TOGGLES
 
-Disable features in `oh-my-opencode.json`:
-
 ```json
 {
   "claude_code": {
-    "mcp": false,      // Skip .mcp.json loading
-    "commands": false, // Skip commands/*.md loading
-    "skills": false,   // Skip skills/*/SKILL.md loading
-    "agents": false,   // Skip agents/*.md loading
+    "mcp": false,      // Skip .mcp.json
+    "commands": false, // Skip commands/*.md
+    "skills": false,   // Skip skills/*/SKILL.md
+    "agents": false,   // Skip agents/*.md
     "hooks": false     // Skip settings.json hooks
   }
 }
 ```
 
-## HOOK MESSAGE INJECTOR
+## BACKGROUND AGENT
 
-- **Purpose**: Inject system messages into conversation at specific points
-- **Timing**: PreToolUse, PostToolUse, UserPromptSubmit, Stop
-- **Format**: Returns `{ messages: [{ role: "user", content: "..." }] }`
+- Lifecycle: pending → running → completed/failed
+- OS notification on complete
+- `background_output` to retrieve results
+- `background_cancel` with task_id or all=true
 
-## ANTI-PATTERNS (FEATURES)
+## SKILL MCP
 
-- **Blocking on load**: Loaders run at startup, keep them fast
-- **No error handling**: Always try/catch, log failures, return empty on error
-- **Ignoring priority**: Higher priority dirs must override lower
-- **Modifying user files**: Loaders read-only, never write to ~/.claude/
+- MCP servers embedded in skill YAML frontmatter
+- Lazy client loading, session-scoped cleanup
+- `skill_mcp` tool exposes capabilities
+
+## ANTI-PATTERNS
+
+- Blocking on load (loaders run at startup)
+- No error handling (always try/catch)
+- Ignoring priority order
+- Writing to ~/.claude/ (read-only)

src/features/background-agent/manager.test.ts

@@ -1,8 +1,11 @@
 import { describe, test, expect, beforeEach } from "bun:test"
 import type { BackgroundTask } from "./types"
 
+const TASK_TTL_MS = 30 * 60 * 1000
+
 class MockBackgroundManager {
   private tasks: Map<string, BackgroundTask> = new Map()
+  private notifications: Map<string, BackgroundTask[]> = new Map()
 
   addTask(task: BackgroundTask): void {
     this.tasks.set(task.id, task)
@@ -34,6 +37,74 @@ class MockBackgroundManager {
 
     return result
   }
+
+  markForNotification(task: BackgroundTask): void {
+    const queue = this.notifications.get(task.parentSessionID) ?? []
+    queue.push(task)
+    this.notifications.set(task.parentSessionID, queue)
+  }
+
+  getPendingNotifications(sessionID: string): BackgroundTask[] {
+    return this.notifications.get(sessionID) ?? []
+  }
+
+  private clearNotificationsForTask(taskId: string): void {
+    for (const [sessionID, tasks] of this.notifications.entries()) {
+      const filtered = tasks.filter((t) => t.id !== taskId)
+      if (filtered.length === 0) {
+        this.notifications.delete(sessionID)
+      } else {
+        this.notifications.set(sessionID, filtered)
+      }
+    }
+  }
+
+  pruneStaleTasksAndNotifications(): { prunedTasks: string[]; prunedNotifications: number } {
+    const now = Date.now()
+    const prunedTasks: string[] = []
+    let prunedNotifications = 0
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        prunedTasks.push(taskId)
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      const removed = notifications.length - validNotifications.length
+      prunedNotifications += removed
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+
+    return { prunedTasks, prunedNotifications }
+  }
+
+  getTaskCount(): number {
+    return this.tasks.size
+  }
+
+  getNotificationCount(): number {
+    let count = 0
+    for (const notifications of this.notifications.values()) {
+      count += notifications.length
+    }
+    return count
+  }
 }
 
 function createMockTask(overrides: Partial<BackgroundTask> & { id: string; sessionID: string; parentSessionID: string }): BackgroundTask {
@@ -230,3 +301,116 @@ describe("BackgroundManager.getAllDescendantTasks", () => {
     expect(result[0].id).toBe("task-b")
   })
 })
+
+describe("BackgroundManager.pruneStaleTasksAndNotifications", () => {
+  let manager: MockBackgroundManager
+
+  beforeEach(() => {
+    // #given
+    manager = new MockBackgroundManager()
+  })
+
+  test("should not prune fresh tasks", () => {
+    // #given
+    const task = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(0)
+    expect(manager.getTaskCount()).toBe(1)
+  })
+
+  test("should prune tasks older than 30 minutes", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(0)
+  })
+
+  test("should prune stale notifications", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.markForNotification(task)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedNotifications).toBe(1)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should clean up notifications when task is pruned", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const task = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    manager.addTask(task)
+    manager.markForNotification(task)
+
+    // #when
+    manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(manager.getTaskCount()).toBe(0)
+    expect(manager.getNotificationCount()).toBe(0)
+  })
+
+  test("should keep fresh tasks while pruning stale ones", () => {
+    // #given
+    const staleDate = new Date(Date.now() - 31 * 60 * 1000)
+    const staleTask = createMockTask({
+      id: "task-stale",
+      sessionID: "session-stale",
+      parentSessionID: "session-parent",
+      startedAt: staleDate,
+    })
+    const freshTask = createMockTask({
+      id: "task-fresh",
+      sessionID: "session-fresh",
+      parentSessionID: "session-parent",
+      startedAt: new Date(),
+    })
+    manager.addTask(staleTask)
+    manager.addTask(freshTask)
+
+    // #when
+    const result = manager.pruneStaleTasksAndNotifications()
+
+    // #then
+    expect(result.prunedTasks).toHaveLength(1)
+    expect(result.prunedTasks).toContain("task-stale")
+    expect(manager.getTaskCount()).toBe(1)
+    expect(manager.getTask("task-fresh")).toBeDefined()
+  })
+})

src/features/background-agent/manager.ts

@@ -12,6 +12,8 @@ import {
 } from "../hook-message-injector"
 import { subagentSessions } from "../claude-code-session-state"
 
+const TASK_TTL_MS = 30 * 60 * 1000
+
 type OpencodeClient = PluginInput["client"]
 
 interface MessagePartInfo {
@@ -345,11 +347,12 @@ export class BackgroundManager {
           },
           query: { directory: this.directory },
         })
-        this.clearNotificationsForTask(taskId)
         log("[background-agent] Successfully sent prompt to parent session:", { parentSessionID: task.parentSessionID })
       } catch (error) {
         log("[background-agent] prompt failed:", String(error))
       } finally {
+        // Always clean up both maps to prevent memory leaks
+        this.clearNotificationsForTask(taskId)
         this.tasks.delete(taskId)
         log("[background-agent] Removed completed task from memory:", taskId)
       }
@@ -377,7 +380,42 @@ export class BackgroundManager {
     return false
   }
 
+  private pruneStaleTasksAndNotifications(): void {
+    const now = Date.now()
+
+    for (const [taskId, task] of this.tasks.entries()) {
+      const age = now - task.startedAt.getTime()
+      if (age > TASK_TTL_MS) {
+        log("[background-agent] Pruning stale task:", { taskId, age: Math.round(age / 1000) + "s" })
+        task.status = "error"
+        task.error = "Task timed out after 30 minutes"
+        task.completedAt = new Date()
+        this.clearNotificationsForTask(taskId)
+        this.tasks.delete(taskId)
+        subagentSessions.delete(task.sessionID)
+      }
+    }
+
+    for (const [sessionID, notifications] of this.notifications.entries()) {
+      if (notifications.length === 0) {
+        this.notifications.delete(sessionID)
+        continue
+      }
+      const validNotifications = notifications.filter((task) => {
+        const age = now - task.startedAt.getTime()
+        return age <= TASK_TTL_MS
+      })
+      if (validNotifications.length === 0) {
+        this.notifications.delete(sessionID)
+      } else if (validNotifications.length !== notifications.length) {
+        this.notifications.set(sessionID, validNotifications)
+      }
+    }
+  }
+
   private async pollRunningTasks(): Promise<void> {
+    this.pruneStaleTasksAndNotifications()
+
     const statusResult = await this.client.session.status()
     const allStatuses = (statusResult.data ?? {}) as Record<string, { type: string }>
 

src/features/builtin-commands/commands.ts

@@ -1,6 +1,7 @@
 import type { CommandDefinition } from "../claude-code-command-loader"
 import type { BuiltinCommandName, BuiltinCommands } from "./types"
 import { INIT_DEEP_TEMPLATE } from "./templates/init-deep"
+import { RALPH_LOOP_TEMPLATE, CANCEL_RALPH_TEMPLATE } from "./templates/ralph-loop"
 
 const BUILTIN_COMMAND_DEFINITIONS: Record<BuiltinCommandName, Omit<CommandDefinition, "name">> = {
   "init-deep": {
@@ -14,6 +15,23 @@ $ARGUMENTS
 </user-request>`,
     argumentHint: "[--create-new] [--max-depth=N]",
   },
+  "ralph-loop": {
+    description: "(builtin) Start self-referential development loop until completion",
+    template: `<command-instruction>
+${RALPH_LOOP_TEMPLATE}
+</command-instruction>
+
+<user-task>
+$ARGUMENTS
+</user-task>`,
+    argumentHint: '"task description" [--completion-promise=TEXT] [--max-iterations=N]',
+  },
+  "cancel-ralph": {
+    description: "(builtin) Cancel active Ralph Loop",
+    template: `<command-instruction>
+${CANCEL_RALPH_TEMPLATE}
+</command-instruction>`,
+  },
 }
 
 export function loadBuiltinCommands(
@@ -24,10 +42,8 @@ export function loadBuiltinCommands(
 
   for (const [name, definition] of Object.entries(BUILTIN_COMMAND_DEFINITIONS)) {
     if (!disabled.has(name as BuiltinCommandName)) {
-      commands[name] = {
-        name,
-        ...definition,
-      }
+      const { argumentHint: _argumentHint, ...openCodeCompatible } = definition
+      commands[name] = openCodeCompatible as CommandDefinition
     }
   }
 

src/features/builtin-commands/templates/init-deep.ts

@@ -1,205 +1,191 @@
-export const INIT_DEEP_TEMPLATE = `# Initialize Deep Knowledge Base
+export const INIT_DEEP_TEMPLATE = `# /init-deep
 
-Generate comprehensive AGENTS.md files across project hierarchy. Combines root-level project knowledge (gen-knowledge) with complexity-based subdirectory documentation (gen-knowledge-deep).
+Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.
 
 ## Usage
 
 \`\`\`
-/init-deep                      # Analyze and generate hierarchical AGENTS.md
-/init-deep --create-new         # Force create from scratch (ignore existing)
-/init-deep --max-depth=2        # Limit to N directory levels (default: 3)
+/init-deep                      # Update mode: modify existing + create new where warranted
+/init-deep --create-new         # Read existing → remove all → regenerate from scratch
+/init-deep --max-depth=2        # Limit directory depth (default: 3)
 \`\`\`
 
 ---
 
-## Core Principles
+## Workflow (High-Level)
 
-- **Telegraphic Style**: Sacrifice grammar for concision ("Project uses React" → "React 18")
-- **Predict-then-Compare**: Predict standard → find actual → document ONLY deviations
-- **Hierarchy Aware**: Parent covers general, children cover specific
-- **No Redundancy**: Child AGENTS.md NEVER repeats parent content
-- **LSP-First**: Use LSP tools for accurate code intelligence when available (semantic > text search)
-
----
-
-## Process
+1. **Discovery + Analysis** (concurrent)
+   - Fire background explore agents immediately
+   - Main session: bash structure + LSP codemap + read existing AGENTS.md
+2. **Score & Decide** - Determine AGENTS.md locations from merged findings
+3. **Generate** - Root first, then subdirs in parallel
+4. **Review** - Deduplicate, trim, validate
 
 <critical>
-**MANDATORY: TodoWrite for ALL phases. Mark in_progress → completed in real-time.**
-</critical>
-
-### Phase 0: Initialize
-
+**TodoWrite ALL phases. Mark in_progress → completed in real-time.**
 \`\`\`
 TodoWrite([
-  { id: "p1-analysis", content: "Parallel project structure & complexity analysis", status: "pending", priority: "high" },
-  { id: "p2-scoring", content: "Score directories, determine AGENTS.md locations", status: "pending", priority: "high" },
-  { id: "p3-root", content: "Generate root AGENTS.md with Predict-then-Compare", status: "pending", priority: "high" },
-  { id: "p4-subdirs", content: "Generate subdirectory AGENTS.md files in parallel", status: "pending", priority: "high" },
-  { id: "p5-review", content: "Review, deduplicate, validate all files", status: "pending", priority: "medium" }
+  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },
+  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },
+  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },
+  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }
 ])
 \`\`\`
+</critical>
 
 ---
 
-## Phase 1: Parallel Project Analysis
+## Phase 1: Discovery + Analysis (Concurrent)
 
-**Mark "p1-analysis" as in_progress.**
+**Mark "discovery" as in_progress.**
 
-Launch **ALL tasks simultaneously**:
+### Fire Background Explore Agents IMMEDIATELY
 
-<parallel-tasks>
+Don't wait—these run async while main session works.
+
+\`\`\`
+// Fire all at once, collect results later
+background_task(agent="explore", prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only")
+background_task(agent="explore", prompt="Entry points: FIND main files → REPORT non-standard organization")
+background_task(agent="explore", prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules")
+background_task(agent="explore", prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns")
+background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns")
+background_task(agent="explore", prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions")
+\`\`\`
+
+<dynamic-agents>
+**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:
+
+| Factor | Threshold | Additional Agents |
+|--------|-----------|-------------------|
+| **Total files** | >100 | +1 per 100 files |
+| **Total lines** | >10k | +1 per 10k lines |
+| **Directory depth** | ≥4 | +2 for deep exploration |
+| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |
+| **Monorepo** | detected | +1 per package/workspace |
+| **Multiple languages** | >1 | +1 per language |
 
-### Structural Analysis (bash - run in parallel)
 \`\`\`bash
-# Task A: Directory depth analysis
-find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+# Measure project scale first
+total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
+total_lines=$(find . -type f \\( -name "*.ts" -o -name "*.py" -o -name "*.go" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+large_files=$(find . -type f \\( -name "*.ts" -o -name "*.py" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
+max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)
+\`\`\`
 
-# Task B: File count per directory  
-find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/__pycache__/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+Example spawning:
+\`\`\`
+// 500 files, 50k lines, depth 6, 15 large files → spawn 5+5+2+1 = 13 additional agents
+background_task(agent="explore", prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots")
+background_task(agent="explore", prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions")
+background_task(agent="explore", prompt="Cross-cutting concerns: FIND shared utilities across directories")
+// ... more based on calculation
+\`\`\`
+</dynamic-agents>
 
-# Task C: Code concentration
-find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \\) -not -path '*/node_modules/*' -not -path '*/venv/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+### Main Session: Concurrent Analysis
 
-# Task D: Existing knowledge files
+**While background agents run**, main session does:
+
+#### 1. Bash Structural Analysis
+\`\`\`bash
+# Directory depth + file counts
+find . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+
+# Files per directory (top 30)
+find . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+
+# Code concentration by extension
+find . -type f \\( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+
+# Existing AGENTS.md / CLAUDE.md
 find . -type f \\( -name "AGENTS.md" -o -name "CLAUDE.md" \\) -not -path '*/node_modules/*' 2>/dev/null
 \`\`\`
 
-### Context Gathering (Explore agents - background_task in parallel)
-
+#### 2. Read Existing AGENTS.md
 \`\`\`
-background_task(agent="explore", prompt="Project structure: PREDICT standard {lang} patterns → FIND package.json/pyproject.toml/go.mod → REPORT deviations only")
-
-background_task(agent="explore", prompt="Entry points: PREDICT typical (main.py, index.ts) → FIND actual → REPORT non-standard organization")
-
-background_task(agent="explore", prompt="Conventions: FIND .cursor/rules, .cursorrules, eslintrc, pyproject.toml → REPORT project-specific rules DIFFERENT from defaults")
-
-background_task(agent="explore", prompt="Anti-patterns: FIND comments with 'DO NOT', 'NEVER', 'ALWAYS', 'LEGACY', 'DEPRECATED' → REPORT forbidden patterns")
-
-background_task(agent="explore", prompt="Build/CI: FIND .github/workflows, Makefile, justfile → REPORT non-standard build/deploy patterns")
-
-background_task(agent="explore", prompt="Test patterns: FIND pytest.ini, jest.config, test structure → REPORT unique testing conventions")
+For each existing file found:
+  Read(filePath=file)
+  Extract: key insights, conventions, anti-patterns
+  Store in EXISTING_AGENTS map
 \`\`\`
 
-### Code Intelligence Analysis (LSP tools - run in parallel)
-
-LSP provides semantic understanding beyond text search. Use for accurate code mapping.
+If \`--create-new\`: Read all existing first (preserve context) → then delete all → regenerate.
 
+#### 3. LSP Codemap (if available)
 \`\`\`
-# Step 1: Check LSP availability
-lsp_servers()  # Verify language server is available
+lsp_servers()  # Check availability
 
-# Step 2: Analyze entry point files (run in parallel)
-# Find entry points first, then analyze each with lsp_document_symbols
-lsp_document_symbols(filePath="src/index.ts")      # Main entry
-lsp_document_symbols(filePath="src/main.py")       # Python entry
-lsp_document_symbols(filePath="cmd/main.go")       # Go entry
+# Entry points (parallel)
+lsp_document_symbols(filePath="src/index.ts")
+lsp_document_symbols(filePath="main.py")
 
-# Step 3: Discover key symbols across workspace (run in parallel)
-lsp_workspace_symbols(filePath=".", query="class")      # All classes
-lsp_workspace_symbols(filePath=".", query="interface")  # All interfaces
-lsp_workspace_symbols(filePath=".", query="function")   # Top-level functions
-lsp_workspace_symbols(filePath=".", query="type")       # Type definitions
+# Key symbols (parallel)
+lsp_workspace_symbols(filePath=".", query="class")
+lsp_workspace_symbols(filePath=".", query="interface")
+lsp_workspace_symbols(filePath=".", query="function")
 
-# Step 4: Analyze symbol centrality (for top 5-10 key symbols)
-# High reference count = central/important concept
-lsp_find_references(filePath="src/index.ts", line=X, character=Y)  # Main export
+# Centrality for top exports
+lsp_find_references(filePath="...", line=X, character=Y)
 \`\`\`
 
-#### LSP Analysis Output Format
+**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.
+
+### Collect Background Results
 
 \`\`\`
-CODE_INTELLIGENCE = {
-  entry_points: [
-    { file: "src/index.ts", exports: ["Plugin", "createHook"], symbol_count: 12 }
-  ],
-  key_symbols: [
-    { name: "Plugin", type: "class", file: "src/index.ts", refs: 45, role: "Central orchestrator" },
-    { name: "createHook", type: "function", file: "src/utils.ts", refs: 23, role: "Hook factory" }
-  ],
-  module_boundaries: [
-    { dir: "src/hooks", exports: 21, imports_from: ["shared/"] },
-    { dir: "src/tools", exports: 15, imports_from: ["shared/", "hooks/"] }
-  ]
-}
+// After main session analysis done, collect all task results
+for each task_id: background_output(task_id="...")
 \`\`\`
 
-<critical>
-**LSP Fallback**: If LSP unavailable (no server installed), skip this section and rely on explore agents + AST-grep patterns.
-</critical>
-
-</parallel-tasks>
-
-**Collect all results. Mark "p1-analysis" as completed.**
+**Merge: bash + LSP + existing + explore findings. Mark "discovery" as completed.**
 
 ---
 
-## Phase 2: Complexity Scoring & Location Decision
+## Phase 2: Scoring & Location Decision
 
-**Mark "p2-scoring" as in_progress.**
+**Mark "scoring" as in_progress.**
 
 ### Scoring Matrix
 
-| Factor | Weight | Threshold | Source |
-|--------|--------|-----------|--------|
-| File count | 3x | >20 files = high | bash |
-| Subdirectory count | 2x | >5 subdirs = high | bash |
-| Code file ratio | 2x | >70% code = high | bash |
+| Factor | Weight | High Threshold | Source |
+|--------|--------|----------------|--------|
+| File count | 3x | >20 | bash |
+| Subdir count | 2x | >5 | bash |
+| Code ratio | 2x | >70% | bash |
 | Unique patterns | 1x | Has own config | explore |
-| Module boundary | 2x | Has __init__.py/index.ts | bash |
-| **Symbol density** | 2x | >30 symbols = high | LSP |
-| **Export count** | 2x | >10 exports = high | LSP |
-| **Reference centrality** | 3x | Symbols with >20 refs | LSP |
-
-<lsp-scoring>
-**LSP-Enhanced Scoring** (if available):
-
-\`\`\`
-For each directory in candidates:
-  symbols = lsp_document_symbols(dir/index.ts or dir/__init__.py)
-  
-  symbol_score = len(symbols) > 30 ? 6 : len(symbols) > 15 ? 3 : 0
-  export_score = count(exported symbols) > 10 ? 4 : 0
-  
-  # Check if this module is central (many things depend on it)
-  for each exported symbol:
-    refs = lsp_find_references(symbol)
-    if refs > 20: centrality_score += 3
-  
-  total_score += symbol_score + export_score + centrality_score
-\`\`\`
-</lsp-scoring>
+| Module boundary | 2x | Has index.ts/__init__.py | bash |
+| Symbol density | 2x | >30 symbols | LSP |
+| Export count | 2x | >10 exports | LSP |
+| Reference centrality | 3x | >20 refs | LSP |
 
 ### Decision Rules
 
 | Score | Action |
 |-------|--------|
-| **Root (.)** | ALWAYS create AGENTS.md |
-| **High (>15)** | Create dedicated AGENTS.md |
-| **Medium (8-15)** | Create if distinct domain |
-| **Low (<8)** | Skip, parent sufficient |
-
-### Output Format
+| **Root (.)** | ALWAYS create |
+| **>15** | Create AGENTS.md |
+| **8-15** | Create if distinct domain |
+| **<8** | Skip (parent covers) |
 
+### Output
 \`\`\`
 AGENTS_LOCATIONS = [
   { path: ".", type: "root" },
-  { path: "src/api", score: 18, reason: "high complexity, 45 files" },
-  { path: "src/hooks", score: 12, reason: "distinct domain, unique patterns" },
+  { path: "src/hooks", score: 18, reason: "high complexity" },
+  { path: "src/api", score: 12, reason: "distinct domain" }
 ]
 \`\`\`
 
-**Mark "p2-scoring" as completed.**
+**Mark "scoring" as completed.**
 
 ---
 
-## Phase 3: Generate Root AGENTS.md
+## Phase 3: Generate AGENTS.md
 
-**Mark "p3-root" as in_progress.**
+**Mark "generate" as in_progress.**
 
-Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis.
-
-### Required Sections
+### Root AGENTS.md (Full Treatment)
 
 \`\`\`markdown
 # PROJECT KNOWLEDGE BASE
@@ -209,153 +195,75 @@ Root AGENTS.md gets **full treatment** with Predict-then-Compare synthesis.
 **Branch:** {BRANCH}
 
 ## OVERVIEW
-
-{1-2 sentences: what project does, core tech stack}
+{1-2 sentences: what + core stack}
 
 ## STRUCTURE
-
 \\\`\\\`\\\`
-{project-root}/
-├── {dir}/      # {non-obvious purpose only}
-└── {entry}     # entry point
+{root}/
+├── {dir}/    # {non-obvious purpose only}
+└── {entry}
 \\\`\\\`\\\`
 
 ## WHERE TO LOOK
-
 | Task | Location | Notes |
 |------|----------|-------|
-| Add feature X | \\\`src/x/\\\` | {pattern hint} |
 
 ## CODE MAP
-
-{Generated from LSP analysis - shows key symbols and their relationships}
+{From LSP - skip if unavailable or project <10 files}
 
 | Symbol | Type | Location | Refs | Role |
 |--------|------|----------|------|------|
-| {MainClass} | Class | \\\`src/index.ts\\\` | {N} | {Central orchestrator} |
-| {createX} | Function | \\\`src/utils.ts\\\` | {N} | {Factory pattern} |
-| {Config} | Interface | \\\`src/types.ts\\\` | {N} | {Configuration contract} |
-
-### Module Dependencies
-
-\\\`\\\`\\\`
-{entry} ──imports──> {core/}
-   │                    │
-   └──imports──> {utils/} <──imports── {features/}
-\\\`\\\`\\\`
-
-<code-map-note>
-**Skip CODE MAP if**: LSP unavailable OR project too small (<10 files) OR no clear module boundaries.
-</code-map-note>
 
 ## CONVENTIONS
-
-{ONLY deviations from standard - skip generic advice}
-
-- **{rule}**: {specific detail}
+{ONLY deviations from standard}
 
 ## ANTI-PATTERNS (THIS PROJECT)
-
-{Things explicitly forbidden HERE}
-
-- **{pattern}**: {why} → {alternative}
+{Explicitly forbidden here}
 
 ## UNIQUE STYLES
-
-{Project-specific coding styles}
-
-- **{style}**: {how different}
+{Project-specific}
 
 ## COMMANDS
-
 \\\`\\\`\\\`bash
-{dev-command}
-{test-command}
-{build-command}
+{dev/test/build}
 \\\`\\\`\\\`
 
 ## NOTES
-
-{Gotchas, non-obvious info}
+{Gotchas}
 \`\`\`
 
-### Quality Gates
+**Quality gates**: 50-150 lines, no generic advice, no obvious info.
 
-- [ ] Size: 50-150 lines
-- [ ] No generic advice ("write clean code")
-- [ ] No obvious info ("tests/ has tests")
-- [ ] Every item is project-specific
+### Subdirectory AGENTS.md (Parallel)
 
-**Mark "p3-root" as completed.**
+Launch document-writer agents for each location:
+
+\`\`\`
+for loc in AGENTS_LOCATIONS (except root):
+  background_task(agent="document-writer", prompt=\\\`
+    Generate AGENTS.md for: \${loc.path}
+    - Reason: \${loc.reason}
+    - 30-80 lines max
+    - NEVER repeat parent content
+    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
+  \\\`)
+\`\`\`
+
+**Wait for all. Mark "generate" as completed.**
 
 ---
 
-## Phase 4: Generate Subdirectory AGENTS.md
+## Phase 4: Review & Deduplicate
 
-**Mark "p4-subdirs" as in_progress.**
+**Mark "review" as in_progress.**
 
-For each location in AGENTS_LOCATIONS (except root), launch **parallel document-writer agents**:
+For each generated file:
+- Remove generic advice
+- Remove parent duplicates
+- Trim to size limits
+- Verify telegraphic style
 
-\`\`\`typescript
-for (const loc of AGENTS_LOCATIONS.filter(l => l.path !== ".")) {
-  background_task({
-    agent: "document-writer",
-    prompt: \\\`
-      Generate AGENTS.md for: \${loc.path}
-      
-      CONTEXT:
-      - Complexity reason: \${loc.reason}
-      - Parent AGENTS.md: ./AGENTS.md (already covers project overview)
-      
-      CRITICAL RULES:
-      1. Focus ONLY on this directory's specific context
-      2. NEVER repeat parent AGENTS.md content
-      3. Shorter is better - 30-80 lines max
-      4. Telegraphic style - sacrifice grammar
-      
-      REQUIRED SECTIONS:
-      - OVERVIEW (1 line: what this directory does)
-      - STRUCTURE (only if >5 subdirs)
-      - WHERE TO LOOK (directory-specific tasks)
-      - CONVENTIONS (only if DIFFERENT from root)
-      - ANTI-PATTERNS (directory-specific only)
-      
-      OUTPUT: Write to \${loc.path}/AGENTS.md
-    \\\`
-  })
-}
-\`\`\`
-
-**Wait for all agents. Mark "p4-subdirs" as completed.**
-
----
-
-## Phase 5: Review & Deduplicate
-
-**Mark "p5-review" as in_progress.**
-
-### Validation Checklist
-
-For EACH generated AGENTS.md:
-
-| Check | Action if Fail |
-|-------|----------------|
-| Contains generic advice | REMOVE the line |
-| Repeats parent content | REMOVE the line |
-| Missing required section | ADD it |
-| Over 150 lines (root) / 80 lines (subdir) | TRIM |
-| Verbose explanations | REWRITE telegraphic |
-
-### Cross-Reference Validation
-
-\`\`\`
-For each child AGENTS.md:
-  For each line in child:
-    If similar line exists in parent:
-      REMOVE from child (parent already covers)
-\`\`\`
-
-**Mark "p5-review" as completed.**
+**Mark "review" as completed.**
 
 ---
 
@@ -364,31 +272,29 @@ For each child AGENTS.md:
 \`\`\`
 === init-deep Complete ===
 
-Files Generated:
+Mode: {update | create-new}
+
+Files:
   ✓ ./AGENTS.md (root, {N} lines)
   ✓ ./src/hooks/AGENTS.md ({N} lines)
-  ✓ ./src/tools/AGENTS.md ({N} lines)
 
-Directories Analyzed: {N}
+Dirs Analyzed: {N}
 AGENTS.md Created: {N}
-Total Lines: {N}
+AGENTS.md Updated: {N}
 
 Hierarchy:
   ./AGENTS.md
-  ├── src/hooks/AGENTS.md
-  └── src/tools/AGENTS.md
+  └── src/hooks/AGENTS.md
 \`\`\`
 
 ---
 
-## Anti-Patterns for THIS Command
+## Anti-Patterns
 
-- **Over-documenting**: Not every directory needs AGENTS.md
-- **Redundancy**: Child must NOT repeat parent
+- **Static agent count**: MUST vary agents based on project size/depth
+- **Sequential execution**: MUST parallel (explore + LSP concurrent)
+- **Ignoring existing**: ALWAYS read existing first, even with --create-new
+- **Over-documenting**: Not every dir needs AGENTS.md
+- **Redundancy**: Child never repeats parent
 - **Generic content**: Remove anything that applies to ALL projects
-- **Sequential execution**: MUST use parallel agents
-- **Deep nesting**: Rarely need AGENTS.md at depth 4+
-- **Verbose style**: "This directory contains..." → just list it
-- **Ignoring LSP**: If LSP available, USE IT - semantic analysis > text grep
-- **LSP without fallback**: Always have explore agent backup if LSP unavailable
-- **Over-referencing**: Don't trace refs for EVERY symbol - focus on exports only`
+- **Verbose style**: Telegraphic or die`

src/features/builtin-commands/templates/ralph-loop.ts

@@ -0,0 +1,38 @@
+export const RALPH_LOOP_TEMPLATE = `You are starting a Ralph Loop - a self-referential development loop that runs until task completion.
+
+## How Ralph Loop Works
+
+1. You will work on the task continuously
+2. When you believe the task is FULLY complete, output: \`<promise>{{COMPLETION_PROMISE}}</promise>\`
+3. If you don't output the promise, the loop will automatically inject another prompt to continue
+4. Maximum iterations: Configurable (default 100)
+
+## Rules
+
+- Focus on completing the task fully, not partially
+- Don't output the completion promise until the task is truly done
+- Each iteration should make meaningful progress toward the goal
+- If stuck, try different approaches
+- Use todos to track your progress
+
+## Exit Conditions
+
+1. **Completion**: Output \`<promise>DONE</promise>\` (or custom promise text) when fully complete
+2. **Max Iterations**: Loop stops automatically at limit
+3. **Cancel**: User runs \`/cancel-ralph\` command
+
+## Your Task
+
+Parse the arguments below and begin working on the task. The format is:
+\`"task description" [--completion-promise=TEXT] [--max-iterations=N]\`
+
+Default completion promise is "DONE" and default max iterations is 100.`
+
+export const CANCEL_RALPH_TEMPLATE = `Cancel the currently active Ralph Loop.
+
+This will:
+1. Stop the loop from continuing
+2. Clear the loop state file
+3. Allow the session to end normally
+
+Check if a loop is active and cancel it. Inform the user of the result.`

src/features/builtin-commands/types.ts

@@ -1,6 +1,6 @@
 import type { CommandDefinition } from "../claude-code-command-loader"
 
-export type BuiltinCommandName = "init-deep"
+export type BuiltinCommandName = "init-deep" | "ralph-loop" | "cancel-ralph"
 
 export interface BuiltinCommandConfig {
   disabled_commands?: BuiltinCommandName[]

src/features/builtin-skills/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export { createBuiltinSkills } from "./skills"

src/features/builtin-skills/skills.ts

@@ -0,0 +1,19 @@
+import type { BuiltinSkill } from "./types"
+
+const playwrightSkill: BuiltinSkill = {
+  name: "playwright",
+  description: "Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.",
+  template: `# Playwright Browser Automation
+
+This skill provides browser automation capabilities via the Playwright MCP server.`,
+  mcpConfig: {
+    playwright: {
+      command: "npx",
+      args: ["@playwright/mcp@latest"],
+    },
+  },
+}
+
+export function createBuiltinSkills(): BuiltinSkill[] {
+  return [playwrightSkill]
+}

src/features/builtin-skills/types.ts

@@ -0,0 +1,16 @@
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
+export interface BuiltinSkill {
+  name: string
+  description: string
+  template: string
+  license?: string
+  compatibility?: string
+  metadata?: Record<string, unknown>
+  allowedTools?: string[]
+  agent?: string
+  model?: string
+  subtask?: boolean
+  argumentHint?: string
+  mcpConfig?: SkillMcpConfig
+}

src/features/claude-code-command-loader/loader.ts

@@ -1,24 +1,59 @@
-import { existsSync, readdirSync, readFileSync } from "fs"
+import { existsSync, readdirSync, readFileSync, realpathSync, type Dirent } from "fs"
 import { join, basename } from "path"
 import { parseFrontmatter } from "../../shared/frontmatter"
 import { sanitizeModelField } from "../../shared/model-sanitizer"
 import { isMarkdownFile } from "../../shared/file-utils"
 import { getClaudeConfigDir } from "../../shared"
+import { log } from "../../shared/logger"
 import type { CommandScope, CommandDefinition, CommandFrontmatter, LoadedCommand } from "./types"
 
-function loadCommandsFromDir(commandsDir: string, scope: CommandScope): LoadedCommand[] {
+function loadCommandsFromDir(
+  commandsDir: string,
+  scope: CommandScope,
+  visited: Set<string> = new Set(),
+  prefix: string = ""
+): LoadedCommand[] {
   if (!existsSync(commandsDir)) {
     return []
   }
 
-  const entries = readdirSync(commandsDir, { withFileTypes: true })
+  let realPath: string
+  try {
+    realPath = realpathSync(commandsDir)
+  } catch (error) {
+    log(`Failed to resolve command directory: ${commandsDir}`, error)
+    return []
+  }
+
+  if (visited.has(realPath)) {
+    return []
+  }
+  visited.add(realPath)
+
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(commandsDir, { withFileTypes: true })
+  } catch (error) {
+    log(`Failed to read command directory: ${commandsDir}`, error)
+    return []
+  }
+
   const commands: LoadedCommand[] = []
 
   for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".")) continue
+      const subDirPath = join(commandsDir, entry.name)
+      const subPrefix = prefix ? `${prefix}:${entry.name}` : entry.name
+      commands.push(...loadCommandsFromDir(subDirPath, scope, visited, subPrefix))
+      continue
+    }
+
     if (!isMarkdownFile(entry)) continue
 
     const commandPath = join(commandsDir, entry.name)
-    const commandName = basename(entry.name, ".md")
+    const baseCommandName = basename(entry.name, ".md")
+    const commandName = prefix ? `${prefix}:${baseCommandName}` : baseCommandName
 
     try {
       const content = readFileSync(commandPath, "utf-8")
@@ -43,6 +78,7 @@ $ARGUMENTS
         model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
         subtask: data.subtask,
         argumentHint: data["argument-hint"],
+        handoffs: data.handoffs,
       }
 
       commands.push({
@@ -51,7 +87,8 @@ $ARGUMENTS
         definition,
         scope,
       })
-    } catch {
+    } catch (error) {
+      log(`Failed to parse command: ${commandPath}`, error)
       continue
     }
   }
@@ -62,7 +99,8 @@ $ARGUMENTS
 function commandsToRecord(commands: LoadedCommand[]): Record<string, CommandDefinition> {
   const result: Record<string, CommandDefinition> = {}
   for (const cmd of commands) {
-    result[cmd.name] = cmd.definition
+    const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = cmd.definition
+    result[cmd.name] = openCodeCompatible as CommandDefinition
   }
   return result
 }

src/features/claude-code-command-loader/types.ts

@@ -1,5 +1,21 @@
 export type CommandScope = "user" | "project" | "opencode" | "opencode-project"
 
+/**
+ * Handoff definition for command workflows.
+ * Based on speckit's handoff pattern for multi-agent orchestration.
+ * @see https://github.com/github/spec-kit
+ */
+export interface HandoffDefinition {
+  /** Human-readable label for the handoff action */
+  label: string
+  /** Target agent/command identifier (e.g., "speckit.tasks") */
+  agent: string
+  /** Pre-filled prompt text for the handoff */
+  prompt: string
+  /** If true, automatically executes after command completion; if false, shows as suggestion */
+  send?: boolean
+}
+
 export interface CommandDefinition {
   name: string
   description?: string
@@ -8,6 +24,8 @@ export interface CommandDefinition {
   model?: string
   subtask?: boolean
   argumentHint?: string
+  /** Handoff definitions for workflow transitions */
+  handoffs?: HandoffDefinition[]
 }
 
 export interface CommandFrontmatter {
@@ -16,6 +34,8 @@ export interface CommandFrontmatter {
   agent?: string
   model?: string
   subtask?: boolean
+  /** Handoff definitions for workflow transitions */
+  handoffs?: HandoffDefinition[]
 }
 
 export interface LoadedCommand {

src/features/claude-code-mcp-loader/loader.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+
+const TEST_DIR = join(tmpdir(), "mcp-loader-test-" + Date.now())
+
+describe("getSystemMcpServerNames", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true })
+  })
+
+  it("returns empty set when no .mcp.json files exist", async () => {
+    // #given
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names).toBeInstanceOf(Set)
+      expect(names.size).toBe(0)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("returns server names from project .mcp.json", async () => {
+    // #given
+    const mcpConfig = {
+      mcpServers: {
+        playwright: {
+          command: "npx",
+          args: ["@playwright/mcp@latest"],
+        },
+        sqlite: {
+          command: "uvx",
+          args: ["mcp-server-sqlite"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(true)
+      expect(names.has("sqlite")).toBe(true)
+      expect(names.size).toBe(2)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("returns server names from .claude/.mcp.json", async () => {
+    // #given
+    mkdirSync(join(TEST_DIR, ".claude"), { recursive: true })
+    const mcpConfig = {
+      mcpServers: {
+        memory: {
+          command: "npx",
+          args: ["-y", "@anthropic-ai/mcp-server-memory"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".claude", ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("memory")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("excludes disabled MCP servers", async () => {
+    // #given
+    const mcpConfig = {
+      mcpServers: {
+        playwright: {
+          command: "npx",
+          args: ["@playwright/mcp@latest"],
+          disabled: true,
+        },
+        active: {
+          command: "npx",
+          args: ["some-mcp"],
+        },
+      },
+    }
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(mcpConfig))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(false)
+      expect(names.has("active")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it("merges server names from multiple .mcp.json files", async () => {
+    // #given
+    mkdirSync(join(TEST_DIR, ".claude"), { recursive: true })
+    
+    const projectMcp = {
+      mcpServers: {
+        playwright: { command: "npx", args: ["@playwright/mcp@latest"] },
+      },
+    }
+    const localMcp = {
+      mcpServers: {
+        memory: { command: "npx", args: ["-y", "@anthropic-ai/mcp-server-memory"] },
+      },
+    }
+    
+    writeFileSync(join(TEST_DIR, ".mcp.json"), JSON.stringify(projectMcp))
+    writeFileSync(join(TEST_DIR, ".claude", ".mcp.json"), JSON.stringify(localMcp))
+
+    const originalCwd = process.cwd()
+    process.chdir(TEST_DIR)
+
+    try {
+      // #when
+      const { getSystemMcpServerNames } = await import("./loader")
+      const names = getSystemMcpServerNames()
+
+      // #then
+      expect(names.has("playwright")).toBe(true)
+      expect(names.has("memory")).toBe(true)
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+})

src/features/claude-code-mcp-loader/loader.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "fs"
+import { existsSync, readFileSync } from "fs"
 import { join } from "path"
 import { getClaudeConfigDir } from "../../shared"
 import type {
@@ -42,6 +42,30 @@ async function loadMcpConfigFile(
   }
 }
 
+export function getSystemMcpServerNames(): Set<string> {
+  const names = new Set<string>()
+  const paths = getMcpConfigPaths()
+
+  for (const { path } of paths) {
+    if (!existsSync(path)) continue
+
+    try {
+      const content = readFileSync(path, "utf-8")
+      const config = JSON.parse(content) as ClaudeCodeMcpConfig
+      if (!config?.mcpServers) continue
+
+      for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+        if (serverConfig.disabled) continue
+        names.add(name)
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return names
+}
+
 export async function loadMcpConfigs(): Promise<McpLoadResult> {
   const servers: McpLoadResult["servers"] = {}
   const loadedServers: LoadedMcpServer[] = []

src/features/claude-code-plugin-loader/loader.ts

@@ -9,7 +9,7 @@ import { log } from "../../shared/logger"
 import { expandEnvVarsInObject } from "../claude-code-mcp-loader/env-expander"
 import { transformMcpServer } from "../claude-code-mcp-loader/transformer"
 import type { CommandDefinition, CommandFrontmatter } from "../claude-code-command-loader/types"
-import type { SkillMetadata } from "../claude-code-skill-loader/types"
+import type { SkillMetadata } from "../opencode-skill-loader/types"
 import type { AgentFrontmatter } from "../claude-code-agent-loader/types"
 import type { ClaudeCodeMcpConfig, McpServerConfig } from "../claude-code-mcp-loader/types"
 import type {
@@ -246,7 +246,7 @@ $ARGUMENTS
 
         const formattedDescription = `(plugin: ${plugin.name}) ${data.description || ""}`
 
-        commands[namespacedName] = {
+        const definition = {
           name: namespacedName,
           description: formattedDescription,
           template: wrappedTemplate,
@@ -255,6 +255,8 @@ $ARGUMENTS
           subtask: data.subtask,
           argumentHint: data["argument-hint"],
         }
+        const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = definition
+        commands[namespacedName] = openCodeCompatible as CommandDefinition
 
         log(`Loaded plugin command: ${namespacedName}`, { path: commandPath })
       } catch (error) {
@@ -306,12 +308,14 @@ ${body.trim()}
 $ARGUMENTS
 </user-request>`
 
-        skills[namespacedName] = {
+        const definition = {
           name: namespacedName,
           description: formattedDescription,
           template: wrappedTemplate,
           model: sanitizeModelField(data.model),
         }
+        const { name: _name, ...openCodeCompatible } = definition
+        skills[namespacedName] = openCodeCompatible as CommandDefinition
 
         log(`Loaded plugin skill: ${namespacedName}`, { path: resolvedPath })
       } catch (error) {

src/features/claude-code-skill-loader/loader.ts

@@ -1,86 +0,0 @@
-import { existsSync, readdirSync, readFileSync } from "fs"
-import { join } from "path"
-import { parseFrontmatter } from "../../shared/frontmatter"
-import { sanitizeModelField } from "../../shared/model-sanitizer"
-import { resolveSymlink } from "../../shared/file-utils"
-import { getClaudeConfigDir } from "../../shared"
-import type { CommandDefinition } from "../claude-code-command-loader/types"
-import type { SkillScope, SkillMetadata, LoadedSkillAsCommand } from "./types"
-
-function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkillAsCommand[] {
-  if (!existsSync(skillsDir)) {
-    return []
-  }
-
-  const entries = readdirSync(skillsDir, { withFileTypes: true })
-  const skills: LoadedSkillAsCommand[] = []
-
-  for (const entry of entries) {
-    if (entry.name.startsWith(".")) continue
-
-    const skillPath = join(skillsDir, entry.name)
-
-    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
-
-    const resolvedPath = resolveSymlink(skillPath)
-
-    const skillMdPath = join(resolvedPath, "SKILL.md")
-    if (!existsSync(skillMdPath)) continue
-
-    try {
-      const content = readFileSync(skillMdPath, "utf-8")
-      const { data, body } = parseFrontmatter<SkillMetadata>(content)
-
-      const skillName = data.name || entry.name
-      const originalDescription = data.description || ""
-      const formattedDescription = `(${scope} - Skill) ${originalDescription}`
-
-      const wrappedTemplate = `<skill-instruction>
-Base directory for this skill: ${resolvedPath}/
-File references (@path) in this skill are relative to this directory.
-
-${body.trim()}
-</skill-instruction>
-
-<user-request>
-$ARGUMENTS
-</user-request>`
-
-      const definition: CommandDefinition = {
-        name: skillName,
-        description: formattedDescription,
-        template: wrappedTemplate,
-        model: sanitizeModelField(data.model),
-      }
-
-      skills.push({
-        name: skillName,
-        path: resolvedPath,
-        definition,
-        scope,
-      })
-    } catch {
-      continue
-    }
-  }
-
-  return skills
-}
-
-export function loadUserSkillsAsCommands(): Record<string, CommandDefinition> {
-  const userSkillsDir = join(getClaudeConfigDir(), "skills")
-  const skills = loadSkillsFromDir(userSkillsDir, "user")
-  return skills.reduce((acc, skill) => {
-    acc[skill.name] = skill.definition
-    return acc
-  }, {} as Record<string, CommandDefinition>)
-}
-
-export function loadProjectSkillsAsCommands(): Record<string, CommandDefinition> {
-  const projectSkillsDir = join(process.cwd(), ".claude", "skills")
-  const skills = loadSkillsFromDir(projectSkillsDir, "project")
-  return skills.reduce((acc, skill) => {
-    acc[skill.name] = skill.definition
-    return acc
-  }, {} as Record<string, CommandDefinition>)
-}

src/features/claude-code-skill-loader/types.ts

@@ -1,16 +0,0 @@
-import type { CommandDefinition } from "../claude-code-command-loader/types"
-
-export type SkillScope = "user" | "project"
-
-export interface SkillMetadata {
-  name: string
-  description: string
-  model?: string
-}
-
-export interface LoadedSkillAsCommand {
-  name: string
-  path: string
-  definition: CommandDefinition
-  scope: SkillScope
-}

src/features/opencode-skill-loader/index.ts

@@ -1,2 +1,3 @@
 export * from "./types"
 export * from "./loader"
+export * from "./merger"

src/features/opencode-skill-loader/loader.test.ts

@@ -0,0 +1,273 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { mkdirSync, writeFileSync, rmSync } from "fs"
+import { join } from "path"
+import { tmpdir } from "os"
+
+const TEST_DIR = join(tmpdir(), "skill-loader-test-" + Date.now())
+const SKILLS_DIR = join(TEST_DIR, ".opencode", "skill")
+
+function createTestSkill(name: string, content: string, mcpJson?: object): string {
+  const skillDir = join(SKILLS_DIR, name)
+  mkdirSync(skillDir, { recursive: true })
+  const skillPath = join(skillDir, "SKILL.md")
+  writeFileSync(skillPath, content)
+  if (mcpJson) {
+    writeFileSync(join(skillDir, "mcp.json"), JSON.stringify(mcpJson, null, 2))
+  }
+  return skillDir
+}
+
+describe("skill loader MCP parsing", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true })
+  })
+
+  describe("parseSkillMcpConfig", () => {
+    it("parses skill with nested MCP config", async () => {
+      // #given
+      const skillContent = `---
+name: test-skill
+description: A test skill with MCP
+mcp:
+  sqlite:
+    command: uvx
+    args:
+      - mcp-server-sqlite
+      - --db-path
+      - ./data.db
+  memory:
+    command: npx
+    args: [-y, "@anthropic-ai/mcp-server-memory"]
+---
+This is the skill body.
+`
+      createTestSkill("test-mcp-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "test-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite?.command).toBe("uvx")
+        expect(skill?.mcpConfig?.sqlite?.args).toEqual([
+          "mcp-server-sqlite",
+          "--db-path",
+          "./data.db"
+        ])
+        expect(skill?.mcpConfig?.memory).toBeDefined()
+        expect(skill?.mcpConfig?.memory?.command).toBe("npx")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("returns undefined mcpConfig for skill without MCP", async () => {
+      // #given
+      const skillContent = `---
+name: simple-skill
+description: A simple skill without MCP
+---
+This is a simple skill.
+`
+      createTestSkill("simple-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "simple-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("preserves env var placeholders without expansion", async () => {
+      // #given
+      const skillContent = `---
+name: env-skill
+mcp:
+  api-server:
+    command: node
+    args: [server.js]
+    env:
+      API_KEY: "\${API_KEY}"
+      DB_PATH: "\${HOME}/data.db"
+---
+Skill with env vars.
+`
+      createTestSkill("env-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "env-skill")
+
+        // #then
+        expect(skill?.mcpConfig?.["api-server"]?.env?.API_KEY).toBe("${API_KEY}")
+        expect(skill?.mcpConfig?.["api-server"]?.env?.DB_PATH).toBe("${HOME}/data.db")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("handles malformed YAML gracefully", async () => {
+      // #given - malformed YAML causes entire frontmatter to fail parsing
+      const skillContent = `---
+name: bad-yaml
+mcp: [this is not valid yaml for mcp
+---
+Skill body.
+`
+      createTestSkill("bad-yaml-skill", skillContent)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        // #then - when YAML fails, skill uses directory name as fallback
+        const skill = skills.find(s => s.name === "bad-yaml-skill")
+
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+  })
+
+  describe("mcp.json file loading (AmpCode compat)", () => {
+    it("loads MCP config from mcp.json with mcpServers format", async () => {
+      // #given
+      const skillContent = `---
+name: ampcode-skill
+description: Skill with mcp.json
+---
+Skill body.
+`
+      const mcpJson = {
+        mcpServers: {
+          playwright: {
+            command: "npx",
+            args: ["@playwright/mcp@latest"]
+          }
+        }
+      }
+      createTestSkill("ampcode-skill", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "ampcode-skill")
+
+        // #then
+        expect(skill).toBeDefined()
+        expect(skill?.mcpConfig).toBeDefined()
+        expect(skill?.mcpConfig?.playwright).toBeDefined()
+        expect(skill?.mcpConfig?.playwright?.command).toBe("npx")
+        expect(skill?.mcpConfig?.playwright?.args).toEqual(["@playwright/mcp@latest"])
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("mcp.json takes priority over YAML frontmatter", async () => {
+      // #given
+      const skillContent = `---
+name: priority-skill
+mcp:
+  from-yaml:
+    command: yaml-cmd
+    args: [yaml-arg]
+---
+Skill body.
+`
+      const mcpJson = {
+        mcpServers: {
+          "from-json": {
+            command: "json-cmd",
+            args: ["json-arg"]
+          }
+        }
+      }
+      createTestSkill("priority-skill", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "priority-skill")
+
+        // #then - mcp.json should take priority
+        expect(skill?.mcpConfig?.["from-json"]).toBeDefined()
+        expect(skill?.mcpConfig?.["from-yaml"]).toBeUndefined()
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+
+    it("supports direct format without mcpServers wrapper", async () => {
+      // #given
+      const skillContent = `---
+name: direct-format
+---
+Skill body.
+`
+      const mcpJson = {
+        sqlite: {
+          command: "uvx",
+          args: ["mcp-server-sqlite"]
+        }
+      }
+      createTestSkill("direct-format", skillContent, mcpJson)
+
+      // #when
+      const { discoverSkills } = await import("./loader")
+      const originalCwd = process.cwd()
+      process.chdir(TEST_DIR)
+
+      try {
+        const skills = discoverSkills({ includeClaudeCodePaths: false })
+        const skill = skills.find(s => s.name === "direct-format")
+
+        // #then
+        expect(skill?.mcpConfig?.sqlite).toBeDefined()
+        expect(skill?.mcpConfig?.sqlite?.command).toBe("uvx")
+      } finally {
+        process.chdir(originalCwd)
+      }
+    })
+  })
+})

src/features/opencode-skill-loader/loader.ts

@@ -0,0 +1,288 @@
+import { existsSync, readdirSync, readFileSync } from "fs"
+import { join, basename } from "path"
+import { homedir } from "os"
+import yaml from "js-yaml"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import { sanitizeModelField } from "../../shared/model-sanitizer"
+import { resolveSymlink, isMarkdownFile } from "../../shared/file-utils"
+import { getClaudeConfigDir } from "../../shared"
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+import type { SkillScope, SkillMetadata, LoadedSkill } from "./types"
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
+function parseSkillMcpConfigFromFrontmatter(content: string): SkillMcpConfig | undefined {
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!frontmatterMatch) return undefined
+
+  try {
+    const parsed = yaml.load(frontmatterMatch[1]) as Record<string, unknown>
+    if (parsed && typeof parsed === "object" && "mcp" in parsed && parsed.mcp) {
+      return parsed.mcp as SkillMcpConfig
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+function loadMcpJsonFromDir(skillDir: string): SkillMcpConfig | undefined {
+  const mcpJsonPath = join(skillDir, "mcp.json")
+  if (!existsSync(mcpJsonPath)) return undefined
+
+  try {
+    const content = readFileSync(mcpJsonPath, "utf-8")
+    const parsed = JSON.parse(content) as Record<string, unknown>
+    
+    // AmpCode format: { "mcpServers": { "name": { ... } } }
+    if (parsed && typeof parsed === "object" && "mcpServers" in parsed && parsed.mcpServers) {
+      return parsed.mcpServers as SkillMcpConfig
+    }
+    
+    // Also support direct format: { "name": { command: ..., args: ... } }
+    if (parsed && typeof parsed === "object" && !("mcpServers" in parsed)) {
+      const hasCommandField = Object.values(parsed).some(
+        (v) => v && typeof v === "object" && "command" in (v as Record<string, unknown>)
+      )
+      if (hasCommandField) {
+        return parsed as SkillMcpConfig
+      }
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+function parseAllowedTools(allowedTools: string | undefined): string[] | undefined {
+  if (!allowedTools) return undefined
+  return allowedTools.split(/\s+/).filter(Boolean)
+}
+
+function loadSkillFromPath(
+  skillPath: string,
+  resolvedPath: string,
+  defaultName: string,
+  scope: SkillScope
+): LoadedSkill | null {
+  try {
+    const content = readFileSync(skillPath, "utf-8")
+    const { data, body } = parseFrontmatter<SkillMetadata>(content)
+    const frontmatterMcp = parseSkillMcpConfigFromFrontmatter(content)
+    const mcpJsonMcp = loadMcpJsonFromDir(resolvedPath)
+    const mcpConfig = mcpJsonMcp || frontmatterMcp
+
+    const skillName = data.name || defaultName
+    const originalDescription = data.description || ""
+    const isOpencodeSource = scope === "opencode" || scope === "opencode-project"
+    const formattedDescription = `(${scope} - Skill) ${originalDescription}`
+
+    const wrappedTemplate = `<skill-instruction>
+Base directory for this skill: ${resolvedPath}/
+File references (@path) in this skill are relative to this directory.
+
+${body.trim()}
+</skill-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`
+
+    const definition: CommandDefinition = {
+      name: skillName,
+      description: formattedDescription,
+      template: wrappedTemplate,
+      model: sanitizeModelField(data.model, isOpencodeSource ? "opencode" : "claude-code"),
+      agent: data.agent,
+      subtask: data.subtask,
+      argumentHint: data["argument-hint"],
+    }
+
+    return {
+      name: skillName,
+      path: skillPath,
+      resolvedPath,
+      definition,
+      scope,
+      license: data.license,
+      compatibility: data.compatibility,
+      metadata: data.metadata,
+      allowedTools: parseAllowedTools(data["allowed-tools"]),
+      mcpConfig,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load skills from a directory, supporting BOTH patterns:
+ * - Directory with SKILL.md: skill-name/SKILL.md
+ * - Directory with {SKILLNAME}.md: skill-name/{SKILLNAME}.md
+ * - Direct markdown file: skill-name.md
+ */
+function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkill[] {
+  if (!existsSync(skillsDir)) {
+    return []
+  }
+
+  const entries = readdirSync(skillsDir, { withFileTypes: true })
+  const skills: LoadedSkill[] = []
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue
+
+    const entryPath = join(skillsDir, entry.name)
+
+    if (entry.isDirectory() || entry.isSymbolicLink()) {
+      const resolvedPath = resolveSymlink(entryPath)
+      const dirName = entry.name
+
+      const skillMdPath = join(resolvedPath, "SKILL.md")
+      if (existsSync(skillMdPath)) {
+        const skill = loadSkillFromPath(skillMdPath, resolvedPath, dirName, scope)
+        if (skill) skills.push(skill)
+        continue
+      }
+
+      const namedSkillMdPath = join(resolvedPath, `${dirName}.md`)
+      if (existsSync(namedSkillMdPath)) {
+        const skill = loadSkillFromPath(namedSkillMdPath, resolvedPath, dirName, scope)
+        if (skill) skills.push(skill)
+        continue
+      }
+
+      continue
+    }
+
+    if (isMarkdownFile(entry)) {
+      const skillName = basename(entry.name, ".md")
+      const skill = loadSkillFromPath(entryPath, skillsDir, skillName, scope)
+      if (skill) skills.push(skill)
+    }
+  }
+
+  return skills
+}
+
+function skillsToRecord(skills: LoadedSkill[]): Record<string, CommandDefinition> {
+  const result: Record<string, CommandDefinition> = {}
+  for (const skill of skills) {
+    const { name: _name, argumentHint: _argumentHint, ...openCodeCompatible } = skill.definition
+    result[skill.name] = openCodeCompatible as CommandDefinition
+  }
+  return result
+}
+
+/**
+ * Load skills from Claude Code user directory (~/.claude/skills/)
+ */
+export function loadUserSkills(): Record<string, CommandDefinition> {
+  const userSkillsDir = join(getClaudeConfigDir(), "skills")
+  const skills = loadSkillsFromDir(userSkillsDir, "user")
+  return skillsToRecord(skills)
+}
+
+/**
+ * Load skills from Claude Code project directory (.claude/skills/)
+ */
+export function loadProjectSkills(): Record<string, CommandDefinition> {
+  const projectSkillsDir = join(process.cwd(), ".claude", "skills")
+  const skills = loadSkillsFromDir(projectSkillsDir, "project")
+  return skillsToRecord(skills)
+}
+
+/**
+ * Load skills from OpenCode global directory (~/.config/opencode/skill/)
+ */
+export function loadOpencodeGlobalSkills(): Record<string, CommandDefinition> {
+  const opencodeSkillsDir = join(homedir(), ".config", "opencode", "skill")
+  const skills = loadSkillsFromDir(opencodeSkillsDir, "opencode")
+  return skillsToRecord(skills)
+}
+
+/**
+ * Load skills from OpenCode project directory (.opencode/skill/)
+ */
+export function loadOpencodeProjectSkills(): Record<string, CommandDefinition> {
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
+  const skills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
+  return skillsToRecord(skills)
+}
+
+/**
+ * Discover all skills from all sources with priority ordering.
+ * Priority order: opencode-project > project > opencode > user
+ * 
+ * @returns Array of LoadedSkill objects for use in slashcommand discovery
+ */
+export function discoverAllSkills(): LoadedSkill[] {
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
+  const projectDir = join(process.cwd(), ".claude", "skills")
+  const opencodeGlobalDir = join(homedir(), ".config", "opencode", "skill")
+  const userDir = join(getClaudeConfigDir(), "skills")
+
+  const opencodeProjectSkills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
+  const projectSkills = loadSkillsFromDir(projectDir, "project")
+  const opencodeGlobalSkills = loadSkillsFromDir(opencodeGlobalDir, "opencode")
+  const userSkills = loadSkillsFromDir(userDir, "user")
+
+  return [...opencodeProjectSkills, ...projectSkills, ...opencodeGlobalSkills, ...userSkills]
+}
+
+export interface DiscoverSkillsOptions {
+  includeClaudeCodePaths?: boolean
+}
+
+/**
+ * Discover skills with optional filtering.
+ * When includeClaudeCodePaths is false, only loads from OpenCode paths.
+ */
+export function discoverSkills(options: DiscoverSkillsOptions = {}): LoadedSkill[] {
+  const { includeClaudeCodePaths = true } = options
+
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
+  const opencodeGlobalDir = join(homedir(), ".config", "opencode", "skill")
+
+  const opencodeProjectSkills = loadSkillsFromDir(opencodeProjectDir, "opencode-project")
+  const opencodeGlobalSkills = loadSkillsFromDir(opencodeGlobalDir, "opencode")
+
+  if (!includeClaudeCodePaths) {
+    return [...opencodeProjectSkills, ...opencodeGlobalSkills]
+  }
+
+  const projectDir = join(process.cwd(), ".claude", "skills")
+  const userDir = join(getClaudeConfigDir(), "skills")
+
+  const projectSkills = loadSkillsFromDir(projectDir, "project")
+  const userSkills = loadSkillsFromDir(userDir, "user")
+
+  return [...opencodeProjectSkills, ...projectSkills, ...opencodeGlobalSkills, ...userSkills]
+}
+
+/**
+ * Get a skill by name from all available sources.
+ */
+export function getSkillByName(name: string, options: DiscoverSkillsOptions = {}): LoadedSkill | undefined {
+  const skills = discoverSkills(options)
+  return skills.find(s => s.name === name)
+}
+
+export function discoverUserClaudeSkills(): LoadedSkill[] {
+  const userSkillsDir = join(getClaudeConfigDir(), "skills")
+  return loadSkillsFromDir(userSkillsDir, "user")
+}
+
+export function discoverProjectClaudeSkills(): LoadedSkill[] {
+  const projectSkillsDir = join(process.cwd(), ".claude", "skills")
+  return loadSkillsFromDir(projectSkillsDir, "project")
+}
+
+export function discoverOpencodeGlobalSkills(): LoadedSkill[] {
+  const opencodeSkillsDir = join(homedir(), ".config", "opencode", "skill")
+  return loadSkillsFromDir(opencodeSkillsDir, "opencode")
+}
+
+export function discoverOpencodeProjectSkills(): LoadedSkill[] {
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "skill")
+  return loadSkillsFromDir(opencodeProjectDir, "opencode-project")
+}

src/features/opencode-skill-loader/merger.ts

@@ -0,0 +1,267 @@
+import type { LoadedSkill, SkillScope, SkillMetadata } from "./types"
+import type { SkillsConfig, SkillDefinition } from "../../config/schema"
+import type { BuiltinSkill } from "../builtin-skills/types"
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+import { readFileSync, existsSync } from "fs"
+import { dirname, resolve, isAbsolute } from "path"
+import { homedir } from "os"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import { sanitizeModelField } from "../../shared/model-sanitizer"
+import { deepMerge } from "../../shared/deep-merge"
+
+const SCOPE_PRIORITY: Record<SkillScope, number> = {
+  builtin: 1,
+  config: 2,
+  user: 3,
+  opencode: 4,
+  project: 5,
+  "opencode-project": 6,
+}
+
+function builtinToLoaded(builtin: BuiltinSkill): LoadedSkill {
+  const definition: CommandDefinition = {
+    name: builtin.name,
+    description: `(opencode - Skill) ${builtin.description}`,
+    template: builtin.template,
+    model: builtin.model,
+    agent: builtin.agent,
+    subtask: builtin.subtask,
+    argumentHint: builtin.argumentHint,
+  }
+
+  return {
+    name: builtin.name,
+    definition,
+    scope: "builtin",
+    license: builtin.license,
+    compatibility: builtin.compatibility,
+    metadata: builtin.metadata as Record<string, string> | undefined,
+    allowedTools: builtin.allowedTools,
+    mcpConfig: builtin.mcpConfig,
+  }
+}
+
+function resolveFilePath(from: string, configDir?: string): string {
+  let filePath = from
+
+  if (filePath.startsWith("{file:") && filePath.endsWith("}")) {
+    filePath = filePath.slice(6, -1)
+  }
+
+  if (filePath.startsWith("~/")) {
+    return resolve(homedir(), filePath.slice(2))
+  }
+
+  if (isAbsolute(filePath)) {
+    return filePath
+  }
+
+  const baseDir = configDir || process.cwd()
+  return resolve(baseDir, filePath)
+}
+
+function loadSkillFromFile(filePath: string): { template: string; metadata: SkillMetadata } | null {
+  try {
+    if (!existsSync(filePath)) return null
+    const content = readFileSync(filePath, "utf-8")
+    const { data, body } = parseFrontmatter<SkillMetadata>(content)
+    return { template: body, metadata: data }
+  } catch {
+    return null
+  }
+}
+
+function configEntryToLoaded(
+  name: string,
+  entry: SkillDefinition,
+  configDir?: string
+): LoadedSkill | null {
+  let template = entry.template || ""
+  let fileMetadata: SkillMetadata = {}
+
+  if (entry.from) {
+    const filePath = resolveFilePath(entry.from, configDir)
+    const loaded = loadSkillFromFile(filePath)
+    if (loaded) {
+      template = loaded.template
+      fileMetadata = loaded.metadata
+    } else {
+      return null
+    }
+  }
+
+  if (!template && !entry.from) {
+    return null
+  }
+
+  const description = entry.description || fileMetadata.description || ""
+  const resolvedPath = entry.from ? dirname(resolveFilePath(entry.from, configDir)) : configDir || process.cwd()
+
+  const wrappedTemplate = `<skill-instruction>
+Base directory for this skill: ${resolvedPath}/
+File references (@path) in this skill are relative to this directory.
+
+${template.trim()}
+</skill-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`
+
+  const definition: CommandDefinition = {
+    name,
+    description: `(config - Skill) ${description}`,
+    template: wrappedTemplate,
+    model: sanitizeModelField(entry.model || fileMetadata.model, "opencode"),
+    agent: entry.agent || fileMetadata.agent,
+    subtask: entry.subtask ?? fileMetadata.subtask,
+    argumentHint: entry["argument-hint"] || fileMetadata["argument-hint"],
+  }
+
+  const allowedTools = entry["allowed-tools"] ||
+    (fileMetadata["allowed-tools"] ? fileMetadata["allowed-tools"].split(/\s+/).filter(Boolean) : undefined)
+
+  return {
+    name,
+    path: entry.from ? resolveFilePath(entry.from, configDir) : undefined,
+    resolvedPath,
+    definition,
+    scope: "config",
+    license: entry.license || fileMetadata.license,
+    compatibility: entry.compatibility || fileMetadata.compatibility,
+    metadata: entry.metadata as Record<string, string> | undefined || fileMetadata.metadata,
+    allowedTools,
+  }
+}
+
+function normalizeConfig(config: SkillsConfig | undefined): {
+  sources: Array<string | { path: string; recursive?: boolean; glob?: string }>
+  enable: string[]
+  disable: string[]
+  entries: Record<string, boolean | SkillDefinition>
+} {
+  if (!config) {
+    return { sources: [], enable: [], disable: [], entries: {} }
+  }
+
+  if (Array.isArray(config)) {
+    return { sources: [], enable: config, disable: [], entries: {} }
+  }
+
+  const { sources = [], enable = [], disable = [], ...entries } = config
+  return { sources, enable, disable, entries }
+}
+
+function mergeSkillDefinitions(base: LoadedSkill, patch: SkillDefinition): LoadedSkill {
+  const mergedMetadata = base.metadata || patch.metadata
+    ? deepMerge(base.metadata || {}, (patch.metadata as Record<string, string>) || {})
+    : undefined
+
+  const mergedTools = base.allowedTools || patch["allowed-tools"]
+    ? [...(base.allowedTools || []), ...(patch["allowed-tools"] || [])]
+    : undefined
+
+  const description = patch.description || base.definition.description?.replace(/^\([^)]+\) /, "")
+
+  return {
+    ...base,
+    definition: {
+      ...base.definition,
+      description: `(${base.scope} - Skill) ${description}`,
+      model: patch.model || base.definition.model,
+      agent: patch.agent || base.definition.agent,
+      subtask: patch.subtask ?? base.definition.subtask,
+      argumentHint: patch["argument-hint"] || base.definition.argumentHint,
+    },
+    license: patch.license || base.license,
+    compatibility: patch.compatibility || base.compatibility,
+    metadata: mergedMetadata as Record<string, string> | undefined,
+    allowedTools: mergedTools ? [...new Set(mergedTools)] : undefined,
+  }
+}
+
+export interface MergeSkillsOptions {
+  configDir?: string
+}
+
+export function mergeSkills(
+  builtinSkills: BuiltinSkill[],
+  config: SkillsConfig | undefined,
+  userClaudeSkills: LoadedSkill[],
+  userOpencodeSkills: LoadedSkill[],
+  projectClaudeSkills: LoadedSkill[],
+  projectOpencodeSkills: LoadedSkill[],
+  options: MergeSkillsOptions = {}
+): LoadedSkill[] {
+  const skillMap = new Map<string, LoadedSkill>()
+
+  for (const builtin of builtinSkills) {
+    const loaded = builtinToLoaded(builtin)
+    skillMap.set(loaded.name, loaded)
+  }
+
+  const normalizedConfig = normalizeConfig(config)
+
+  for (const [name, entry] of Object.entries(normalizedConfig.entries)) {
+    if (entry === false) continue
+    if (entry === true) continue
+
+    if (entry.disable) continue
+
+    const loaded = configEntryToLoaded(name, entry, options.configDir)
+    if (loaded) {
+      const existing = skillMap.get(name)
+      if (existing && !entry.template && !entry.from) {
+        skillMap.set(name, mergeSkillDefinitions(existing, entry))
+      } else {
+        skillMap.set(name, loaded)
+      }
+    }
+  }
+
+  const fileSystemSkills = [
+    ...userClaudeSkills,
+    ...userOpencodeSkills,
+    ...projectClaudeSkills,
+    ...projectOpencodeSkills,
+  ]
+
+  for (const skill of fileSystemSkills) {
+    const existing = skillMap.get(skill.name)
+    if (!existing || SCOPE_PRIORITY[skill.scope] > SCOPE_PRIORITY[existing.scope]) {
+      skillMap.set(skill.name, skill)
+    }
+  }
+
+  for (const [name, entry] of Object.entries(normalizedConfig.entries)) {
+    if (entry === true) continue
+    if (entry === false) {
+      skillMap.delete(name)
+      continue
+    }
+    if (entry.disable) {
+      skillMap.delete(name)
+      continue
+    }
+
+    const existing = skillMap.get(name)
+    if (existing && !entry.template && !entry.from) {
+      skillMap.set(name, mergeSkillDefinitions(existing, entry))
+    }
+  }
+
+  for (const name of normalizedConfig.disable) {
+    skillMap.delete(name)
+  }
+
+  if (normalizedConfig.enable.length > 0) {
+    const enableSet = new Set(normalizedConfig.enable)
+    for (const name of skillMap.keys()) {
+      if (!enableSet.has(name)) {
+        skillMap.delete(name)
+      }
+    }
+  }
+
+  return Array.from(skillMap.values())
+}

src/features/opencode-skill-loader/types.ts

@@ -0,0 +1,31 @@
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+import type { SkillMcpConfig } from "../skill-mcp-manager/types"
+
+export type SkillScope = "builtin" | "config" | "user" | "project" | "opencode" | "opencode-project"
+
+export interface SkillMetadata {
+  name?: string
+  description?: string
+  model?: string
+  "argument-hint"?: string
+  agent?: string
+  subtask?: boolean
+  license?: string
+  compatibility?: string
+  metadata?: Record<string, string>
+  "allowed-tools"?: string
+  mcp?: SkillMcpConfig
+}
+
+export interface LoadedSkill {
+  name: string
+  path?: string
+  resolvedPath?: string
+  definition: CommandDefinition
+  scope: SkillScope
+  license?: string
+  compatibility?: string
+  metadata?: Record<string, string>
+  allowedTools?: string[]
+  mcpConfig?: SkillMcpConfig
+}

src/features/skill-mcp-manager/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export { SkillMcpManager } from "./manager"

src/features/skill-mcp-manager/manager.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn } from "bun:test"
+import { SkillMcpManager } from "./manager"
+import type { SkillMcpClientInfo, SkillMcpServerContext } from "./types"
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+
+describe("SkillMcpManager", () => {
+  let manager: SkillMcpManager
+
+  beforeEach(() => {
+    manager = new SkillMcpManager()
+  })
+
+  afterEach(async () => {
+    await manager.disconnectAll()
+  })
+
+  describe("getOrCreateClient", () => {
+    it("throws error when command is missing", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-1",
+      }
+      const config: ClaudeCodeMcpServer = {}
+
+      // #when / #then
+      await expect(manager.getOrCreateClient(info, config)).rejects.toThrow(
+        /missing required 'command' field/
+      )
+    })
+
+    it("includes helpful error message with example when command is missing", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "my-mcp",
+        skillName: "data-skill",
+        sessionID: "session-1",
+      }
+      const config: ClaudeCodeMcpServer = {}
+
+      // #when / #then
+      await expect(manager.getOrCreateClient(info, config)).rejects.toThrow(
+        /my-mcp[\s\S]*data-skill[\s\S]*Example/
+      )
+    })
+  })
+
+  describe("disconnectSession", () => {
+    it("removes all clients for a specific session", async () => {
+      // #given
+      const session1Info: SkillMcpClientInfo = {
+        serverName: "server1",
+        skillName: "skill1",
+        sessionID: "session-1",
+      }
+      const session2Info: SkillMcpClientInfo = {
+        serverName: "server1",
+        skillName: "skill1",
+        sessionID: "session-2",
+      }
+
+      // #when
+      await manager.disconnectSession("session-1")
+
+      // #then
+      expect(manager.isConnected(session1Info)).toBe(false)
+      expect(manager.isConnected(session2Info)).toBe(false)
+    })
+
+    it("does not throw when session has no clients", async () => {
+      // #given / #when / #then
+      await expect(manager.disconnectSession("nonexistent")).resolves.toBeUndefined()
+    })
+  })
+
+  describe("disconnectAll", () => {
+    it("clears all clients", async () => {
+      // #given - no actual clients connected (would require real MCP server)
+
+      // #when
+      await manager.disconnectAll()
+
+      // #then
+      expect(manager.getConnectedServers()).toEqual([])
+    })
+  })
+
+  describe("isConnected", () => {
+    it("returns false for unconnected server", () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "unknown",
+        skillName: "test",
+        sessionID: "session-1",
+      }
+
+      // #when / #then
+      expect(manager.isConnected(info)).toBe(false)
+    })
+  })
+
+  describe("getConnectedServers", () => {
+    it("returns empty array when no servers connected", () => {
+      // #given / #when / #then
+      expect(manager.getConnectedServers()).toEqual([])
+    })
+  })
+
+  describe("environment variable handling", () => {
+    it("always inherits process.env even when config.env is undefined", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-1",
+      }
+      const configWithoutEnv: ClaudeCodeMcpServer = {
+        command: "node",
+        args: ["-e", "process.exit(0)"],
+      }
+
+      // #when - attempt connection (will fail but exercises env merging code path)
+      // #then - should not throw "undefined" related errors for env
+      try {
+        await manager.getOrCreateClient(info, configWithoutEnv)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        expect(message).not.toContain("env")
+        expect(message).not.toContain("undefined")
+      }
+    })
+
+    it("overlays config.env on top of inherited process.env", async () => {
+      // #given
+      const info: SkillMcpClientInfo = {
+        serverName: "test-server",
+        skillName: "test-skill",
+        sessionID: "session-2",
+      }
+      const configWithEnv: ClaudeCodeMcpServer = {
+        command: "node",
+        args: ["-e", "process.exit(0)"],
+        env: {
+          CUSTOM_VAR: "custom_value",
+        },
+      }
+
+      // #when - attempt connection
+      // #then - should not throw, env merging should work
+      try {
+        await manager.getOrCreateClient(info, configWithEnv)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        expect(message).toContain("Failed to connect")
+      }
+    })
+  })
+})

src/features/skill-mcp-manager/manager.ts

@@ -0,0 +1,213 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import type { Tool, Resource, Prompt } from "@modelcontextprotocol/sdk/types.js"
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+import { expandEnvVarsInObject } from "../claude-code-mcp-loader/env-expander"
+import type { SkillMcpClientInfo, SkillMcpServerContext } from "./types"
+
+interface ManagedClient {
+  client: Client
+  transport: StdioClientTransport
+  skillName: string
+}
+
+export class SkillMcpManager {
+  private clients: Map<string, ManagedClient> = new Map()
+
+  private getClientKey(info: SkillMcpClientInfo): string {
+    return `${info.sessionID}:${info.skillName}:${info.serverName}`
+  }
+
+  async getOrCreateClient(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    const key = this.getClientKey(info)
+    const existing = this.clients.get(key)
+
+    if (existing) {
+      return existing.client
+    }
+
+    const expandedConfig = expandEnvVarsInObject(config)
+    const client = await this.createClient(info, expandedConfig)
+    return client
+  }
+
+  private async createClient(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    const key = this.getClientKey(info)
+
+    if (!config.command) {
+      throw new Error(
+        `MCP server "${info.serverName}" is missing required 'command' field.\n\n` +
+        `The MCP configuration in skill "${info.skillName}" must specify a command to execute.\n\n` +
+        `Example:\n` +
+        `  mcp:\n` +
+        `    ${info.serverName}:\n` +
+        `      command: npx\n` +
+        `      args: [-y, @some/mcp-server]`
+      )
+    }
+
+    const command = config.command
+    const args = config.args || []
+
+    // Always inherit parent process environment
+    const mergedEnv: Record<string, string> = {}
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) mergedEnv[key] = value
+    }
+    // Overlay with skill-specific env vars if present
+    if (config.env) {
+      Object.assign(mergedEnv, config.env)
+    }
+
+    const transport = new StdioClientTransport({
+      command,
+      args,
+      env: mergedEnv,
+      stderr: "ignore",
+    })
+
+    const client = new Client(
+      { name: `skill-mcp-${info.skillName}-${info.serverName}`, version: "1.0.0" },
+      { capabilities: {} }
+    )
+
+    try {
+      await client.connect(transport)
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `Failed to connect to MCP server "${info.serverName}".\n\n` +
+        `Command: ${command} ${args.join(" ")}\n` +
+        `Reason: ${errorMessage}\n\n` +
+        `Hints:\n` +
+        `  - Ensure the command is installed and available in PATH\n` +
+        `  - Check if the MCP server package exists\n` +
+        `  - Verify the args are correct for this server`
+      )
+    }
+
+    this.clients.set(key, { client, transport, skillName: info.skillName })
+    return client
+  }
+
+  async disconnectSession(sessionID: string): Promise<void> {
+    const keysToRemove: string[] = []
+
+    for (const [key, managed] of this.clients.entries()) {
+      if (key.startsWith(`${sessionID}:`)) {
+        keysToRemove.push(key)
+        try {
+          await managed.client.close()
+        } catch {
+          // Ignore close errors - process may already be terminated
+        }
+      }
+    }
+
+    for (const key of keysToRemove) {
+      this.clients.delete(key)
+    }
+  }
+
+  async disconnectAll(): Promise<void> {
+    for (const [, managed] of this.clients.entries()) {
+      try {
+        await managed.client.close()
+      } catch { /* process may already be terminated */ }
+    }
+    this.clients.clear()
+  }
+
+  async listTools(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Tool[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listTools()
+    return result.tools
+  }
+
+  async listResources(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Resource[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listResources()
+    return result.resources
+  }
+
+  async listPrompts(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext
+  ): Promise<Prompt[]> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.listPrompts()
+    return result.prompts
+  }
+
+  async callTool(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.callTool({ name, arguments: args })
+    return result.content
+  }
+
+  async readResource(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    uri: string
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.readResource({ uri })
+    return result.contents
+  }
+
+  async getPrompt(
+    info: SkillMcpClientInfo,
+    context: SkillMcpServerContext,
+    name: string,
+    args: Record<string, string>
+  ): Promise<unknown> {
+    const client = await this.getOrCreateClientWithRetry(info, context.config)
+    const result = await client.getPrompt({ name, arguments: args })
+    return result.messages
+  }
+
+  private async getOrCreateClientWithRetry(
+    info: SkillMcpClientInfo,
+    config: ClaudeCodeMcpServer
+  ): Promise<Client> {
+    try {
+      return await this.getOrCreateClient(info, config)
+    } catch (error) {
+      const key = this.getClientKey(info)
+      const existing = this.clients.get(key)
+      if (existing) {
+        try {
+          await existing.client.close()
+        } catch { /* process may already be terminated */ }
+        this.clients.delete(key)
+        return await this.getOrCreateClient(info, config)
+      }
+      throw error
+    }
+  }
+
+  getConnectedServers(): string[] {
+    return Array.from(this.clients.keys())
+  }
+
+  isConnected(info: SkillMcpClientInfo): boolean {
+    return this.clients.has(this.getClientKey(info))
+  }
+}

src/features/skill-mcp-manager/types.ts

@@ -0,0 +1,14 @@
+import type { ClaudeCodeMcpServer } from "../claude-code-mcp-loader/types"
+
+export type SkillMcpConfig = Record<string, ClaudeCodeMcpServer>
+
+export interface SkillMcpClientInfo {
+  serverName: string
+  skillName: string
+  sessionID: string
+}
+
+export interface SkillMcpServerContext {
+  config: ClaudeCodeMcpServer
+  skillName: string
+}

src/hooks/AGENTS.md

@@ -2,83 +2,65 @@
 
 ## OVERVIEW
 
-Lifecycle hooks that intercept/modify agent behavior. Inject context, enforce rules, recover from errors, notify on events.
+22 lifecycle hooks intercepting/modifying agent behavior. Context injection, error recovery, output control, notifications.
 
 ## STRUCTURE
 
 ```
 hooks/
-├── agent-usage-reminder/       # Remind to use specialized agents
-├── anthropic-auto-compact/     # Auto-compact Claude at token limit
-├── auto-update-checker/        # Version update notifications
-├── background-notification/    # OS notify on background task complete
-├── claude-code-hooks/          # Claude Code settings.json integration
+├── anthropic-context-window-limit-recovery/  # Auto-compact at token limit (554 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
 ├── comment-checker/            # Prevent excessive AI comments
-│   ├── filters/                # Filtering rules (docstring, directive, bdd, etc.)
-│   └── output/                 # Output formatting
-├── compaction-context-injector/ # Inject context during compaction
-├── directory-agents-injector/  # Auto-inject AGENTS.md files
-├── directory-readme-injector/  # Auto-inject README.md files
+│   └── filters/                # docstring, directive, bdd, etc
+├── compaction-context-injector/ # Preserve context during compaction
+├── directory-agents-injector/  # Auto-inject AGENTS.md
+├── directory-readme-injector/  # Auto-inject README.md
 ├── empty-message-sanitizer/    # Sanitize empty messages
 ├── interactive-bash-session/   # Tmux session management
-├── keyword-detector/           # Detect ultrawork/search keywords
-├── non-interactive-env/        # CI/headless environment handling
-├── preemptive-compaction/      # Pre-emptive session compaction
+├── keyword-detector/           # ultrawork/search keyword activation
+├── non-interactive-env/        # CI/headless handling
+├── preemptive-compaction/      # Pre-emptive at 85% usage
+├── ralph-loop/                 # Self-referential dev loop
 ├── rules-injector/             # Conditional rules from .claude/rules/
-├── session-recovery/           # Recover from session errors
+├── session-recovery/           # Recover from errors (430 lines)
 ├── think-mode/                 # Auto-detect thinking triggers
-├── thinking-block-validator/   # Validate thinking blocks in messages
-├── context-window-monitor.ts   # Monitor context usage (standalone)
-├── empty-task-response-detector.ts
-├── session-notification.ts     # OS notify on idle (standalone)
-├── todo-continuation-enforcer.ts # Force TODO completion (standalone)
-└── tool-output-truncator.ts    # Truncate verbose outputs (standalone)
+├── 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
+└── tool-output-truncator.ts    # Truncate verbose outputs
 ```
 
-## HOOK CATEGORIES
-
-| Category | Hooks | Purpose |
-|----------|-------|---------|
-| Context Injection | directory-agents-injector, directory-readme-injector, rules-injector, compaction-context-injector | Auto-inject relevant context |
-| Session Management | session-recovery, anthropic-auto-compact, preemptive-compaction, empty-message-sanitizer | Handle session lifecycle |
-| Output Control | comment-checker, tool-output-truncator | Control agent output quality |
-| Notifications | session-notification, background-notification, auto-update-checker | OS/user notifications |
-| Behavior Enforcement | todo-continuation-enforcer, keyword-detector, think-mode, agent-usage-reminder | Enforce agent behavior |
-| Environment | non-interactive-env, interactive-bash-session, context-window-monitor | Adapt to runtime environment |
-| Compatibility | claude-code-hooks | Claude Code settings.json support |
-
-## HOW TO ADD A HOOK
-
-1. Create directory: `src/hooks/my-hook/`
-2. Create files:
-   - `index.ts`: Export `createMyHook(input: PluginInput)`
-   - `constants.ts`: Hook name constant
-   - `types.ts`: TypeScript interfaces (optional)
-   - `storage.ts`: Persistent state (optional)
-3. Return event handlers: `{ PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }`
-4. Export from `src/hooks/index.ts`
-5. Register in main plugin
-
 ## HOOK EVENTS
 
 | Event | Timing | Can Block | Use Case |
 |-------|--------|-----------|----------|
-| PreToolUse | Before tool exec | Yes | Validate, modify input |
-| PostToolUse | After tool exec | No | Add context, warnings |
-| UserPromptSubmit | On user prompt | Yes | Inject messages, block |
+| 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 | During compaction | No | Preserve critical context |
+| onSummarize | Compaction | No | Preserve context |
 
-## COMMON PATTERNS
+## HOW TO ADD
 
-- **Storage**: Use `storage.ts` with JSON file for persistent state across sessions
-- **Once-per-session**: Track injected paths in Set to avoid duplicate injection
-- **Message injection**: Return `{ messages: [...] }` from event handlers
-- **Blocking**: Return `{ blocked: true, message: "reason" }` from PreToolUse
+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`
 
-## ANTI-PATTERNS (HOOKS)
+## PATTERNS
 
-- **Heavy computation** in PreToolUse: Slows every tool call
-- **Blocking without clear reason**: Always provide actionable message
-- **Duplicate injection**: Track what's already injected per session
-- **Ignoring errors**: Always try/catch, log failures, don't crash session
+- **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
+
+## 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)

src/hooks/anthropic-context-window-limit-recovery/executor.test.ts

@@ -1,6 +1,7 @@
-import { describe, test, expect, mock, beforeEach } from "bun:test"
+import { describe, test, expect, mock, beforeEach, spyOn } from "bun:test"
 import { executeCompact } from "./executor"
 import type { AutoCompactState } from "./types"
+import * as storage from "./storage"
 
 describe("executeCompact lock management", () => {
   let autoCompactState: AutoCompactState
@@ -15,7 +16,6 @@ describe("executeCompact lock management", () => {
       pendingCompact: new Set<string>(),
       errorDataBySession: new Map(),
       retryStateBySession: new Map(),
-      fallbackStateBySession: new Map(),
       truncateStateBySession: new Map(),
       dcpStateBySession: new Map(),
       emptyContentAttemptBySession: new Map(),
@@ -68,38 +68,6 @@ describe("executeCompact lock management", () => {
     expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
   })
 
-  test("clears lock when revert throws exception", async () => {
-    // #given: Force revert path by exhausting retry attempts and making revert fail
-    mockClient.session.revert = mock(() =>
-      Promise.reject(new Error("Revert failed")),
-    )
-    mockClient.session.messages = mock(() =>
-      Promise.resolve({
-        data: [
-          { info: { id: "msg1", role: "user" } },
-          { info: { id: "msg2", role: "assistant" } },
-        ],
-      }),
-    )
-
-    // Exhaust retry attempts
-    autoCompactState.retryStateBySession.set(sessionID, {
-      attempt: 5,
-      lastAttemptTime: Date.now(),
-    })
-    autoCompactState.errorDataBySession.set(sessionID, {
-      errorType: "token_limit",
-      currentTokens: 100000,
-      maxTokens: 200000,
-    })
-
-    // #when: Execute compaction
-    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
-
-    // #then: Lock cleared even though revert failed
-    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
-  })
-
   test("shows toast when lock already held", async () => {
     // #given: Lock already held
     autoCompactState.compactionInProgress.add(sessionID)
@@ -151,6 +119,7 @@ describe("executeCompact lock management", () => {
       truncate_all_tool_outputs: false,
       aggressive_truncation: true,
     }
+    const dcpForCompaction = true
 
     // #when: Execute compaction with experimental flag
     await executeCompact(
@@ -160,6 +129,7 @@ describe("executeCompact lock management", () => {
       mockClient,
       directory,
       experimental,
+      dcpForCompaction,
     )
 
     // #then: Lock should be cleared even on early return
@@ -193,9 +163,6 @@ describe("executeCompact lock management", () => {
       attempt: 5,
       lastAttemptTime: Date.now(),
     })
-    autoCompactState.fallbackStateBySession.set(sessionID, {
-      revertAttempt: 5,
-    })
     autoCompactState.truncateStateBySession.set(sessionID, {
       truncateAttempt: 5,
     })
@@ -258,4 +225,86 @@ describe("executeCompact lock management", () => {
     // The continuation happens in setTimeout, but lock is cleared in finally before that
     expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
   })
+
+  test("falls through to summarize when truncation is insufficient", async () => {
+    // #given: Over token limit with truncation returning insufficient
+    autoCompactState.errorDataBySession.set(sessionID, {
+      errorType: "token_limit",
+      currentTokens: 250000,
+      maxTokens: 200000,
+    })
+
+    const truncateSpy = spyOn(storage, "truncateUntilTargetTokens").mockReturnValue({
+      success: true,
+      sufficient: false,
+      truncatedCount: 3,
+      totalBytesRemoved: 10000,
+      targetBytesToRemove: 50000,
+      truncatedTools: [
+        { toolName: "Grep", originalSize: 5000 },
+        { toolName: "Read", originalSize: 3000 },
+        { toolName: "Bash", originalSize: 2000 },
+      ],
+    })
+
+    // #when: Execute compaction
+    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
+
+    // #then: Truncation was attempted
+    expect(truncateSpy).toHaveBeenCalled()
+
+    // #then: Summarize should be called (fall through from insufficient truncation)
+    expect(mockClient.session.summarize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: { id: sessionID },
+        body: { providerID: "anthropic", modelID: "claude-opus-4-5" },
+      }),
+    )
+
+    // #then: Lock should be cleared
+    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
+
+    truncateSpy.mockRestore()
+  })
+
+  test("does NOT call summarize when truncation is sufficient", async () => {
+    // #given: Over token limit with truncation returning sufficient
+    autoCompactState.errorDataBySession.set(sessionID, {
+      errorType: "token_limit",
+      currentTokens: 250000,
+      maxTokens: 200000,
+    })
+
+    const truncateSpy = spyOn(storage, "truncateUntilTargetTokens").mockReturnValue({
+      success: true,
+      sufficient: true,
+      truncatedCount: 5,
+      totalBytesRemoved: 60000,
+      targetBytesToRemove: 50000,
+      truncatedTools: [
+        { toolName: "Grep", originalSize: 30000 },
+        { toolName: "Read", originalSize: 30000 },
+      ],
+    })
+
+    // #when: Execute compaction
+    await executeCompact(sessionID, msg, autoCompactState, mockClient, directory)
+
+    // Wait for setTimeout callback
+    await new Promise((resolve) => setTimeout(resolve, 600))
+
+    // #then: Truncation was attempted
+    expect(truncateSpy).toHaveBeenCalled()
+
+    // #then: Summarize should NOT be called (early return from sufficient truncation)
+    expect(mockClient.session.summarize).not.toHaveBeenCalled()
+
+    // #then: prompt_async should be called (Continue after successful truncation)
+    expect(mockClient.session.prompt_async).toHaveBeenCalled()
+
+    // #then: Lock should be cleared
+    expect(autoCompactState.compactionInProgress.has(sessionID)).toBe(false)
+
+    truncateSpy.mockRestore()
+  })
 })

src/hooks/anthropic-context-window-limit-recovery/executor.ts

@@ -1,12 +1,11 @@
 import type {
   AutoCompactState,
   DcpState,
-  FallbackState,
   RetryState,
   TruncateState,
 } from "./types";
 import type { ExperimentalConfig } from "../../config";
-import { FALLBACK_CONFIG, RETRY_CONFIG, TRUNCATE_CONFIG } from "./types";
+import { RETRY_CONFIG, TRUNCATE_CONFIG } from "./types";
 import { executeDynamicContextPruning } from "./pruning-executor";
 import {
   findLargestToolResult,
@@ -40,7 +39,7 @@ type Client = {
       query: { directory: string };
     }) => Promise<unknown>;
     prompt_async: (opts: {
-      path: { sessionID: string };
+      path: { id: string };
       body: { parts: Array<{ type: string; text: string }> };
       query: { directory: string };
     }) => Promise<unknown>;
@@ -69,17 +68,7 @@ function getOrCreateRetryState(
   return state;
 }
 
-function getOrCreateFallbackState(
-  autoCompactState: AutoCompactState,
-  sessionID: string,
-): FallbackState {
-  let state = autoCompactState.fallbackStateBySession.get(sessionID);
-  if (!state) {
-    state = { revertAttempt: 0 };
-    autoCompactState.fallbackStateBySession.set(sessionID, state);
-  }
-  return state;
-}
+
 
 function getOrCreateTruncateState(
   autoCompactState: AutoCompactState,
@@ -135,58 +124,6 @@ function sanitizeEmptyMessagesBeforeSummarize(sessionID: string): number {
   return fixedCount;
 }
 
-async function getLastMessagePair(
-  sessionID: string,
-  client: Client,
-  directory: string,
-): Promise<{ userMessageID: string; assistantMessageID?: string } | null> {
-  try {
-    const resp = await client.session.messages({
-      path: { id: sessionID },
-      query: { directory },
-    });
-
-    const data = (resp as { data?: unknown[] }).data;
-    if (
-      !Array.isArray(data) ||
-      data.length < FALLBACK_CONFIG.minMessagesRequired
-    ) {
-      return null;
-    }
-
-    const reversed = [...data].reverse();
-
-    const lastAssistant = reversed.find((m) => {
-      const msg = m as Record<string, unknown>;
-      const info = msg.info as Record<string, unknown> | undefined;
-      return info?.role === "assistant";
-    });
-
-    const lastUser = reversed.find((m) => {
-      const msg = m as Record<string, unknown>;
-      const info = msg.info as Record<string, unknown> | undefined;
-      return info?.role === "user";
-    });
-
-    if (!lastUser) return null;
-    const userInfo = (lastUser as { info?: Record<string, unknown> }).info;
-    const userMessageID = userInfo?.id as string | undefined;
-    if (!userMessageID) return null;
-
-    let assistantMessageID: string | undefined;
-    if (lastAssistant) {
-      const assistantInfo = (
-        lastAssistant as { info?: Record<string, unknown> }
-      ).info;
-      assistantMessageID = assistantInfo?.id as string | undefined;
-    }
-
-    return { userMessageID, assistantMessageID };
-  } catch {
-    return null;
-  }
-}
-
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes}B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
@@ -221,6 +158,8 @@ export async function getLastAssistant(
   }
 }
 
+
+
 function clearSessionState(
   autoCompactState: AutoCompactState,
   sessionID: string,
@@ -228,7 +167,6 @@ function clearSessionState(
   autoCompactState.pendingCompact.delete(sessionID);
   autoCompactState.errorDataBySession.delete(sessionID);
   autoCompactState.retryStateBySession.delete(sessionID);
-  autoCompactState.fallbackStateBySession.delete(sessionID);
   autoCompactState.truncateStateBySession.delete(sessionID);
   autoCompactState.dcpStateBySession.delete(sessionID);
   autoCompactState.emptyContentAttemptBySession.delete(sessionID);
@@ -337,6 +275,7 @@ export async function executeCompact(
   client: any,
   directory: string,
   experimental?: ExperimentalConfig,
+  dcpForCompaction?: boolean,
 ): Promise<void> {
   if (autoCompactState.compactionInProgress.has(sessionID)) {
     await (client as Client).tui
@@ -358,38 +297,43 @@ export async function executeCompact(
     const errorData = autoCompactState.errorDataBySession.get(sessionID);
     const truncateState = getOrCreateTruncateState(autoCompactState, sessionID);
 
-    // DCP FIRST - run before any other recovery attempts when token limit exceeded
-    const dcpState = getOrCreateDcpState(autoCompactState, sessionID);
-    if (
-      experimental?.dcp_for_compaction &&
-      !dcpState.attempted &&
+    const isOverLimit =
       errorData?.currentTokens &&
       errorData?.maxTokens &&
-      errorData.currentTokens > errorData.maxTokens
-    ) {
+      errorData.currentTokens > errorData.maxTokens;
+
+    // PHASE 1: DCP (Dynamic Context Pruning) - prune duplicate tool calls first
+    const dcpState = getOrCreateDcpState(autoCompactState, sessionID);
+    if (dcpForCompaction !== false && !dcpState.attempted && isOverLimit) {
       dcpState.attempted = true;
-      log("[auto-compact] DCP triggered FIRST on token limit error", {
+      log("[auto-compact] PHASE 1: DCP triggered on token limit error", {
         sessionID,
         currentTokens: errorData.currentTokens,
         maxTokens: errorData.maxTokens,
       });
 
-      const dcpConfig = experimental.dynamic_context_pruning ?? {
+      const dcpConfig = experimental?.dynamic_context_pruning ?? {
         enabled: true,
         notification: "detailed" as const,
-        protected_tools: ["task", "todowrite", "todoread", "lsp_rename", "lsp_code_action_resolve"],
+        protected_tools: [
+          "task",
+          "todowrite",
+          "todoread",
+          "lsp_rename",
+          "lsp_code_action_resolve",
+        ],
       };
 
       try {
         const pruningResult = await executeDynamicContextPruning(
           sessionID,
           dcpConfig,
-          client
+          client,
         );
 
         if (pruningResult.itemsPruned > 0) {
           dcpState.itemsPruned = pruningResult.itemsPruned;
-          log("[auto-compact] DCP successful, proceeding to compaction", {
+          log("[auto-compact] DCP successful, proceeding to truncation", {
             itemsPruned: pruningResult.itemsPruned,
             tokensSaved: pruningResult.totalTokensSaved,
           });
@@ -398,56 +342,13 @@ export async function executeCompact(
             .showToast({
               body: {
                 title: "Dynamic Context Pruning",
-                message: `Pruned ${pruningResult.itemsPruned} items (~${Math.round(pruningResult.totalTokensSaved / 1000)}k tokens). Running compaction...`,
+                message: `Pruned ${pruningResult.itemsPruned} items (~${Math.round(pruningResult.totalTokensSaved / 1000)}k tokens). Proceeding to truncation...`,
                 variant: "success",
                 duration: 3000,
               },
             })
             .catch(() => {});
-
-          // After DCP, immediately try summarize
-          const providerID = msg.providerID as string | undefined;
-          const modelID = msg.modelID as string | undefined;
-
-          if (providerID && modelID) {
-            try {
-              sanitizeEmptyMessagesBeforeSummarize(sessionID);
-
-              await (client as Client).tui
-                .showToast({
-                  body: {
-                    title: "Auto Compact",
-                    message: "Summarizing session after DCP...",
-                    variant: "warning",
-                    duration: 3000,
-                  },
-                })
-                .catch(() => {});
-
-              await (client as Client).session.summarize({
-                path: { id: sessionID },
-                body: { providerID, modelID },
-                query: { directory },
-              });
-
-              clearSessionState(autoCompactState, sessionID);
-
-              setTimeout(async () => {
-                try {
-                  await (client as Client).session.prompt_async({
-                    path: { sessionID },
-                    body: { parts: [{ type: "text", text: "Continue" }] },
-                    query: { directory },
-                  });
-                } catch {}
-              }, 500);
-              return;
-            } catch (summarizeError) {
-              log("[auto-compact] summarize after DCP failed, continuing recovery", {
-                error: String(summarizeError),
-              });
-            }
-          }
+          // Continue to PHASE 2 (truncation) instead of summarizing immediately
         } else {
           log("[auto-compact] DCP did not prune any items", { sessionID });
         }
@@ -456,14 +357,12 @@ export async function executeCompact(
       }
     }
 
+    // PHASE 2: Aggressive Truncation - always try when over limit (not experimental-only)
     if (
-      experimental?.aggressive_truncation &&
-      errorData?.currentTokens &&
-      errorData?.maxTokens &&
-      errorData.currentTokens > errorData.maxTokens &&
+      isOverLimit &&
       truncateState.truncateAttempt < TRUNCATE_CONFIG.maxTruncateAttempts
     ) {
-      log("[auto-compact] aggressive truncation triggered (experimental)", {
+      log("[auto-compact] PHASE 2: aggressive truncation triggered", {
         currentTokens: errorData.currentTokens,
         maxTokens: errorData.maxTokens,
         targetRatio: TRUNCATE_CONFIG.targetTokenRatio,
@@ -485,16 +384,16 @@ export async function executeCompact(
           .join(", ");
         const statusMsg = aggressiveResult.sufficient
           ? `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)})`
-          : `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)}) but need ${formatBytes(aggressiveResult.targetBytesToRemove)}. Falling back to summarize/revert...`;
+          : `Truncated ${aggressiveResult.truncatedCount} outputs (${formatBytes(aggressiveResult.totalBytesRemoved)}) - continuing to summarize...`;
 
         await (client as Client).tui
           .showToast({
             body: {
               title: aggressiveResult.sufficient
-                ? "Aggressive Truncation"
+                ? "Truncation Complete"
                 : "Partial Truncation",
               message: `${statusMsg}: ${toolNames}`,
-              variant: "warning",
+              variant: aggressiveResult.sufficient ? "success" : "warning",
               duration: 4000,
             },
           })
@@ -502,11 +401,14 @@ export async function executeCompact(
 
         log("[auto-compact] aggressive truncation completed", aggressiveResult);
 
+        // Only return early if truncation was sufficient to get under token limit
+        // Otherwise fall through to PHASE 3 (Summarize)
         if (aggressiveResult.sufficient) {
+          clearSessionState(autoCompactState, sessionID);
           setTimeout(async () => {
             try {
               await (client as Client).session.prompt_async({
-                path: { sessionID },
+                path: { id: sessionID },
                 body: { parts: [{ type: "text", text: "Continue" }] },
                 query: { directory },
               });
@@ -514,87 +416,16 @@ export async function executeCompact(
           }, 500);
           return;
         }
-      } else {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Truncation Skipped",
-              message: "No tool outputs found to truncate.",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      }
-    }
-
-    let skipSummarize = false;
-
-    if (truncateState.truncateAttempt < TRUNCATE_CONFIG.maxTruncateAttempts) {
-      const largest = findLargestToolResult(sessionID);
-
-      if (
-        largest &&
-        largest.outputSize >= TRUNCATE_CONFIG.minOutputSizeToTruncate
-      ) {
-        const result = truncateToolResult(largest.partPath);
-
-        if (result.success) {
-          truncateState.truncateAttempt++;
-          truncateState.lastTruncatedPartId = largest.partId;
-
-          await (client as Client).tui
-            .showToast({
-              body: {
-                title: "Truncating Large Output",
-                message: `Truncated ${result.toolName} (${formatBytes(result.originalSize ?? 0)}). Retrying...`,
-                variant: "warning",
-                duration: 3000,
-              },
-            })
-            .catch(() => {});
-
-          setTimeout(async () => {
-            try {
-              await (client as Client).session.prompt_async({
-                path: { sessionID },
-                body: { parts: [{ type: "text", text: "Continue" }] },
-                query: { directory },
-              });
-            } catch {}
-          }, 500);
-          return;
-        }
-      } else if (
-        errorData?.currentTokens &&
-        errorData?.maxTokens &&
-        errorData.currentTokens > errorData.maxTokens
-      ) {
-        skipSummarize = true;
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Summarize Skipped",
-              message: `Over token limit (${errorData.currentTokens}/${errorData.maxTokens}) with nothing to truncate. Going to revert...`,
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      } else if (!errorData?.currentTokens) {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Truncation Skipped",
-              message: "No large tool outputs found.",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
+        // Truncation was insufficient - fall through to Summarize
+        log("[auto-compact] truncation insufficient, falling through to summarize", {
+          sessionID,
+          truncatedCount: aggressiveResult.truncatedCount,
+          sufficient: aggressiveResult.sufficient,
+        });
       }
     }
 
+    // PHASE 3: Summarize - fallback when truncation insufficient or no tool outputs
     const retryState = getOrCreateRetryState(autoCompactState, sessionID);
 
     if (errorData?.errorType?.includes("non-empty content")) {
@@ -618,6 +449,7 @@ export async function executeCompact(
               client,
               directory,
               experimental,
+              dcpForCompaction,
             );
           }, 500);
           return;
@@ -640,11 +472,10 @@ export async function executeCompact(
 
     if (Date.now() - retryState.lastAttemptTime > 300000) {
       retryState.attempt = 0;
-      autoCompactState.fallbackStateBySession.delete(sessionID);
       autoCompactState.truncateStateBySession.delete(sessionID);
     }
 
-    if (!skipSummarize && retryState.attempt < RETRY_CONFIG.maxAttempts) {
+    if (retryState.attempt < RETRY_CONFIG.maxAttempts) {
       retryState.attempt++;
       retryState.lastAttemptTime = Date.now();
 
@@ -675,7 +506,7 @@ export async function executeCompact(
           setTimeout(async () => {
             try {
               await (client as Client).session.prompt_async({
-                path: { sessionID },
+                path: { id: sessionID },
                 body: { parts: [{ type: "text", text: "Continue" }] },
                 query: { directory },
               });
@@ -696,6 +527,7 @@ export async function executeCompact(
               client,
               directory,
               experimental,
+              dcpForCompaction,
             );
           }, cappedDelay);
           return;
@@ -705,75 +537,7 @@ export async function executeCompact(
           .showToast({
             body: {
               title: "Summarize Skipped",
-              message: "Missing providerID or modelID. Skipping to revert...",
-              variant: "warning",
-              duration: 3000,
-            },
-          })
-          .catch(() => {});
-      }
-    }
-
-    const fallbackState = getOrCreateFallbackState(autoCompactState, sessionID);
-
-    if (fallbackState.revertAttempt < FALLBACK_CONFIG.maxRevertAttempts) {
-      const pair = await getLastMessagePair(
-        sessionID,
-        client as Client,
-        directory,
-      );
-
-      if (pair) {
-        try {
-          await (client as Client).tui
-            .showToast({
-              body: {
-                title: "Emergency Recovery",
-                message: "Removing last message pair...",
-                variant: "warning",
-                duration: 3000,
-              },
-            })
-            .catch(() => {});
-
-          if (pair.assistantMessageID) {
-            await (client as Client).session.revert({
-              path: { id: sessionID },
-              body: { messageID: pair.assistantMessageID },
-              query: { directory },
-            });
-          }
-
-          await (client as Client).session.revert({
-            path: { id: sessionID },
-            body: { messageID: pair.userMessageID },
-            query: { directory },
-          });
-
-          fallbackState.revertAttempt++;
-          fallbackState.lastRevertedMessageID = pair.userMessageID;
-
-          // Clear all state after successful revert - don't recurse
-          clearSessionState(autoCompactState, sessionID);
-
-          // Send "Continue" prompt to resume session
-          setTimeout(async () => {
-            try {
-              await (client as Client).session.prompt_async({
-                path: { sessionID },
-                body: { parts: [{ type: "text", text: "Continue" }] },
-                query: { directory },
-              });
-            } catch {}
-          }, 500);
-          return;
-        } catch {}
-      } else {
-        await (client as Client).tui
-          .showToast({
-            body: {
-              title: "Revert Skipped",
-              message: "Could not find last message pair to revert.",
+              message: "Missing providerID or modelID.",
               variant: "warning",
               duration: 3000,
             },

src/hooks/anthropic-context-window-limit-recovery/index.ts

@@ -5,16 +5,16 @@ import { parseAnthropicTokenLimitError } from "./parser"
 import { executeCompact, getLastAssistant } from "./executor"
 import { log } from "../../shared/logger"
 
-export interface AnthropicAutoCompactOptions {
+export interface AnthropicContextWindowLimitRecoveryOptions {
   experimental?: ExperimentalConfig
+  dcpForCompaction?: boolean
 }
 
-function createAutoCompactState(): AutoCompactState {
+function createRecoveryState(): AutoCompactState {
   return {
     pendingCompact: new Set<string>(),
     errorDataBySession: new Map<string, ParsedTokenLimitError>(),
     retryStateBySession: new Map(),
-    fallbackStateBySession: new Map(),
     truncateStateBySession: new Map(),
     dcpStateBySession: new Map(),
     emptyContentAttemptBySession: new Map(),
@@ -22,9 +22,10 @@ function createAutoCompactState(): AutoCompactState {
   }
 }
 
-export function createAnthropicAutoCompactHook(ctx: PluginInput, options?: AnthropicAutoCompactOptions) {
-  const autoCompactState = createAutoCompactState()
+export function createAnthropicContextWindowLimitRecoveryHook(ctx: PluginInput, options?: AnthropicContextWindowLimitRecoveryOptions) {
+  const autoCompactState = createRecoveryState()
   const experimental = options?.experimental
+  const dcpForCompaction = options?.dcpForCompaction
 
   const eventHandler = async ({ event }: { event: { type: string; properties?: unknown } }) => {
     const props = event.properties as Record<string, unknown> | undefined
@@ -35,7 +36,6 @@ export function createAnthropicAutoCompactHook(ctx: PluginInput, options?: Anthr
         autoCompactState.pendingCompact.delete(sessionInfo.id)
         autoCompactState.errorDataBySession.delete(sessionInfo.id)
         autoCompactState.retryStateBySession.delete(sessionInfo.id)
-        autoCompactState.fallbackStateBySession.delete(sessionInfo.id)
         autoCompactState.truncateStateBySession.delete(sessionInfo.id)
         autoCompactState.dcpStateBySession.delete(sessionInfo.id)
         autoCompactState.emptyContentAttemptBySession.delete(sessionInfo.id)
@@ -81,7 +81,8 @@ export function createAnthropicAutoCompactHook(ctx: PluginInput, options?: Anthr
             autoCompactState,
             ctx.client,
             ctx.directory,
-            experimental
+            experimental,
+            dcpForCompaction
           )
         }, 300)
       }
@@ -140,7 +141,8 @@ export function createAnthropicAutoCompactHook(ctx: PluginInput, options?: Anthr
         autoCompactState,
         ctx.client,
         ctx.directory,
-        experimental
+        experimental,
+        dcpForCompaction
       )
     }
   }
@@ -150,6 +152,6 @@ export function createAnthropicAutoCompactHook(ctx: PluginInput, options?: Anthr
   }
 }
 
-export type { AutoCompactState, DcpState, FallbackState, ParsedTokenLimitError, TruncateState } from "./types"
+export type { AutoCompactState, DcpState, ParsedTokenLimitError, TruncateState } from "./types"
 export { parseAnthropicTokenLimitError } from "./parser"
 export { executeCompact, getLastAssistant } from "./executor"

src/hooks/anthropic-context-window-limit-recovery/parser.ts

@@ -26,9 +26,23 @@ const TOKEN_LIMIT_KEYWORDS = [
   "context length",
   "too many tokens",
   "non-empty content",
-  "invalid_request_error",
 ]
 
+// Patterns that indicate thinking block structure errors (NOT token limit errors)
+// These should be handled by session-recovery hook, not compaction
+const THINKING_BLOCK_ERROR_PATTERNS = [
+  /thinking.*first block/i,
+  /first block.*thinking/i,
+  /must.*start.*thinking/i,
+  /thinking.*redacted_thinking/i,
+  /expected.*thinking.*found/i,
+  /thinking.*disabled.*cannot.*contain/i,
+]
+
+function isThinkingBlockError(text: string): boolean {
+  return THINKING_BLOCK_ERROR_PATTERNS.some((pattern) => pattern.test(text))
+}
+
 const MESSAGE_INDEX_PATTERN = /messages\.(\d+)/
 
 function extractTokensFromMessage(message: string): { current: number; max: number } | null {
@@ -52,6 +66,9 @@ function extractMessageIndex(text: string): number | undefined {
 }
 
 function isTokenLimitError(text: string): boolean {
+  if (isThinkingBlockError(text)) {
+    return false
+  }
   const lower = text.toLowerCase()
   return TOKEN_LIMIT_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()))
 }

src/hooks/anthropic-context-window-limit-recovery/storage.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect, mock, beforeEach } from "bun:test"
+import { truncateUntilTargetTokens } from "./storage"
+import * as storage from "./storage"
+
+// Mock the entire module
+mock.module("./storage", () => {
+  return {
+    ...storage,
+    findToolResultsBySize: mock(() => []),
+    truncateToolResult: mock(() => ({ success: false })),
+  }
+})
+
+describe("truncateUntilTargetTokens", () => {
+  const sessionID = "test-session"
+  
+  beforeEach(() => {
+    // Reset mocks
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    findToolResultsBySize.mockReset()
+    truncateToolResult.mockReset()
+  })
+
+  test("truncates only until target is reached", () => {
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    
+    // #given: Two tool results, each 1000 chars. Target reduction is 500 chars.
+    const results = [
+      { partPath: "path1", partId: "id1", messageID: "m1", toolName: "tool1", outputSize: 1000 },
+      { partPath: "path2", partId: "id2", messageID: "m2", toolName: "tool2", outputSize: 1000 },
+    ]
+    
+    findToolResultsBySize.mockReturnValue(results)
+    truncateToolResult.mockImplementation((path: string) => ({
+      success: true,
+      toolName: path === "path1" ? "tool1" : "tool2",
+      originalSize: 1000
+    }))
+
+    // #when: currentTokens=1000, maxTokens=1000, targetRatio=0.5 (target=500, reduce=500)
+    // charsPerToken=1 for simplicity in test
+    const result = truncateUntilTargetTokens(sessionID, 1000, 1000, 0.5, 1)
+
+    // #then: Should only truncate the first tool
+    expect(result.truncatedCount).toBe(1)
+    expect(truncateToolResult).toHaveBeenCalledTimes(1)
+    expect(truncateToolResult).toHaveBeenCalledWith("path1")
+    expect(result.totalBytesRemoved).toBe(1000)
+    expect(result.sufficient).toBe(true)
+  })
+
+  test("truncates all if target not reached", () => {
+    const { findToolResultsBySize, truncateToolResult } = require("./storage")
+    
+    // #given: Two tool results, each 100 chars. Target reduction is 500 chars.
+    const results = [
+      { partPath: "path1", partId: "id1", messageID: "m1", toolName: "tool1", outputSize: 100 },
+      { partPath: "path2", partId: "id2", messageID: "m2", toolName: "tool2", outputSize: 100 },
+    ]
+    
+    findToolResultsBySize.mockReturnValue(results)
+    truncateToolResult.mockImplementation((path: string) => ({
+      success: true,
+      toolName: path === "path1" ? "tool1" : "tool2",
+      originalSize: 100
+    }))
+
+    // #when: reduce 500 chars
+    const result = truncateUntilTargetTokens(sessionID, 1000, 1000, 0.5, 1)
+
+    // #then: Should truncate both
+    expect(result.truncatedCount).toBe(2)
+    expect(truncateToolResult).toHaveBeenCalledTimes(2)
+    expect(result.totalBytesRemoved).toBe(200)
+    expect(result.sufficient).toBe(false)
+  })
+})

src/hooks/anthropic-context-window-limit-recovery/storage.ts

@@ -230,6 +230,10 @@ export function truncateUntilTargetTokens(
         toolName: truncateResult.toolName ?? result.toolName,
         originalSize: removedSize,
       })
+      
+      if (totalRemoved >= charsToReduce) {
+        break
+      }
     }
   }
 

src/hooks/anthropic-context-window-limit-recovery/types.ts

@@ -13,11 +13,6 @@ export interface RetryState {
   lastAttemptTime: number
 }
 
-export interface FallbackState {
-  revertAttempt: number
-  lastRevertedMessageID?: string
-}
-
 export interface TruncateState {
   truncateAttempt: number
   lastTruncatedPartId?: string
@@ -32,7 +27,6 @@ export interface AutoCompactState {
   pendingCompact: Set<string>
   errorDataBySession: Map<string, ParsedTokenLimitError>
   retryStateBySession: Map<string, RetryState>
-  fallbackStateBySession: Map<string, FallbackState>
   truncateStateBySession: Map<string, TruncateState>
   dcpStateBySession: Map<string, DcpState>
   emptyContentAttemptBySession: Map<string, number>
@@ -46,11 +40,6 @@ export const RETRY_CONFIG = {
   maxDelayMs: 30000,
 } as const
 
-export const FALLBACK_CONFIG = {
-  maxRevertAttempts: 3,
-  minMessagesRequired: 2,
-} as const
-
 export const TRUNCATE_CONFIG = {
   maxTruncateAttempts: 20,
   minOutputSizeToTruncate: 500,