# oh-my-opencode Setup & Troubleshooting Runbook

## Overview
This runbook covers the steps required to enable `oh-my-opencode` properly, ensuring all primary agents (Sisyphus, Atlas, Prometheus) load and function correctly across the homelab infrastructure.

## Problem Context
Initially, `oh-my-opencode` was installed but failed to load primary agents. Symptoms included missing agents in the TUI and logs showing plugins loading except for `oh-my-opencode`.

## Root Causes Identified
1.  **Malformed Configuration**: `oh-my-opencode.json` had broken JSON syntax and missing agent/hook blocks.
2.  **Plugin Loading Order**: `oh-my-opencode` was not the first plugin in `opencode.json`, potentially causing initialization delays or conflicts.
3.  **Missing Built-in Definitions**: Primary agents were not explicitly defined with correct model/category mappings.

## Step-by-Step Enablement

### 1. Update `opencode.json`
Ensure `oh-my-opencode@latest` is the first plugin in the list. This ensures it initializes before other plugins that might depend on it or conflict with its hooks.

```json
"plugin": [
  "oh-my-opencode@latest",
  "opencode-antigravity-auth@latest",
  "./plugin/kilocode/plugin_kilocode.ts"
]
```

### 2. Standardize `oh-my-opencode.json`
Apply the standardized configuration with all hooks enabled and primary agents defined. Key sections to include:
- `sisyphus_agent`: Enable planner and plan replacement.
- `hooks`: Enable all 16+ hooks including `session-recovery`, `rules-injector`, and `think-mode`.
- `agents`: Define `sisyphus`, `atlas`, `prometheus`, `oracle`, `librarian`, and `explore` with appropriate models.

### 3. Verify Plugin Loading
Check OpenCode logs for successful plugin initialization:
```bash
grep "service=plugin.*loading" ~/.local/share/opencode/log/*.log
```
Look for: `service=plugin path=...oh-my-opencode/dist/index.js loading plugin`

### 4. Verify Agents in TUI
Launch OpenCode and verify `Sisyphus` appears in the agent selection. Also test slash commands like `/refactor` or `/git-master`.

## GitOps Workflow
All configuration changes must be made in the `homelabagentroot` repository and pushed to trigger the automated deployment sync.

1.  Edit configs in `homelab/configs/opencode-global/`
2.  Commit and push to `origin main`
3.  The Gitea runner will pull changes and restart services as configured.

---
**Last Updated:** January 25, 2026
**Status:** Verified Working ✅