elias/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add orchestration, category-skill, and CLI guides

Browse Source
This commit is contained in:
YeonGyu-Kim 2026-01-09 02:06:20 +09:00
parent a4e161d485
commit 72ca8b8637
4 changed files with 603 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
docs/CRASH_INVESTIGATION_TIMELINE.md
View File

@ -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

200
docs/category-skill-guide.md Normal file
View File

@ -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"]
}
```

272
docs/cli-guide.md Normal file
View File

@ -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 <name>` | 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 <seconds>` | 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"
```

131
docs/orchestration-guide.md Normal file
View File

@ -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<br>Planner] --> Metis[Metis<br>Consultant]
Metis --> Prometheus
Prometheus --> Momus[Momus<br>Reviewer]
Momus --> Prometheus
Prometheus --> PlanFile[/.sisyphus/plans/*.md]
end
PlanFile --> StartWork[/start-work]
StartWork --> BoulderState[boulder.json]
subgraph Execution Phase
BoulderState --> Sisyphus[Sisyphus<br>Orchestrator]
Sisyphus --> Oracle[Oracle]
Sisyphus --> Frontend[Frontend<br>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.