Use Cases

Use Cases

This document demonstrates how to efficiently use Oh My OpenCode in real projects through 5 practical scenarios.

Scenario 1: Large-Scale Project Refactoring

Scenario Description

A 5-year-old e-commerce platform with over 500,000 lines of code needs to migrate from JavaScript to TypeScript while refactoring outdated architecture patterns.

Challenges

• Massive codebase, cannot migrate all at once
• Need to maintain business continuity
• Multiple interdependent modules with hard-to-assess impact scope

Solution

Use multi-agent collaboration and LSP tools from Oh My OpenCode:

# Step 1: Architecture analysis
opencode "@oracle Analyze current project architecture, develop TypeScript migration plan, divide migration phases"

# Step 2: Dependency analysis (background task)
opencode "ulw: @explore Analyze all module dependencies, generate dependency graph, identify critical path modules"

# Step 3: Module-by-module migration
opencode "ulw: @backend-engineer Migrate user-service module to TypeScript, use LSP tools to ensure type safety"

# Step 4: Validation and testing
opencode "@explore Use LSP tools to check type errors, run test suite, generate migration report"

Configuration

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "prompt_append": "Consider business continuity, provide incremental migration plan"
    },
    "explore": {
      "enabled": true,
      "tools": {
        "lsp": true,
        "ast_grep": true
      }
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "Maintain API backward compatibility, add complete type annotations"
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript"]
  },
  "background_task": {
    "enabled": true,
    "defaultConcurrency": 3
  }
}

Implementation Steps

1. Architecture Assessment (1 day)

   opencode "@oracle Evaluate current architecture, identify technical debt, establish refactoring priorities"

2. Dependency Analysis (parallel, 2 days)

   opencode "ulw: @explore Analyze module dependencies, @librarian research TypeScript migration best practices"

3. Module Migration (batched, 4 weeks)

   # Migrate each module separately
   opencode "ulw: @backend-engineer Migrate auth module, @explore verify type coverage"

4. Integration Testing (continuous)

   opencode "@explore Run complete test suite, report migration progress"

Results

• ✅ Completed 500k line migration in 4 weeks
• ✅ 100% TypeScript type coverage
• ✅ 0 business disruption
• ✅ Discovered and fixed 47 potential bugs

Scenario 2: Multi-Framework Full-Stack Application Development

Scenario Description

Develop a SaaS product with React frontend and Node.js + Express backend, complete MVP in 3 weeks.

Challenges

• Frontend and backend need synchronized development
• API interfaces require frequent adjustments
• Time constraints require efficient collaboration

Solution

Use multi-agent parallel development:

# Start ultrawork mode
opencode "ulw: Develop user authentication system, including frontend login interface and backend API, support JWT and OAuth2"

# Sisyphus automatically assigns:
# - @oracle: Design authentication architecture and data models
# - @frontend-ui-ux-engineer: Implement login/registration interface and user experience
# - Sisyphus: Handle backend logic and API endpoint implementation
# - @librarian: Research security best practices

Configuration

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "delegation_strategy": "parallel",
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "temperature": 0.7
    },
    "frontend-engineer": {
      "enabled": true,
      "prompt_append": "Use React 18 + TypeScript + Tailwind CSS + React Query"
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "Use Node.js + Express + PostgreSQL + Prisma ORM"
    },
    "librarian": {
      "enabled": true
    }
  },
  "context_injection": {
    "enabled": true,
    "files": ["AGENTS.md", ".opencode/TECH_STACK.md"]
  }
}

Project Structure and Context

<!-- project/AGENTS.md -->
# Project Standards

## Technology Stack
- Frontend: React 18 + TypeScript + Vite + Tailwind
- Backend: Node.js 18 + Express + PostgreSQL + Prisma
- Authentication: JWT + OAuth2 (Google, GitHub)

## API Standards
- RESTful API design
- Unified error handling
- Request/response logging

## Code Standards
- ESLint + Prettier
- Husky + lint-staged
- Commits must pass CI checks

Workflow

# Day 1: Architecture design
opencode "@oracle Design user authentication system architecture, including data models, API endpoints, and frontend routes"

# Days 2-3: Parallel development
opencode "ulw: @frontend-ui-ux-engineer Implement login/registration interface, Sisyphus implement authentication API"

# Day 4: Integration and debugging
opencode "@explore Analyze frontend/backend integration issues, adjust API interfaces"

# Day 5: Testing and optimization
opencode "ulw: @frontend-ui-ux-engineer Add E2E tests, add backend unit tests"

Results

• ✅ Completed authentication system in 5 days
• ✅ Fully decoupled frontend and backend
• ✅ 85% test coverage
• ✅ Support for multiple OAuth2 providers

Scenario 3: Open Source Project Documentation

Scenario Description

A popular open-source library with rich features but lacking documentation needs complete documentation site.

Challenges

• Complex codebase requiring deep understanding
• Documentation must be accurate and comprehensive
• Example code must be runnable

Solution

Use @librarian for research and @document-writer for documentation:

# Step 1: Project analysis
opencode "@explore Analyze project structure, list all public APIs and core features"

# Step 2: Documentation research
opencode "@librarian Research project code, understand purpose and parameters of each API, read existing comments"

# Step 3: Write documentation
opencode "ulw: @document-writer Write complete documentation for project, including:
- README.md (overview, quick start, installation)
- API.md (complete API reference)
- GUIDE.md (usage guide and best practices)
- EXAMPLES.md (common scenario examples)
Use LSP tools to verify API information accuracy"

# Step 4: Example code
opencode "@backend-engineer Write runnable example code for each API, add detailed comments"

Configuration

{
  "subscription": "chatgpt-plus",
  "agents": {
    "librarian": {
      "enabled": true,
      "model": "gpt-4-turbo",
      "temperature": 0.5,
      "prompt_append": "Carefully read code and comments, ensure documentation accuracy, provide clear explanations and examples"
    },
    "explore": {
      "enabled": true,
      "tools": {
        "lsp": true,
        "ast_grep": true
      }
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "Example code must be runnable, include error handling, add detailed comments"
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript"]
  }
}

Documentation Structure

# Generate documentation outline
opencode "@librarian Analyze project, generate documentation outline, include all topics to cover"

# Documentation outline example:
# docs/
# ├── README.md              # Project overview
# ├── getting-started.md     # Quick start
# ├── installation.md        # Installation guide
# ├── api/
# │   ├── configuration.md   # Configuration API
# │   ├── core.md           # Core API
# │   └── utilities.md      # Utility functions
# ├── guides/
# │   ├── basic-usage.md    # Basic usage
# │   ├── advanced.md       # Advanced techniques
# │   └── best-practices.md # Best practices
# └── examples/
#     ├── quickstart.md     # Quick examples
#     └── real-world.md     # Real-world cases

Results

• ✅ Completed full documentation site in 2 days
• ✅ All public APIs documented
• ✅ 30+ runnable examples
• ✅ GitHub stars grew 300%

Scenario 4: Complex Bug Debugging

Scenario Description

Production environment experiencing intermittent performance issues with unclear error logs, difficult to reproduce.

Challenges

• Bug difficult to reproduce
• Large codebase, hard to locate issue
• Affecting production, requires quick resolution

Solution

Use Oracle + Explore for deep analysis:

# Step 1: Collect information
opencode "@explore Analyze error logs and monitoring data, identify abnormal patterns"

# Step 2: Code analysis
opencode "ulw: @explore Use LSP tools to analyze call chain of suspicious modules, @oracle evaluate possible root causes"

# Step 3: Hypothesis validation
opencode "@oracle Based on analysis results, propose 3 hypotheses, @explore find evidence for each hypothesis"

# Step 4: Fix and verify
opencode "@backend-engineer Implement fix solution, add monitoring and logging, @explore verify fix effectiveness"

Configuration

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "temperature": 0.7,
      "prompt_append": "Systematically analyze problem, consider concurrency, cache, network and other factors"
    },
    "explore": {
      "enabled": true,
      "temperature": 0.3,
      "tools": {
        "lsp": true,
        "ast_grep": true
      },
      "prompt_append": "Carefully trace code execution paths, focus on edge cases and exceptions"
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "Fix must be backward compatible, add defensive programming measures"
    }
  }
}

Debug Process

# 1. Log analysis
opencode "@explore Analyze last 7 days of error logs, identify most frequent errors and time patterns"

# 2. Performance analysis
opencode "@explore Use LSP tools to analyze performance bottleneck modules, find all database queries and API calls"

# 3. Code review
opencode "@oracle Review suspicious code, identify potential concurrency issues, memory leaks, or resource contention"

# 4. Fix implementation
opencode "@backend-engineer Implement fix:
- Add database connection pool management
- Optimize queries, add indexes
- Add timeout and retry mechanisms
- Improve error handling and logging"

# 5. Verification
opencode "@explore Reproduce issue in test environment, verify fix effectiveness, run stress tests"

Results

• ✅ Located root cause in 4 hours
• ✅ 60% performance improvement after fix
• ✅ 95% error rate reduction
• ✅ Added comprehensive monitoring and alerting

Scenario 5: UI/UX Rapid Prototyping

Scenario Description

Product manager proposes new feature idea, need to quickly implement interactive prototype for user testing.

Challenges

• Time constraints (2 days)
• Need near-real interaction
• May require subsequent adjustments

Solution

Use specialized frontend agents for rapid iteration:

# Rapid prototype development
opencode "@frontend-engineer Implement user dashboard prototype, including:
- Data visualization charts (using Recharts)
- Responsive layout (Tailwind CSS)
- Mock data and interactions
- Smooth animations
Use React + TypeScript + Vite"

Configuration

{
  "subscription": "chatgpt-plus",
  "agents": {
    "frontend-engineer": {
      "enabled": true,
      "model": "gpt-4",
      "temperature": 0.6,
      "prompt_append": "Rapid prototype requirements:\n- Prioritize core interaction flows\n- Use ready-made UI component libraries (shadcn/ui, Headless UI)\n- Mock data and API calls\n- Focus on visual effects and user experience\n- Code should be concise and easy to adjust"
    }
  }
}

Prototype Development Process

# Step 1: Layout and navigation
opencode "@frontend-engineer Implement dashboard layout: sidebar navigation, top bar, main content area"

# Step 2: Core components
opencode "ulw: @frontend-engineer Implement core components:
- Data cards (KPI metrics)
- Chart components (line charts, pie charts)
- Data tables (sortable, filterable)
- Action buttons and forms"

# Step 3: Interactions and animations
opencode "@frontend-engineer Add interactive effects:
- Page transition animations
- Data loading states
- Hover and click feedback
- Responsive adaptation"

# Step 4: Mock data
opencode "@frontend-engineer Create mock data and APIs, use MSW (Mock Service Worker)"

Project Configuration

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true
  }
})

// package.json (dependencies)
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "recharts": "^2.10.0",
    "tailwindcss": "^3.4.0",
    "@headlessui/react": "^1.7.0",
    "framer-motion": "^10.16.0"
  }
}

Results

• ✅ Completed interactive prototype in 1.5 days
• ✅ Includes 15+ beautiful components
• ✅ Complete mock data and APIs
• ✅ Excellent user testing feedback

Summary

Scenario Comparison

Scenario	Main Agents	Time	Core Features
Large Refactoring	Oracle + Explore	4 weeks	LSP + Parallel tasks
Full-Stack Dev	Frontend + Backend	5 days	Multi-agent collaboration
Documentation	Librarian + Explore	2 days	LSP + Code analysis
Bug Debugging	Oracle + Explore	4 hours	LSP + Deep analysis
UI Prototype	Frontend Engineer	1.5 days	Rapid iteration

Key Learnings

1. Choose Appropriate Agents: Select specialist agents based on task type
2. Leverage ultrawork: Enable all features for complex tasks
3. Parallel Execution: Independent tasks in parallel to improve efficiency
4. LSP Tools: Powerful tool for code analysis and refactoring
5. Context Management: AGENTS.md provides project-specific rules

General Configuration Recommendations

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3  // Adjust based on subscription, example for Claude Max20
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]  // Project languages
  },
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  },
  "context_injection": {
    "enabled": true,
    "files": ["AGENTS.md", ".opencode/CONTEXT.md"]
  }
}

---

Ready to apply these patterns to your project? Start with Quick Start, or check Best Practices for more tips!