Best Practices

This document shares best practices and efficient patterns for using Oh My OpenCode, helping you fully leverage the power of multi-agent collaboration.

ultrawork Magic Keyword

What is ultrawork?

ultrawork (abbreviated as ulw) is Oh My OpenCode’s magic keyword. Adding this word to your task description automatically enables all advanced features.

Features Enabled

When using ultrawork, the system automatically enables:

✅ All configured specialist agents
✅ Background task parallel execution
✅ Full LSP tool integration
✅ Intelligent context management
✅ AST-Grep code search
✅ Automatic task decomposition and coordination

Usage Examples

# Full form
opencode "ultrawork: Refactor user authentication system, add OAuth2 support"

# Abbreviated form
opencode "ulw: Add TypeScript types to entire project"

# Combined with agents
opencode "ultrawork: @oracle Design microservices architecture"

When to Use

Recommended to use ultrawork:

🏗️ Large refactoring tasks
🌐 Full-stack feature development
📚 Complex problem analysis
🎯 Multi-step implementation tasks

No need for ultrawork:

🔍 Simple queries
✏️ Small-scope modifications
📖 Single-file edits
❓ Q&A type requests

Multi-Agent Collaboration Patterns

Pattern 1: Sequential Collaboration

Use case: Tasks with clear sequential dependencies

# Step 1: Architecture design
opencode "@oracle Design architecture for user permission system"

# Step 2: Documentation research
opencode "@librarian Research RBAC and ABAC best practices"

# Step 3: Implementation
opencode "@backend-engineer Implement permission system based on @oracle's design"

Advantages:

Clear division of responsibilities
Each step’s results can be manually reviewed
Easier to track issues

Pattern 2: Parallel Collaboration

Use case: Subtasks are relatively independent and can proceed simultaneously

# Use ultrawork for automatic parallelization
opencode "ulw: Develop user dashboard feature, including frontend UI and backend API"

# Sisyphus automatically assigns:
# - @frontend-engineer: Implement UI components
# - @backend-engineer: Implement API endpoints
# - @librarian: Research best practices

Advantages:

Dramatically improve efficiency
Automatic coordination and integration
Suitable for time-sensitive tasks

Pattern 3: Layered Collaboration

Use case: Requires different levels of decision-making and implementation

# Layer 1: Strategic decisions
opencode "@oracle Evaluate whether to migrate from REST to GraphQL"

# Layer 2: Technical research
opencode "@librarian Research GraphQL ecosystem and toolchain"

# Layer 3: Prototype development
opencode "@backend-engineer Implement a GraphQL prototype"

# Layer 4: Validation testing
opencode "@explore Analyze prototype performance and maintainability"

Choosing the Right Agent

Task Type	Primary Agent	Alternative	Notes
Architecture decisions	@oracle	-	Strongest system thinking
Documentation writing	@document-writer	@librarian	Document Writer focuses on technical writing
Documentation research	@librarian	-	Excels at information retrieval and organization
UI/UX design	@frontend-ui-ux-engineer	@frontend-engineer	Focuses on user experience
Frontend development	@frontend-engineer	@frontend-ui-ux-engineer	Frontend technical expert
API development	@backend-engineer	-	Backend expert
Bug debugging	@explore	@oracle	Explore excels at code analysis
Performance optimization	@oracle	@explore	Oracle provides strategy, Explore analyzes details
Visual analysis	@multimodal-looker	-	Analyze design mockups and UI screenshots

Context Management Best Practices

AGENTS.md Hierarchical System

Properly use hierarchical context rules:

Global Rules (Project Root)

<!-- project/AGENTS.md -->
# Global Development Standards

## General Rules
- Use TypeScript strict mode
- All functions must have type annotations
- Use ESLint and Prettier

## Commit Standards
- Follow Conventional Commits
- Every commit must pass all tests

Module Rules (src Directory)

<!-- project/src/AGENTS.md -->
# Source Code Standards

## Code Organization
- Organize by feature modules, not by type
- Each module includes index.ts exports

## Testing Requirements
- Core business logic must have unit tests
- Coverage not less than 80%

Component Rules (components Directory)

<!-- project/src/components/AGENTS.md -->
# React Component Standards

## when: file.ext == "*.tsx"
- Use function components and Hooks
- Props must define TypeScript interface
- Use CSS Modules for style management

## when: agent == "@frontend-engineer"
- Follow company UI design system
- Document components with Storybook

Using Conditional Rules

Activate by File Type

## when: file.ext == "*.test.ts"
Use Jest and React Testing Library
Follow AAA pattern (Arrange, Act, Assert)

## when: file.ext == "*.spec.ts"
Use Cypress for E2E testing

Activate by Agent Type

## when: agent == "@oracle"
Provide detailed technical decision rationale
Consider long-term maintainability

## when: agent == "@frontend-engineer"
Prioritize user experience
Follow accessibility (a11y) standards

Activate by Task Phase

## when: phase == "design"
Output architecture diagrams and technology selection documents

## when: phase == "implementation"
Write testable code
Add necessary comments

Background Task Usage Tips

Set Concurrency Appropriately

Adjust according to subscription plan:

Claude Max20 Configuration:

{
  "sisyphus": {
    "max_concurrent_tasks": 3
  }
}

ChatGPT Plus / Gemini Configuration:

{
  "sisyphus": {
    "max_concurrent_tasks": 2
  }
}

Free or Limited Plans:

{
  "sisyphus": {
    "max_concurrent_tasks": 1
  }
}

Background Task Use Cases

Suitable for background execution:

📖 Documentation research
🔍 Code base analysis
📊 Performance benchmarking
🧪 Test execution
📝 Auxiliary documentation generation

Not suitable for background execution:

✏️ Direct code modifications
🚀 Critical path tasks
👤 Operations requiring user confirmation

Monitor Background Tasks

# View currently running background tasks
opencode "Show all background task statuses"

# Cancel specific background task
opencode "Cancel task ID: abc123"

# Wait for all background tasks to complete
opencode "Wait for all background tasks to complete before continuing"

Code Quality Control Strategies

Automatic Comment Checking

Configure agents to automatically add necessary comments:

{
  "code_quality": {
    "enforce_comments": true,
    "comment_rules": {
      "functions": "Complexity > 10 requires comments",
      "classes": "Public classes require comments",
      "exports": "Exported functions/classes require comments"
    }
  }
}

Code Review Integration

Let agents help review code:

# Review specific file
opencode "@oracle Review code quality of src/auth/login.ts"

# Review entire PR
opencode "ulw: Review all changes in current branch"

# Check security issues
opencode "@explore Check for security vulnerabilities in code"

Todo Continuation Executor

Use Todo system to track long-term tasks:

# Create Todo
opencode "Create todo: Refactor user authentication module"

# View Todos
opencode "List all incomplete todos"

# Continue executing Todo
opencode "Continue executing todo: Refactor user authentication module"

Performance Optimization Recommendations

Optimize Model Selection

Use different models for different tasks:

{
  "agents": {
    "oracle": {
      "model": "claude-sonnet-4",  // Use strongest model for complex decisions
      "temperature": 0.7
    },
    "explore": {
      "model": "claude-sonnet-3.5",  // Use mid-tier model for code analysis
      "temperature": 0.3
    },
    "librarian": {
      "model": "gpt-4-turbo",  // Can use other models for documentation research
      "temperature": 0.5
    }
  }
}

Control Token Usage

{
  "token_management": {
    "max_context_tokens": 4096,
    "summarize_long_context": true,
    "cache_common_queries": true
  }
}

Optimize Task Descriptions

❌ Vague description:

opencode "Improve code"

✅ Clear description:

opencode "@explore Analyze performance bottlenecks in UserService.ts, then @backend-engineer optimize database queries"

Use Caching

{
  "caching": {
    "enabled": true,
    "cache_lsp_results": true,
    "cache_duration": 3600,  // 1 hour
    "cache_directory": ".opencode/cache"
  }
}

Common Pitfalls and Solutions

Pitfall 1: Overusing ultrawork

Problem: Using ultrawork for simple tasks, wasting resources

Solution:

# ❌ Overuse
opencode "ulw: View package.json contents"

# ✅ Simple task direct execution
opencode "View package.json"

Pitfall 2: Inappropriate Agent Selection

Problem: Having unsuitable agents execute tasks

Solution:

# ❌ Poor choice
opencode "@librarian Implement a React component"

# ✅ Correct choice
opencode "@frontend-engineer Implement a React component"

Pitfall 3: Ignoring Context Management

Problem: Not configuring AGENTS.md for project

Solution: Create hierarchical AGENTS.md files to provide necessary context

Pitfall 4: Too Many Concurrent Tasks

Problem: Setting max_concurrent_tasks too high causing API rate limiting

Solution: Adjust concurrency based on actual subscription plan

Practical Tips Summary

Quick Start Templates

# New feature development
opencode "ulw: @oracle Design architecture for [feature name], @librarian research related technologies, @frontend-engineer and @backend-engineer implement in parallel"

# Bug fixing
opencode "@explore Analyze root cause of [bug description], then fix it"

# Code review
opencode "@oracle Review architectural soundness of current PR, @explore check for potential issues"

# Documentation writing
opencode "@librarian Research project structure, then write complete README.md"

Efficiency Improvement Checklist

✅ Configure AGENTS.md hierarchical rules for project
✅ Adjust concurrency based on subscription plan
✅ Use ultrawork for complex tasks
✅ Choose appropriate agents for tasks
✅ Leverage background tasks to improve efficiency
✅ Use Todo system to track long-term tasks
✅ Regularly clean cache and sessions

Next Steps

After mastering best practices, we recommend:

⚙️ Explore Advanced Configuration for deep customization
💡 Refer to Use Cases for more inspiration
🔧 Customize your workflow based on team needs