diff --git a/docs/CRASH_INVESTIGATION_TIMELINE.md b/docs/CRASH_INVESTIGATION_TIMELINE.md deleted file mode 100644 index 750abda56..000000000 --- a/docs/CRASH_INVESTIGATION_TIMELINE.md +++ /dev/null @@ -1,152 +0,0 @@ -# Windows Crash Investigation Timeline - -## Executive Summary - -**Initial Hypothesis**: Bun.spawn/ShellInterpreter GC bug causing crashes on Windows -**Actual Root Cause**: Conflict between oh-my-opencode's session-notification and external notification plugins (specifically `@mohak34/opencode-notifier`) - -**Evidence**: User removed `@mohak34/opencode-notifier` plugin → crashes stopped immediately. The release version of oh-my-opencode (with original Bun.spawn code) works fine when used alone. - ---- - -## Timeline - -### Phase 1: Initial Crash Reports (Early January 2026) - -**Symptoms:** -- Windows users experiencing crashes after extended oh-my-opencode usage -- Stack traces pointed to Bun's ShellInterpreter finalizer: - ``` - Segmentation fault at address 0x337081E00E0 - - interpreter.zig:1239: deinitFromFinalizer - - ZigGeneratedClasses.zig:19925: ShellInterpreterClass__finalize - ``` - -**Initial Analysis:** -- Similar to known Bun issues: oven-sh/bun#23177, oven-sh/bun#24368 -- Focus on `ctx.$` (Bun shell template literals) in session-notification.ts - -### Phase 2: PR #543 - Wrong Fix Merged (January 6, 2026) - -**PR**: [#543 - fix(session-notification): avoid Bun shell GC crash on Windows](https://github.com/code-yeongyu/oh-my-opencode/pull/543) - -**Changes Made:** -- Replaced `ctx.$` with `node:child_process.spawn` in `session-notification.ts` -- Updated tests to mock spawn instead of ctx.$ - -**Assumption**: The ShellInterpreter GC bug was causing crashes when notification commands were executed. - -**Status**: ❌ MERGED (reverted in this PR) - -### Phase 3: Continued Investigation - Debug Tracing (January 6-7, 2026) - -Crashes continued after PR #543. Added debug tracing system (PR #571) to capture what happens before crashes. - -**PR #571**: [feat(debug): add comprehensive crash tracing system](https://github.com/code-yeongyu/oh-my-opencode/pull/571) - -Tracing revealed LSP ENOENT errors, leading to: - -**PR #572**: [fix(lsp): add resilient handling for missing LSP server binaries](https://github.com/code-yeongyu/oh-my-opencode/pull/572) - -### Phase 4: More Bun.spawn Changes (January 7, 2026) - WRONG PATH - -Based on the assumption that Bun.spawn was the issue, additional files were modified locally: -- `src/hooks/session-notification-utils.ts` -- `src/hooks/comment-checker/cli.ts` -- `src/hooks/comment-checker/downloader.ts` -- `src/hooks/interactive-bash-session/index.ts` - -**Status**: ❌ REVERTED (never committed) - -### Phase 5: Root Cause Discovery (January 7, 2026) - -**Critical Observation by User:** -> "I removed `@mohak34/opencode-notifier` and crashes stopped. The release version with Bun.spawn works perfectly fine." - -**Key Evidence:** -1. Removing ONLY the notifier plugin fixed crashes -2. Release version (before PR #543) works fine for user and most others -3. No widespread complaints from other users about crashes -4. PR #543 was based on superficial pattern matching with Bun issues - ---- - -## The Real Root Cause: Notification Plugin Conflict - -### Two Plugins, Same Event - -Both plugins listen to `session.idle` and send notifications: - -| Aspect | oh-my-opencode | opencode-notifier | -|--------|---------------|-------------------| -| **Event** | `session.idle` | `session.idle` | -| **Delay** | 1.5s confirmation delay | Immediate | -| **Windows Notification** | PowerShell + Windows.UI.Notifications API | `node-notifier` → WindowsToaster → SnoreToast.exe | -| **Sound** | PowerShell Media.SoundPlayer | PowerShell Media.SoundPlayer | -| **Process spawning** | `ctx.$` (Bun shell) | `node:child_process` | - -### Conflict Points - -1. **Different notification systems fighting**: - - oh-my-opencode: Direct PowerShell → Windows.UI.Notifications - - opencode-notifier: SnoreToast.exe binary via node-notifier - -2. **Same app identity**: Both register with "OpenCode" as the toast notifier app - -3. **Concurrent execution**: Both trigger within milliseconds of each other on `session.idle` - -4. **Resource contention**: Windows Toast API may not handle concurrent registrations gracefully - -### Why It Wasn't Bun.spawn - -- Both plugins use different spawning methods - this didn't matter -- Release version works fine when used alone -- Most users don't have this issue (most don't use both plugins) -- The stack trace pointed to ShellInterpreter, but correlation ≠ causation - ---- - -## The Fix - -### What This PR Does - -1. **Reverts PR #543**: Restores original `ctx.$` usage (it was never the problem) - -2. **Adds conflict detection**: - - Scans `opencode.json` for known notification plugins - - Known plugins: `opencode-notifier`, `@mohak34/opencode-notifier` - -3. **Auto-disables on conflict**: - - When external notifier detected, skips creating session-notification hook - - Logs clear warning explaining why - -4. **Config override**: - ```json - { - "notification": { - "force_enable": true - } - } - ``` - Users can force-enable oh-my-opencode's notification if they want. - ---- - -## Lessons Learned - -1. **Correlation ≠ Causation**: Stack traces can be misleading; investigate root cause thoroughly -2. **Test with user's exact environment**: The crash only happened with specific plugin combination -3. **Challenge assumptions**: "Bun.spawn is buggy" was accepted too quickly without verifying -4. **Evidence-based debugging**: User's discovery (removing notifier = no crash) was the key evidence - ---- - -## Related Links - -- PR #543 (merged, reverted in this PR): https://github.com/code-yeongyu/oh-my-opencode/pull/543 -- PR #571 (open): https://github.com/code-yeongyu/oh-my-opencode/pull/571 -- PR #572 (open): https://github.com/code-yeongyu/oh-my-opencode/pull/572 -- opencode-notifier: https://github.com/mohak34/opencode-notifier -- Bun issues referenced (not actually the cause): - - https://github.com/oven-sh/bun/issues/23177 - - https://github.com/oven-sh/bun/issues/24368 diff --git a/docs/category-skill-guide.md b/docs/category-skill-guide.md new file mode 100644 index 000000000..1d5d8f8fe --- /dev/null +++ b/docs/category-skill-guide.md @@ -0,0 +1,200 @@ +# Category & Skill System Guide + +This document provides a comprehensive guide to the **Category** and **Skill** systems, which form the extensibility core of Oh-My-OpenCode. + +## 1. Overview + +Instead of delegating everything to a single AI agent, it's far more efficient to invoke **specialists** tailored to the nature of the task. + +- **Category**: "What kind of work is this?" (determines model, temperature, prompt mindset) +- **Skill**: "What tools and knowledge are needed?" (injects specialized knowledge, MCP tools, workflows) + +By combining these two concepts, you can generate optimal agents through `sisyphus_task`. + +--- + +## 2. Category System + +A Category is an agent configuration preset optimized for specific domains. + +### Available Built-in Categories + +| Category | Optimal Model | Characteristics | Use Cases | +|----------|---------------|-----------------|-----------| +| `visual-engineering` | `gemini-3-pro` | High creativity (Temp 0.7) | Frontend, UI/UX, animations, styling | +| `ultrabrain` | `gpt-5.2` | Maximum logical reasoning (Temp 0.1) | Architecture design, complex business logic, debugging | +| `artistry` | `gemini-3-pro` | Artistic (Temp 0.9) | Creative ideation, design concepts, storytelling | +| `quick` | `claude-haiku` | Fast (Temp 0.3) | Simple tasks, refactoring, script writing | +| `writing` | `gemini-3-flash` | Natural flow (Temp 0.5) | Documentation, technical blogs, README writing | +| `most-capable` | `claude-opus` | High performance (Temp 0.1) | Extremely difficult complex tasks | + +### Usage + +Specify the `category` parameter when invoking the `sisyphus_task` tool. + +```typescript +sisyphus_task( + category="visual-engineering", + prompt="Add a responsive chart component to the dashboard page" +) +``` + +### Sisyphus-Junior (Delegated Executor) + +When you use a Category, a special agent called **Sisyphus-Junior** performs the work. +- **Characteristic**: Cannot **re-delegate** tasks to other agents. +- **Purpose**: Prevents infinite delegation loops and ensures focus on the assigned task. + +--- + +## 3. Skill System + +A Skill is a mechanism that injects **specialized knowledge (Context)** and **tools (MCP)** for specific domains into agents. + +### Built-in Skills + +1. **`git-master`** + - **Capabilities**: Git expert. Detects commit styles, splits atomic commits, formulates rebase strategies. + - **MCP**: None (uses Git commands) + - **Usage**: Essential for commits, history searches, branch management. + +2. **`playwright`** + - **Capabilities**: Browser automation. Web page testing, screenshots, scraping. + - **MCP**: `@playwright/mcp` (auto-executed) + - **Usage**: For post-implementation UI verification, E2E test writing. + +3. **`frontend-ui-ux`** + - **Capabilities**: Injects designer mindset. Color, typography, motion guidelines. + - **Usage**: For aesthetic UI work beyond simple implementation. + +### Usage + +Add desired skill names to the `skills` array. + +```typescript +sisyphus_task( + category="quick", + skills=["git-master"], + prompt="Commit current changes. Follow commit message style." +) +``` + +### Skill Customization (SKILL.md) + +You can add custom skills directly to `.opencode/skills/` in your project root or `~/.claude/skills/` in your home directory. + +**Example: `.opencode/skills/my-skill/SKILL.md`** + +```markdown +--- +name: my-skill +description: My special custom skill +mcp: + my-mcp: + command: npx + args: ["-y", "my-mcp-server"] +--- + +# My Skill Prompt + +This content will be injected into the agent's system prompt. +... +``` + +--- + +## 4. Combination Strategies (Combos) + +You can create powerful specialized agents by combining Categories and Skills. + +### 🎨 The Designer (UI Implementation) +- **Category**: `visual-engineering` +- **Skills**: `["frontend-ui-ux", "playwright"]` +- **Effect**: Implements aesthetic UI and verifies rendering results directly in browser. + +### 🏗️ The Architect (Design Review) +- **Category**: `ultrabrain` +- **Skills**: `[]` (pure reasoning) +- **Effect**: Leverages GPT-5.2's logical reasoning for in-depth system architecture analysis. + +### ⚡ The Maintainer (Quick Fixes) +- **Category**: `quick` +- **Skills**: `["git-master"]` +- **Effect**: Uses cost-effective models to quickly fix code and generate clean commits. + +--- + +## 5. sisyphus_task Prompt Guide + +When delegating, **clear and specific** prompts are essential. Include these 7 elements: + +1. **TASK**: What needs to be done? (single objective) +2. **EXPECTED OUTCOME**: What is the deliverable? +3. **REQUIRED SKILLS**: Which skills should be used? +4. **REQUIRED TOOLS**: Which tools must be used? (whitelist) +5. **MUST DO**: What must be done (constraints) +6. **MUST NOT DO**: What must never be done +7. **CONTEXT**: File paths, existing patterns, reference materials + +**Bad Example**: +> "Fix this" + +**Good Example**: +> **TASK**: Fix mobile layout breaking issue in `LoginButton.tsx` +> **CONTEXT**: `src/components/LoginButton.tsx`, using Tailwind CSS +> **MUST DO**: Change flex-direction at `md:` breakpoint +> **MUST NOT DO**: Modify existing desktop layout +> **EXPECTED**: Buttons align vertically on mobile + +--- + +## 6. Configuration Guide (oh-my-opencode.json) + +You can fine-tune categories in `oh-my-opencode.json`. + +### Category Configuration Schema (CategoryConfig) + +| Field | Type | Description | +|-------|------|-------------| +| `model` | string | AI model ID to use (e.g., `anthropic/claude-opus-4-5`) | +| `temperature` | number | Creativity level (0.0 ~ 2.0). Lower is more deterministic. | +| `prompt_append` | string | Content to append to system prompt when this category is selected | +| `thinking` | object | Thinking model configuration (`{ type: "enabled", budgetTokens: 16000 }`) | +| `tools` | object | Tool usage control (disable with `{ "tool_name": false }`) | +| `maxTokens` | number | Maximum response token count | + +### Example Configuration + +```jsonc +{ + "categories": { + // 1. Define new custom category + "korean-writer": { + "model": "google/gemini-3-flash-preview", + "temperature": 0.5, + "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone." + }, + + // 2. Override existing category (change model) + "visual-engineering": { + "model": "openai/gpt-5.2", // Can change model + "temperature": 0.8 + }, + + // 3. Configure thinking model and restrict tools + "deep-reasoning": { + "model": "anthropic/claude-opus-4-5", + "thinking": { + "type": "enabled", + "budgetTokens": 32000 + }, + "tools": { + "websearch_web_search_exa": false // Disable web search + } + } + }, + + // Disable skills + "disabled_skills": ["playwright"] +} +``` diff --git a/docs/cli-guide.md b/docs/cli-guide.md new file mode 100644 index 000000000..747fa12f0 --- /dev/null +++ b/docs/cli-guide.md @@ -0,0 +1,272 @@ +# Oh-My-OpenCode CLI Guide + +This document provides a comprehensive guide to using the Oh-My-OpenCode CLI tools. + +## 1. Overview + +Oh-My-OpenCode provides CLI tools accessible via the `bunx oh-my-opencode` command. The CLI supports various features including plugin installation, environment diagnostics, and session execution. + +```bash +# Basic execution (displays help) +bunx oh-my-opencode + +# Or run with npx +npx oh-my-opencode +``` + +--- + +## 2. Available Commands + +| Command | Description | +|---------|-------------| +| `install` | Interactive Setup Wizard | +| `doctor` | Environment diagnostics and health checks | +| `run` | OpenCode session runner | +| `auth` | Google Antigravity authentication management | +| `version` | Display version information | + +--- + +## 3. `install` - Interactive Setup Wizard + +An interactive installation tool for initial Oh-My-OpenCode setup. Provides a beautiful TUI (Text User Interface) based on `@clack/prompts`. + +### Usage + +```bash +bunx oh-my-opencode install +``` + +### Installation Process + +1. **Provider Selection**: Choose your AI provider from Claude, ChatGPT, or Gemini. +2. **API Key Input**: Enter the API key for your selected provider. +3. **Configuration File Creation**: Generates `opencode.json` or `oh-my-opencode.json` files. +4. **Plugin Registration**: Automatically registers the oh-my-opencode plugin in OpenCode settings. + +### Options + +| Option | Description | +|--------|-------------| +| `--no-tui` | Run in non-interactive mode without TUI (for CI/CD environments) | +| `--verbose` | Display detailed logs | + +--- + +## 4. `doctor` - Environment Diagnostics + +Diagnoses your environment to ensure Oh-My-OpenCode is functioning correctly. Performs 17+ health checks. + +### Usage + +```bash +bunx oh-my-opencode doctor +``` + +### Diagnostic Categories + +| Category | Check Items | +|----------|-------------| +| **Installation** | OpenCode version (>= 1.0.150), plugin registration status | +| **Configuration** | Configuration file validity, JSONC parsing | +| **Authentication** | Anthropic, OpenAI, Google API key validity | +| **Dependencies** | Bun, Node.js, Git installation status | +| **Tools** | LSP server status, MCP server status | +| **Updates** | Latest version check | + +### Options + +| Option | Description | +|--------|-------------| +| `--category ` | Check specific category only (e.g., `--category authentication`) | +| `--json` | Output results in JSON format | +| `--verbose` | Include detailed information | + +### Example Output + +``` +oh-my-opencode doctor + +┌──────────────────────────────────────────────────┐ +│ Oh-My-OpenCode Doctor │ +└──────────────────────────────────────────────────┘ + +Installation + ✓ OpenCode version: 1.0.155 (>= 1.0.150) + ✓ Plugin registered in opencode.json + +Configuration + ✓ oh-my-opencode.json is valid + ⚠ categories.visual-engineering: using default model + +Authentication + ✓ Anthropic API key configured + ✓ OpenAI API key configured + ✗ Google API key not found + +Dependencies + ✓ Bun 1.2.5 installed + ✓ Node.js 22.0.0 installed + ✓ Git 2.45.0 installed + +Summary: 10 passed, 1 warning, 1 failed +``` + +--- + +## 5. `run` - OpenCode Session Runner + +Executes OpenCode sessions and monitors task completion. + +### Usage + +```bash +bunx oh-my-opencode run [prompt] +``` + +### Options + +| Option | Description | +|--------|-------------| +| `--enforce-completion` | Keep session active until all TODOs are completed | +| `--timeout ` | Set maximum execution time | + +--- + +## 6. `auth` - Authentication Management + +Manages Google Antigravity OAuth authentication. Required for using Gemini models. + +### Usage + +```bash +# Login +bunx oh-my-opencode auth login + +# Logout +bunx oh-my-opencode auth logout + +# Check current status +bunx oh-my-opencode auth status +``` + +--- + +## 7. Configuration Files + +The CLI searches for configuration files in the following locations (in priority order): + +1. **Project Level**: `.opencode/oh-my-opencode.json` +2. **User Level**: `~/.config/opencode/oh-my-opencode.json` + +### JSONC Support + +Configuration files support **JSONC (JSON with Comments)** format. You can use comments and trailing commas. + +```jsonc +{ + // Agent configuration + "sisyphus_agent": { + "disabled": false, + "planner_enabled": true, + }, + + /* Category customization */ + "categories": { + "visual-engineering": { + "model": "google/gemini-3-pro-preview", + }, + }, +} +``` + +--- + +## 8. Troubleshooting + +### "OpenCode version too old" Error + +```bash +# Update OpenCode +npm install -g opencode@latest +# or +bun install -g opencode@latest +``` + +### "Plugin not registered" Error + +```bash +# Reinstall plugin +bunx oh-my-opencode install +``` + +### Doctor Check Failures + +```bash +# Diagnose with detailed information +bunx oh-my-opencode doctor --verbose + +# Check specific category only +bunx oh-my-opencode doctor --category authentication +``` + +--- + +## 9. Non-Interactive Mode + +Use the `--no-tui` option for CI/CD environments. + +```bash +# Run doctor in CI environment +bunx oh-my-opencode doctor --no-tui --json + +# Save results to file +bunx oh-my-opencode doctor --json > doctor-report.json +``` + +--- + +## 10. Developer Information + +### CLI Structure + +``` +src/cli/ +├── index.ts # Commander.js-based main entry +├── install.ts # @clack/prompts-based TUI installer +├── config-manager.ts # JSONC parsing, multi-source config management +├── doctor/ # Health check system +│ ├── index.ts # Doctor command entry +│ └── checks/ # 17+ individual check modules +├── run/ # Session runner +└── commands/auth.ts # Authentication management +``` + +### Adding New Doctor Checks + +1. Create `src/cli/doctor/checks/my-check.ts`: + +```typescript +import type { DoctorCheck } from "../types" + +export const myCheck: DoctorCheck = { + name: "my-check", + category: "environment", + check: async () => { + // Check logic + const isOk = await someValidation() + + return { + status: isOk ? "pass" : "fail", + message: isOk ? "Everything looks good" : "Something is wrong", + } + }, +} +``` + +2. Register in `src/cli/doctor/checks/index.ts`: + +```typescript +export { myCheck } from "./my-check" +``` diff --git a/docs/orchestration-guide.md b/docs/orchestration-guide.md new file mode 100644 index 000000000..550b97df8 --- /dev/null +++ b/docs/orchestration-guide.md @@ -0,0 +1,131 @@ +# Oh-My-OpenCode Orchestration Guide + +This document provides a comprehensive guide to the orchestration system that implements Oh-My-OpenCode's core philosophy: **"Separation of Planning and Execution"**. + +## 1. Overview + +Traditional AI agents often mix planning and execution, leading to context pollution, goal drift, and AI slop (low-quality code). + +Oh-My-OpenCode solves this by clearly separating two roles: + +1. **Prometheus (Planner)**: A pure strategist who never writes code. Establishes perfect plans through interviews and analysis. +2. **Sisyphus (Executor)**: An orchestrator who executes plans. Delegates work to specialized agents and never stops until completion. + +--- + +## 2. Overall Architecture + +```mermaid +graph TD + User[User Request] --> Prometheus + + subgraph Planning Phase + Prometheus[Prometheus
Planner] --> Metis[Metis
Consultant] + Metis --> Prometheus + Prometheus --> Momus[Momus
Reviewer] + Momus --> Prometheus + Prometheus --> PlanFile[/.sisyphus/plans/*.md] + end + + PlanFile --> StartWork[/start-work] + StartWork --> BoulderState[boulder.json] + + subgraph Execution Phase + BoulderState --> Sisyphus[Sisyphus
Orchestrator] + Sisyphus --> Oracle[Oracle] + Sisyphus --> Frontend[Frontend
Engineer] + Sisyphus --> Explore[Explore] + end +``` + +--- + +## 3. Key Components + +### 🔮 Prometheus (The Planner) +- **Model**: `anthropic/claude-opus-4-5` +- **Role**: Strategic planning, requirements interviews, work plan creation +- **Constraint**: **READ-ONLY**. Can only create/modify markdown files within `.sisyphus/` directory. +- **Characteristic**: Never writes code directly, focuses solely on "how to do it". + +### 🦉 Metis (The Consultant) +- **Role**: Pre-analysis and gap detection +- **Function**: Identifies hidden user intent, prevents AI over-engineering, eliminates ambiguity. +- **Workflow**: Metis consultation is mandatory before plan creation. + +### ⚖️ Momus (The Reviewer) +- **Role**: High-precision plan validation (High Accuracy Mode) +- **Function**: Rejects and demands revisions until the plan is perfect. +- **Trigger**: Activated when user requests "high accuracy". + +### 🪨 Sisyphus (The Orchestrator) +- **Model**: `anthropic/claude-opus-4-5` (Extended Thinking 32k) +- **Role**: Execution and delegation +- **Characteristic**: Doesn't do everything directly, actively delegates to specialized agents (Frontend, Librarian, etc.). + +--- + +## 4. Workflow + +### Phase 1: Interview and Planning (Interview Mode) +Prometheus starts in **interview mode** by default. Instead of immediately creating a plan, it collects sufficient context. + +1. **Intent Identification**: Classifies whether the user's request is Refactoring or New Feature. +2. **Context Collection**: Investigates codebase and external documentation through `explore` and `librarian` agents. +3. **Draft Creation**: Continuously records discussion content in `.sisyphus/drafts/`. + +### Phase 2: Plan Generation +When the user requests "Make it a plan", plan generation begins. + +1. **Metis Consultation**: Confirms any missed requirements or risk factors. +2. **Plan Creation**: Writes a single plan in `.sisyphus/plans/{name}.md` file. +3. **Handoff**: Once plan creation is complete, guides user to use `/start-work` command. + +### Phase 3: Execution +When the user enters `/start-work`, the execution phase begins. + +1. **State Management**: Creates `boulder.json` file to track current plan and session ID. +2. **Task Execution**: Sisyphus reads the plan and processes TODOs one by one. +3. **Delegation**: UI work is delegated to Frontend agent, complex logic to Oracle. +4. **Continuity**: Even if the session is interrupted, work continues in the next session through `boulder.json`. + +--- + +## 5. Commands and Usage + +### `/plan [request]` +Invokes Prometheus to start a planning session. +- Example: `/plan "I want to refactor the authentication system to NextAuth"` + +### `/start-work` +Executes the generated plan. +- Function: Finds plan in `.sisyphus/plans/` and enters execution mode. +- If there's interrupted work, automatically resumes from where it left off. + +--- + +## 6. Configuration Guide + +You can control related features in `oh-my-opencode.json`. + +```jsonc +{ + "sisyphus_agent": { + "disabled": false, // Enable Sisyphus orchestration (default: false) + "planner_enabled": true, // Enable Prometheus (default: true) + "replace_plan": true // Replace default plan agent with Prometheus (default: true) + }, + + // Hook settings (add to disable) + "disabled_hooks": [ + // "start-work", // Disable execution trigger + // "prometheus-md-only" // Remove Prometheus write restrictions (not recommended) + ] +} +``` + +## 7. Best Practices + +1. **Don't Rush**: Invest sufficient time in the interview with Prometheus. The more perfect the plan, the faster the execution. +2. **Single Plan Principle**: No matter how large the task, contain all TODOs in one plan file (`.md`). This prevents context fragmentation. +3. **Active Delegation**: During execution, delegate to specialized agents via `sisyphus_task` rather than modifying code directly.